@lessonkit/react 0.3.0 → 0.4.0

package/README.md

@@ -17,7 +17,7 @@ npm install @lessonkit/react react react-dom
 ```tsx
 import { useMemo } from "react";
 import type { TelemetryEvent } from "@lessonkit/core";
-import { Course, Lesson, Quiz, Scenario, ProgressTracker } from "@lessonkit/react";
+import { Course, Lesson, Quiz, Scenario, ProgressTracker, ThemeProvider } from "@lessonkit/react";
 import type { XAPIStatement } from "@lessonkit/xapi";
 
 export default function App() {
@@ -34,6 +34,7 @@ export default function App() {
   );
 
   return (
+    <ThemeProvider mode="light">
     <Course title="Cybersecurity Basics" courseId="cyber-basics" config={config}>
       <ProgressTracker />
 
@@ -49,11 +50,12 @@ export default function App() {
         />
       </Lesson>
     </Course>
+    </ThemeProvider>
   );
 }
 ```
 
-## API (0.3.0)
+## API (0.4.0)
 
 ### Components
 
@@ -71,6 +73,12 @@ export default function App() {
 - `useTracking`
 - `useQuizState`
 - `useCompletion`
+- `useTheme`
+
+### Theming
+
+- `ThemeProvider` — injects `--lk-*` CSS variables (see [`docs/THEMING.md`](../../docs/THEMING.md))
+- Props: `preset`, `mode` (`light` | `dark` | `system`), `theme` (partial override), `target` (`document` | `element`)
 
 ## Notes
 
@@ -84,4 +92,5 @@ export default function App() {
 - 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).
+- Theming and token catalog: [`docs/THEMING.md`](../../docs/THEMING.md).
 

package/dist/index.cjs

@@ -1,7 +1,9 @@
 "use strict";
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -15,6 +17,14 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/index.tsx
@@ -28,10 +38,12 @@ __export(index_exports, {
   Quiz: () => Quiz,
   Reflection: () => Reflection,
   Scenario: () => Scenario,
+  ThemeProvider: () => ThemeProvider,
   useCompletion: () => useCompletion,
   useLessonkit: () => useLessonkit,
   useProgress: () => useProgress,
   useQuizState: () => useQuizState,
+  useTheme: () => useTheme,
   useTracking: () => useTracking
 });
 module.exports = __toCommonJS(index_exports);
@@ -42,69 +54,91 @@ var import_accessibility = require("@lessonkit/accessibility");
 
 // src/context.tsx
 var import_react = require("react");
-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?.();
+var import_core2 = require("@lessonkit/core");
+var import_xapi2 = require("@lessonkit/xapi");
+
+// src/runtime/ports.ts
+function createNoopStorage() {
+  return {
+    getItem: () => null,
+    setItem: () => {
+    }
+  };
 }
-function safeSessionStorageGetItem(key) {
-  if (typeof sessionStorage === "undefined") return null;
-  try {
-    return sessionStorage.getItem(key);
-  } catch {
-    return null;
-  }
+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 {
+      }
+    }
+  };
 }
