@lessonkit/core 1.0.2 → 1.2.0

package/dist/index.js

@@ -102,6 +102,122 @@ function buildLessonkitUrn(parts) {
   return urn;
 }
 
+// src/compound.ts
+var COMPOUND_RESUME_SCHEMA_VERSION = 1;
+function createCompoundResumeState(input = {}) {
+  const childStates = {};
+  if (input.childStates) {
+    for (const [key, value] of Object.entries(input.childStates)) {
+      childStates[key] = value;
+    }
+  }
+  return {
+    schemaVersion: COMPOUND_RESUME_SCHEMA_VERSION,
+    activePageIndex: input.activePageIndex ?? 0,
+    ...input.activeChapterIndex !== void 0 ? { activeChapterIndex: input.activeChapterIndex } : {},
+    childStates
+  };
+}
+function clampCompoundPageIndex(index, pageCount) {
+  if (pageCount < 1) return 0;
+  return Math.min(Math.max(0, Math.floor(index)), pageCount - 1);
+}
+function parseCompoundResumeState(raw) {
+  if (!raw || typeof raw !== "object") return null;
+  const obj = raw;
+  if (obj.schemaVersion !== COMPOUND_RESUME_SCHEMA_VERSION) return null;
+  if (typeof obj.activePageIndex !== "number" || !Number.isFinite(obj.activePageIndex)) return null;
+  const childStates = {};
+  if (obj.childStates && typeof obj.childStates === "object" && !Array.isArray(obj.childStates)) {
+    for (const [key, value] of Object.entries(obj.childStates)) {
+      if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+        childStates[key] = value;
+      }
+    }
+  }
+  const activeChapterIndex = typeof obj.activeChapterIndex === "number" && Number.isFinite(obj.activeChapterIndex) ? obj.activeChapterIndex : void 0;
+  return {
+    schemaVersion: COMPOUND_RESUME_SCHEMA_VERSION,
+    activePageIndex: Math.max(0, Math.floor(obj.activePageIndex)),
+    ...activeChapterIndex !== void 0 ? { activeChapterIndex: Math.max(0, Math.floor(activeChapterIndex)) } : {},
+    childStates
+  };
+}
+
+// src/compoundState.ts
+var COMPOUND_STATE_PREFIX = "lessonkit:compound:";
+function compoundStateStorageKey(courseId, compoundId) {
+  return `${COMPOUND_STATE_PREFIX}${courseId}:${compoundId}`;
+}
+function loadCompoundState(storage, courseId, compoundId) {
+  const raw = storage.getItem(compoundStateStorageKey(courseId, compoundId));
+  if (!raw) return null;
+  try {
+    return parseCompoundResumeState(JSON.parse(raw));
+  } catch {
+    return null;
+  }
+}
+function saveCompoundState(storage, courseId, compoundId, state) {
+  storage.setItem(compoundStateStorageKey(courseId, compoundId), JSON.stringify(state));
+}
+function clearCompoundState(storage, courseId, compoundId) {
+  storage.removeItem?.(compoundStateStorageKey(courseId, compoundId));
+}
+
+// src/compoundAllowlists.ts
+var PAGE_ALLOWED_CHILD_TYPES = [
+  "Text",
+  "Heading",
+  "Image",
+  "Scenario",
+  "Reflection",
+  "Quiz",
+  "KnowledgeCheck",
+  "TrueFalse",
+  "FillInTheBlanks",
+  "DragAndDrop",
+  "DragTheWords",
+  "MarkTheWords",
+  "Accordion",
+  "DialogCards",
+  "Flashcards",
+  "ImageHotspots",
+  "FindHotspot",
+  "FindMultipleHotspots",
+  "ImageSlider",
+  "ProgressTracker"
+];
+var INTERACTIVE_BOOK_ALLOWED_CHILD_TYPES = ["Page"];
+var ASSESSMENT_SEQUENCE_ALLOWED_CHILD_TYPES = [
+  "TrueFalse",
+  "FillInTheBlanks",
+  "DragAndDrop",
+  "DragTheWords",
+  "MarkTheWords",
+  "Quiz",
+  "KnowledgeCheck",
+  "FindHotspot",
+  "FindMultipleHotspots"
+];
+var ALLOWLISTS = {
+  Page: PAGE_ALLOWED_CHILD_TYPES,
+  InteractiveBook: INTERACTIVE_BOOK_ALLOWED_CHILD_TYPES,
+  AssessmentSequence: ASSESSMENT_SEQUENCE_ALLOWED_CHILD_TYPES
+};
+var COMPOUND_MAX_NESTING_DEPTH = {
+  Page: 1,
+  InteractiveBook: 2,
+  AssessmentSequence: 1
+};
+function getAllowedChildTypes(parent) {
+  return ALLOWLISTS[parent];
+}
+function isChildTypeAllowed(parent, childType) {
+  return ALLOWLISTS[parent].includes(childType);
+}
+var ACCORDION_FORBIDDEN_CHILD_TYPES = ["Accordion"];
+
 // src/telemetryCatalog.ts
 var telemetryCatalogVersion = 1;
 var TELEMETRY_EVENT_CATALOG = [
@@ -174,35 +290,125 @@ function buildTelemetryCatalog() {
   return TELEMETRY_EVENT_CATALOG.map((entry) => ({ ...entry }));
 }
 
-// src/trackingClient.ts
+// src/telemetryCatalogV2.ts
+var telemetryCatalogV2Version = 2;
+var TELEMETRY_EVENT_CATALOG_V2 = [
+  {
+    name: "assessment_answered",
+    description: "Learner submitted an assessment interaction answer",
+    requiredFields: ["courseId", "lessonId", "sessionId", "timestamp"],
+    dataFields: ["checkId", "interactionType", "question", "response", "correct"],
+    xapiVerb: "http://adlnet.gov/expapi/verbs/answered",
+    urnPattern: "urn:lessonkit:course:{courseId}:lesson:{lessonId}:check:{checkId}"
+  },
+  {
+    name: "assessment_completed",
+    description: "Assessment interaction completed (passing criteria met)",
+    requiredFields: ["courseId", "lessonId", "sessionId", "timestamp"],
+    dataFields: ["checkId", "interactionType", "score", "maxScore", "passingScore"],
+    xapiVerb: "http://adlnet.gov/expapi/verbs/completed",
+    urnPattern: "urn:lessonkit:course:{courseId}:lesson:{lessonId}:check:{checkId}"
+  }
+];
+function buildTelemetryCatalogV2() {
+  return TELEMETRY_EVENT_CATALOG_V2.map((entry) => ({ ...entry }));
+}
+
+// src/telemetryCatalogV3.ts
+var telemetryCatalogV3Version = 3;
+var TELEMETRY_EVENT_CATALOG_V3 = [
+  {
+    name: "book_page_viewed",
+    description: "Learner viewed a page/chapter in an Interactive Book",
+    requiredFields: ["courseId", "lessonId", "sessionId", "timestamp"],
+    dataFields: ["blockId", "pageIndex", "pageTitle"],
+    xapiVerb: "http://adlnet.gov/expapi/verbs/experienced",
+    urnPattern: "urn:lessonkit:course:{courseId}:lesson:{lessonId}:block:{blockId}"
+  },
+  {
+    name: "compound_page_viewed",
+    description: "Learner activated a page inside a compound container",
+    requiredFields: ["courseId", "lessonId", "sessionId", "timestamp"],
+    dataFields: ["blockId", "pageIndex", "parentType"],
+    xapiVerb: "http://adlnet.gov/expapi/verbs/experienced",
+    urnPattern: "urn:lessonkit:course:{courseId}:lesson:{lessonId}:block:{blockId}"
+  },
+  {
+    name: "hotspot_opened",
+    description: "Learner opened an image hotspot popover",
+    requiredFields: ["courseId", "sessionId", "timestamp"],
+    dataFields: ["blockId", "hotspotId"],
+    xapiVerb: "http://adlnet.gov/expapi/verbs/experienced",
+    urnPattern: "urn:lessonkit:course:{courseId}:lesson:{lessonId}:block:{blockId}"
+  },
+  {
+    name: "accordion_section_toggled",
+    description: "Learner expanded or collapsed an accordion section",
+    requiredFields: ["courseId", "sessionId", "timestamp"],
+    dataFields: ["blockId", "sectionId", "expanded"],
+    xapiVerb: "http://adlnet.gov/expapi/verbs/experienced",
+    urnPattern: "urn:lessonkit:course:{courseId}:lesson:{lessonId}:block:{blockId}"
+  },
+  {
+    name: "flashcard_flipped",
+    description: "Learner flipped a flashcard",
+    requiredFields: ["courseId", "sessionId", "timestamp"],
+    dataFields: ["blockId", "cardIndex", "face"],
+    xapiVerb: "http://adlnet.gov/expapi/verbs/experienced",
+    urnPattern: "urn:lessonkit:course:{courseId}:lesson:{lessonId}:block:{blockId}"
+  },
+  {
+    name: "image_slider_changed",
+    description: "Learner changed the active slide in an image slider",
+    requiredFields: ["courseId", "sessionId", "timestamp"],
+    dataFields: ["blockId", "slideIndex"],
+    xapiVerb: "http://adlnet.gov/expapi/verbs/experienced",
+    urnPattern: "urn:lessonkit:course:{courseId}:lesson:{lessonId}:block:{blockId}"
+  }
+];
+function buildTelemetryCatalogV3() {
+  return TELEMETRY_EVENT_CATALOG_V3.map((entry) => ({ ...entry }));
+}
+
+// src/internal/env.ts
 function isDevEnvironment() {
   const g = globalThis;
   return typeof g.process !== "undefined" && g.process.env?.NODE_ENV !== "production";
 }
+function warnDev(message, err) {
+  if (!isDevEnvironment()) return;
+  console.warn(message, err instanceof Error ? err.message : err);
+}
+
+// src/internal/sinkInvoke.ts
 function invokeTrackingSink(sink, event) {
   let result;
   try {
     result = sink(event);
   } catch (err) {
-    if (isDevEnvironment()) {
-      console.warn(
-        "[lessonkit] tracking sink failed:",
-        err instanceof Error ? err.message : err
-      );
-    }
+    warnDev("[lessonkit] tracking sink failed:", err);
     throw err;
   }
   if (result != null && typeof result.catch === "function") {
-    void result.catch((err) => {
-      if (isDevEnvironment()) {
-        console.warn(
-          "[lessonkit] tracking sink failed:",
-          err instanceof Error ? err.message : err
-        );
-      }
-    });
+    void result.catch((err) => warnDev("[lessonkit] tracking sink failed:", err));
   }
 }
+function invokePipelineSink(sinkId, emit) {
+  let result;
+  try {
+    result = emit();
+  } catch (err) {
+    warnDev(`[lessonkit] telemetry sink "${sinkId}" failed:`, err);
+    return;
+  }
+  if (result != null && typeof result.catch === "function") {
+    void result.catch(
+      (err) => warnDev(`[lessonkit] telemetry sink "${sinkId}" failed:`, err)
+    );
+  }
+}
+
+// src/trackingClient.ts
 function createTrackingClient(opts) {
   const sink = opts?.sink;
   const batchSink = opts?.batchSink;
@@ -320,81 +526,234 @@ function nowIso() {
   return (/* @__PURE__ */ new Date()).toISOString();
 }
 
-// src/telemetryBuilder.ts
-var warnedMissingQuizLesson = false;
-function isDevEnvironment2() {
-  const g = globalThis;
-  return typeof g.process !== "undefined" && g.process.env?.NODE_ENV !== "production";
-}
-function resetTelemetryBuilderWarningsForTests() {
-  warnedMissingQuizLesson = false;
-}
+// src/telemetry/eventRegistry.ts
 function resolveLessonId(opts, eventName) {
   const lessonId = opts.lessonId ?? opts.data?.lessonId;
   if (!lessonId) throw new Error(`${eventName} requires lessonId`);
   return lessonId;
 }
-function buildTelemetryEvent(opts) {
-  const base = {
-    timestamp: opts.timestamp ?? nowIso(),
-    courseId: opts.courseId,
-    sessionId: opts.sessionId,
-    attemptId: opts.attemptId,
-    user: opts.user
-  };
-  switch (opts.name) {
-    case "course_started":
-      return { name: "course_started", ...base };
-    case "course_completed":
-      return { name: "course_completed", ...base };
-    case "lesson_started": {
+function withLessonScopedData(name, base, lessonId, data) {
+  return { name, ...base, lessonId, data: { ...data, lessonId } };
+}
+var TELEMETRY_EVENT_REGISTRY = {
+  course_started: {
+    build: (_opts, base) => ({ name: "course_started", ...base })
+  },
+  course_completed: {
+    build: (_opts, base) => ({ name: "course_completed", ...base })
+  },
+  lesson_started: {
+    requiresLessonId: true,
+    build: (opts, base) => {
+      if (opts.name !== "lesson_started") throw new Error("unexpected event");
       const lessonId = resolveLessonId(opts, "lesson_started");
+      return withLessonScopedData("lesson_started", base, lessonId, opts.data);
+    }
+  },
+  lesson_completed: {
+    requiresLessonId: true,
+    build: (opts, base) => {
+      if (opts.name !== "lesson_completed") throw new Error("unexpected event");
+      const lessonId = resolveLessonId(opts, opts.name);
+      return withLessonScopedData(opts.name, base, lessonId, opts.data);
+    }
+  },
+  lesson_time_on_task: {
+    requiresLessonId: true,
+    build: (opts, base) => {
+      if (opts.name !== "lesson_time_on_task") throw new Error("unexpected event");
+      const lessonId = resolveLessonId(opts, opts.name);
+      return withLessonScopedData(opts.name, base, lessonId, opts.data);
+    }
+  },
+  quiz_answered: {
+    requiresLessonId: true,
+    tryBuildMissingLessonWarning: "quiz",
+    build: (opts, base) => {
+      if (opts.name !== "quiz_answered") throw new Error("unexpected event");
+      const lessonId = opts.lessonId;
+      if (!lessonId) throw new Error("quiz_answered requires active lessonId");
       return {
-        name: "lesson_started",
+        name: "quiz_answered",
         ...base,
         lessonId,
-        data: { ...opts.data, lessonId }
+        data: opts.data
       };
     }
-    case "lesson_completed":
-    case "lesson_time_on_task": {
-      const lessonId = resolveLessonId(opts, opts.name);
+  },
+  quiz_completed: {
+    requiresLessonId: true,
+    tryBuildMissingLessonWarning: "quiz",
+    build: (opts, base) => {
+      if (opts.name !== "quiz_completed") throw new Error("unexpected event");
+      const lessonId = opts.lessonId;
+      if (!lessonId) throw new Error("quiz_completed requires active lessonId");
       return {
-        name: opts.name,
+        name: "quiz_completed",
         ...base,
         lessonId,
-        data: { ...opts.data, lessonId }
+        data: opts.data
       };
     }
-    case "quiz_answered": {
+  },
+  assessment_answered: {
+    requiresLessonId: true,
+    tryBuildMissingLessonWarning: "assessment",
+    build: (opts, base) => {
+      if (opts.name !== "assessment_answered") throw new Error("unexpected event");
       const lessonId = opts.lessonId;
-      if (!lessonId) throw new Error("quiz_answered requires active lessonId");
-      return { name: "quiz_answered", ...base, lessonId, data: opts.data };
+      if (!lessonId) throw new Error("assessment_answered requires active lessonId");
+      return {
+        name: "assessment_answered",
+        ...base,
+        lessonId,
+        data: opts.data
+      };
     }
-    case "quiz_completed": {
+  },
+  assessment_completed: {
+    requiresLessonId: true,
+    tryBuildMissingLessonWarning: "assessment",
+    build: (opts, base) => {
+      if (opts.name !== "assessment_completed") throw new Error("unexpected event");
       const lessonId = opts.lessonId;
-      if (!lessonId) throw new Error("quiz_completed requires active lessonId");
-      return { name: "quiz_completed", ...base, lessonId, data: opts.data };
+      if (!lessonId) throw new Error("assessment_completed requires active lessonId");
+      return {
+        name: "assessment_completed",
+        ...base,
+        lessonId,
+        data: opts.data
+      };
     }
-    case "interaction":
+  },
+  interaction: {
+    build: (opts, base) => {
+      if (opts.name !== "interaction") throw new Error("unexpected event");
       return {
         name: "interaction",
         ...base,
         lessonId: opts.lessonId,
         data: opts.data
       };
-    default:
-      return assertNever(opts);
+    }
+  },
+  book_page_viewed: {
+    requiresLessonId: true,
+    build: (opts, base) => {
+      if (opts.name !== "book_page_viewed") throw new Error("unexpected event");
+      const lessonId = opts.lessonId;
+      if (!lessonId) throw new Error("book_page_viewed requires active lessonId");
+      return {
+        name: "book_page_viewed",
+        ...base,
+        lessonId,
+        data: opts.data
+      };
+    }
+  },
+  compound_page_viewed: {
+    requiresLessonId: true,
+    build: (opts, base) => {
+      if (opts.name !== "compound_page_viewed") throw new Error("unexpected event");
+      const lessonId = opts.lessonId;
+      if (!lessonId) throw new Error("compound_page_viewed requires active lessonId");
+      return {
+        name: "compound_page_viewed",
+        ...base,
+        lessonId,
+        data: opts.data
+      };
+    }
+  },
+  hotspot_opened: {
+    build: (opts, base) => {
+      if (opts.name !== "hotspot_opened") throw new Error("unexpected event");
+      return {
+        name: "hotspot_opened",
+        ...base,
+        lessonId: opts.lessonId,
+        data: opts.data
+      };
+    }
+  },
+  accordion_section_toggled: {
+    build: (opts, base) => {
+      if (opts.name !== "accordion_section_toggled") throw new Error("unexpected event");
+      return {
+        name: "accordion_section_toggled",
+        ...base,
+        lessonId: opts.lessonId,
+        data: opts.data
+      };
+    }
+  },
+  flashcard_flipped: {
+    build: (opts, base) => {
+      if (opts.name !== "flashcard_flipped") throw new Error("unexpected event");
+      return {
+        name: "flashcard_flipped",
+        ...base,
+        lessonId: opts.lessonId,
+        data: opts.data
+      };
+    }
+  },
+  image_slider_changed: {
+    build: (opts, base) => {
+      if (opts.name !== "image_slider_changed") throw new Error("unexpected event");
+      return {
+        name: "image_slider_changed",
+        ...base,
+        lessonId: opts.lessonId,
+        data: opts.data
+      };
+    }
   }
+};
+function buildTelemetryEventFromRegistry(opts) {
+  const entry = TELEMETRY_EVENT_REGISTRY[opts.name];
+  if (!entry) {
+    throw new Error("Unexpected value");
+  }
+  const base = {
+    timestamp: opts.timestamp ?? nowIso(),
+    courseId: opts.courseId,
+    sessionId: opts.sessionId,
+    attemptId: opts.attemptId,
+    user: opts.user
+  };
+  return entry.build(opts, base);
+}
+function getTelemetryEventRegistryEntry(name) {
+  return TELEMETRY_EVENT_REGISTRY[name];
+}
+
+// src/telemetryBuilder.ts
+var warnedMissingQuizLesson = false;
+var warnedMissingAssessmentLesson = false;
+function resetTelemetryBuilderWarningsForTests() {
+  warnedMissingQuizLesson = false;
+  warnedMissingAssessmentLesson = false;
+}
+function buildTelemetryEvent(opts) {
+  return buildTelemetryEventFromRegistry(opts);
 }
 function tryBuildTelemetryEvent(opts) {
-  const isQuiz = opts.name === "quiz_answered" || opts.name === "quiz_completed";
-  if (isQuiz && !opts.lessonId) {
-    if (isDevEnvironment2() && !warnedMissingQuizLesson) {
-      warnedMissingQuizLesson = true;
-      console.warn(
-        `[lessonkit] ${opts.name} skipped: wrap <Quiz> in <Lesson> so an active lessonId is available`
-      );
+  const entry = getTelemetryEventRegistryEntry(opts.name);
+  if (entry.requiresLessonId && !opts.lessonId && entry.tryBuildMissingLessonWarning) {
+    if (isDevEnvironment()) {
+      if (entry.tryBuildMissingLessonWarning === "quiz" && !warnedMissingQuizLesson) {
+        warnedMissingQuizLesson = true;
+        console.warn(
+          `[lessonkit] ${opts.name} skipped: wrap <Quiz> in <Lesson> so an active lessonId is available`
+        );
+      }
+      if (entry.tryBuildMissingLessonWarning === "assessment" && !warnedMissingAssessmentLesson) {
+        warnedMissingAssessmentLesson = true;
+        console.warn(
+          `[lessonkit] ${opts.name} skipped: wrap assessment blocks in <Lesson> so an active lessonId is available`
+        );
+      }
     }
     return null;
   }
@@ -402,29 +761,8 @@ function tryBuildTelemetryEvent(opts) {
 }
 
 // src/telemetryPipeline.ts
-function isDevEnvironment3() {
-  const g = globalThis;
-  return typeof g.process !== "undefined" && g.process.env?.NODE_ENV !== "production";
-}
-function warnSinkFailure(sinkId, err) {
-  if (isDevEnvironment3()) {
-    console.warn(
-      `[lessonkit] telemetry sink "${sinkId}" failed:`,
-      err instanceof Error ? err.message : err
-    );
-  }
-}
 function invokeSink(sink, event, emitCtx) {
-  let result;
-  try {
-    result = sink.emit(event, emitCtx);
-  } catch (err) {
-    warnSinkFailure(sink.id, err);
-    return;
-  }
-  if (result != null && typeof result.catch === "function") {
-    void result.catch((err) => warnSinkFailure(sink.id, err));
-  }
+  invokePipelineSink(sink.id, () => sink.emit(event, emitCtx));
 }
 function createTelemetryPipeline(sinks) {
   const list = [...sinks];
@@ -700,101 +1038,13 @@ function completeCourseWithTelemetry(opts) {
   return true;
 }
 
-// src/runtime/createLessonkitRuntime.ts
-function createLessonkitRuntime(config, ports = {}) {
-  const storage = ports.storage ?? createSessionStoragePort();
-  const clock = ports.clock ?? createDefaultClock();
-  const configSnapshot = { ...config };
-  let sessionId = resolveSessionId(storage, configSnapshot.session?.sessionId);
-  let attemptId = configSnapshot.session?.attemptId;
-  let user = configSnapshot.session?.user;
-  let courseId = configSnapshot.courseId;
-  let progress = createProgressController();
-  const getSession = () => ({ sessionId, attemptId, user });
-  const syncSessionFromConfig = (next) => {
-    sessionId = resolveSessionId(storage, next.session?.sessionId);
-    attemptId = next.session?.attemptId;
-    user = next.session?.user;
-    courseId = next.courseId;
-  };
-  syncSessionFromConfig(configSnapshot);
-  const track = (name, data, emit, lessonId) => {
-    const event = tryBuildTelemetryEvent({
-      name,
-      courseId,
-      lessonId: lessonId ?? progress.getState().activeLessonId,
-      sessionId,
-      attemptId,
-      user,
-      data
-    });
-    if (!event) return;
-    emit(event);
-  };
-  const emitLessonCompleted = (lessonId, durationMs, emitFn) => {
-    emitFn("lesson_completed", { lessonId, durationMs }, lessonId);
-    if (durationMs !== void 0) {
-      emitFn("lesson_time_on_task", { lessonId, durationMs }, lessonId);
-    }
-  };
+// src/plugins/context.ts
+function buildPluginContext(opts) {
   return {
-    get config() {
-      return configSnapshot;
-    },
-    get progress() {
-      return progress;
-    },
-    getProgressState: () => progress.getState(),
-    getSession,
-    updateConfig(next) {
-      if (next.courseId !== void 0) configSnapshot.courseId = next.courseId;
-      if (next.runtimeVersion !== void 0) configSnapshot.runtimeVersion = next.runtimeVersion;
-      if (next.plugins !== void 0) configSnapshot.plugins = next.plugins;
-      if (next.session !== void 0) {
-        configSnapshot.session = { ...configSnapshot.session, ...next.session };
-      }
-      syncSessionFromConfig(configSnapshot);
-    },
-    setActiveLesson(lessonId, emitFn) {
-      const current = progress.getState();
-      if (current.activeLessonId === lessonId) return;
-      if (current.completedLessonIds.has(lessonId)) {
-        progress.setActiveLesson(lessonId, clock.nowMs());
-        return;
-      }
-      const previous = current.activeLessonId;
-      if (previous && previous !== lessonId) {
-        const completed = progress.completeLesson(previous, clock.nowMs());
-        if (completed.didComplete) {
-          emitLessonCompleted(previous, completed.durationMs, emitFn);
-        }
-      }
-      progress.setActiveLesson(lessonId, clock.nowMs());
-      emitFn("lesson_started", { lessonId }, lessonId);
-    },
-    completeLesson(lessonId, emitFn) {
-      const result = progress.completeLesson(lessonId, clock.nowMs());
-      if (!result.didComplete) return;
-      emitLessonCompleted(lessonId, result.durationMs, emitFn);
-    },
-    completeCourse(emitFn) {
-      const current = progress.getState();
-      if (current.activeLessonId) {
-        const lessonResult = progress.completeLesson(current.activeLessonId, clock.nowMs());
-        if (lessonResult.didComplete) {
-          emitLessonCompleted(current.activeLessonId, lessonResult.durationMs, emitFn);
-        }
-      }
-      const result = progress.completeCourse();
-      if (!result.didComplete) return;
-      emitFn("course_completed");
-    },
-    track,
-    resetForCourseChange(nextCourseId) {
-      configSnapshot.courseId = nextCourseId;
-      courseId = nextCourseId;
-      progress = createProgressController();
-    }
+    courseId: opts.courseId,
+    sessionId: opts.sessionId,
+    attemptId: opts.attemptId,
+    user: opts.user
   };
 }
 
@@ -885,6 +1135,161 @@ function createPluginRegistry(plugins = []) {
   };
 }
 
+// src/runtime/createLessonkitRuntime.ts
+function resolvePluginHost(plugins) {
+  if (!plugins) return null;
+  if (typeof plugins === "object" && "runTelemetry" in plugins) return plugins;
+  if (Array.isArray(plugins) && plugins.length > 0) return createPluginRegistry(plugins);
+  return null;
+}
+function warnRuntimeV1Deprecated() {
+  const g = globalThis;
+  if (typeof g.process !== "undefined" && g.process.env?.NODE_ENV === "production") return;
+  console.warn(
+    '[lessonkit] runtimeVersion "v1" is deprecated; use "v2" (default). v1 will be removed in LessonKit 2.0.'
+  );
+}
+function createLessonkitRuntime(config, ports = {}) {
+  if (config.runtimeVersion === "v1") warnRuntimeV1Deprecated();
+  const storage = ports.storage ?? createSessionStoragePort();
+  const clock = ports.clock ?? createDefaultClock();
+  const configSnapshot = { ...config };
+  let sessionId = resolveSessionId(storage, configSnapshot.session?.sessionId);
+  let attemptId = configSnapshot.session?.attemptId;
+  let user = configSnapshot.session?.user;
+  let courseId = configSnapshot.courseId;
+  let progress = createProgressController();
+  let pluginHost = resolvePluginHost(configSnapshot.plugins);
+  const getPluginCtx = () => buildPluginContext({
+    courseId,
+    sessionId,
+    attemptId,
+    user
+  });
+  const getSession = () => ({ sessionId, attemptId, user });
+  const syncSessionFromConfig = (next) => {
+    sessionId = resolveSessionId(storage, next.session?.sessionId);
+    attemptId = next.session?.attemptId;
+    user = next.session?.user;
+    courseId = next.courseId;
+  };
+  const applyPluginsToEvent = (event) => {
+    if (!pluginHost) return event;
+    return pluginHost.runTelemetry(event, getPluginCtx());
+  };
+  const buildAndApply = (name, data, lessonId) => {
+    const event = tryBuildTelemetryEvent({
+      name,
+      courseId,
+      lessonId: lessonId ?? progress.getState().activeLessonId,
+      sessionId,
+      attemptId,
+      user,
+      data
+    });
+    if (!event) return null;
+    return applyPluginsToEvent(event);
+  };
+  const wrapEmitFn = (emitFn) => {
+    return (name, data, lessonId) => {
+      const event = buildAndApply(name, data, lessonId);
+      if (event === null) return;
+      const eventLessonId = "lessonId" in event ? event.lessonId : lessonId;
+      const eventData = "data" in event ? event.data : data;
+      emitFn(event.name, eventData, eventLessonId);
+    };
+  };
+  syncSessionFromConfig(configSnapshot);
+  const track = (name, data, emit, lessonId) => {
+    const event = buildAndApply(name, data, lessonId);
+    if (!event) return;
+    emit(event);
+  };
+  const emitLessonCompletedEvents = (lessonId, durationMs, emitFn) => {
+    const wrapped = wrapEmitFn(emitFn);
+    wrapped("lesson_completed", { lessonId, durationMs }, lessonId);
+    if (durationMs !== void 0) {
+      wrapped("lesson_time_on_task", { lessonId, durationMs }, lessonId);
+    }
+  };
+  return {
+    get config() {
+      return configSnapshot;
+    },
+    get progress() {
+      return progress;
+    },
+    get pluginHost() {
+      return pluginHost;
+    },
+    getProgressState: () => progress.getState(),
+    getSession,
+    updateConfig(next) {
+      if (next.plugins !== void 0 && next.plugins !== pluginHost) {
+        pluginHost?.disposeAll();
+        configSnapshot.plugins = next.plugins;
+        pluginHost = resolvePluginHost(configSnapshot.plugins);
+      }
+      if (next.courseId !== void 0) configSnapshot.courseId = next.courseId;
+      if (next.runtimeVersion !== void 0) {
+        if (next.runtimeVersion === "v1") warnRuntimeV1Deprecated();
+        configSnapshot.runtimeVersion = next.runtimeVersion;
+      }
+      if (next.session !== void 0) {
+        configSnapshot.session = { ...configSnapshot.session, ...next.session };
+      }
+      syncSessionFromConfig(configSnapshot);
+    },
+    setActiveLesson(lessonId, emitFn) {
+      const wrapped = wrapEmitFn(emitFn);
+      const current = progress.getState();
+      if (current.activeLessonId === lessonId) return;
+      if (current.completedLessonIds.has(lessonId)) {
+        progress.setActiveLesson(lessonId, clock.nowMs());
+        return;
+      }
+      const previous = current.activeLessonId;
+      if (previous && previous !== lessonId) {
+        const completed = progress.completeLesson(previous, clock.nowMs());
+        if (completed.didComplete) {
+          emitLessonCompletedEvents(previous, completed.durationMs, wrapped);
+        }
+      }
+      progress.setActiveLesson(lessonId, clock.nowMs());
+      wrapped("lesson_started", { lessonId }, lessonId);
+    },
+    completeLesson(lessonId, emitFn) {
+      completeLessonWithTelemetry({
+        progress,
+        lessonId,
+        nowMs: clock.nowMs(),
+        emitLessonCompleted: (id, durationMs) => emitLessonCompletedEvents(id, durationMs, wrapEmitFn(emitFn))
+      });
+    },
+    completeCourse(emitFn) {
+      completeCourseWithTelemetry({
+        progress,
+        nowMs: clock.nowMs(),
+        emitLessonCompleted: (id, durationMs) => emitLessonCompletedEvents(id, durationMs, wrapEmitFn(emitFn)),
+        emitCourseCompleted: () => wrapEmitFn(emitFn)("course_completed")
+      });
+    },
+    track,
+    scoreAssessment(input, _lessonId) {
+      if (!pluginHost) return null;
+      return pluginHost.scoreAssessment(input, getPluginCtx());
+    },
+    resetForCourseChange(nextCourseId) {
+      configSnapshot.courseId = nextCourseId;
+      courseId = nextCourseId;
+      progress = createProgressController();
+    },
+    dispose() {
+      pluginHost?.disposeAll();
+    }
+  };
+}
+
 // src/plugins/define.ts
 function defineTelemetryPlugin(plugin) {
   return plugin;
@@ -896,18 +1301,33 @@ function defineLifecyclePlugin(plugin) {
   return plugin;
 }
 export {
+  ACCORDION_FORBIDDEN_CHILD_TYPES,
+  ASSESSMENT_SEQUENCE_ALLOWED_CHILD_TYPES,
+  COMPOUND_MAX_NESTING_DEPTH,
+  COMPOUND_RESUME_SCHEMA_VERSION,
   ID_MAX_LENGTH,
   ID_PATTERN,
+  INTERACTIVE_BOOK_ALLOWED_CHILD_TYPES,
+  PAGE_ALLOWED_CHILD_TYPES,
   SESSION_STORAGE_KEY,
   TELEMETRY_EVENT_CATALOG,
+  TELEMETRY_EVENT_CATALOG_V2,
+  TELEMETRY_EVENT_CATALOG_V3,
   assertNever,
   assertValidId,
   buildCourseStartedTelemetryEvent,
   buildLessonkitUrn,
+  buildPluginContext,
   buildTelemetryCatalog,
+  buildTelemetryCatalogV2,
+  buildTelemetryCatalogV3,
   buildTelemetryEvent,
+  clampCompoundPageIndex,
+  clearCompoundState,
   completeCourseWithTelemetry,
   completeLessonWithTelemetry,
+  compoundStateStorageKey,
+  createCompoundResumeState,
   createDefaultClock,
   createGlobalTimer,
   createLessonkitRuntime,
@@ -923,10 +1343,13 @@ export {
   defineLifecyclePlugin,
   defineTelemetryPlugin,
   deriveId,
+  getAllowedChildTypes,
   getTabSessionId,
   hasCourseStarted,
   hasCourseStartedEmittedToTracking,
   hasCourseStartedPipelineDelivered,
+  isChildTypeAllowed,
+  loadCompoundState,
   markCourseStarted,
   markCourseStartedEmittedToTracking,
   markCourseStartedPipelineDelivered,
@@ -934,12 +1357,16 @@ export {
   nowIso,
   parseBlockId,
   parseCheckId,
+  parseCompoundResumeState,
   parseCourseId,
   parseLessonId,
   resetStoragePortForTests,
   resetTelemetryBuilderWarningsForTests,
   resolveSessionId,
+  saveCompoundState,
   slugifyId,
+  telemetryCatalogV2Version,
+  telemetryCatalogV3Version,
   telemetryCatalogVersion,
   tryBuildTelemetryEvent,
   tryEmitCourseStarted,