@lessonkit/react 0.7.0 → 0.8.1

package/dist/index.cjs

@@ -30,6 +30,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.tsx
 var index_exports = {};
 __export(index_exports, {
+  BLOCK_CATALOG: () => BLOCK_CATALOG,
   Course: () => Course,
   KnowledgeCheck: () => KnowledgeCheck,
   Lesson: () => Lesson,
@@ -39,6 +40,9 @@ __export(index_exports, {
   Reflection: () => Reflection,
   Scenario: () => Scenario,
   ThemeProvider: () => ThemeProvider,
+  blockCatalogVersion: () => blockCatalogVersion,
+  buildBlockCatalog: () => buildBlockCatalog,
+  getBlockCatalogEntry: () => getBlockCatalogEntry,
   useCompletion: () => useCompletion,
   useLessonkit: () => useLessonkit,
   useProgress: () => useProgress,
@@ -54,7 +58,7 @@ var import_accessibility = require("@lessonkit/accessibility");
 
 // src/context.tsx
 var import_react = require("react");
-var import_core3 = require("@lessonkit/core");
+var import_core4 = require("@lessonkit/core");
 var import_xapi3 = require("@lessonkit/xapi");
 var import_xapi4 = require("@lessonkit/xapi");
 
@@ -94,7 +98,10 @@ function forwardTelemetryToLxpack(event, mode = "auto") {
       bridge.submitAssessment?.({
         id: data.checkId,
         score: scaled,
-        passingScore: (0, import_bridge.normalizeAssessmentPassingScore)(data.passingScore)
+        passingScore: (0, import_bridge.normalizeAssessmentPassingScore)({
+          passingScore: data.passingScore,
+          maxScore: data.maxScore
+        })
       });
       return;
     }
@@ -225,6 +232,12 @@ function createSessionStoragePort() {
         sessionStorage.setItem(key, value);
       } catch {
       }
+    },
+    removeItem: (key) => {
+      try {
+        sessionStorage.removeItem(key);
+      } catch {
+      }
     }
   };
 }
@@ -272,6 +285,8 @@ function createXapiClientFromConfig(config, queue) {
   if (config.xapi?.enabled === false) return null;
   if (config.xapi?.client) return config.xapi.client;
   if (!config.courseId) return null;
+  const hasTransport = typeof config.xapi?.transport === "function";
+  if (!hasTransport && config.xapi?.enabled !== true) return null;
   return (0, import_xapi2.createXAPIClient)({
     courseId: config.courseId,
     transport: config.xapi?.transport,
@@ -282,6 +297,9 @@ function createXapiClientFromConfig(config, queue) {
 // src/runtime/session.ts
 var import_core2 = require("@lessonkit/core");
 var SESSION_STORAGE_KEY = "lessonkit:sessionId";
+function getTabSessionId(storage) {
+  return storage.getItem(SESSION_STORAGE_KEY);
+}
 var COURSE_STARTED_PREFIX = "lessonkit:course_started:";
 function resolveSessionId(storage, provided) {
   if (provided) return provided;
@@ -302,30 +320,47 @@ function markCourseStarted(storage, sessionId, courseId) {
   if (!courseId) return;
   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?.();
+function migrateCourseStartedMark(storage, fromSessionId, toSessionId, courseId) {
+  if (!courseId || fromSessionId === toSessionId) return;
+  if (hasCourseStarted(storage, fromSessionId, courseId)) {
+    markCourseStarted(storage, toSessionId, courseId);
+    storage.removeItem?.(courseStartedStorageKey(fromSessionId, courseId));
+  }
 }
-var defaultStorage = createSessionStoragePort();
+
+// src/runtime/telemetry.ts
+var import_core3 = require("@lessonkit/core");
 function createTrackingClientFromConfig(config) {
-  if (config.tracking?.enabled === false) {
-    return (0, import_core3.createTrackingClient)();
-  }
+  if (config.tracking?.enabled === false) return (0, import_core3.createTrackingClient)();
+  if (config.tracking?.createClient) return config.tracking.createClient();
   return (0, import_core3.createTrackingClient)({
     sink: config.tracking?.sink,
     batchSink: config.tracking?.batchSink,
     batch: config.tracking?.batch
   });
 }
+function disposeTrackingClient(client) {
+  client?.flush?.();
+  client?.dispose?.();
+}
+
+// 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;
+var defaultStorage = createSessionStoragePort();
+function isTrackingActive(tracking) {
+  return tracking?.enabled !== false;
+}
 function LessonkitProvider(props) {
   const config = props.config;
   const sessionIdRef = (0, import_react.useRef)(resolveSessionId(defaultStorage, config.session?.sessionId));
-  if (config.session?.sessionId) sessionIdRef.current = config.session.sessionId;
+  const prevConfiguredSessionIdRef = (0, import_react.useRef)(config.session?.sessionId);
+  if (config.session?.sessionId) {
+    sessionIdRef.current = config.session.sessionId;
+  } else if (prevConfiguredSessionIdRef.current) {
+    sessionIdRef.current = resolveSessionId(defaultStorage, void 0);
+  }
   const attemptIdRef = (0, import_react.useRef)(config.session?.attemptId);
   const userRef = (0, import_react.useRef)(config.session?.user);
   attemptIdRef.current = config.session?.attemptId;
@@ -335,6 +370,15 @@ function LessonkitProvider(props) {
   const lxpackBridgeModeRef = (0, import_react.useRef)(config.lxpack?.bridge ?? "auto");
   lxpackBridgeModeRef.current = config.lxpack?.bridge ?? "auto";
   const progressRef = (0, import_react.useRef)(createProgressController());
+  const courseStartedEmittedToSinkRef = (0, import_react.useRef)(false);
+  const prevCourseIdForProgressRef = (0, import_react.useRef)(config.courseId);
+  const pendingCourseIdResetRef = (0, import_react.useRef)(false);
+  if (prevCourseIdForProgressRef.current !== config.courseId) {
+    prevCourseIdForProgressRef.current = config.courseId;
+    progressRef.current = createProgressController();
+    pendingCourseIdResetRef.current = true;
+    courseStartedEmittedToSinkRef.current = false;
+  }
   const [progress, setProgress] = (0, import_react.useState)(() => progressRef.current.getState());
   const syncProgress = (0, import_react.useCallback)(() => {
     setProgress(progressRef.current.getState());
@@ -344,11 +388,16 @@ function LessonkitProvider(props) {
   const xapiQueueRef = (0, import_react.useRef)((0, import_xapi3.createInMemoryXAPIQueue)());
   const xapiRef = (0, import_react.useRef)(null);
   const [xapi, setXapi] = (0, import_react.useState)(null);
+  const prevXapiCourseIdRef = (0, import_react.useRef)(config.courseId);
   const xapiEnabled = config.xapi?.enabled;
   const xapiClient = config.xapi?.client;
   const xapiTransport = config.xapi?.transport;
   const courseId = config.courseId;
   useIsoLayoutEffect(() => {
+    if (prevXapiCourseIdRef.current !== courseId) {
+      xapiQueueRef.current = (0, import_xapi3.createInMemoryXAPIQueue)();
+      prevXapiCourseIdRef.current = courseId;
+    }
     const prev = xapiRef.current;
     const next = createXapiClientFromConfig(config, xapiQueueRef.current);
     xapiRef.current = next;
@@ -356,22 +405,21 @@ function LessonkitProvider(props) {
     if (next && !prev) {
       const sessionId = sessionIdRef.current;
       const cid = courseIdRef.current;
-      if (hasCourseStarted(defaultStorage, sessionId, cid)) {
-        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 {
-        }
+      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;
     void (async () => {
       if (prev) {
         try {
@@ -379,16 +427,19 @@ function LessonkitProvider(props) {
         } catch {
         }
       }
+      if (cancelled) return;
       try {
         await next?.flush();
       } catch {
       }
     })();
     return () => {
+      cancelled = true;
       void prev?.flush();
     };
   }, [xapiEnabled, xapiClient, xapiTransport, courseId]);
-  const trackingRef = (0, import_react.useRef)((0, import_core3.createTrackingClient)());
+  const trackingRef = (0, import_react.useRef)((0, import_core4.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;
@@ -398,12 +449,16 @@ function LessonkitProvider(props) {
   const batchMaxBatchSize = config.tracking?.batch?.maxBatchSize;
   useIsoLayoutEffect(() => {
     const prev = trackingRef.current;
-    const next = createTrackingClientFromConfig(config);
+    const next = createTrackingClientFromConfig({ tracking: config.tracking });
     trackingRef.current = next;
+    trackingClientForUnmountRef.current = next;
     setTracking(next);
     const sessionId = sessionIdRef.current;
     const cid = courseIdRef.current;
-    if (!hasCourseStarted(defaultStorage, sessionId, cid)) {
+    const trackingActive = isTrackingActive(config.tracking);
+    if (!trackingActive) {
+      courseStartedEmittedToSinkRef.current = false;
+    } else if (!courseStartedEmittedToSinkRef.current && !hasCourseStarted(defaultStorage, sessionId, cid)) {
       markCourseStarted(defaultStorage, sessionId, cid);
       emitTelemetry(
         next,
@@ -417,6 +472,9 @@ function LessonkitProvider(props) {
         }),
         { lxpackBridge: lxpackBridgeModeRef.current }
       );
+      courseStartedEmittedToSinkRef.current = true;
+    } else if (trackingActive) {
+      courseStartedEmittedToSinkRef.current = true;
     }
     return () => {
       if (prev !== trackingRef.current) {
@@ -455,21 +513,14 @@ function LessonkitProvider(props) {
     },
     [emitWithBridge]
   );
-  const prevCourseIdRef = (0, import_react.useRef)(config.courseId);
-  (0, import_react.useEffect)(() => {
-    if (prevCourseIdRef.current === config.courseId) return;
-    const previousActiveLesson = progressRef.current.getState().activeLessonId;
-    prevCourseIdRef.current = config.courseId;
-    progressRef.current = createProgressController();
+  (0, import_react.useLayoutEffect)(() => {
+    if (!pendingCourseIdResetRef.current) return;
+    pendingCourseIdResetRef.current = false;
     syncProgress();
-    if (previousActiveLesson) {
-      progressRef.current.setActiveLesson(previousActiveLesson, Date.now());
-      syncProgress();
-      track("lesson_started", { lessonId: previousActiveLesson }, { lessonId: previousActiveLesson });
-    }
+    if (!isTrackingActive(config.tracking)) return;
     const sessionId = sessionIdRef.current;
-    const cid = config.courseId;
-    if (!hasCourseStarted(defaultStorage, sessionId, cid)) {
+    const cid = courseIdRef.current;
+    if (!courseStartedEmittedToSinkRef.current && !hasCourseStarted(defaultStorage, sessionId, cid)) {
       markCourseStarted(defaultStorage, sessionId, cid);
       emitTelemetry(
         trackingRef.current,
@@ -483,8 +534,9 @@ function LessonkitProvider(props) {
         }),
         { lxpackBridge: lxpackBridgeModeRef.current }
       );
+      courseStartedEmittedToSinkRef.current = true;
     }
-  }, [config.courseId, syncProgress, track]);
+  }, [config.courseId, config.tracking?.enabled, syncProgress]);
   const emitLessonCompleted = (0, import_react.useCallback)(
     (lessonId, durationMs) => {
       track("lesson_completed", { lessonId, durationMs }, { lessonId });
@@ -504,16 +556,21 @@ function LessonkitProvider(props) {
     },
     [syncProgress, emitLessonCompleted]
   );
+  const unmountTimerIdsRef = (0, import_react.useRef)([]);
   (0, import_react.useEffect)(() => {
     return () => {
-      const client = trackingRef.current;
+      for (const id of unmountTimerIdsRef.current) clearTimeout(id);
+      unmountTimerIdsRef.current = [];
+      const client = trackingClientForUnmountRef.current;
       void xapiRef.current?.flush();
-      setTimeout(() => {
+      const flushTimer = setTimeout(() => {
         client?.flush?.();
-        setTimeout(() => {
+        const disposeTimer = setTimeout(() => {
           client?.dispose?.();
         }, 0);
+        unmountTimerIdsRef.current.push(disposeTimer);
       }, 0);
+      unmountTimerIdsRef.current.push(flushTimer);
     };
   }, []);
   const setActiveLesson = (0, import_react.useCallback)(
@@ -538,10 +595,34 @@ function LessonkitProvider(props) {
     if (!result.didComplete) return;
     syncProgress();
     track("course_completed");
+    void trackingRef.current?.flush?.();
   }, [track, syncProgress]);
   const sessionUser = config.session?.user;
   const sessionAttemptId = config.session?.attemptId;
   const sessionConfiguredId = config.session?.sessionId;
+  (0, import_react.useEffect)(() => {
+    const nextConfigured = config.session?.sessionId;
+    const prevConfigured = prevConfiguredSessionIdRef.current;
+    if (nextConfigured === prevConfigured) return;
+    prevConfiguredSessionIdRef.current = nextConfigured;
+    const cid = courseIdRef.current;
+    if (nextConfigured) {
+      const fromIds = /* @__PURE__ */ new Set();
+      if (prevConfigured) fromIds.add(prevConfigured);
+      const tabId = getTabSessionId(defaultStorage);
+      if (tabId) fromIds.add(tabId);
+      for (const fromId of fromIds) {
+        if (fromId !== nextConfigured) {
+          migrateCourseStartedMark(defaultStorage, fromId, nextConfigured, cid);
+        }
+      }
+      sessionIdRef.current = nextConfigured;
+    } else if (prevConfigured) {
+      const nextAuto = resolveSessionId(defaultStorage, void 0);
+      migrateCourseStartedMark(defaultStorage, prevConfigured, nextAuto, cid);
+      sessionIdRef.current = nextAuto;
+    }
+  }, [sessionConfiguredId, config.courseId]);
   const runtime = (0, import_react.useMemo)(
     () => ({
       config,
@@ -606,7 +687,7 @@ function useQuizState() {
 }
 
 // src/runtime/validateComponentId.ts
-var import_core4 = require("@lessonkit/core");
+var import_core5 = require("@lessonkit/core");
 var warnedPaths = /* @__PURE__ */ new Set();
 function isDevEnvironment2() {
   const g = globalThis;
@@ -616,7 +697,7 @@ function warnInvalidComponentId(id, path) {
   if (!isDevEnvironment2()) return;
   const key = `${path}:${String(id)}`;
   if (warnedPaths.has(key)) return;
-  const result = (0, import_core4.validateId)(id, path);
+  const result = (0, import_core5.validateId)(id, path);
   if (result.ok) return;
   warnedPaths.add(key);
   const detail = result.issues.map((i) => `${i.path}: ${i.message}`).join("; ");
@@ -694,6 +775,10 @@ function Quiz(props) {
   const [selected, setSelected] = (0, import_react3.useState)(null);
   const completedRef = (0, import_react3.useRef)(false);
   const questionId = (0, import_react3.useId)();
+  (0, import_react3.useEffect)(() => {
+    completedRef.current = false;
+    setSelected(null);
+  }, [props.checkId, props.answer, props.question]);
   return /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("section", { "aria-label": "Quiz", "data-lk-check-id": props.checkId, children: [
     /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("p", { id: questionId, children: props.question }),
     /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("fieldset", { "aria-labelledby": questionId, children: [
@@ -844,8 +929,196 @@ function useTheme() {
   }
   return ctx;
 }
+
+// src/blockCatalog.ts
+var blockCatalogVersion = 1;
+var BLOCK_CATALOG = [
+  {
+    type: "Course",
+    category: "container",
+    description: "Top-level course shell; wraps LessonkitProvider and emits course lifecycle telemetry.",
+    props: [
+      { name: "title", type: "string", required: true, description: "Course title shown in the h1." },
+      { name: "courseId", type: "CourseId", required: true, description: "Stable course identifier for telemetry and packaging." },
+      {
+        name: "config",
+        type: "Omit<LessonkitConfig, 'courseId'>",
+        required: false,
+        description: "Runtime config (tracking, xAPI, session, lxpack bridge). courseId is merged from props."
+      },
+      { name: "children", type: "ReactNode", required: true, description: "Lessons and course chrome." }
+    ],
+    requiredIds: ["courseId"],
+    a11y: {
+      element: "section",
+      ariaLabel: "title prop",
+      keyboard: "No block-specific keyboard behavior; focus flows to child content.",
+      notes: "Renders h1 with course title. Wrap with ThemeProvider at app root for theming."
+    },
+    theming: {
+      surface: "global-inherit",
+      stylingNotes: "Inherits --lk-* CSS variables from ThemeProvider on document or scoped host."
+    },
+    telemetry: {
+      emits: ["course_started", "course_completed"]
+    }
+  },
+  {
+    type: "Lesson",
+    category: "container",
+    description: "Lesson container; sets active lesson on mount and completes on unmount.",
+    props: [
+      { name: "title", type: "string", required: true, description: "Lesson title shown in the h2." },
+      { name: "lessonId", type: "LessonId", required: true, description: "Stable lesson identifier for telemetry and packaging." },
+      { name: "children", type: "ReactNode", required: true, description: "Scenario, Quiz, Reflection, and other blocks." }
+    ],
+    requiredIds: ["lessonId"],
+    parentConstraints: ["Course"],
+    a11y: {
+      element: "article",
+      ariaLabel: "title prop",
+      keyboard: "No block-specific keyboard behavior; focus flows to child content.",
+      notes: "Renders h2 with lesson title. Only one Lesson should be mounted as active at a time in typical SPA layouts."
+    },
+    theming: {
+      surface: "global-inherit",
+      stylingNotes: "Inherits --lk-* CSS variables from ThemeProvider."
+    },
+    telemetry: {
+      emits: ["lesson_started", "lesson_completed", "lesson_time_on_task"]
+    }
+  },
+  {
+    type: "Scenario",
+    category: "content",
+    description: "Scenario or narrative content region for branching stories and situational context.",
+    props: [
+      { name: "blockId", type: "BlockId", required: false, description: "Optional stable block id for interaction telemetry URNs." },
+      { name: "children", type: "ReactNode", required: true, description: "Scenario narrative and custom UI." }
+    ],
+    requiredIds: [],
+    optionalIds: ["blockId"],
+    parentConstraints: ["Lesson"],
+    a11y: {
+      element: "section",
+      ariaLabel: "Scenario",
+      keyboard: "No block-specific keyboard behavior; custom children may define their own.",
+      notes: "Use for situational framing. Pair with useTracking() for branching interactions."
+    },
+    theming: {
+      surface: "global-inherit",
+      dataAttributes: ["data-lk-block-id"],
+      stylingNotes: "Optional data-lk-block-id when blockId is set. Style via app CSS using --lk-* tokens."
+    },
+    telemetry: {
+      emits: [],
+      manualTracking: "useTracking().track('interaction', { kind, blockId, payload })"
+    }
+  },
+  {
+    type: "Reflection",
+    category: "content",
+    description: "Reflection prompt with a textarea for learner free-text responses.",
+    props: [
+      { name: "blockId", type: "BlockId", required: false, description: "Optional stable block id for interaction telemetry URNs." },
+      { name: "prompt", type: "string", required: false, description: "Reflection question or instruction." },
+      { name: "children", type: "ReactNode", required: false, description: "Optional content above the textarea." }
+    ],
+    requiredIds: [],
+    optionalIds: ["blockId"],
+    parentConstraints: ["Lesson"],
+    a11y: {
+      element: "section",
+      ariaLabel: "Reflection",
+      keyboard: "Textarea is keyboard-focusable; standard text entry.",
+      notes: "When prompt is set, textarea uses aria-labelledby; otherwise aria-label='Reflection response'."
+    },
+    theming: {
+      surface: "global-inherit",
+      dataAttributes: ["data-lk-block-id"],
+      stylingNotes: "Optional data-lk-block-id when blockId is set. Style textarea via app CSS."
+    },
+    telemetry: {
+      emits: [],
+      manualTracking: "useTracking().track('interaction', { kind, blockId, payload }) on submit or blur"
+    }
+  },
+  {
+    type: "Quiz",
+    aliases: ["KnowledgeCheck"],
+    category: "assessment",
+    description: "Single-question multiple-choice assessment with automatic answer and completion telemetry.",
+    props: [
+      { name: "checkId", type: "CheckId", required: true, description: "Stable check identifier for telemetry and LXPack assessments." },
+      { name: "question", type: "string", required: true, description: "Question text shown above choices." },
+      { name: "choices", type: "string[]", required: true, description: "Radio button choice labels." },
+      { name: "answer", type: "string", required: true, description: "Correct choice value (must match one choice)." }
+    ],
+    requiredIds: ["checkId"],
+    parentConstraints: ["Lesson"],
+    a11y: {
+      element: "section",
+      ariaLabel: "Quiz",
+      keyboard: "Radio group navigable with arrow keys; one choice per question.",
+      liveRegions: "role='status' aria-live='polite' for Correct / Try again feedback.",
+      notes: "Fieldset with visually hidden legend. KnowledgeCheck is an alias that renders Quiz with identical behavior."
+    },
+    theming: {
+      surface: "global-inherit",
+      dataAttributes: ["data-lk-check-id"],
+      stylingNotes: "data-lk-check-id set from checkId. Style labels and feedback via app CSS."
+    },
+    telemetry: {
+      emits: ["quiz_answered", "quiz_completed"],
+      requiresActiveLesson: true
+    }
+  },
+  {
+    type: "ProgressTracker",
+    category: "chrome",
+    description: "Displays count of completed lessons from runtime progress state.",
+    props: [],
+    requiredIds: [],
+    parentConstraints: ["Course"],
+    a11y: {
+      element: "aside",
+      ariaLabel: "Progress",
+      keyboard: "Presentational; no interactive elements.",
+      notes: "Shows 'Lessons completed: N' from progress.completedLessonIds."
+    },
+    theming: {
+      surface: "global-inherit",
+      stylingNotes: "Inherits --lk-* CSS variables; style via app CSS."
+    },
+    telemetry: {
+      emits: []
+    }
+  }
+];
+function buildBlockCatalog() {
+  return BLOCK_CATALOG.map((entry) => ({
+    ...entry,
+    props: entry.props.map((p) => ({ ...p })),
+    aliases: entry.aliases ? [...entry.aliases] : void 0,
+    optionalIds: entry.optionalIds ? [...entry.optionalIds] : void 0,
+    parentConstraints: entry.parentConstraints ? [...entry.parentConstraints] : void 0,
+    a11y: { ...entry.a11y },
+    theming: {
+      ...entry.theming,
+      dataAttributes: entry.theming.dataAttributes ? [...entry.theming.dataAttributes] : void 0
+    },
+    telemetry: {
+      ...entry.telemetry,
+      emits: [...entry.telemetry.emits]
+    }
+  }));
+}
+function getBlockCatalogEntry(type) {
+  return BLOCK_CATALOG.find((entry) => entry.type === type || entry.aliases?.includes(type));
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  BLOCK_CATALOG,
   Course,
   KnowledgeCheck,
   Lesson,
@@ -855,6 +1128,9 @@ function useTheme() {
   Reflection,
   Scenario,
   ThemeProvider,
+  blockCatalogVersion,
+  buildBlockCatalog,
+  getBlockCatalogEntry,
   useCompletion,
   useLessonkit,
   useProgress,

package/dist/index.d.cts

@@ -142,4 +142,42 @@ type ThemeContextValue = {
 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 };
+declare const blockCatalogVersion: 1;
+type BlockPropSpec = {
+    name: string;
+    type: string;
+    required: boolean;
+    description: string;
+};
+type BlockCatalogEntry = {
+    type: string;
+    aliases?: string[];
+    category: "container" | "content" | "assessment" | "chrome";
+    description: string;
+    props: BlockPropSpec[];
+    requiredIds: string[];
+    optionalIds?: string[];
+    parentConstraints?: string[];
+    a11y: {
+        element: string;
+        ariaLabel: string;
+        keyboard: string;
+        liveRegions?: string;
+        notes: string;
+    };
+    theming: {
+        surface: "global-inherit";
+        dataAttributes?: string[];
+        stylingNotes: string;
+    };
+    telemetry: {
+        emits: string[];
+        requiresActiveLesson?: boolean;
+        manualTracking?: string;
+    };
+};
+declare const BLOCK_CATALOG: BlockCatalogEntry[];
+declare function buildBlockCatalog(): BlockCatalogEntry[];
+declare function getBlockCatalogEntry(type: string): BlockCatalogEntry | undefined;
+
+export { BLOCK_CATALOG, type BlockCatalogEntry, type BlockPropSpec, Course, KnowledgeCheck, Lesson, type LessonkitConfig, LessonkitProvider, type LessonkitRuntime, ProgressTracker, Quiz, Reflection, Scenario, type ThemeContextValue, type ThemeMode, ThemeProvider, type ThemeProviderProps, type ThemeResolvedMode, blockCatalogVersion, buildBlockCatalog, getBlockCatalogEntry, useCompletion, useLessonkit, useProgress, useQuizState, useTheme, useTracking };

package/dist/index.d.ts

@@ -142,4 +142,42 @@ type ThemeContextValue = {
 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 };
+declare const blockCatalogVersion: 1;
+type BlockPropSpec = {
+    name: string;
+    type: string;
+    required: boolean;
+    description: string;
+};
+type BlockCatalogEntry = {
+    type: string;
+    aliases?: string[];
+    category: "container" | "content" | "assessment" | "chrome";
+    description: string;
+    props: BlockPropSpec[];
+    requiredIds: string[];
+    optionalIds?: string[];
+    parentConstraints?: string[];
+    a11y: {
+        element: string;
+        ariaLabel: string;
+        keyboard: string;
+        liveRegions?: string;
+        notes: string;
+    };
+    theming: {
+        surface: "global-inherit";
+        dataAttributes?: string[];
+        stylingNotes: string;
+    };
+    telemetry: {
+        emits: string[];
+        requiresActiveLesson?: boolean;
+        manualTracking?: string;
+    };
+};
+declare const BLOCK_CATALOG: BlockCatalogEntry[];
+declare function buildBlockCatalog(): BlockCatalogEntry[];
+declare function getBlockCatalogEntry(type: string): BlockCatalogEntry | undefined;
+
+export { BLOCK_CATALOG, type BlockCatalogEntry, type BlockPropSpec, Course, KnowledgeCheck, Lesson, type LessonkitConfig, LessonkitProvider, type LessonkitRuntime, ProgressTracker, Quiz, Reflection, Scenario, type ThemeContextValue, type ThemeMode, ThemeProvider, type ThemeProviderProps, type ThemeResolvedMode, blockCatalogVersion, buildBlockCatalog, getBlockCatalogEntry, useCompletion, useLessonkit, useProgress, useQuizState, useTheme, useTracking };