-function safeSessionStorageSetItem(key, value) {
-  if (typeof sessionStorage === "undefined") return;
-  try {
-    sessionStorage.setItem(key, value);
-  } catch {
-  }
+
+// src/runtime/xapi.ts
+var import_xapi = require("@lessonkit/xapi");
+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 resolveSessionId(provided) {
+
+// src/runtime/session.ts
+var import_core = require("@lessonkit/core");
+var SESSION_STORAGE_KEY = "lessonkit:sessionId";
+var COURSE_STARTED_PREFIX = "lessonkit:course_started:";
+function resolveSessionId(storage, provided) {
   if (provided) return provided;
-  const existing = safeSessionStorageGetItem(SESSION_STORAGE_KEY);
+  const existing = storage.getItem(SESSION_STORAGE_KEY);
   if (existing) return existing;
   const id = (0, import_core.createSessionId)();
-  safeSessionStorageSetItem(SESSION_STORAGE_KEY, id);
+  storage.setItem(SESSION_STORAGE_KEY, id);
   return id;
 }
 function courseStartedStorageKey(sessionId, courseId) {
   return `${COURSE_STARTED_PREFIX}${sessionId}:${courseId ?? ""}`;
 }
-function hasCourseStarted(sessionId, courseId) {
+function hasCourseStarted(storage, sessionId, courseId) {
   if (!courseId) return false;
-  return safeSessionStorageGetItem(courseStartedStorageKey(sessionId, courseId)) === "1";
+  return storage.getItem(courseStartedStorageKey(sessionId, courseId)) === "1";
 }
-function markCourseStarted(sessionId, courseId) {
+function markCourseStarted(storage, sessionId, courseId) {
   if (!courseId) return;
-  safeSessionStorageSetItem(courseStartedStorageKey(sessionId, courseId), "1");
+  storage.setItem(courseStartedStorageKey(sessionId, courseId), "1");
 }
+
+// src/context.tsx
+var import_jsx_runtime = require("react/jsx-runtime");
+var LessonkitContext = (0, import_react.createContext)(null);
+var useIsoLayoutEffect = typeof window !== "undefined" ? import_react.useLayoutEffect : import_react.useEffect;
+function disposeTrackingClient(client) {
+  client?.flush?.();
+  client?.dispose?.();
+}
+var defaultStorage = createSessionStoragePort();
 function createTrackingClientFromConfig(config) {
   if (config.tracking?.enabled === false) {
-    return (0, import_core.createTrackingClient)();
+    return (0, import_core2.createTrackingClient)();
   }
-  return (0, import_core.createTrackingClient)({
+  return (0, import_core2.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 sessionIdRef = (0, import_react.useRef)(resolveSessionId(config.session?.sessionId));
+  const sessionIdRef = (0, import_react.useRef)(resolveSessionId(defaultStorage, 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);
@@ -112,7 +146,7 @@ function LessonkitProvider(props) {
   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 trackingRef = (0, import_react.useRef)((0, import_core2.createTrackingClient)());
   const [tracking, setTracking] = (0, import_react.useState)(() => trackingRef.current);
   const courseStartedInProviderRef = (0, import_react.useRef)(false);
   const trackingEnabled = config.tracking?.enabled;
@@ -121,23 +155,23 @@ function LessonkitProvider(props) {
   const batchEnabled = config.tracking?.batch?.enabled;
   const batchFlushIntervalMs = config.tracking?.batch?.flushIntervalMs;
   const batchMaxBatchSize = config.tracking?.batch?.maxBatchSize;
-  (0, import_react.useLayoutEffect)(() => {
+  useIsoLayoutEffect(() => {
     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;
+    const shouldEmitCourseStarted = cid ? !hasCourseStarted(defaultStorage, sessionId, cid) : !courseStartedInProviderRef.current;
     if (shouldEmitCourseStarted) {
       if (cid) {
-        markCourseStarted(sessionId, cid);
+        markCourseStarted(defaultStorage, sessionId, cid);
       } else {
         courseStartedInProviderRef.current = true;
       }
       next.track({
         name: "course_started",
-        timestamp: (0, import_core.nowIso)(),
+        timestamp: (0, import_core2.nowIso)(),
         courseId: cid,
         sessionId,
         attemptId: attemptIdRef.current,
@@ -155,14 +189,14 @@ function LessonkitProvider(props) {
     batchFlushIntervalMs,
     batchMaxBatchSize
   ]);
-  const xapiQueueRef = (0, import_react.useRef)((0, import_xapi.createInMemoryXAPIQueue)());
+  const xapiQueueRef = (0, import_react.useRef)((0, import_xapi2.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)(() => {
+  useIsoLayoutEffect(() => {
     const prev = xapiRef.current;
     const next = createXapiClientFromConfig(config, xapiQueueRef.current);
     xapiRef.current = next;
@@ -197,7 +231,7 @@ function LessonkitProvider(props) {
     (name, data, opts) => {
       trackingRef.current?.track({
         name,
-        timestamp: (0, import_core.nowIso)(),
+        timestamp: (0, import_core2.nowIso)(),
         courseId: courseIdRef.current,
         lessonId: opts?.lessonId ?? activeLessonIdRef.current,
         sessionId: sessionIdRef.current,
@@ -399,6 +433,114 @@ function sanitizeLessonId(id) {
   const s = id.replace(/[^a-zA-Z0-9_-]/g, "");
   return s.length ? s : "id";
 }
+
+// src/theme/ThemeProvider.tsx
+var import_react4 = __toESM(require("react"), 1);
+var import_themes = require("@lessonkit/themes");
+
+// src/theme/applyCssVariables.ts
+function applyCssVariables(target, vars, previousKeys) {
+  for (const key of previousKeys) {
+    if (!(key in vars)) {
+      target.style.removeProperty(key);
+    }
+  }
+  const nextKeys = /* @__PURE__ */ new Set();
+  for (const [key, value] of Object.entries(vars)) {
+    target.style.setProperty(key, value);
+    nextKeys.add(key);
+  }
+  return nextKeys;
+}
+
+// src/theme/ThemeProvider.tsx
+var import_jsx_runtime3 = require("react/jsx-runtime");
+var ThemeContext = (0, import_react4.createContext)(null);
+var useIsoLayoutEffect2 = typeof window !== "undefined" ? import_react4.useLayoutEffect : import_react4.default.useEffect;
+function getSystemMode() {
+  if (typeof window === "undefined" || typeof window.matchMedia !== "function") {
+    return "light";
+  }
+  return window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
+}
+function resolveModeBase(mode, resolvedMode) {
+  if (mode === "system") {
+    return resolvedMode === "dark" ? import_themes.darkTheme : import_themes.lightTheme;
+  }
+  if (mode === "dark") return import_themes.darkTheme;
+  return import_themes.lightTheme;
+}
+function ThemeProvider(props) {
+  const preset = props.preset ?? "default";
+  const mode = props.mode ?? "light";
+  const targetKind = props.target ?? "document";
+  const [resolvedMode, setResolvedMode] = (0, import_react4.useState)(
+    () => mode === "system" ? getSystemMode() : mode
+  );
+  useIsoLayoutEffect2(() => {
+    if (mode !== "system") {
+      setResolvedMode(mode);
+      return;
+    }
+    setResolvedMode(getSystemMode());
+    if (typeof window === "undefined" || typeof window.matchMedia !== "function") return;
+    const mq = window.matchMedia("(prefers-color-scheme: dark)");
+    const onChange = () => setResolvedMode(mq.matches ? "dark" : "light");
+    mq.addEventListener("change", onChange);
+    return () => mq.removeEventListener("change", onChange);
+  }, [mode]);
+  const dataTheme = mode === "system" ? resolvedMode : mode === "dark" ? "dark" : "light";
+  const effectiveTheme = (0, import_react4.useMemo)(() => {
+    const modeBase = resolveModeBase(mode, dataTheme);
+    const base = preset === "default" ? modeBase : preset === "brand" ? (0, import_themes.mergeThemes)(modeBase, import_themes.brandThemeOverrides) : (0, import_themes.mergeThemes)(modeBase, (0, import_themes.getPresetTheme)(preset));
+    return (0, import_themes.mergeThemes)(base, props.theme ?? {});
+  }, [preset, mode, dataTheme, props.theme]);
+  const hostRef = (0, import_react4.useRef)(null);
+  const appliedKeysRef = (0, import_react4.useRef)(/* @__PURE__ */ new Set());
+  useIsoLayoutEffect2(() => {
+    if (targetKind === "document" && typeof document !== "undefined") {
+      document.documentElement.setAttribute("data-lk-theme", dataTheme);
+      return () => document.documentElement.removeAttribute("data-lk-theme");
+    }
+  }, [targetKind, dataTheme]);
+  const inject = (0, import_react4.useCallback)(() => {
+    const vars = (0, import_themes.themeToCssVariables)(effectiveTheme);
+    const el = targetKind === "document" && typeof document !== "undefined" ? document.documentElement : hostRef.current;
+    if (!el) return;
+    appliedKeysRef.current = applyCssVariables(el, vars, appliedKeysRef.current);
+  }, [effectiveTheme, targetKind]);
+  useIsoLayoutEffect2(() => {
+    inject();
+    return () => {
+      const el = targetKind === "document" && typeof document !== "undefined" ? document.documentElement : hostRef.current;
+      if (!el) return;
+      for (const key of appliedKeysRef.current) {
+        el.style.removeProperty(key);
+      }
+      appliedKeysRef.current = /* @__PURE__ */ new Set();
+    };
+  }, [inject, targetKind]);
+  const value = (0, import_react4.useMemo)(
+    () => ({
+      theme: effectiveTheme,
+      preset,
+      mode,
+      resolvedMode: dataTheme
+    }),
+    [effectiveTheme, preset, mode, dataTheme]
+  );
+  if (targetKind === "document") {
+    return /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(ThemeContext.Provider, { value, children: /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("div", { "data-lk-theme": dataTheme, style: { display: "contents" }, children: props.children }) });
+  }
+  return /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(ThemeContext.Provider, { value, children: /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("div", { ref: hostRef, "data-lk-theme": dataTheme, children: props.children }) });
+}
+function useTheme() {
+  const ctx = (0, import_react4.useContext)(ThemeContext);
+  if (!ctx) {
+    throw new Error("useTheme must be used within a ThemeProvider");
+  }
+  return ctx;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   Course,
@@ -409,9 +551,11 @@ function sanitizeLessonId(id) {
   Quiz,
   Reflection,
   Scenario,
+  ThemeProvider,
   useCompletion,
   useLessonkit,
   useProgress,
   useQuizState,
+  useTheme,
   useTracking
 });

package/dist/index.d.cts

@@ -3,6 +3,8 @@ import React from 'react';
 import * as _lessonkit_core from '@lessonkit/core';
 import { CourseId, TelemetryUser, TelemetryEvent, TrackingClient, LessonId } from '@lessonkit/core';
 import { XAPITransport, XAPIClient } from '@lessonkit/xapi';
+import { LessonkitThemeV1, ThemePresetName, PartialLessonkitThemeV1 } from '@lessonkit/themes';
+export { ThemePresetName } from '@lessonkit/themes';
 
 type LessonkitConfig = {
     courseId?: CourseId;
@@ -107,4 +109,24 @@ declare function useQuizState(): {
     }) => void;
 };
 
-export { Course, KnowledgeCheck, Lesson, type LessonkitConfig, LessonkitProvider, type LessonkitRuntime, ProgressTracker, Quiz, Reflection, Scenario, useCompletion, useLessonkit, useProgress, useQuizState, useTracking };
+type ThemeMode = "light" | "dark" | "system";
+type ThemeResolvedMode = "light" | "dark";
+type ThemeProviderProps = {
+    children: React.ReactNode;
+    /** Partial theme merged on top of the resolved preset (last writer wins). */
+    theme?: PartialLessonkitThemeV1;
+    preset?: ThemePresetName;
+    mode?: ThemeMode;
+    /** `document` injects on `:root`; `element` scopes to the provider wrapper. */
+    target?: "document" | "element";
+};
+type ThemeContextValue = {
+    theme: LessonkitThemeV1;
+    preset: ThemePresetName;
+    mode: ThemeMode;
+    resolvedMode: ThemeResolvedMode;
+};
+declare function ThemeProvider(props: ThemeProviderProps): react_jsx_runtime.JSX.Element;
+declare function useTheme(): ThemeContextValue;
+
+export { Course, KnowledgeCheck, Lesson, type LessonkitConfig, LessonkitProvider, type LessonkitRuntime, ProgressTracker, Quiz, Reflection, Scenario, type ThemeContextValue, type ThemeMode, ThemeProvider, type ThemeProviderProps, type ThemeResolvedMode, useCompletion, useLessonkit, useProgress, useQuizState, useTheme, useTracking };

package/dist/index.d.ts

@@ -3,6 +3,8 @@ import React from 'react';
 import * as _lessonkit_core from '@lessonkit/core';
 import { CourseId, TelemetryUser, TelemetryEvent, TrackingClient, LessonId } from '@lessonkit/core';
 import { XAPITransport, XAPIClient } from '@lessonkit/xapi';
+import { LessonkitThemeV1, ThemePresetName, PartialLessonkitThemeV1 } from '@lessonkit/themes';
+export { ThemePresetName } from '@lessonkit/themes';
 
 type LessonkitConfig = {
     courseId?: CourseId;
@@ -107,4 +109,24 @@ declare function useQuizState(): {
     }) => void;
 };
 
-export { Course, KnowledgeCheck, Lesson, type LessonkitConfig, LessonkitProvider, type LessonkitRuntime, ProgressTracker, Quiz, Reflection, Scenario, useCompletion, useLessonkit, useProgress, useQuizState, useTracking };
+type ThemeMode = "light" | "dark" | "system";
+type ThemeResolvedMode = "light" | "dark";
+type ThemeProviderProps = {
+    children: React.ReactNode;
+    /** Partial theme merged on top of the resolved preset (last writer wins). */
+    theme?: PartialLessonkitThemeV1;
+    preset?: ThemePresetName;
+    mode?: ThemeMode;
+    /** `document` injects on `:root`; `element` scopes to the provider wrapper. */
+    target?: "document" | "element";
+};
+type ThemeContextValue = {
+    theme: LessonkitThemeV1;
+    preset: ThemePresetName;
+    mode: ThemeMode;
+    resolvedMode: ThemeResolvedMode;
+};
+declare function ThemeProvider(props: ThemeProviderProps): react_jsx_runtime.JSX.Element;
+declare function useTheme(): ThemeContextValue;
+
+export { Course, KnowledgeCheck, Lesson, type LessonkitConfig, LessonkitProvider, type LessonkitRuntime, ProgressTracker, Quiz, Reflection, Scenario, type ThemeContextValue, type ThemeMode, ThemeProvider, type ThemeProviderProps, type ThemeResolvedMode, useCompletion, useLessonkit, useProgress, useQuizState, useTheme, useTracking };

package/dist/index.js

@@ -12,50 +12,78 @@ import {
   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?.();
+import { createTrackingClient, nowIso } from "@lessonkit/core";
+import { createInMemoryXAPIQueue } from "@lessonkit/xapi";
+
+// src/runtime/ports.ts
+function createNoopStorage() {
+  return {
+    getItem: () => null,
+    setItem: () => {
+    }
+  };
 }
-function safeSessionStorageGetItem(key) {
-  if (typeof sessionStorage === "undefined") return null;
-  try {
-    return sessionStorage.getItem(key);
-  } catch {
-    return null;
-  }
+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 {
+      }
+    }
+  };
 }
-function safeSessionStorageSetItem(key, value) {
-  if (typeof sessionStorage === "undefined") return;
-  try {
-    sessionStorage.setItem(key, value);
-  } catch {
-  }
+
+// src/runtime/xapi.ts
+import { createXAPIClient } from "@lessonkit/xapi";
+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 resolveSessionId(provided) {
+
+// src/runtime/session.ts
+import { createSessionId } from "@lessonkit/core";
+var SESSION_STORAGE_KEY = "lessonkit:sessionId";
+var COURSE_STARTED_PREFIX = "lessonkit:course_started:";
+function resolveSessionId(storage, provided) {
   if (provided) return provided;
-  const existing = safeSessionStorageGetItem(SESSION_STORAGE_KEY);
+  const existing = storage.getItem(SESSION_STORAGE_KEY);
   if (existing) return existing;
   const id = createSessionId();
-  safeSessionStorageSetItem(SESSION_STORAGE_KEY, id);
+  storage.setItem(SESSION_STORAGE_KEY, id);
   return id;
 }
 function courseStartedStorageKey(sessionId, courseId) {
   return `${COURSE_STARTED_PREFIX}${sessionId}:${courseId ?? ""}`;
 }
-function hasCourseStarted(sessionId, courseId) {
+function hasCourseStarted(storage, sessionId, courseId) {
   if (!courseId) return false;
-  return safeSessionStorageGetItem(courseStartedStorageKey(sessionId, courseId)) === "1";
+  return storage.getItem(courseStartedStorageKey(sessionId, courseId)) === "1";
 }
-function markCourseStarted(sessionId, courseId) {
+function markCourseStarted(storage, sessionId, courseId) {
   if (!courseId) return;
-  safeSessionStorageSetItem(courseStartedStorageKey(sessionId, courseId), "1");
+  storage.setItem(courseStartedStorageKey(sessionId, courseId), "1");
 }
+
+// src/context.tsx
+import { jsx } from "react/jsx-runtime";
+var LessonkitContext = createContext(null);
+var useIsoLayoutEffect = typeof window !== "undefined" ? useLayoutEffect : useEffect;
+function disposeTrackingClient(client) {
+  client?.flush?.();
+  client?.dispose?.();
+}
+var defaultStorage = createSessionStoragePort();
 function createTrackingClientFromConfig(config) {
   if (config.tracking?.enabled === false) {
     return createTrackingClient();
@@ -66,15 +94,9 @@ function createTrackingClientFromConfig(config) {
     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 sessionIdRef = useRef(resolveSessionId(config.session?.sessionId));
+  const sessionIdRef = useRef(resolveSessionId(defaultStorage, config.session?.sessionId));
   if (config.session?.sessionId) sessionIdRef.current = config.session.sessionId;
   const attemptIdRef = useRef(config.session?.attemptId);
   const userRef = useRef(config.session?.user);
@@ -91,17 +113,17 @@ function LessonkitProvider(props) {
   const batchEnabled = config.tracking?.batch?.enabled;
   const batchFlushIntervalMs = config.tracking?.batch?.flushIntervalMs;
   const batchMaxBatchSize = config.tracking?.batch?.maxBatchSize;
-  useLayoutEffect(() => {
+  useIsoLayoutEffect(() => {
     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;
+    const shouldEmitCourseStarted = cid ? !hasCourseStarted(defaultStorage, sessionId, cid) : !courseStartedInProviderRef.current;
     if (shouldEmitCourseStarted) {
       if (cid) {
-        markCourseStarted(sessionId, cid);
+        markCourseStarted(defaultStorage, sessionId, cid);
       } else {
         courseStartedInProviderRef.current = true;
       }
@@ -132,7 +154,7 @@ function LessonkitProvider(props) {
   const xapiClient = config.xapi?.client;
   const xapiTransport = config.xapi?.transport;
   const courseId = config.courseId;
-  useLayoutEffect(() => {
+  useIsoLayoutEffect(() => {
     const prev = xapiRef.current;
     const next = createXapiClientFromConfig(config, xapiQueueRef.current);
     xapiRef.current = next;
@@ -369,6 +391,129 @@ function sanitizeLessonId(id) {
   const s = id.replace(/[^a-zA-Z0-9_-]/g, "");
   return s.length ? s : "id";
 }
+
+// src/theme/ThemeProvider.tsx
+import React3, {
+  createContext as createContext2,
+  useCallback as useCallback2,
+  useContext as useContext2,
+  useLayoutEffect as useLayoutEffect2,
+  useMemo as useMemo4,
+  useRef as useRef3,
+  useState as useState3
+} from "react";
+import {
+  brandThemeOverrides,
+  darkTheme,
+  getPresetTheme,
+  lightTheme,
+  mergeThemes,
+  themeToCssVariables
+} from "@lessonkit/themes";
+
+// src/theme/applyCssVariables.ts
+function applyCssVariables(target, vars, previousKeys) {
+  for (const key of previousKeys) {
+    if (!(key in vars)) {
+      target.style.removeProperty(key);
+    }
+  }
+  const nextKeys = /* @__PURE__ */ new Set();
+  for (const [key, value] of Object.entries(vars)) {
+    target.style.setProperty(key, value);
+    nextKeys.add(key);
+  }
+  return nextKeys;
+}
+
+// src/theme/ThemeProvider.tsx
+import { jsx as jsx3 } from "react/jsx-runtime";
+var ThemeContext = createContext2(null);
+var useIsoLayoutEffect2 = typeof window !== "undefined" ? useLayoutEffect2 : React3.useEffect;
+function getSystemMode() {
+  if (typeof window === "undefined" || typeof window.matchMedia !== "function") {
+    return "light";
+  }
+  return window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
+}
+function resolveModeBase(mode, resolvedMode) {
+  if (mode === "system") {
+    return resolvedMode === "dark" ? darkTheme : lightTheme;
+  }
+  if (mode === "dark") return darkTheme;
+  return lightTheme;
+}
+function ThemeProvider(props) {
+  const preset = props.preset ?? "default";
+  const mode = props.mode ?? "light";
+  const targetKind = props.target ?? "document";
+  const [resolvedMode, setResolvedMode] = useState3(
+    () => mode === "system" ? getSystemMode() : mode
+  );
+  useIsoLayoutEffect2(() => {
+    if (mode !== "system") {
+      setResolvedMode(mode);
+      return;
+    }
+    setResolvedMode(getSystemMode());
+    if (typeof window === "undefined" || typeof window.matchMedia !== "function") return;
+    const mq = window.matchMedia("(prefers-color-scheme: dark)");
+    const onChange = () => setResolvedMode(mq.matches ? "dark" : "light");
+    mq.addEventListener("change", onChange);
+    return () => mq.removeEventListener("change", onChange);
+  }, [mode]);
+  const dataTheme = mode === "system" ? resolvedMode : mode === "dark" ? "dark" : "light";
+  const effectiveTheme = useMemo4(() => {
+    const modeBase = resolveModeBase(mode, dataTheme);
+    const base = preset === "default" ? modeBase : preset === "brand" ? mergeThemes(modeBase, brandThemeOverrides) : mergeThemes(modeBase, getPresetTheme(preset));
+    return mergeThemes(base, props.theme ?? {});
+  }, [preset, mode, dataTheme, props.theme]);
+  const hostRef = useRef3(null);
+  const appliedKeysRef = useRef3(/* @__PURE__ */ new Set());
+  useIsoLayoutEffect2(() => {
+    if (targetKind === "document" && typeof document !== "undefined") {
+      document.documentElement.setAttribute("data-lk-theme", dataTheme);
+      return () => document.documentElement.removeAttribute("data-lk-theme");
+    }
+  }, [targetKind, dataTheme]);
+  const inject = useCallback2(() => {
+    const vars = themeToCssVariables(effectiveTheme);
+    const el = targetKind === "document" && typeof document !== "undefined" ? document.documentElement : hostRef.current;
+    if (!el) return;
+    appliedKeysRef.current = applyCssVariables(el, vars, appliedKeysRef.current);
+  }, [effectiveTheme, targetKind]);
+  useIsoLayoutEffect2(() => {
+    inject();
+    return () => {
+      const el = targetKind === "document" && typeof document !== "undefined" ? document.documentElement : hostRef.current;
+      if (!el) return;
+      for (const key of appliedKeysRef.current) {
+        el.style.removeProperty(key);
+      }
+      appliedKeysRef.current = /* @__PURE__ */ new Set();
+    };
+  }, [inject, targetKind]);
+  const value = useMemo4(
+    () => ({
+      theme: effectiveTheme,
+      preset,
+      mode,
+      resolvedMode: dataTheme
+    }),
+    [effectiveTheme, preset, mode, dataTheme]
+  );
+  if (targetKind === "document") {
+    return /* @__PURE__ */ jsx3(ThemeContext.Provider, { value, children: /* @__PURE__ */ jsx3("div", { "data-lk-theme": dataTheme, style: { display: "contents" }, children: props.children }) });
+  }
+  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);
+  if (!ctx) {
+    throw new Error("useTheme must be used within a ThemeProvider");
+  }
+  return ctx;
+}
 export {
   Course,
   KnowledgeCheck,
@@ -378,9 +523,11 @@ export {
   Quiz,
   Reflection,
   Scenario,
+  ThemeProvider,
   useCompletion,
   useLessonkit,
   useProgress,
   useQuizState,
+  useTheme,
   useTracking
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lessonkit/react",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "private": false,
   "description": "React components and hooks for building learning experiences with LessonKit.",
   "license": "Apache-2.0",
@@ -37,8 +37,8 @@
     "dist"
   ],
   "scripts": {
-    "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",
+    "build": "tsup src/index.tsx --format esm,cjs --dts --external react --external react-dom --external @lessonkit/accessibility --external @lessonkit/themes",
+    "dev": "tsup src/index.tsx --format esm,cjs --dts --watch --external react --external react-dom --external @lessonkit/accessibility --external @lessonkit/themes",
     "prepublishOnly": "npm run build",
     "typecheck": "tsc -p tsconfig.json",
     "test": "vitest run --passWithNoTests",
@@ -50,9 +50,10 @@
     "react-dom": ">=18"
   },
   "dependencies": {
-    "@lessonkit/accessibility": "0.3.0",
-    "@lessonkit/core": "0.3.0",
-    "@lessonkit/xapi": "0.3.0"
+    "@lessonkit/accessibility": "0.4.0",
+    "@lessonkit/core": "0.4.0",
+    "@lessonkit/themes": "0.4.0",
+    "@lessonkit/xapi": "0.4.0"
   },
   "devDependencies": {
     "@testing-library/react": "^16.3.0",