@lessonkit/core 1.1.0 → 1.3.0

package/dist/index.js

@@ -60,21 +60,40 @@ function assertValidId(input, path = "id") {
 }
 
 // src/slugify.ts
+function shortHash(input) {
+  let h = 0;
+  for (let i = 0; i < input.length; i++) {
+    h = Math.imul(31, h) + input.charCodeAt(i) >>> 0;
+  }
+  return h.toString(36);
+}
+function uniqueFallbackId(input, usedIds) {
+  const hash = shortHash(input);
+  for (let n = 0; n < 100; n++) {
+    const candidate = (n === 0 ? `id-${hash}` : `id-${hash}-${n}`).slice(0, 64);
+    const validated2 = validateId(candidate);
+    if (validated2.ok && !usedIds.has(validated2.id)) return validated2.id;
+  }
+  const timed = `id-${hash}-${Date.now().toString(36)}`.slice(0, 64);
+  const validated = validateId(timed);
+  return validated.ok ? validated.id : `id-${hash}`;
+}
 function slugifyId(input) {
   const slug = input.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").replace(/-+/g, "-").slice(0, 64);
-  if (!slug.length) return "id";
-  const candidate = /^[a-z]/.test(slug) ? slug : `id-${slug}`;
+  if (!slug.length) return uniqueFallbackId(input, /* @__PURE__ */ new Set());
+  const candidate = /^[a-z]/.test(slug) ? slug : `id-${slug}`.slice(0, 64);
   const validated = validateId(candidate);
-  return validated.ok ? validated.id : "id";
+  return validated.ok ? validated.id : uniqueFallbackId(input, /* @__PURE__ */ new Set());
 }
 function deriveId(title, usedIds = /* @__PURE__ */ new Set()) {
   const base = slugifyId(title);
-  if (!usedIds.has(base)) return base;
+  if (!usedIds.has(base) && validateId(base).ok) return base;
   for (let n = 2; n < 1e3; n++) {
-    const candidate = `${base}-${n}`;
-    if (!usedIds.has(candidate)) return candidate;
+    const candidate = `${base}-${n}`.slice(0, 64);
+    const validated = validateId(candidate);
+    if (validated.ok && !usedIds.has(validated.id)) return validated.id;
   }
-  return `${base}-${Date.now()}`;
+  return uniqueFallbackId(`${title}-${Date.now()}`, usedIds);
 }
 
 // src/urn.ts
