@lessonkit/core 1.5.0 → 1.7.0

package/README.md

@@ -63,7 +63,7 @@ Machine-readable: `@lessonkit/core/telemetry-catalog.v3.json` (current; v1–v3
 
 ## Docs
 
-[Core reference](https://lessonkit.readthedocs.io/en/latest/reference/core.html) · [Identity](https://lessonkit.readthedocs.io/en/latest/reference/identity.html) · [Telemetry](https://lessonkit.readthedocs.io/en/latest/reference/telemetry.html) · [Plugins](https://lessonkit.readthedocs.io/en/latest/reference/plugins.html) · [TypeDoc API index](https://lessonkit.readthedocs.io/en/latest/reference/api.html)
+[5-minute guide](https://lessonkit.readthedocs.io/en/latest/guides/react-developers/getting-started-in-5-minutes.html) · [LMS Go-Live](https://lessonkit.readthedocs.io/en/latest/guides/react-developers/lms-go-live.html) · [Core reference](https://lessonkit.readthedocs.io/en/latest/reference/core.html) · [TypeDoc API index](https://lessonkit.readthedocs.io/en/latest/reference/api.html)
 
 ## License
 

package/dist/{chunk-KFXFQ6B2.js → chunk-DTJGIMUU.js}

@@ -60,7 +60,8 @@ function randomSessionIdFallback() {
   if (g.crypto?.getRandomValues) {
     const bytes = new Uint8Array(16);
     g.crypto.getRandomValues(bytes);
-    return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+    const hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+    return `s-${hex}`;
   }
   throw new Error(
     "[lessonkit] createSessionId requires crypto.randomUUID or crypto.getRandomValues"
@@ -68,7 +69,9 @@ function randomSessionIdFallback() {
 }
 function createSessionId() {
   const g = globalThis;
-  if (g.crypto?.randomUUID) return g.crypto.randomUUID();
+  if (g.crypto?.randomUUID) {
+    return `s-${g.crypto.randomUUID().replace(/-/g, "")}`;
+  }
   return randomSessionIdFallback();
 }
 
@@ -386,6 +389,90 @@ var TELEMETRY_EVENT_REGISTRY = {
         data: opts.data
       };
     }
+  },
+  image_juxtaposition_changed: {
+    build: (opts, base) => ({
+      name: "image_juxtaposition_changed",
+      ...base,
+      lessonId: opts.lessonId,
+      data: opts.data
+    })
+  },
+  timeline_event_viewed: {
+    build: (opts, base) => ({
+      name: "timeline_event_viewed",
+      ...base,
+      lessonId: opts.lessonId,
+      data: opts.data
+    })
+  },
+  image_sequence_changed: {
+    build: (opts, base) => ({
+      name: "image_sequence_changed",
+      ...base,
+      lessonId: opts.lessonId,
+      data: opts.data
+    })
+  },
+  audio_recording_started: {
+    build: (opts, base) => ({
+      name: "audio_recording_started",
+      ...base,
+      lessonId: opts.lessonId,
+      data: opts.data
+    })
+  },
+  audio_recording_completed: {
+    build: (opts, base) => ({
+      name: "audio_recording_completed",
+      ...base,
+      lessonId: opts.lessonId,
+      data: opts.data
+    })
+  },
+  qr_content_revealed: {
+    build: (opts, base) => ({
+      name: "qr_content_revealed",
+      ...base,
+      lessonId: opts.lessonId,
+      data: opts.data
+    })
+  },
+  advent_door_opened: {
+    build: (opts, base) => ({
+      name: "advent_door_opened",
+      ...base,
+      lessonId: opts.lessonId,
+      data: opts.data
+    })
+  },
+  map_stage_viewed: {
+    requiresLessonId: true,
+    build: (opts, base) => {
+      if (opts.name !== "map_stage_viewed") throw new Error("unexpected event");
+      const lessonId = opts.lessonId;
+      if (!lessonId) throw new Error("map_stage_viewed requires active lessonId");
+      return {
+        name: "map_stage_viewed",
+        ...base,
+        lessonId,
+        data: opts.data
+      };
+    }
+  },
+  map_exit_selected: {
+    requiresLessonId: true,
+    build: (opts, base) => {
+      if (opts.name !== "map_exit_selected") throw new Error("unexpected event");
+      const lessonId = opts.lessonId;
+      if (!lessonId) throw new Error("map_exit_selected requires active lessonId");
+      return {
+        name: "map_exit_selected",
+        ...base,
+        lessonId,
+        data: opts.data
+      };
+    }
   }
 };
 function buildTelemetryEventFromRegistry(opts) {
@@ -494,26 +581,35 @@ function createMemoryBackedSessionStorage(session) {
       );
     }
   };
+  const bypassCacheForKey = (key) => key === "lessonkit:sessionId" || key.startsWith("lessonkit:course_started");
   return {
     getItem: (key) => {
       if (tombstones.has(key)) return null;
-      if (memory.has(key)) return memory.get(key);
+      if (!bypassCacheForKey(key) && memory.has(key)) return memory.get(key);
       try {
         const value = session.getItem(key);
-        if (value !== null) memory.set(key, value);
-        return value;
+        if (value !== null) {
+          memory.set(key, value);
+          return value;
+        }
+        if (bypassCacheForKey(key) && memory.has(key)) {
+          return memory.get(key);
+        }
+        if (bypassCacheForKey(key)) memory.delete(key);
+        return null;
       } catch {
         return memory.get(key) ?? null;
       }
     },
     setItem: (key, value) => {
       tombstones.delete(key);
-      memory.set(key, value);
       try {
         session.setItem(key, value);
+        memory.set(key, value);
         return true;
       } catch {
         warnPersistFailure();
+        memory.set(key, value);
         return false;
       }
     },
@@ -579,6 +675,29 @@ function createGlobalTimer() {
 // src/session.ts
 var SESSION_STORAGE_KEY = "lessonkit:sessionId";
 var volatileSessionIds = /* @__PURE__ */ new WeakMap();
+var volatileStorageMarks = /* @__PURE__ */ new WeakMap();
+function rememberVolatileMark(storage, key) {
+  let keys = volatileStorageMarks.get(storage);
+  if (!keys) {
+    keys = /* @__PURE__ */ new Set();
+    volatileStorageMarks.set(storage, keys);
+  }
+  keys.add(key);
+}
+function hasVolatileMark(storage, key) {
+  return volatileStorageMarks.get(storage)?.has(key) ?? false;
+}
+function clearVolatileMark(storage, key) {
+  volatileStorageMarks.get(storage)?.delete(key);
+}
+function storageHasMark(storage, key) {
+  return storage.getItem(key) === "1" || hasVolatileMark(storage, key);
+}
+function storageSetMark(storage, key) {
+  const persisted = storage.setItem(key, "1");
+  if (!persisted) rememberVolatileMark(storage, key);
+  return persisted;
+}
 function isDevEnvironment2() {
   const g = globalThis;
   return typeof g.process !== "undefined" && g.process.env?.NODE_ENV !== "production";
@@ -594,21 +713,7 @@ function sessionKeySegment(sessionId) {
   const validated = validateId(sessionId);
   return validated.ok ? validated.id : encodeURIComponent(sessionId);
 }
-function resolveSessionId(storage, provided) {
-  if (provided !== void 0) {
-    const trimmed = provided.trim();
-    if (trimmed.length > 0) {
-      const validated = validateId(trimmed);
-      if (validated.ok) return validated.id;
-      if (isDevEnvironment2()) {
-        console.warn(
-          `[lessonkit] Invalid sessionId "${trimmed}"; falling back to tab or generated id.`
-        );
-      }
-    }
-  }
-  const existing = storage.getItem(SESSION_STORAGE_KEY);
-  if (existing) return existing;
+function resolveGeneratedSessionId(storage) {
   const volatile = volatileSessionIds.get(storage);
   if (volatile) return volatile;
   const id = createSessionId();
@@ -624,6 +729,50 @@ function resolveSessionId(storage, provided) {
   }
   return id;
 }
+function resolveFallbackSessionId(storage, options) {
+  const existing = storage.getItem(SESSION_STORAGE_KEY);
+  if (existing) {
+    const trimmedExisting = existing.trim();
+    const validatedExisting = validateId(trimmedExisting);
+    if (validatedExisting.ok) return validatedExisting.id;
+    storage.removeItem?.(SESSION_STORAGE_KEY);
+    if (isDevEnvironment2()) {
+      console.warn(
+        `[lessonkit] Invalid stored sessionId "${existing}"; generating a new id.`
+      );
+    }
+    const fallback = resolveGeneratedSessionId(storage);
+    options?.onInvalidSessionId?.({
+      invalidId: existing,
+      fallbackId: fallback,
+      source: "stored"
+    });
+    return fallback;
+  }
+  return resolveGeneratedSessionId(storage);
+}
+function resolveSessionId(storage, provided, options) {
+  if (provided !== void 0) {
+    const trimmed = provided.trim();
+    if (trimmed.length > 0) {
+      const validated = validateId(trimmed);
+      if (validated.ok) return validated.id;
+      if (isDevEnvironment2()) {
+        console.warn(
+          `[lessonkit] Invalid sessionId "${trimmed}"; falling back to tab or generated id.`
+        );
+      }
+      const fallback = resolveFallbackSessionId(storage, options);
+      options?.onInvalidSessionId?.({
+        invalidId: trimmed,
+        fallbackId: fallback,
+        source: "provided"
+      });
+      return fallback;
+    }
+  }
+  return resolveFallbackSessionId(storage, options);
+}
 function courseStartedStorageKey(sessionId, courseId) {
   return `${COURSE_STARTED_PREFIX}${sessionKeySegment(sessionId)}:${courseId ?? ""}`;
 }
@@ -638,35 +787,35 @@ function courseStartedXapiStorageKey(sessionId, courseId) {
 }
 function hasCourseStarted(storage, sessionId, courseId) {
   if (!courseId) return false;
-  return storage.getItem(courseStartedStorageKey(sessionId, courseId)) === "1";
+  return storageHasMark(storage, courseStartedStorageKey(sessionId, courseId));
 }
 function markCourseStarted(storage, sessionId, courseId) {
   if (!courseId) return false;
-  return storage.setItem(courseStartedStorageKey(sessionId, courseId), "1");
+  return storageSetMark(storage, courseStartedStorageKey(sessionId, courseId));
 }
 function hasCourseStartedEmittedToTracking(storage, sessionId, courseId) {
   if (!courseId) return false;
-  return storage.getItem(courseStartedTrackingStorageKey(sessionId, courseId)) === "1";
+  return storageHasMark(storage, courseStartedTrackingStorageKey(sessionId, courseId));
 }
 function markCourseStartedEmittedToTracking(storage, sessionId, courseId) {
   if (!courseId) return false;
-  return storage.setItem(courseStartedTrackingStorageKey(sessionId, courseId), "1");
+  return storageSetMark(storage, courseStartedTrackingStorageKey(sessionId, courseId));
 }
 function hasCourseStartedPipelineDelivered(storage, sessionId, courseId) {
   if (!courseId) return false;
-  return storage.getItem(courseStartedPipelineStorageKey(sessionId, courseId)) === "1";
+  return storageHasMark(storage, courseStartedPipelineStorageKey(sessionId, courseId));
 }
 function markCourseStartedPipelineDelivered(storage, sessionId, courseId) {
   if (!courseId) return false;
-  return storage.setItem(courseStartedPipelineStorageKey(sessionId, courseId), "1");
+  return storageSetMark(storage, courseStartedPipelineStorageKey(sessionId, courseId));
 }
 function hasCourseStartedXapiSent(storage, sessionId, courseId) {
   if (!courseId) return false;
-  return storage.getItem(courseStartedXapiStorageKey(sessionId, courseId)) === "1";
+  return storageHasMark(storage, courseStartedXapiStorageKey(sessionId, courseId));
 }
 function markCourseStartedXapiSent(storage, sessionId, courseId) {
   if (!courseId) return false;
-  return storage.setItem(courseStartedXapiStorageKey(sessionId, courseId), "1");
+  return storageSetMark(storage, courseStartedXapiStorageKey(sessionId, courseId));
 }
 function resetSharedVolatileSessionIdForTests() {
 }
@@ -674,6 +823,7 @@ function migrateStorageMark(storage, fromKey, toKey, hasMark) {
   if (!hasMark) return;
   if (storage.setItem(toKey, "1")) {
     storage.removeItem?.(fromKey);
+    clearVolatileMark(storage, fromKey);
   }
 }
 function migrateCourseStartedMark(storage, fromSessionId, toSessionId, courseId) {
@@ -706,14 +856,32 @@ function migrateCourseStartedMark(storage, fromSessionId, toSessionId, courseId)
 
 // src/runtime/courseLifecycle.ts
 var courseStartedEmitFlights = /* @__PURE__ */ new Map();
+var courseStartedEmittedInTab = /* @__PURE__ */ new Set();
 function resetCourseStartedEmitFlightForTests() {
   courseStartedEmitFlights.clear();
+  courseStartedEmittedInTab.clear();
 }
 function tryEmitCourseStarted(ctx, deps, alreadyEmittedToSink) {
   const flightKey = `${ctx.sessionId}:${ctx.courseId}`;
   const marked = hasCourseStarted(ctx.storage, ctx.sessionId, ctx.courseId);
+  if (courseStartedEmittedInTab.has(flightKey)) {
+    return Promise.resolve({
+      emitted: true,
+      marked: marked || markCourseStarted(ctx.storage, ctx.sessionId, ctx.courseId)
+    });
+  }
   if (alreadyEmittedToSink) {
-    return Promise.resolve({ emitted: true, marked });
+    const markPersisted = marked ? true : markCourseStarted(ctx.storage, ctx.sessionId, ctx.courseId);
+    return Promise.resolve({
+      emitted: true,
+      marked: markPersisted
+    });
+  }
+  if (marked && hasCourseStartedEmittedToTracking(ctx.storage, ctx.sessionId, ctx.courseId)) {
+    return Promise.resolve({
+      emitted: true,
+      marked: true
+    });
   }
   const existing = courseStartedEmitFlights.get(flightKey);
   if (existing) {
@@ -722,15 +890,19 @@ function tryEmitCourseStarted(ctx, deps, alreadyEmittedToSink) {
   const flight = Promise.resolve().then(() => {
     try {
       const emitted = deps.emitCourseStartedEvent(ctx);
-      if (emitted && !marked) {
-        markCourseStarted(ctx.storage, ctx.sessionId, ctx.courseId);
+      if (emitted) {
+        courseStartedEmittedInTab.add(flightKey);
       }
+      const markPersisted = emitted && !marked ? markCourseStarted(ctx.storage, ctx.sessionId, ctx.courseId) : marked;
       return {
         emitted,
-        marked: hasCourseStarted(ctx.storage, ctx.sessionId, ctx.courseId)
+        marked: markPersisted
       };
     } catch {
-      return { emitted: false, marked };
+      return {
+        emitted: false,
+        marked: hasCourseStarted(ctx.storage, ctx.sessionId, ctx.courseId)
+      };
     } finally {
       if (courseStartedEmitFlights.get(flightKey) === flight) {
         courseStartedEmitFlights.delete(flightKey);
@@ -766,7 +938,16 @@ function completeCourseWithTelemetry(opts) {
     });
   }
   const result = opts.progress.completeCourse();
-  if (!result.didComplete) return false;
+  if (!result.didComplete) {
+    const after = opts.progress.getState();
+    if (after.activeLessonId) {
+      const lessonResult = opts.progress.completeLesson(after.activeLessonId, opts.nowMs);
+      if (lessonResult.didComplete) {
+        opts.emitLessonCompleted(after.activeLessonId, lessonResult.durationMs);
+      }
+    }
+    return false;
+  }
   opts.emitCourseCompleted();
   return true;
 }