@lessonkit/core 1.3.0 → 1.4.0

package/dist/index.cjs

@@ -22,11 +22,13 @@ var index_exports = {};
 __export(index_exports, {
   ACCORDION_FORBIDDEN_CHILD_TYPES: () => ACCORDION_FORBIDDEN_CHILD_TYPES,
   ASSESSMENT_SEQUENCE_ALLOWED_CHILD_TYPES: () => ASSESSMENT_SEQUENCE_ALLOWED_CHILD_TYPES,
+  BLOCKS_14_PAGE_SLIDE: () => BLOCKS_14_PAGE_SLIDE,
   COMPOUND_MAX_NESTING_DEPTH: () => COMPOUND_MAX_NESTING_DEPTH,
   COMPOUND_RESUME_SCHEMA_VERSION: () => COMPOUND_RESUME_SCHEMA_VERSION,
   ID_MAX_LENGTH: () => ID_MAX_LENGTH,
   ID_PATTERN: () => ID_PATTERN,
   INTERACTIVE_BOOK_ALLOWED_CHILD_TYPES: () => INTERACTIVE_BOOK_ALLOWED_CHILD_TYPES,
+  INTERACTIVE_VIDEO_ALLOWED_CHILD_TYPES: () => INTERACTIVE_VIDEO_ALLOWED_CHILD_TYPES,
   PAGE_ALLOWED_CHILD_TYPES: () => PAGE_ALLOWED_CHILD_TYPES,
   SESSION_STORAGE_KEY: () => SESSION_STORAGE_KEY,
   SLIDE_ALLOWED_CHILD_TYPES: () => SLIDE_ALLOWED_CHILD_TYPES,
@@ -34,6 +36,7 @@ __export(index_exports, {
   TELEMETRY_EVENT_CATALOG: () => TELEMETRY_EVENT_CATALOG,
   TELEMETRY_EVENT_CATALOG_V2: () => TELEMETRY_EVENT_CATALOG_V2,
   TELEMETRY_EVENT_CATALOG_V3: () => TELEMETRY_EVENT_CATALOG_V3,
+  TIMED_CUE_ALLOWED_CHILD_TYPES: () => TIMED_CUE_ALLOWED_CHILD_TYPES,
   assertNever: () => assertNever,
   assertValidId: () => assertValidId,
   buildCourseStartedTelemetryEvent: () => buildCourseStartedTelemetryEvent,
@@ -322,10 +325,23 @@ function clearCompoundState(storage, courseId, compoundId) {
 }
 
 // src/compoundAllowlists.ts
+var PAGE_AND_SLIDE_14_BLOCKS = [
+  "Video",
+  "Summary",
+  "ImagePairing",
+  "ImageSequencing",
+  "MemoryGame",
+  "InformationWall",
+  "ParallaxSlideshow",
+  "Questionnaire",
+  "Essay",
+  "ArithmeticQuiz"
+];
 var PAGE_ALLOWED_CHILD_TYPES = [
   "Text",
   "Heading",
   "Image",
+  "Video",
   "Scenario",
   "Reflection",
   "Quiz",
@@ -335,6 +351,15 @@ var PAGE_ALLOWED_CHILD_TYPES = [
   "DragAndDrop",
   "DragTheWords",
   "MarkTheWords",
+  "Summary",
+  "ImagePairing",
+  "ImageSequencing",
+  "MemoryGame",
+  "InformationWall",
+  "ParallaxSlideshow",
+  "Questionnaire",
+  "Essay",
+  "ArithmeticQuiz",
   "Accordion",
   "DialogCards",
   "Flashcards",
@@ -349,6 +374,7 @@ var SLIDE_ALLOWED_CHILD_TYPES = [
   "Text",
   "Heading",
   "Image",
+  "Video",
   "Scenario",
   "Reflection",
   "Quiz",
@@ -358,6 +384,15 @@ var SLIDE_ALLOWED_CHILD_TYPES = [
   "DragAndDrop",
   "DragTheWords",
   "MarkTheWords",
+  "Summary",
+  "ImagePairing",
+  "ImageSequencing",
+  "MemoryGame",
+  "InformationWall",
+  "ParallaxSlideshow",
+  "Questionnaire",
+  "Essay",
+  "ArithmeticQuiz",
   "Accordion",
   "DialogCards",
   "Flashcards",
@@ -367,6 +402,22 @@ var SLIDE_ALLOWED_CHILD_TYPES = [
   "ImageSlider"
 ];
 var SLIDE_DECK_ALLOWED_CHILD_TYPES = ["Slide"];
+var TIMED_CUE_ALLOWED_CHILD_TYPES = [
+  "Text",
+  "Heading",
+  "Image",
+  "Quiz",
+  "TrueFalse",
+  "FillInTheBlanks",
+  "Summary",
+  "ImagePairing",
+  "ImageSequencing",
+  "MemoryGame",
+  "Questionnaire",
+  "Essay",
+  "ArithmeticQuiz"
+];
+var INTERACTIVE_VIDEO_ALLOWED_CHILD_TYPES = ["TimedCue"];
 var ASSESSMENT_SEQUENCE_ALLOWED_CHILD_TYPES = [
   "TrueFalse",
   "FillInTheBlanks",
@@ -376,13 +427,20 @@ var ASSESSMENT_SEQUENCE_ALLOWED_CHILD_TYPES = [
   "Quiz",
   "KnowledgeCheck",
   "FindHotspot",
-  "FindMultipleHotspots"
+  "FindMultipleHotspots",
+  "Summary",
+  "ImagePairing",
+  "ImageSequencing",
+  "ArithmeticQuiz",
+  "Essay"
 ];
 var ALLOWLISTS = {
   Page: PAGE_ALLOWED_CHILD_TYPES,
   InteractiveBook: INTERACTIVE_BOOK_ALLOWED_CHILD_TYPES,
   Slide: SLIDE_ALLOWED_CHILD_TYPES,
   SlideDeck: SLIDE_DECK_ALLOWED_CHILD_TYPES,
+  TimedCue: TIMED_CUE_ALLOWED_CHILD_TYPES,
+  InteractiveVideo: INTERACTIVE_VIDEO_ALLOWED_CHILD_TYPES,
   AssessmentSequence: ASSESSMENT_SEQUENCE_ALLOWED_CHILD_TYPES
 };
 var COMPOUND_MAX_NESTING_DEPTH = {
@@ -390,6 +448,8 @@ var COMPOUND_MAX_NESTING_DEPTH = {
   InteractiveBook: 2,
   Slide: 1,
   SlideDeck: 2,
+  TimedCue: 1,
+  InteractiveVideo: 2,
   AssessmentSequence: 1
 };
 function getAllowedChildTypes(parent) {
@@ -399,6 +459,7 @@ function isChildTypeAllowed(parent, childType) {
   return ALLOWLISTS[parent].includes(childType);
 }
 var ACCORDION_FORBIDDEN_CHILD_TYPES = ["Accordion"];
+var BLOCKS_14_PAGE_SLIDE = PAGE_AND_SLIDE_14_BLOCKS;
 
 // src/telemetryCatalog.ts
 var telemetryCatalogVersion = 1;
@@ -554,6 +615,54 @@ var TELEMETRY_EVENT_CATALOG_V3 = [
     dataFields: ["blockId", "slideIndex"],
     xapiVerb: "http://adlnet.gov/expapi/verbs/experienced",
     urnPattern: "urn:lessonkit:course:{courseId}:lesson:{lessonId}:block:{blockId}"
+  },
+  {
+    name: "video_cue_reached",
+    description: "Learner reached a timed cue in an Interactive Video",
+    requiredFields: ["courseId", "lessonId", "sessionId", "timestamp"],
+    dataFields: ["blockId", "cueIndex", "atSeconds", "cueLabel"],
+    xapiVerb: "http://adlnet.gov/expapi/verbs/experienced",
+    urnPattern: "urn:lessonkit:course:{courseId}:lesson:{lessonId}:block:{blockId}"
+  },
+  {
+    name: "video_segment_completed",
+    description: "Learner completed a timed segment in an Interactive Video",
+    requiredFields: ["courseId", "lessonId", "sessionId", "timestamp"],
+    dataFields: ["blockId", "segmentIndex", "atSeconds", "segmentLabel"],
+    xapiVerb: "http://adlnet.gov/expapi/verbs/completed",
+    urnPattern: "urn:lessonkit:course:{courseId}:lesson:{lessonId}:block:{blockId}"
+  },
+  {
+    name: "memory_card_flipped",
+    description: "Learner flipped a memory game card",
+    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: "information_wall_search",
+    description: "Learner searched an information wall",
+    requiredFields: ["courseId", "sessionId", "timestamp"],
+    dataFields: ["blockId", "query", "resultCount"],
+    xapiVerb: "http://adlnet.gov/expapi/verbs/experienced",
+    urnPattern: "urn:lessonkit:course:{courseId}:lesson:{lessonId}:block:{blockId}"
+  },
+  {
+    name: "parallax_slide_viewed",
+    description: "Learner viewed a slide in a parallax slideshow",
+    requiredFields: ["courseId", "sessionId", "timestamp"],
+    dataFields: ["blockId", "slideIndex"],
+    xapiVerb: "http://adlnet.gov/expapi/verbs/experienced",
+    urnPattern: "urn:lessonkit:course:{courseId}:lesson:{lessonId}:block:{blockId}"
+  },
+  {
+    name: "questionnaire_submitted",
+    description: "Learner submitted an unscored questionnaire",
+    requiredFields: ["courseId", "lessonId", "sessionId", "timestamp"],
+    dataFields: ["blockId", "fieldCount"],
+    xapiVerb: "http://adlnet.gov/expapi/verbs/completed",
+    urnPattern: "urn:lessonkit:course:{courseId}:lesson:{lessonId}:block:{blockId}"
   }
 ];
 function buildTelemetryCatalogV3() {
@@ -561,6 +670,18 @@ function buildTelemetryCatalogV3() {
 }
 
 // src/internal/sinkInvoke.ts
+async function invokeTrackingSinkWithResult(sink, event) {
+  try {
+    const result = sink(event);
+    if (result != null && typeof result.then === "function") {
+      await result;
+    }
+    return true;
+  } catch (err) {
+    warnDev("[lessonkit] tracking sink failed:", err);
+    return false;
+  }
+}
 function invokeTrackingSink(sink, event) {
   let result;
   try {
@@ -607,7 +728,17 @@ function createTrackingClient(opts) {
     return {
       track: (event) => {
         if (disposed2) return;
-        if (sink) invokeTrackingSink(sink, event);
+        if (sink) {
+          try {
+            invokeTrackingSink(sink, event);
+          } catch {
+          }
+        }
+      },
+      deliver: async (event) => {
+        if (disposed2) return false;
+        if (!sink) return true;
+        return invokeTrackingSinkWithResult(sink, event);
       },
       dispose: () => {
         disposed2 = true;
@@ -620,12 +751,14 @@ function createTrackingClient(opts) {
   }
   const buffer = [];
   let flushInFlight = null;
+  let inflightExitBatch = null;
   let disposed = false;
   let disposing = false;
   let intervalId;
   const runFlush = () => {
     if (!buffer.length) return Promise.resolve(true);
     const events = buffer.splice(0, buffer.length);
+    inflightExitBatch = events;
     let succeeded = false;
     return Promise.resolve().then(async () => {
       if (batchSink) {
@@ -650,6 +783,8 @@ function createTrackingClient(opts) {
         return runFlush();
       }
       return succeeded;
+    }).finally(() => {
+      inflightExitBatch = null;
     });
   };
   const flush = () => {
@@ -680,23 +815,44 @@ function createTrackingClient(opts) {
   };
   intervalId = flushIntervalMs > 0 ? globalThis.setInterval(() => void flush(), flushIntervalMs) : void 0;
   intervalId?.unref?.();
-  return {
-    track: (event) => {
-      if (disposed || disposing) return;
-      if (buffer.length >= maxBufferSize) {
-        opts?.onBufferDrop?.();
-        if (!warnedBufferCap && isDevEnvironment()) {
-          warnedBufferCap = true;
-          console.warn(
-            `[lessonkit] telemetry batch buffer capped at ${maxBufferSize} events; new events are dropped until the buffer drains.`
-          );
-        }
-        return;
+  const track = (event) => {
+    if (disposed || disposing) return;
+    if (buffer.length >= maxBufferSize) {
+      opts?.onBufferDrop?.();
+      if (!warnedBufferCap && isDevEnvironment()) {
+        warnedBufferCap = true;
+        console.warn(
+          `[lessonkit] telemetry batch buffer capped at ${maxBufferSize} events; new events are dropped until the buffer drains.`
+        );
       }
-      buffer.push(event);
-      if (buffer.length >= maxBatchSize) void flush();
+      return;
+    }
+    buffer.push(event);
+    if (buffer.length >= maxBatchSize) void flush();
+  };
+  return {
+    track,
+    deliver: async (event) => {
+      track(event);
+      return flush();
     },
     flush,
+    flushOnExit: opts?.exitBatchSink ? () => {
+      const fromBuffer = buffer.splice(0, buffer.length);
+      const fromInflight = inflightExitBatch ? [...inflightExitBatch] : [];
+      const events = [...fromInflight, ...fromBuffer];
+      if (!events.length) return;
+      try {
+        const result = opts.exitBatchSink(events);
+        if (result != null && typeof result.catch === "function") {
+          void result.catch(() => {
+            buffer.unshift(...events);
+          });
+        }
+      } catch {
+        buffer.unshift(...events);
+      }
+    } : void 0,
     dispose: () => {
       if (disposed || disposing) return Promise.resolve();
       disposing = true;
@@ -920,6 +1076,81 @@ var TELEMETRY_EVENT_REGISTRY = {
         data: opts.data
       };
     }
+  },
+  video_cue_reached: {
+    requiresLessonId: true,
+    build: (opts, base) => {
+      if (opts.name !== "video_cue_reached") throw new Error("unexpected event");
+      const lessonId = opts.lessonId;
+      if (!lessonId) throw new Error("video_cue_reached requires active lessonId");
+      return {
+        name: "video_cue_reached",
+        ...base,
+        lessonId,
+        data: opts.data
+      };
+    }
+  },
+  video_segment_completed: {
+    requiresLessonId: true,
+    build: (opts, base) => {
+      if (opts.name !== "video_segment_completed") throw new Error("unexpected event");
+      const lessonId = opts.lessonId;
+      if (!lessonId) throw new Error("video_segment_completed requires active lessonId");
+      return {
+        name: "video_segment_completed",
+        ...base,
+        lessonId,
+        data: opts.data
+      };
+    }
+  },
+  memory_card_flipped: {
+    build: (opts, base) => {
+      if (opts.name !== "memory_card_flipped") throw new Error("unexpected event");
+      return {
+        name: "memory_card_flipped",
+        ...base,
+        lessonId: opts.lessonId,
+        data: opts.data
+      };
+    }
+  },
+  information_wall_search: {
+    build: (opts, base) => {
+      if (opts.name !== "information_wall_search") throw new Error("unexpected event");
+      return {
+        name: "information_wall_search",
+        ...base,
+        lessonId: opts.lessonId,
+        data: opts.data
+      };
+    }
+  },
+  parallax_slide_viewed: {
+    build: (opts, base) => {
+      if (opts.name !== "parallax_slide_viewed") throw new Error("unexpected event");
+      return {
+        name: "parallax_slide_viewed",
+        ...base,
+        lessonId: opts.lessonId,
+        data: opts.data
+      };
+    }
+  },
+  questionnaire_submitted: {
+    requiresLessonId: true,
+    build: (opts, base) => {
+      if (opts.name !== "questionnaire_submitted") throw new Error("unexpected event");
+      const lessonId = opts.lessonId;
+      if (!lessonId) throw new Error("questionnaire_submitted requires active lessonId");
+      return {
+        name: "questionnaire_submitted",
+        ...base,
+        lessonId,
+        data: opts.data
+      };
+    }
   }
 };
 function buildTelemetryEventFromRegistry(opts) {
@@ -1207,16 +1438,16 @@ function hasCourseStartedEmittedToTracking(storage, sessionId, courseId) {
   return storage.getItem(courseStartedTrackingStorageKey(sessionId, courseId)) === "1";
 }
 function markCourseStartedEmittedToTracking(storage, sessionId, courseId) {
-  if (!courseId) return;
-  storage.setItem(courseStartedTrackingStorageKey(sessionId, courseId), "1");
+  if (!courseId) return false;
+  return storage.setItem(courseStartedTrackingStorageKey(sessionId, courseId), "1");
 }
 function hasCourseStartedPipelineDelivered(storage, sessionId, courseId) {
   if (!courseId) return false;
   return storage.getItem(courseStartedPipelineStorageKey(sessionId, courseId)) === "1";
 }
 function markCourseStartedPipelineDelivered(storage, sessionId, courseId) {
-  if (!courseId) return;
-  storage.setItem(courseStartedPipelineStorageKey(sessionId, courseId), "1");
+  if (!courseId) return false;
+  return storage.setItem(courseStartedPipelineStorageKey(sessionId, courseId), "1");
 }
 function resetSharedVolatileSessionIdForTests() {
   sharedVolatileSessionId = null;
@@ -1238,19 +1469,29 @@ function migrateCourseStartedMark(storage, fromSessionId, toSessionId, courseId)
 }
 
 // src/runtime/courseLifecycle.ts
+var courseStartedEmitFlights = /* @__PURE__ */ new Set();
 function tryEmitCourseStarted(ctx, deps, alreadyEmittedToSink) {
+  const flightKey = `${ctx.sessionId}:${ctx.courseId}`;
   const marked = hasCourseStarted(ctx.storage, ctx.sessionId, ctx.courseId);
   if (alreadyEmittedToSink) {
     return { emitted: true, marked };
   }
-  const emitted = deps.emitCourseStartedEvent(ctx);
-  if (emitted && !marked) {
-    markCourseStarted(ctx.storage, ctx.sessionId, ctx.courseId);
+  if (courseStartedEmitFlights.has(flightKey)) {
+    return { emitted: false, marked };
+  }
+  courseStartedEmitFlights.add(flightKey);
+  try {
+    const emitted = deps.emitCourseStartedEvent(ctx);
+    if (emitted && !marked) {
+      markCourseStarted(ctx.storage, ctx.sessionId, ctx.courseId);
+    }
+    return {
+      emitted,
+      marked: hasCourseStarted(ctx.storage, ctx.sessionId, ctx.courseId)
+    };
+  } finally {
+    courseStartedEmitFlights.delete(flightKey);
   }
-  return {
-    emitted,
-    marked: hasCourseStarted(ctx.storage, ctx.sessionId, ctx.courseId)
-  };
 }
 function buildCourseStartedTelemetryEvent(ctx) {
   return buildTelemetryEvent({
@@ -1488,11 +1729,13 @@ function createLessonkitRuntime(config, ports = {}) {
       if (next.courseId !== void 0 && next.courseId !== previousCourseId) {
         progress = createProgressController();
       }
-      if (next.plugins !== void 0 && next.plugins !== pluginHost) {
+      if (next.plugins !== void 0 && next.plugins !== configSnapshot.plugins) {
         pluginHost?.disposeAll();
         configSnapshot.plugins = next.plugins;
         pluginHost = resolvePluginHost(configSnapshot.plugins);
-        pluginHost?.setupAll(getPluginCtx());
+        if (!configSnapshot.deferPluginSetup) {
+          pluginHost?.setupAll(getPluginCtx());
+        }
       } else if (next.session !== void 0 && sessionKeyBefore !== sessionKeyAfter && pluginHost && !configSnapshot.deferPluginSetup) {
         pluginHost.disposeAll();
         pluginHost.setupAll(getPluginCtx());
@@ -1502,17 +1745,17 @@ function createLessonkitRuntime(config, ports = {}) {
       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) {
+      if (previous && previous !== lessonId && !current.completedLessonIds.has(previous)) {
         const completed = progress.completeLesson(previous, clock.nowMs());
         if (completed.didComplete) {
           emitLessonCompletedEvents(previous, completed.durationMs, wrapped);
         }
       }
+      if (current.completedLessonIds.has(lessonId)) {
+        progress.setActiveLesson(lessonId, clock.nowMs());
+        return;
+      }
       progress.setActiveLesson(lessonId, clock.nowMs());
       wrapped("lesson_started", { lessonId }, lessonId);
     },
@@ -1533,9 +1776,12 @@ function createLessonkitRuntime(config, ports = {}) {
       });
     },
     track,
-    scoreAssessment(input, _lessonId) {
+    scoreAssessment(input, lessonId) {
       if (!pluginHost) return null;
-      return pluginHost.scoreAssessment(input, getPluginCtx());
+      return pluginHost.scoreAssessment(
+        { ...input, lessonId: input.lessonId ?? lessonId },
+        getPluginCtx()
+      );
     },
     resetForCourseChange(nextCourseId) {
       configSnapshot.courseId = nextCourseId;
@@ -1562,11 +1808,13 @@ function defineLifecyclePlugin(plugin) {
 0 && (module.exports = {
   ACCORDION_FORBIDDEN_CHILD_TYPES,
   ASSESSMENT_SEQUENCE_ALLOWED_CHILD_TYPES,
+  BLOCKS_14_PAGE_SLIDE,
   COMPOUND_MAX_NESTING_DEPTH,
   COMPOUND_RESUME_SCHEMA_VERSION,
   ID_MAX_LENGTH,
   ID_PATTERN,
   INTERACTIVE_BOOK_ALLOWED_CHILD_TYPES,
+  INTERACTIVE_VIDEO_ALLOWED_CHILD_TYPES,
   PAGE_ALLOWED_CHILD_TYPES,
   SESSION_STORAGE_KEY,
   SLIDE_ALLOWED_CHILD_TYPES,
@@ -1574,6 +1822,7 @@ function defineLifecyclePlugin(plugin) {
   TELEMETRY_EVENT_CATALOG,
   TELEMETRY_EVENT_CATALOG_V2,
   TELEMETRY_EVENT_CATALOG_V3,
+  TIMED_CUE_ALLOWED_CHILD_TYPES,
   assertNever,
   assertValidId,
   buildCourseStartedTelemetryEvent,