@@ -102,6 +121,187 @@ 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 isJsonPrimitive(value) {
+  return value === null || typeof value === "boolean" || typeof value === "string" || typeof value === "number" && Number.isFinite(value);
+}
+function isPlainStringKeyMap(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  return Object.entries(value).every(
+    ([key, entry]) => typeof key === "string" && isJsonPrimitive(entry)
+  );
+}
+function isValidChildResumeValue(value) {
+  if (isJsonPrimitive(value)) return true;
+  if (Array.isArray(value)) return value.every((item) => isJsonPrimitive(item));
+  if (isPlainStringKeyMap(value)) return true;
+  return false;
+}
+function isPlainSerializableChildState(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  return Object.values(value).every(
+    (entry) => isValidChildResumeValue(entry)
+  );
+}
+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 (isPlainSerializableChildState(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/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/compoundState.ts
+var COMPOUND_STATE_PREFIX = "lessonkit:compound:";
+function compoundStateStorageKey(courseId, compoundId) {
+  return `${COMPOUND_STATE_PREFIX}${courseId}:${compoundId}`;
+}
+function loadCompoundState(storage, courseId, compoundId) {
+  const key = compoundStateStorageKey(courseId, compoundId);
+  const raw = storage.getItem(key);
+  if (!raw) return null;
+  try {
+    const parsed = parseCompoundResumeState(JSON.parse(raw));
+    if (parsed === null && isDevEnvironment()) {
+      console.warn(`[lessonkit] Ignoring corrupt compound resume state at ${key}`);
+    }
+    return parsed;
+  } catch {
+    if (isDevEnvironment()) {
+      console.warn(`[lessonkit] Ignoring corrupt compound resume state at ${key}`);
+    }
+    return null;
+  }
+}
+function saveCompoundState(storage, courseId, compoundId, state) {
+  return 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 SLIDE_ALLOWED_CHILD_TYPES = [
+  "Text",
+  "Heading",
+  "Image",
+  "Scenario",
+  "Reflection",
+  "Quiz",
+  "KnowledgeCheck",
+  "TrueFalse",
+  "FillInTheBlanks",
+  "DragAndDrop",
+  "DragTheWords",
+  "MarkTheWords",
+  "Accordion",
+  "DialogCards",
+  "Flashcards",
+  "ImageHotspots",
+  "FindHotspot",
+  "FindMultipleHotspots",
+  "ImageSlider"
+];
+var SLIDE_DECK_ALLOWED_CHILD_TYPES = ["Slide"];
+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,
+  Slide: SLIDE_ALLOWED_CHILD_TYPES,
+  SlideDeck: SLIDE_DECK_ALLOWED_CHILD_TYPES,
+  AssessmentSequence: ASSESSMENT_SEQUENCE_ALLOWED_CHILD_TYPES
+};
+var COMPOUND_MAX_NESTING_DEPTH = {
+  Page: 1,
+  InteractiveBook: 2,
+  Slide: 1,
+  SlideDeck: 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 = [
@@ -198,35 +398,99 @@ function buildTelemetryCatalogV2() {
   return TELEMETRY_EVENT_CATALOG_V2.map((entry) => ({ ...entry }));
 }
 
-// src/trackingClient.ts
-function isDevEnvironment() {
-  const g = globalThis;
-  return typeof g.process !== "undefined" && g.process.env?.NODE_ENV !== "production";
+// 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: "slide_viewed",
+    description: "Learner viewed a slide in a SlideDeck (Course Presentation)",
+    requiredFields: ["courseId", "lessonId", "sessionId", "timestamp"],
+    dataFields: ["blockId", "slideIndex", "slideTitle"],
+    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/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;
@@ -262,41 +526,58 @@ function createTrackingClient(opts) {
   let disposing = false;
   let intervalId;
   const runFlush = () => {
-    if (!buffer.length) return Promise.resolve();
+    if (!buffer.length) return Promise.resolve(true);
     const events = buffer.splice(0, buffer.length);
-    let sent = 0;
     let succeeded = false;
     return Promise.resolve().then(async () => {
       if (batchSink) {
         await batchSink(events);
       } else {
-        for (const e of events) {
-          await sink?.(e);
-          sent += 1;
+        for (let i = 0; i < events.length; i++) {
+          try {
+            await sink?.(events[i]);
+          } catch {
+            buffer.unshift(...events.slice(i));
+            return;
+          }
         }
       }
       succeeded = true;
     }).catch(() => {
-      buffer.unshift(...events.slice(sent));
-    }).then(() => {
+      if (batchSink) {
+        buffer.unshift(...events);
+      }
+    }).then(async () => {
       if (succeeded && buffer.length > 0 && !disposed) {
         return runFlush();
       }
+      return succeeded;
     });
   };
   const flush = () => {
-    if (disposed) return Promise.resolve();
+    if (disposed) return Promise.resolve(true);
     if (flushInFlight) return flushInFlight;
-    if (!buffer.length) return Promise.resolve();
+    if (!buffer.length) return Promise.resolve(true);
     flushInFlight = runFlush().finally(() => {
       flushInFlight = null;
     });
     return flushInFlight;
   };
+  const MAX_DISPOSE_FLUSH_ATTEMPTS = 10;
   const drainAll = async () => {
-    await flush();
-    while (buffer.length > 0) {
-      await flush();
+    let attempts = 0;
+    while (buffer.length > 0 && attempts < MAX_DISPOSE_FLUSH_ATTEMPTS) {
+      const delivered = await flush();
+      attempts += 1;
+      if (!delivered) break;
+    }
+    if (buffer.length > 0) {
+      if (isDevEnvironment()) {
+        console.warn(
+          `[lessonkit] dropped ${buffer.length} buffered telemetry event(s) after dispose flush cap`
+        );
+      }
+      buffer.length = 0;
     }
   };
   intervalId = flushIntervalMs > 0 ? globalThis.setInterval(() => void flush(), flushIntervalMs) : void 0;
@@ -305,13 +586,14 @@ function createTrackingClient(opts) {
     track: (event) => {
       if (disposed || disposing) return;
       if (buffer.length >= maxBufferSize) {
-        buffer.shift();
+        opts?.onBufferDrop?.();
         if (!warnedBufferCap && isDevEnvironment()) {
           warnedBufferCap = true;
           console.warn(
-            `[lessonkit] telemetry batch buffer capped at ${maxBufferSize} events; oldest events are dropped while the sink is unavailable.`
+            `[lessonkit] telemetry batch buffer capped at ${maxBufferSize} events; new events are dropped until the buffer drains.`
           );
         }
+        return;
       }
       buffer.push(event);
       if (buffer.length >= maxBatchSize) void flush();
@@ -344,96 +626,243 @@ function nowIso() {
   return (/* @__PURE__ */ new Date()).toISOString();
 }
 
-// src/telemetryBuilder.ts
-var warnedMissingQuizLesson = false;
-var warnedMissingAssessmentLesson = false;
-function isDevEnvironment2() {
-  const g = globalThis;
-  return typeof g.process !== "undefined" && g.process.env?.NODE_ENV !== "production";
-}
-function resetTelemetryBuilderWarningsForTests() {
-  warnedMissingQuizLesson = false;
-  warnedMissingAssessmentLesson = 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
+      };
+    }
+  },
+  interaction: {
+    build: (opts, base) => {
+      if (opts.name !== "interaction") throw new Error("unexpected event");
+      return {
+        name: "interaction",
+        ...base,
+        lessonId: opts.lessonId,
+        data: opts.data
+      };
     }
-    case "assessment_answered": {
+  },
+  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("assessment_answered requires active lessonId");
-      return { name: "assessment_answered", ...base, lessonId, data: opts.data };
+      if (!lessonId) throw new Error("book_page_viewed requires active lessonId");
+      return {
+        name: "book_page_viewed",
+        ...base,
+        lessonId,
+        data: opts.data
+      };
     }
-    case "assessment_completed": {
+  },
+  slide_viewed: {
+    requiresLessonId: true,
+    build: (opts, base) => {
+      if (opts.name !== "slide_viewed") throw new Error("unexpected event");
       const lessonId = opts.lessonId;
-      if (!lessonId) throw new Error("assessment_completed requires active lessonId");
-      return { name: "assessment_completed", ...base, lessonId, data: opts.data };
+      if (!lessonId) throw new Error("slide_viewed requires active lessonId");
+      return {
+        name: "slide_viewed",
+        ...base,
+        lessonId,
+        data: opts.data
+      };
     }
-    case "interaction":
+  },
+  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: "interaction",
+        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
       };
-    default:
-      return assertNever(opts);
+    }
+  }
+};
+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 needsLesson = opts.name === "quiz_answered" || opts.name === "quiz_completed" || opts.name === "assessment_answered" || opts.name === "assessment_completed";
-  if (needsLesson && !opts.lessonId) {
-    if (isDevEnvironment2()) {
-      if (opts.name.startsWith("quiz_") && !warnedMissingQuizLesson) {
+  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 (opts.name.startsWith("assessment_") && !warnedMissingAssessmentLesson) {
+      if (entry.tryBuildMissingLessonWarning === "assessment" && !warnedMissingAssessmentLesson) {
         warnedMissingAssessmentLesson = true;
         console.warn(
           `[lessonkit] ${opts.name} skipped: wrap assessment blocks in <Lesson> so an active lessonId is available`
@@ -446,29 +875,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];
@@ -505,8 +913,7 @@ function createDefaultClock() {
 function createNoopStorage() {
   return {
     getItem: () => null,
-    setItem: () => {
-    }
+    setItem: () => true
   };
 }
 function createMemoryBackedSessionStorage(session) {
@@ -537,8 +944,10 @@ function createMemoryBackedSessionStorage(session) {
       memory.set(key, value);
       try {
         session.setItem(key, value);
+        return true;
       } catch {
         warnPersistFailure();
+        return false;
       }
     },
     removeItem: (key) => {
@@ -563,6 +972,7 @@ function createInMemorySessionStoragePort() {
     getItem: (key) => memory.get(key) ?? null,
     setItem: (key, value) => {
       memory.set(key, value);
+      return true;
     },
     removeItem: (key) => {
       memory.delete(key);
@@ -615,7 +1025,12 @@ function createProgressController() {
       return { previousLessonId };
     },
     completeLesson: (lessonId, completedAtMs) => {
-      if (completedLessonIds.has(lessonId)) return { didComplete: false };
+      if (completedLessonIds.has(lessonId)) {
+        if (activeLessonId === lessonId) {
+          activeLessonId = void 0;
+        }
+        return { didComplete: false };
+      }
       completedLessonIds = new Set(completedLessonIds).add(lessonId);
       if (activeLessonId === lessonId) {
         activeLessonId = void 0;
@@ -635,6 +1050,12 @@ function createProgressController() {
 
 // src/session.ts
 var SESSION_STORAGE_KEY = "lessonkit:sessionId";
+var volatileSessionIds = /* @__PURE__ */ new WeakMap();
+var sharedVolatileSessionId = null;
+function isDevEnvironment2() {
+  const g = globalThis;
+  return typeof g.process !== "undefined" && g.process.env?.NODE_ENV !== "production";
+}
 function getTabSessionId(storage) {
   return storage.getItem(SESSION_STORAGE_KEY);
 }
@@ -642,11 +1063,28 @@ var COURSE_STARTED_PREFIX = "lessonkit:course_started:";
 var COURSE_STARTED_TRACKING_PREFIX = "lessonkit:course_started_tracking:";
 var COURSE_STARTED_PIPELINE_PREFIX = "lessonkit:course_started_pipeline:";
 function resolveSessionId(storage, provided) {
-  if (provided) return provided;
+  if (provided !== void 0) {
+    const trimmed = provided.trim();
+    if (trimmed.length > 0) return trimmed;
+  }
   const existing = storage.getItem(SESSION_STORAGE_KEY);
   if (existing) return existing;
+  const volatile = volatileSessionIds.get(storage);
+  if (volatile) return volatile;
   const id = createSessionId();
-  storage.setItem(SESSION_STORAGE_KEY, id);
+  const persisted = storage.setItem(SESSION_STORAGE_KEY, id);
+  if (!persisted) {
+    if (!sharedVolatileSessionId) {
+      sharedVolatileSessionId = id;
+    }
+    volatileSessionIds.set(storage, sharedVolatileSessionId);
+    if (isDevEnvironment2()) {
+      console.warn(
+        "[lessonkit] session id could not be persisted; reusing in-memory id for this tab."
+      );
+    }
+    return sharedVolatileSessionId;
+  }
   return id;
 }
 function courseStartedStorageKey(sessionId, courseId) {
@@ -663,8 +1101,8 @@ function hasCourseStarted(storage, sessionId, courseId) {
   return storage.getItem(courseStartedStorageKey(sessionId, courseId)) === "1";
 }
 function markCourseStarted(storage, sessionId, courseId) {
-  if (!courseId) return;
-  storage.setItem(courseStartedStorageKey(sessionId, courseId), "1");
+  if (!courseId) return false;
+  return storage.setItem(courseStartedStorageKey(sessionId, courseId), "1");
 }
 function hasCourseStartedEmittedToTracking(storage, sessionId, courseId) {
   if (!courseId) return false;
@@ -682,6 +1120,9 @@ function markCourseStartedPipelineDelivered(storage, sessionId, courseId) {
   if (!courseId) return;
   storage.setItem(courseStartedPipelineStorageKey(sessionId, courseId), "1");
 }
+function resetSharedVolatileSessionIdForTests() {
+  sharedVolatileSessionId = null;
+}
 function migrateCourseStartedMark(storage, fromSessionId, toSessionId, courseId) {
   if (!courseId || fromSessionId === toSessionId) return;
   if (hasCourseStarted(storage, fromSessionId, courseId)) {
@@ -704,14 +1145,14 @@ function tryEmitCourseStarted(ctx, deps, alreadyEmittedToSink) {
   if (alreadyEmittedToSink) {
     return { emitted: true, marked };
   }
-  if (marked) {
-    return { emitted: false, marked: true };
-  }
   const emitted = deps.emitCourseStartedEvent(ctx);
-  if (emitted) {
+  if (emitted && !marked) {
     markCourseStarted(ctx.storage, ctx.sessionId, ctx.courseId);
   }
-  return { emitted, marked: emitted };
+  return {
+    emitted,
+    marked: hasCourseStarted(ctx.storage, ctx.sessionId, ctx.courseId)
+  };
 }
 function buildCourseStartedTelemetryEvent(ctx) {
   return buildTelemetryEvent({
@@ -744,101 +1185,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
   };
 }
 
@@ -889,7 +1242,7 @@ function createPluginRegistry(plugins = []) {
   const composeTrackingSink = (sink, ctxSource) => {
     if (!sink) return void 0;
     const resolveCtx = () => typeof ctxSource === "function" ? ctxSource() : ctxSource;
-    const ctxKey = (ctx) => `${ctx.courseId}\0${ctx.sessionId ?? ""}\0${ctx.attemptId ?? ""}`;
+    const ctxKey = (ctx) => `${ctx.courseId}\0${ctx.sessionId ?? ""}\0${ctx.attemptId ?? ""}\0${ctx.user?.id ?? ""}`;
     const layers = [];
     let composed = sink;
     for (const plugin of list) {
@@ -929,6 +1282,174 @@ 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
+  });
+  if (!configSnapshot.deferPluginSetup) {
+    pluginHost?.setupAll(getPluginCtx());
+  }
+  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) {
+      const previousCourseId = courseId;
+      const sessionKeyBefore = JSON.stringify({ sessionId, attemptId, user });
+      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);
+      const sessionKeyAfter = JSON.stringify({ sessionId, attemptId, user });
+      if (next.courseId !== void 0 && next.courseId !== previousCourseId) {
+        progress = createProgressController();
+      }
+      if (next.plugins !== void 0 && next.plugins !== pluginHost) {
+        pluginHost?.disposeAll();
+        configSnapshot.plugins = next.plugins;
+        pluginHost = resolvePluginHost(configSnapshot.plugins);
+        pluginHost?.setupAll(getPluginCtx());
+      } else if (next.session !== void 0 && sessionKeyBefore !== sessionKeyAfter && pluginHost && !configSnapshot.deferPluginSetup) {
+        pluginHost.disposeAll();
+        pluginHost.setupAll(getPluginCtx());
+      }
+    },
+    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;
@@ -940,20 +1461,35 @@ 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,
+  SLIDE_ALLOWED_CHILD_TYPES,
+  SLIDE_DECK_ALLOWED_CHILD_TYPES,
   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,
@@ -969,10 +1505,13 @@ export {
   defineLifecyclePlugin,
   defineTelemetryPlugin,
   deriveId,
+  getAllowedChildTypes,
   getTabSessionId,
   hasCourseStarted,
   hasCourseStartedEmittedToTracking,
   hasCourseStartedPipelineDelivered,
+  isChildTypeAllowed,
+  loadCompoundState,
   markCourseStarted,
   markCourseStartedEmittedToTracking,
   markCourseStartedPipelineDelivered,
@@ -980,13 +1519,17 @@ export {
   nowIso,
   parseBlockId,
   parseCheckId,
+  parseCompoundResumeState,
   parseCourseId,
   parseLessonId,
+  resetSharedVolatileSessionIdForTests,
   resetStoragePortForTests,
   resetTelemetryBuilderWarningsForTests,
   resolveSessionId,
+  saveCompoundState,
   slugifyId,
   telemetryCatalogV2Version,
+  telemetryCatalogV3Version,
   telemetryCatalogVersion,
   tryBuildTelemetryEvent,
   tryEmitCourseStarted,