@lessonkit/core 1.6.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-NGCHHJSM.js → chunk-DTJGIMUU.js}

@@ -588,9 +588,15 @@ function createMemoryBackedSessionStorage(session) {
       if (!bypassCacheForKey(key) && memory.has(key)) return memory.get(key);
       try {
         const value = session.getItem(key);
-        if (value !== null) memory.set(key, value);
-        else if (bypassCacheForKey(key)) memory.delete(key);
-        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;
       }
@@ -603,9 +609,7 @@ function createMemoryBackedSessionStorage(session) {
         return true;
       } catch {
         warnPersistFailure();
-        if (!bypassCacheForKey(key)) {
-          memory.set(key, value);
-        }
+        memory.set(key, value);
         return false;
       }
     },
@@ -671,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";
@@ -686,19 +713,23 @@ 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.`
-        );
-      }
+function resolveGeneratedSessionId(storage) {
+  const volatile = volatileSessionIds.get(storage);
+  if (volatile) return volatile;
+  const id = createSessionId();
+  const persisted = storage.setItem(SESSION_STORAGE_KEY, id);
+  if (!persisted) {
+    volatileSessionIds.set(storage, id);
+    if (isDevEnvironment2()) {
+      console.warn(
+        "[lessonkit] session id could not be persisted; using in-memory id for this storage."
+      );
     }
+    return id;
   }
+  return id;
+}
+function resolveFallbackSessionId(storage, options) {
   const existing = storage.getItem(SESSION_STORAGE_KEY);
   if (existing) {
     const trimmedExisting = existing.trim();
@@ -710,21 +741,37 @@ function resolveSessionId(storage, provided) {
         `[lessonkit] Invalid stored sessionId "${existing}"; generating a new id.`
       );
     }
+    const fallback = resolveGeneratedSessionId(storage);
+    options?.onInvalidSessionId?.({
+      invalidId: existing,
+      fallbackId: fallback,
+      source: "stored"
+    });
+    return fallback;
   }
-  const volatile = volatileSessionIds.get(storage);
-  if (volatile) return volatile;
-  const id = createSessionId();
-  const persisted = storage.setItem(SESSION_STORAGE_KEY, id);
-  if (!persisted) {
-    volatileSessionIds.set(storage, id);
-    if (isDevEnvironment2()) {
-      console.warn(
-        "[lessonkit] session id could not be persisted; using in-memory id for this storage."
-      );
+  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 id;
   }
-  return id;
+  return resolveFallbackSessionId(storage, options);
 }
 function courseStartedStorageKey(sessionId, courseId) {
   return `${COURSE_STARTED_PREFIX}${sessionKeySegment(sessionId)}:${courseId ?? ""}`;
@@ -740,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() {
 }
@@ -776,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) {
@@ -808,12 +856,20 @@ 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) {
     const markPersisted = marked ? true : markCourseStarted(ctx.storage, ctx.sessionId, ctx.courseId);
     return Promise.resolve({
@@ -834,6 +890,9 @@ function tryEmitCourseStarted(ctx, deps, alreadyEmittedToSink) {
   const flight = Promise.resolve().then(() => {
     try {
       const emitted = deps.emitCourseStartedEvent(ctx);
+      if (emitted) {
+        courseStartedEmittedInTab.add(flightKey);
+      }
       const markPersisted = emitted && !marked ? markCourseStarted(ctx.storage, ctx.sessionId, ctx.courseId) : marked;
       return {
         emitted,