@lessonkit/react 0.8.1 → 0.9.1

package/README.md

@@ -59,7 +59,7 @@ export default function App() {
 }
 ```
 
-## API (0.8.1)
+## API (0.9.1)
 
 ### Block catalog
 

package/dist/index.cjs

@@ -42,6 +42,8 @@ __export(index_exports, {
   ThemeProvider: () => ThemeProvider,
   blockCatalogVersion: () => blockCatalogVersion,
   buildBlockCatalog: () => buildBlockCatalog,
+  createPluginHost: () => import_core7.createPluginHost,
+  defineLessonkitPlugin: () => import_core7.defineLessonkitPlugin,
   getBlockCatalogEntry: () => getBlockCatalogEntry,
   useCompletion: () => useCompletion,
   useLessonkit: () => useLessonkit,
@@ -58,7 +60,7 @@ var import_accessibility = require("@lessonkit/accessibility");
 
 // src/context.tsx
 var import_react = require("react");
-var import_core4 = require("@lessonkit/core");
+var import_core5 = require("@lessonkit/core");
 var import_xapi3 = require("@lessonkit/xapi");
 var import_xapi4 = require("@lessonkit/xapi");
 
@@ -69,46 +71,55 @@ var import_xapi = require("@lessonkit/xapi");
 // src/runtime/lxpackBridge.ts
 var import_bridge = require("@lessonkit/lxpack/bridge");
 function getBridge() {
+  const fromSdk = (0, import_bridge.getLxpackBridge)();
+  if (fromSdk) return fromSdk;
   if (typeof window === "undefined") return null;
   const parent = window.parent;
   if (!parent || parent === window) return null;
-  return parent.lxpackBridge?.v1 ?? parent.lxpack ?? null;
+  return parent.lxpack ?? null;
 }
-function forwardTelemetryToLxpack(event, mode = "auto") {
-  if (mode === "off") return;
-  const bridge = getBridge();
-  if (!bridge) return;
-  switch (event.name) {
-    case "lesson_completed": {
-      const lessonId = event.lessonId;
-      if (lessonId) bridge.completeLesson?.(lessonId);
+function applyBridgeAction(bridge, action) {
+  if (!action) return;
+  switch (action.kind) {
+    case "completeLesson":
+      bridge.completeLesson?.(action.lessonId);
       return;
-    }
-    case "course_completed":
+    case "completeCourse":
       bridge.completeCourse?.();
       return;
-    case "quiz_completed": {
-      const data = event.data;
-      if (!data?.checkId) return;
-      const scaled = (0, import_bridge.normalizeAssessmentScore)({
-        score: data.score,
-        maxScore: data.maxScore
+    case "submitAssessment": {
+      const scaled = (0, import_bridge.normalizeScore)({
+        score: action.score,
+        maxScore: action.maxScore
       });
       if (scaled === null) return;
       bridge.submitAssessment?.({
-        id: data.checkId,
+        id: action.id,
         score: scaled,
-        passingScore: (0, import_bridge.normalizeAssessmentPassingScore)({
-          passingScore: data.passingScore,
-          maxScore: data.maxScore
-        })
+        passingScore: (0, import_bridge.normalizePassingThreshold)({
+          passingScore: action.passingScore,
+          maxScore: action.maxScore
+        }),
+        maxScore: action.maxScore
       });
       return;
     }
+    case "track":
+      bridge.track?.(action.event);
+      return;
     default:
       return;
   }
 }
+function forwardTelemetryToLxpack(event, mode = "auto") {
+  if (mode === "off") return;
+  const bridge = getBridge();
+  if (!bridge) return;
+  const lessonkitEvent = (0, import_bridge.telemetryEventToLessonkit)(event);
+  if (!lessonkitEvent) return;
+  const action = (0, import_bridge.mapLessonkitTelemetryToBridgeAction)(lessonkitEvent);
+  applyBridgeAction(bridge, action);
+}
 
 // src/runtime/emitTelemetry.ts
 var warnedMissingCourseId = false;
@@ -328,12 +339,31 @@ function migrateCourseStartedMark(storage, fromSessionId, toSessionId, courseId)
   }
 }
 
-// src/runtime/telemetry.ts
+// src/runtime/plugins.ts
 var import_core3 = require("@lessonkit/core");
+function createReactPluginHost(plugins) {
+  if (!plugins?.length) return null;
+  return (0, import_core3.createPluginHost)(plugins);
+}
+function buildPluginContext(opts) {
+  return {
+    courseId: opts.courseId,
+    sessionId: opts.sessionId,
+    attemptId: opts.attemptId
+  };
+}
+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" });
+}
+
+// src/runtime/telemetry.ts
+var import_core4 = require("@lessonkit/core");
 function createTrackingClientFromConfig(config) {
-  if (config.tracking?.enabled === false) return (0, import_core3.createTrackingClient)();
+  if (config.tracking?.enabled === false) return (0, import_core4.createTrackingClient)();
   if (config.tracking?.createClient) return config.tracking.createClient();
-  return (0, import_core3.createTrackingClient)({
+  return (0, import_core4.createTrackingClient)({
     sink: config.tracking?.sink,
     batchSink: config.tracking?.batchSink,
     batch: config.tracking?.batch
@@ -369,6 +399,9 @@ function LessonkitProvider(props) {
   courseIdRef.current = config.courseId;
   const lxpackBridgeModeRef = (0, import_react.useRef)(config.lxpack?.bridge ?? "auto");
   lxpackBridgeModeRef.current = config.lxpack?.bridge ?? "auto";
+  const pluginHost = (0, import_react.useMemo)(() => createReactPluginHost(config.plugins), [config.plugins]);
+  const pluginHostRef = (0, import_react.useRef)(pluginHost);
+  pluginHostRef.current = pluginHost;
   const progressRef = (0, import_react.useRef)(createProgressController());
   const courseStartedEmittedToSinkRef = (0, import_react.useRef)(false);
   const prevCourseIdForProgressRef = (0, import_react.useRef)(config.courseId);
@@ -393,6 +426,7 @@ function LessonkitProvider(props) {
   const xapiClient = config.xapi?.client;
   const xapiTransport = config.xapi?.transport;
   const courseId = config.courseId;
+  const trackingEnabled = config.tracking?.enabled;
   useIsoLayoutEffect(() => {
     if (prevXapiCourseIdRef.current !== courseId) {
       xapiQueueRef.current = (0, import_xapi3.createInMemoryXAPIQueue)();
@@ -405,18 +439,22 @@ function LessonkitProvider(props) {
     if (next && !prev) {
       const sessionId = sessionIdRef.current;
       const cid = courseIdRef.current;
-      try {
-        const statement = (0, import_xapi4.telemetryEventToXAPIStatement)(
-          buildTrackEvent({
-            name: "course_started",
-            courseId: cid,
-            sessionId,
-            attemptId: attemptIdRef.current,
-            user: userRef.current
-          })
-        );
-        if (statement) next.send(statement);
-      } catch {
+      const trackingActive = isTrackingActive(config.tracking);
+      const alreadyStarted = hasCourseStarted(defaultStorage, sessionId, cid);
+      if (!trackingActive || alreadyStarted) {
+        try {
+          const statement = (0, import_xapi4.telemetryEventToXAPIStatement)(
+            buildTrackEvent({
+              name: "course_started",
+              courseId: cid,
+              sessionId,
+              attemptId: attemptIdRef.current,
+              user: userRef.current
+            })
+          );
+          if (statement) next.send(statement);
+        } catch {
+        }
       }
     }
     let cancelled = false;
@@ -437,11 +475,10 @@ function LessonkitProvider(props) {
       cancelled = true;
       void prev?.flush();
     };
-  }, [xapiEnabled, xapiClient, xapiTransport, courseId]);
-  const trackingRef = (0, import_react.useRef)((0, import_core4.createTrackingClient)());
+  }, [xapiEnabled, xapiClient, xapiTransport, courseId, trackingEnabled]);
+  const trackingRef = (0, import_react.useRef)((0, import_core5.createTrackingClient)());
   const trackingClientForUnmountRef = (0, import_react.useRef)(trackingRef.current);
   const [tracking, setTracking] = (0, import_react.useState)(() => trackingRef.current);
-  const trackingEnabled = config.tracking?.enabled;
   const trackingSink = config.tracking?.sink;
   const trackingBatchSink = config.tracking?.batchSink;
   const batchEnabled = config.tracking?.batch?.enabled;
@@ -449,7 +486,19 @@ function LessonkitProvider(props) {
   const batchMaxBatchSize = config.tracking?.batch?.maxBatchSize;
   useIsoLayoutEffect(() => {
     const prev = trackingRef.current;
-    const next = createTrackingClientFromConfig({ tracking: config.tracking });
+    const pluginCtx = buildPluginContext({
+      courseId: courseIdRef.current,
+      sessionId: sessionIdRef.current,
+      attemptId: attemptIdRef.current
+    });
+    const sink = pluginHostRef.current?.composeTrackingSink(config.tracking?.sink, pluginCtx) ?? config.tracking?.sink;
+    const batchSink = pluginHostRef.current && config.tracking?.batchSink ? (events) => {
+      const filtered = pluginHostRef.current.runTelemetryBatch(events, pluginCtx);
+      return config.tracking.batchSink(filtered);
+    } : config.tracking?.batchSink;
+    const next = createTrackingClientFromConfig({
+      tracking: { ...config.tracking, sink, batchSink }
+    });
     trackingRef.current = next;
     trackingClientForUnmountRef.current = next;
     setTracking(next);
@@ -460,18 +509,24 @@ function LessonkitProvider(props) {
       courseStartedEmittedToSinkRef.current = false;
     } else if (!courseStartedEmittedToSinkRef.current && !hasCourseStarted(defaultStorage, sessionId, cid)) {
       markCourseStarted(defaultStorage, sessionId, cid);
-      emitTelemetry(
-        next,
-        xapiRef.current,
-        buildTrackEvent({
+      emitTelemetryWithPlugins({
+        pluginHost: pluginHostRef.current,
+        tracking: next,
+        xapi: xapiRef.current,
+        event: buildTrackEvent({
           name: "course_started",
           courseId: cid,
           sessionId,
           attemptId: attemptIdRef.current,
           user: userRef.current
         }),
-        { lxpackBridge: lxpackBridgeModeRef.current }
-      );
+        pluginCtx: buildPluginContext({
+          courseId: cid,
+          sessionId,
+          attemptId: attemptIdRef.current
+        }),
+        lxpackBridge: lxpackBridgeModeRef.current
+      });
       courseStartedEmittedToSinkRef.current = true;
     } else if (trackingActive) {
       courseStartedEmittedToSinkRef.current = true;
@@ -487,16 +542,23 @@ function LessonkitProvider(props) {
     trackingBatchSink,
     batchEnabled,
     batchFlushIntervalMs,
-    batchMaxBatchSize
+    batchMaxBatchSize,
+    config.plugins
   ]);
-  const emitWithBridge = (0, import_react.useCallback)(
-    (trackingClient, event) => {
-      emitTelemetry(trackingClient, xapiRef.current, event, {
-        lxpackBridge: lxpackBridgeModeRef.current
-      });
-    },
-    []
-  );
+  const emitWithBridge = (0, import_react.useCallback)((trackingClient, event) => {
+    emitTelemetryWithPlugins({
+      pluginHost: pluginHostRef.current,
+      tracking: trackingClient,
+      xapi: xapiRef.current,
+      event,
+      pluginCtx: buildPluginContext({
+        courseId: courseIdRef.current,
+        sessionId: sessionIdRef.current,
+        attemptId: attemptIdRef.current
+      }),
+      lxpackBridge: lxpackBridgeModeRef.current
+    });
+  }, []);
   const track = (0, import_react.useCallback)(
     (name, data, opts) => {
       const event = tryBuildTrackEvent({
@@ -522,18 +584,24 @@ function LessonkitProvider(props) {
     const cid = courseIdRef.current;
     if (!courseStartedEmittedToSinkRef.current && !hasCourseStarted(defaultStorage, sessionId, cid)) {
       markCourseStarted(defaultStorage, sessionId, cid);
-      emitTelemetry(
-        trackingRef.current,
-        xapiRef.current,
-        buildTrackEvent({
+      emitTelemetryWithPlugins({
+        pluginHost: pluginHostRef.current,
+        tracking: trackingRef.current,
+        xapi: xapiRef.current,
+        event: buildTrackEvent({
           name: "course_started",
           courseId: cid,
           sessionId,
           attemptId: attemptIdRef.current,
           user: userRef.current
         }),
-        { lxpackBridge: lxpackBridgeModeRef.current }
-      );
+        pluginCtx: buildPluginContext({
+          courseId: cid,
+          sessionId,
+          attemptId: attemptIdRef.current
+        }),
+        lxpackBridge: lxpackBridgeModeRef.current
+      });
       courseStartedEmittedToSinkRef.current = true;
     }
   }, [config.courseId, config.tracking?.enabled, syncProgress]);
@@ -600,6 +668,18 @@ function LessonkitProvider(props) {
   const sessionUser = config.session?.user;
   const sessionAttemptId = config.session?.attemptId;
   const sessionConfiguredId = config.session?.sessionId;
+  (0, import_react.useEffect)(() => {
+    if (!pluginHost) return;
+    const ctx = buildPluginContext({
+      courseId: courseIdRef.current,
+      sessionId: sessionIdRef.current,
+      attemptId: attemptIdRef.current
+    });
+    pluginHost.setupAll(ctx);
+    return () => {
+      pluginHost.disposeAll();
+    };
+  }, [pluginHost, config.courseId, sessionAttemptId, sessionConfiguredId]);
   (0, import_react.useEffect)(() => {
     const nextConfigured = config.session?.sessionId;
     const prevConfigured = prevConfiguredSessionIdRef.current;
@@ -633,7 +713,8 @@ function LessonkitProvider(props) {
       setActiveLesson,
       completeLesson,
       completeCourse,
-      track
+      track,
+      plugins: pluginHost
     }),
     [
       config,
@@ -644,6 +725,7 @@ function LessonkitProvider(props) {
       completeLesson,
       completeCourse,
       track,
+      pluginHost,
       sessionUser,
       sessionAttemptId,
       sessionConfiguredId
@@ -687,7 +769,7 @@ function useQuizState() {
 }
 
 // src/runtime/validateComponentId.ts
-var import_core5 = require("@lessonkit/core");
+var import_core6 = require("@lessonkit/core");
 var warnedPaths = /* @__PURE__ */ new Set();
 function isDevEnvironment2() {
   const g = globalThis;
@@ -697,7 +779,7 @@ function warnInvalidComponentId(id, path) {
   if (!isDevEnvironment2()) return;
   const key = `${path}:${String(id)}`;
   if (warnedPaths.has(key)) return;
-  const result = (0, import_core5.validateId)(id, path);
+  const result = (0, import_core6.validateId)(id, path);
   if (result.ok) return;
   warnedPaths.add(key);
   const detail = result.issues.map((i) => `${i.path}: ${i.message}`).join("; ");
@@ -822,6 +904,9 @@ function ProgressTracker() {
   ] }) });
 }
 
+// src/index.tsx
+var import_core7 = require("@lessonkit/core");
+
 // src/theme/ThemeProvider.tsx
 var import_react4 = __toESM(require("react"), 1);
 var import_themes = require("@lessonkit/themes");
@@ -1130,6 +1215,8 @@ function getBlockCatalogEntry(type) {
   ThemeProvider,
   blockCatalogVersion,
   buildBlockCatalog,
+  createPluginHost,
+  defineLessonkitPlugin,
   getBlockCatalogEntry,
   useCompletion,
   useLessonkit,

package/dist/index.d.cts

@@ -1,7 +1,8 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import React from 'react';
 import * as _lessonkit_core from '@lessonkit/core';
-import { LessonId, CourseId, TelemetryUser, TrackingClient, TelemetryEventName, CheckId, BlockId } from '@lessonkit/core';
+import { LessonId, CourseId, TelemetryUser, TrackingClient, LessonkitPlugin, TelemetryEventName, PluginHost, CheckId, BlockId } from '@lessonkit/core';
+export { AssessmentScoreInput, AssessmentScoreResult, InteractionBlockRegistration, LessonkitPlugin, LessonkitPluginContext, LessonkitPluginKind, PluginHost, createPluginHost, defineLessonkitPlugin } from '@lessonkit/core';
 import { XAPITransport, XAPIClient } from '@lessonkit/xapi';
 import { LessonkitThemeV1, ThemePresetName, PartialLessonkitThemeV1 } from '@lessonkit/themes';
 export { ThemePresetName } from '@lessonkit/themes';
@@ -38,6 +39,8 @@ type LessonkitConfig = {
         /** Forward completion events to `window.parent.lxpackBridge.v1` when embedded (default `auto`). */
         bridge?: "auto" | "off";
     };
+    /** Framework plugins (analytics, LMS, assessment, interaction, AI). */
+    plugins?: LessonkitPlugin[];
 };
 
 type LessonkitRuntime = {
@@ -56,6 +59,7 @@ type LessonkitRuntime = {
     track: (name: TelemetryEventName, data?: unknown, opts?: {
         lessonId?: LessonId;
     }) => void;
+    plugins: PluginHost | null;
 };
 declare function LessonkitProvider(props: {
     config: LessonkitConfig;

package/dist/index.d.ts

@@ -1,7 +1,8 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import React from 'react';
 import * as _lessonkit_core from '@lessonkit/core';
-import { LessonId, CourseId, TelemetryUser, TrackingClient, TelemetryEventName, CheckId, BlockId } from '@lessonkit/core';
+import { LessonId, CourseId, TelemetryUser, TrackingClient, LessonkitPlugin, TelemetryEventName, PluginHost, CheckId, BlockId } from '@lessonkit/core';
+export { AssessmentScoreInput, AssessmentScoreResult, InteractionBlockRegistration, LessonkitPlugin, LessonkitPluginContext, LessonkitPluginKind, PluginHost, createPluginHost, defineLessonkitPlugin } from '@lessonkit/core';
 import { XAPITransport, XAPIClient } from '@lessonkit/xapi';
 import { LessonkitThemeV1, ThemePresetName, PartialLessonkitThemeV1 } from '@lessonkit/themes';
 export { ThemePresetName } from '@lessonkit/themes';
@@ -38,6 +39,8 @@ type LessonkitConfig = {
         /** Forward completion events to `window.parent.lxpackBridge.v1` when embedded (default `auto`). */
         bridge?: "auto" | "off";
     };
+    /** Framework plugins (analytics, LMS, assessment, interaction, AI). */
+    plugins?: LessonkitPlugin[];
 };
 
 type LessonkitRuntime = {
@@ -56,6 +59,7 @@ type LessonkitRuntime = {
     track: (name: TelemetryEventName, data?: unknown, opts?: {
         lessonId?: LessonId;
     }) => void;
+    plugins: PluginHost | null;
 };
 declare function LessonkitProvider(props: {
     config: LessonkitConfig;

package/dist/index.js

@@ -22,50 +22,62 @@ import { telemetryEventToXAPIStatement } from "@lessonkit/xapi";
 
 // src/runtime/lxpackBridge.ts
 import {
-  normalizeAssessmentPassingScore,
-  normalizeAssessmentScore
+  getLxpackBridge as getLxpackBridgeFromSdk,
+  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.lxpackBridge?.v1 ?? parent.lxpack ?? null;
+  return parent.lxpack ?? null;
 }
-function forwardTelemetryToLxpack(event, mode = "auto") {
-  if (mode === "off") return;
-  const bridge = getBridge();
-  if (!bridge) return;
-  switch (event.name) {
-    case "lesson_completed": {
-      const lessonId = event.lessonId;
-      if (lessonId) bridge.completeLesson?.(lessonId);
+function applyBridgeAction(bridge, action) {
+  if (!action) return;
+  switch (action.kind) {
+    case "completeLesson":
+      bridge.completeLesson?.(action.lessonId);
       return;
-    }
-    case "course_completed":
+    case "completeCourse":
       bridge.completeCourse?.();
       return;
-    case "quiz_completed": {
-      const data = event.data;
-      if (!data?.checkId) return;
-      const scaled = normalizeAssessmentScore({
-        score: data.score,
-        maxScore: data.maxScore
+    case "submitAssessment": {
+      const scaled = normalizeScore({
+        score: action.score,
+        maxScore: action.maxScore
       });
       if (scaled === null) return;
       bridge.submitAssessment?.({
-        id: data.checkId,
+        id: action.id,
         score: scaled,
-        passingScore: normalizeAssessmentPassingScore({
-          passingScore: data.passingScore,
-          maxScore: data.maxScore
-        })
+        passingScore: normalizePassingThreshold({
+          passingScore: action.passingScore,
+          maxScore: action.maxScore
+        }),
+        maxScore: action.maxScore
       });
       return;
     }
+    case "track":
+      bridge.track?.(action.event);
+      return;
     default:
       return;
   }
 }
+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);
+}
 
 // src/runtime/emitTelemetry.ts
 var warnedMissingCourseId = false;
@@ -285,6 +297,25 @@ function migrateCourseStartedMark(storage, fromSessionId, toSessionId, courseId)
   }
 }
 
+// src/runtime/plugins.ts
+import { createPluginHost } from "@lessonkit/core";
+function createReactPluginHost(plugins) {
+  if (!plugins?.length) return null;
+  return createPluginHost(plugins);
+}
+function buildPluginContext(opts) {
+  return {
+    courseId: opts.courseId,
+    sessionId: opts.sessionId,
+    attemptId: opts.attemptId
+  };
+}
+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" });
+}
+
 // src/runtime/telemetry.ts
 import { createTrackingClient } from "@lessonkit/core";
 function createTrackingClientFromConfig(config) {
@@ -326,6 +357,9 @@ function LessonkitProvider(props) {
   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 pluginHostRef = useRef(pluginHost);
+  pluginHostRef.current = pluginHost;
   const progressRef = useRef(createProgressController());
   const courseStartedEmittedToSinkRef = useRef(false);
   const prevCourseIdForProgressRef = useRef(config.courseId);
@@ -350,6 +384,7 @@ function LessonkitProvider(props) {
   const xapiClient = config.xapi?.client;
   const xapiTransport = config.xapi?.transport;
   const courseId = config.courseId;
+  const trackingEnabled = config.tracking?.enabled;
   useIsoLayoutEffect(() => {
     if (prevXapiCourseIdRef.current !== courseId) {
       xapiQueueRef.current = createInMemoryXAPIQueue();
@@ -362,18 +397,22 @@ function LessonkitProvider(props) {
     if (next && !prev) {
       const sessionId = sessionIdRef.current;
       const cid = courseIdRef.current;
-      try {
-        const statement = telemetryEventToXAPIStatement2(
-          buildTrackEvent({
-            name: "course_started",
-            courseId: cid,
-            sessionId,
-            attemptId: attemptIdRef.current,
-            user: userRef.current
-          })
-        );
-        if (statement) next.send(statement);
-      } catch {
+      const trackingActive = isTrackingActive(config.tracking);
+      const alreadyStarted = hasCourseStarted(defaultStorage, sessionId, cid);
+      if (!trackingActive || alreadyStarted) {
+        try {
+          const statement = telemetryEventToXAPIStatement2(
+            buildTrackEvent({
+              name: "course_started",
+              courseId: cid,
+              sessionId,
+              attemptId: attemptIdRef.current,
+              user: userRef.current
+            })
+          );
+          if (statement) next.send(statement);
+        } catch {
+        }
       }
     }
     let cancelled = false;
@@ -394,11 +433,10 @@ function LessonkitProvider(props) {
       cancelled = true;
       void prev?.flush();
     };
-  }, [xapiEnabled, xapiClient, xapiTransport, courseId]);
+  }, [xapiEnabled, xapiClient, xapiTransport, courseId, trackingEnabled]);
   const trackingRef = useRef(createTrackingClient2());
   const trackingClientForUnmountRef = useRef(trackingRef.current);
   const [tracking, setTracking] = useState(() => trackingRef.current);
-  const trackingEnabled = config.tracking?.enabled;
   const trackingSink = config.tracking?.sink;
   const trackingBatchSink = config.tracking?.batchSink;
   const batchEnabled = config.tracking?.batch?.enabled;
@@ -406,7 +444,19 @@ function LessonkitProvider(props) {
   const batchMaxBatchSize = config.tracking?.batch?.maxBatchSize;
   useIsoLayoutEffect(() => {
     const prev = trackingRef.current;
-    const next = createTrackingClientFromConfig({ tracking: config.tracking });
+    const pluginCtx = buildPluginContext({
+      courseId: courseIdRef.current,
+      sessionId: sessionIdRef.current,
+      attemptId: attemptIdRef.current
+    });
+    const sink = pluginHostRef.current?.composeTrackingSink(config.tracking?.sink, pluginCtx) ?? config.tracking?.sink;
+    const batchSink = pluginHostRef.current && config.tracking?.batchSink ? (events) => {
+      const filtered = pluginHostRef.current.runTelemetryBatch(events, pluginCtx);
+      return config.tracking.batchSink(filtered);
+    } : config.tracking?.batchSink;
+    const next = createTrackingClientFromConfig({
+      tracking: { ...config.tracking, sink, batchSink }
+    });
     trackingRef.current = next;
     trackingClientForUnmountRef.current = next;
     setTracking(next);
@@ -417,18 +467,24 @@ function LessonkitProvider(props) {
       courseStartedEmittedToSinkRef.current = false;
     } else if (!courseStartedEmittedToSinkRef.current && !hasCourseStarted(defaultStorage, sessionId, cid)) {
       markCourseStarted(defaultStorage, sessionId, cid);
-      emitTelemetry(
-        next,
-        xapiRef.current,
-        buildTrackEvent({
+      emitTelemetryWithPlugins({
+        pluginHost: pluginHostRef.current,
+        tracking: next,
+        xapi: xapiRef.current,
+        event: buildTrackEvent({
           name: "course_started",
           courseId: cid,
           sessionId,
           attemptId: attemptIdRef.current,
           user: userRef.current
         }),
-        { lxpackBridge: lxpackBridgeModeRef.current }
-      );
+        pluginCtx: buildPluginContext({
+          courseId: cid,
+          sessionId,
+          attemptId: attemptIdRef.current
+        }),
+        lxpackBridge: lxpackBridgeModeRef.current
+      });
       courseStartedEmittedToSinkRef.current = true;
     } else if (trackingActive) {
       courseStartedEmittedToSinkRef.current = true;
@@ -444,16 +500,23 @@ function LessonkitProvider(props) {
     trackingBatchSink,
     batchEnabled,
     batchFlushIntervalMs,
-    batchMaxBatchSize
+    batchMaxBatchSize,
+    config.plugins
   ]);
-  const emitWithBridge = useCallback(
-    (trackingClient, event) => {
-      emitTelemetry(trackingClient, xapiRef.current, event, {
-        lxpackBridge: lxpackBridgeModeRef.current
-      });
-    },
-    []
-  );
+  const emitWithBridge = useCallback((trackingClient, event) => {
+    emitTelemetryWithPlugins({
+      pluginHost: pluginHostRef.current,
+      tracking: trackingClient,
+      xapi: xapiRef.current,
+      event,
+      pluginCtx: buildPluginContext({
+        courseId: courseIdRef.current,
+        sessionId: sessionIdRef.current,
+        attemptId: attemptIdRef.current
+      }),
+      lxpackBridge: lxpackBridgeModeRef.current
+    });
+  }, []);
   const track = useCallback(
     (name, data, opts) => {
       const event = tryBuildTrackEvent({
@@ -479,18 +542,24 @@ function LessonkitProvider(props) {
     const cid = courseIdRef.current;
     if (!courseStartedEmittedToSinkRef.current && !hasCourseStarted(defaultStorage, sessionId, cid)) {
       markCourseStarted(defaultStorage, sessionId, cid);
-      emitTelemetry(
-        trackingRef.current,
-        xapiRef.current,
-        buildTrackEvent({
+      emitTelemetryWithPlugins({
+        pluginHost: pluginHostRef.current,
+        tracking: trackingRef.current,
+        xapi: xapiRef.current,
+        event: buildTrackEvent({
           name: "course_started",
           courseId: cid,
           sessionId,
           attemptId: attemptIdRef.current,
           user: userRef.current
         }),
-        { lxpackBridge: lxpackBridgeModeRef.current }
-      );
+        pluginCtx: buildPluginContext({
+          courseId: cid,
+          sessionId,
+          attemptId: attemptIdRef.current
+        }),
+        lxpackBridge: lxpackBridgeModeRef.current
+      });
       courseStartedEmittedToSinkRef.current = true;
     }
   }, [config.courseId, config.tracking?.enabled, syncProgress]);
@@ -557,6 +626,18 @@ function LessonkitProvider(props) {
   const sessionUser = config.session?.user;
   const sessionAttemptId = config.session?.attemptId;
   const sessionConfiguredId = config.session?.sessionId;
+  useEffect(() => {
+    if (!pluginHost) return;
+    const ctx = buildPluginContext({
+      courseId: courseIdRef.current,
+      sessionId: sessionIdRef.current,
+      attemptId: attemptIdRef.current
+    });
+    pluginHost.setupAll(ctx);
+    return () => {
+      pluginHost.disposeAll();
+    };
+  }, [pluginHost, config.courseId, sessionAttemptId, sessionConfiguredId]);
   useEffect(() => {
     const nextConfigured = config.session?.sessionId;
     const prevConfigured = prevConfiguredSessionIdRef.current;
@@ -590,7 +671,8 @@ function LessonkitProvider(props) {
       setActiveLesson,
       completeLesson,
       completeCourse,
-      track
+      track,
+      plugins: pluginHost
     }),
     [
       config,
@@ -601,6 +683,7 @@ function LessonkitProvider(props) {
       completeLesson,
       completeCourse,
       track,
+      pluginHost,
       sessionUser,
       sessionAttemptId,
       sessionConfiguredId
@@ -779,6 +862,9 @@ function ProgressTracker() {
   ] }) });
 }
 
+// src/index.tsx
+import { createPluginHost as createPluginHost2, defineLessonkitPlugin } from "@lessonkit/core";
+
 // src/theme/ThemeProvider.tsx
 import React3, {
   createContext as createContext2,
@@ -1101,6 +1187,8 @@ export {
   ThemeProvider,
   blockCatalogVersion,
   buildBlockCatalog,
+  createPluginHost2 as createPluginHost,
+  defineLessonkitPlugin,
   getBlockCatalogEntry,
   useCompletion,
   useLessonkit,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lessonkit/react",
-  "version": "0.8.1",
+  "version": "0.9.1",
   "private": false,
   "description": "React components and hooks for building learning experiences with LessonKit.",
   "license": "Apache-2.0",
@@ -54,11 +54,11 @@
     "react-dom": ">=18"
   },
   "dependencies": {
-    "@lessonkit/accessibility": "0.8.1",
-    "@lessonkit/core": "0.8.1",
-    "@lessonkit/lxpack": "0.8.1",
-    "@lessonkit/themes": "0.8.1",
-    "@lessonkit/xapi": "0.8.1"
+    "@lessonkit/accessibility": "0.9.1",
+    "@lessonkit/core": "0.9.1",
+    "@lessonkit/lxpack": "0.9.1",
+    "@lessonkit/themes": "0.9.1",
+    "@lessonkit/xapi": "0.9.1"
   },
   "devDependencies": {
     "@testing-library/react": "^16.3.0",