@lessonkit/core 1.2.0 → 1.3.0

package/dist/index.cjs

@@ -29,6 +29,8 @@ __export(index_exports, {
   INTERACTIVE_BOOK_ALLOWED_CHILD_TYPES: () => INTERACTIVE_BOOK_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,
+  SLIDE_DECK_ALLOWED_CHILD_TYPES: () => SLIDE_DECK_ALLOWED_CHILD_TYPES,
   TELEMETRY_EVENT_CATALOG: () => TELEMETRY_EVENT_CATALOG,
   TELEMETRY_EVENT_CATALOG_V2: () => TELEMETRY_EVENT_CATALOG_V2,
   TELEMETRY_EVENT_CATALOG_V3: () => TELEMETRY_EVENT_CATALOG_V3,
@@ -79,6 +81,7 @@ __export(index_exports, {
   parseCompoundResumeState: () => parseCompoundResumeState,
   parseCourseId: () => parseCourseId,
   parseLessonId: () => parseLessonId,
+  resetSharedVolatileSessionIdForTests: () => resetSharedVolatileSessionIdForTests,
   resetStoragePortForTests: () => resetStoragePortForTests,
   resetTelemetryBuilderWarningsForTests: () => resetTelemetryBuilderWarningsForTests,
   resolveSessionId: () => resolveSessionId,
@@ -155,21 +158,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
@@ -217,6 +239,27 @@ 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;
@@ -225,7 +268,7 @@ function parseCompoundResumeState(raw) {
   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)) {
+      if (isPlainSerializableChildState(value)) {
         childStates[key] = value;
       }
     }
@@ -239,22 +282,40 @@ function parseCompoundResumeState(raw) {
   };
 }
 
+// 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 raw = storage.getItem(compoundStateStorageKey(courseId, compoundId));
+  const key = compoundStateStorageKey(courseId, compoundId);
+  const raw = storage.getItem(key);
   if (!raw) return null;
   try {
-    return parseCompoundResumeState(JSON.parse(raw));
+    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) {
-  storage.setItem(compoundStateStorageKey(courseId, compoundId), JSON.stringify(state));
+  return storage.setItem(compoundStateStorageKey(courseId, compoundId), JSON.stringify(state));
 }
 function clearCompoundState(storage, courseId, compoundId) {
   storage.removeItem?.(compoundStateStorageKey(courseId, compoundId));
@@ -284,6 +345,28 @@ var PAGE_ALLOWED_CHILD_TYPES = [
   "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",
@@ -298,11 +381,15 @@ var ASSESSMENT_SEQUENCE_ALLOWED_CHILD_TYPES = [
 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) {
@@ -420,6 +507,14 @@ var TELEMETRY_EVENT_CATALOG_V3 = [
     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",
@@ -465,16 +560,6 @@ 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;
@@ -539,41 +624,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;
@@ -582,13 +684,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();
@@ -746,6 +849,20 @@ var TELEMETRY_EVENT_REGISTRY = {
       };
     }
   },
+  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("slide_viewed requires active lessonId");
+      return {
+        name: "slide_viewed",
+        ...base,
+        lessonId,
+        data: opts.data
+      };
+    }
+  },
   compound_page_viewed: {
     requiresLessonId: true,
     build: (opts, base) => {
@@ -894,8 +1011,7 @@ function createDefaultClock() {
 function createNoopStorage() {
   return {
     getItem: () => null,
-    setItem: () => {
-    }
+    setItem: () => true
   };
 }
 function createMemoryBackedSessionStorage(session) {
@@ -926,8 +1042,10 @@ function createMemoryBackedSessionStorage(session) {
       memory.set(key, value);
       try {
         session.setItem(key, value);
+        return true;
       } catch {
         warnPersistFailure();
+        return false;
       }
     },
     removeItem: (key) => {
@@ -952,6 +1070,7 @@ function createInMemorySessionStoragePort() {
     getItem: (key) => memory.get(key) ?? null,
     setItem: (key, value) => {
       memory.set(key, value);
+      return true;
     },
     removeItem: (key) => {
       memory.delete(key);
@@ -1004,7 +1123,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;
@@ -1024,6 +1148,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);
 }
@@ -1031,11 +1161,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) {
@@ -1052,8 +1199,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;
@@ -1071,6 +1218,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)) {
@@ -1093,14 +1243,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({
@@ -1190,7 +1340,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) {
@@ -1261,6 +1411,9 @@ function createLessonkitRuntime(config, ports = {}) {
     attemptId,
     user
   });
+  if (!configSnapshot.deferPluginSetup) {
+    pluginHost?.setupAll(getPluginCtx());
+  }
   const getSession = () => ({ sessionId, attemptId, user });
   const syncSessionFromConfig = (next) => {
     sessionId = resolveSessionId(storage, next.session?.sessionId);
@@ -1320,11 +1473,8 @@ function createLessonkitRuntime(config, ports = {}) {
     getProgressState: () => progress.getState(),
     getSession,
     updateConfig(next) {
-      if (next.plugins !== void 0 && next.plugins !== pluginHost) {
-        pluginHost?.disposeAll();
-        configSnapshot.plugins = next.plugins;
-        pluginHost = resolvePluginHost(configSnapshot.plugins);
-      }
+      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();
@@ -1334,6 +1484,19 @@ function createLessonkitRuntime(config, ports = {}) {
         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);
@@ -1406,6 +1569,8 @@ function defineLifecyclePlugin(plugin) {
   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,
@@ -1456,6 +1621,7 @@ function defineLifecyclePlugin(plugin) {
   parseCompoundResumeState,
   parseCourseId,
   parseLessonId,
+  resetSharedVolatileSessionIdForTests,
   resetStoragePortForTests,
   resetTelemetryBuilderWarningsForTests,
   resolveSessionId,

package/dist/index.d.cts

@@ -92,7 +92,7 @@ type AssessmentBaseProps = AssessmentBehaviour & {
     passingScore?: number;
 };
 
-type TelemetryEventName = "course_started" | "course_completed" | "lesson_started" | "lesson_completed" | "lesson_time_on_task" | "quiz_answered" | "quiz_completed" | "assessment_answered" | "assessment_completed" | "interaction" | "book_page_viewed" | "compound_page_viewed" | "hotspot_opened" | "accordion_section_toggled" | "flashcard_flipped" | "image_slider_changed";
+type TelemetryEventName = "course_started" | "course_completed" | "lesson_started" | "lesson_completed" | "lesson_time_on_task" | "quiz_answered" | "quiz_completed" | "assessment_answered" | "assessment_completed" | "interaction" | "book_page_viewed" | "slide_viewed" | "compound_page_viewed" | "hotspot_opened" | "accordion_section_toggled" | "flashcard_flipped" | "image_slider_changed";
 type TelemetryUser = {
     id?: string;
     email?: string;
@@ -150,6 +150,11 @@ type BookPageViewedData = {
     pageIndex: number;
     pageTitle?: string;
 };
+type SlideViewedData = {
+    blockId: BlockId;
+    slideIndex: number;
+    slideTitle?: string;
+};
 type CompoundPageViewedData = {
     blockId: BlockId;
     pageIndex: number;
@@ -217,6 +222,10 @@ type TelemetryEvent = (TelemetryEventBase & {
     name: "book_page_viewed";
     lessonId: LessonId;
     data: BookPageViewedData;
+}) | (TelemetryEventBase & {
+    name: "slide_viewed";
+    lessonId: LessonId;
+    data: SlideViewedData;
 }) | (TelemetryEventBase & {
     name: "compound_page_viewed";
     lessonId: LessonId;
@@ -248,7 +257,8 @@ type TelemetrySink = (event: TelemetryEvent) => void | Promise<void>;
 type TelemetryBatchSink = (events: TelemetryEvent[]) => void | Promise<void>;
 type TrackingClient = {
     track: (event: TelemetryEvent) => void;
-    flush?: () => void | Promise<void>;
+    /** Resolves to true when all buffered events were delivered; false when a sink failure re-queued events. */
+    flush?: () => void | Promise<boolean>;
     dispose?: () => void | Promise<void>;
 };
 
@@ -289,7 +299,8 @@ type CompoundBaseProps = {
 
 type StoragePort = {
     getItem: (key: string) => string | null;
-    setItem: (key: string, value: string) => void;
+    /** Returns false when the value could not be durably persisted (e.g. sessionStorage quota). */
+    setItem: (key: string, value: string) => boolean;
     removeItem?: (key: string) => void;
     /** @internal Test helper to clear in-memory fallback state. */
     resetForTests?: () => void;
@@ -310,14 +321,17 @@ declare function createGlobalTimer(): TimerPort;
 
 declare function compoundStateStorageKey(courseId: CourseId, compoundId: BlockId): string;
 declare function loadCompoundState(storage: StoragePort, courseId: CourseId, compoundId: BlockId): CompoundResumeState | null;
-declare function saveCompoundState(storage: StoragePort, courseId: CourseId, compoundId: BlockId, state: CompoundResumeState): void;
+declare function saveCompoundState(storage: StoragePort, courseId: CourseId, compoundId: BlockId, state: CompoundResumeState): boolean;
 declare function clearCompoundState(storage: StoragePort, courseId: CourseId, compoundId: BlockId): void;
 
 /** Canonical compound child allowlists (H5P sub-content curation). */
 declare const PAGE_ALLOWED_CHILD_TYPES: readonly ["Text", "Heading", "Image", "Scenario", "Reflection", "Quiz", "KnowledgeCheck", "TrueFalse", "FillInTheBlanks", "DragAndDrop", "DragTheWords", "MarkTheWords", "Accordion", "DialogCards", "Flashcards", "ImageHotspots", "FindHotspot", "FindMultipleHotspots", "ImageSlider", "ProgressTracker"];
 declare const INTERACTIVE_BOOK_ALLOWED_CHILD_TYPES: readonly ["Page"];
+/** Per-slide content (H5P Course Presentation slide row). Excludes ProgressTracker. */
+declare const SLIDE_ALLOWED_CHILD_TYPES: readonly ["Text", "Heading", "Image", "Scenario", "Reflection", "Quiz", "KnowledgeCheck", "TrueFalse", "FillInTheBlanks", "DragAndDrop", "DragTheWords", "MarkTheWords", "Accordion", "DialogCards", "Flashcards", "ImageHotspots", "FindHotspot", "FindMultipleHotspots", "ImageSlider"];
+declare const SLIDE_DECK_ALLOWED_CHILD_TYPES: readonly ["Slide"];
 declare const ASSESSMENT_SEQUENCE_ALLOWED_CHILD_TYPES: readonly ["TrueFalse", "FillInTheBlanks", "DragAndDrop", "DragTheWords", "MarkTheWords", "Quiz", "KnowledgeCheck", "FindHotspot", "FindMultipleHotspots"];
-type CompoundParentType = "Page" | "InteractiveBook" | "AssessmentSequence";
+type CompoundParentType = "Page" | "InteractiveBook" | "Slide" | "SlideDeck" | "AssessmentSequence";
 declare const COMPOUND_MAX_NESTING_DEPTH: Record<CompoundParentType, number>;
 declare function getAllowedChildTypes(parent: CompoundParentType): readonly string[];
 declare function isChildTypeAllowed(parent: CompoundParentType, childType: string): boolean;
@@ -349,7 +363,7 @@ declare const TELEMETRY_EVENT_CATALOG_V2: TelemetryCatalogV2Entry[];
 declare function buildTelemetryCatalogV2(): TelemetryCatalogV2Entry[];
 
 declare const telemetryCatalogV3Version: 3;
-type TelemetryCatalogV3EventName = Extract<TelemetryEventName, "book_page_viewed" | "compound_page_viewed" | "hotspot_opened" | "accordion_section_toggled" | "flashcard_flipped" | "image_slider_changed">;
+type TelemetryCatalogV3EventName = Extract<TelemetryEventName, "book_page_viewed" | "slide_viewed" | "compound_page_viewed" | "hotspot_opened" | "accordion_section_toggled" | "flashcard_flipped" | "image_slider_changed">;
 type TelemetryCatalogV3Entry = {
     name: TelemetryCatalogV3EventName;
     description: string;
@@ -369,6 +383,8 @@ declare function createTrackingClient(opts?: {
         maxBatchSize?: number;
     };
     batchSink?: TelemetryBatchSink;
+    /** Called when an event is dropped because the batch buffer is at cap (including in production). */
+    onBufferDrop?: () => void;
 }): TrackingClient;
 
 declare function createSessionId(): string;
@@ -426,6 +442,10 @@ type BuildTelemetryEventInput = (BuildTelemetryEventContext & {
     name: "book_page_viewed";
     lessonId?: LessonId;
     data: BookPageViewedData;
+}) | (BuildTelemetryEventContext & {
+    name: "slide_viewed";
+    lessonId?: LessonId;
+    data: SlideViewedData;
 }) | (BuildTelemetryEventContext & {
     name: "compound_page_viewed";
     lessonId?: LessonId;
@@ -501,11 +521,13 @@ declare const SESSION_STORAGE_KEY = "lessonkit:sessionId";
 declare function getTabSessionId(storage: StoragePort): string | null;
 declare function resolveSessionId(storage: StoragePort, provided?: string): string;
 declare function hasCourseStarted(storage: StoragePort, sessionId: string, courseId?: CourseId): boolean;
-declare function markCourseStarted(storage: StoragePort, sessionId: string, courseId?: CourseId): void;
+declare function markCourseStarted(storage: StoragePort, sessionId: string, courseId?: CourseId): boolean;
 declare function hasCourseStartedEmittedToTracking(storage: StoragePort, sessionId: string, courseId?: CourseId): boolean;
 declare function markCourseStartedEmittedToTracking(storage: StoragePort, sessionId: string, courseId?: CourseId): void;
 declare function hasCourseStartedPipelineDelivered(storage: StoragePort, sessionId: string, courseId?: CourseId): boolean;
 declare function markCourseStartedPipelineDelivered(storage: StoragePort, sessionId: string, courseId?: CourseId): void;
+/** @internal Reset shared volatile session id between tests. */
+declare function resetSharedVolatileSessionIdForTests(): void;
 declare function migrateCourseStartedMark(storage: StoragePort, fromSessionId: string, toSessionId: string, courseId?: CourseId): void;
 
 /** Plugin category — aligns with roadmap extension areas. */
@@ -623,6 +645,8 @@ type HeadlessLessonkitConfig = {
     };
     /** Plugin list or registry; hooks run on {@link HeadlessLessonkitRuntime.track} and lifecycle emits. */
     plugins?: HeadlessLessonkitPlugins;
+    /** When true, skip initial {@link PluginHost.setupAll}; host caller runs setup (React v2 provider). */
+    deferPluginSetup?: boolean;
 };
 type HeadlessRuntimePorts = {
     storage?: StoragePort;
@@ -668,4 +692,4 @@ declare function buildPluginContext(opts: {
     user?: TelemetryUser;
 }): LessonkitPluginContext;
 
-export { ACCORDION_FORBIDDEN_CHILD_TYPES, ASSESSMENT_SEQUENCE_ALLOWED_CHILD_TYPES, type AccordionSectionToggledData, type AssessmentAnsweredData, type AssessmentBaseProps, type AssessmentBehaviour, type AssessmentCompletedData, type AssessmentHandle, type AssessmentInteractionType, type AssessmentPlugin, type AssessmentResumeState, type AssessmentScoreInput, type AssessmentScoreResult, type AssessmentXAPIData, type BlockId, type BookPageViewedData, type BuildTelemetryEventInput, COMPOUND_MAX_NESTING_DEPTH, COMPOUND_RESUME_SCHEMA_VERSION, type CheckId, type ClockPort, type CompoundBaseProps, type CompoundHandle, type CompoundPageViewedData, type CompoundParentType, type CompoundResumeInput, type CompoundResumeState, type CourseId, type CourseLifecycleContext, type CourseLifecycleDeps, type EmitContext, type FlashcardFlippedData, type HeadlessLessonkitConfig, type HeadlessLessonkitRuntime, type HeadlessRuntimePorts, type HotspotOpenedData, ID_MAX_LENGTH, ID_PATTERN, INTERACTIVE_BOOK_ALLOWED_CHILD_TYPES, type IdentityIdPath, type IdentityValidationIssue, type IdentityValidationResult, type ImageSliderChangedData, type InteractionBlockRegistration, type InteractionData, type InteractionPlugin, type LessonCompletionEmitter, type LessonId, type LessonLifecycleData, type LessonkitPlugin, type LessonkitPluginContext, type LessonkitPluginKind, type LessonkitRuntimeVersion, type LessonkitUrn, type LessonkitUrnParts, type LifecyclePlugin, PAGE_ALLOWED_CHILD_TYPES, type PluginHost, type PluginIdentity, type PluginRegistry, type ProgressController, type ProgressState, type QuizAnsweredData, type QuizCompletedData, SESSION_STORAGE_KEY, type StoragePort, TELEMETRY_EVENT_CATALOG, TELEMETRY_EVENT_CATALOG_V2, TELEMETRY_EVENT_CATALOG_V3, type TelemetryBatchSink, type TelemetryCatalogEntry, type TelemetryCatalogV2Entry, type TelemetryCatalogV3Entry, type TelemetryDataFor, type TelemetryEmitFn, type TelemetryEvent, type TelemetryEventBase, type TelemetryEventName, type TelemetryPipeline, type TelemetryPipelineSink, type TelemetryPlugin, type TelemetrySink, type TelemetryUser, type TimerPort, type TrackingClient, assertNever, assertValidId, buildCourseStartedTelemetryEvent, buildLessonkitUrn, buildPluginContext, buildTelemetryCatalog, buildTelemetryCatalogV2, buildTelemetryCatalogV3, buildTelemetryEvent, clampCompoundPageIndex, clearCompoundState, completeCourseWithTelemetry, completeLessonWithTelemetry, compoundStateStorageKey, createCompoundResumeState, createDefaultClock, createGlobalTimer, createLessonkitRuntime, createNoopStorage, createPluginRegistry, createProgressController, createSessionId, createSessionStoragePort, createTelemetryPipeline, createTrackingClient, createTrackingPipelineSink, defineAssessmentPlugin, defineLifecyclePlugin, defineTelemetryPlugin, deriveId, getAllowedChildTypes, getTabSessionId, hasCourseStarted, hasCourseStartedEmittedToTracking, hasCourseStartedPipelineDelivered, isChildTypeAllowed, loadCompoundState, markCourseStarted, markCourseStartedEmittedToTracking, markCourseStartedPipelineDelivered, migrateCourseStartedMark, nowIso, parseBlockId, parseCheckId, parseCompoundResumeState, parseCourseId, parseLessonId, resetStoragePortForTests, resetTelemetryBuilderWarningsForTests, resolveSessionId, saveCompoundState, slugifyId, telemetryCatalogV2Version, telemetryCatalogV3Version, telemetryCatalogVersion, tryBuildTelemetryEvent, tryEmitCourseStarted, validateId };
+export { ACCORDION_FORBIDDEN_CHILD_TYPES, ASSESSMENT_SEQUENCE_ALLOWED_CHILD_TYPES, type AccordionSectionToggledData, type AssessmentAnsweredData, type AssessmentBaseProps, type AssessmentBehaviour, type AssessmentCompletedData, type AssessmentHandle, type AssessmentInteractionType, type AssessmentPlugin, type AssessmentResumeState, type AssessmentScoreInput, type AssessmentScoreResult, type AssessmentXAPIData, type BlockId, type BookPageViewedData, type BuildTelemetryEventInput, COMPOUND_MAX_NESTING_DEPTH, COMPOUND_RESUME_SCHEMA_VERSION, type CheckId, type ClockPort, type CompoundBaseProps, type CompoundHandle, type CompoundPageViewedData, type CompoundParentType, type CompoundResumeInput, type CompoundResumeState, type CourseId, type CourseLifecycleContext, type CourseLifecycleDeps, type EmitContext, type FlashcardFlippedData, type HeadlessLessonkitConfig, type HeadlessLessonkitRuntime, type HeadlessRuntimePorts, type HotspotOpenedData, ID_MAX_LENGTH, ID_PATTERN, INTERACTIVE_BOOK_ALLOWED_CHILD_TYPES, type IdentityIdPath, type IdentityValidationIssue, type IdentityValidationResult, type ImageSliderChangedData, type InteractionBlockRegistration, type InteractionData, type InteractionPlugin, type LessonCompletionEmitter, type LessonId, type LessonLifecycleData, type LessonkitPlugin, type LessonkitPluginContext, type LessonkitPluginKind, type LessonkitRuntimeVersion, type LessonkitUrn, type LessonkitUrnParts, type LifecyclePlugin, PAGE_ALLOWED_CHILD_TYPES, type PluginHost, type PluginIdentity, type PluginRegistry, type ProgressController, type ProgressState, type QuizAnsweredData, type QuizCompletedData, SESSION_STORAGE_KEY, SLIDE_ALLOWED_CHILD_TYPES, SLIDE_DECK_ALLOWED_CHILD_TYPES, type SlideViewedData, type StoragePort, TELEMETRY_EVENT_CATALOG, TELEMETRY_EVENT_CATALOG_V2, TELEMETRY_EVENT_CATALOG_V3, type TelemetryBatchSink, type TelemetryCatalogEntry, type TelemetryCatalogV2Entry, type TelemetryCatalogV3Entry, type TelemetryDataFor, type TelemetryEmitFn, type TelemetryEvent, type TelemetryEventBase, type TelemetryEventName, type TelemetryPipeline, type TelemetryPipelineSink, type TelemetryPlugin, type TelemetrySink, type TelemetryUser, type TimerPort, type TrackingClient, assertNever, assertValidId, buildCourseStartedTelemetryEvent, buildLessonkitUrn, buildPluginContext, buildTelemetryCatalog, buildTelemetryCatalogV2, buildTelemetryCatalogV3, buildTelemetryEvent, clampCompoundPageIndex, clearCompoundState, completeCourseWithTelemetry, completeLessonWithTelemetry, compoundStateStorageKey, createCompoundResumeState, createDefaultClock, createGlobalTimer, createLessonkitRuntime, createNoopStorage, createPluginRegistry, createProgressController, createSessionId, createSessionStoragePort, createTelemetryPipeline, createTrackingClient, createTrackingPipelineSink, defineAssessmentPlugin, defineLifecyclePlugin, defineTelemetryPlugin, deriveId, getAllowedChildTypes, getTabSessionId, hasCourseStarted, hasCourseStartedEmittedToTracking, hasCourseStartedPipelineDelivered, isChildTypeAllowed, loadCompoundState, markCourseStarted, markCourseStartedEmittedToTracking, markCourseStartedPipelineDelivered, migrateCourseStartedMark, nowIso, parseBlockId, parseCheckId, parseCompoundResumeState, parseCourseId, parseLessonId, resetSharedVolatileSessionIdForTests, resetStoragePortForTests, resetTelemetryBuilderWarningsForTests, resolveSessionId, saveCompoundState, slugifyId, telemetryCatalogV2Version, telemetryCatalogV3Version, telemetryCatalogVersion, tryBuildTelemetryEvent, tryEmitCourseStarted, validateId };

package/dist/index.d.ts

@@ -92,7 +92,7 @@ type AssessmentBaseProps = AssessmentBehaviour & {
     passingScore?: number;
 };
 
-type TelemetryEventName = "course_started" | "course_completed" | "lesson_started" | "lesson_completed" | "lesson_time_on_task" | "quiz_answered" | "quiz_completed" | "assessment_answered" | "assessment_completed" | "interaction" | "book_page_viewed" | "compound_page_viewed" | "hotspot_opened" | "accordion_section_toggled" | "flashcard_flipped" | "image_slider_changed";
+type TelemetryEventName = "course_started" | "course_completed" | "lesson_started" | "lesson_completed" | "lesson_time_on_task" | "quiz_answered" | "quiz_completed" | "assessment_answered" | "assessment_completed" | "interaction" | "book_page_viewed" | "slide_viewed" | "compound_page_viewed" | "hotspot_opened" | "accordion_section_toggled" | "flashcard_flipped" | "image_slider_changed";
 type TelemetryUser = {
     id?: string;
     email?: string;
@@ -150,6 +150,11 @@ type BookPageViewedData = {
     pageIndex: number;
     pageTitle?: string;
 };
+type SlideViewedData = {
+    blockId: BlockId;
+    slideIndex: number;
+    slideTitle?: string;
+};
 type CompoundPageViewedData = {
     blockId: BlockId;
     pageIndex: number;
@@ -217,6 +222,10 @@ type TelemetryEvent = (TelemetryEventBase & {
     name: "book_page_viewed";
     lessonId: LessonId;
     data: BookPageViewedData;
+}) | (TelemetryEventBase & {
+    name: "slide_viewed";
+    lessonId: LessonId;
+    data: SlideViewedData;
 }) | (TelemetryEventBase & {
     name: "compound_page_viewed";
     lessonId: LessonId;
@@ -248,7 +257,8 @@ type TelemetrySink = (event: TelemetryEvent) => void | Promise<void>;
 type TelemetryBatchSink = (events: TelemetryEvent[]) => void | Promise<void>;
 type TrackingClient = {
     track: (event: TelemetryEvent) => void;
-    flush?: () => void | Promise<void>;
+    /** Resolves to true when all buffered events were delivered; false when a sink failure re-queued events. */
+    flush?: () => void | Promise<boolean>;
     dispose?: () => void | Promise<void>;
 };
 
@@ -289,7 +299,8 @@ type CompoundBaseProps = {
 
 type StoragePort = {
     getItem: (key: string) => string | null;
-    setItem: (key: string, value: string) => void;
+    /** Returns false when the value could not be durably persisted (e.g. sessionStorage quota). */
+    setItem: (key: string, value: string) => boolean;
     removeItem?: (key: string) => void;
     /** @internal Test helper to clear in-memory fallback state. */
     resetForTests?: () => void;
@@ -310,14 +321,17 @@ declare function createGlobalTimer(): TimerPort;
 
 declare function compoundStateStorageKey(courseId: CourseId, compoundId: BlockId): string;
 declare function loadCompoundState(storage: StoragePort, courseId: CourseId, compoundId: BlockId): CompoundResumeState | null;
-declare function saveCompoundState(storage: StoragePort, courseId: CourseId, compoundId: BlockId, state: CompoundResumeState): void;
+declare function saveCompoundState(storage: StoragePort, courseId: CourseId, compoundId: BlockId, state: CompoundResumeState): boolean;
 declare function clearCompoundState(storage: StoragePort, courseId: CourseId, compoundId: BlockId): void;
 
 /** Canonical compound child allowlists (H5P sub-content curation). */
 declare const PAGE_ALLOWED_CHILD_TYPES: readonly ["Text", "Heading", "Image", "Scenario", "Reflection", "Quiz", "KnowledgeCheck", "TrueFalse", "FillInTheBlanks", "DragAndDrop", "DragTheWords", "MarkTheWords", "Accordion", "DialogCards", "Flashcards", "ImageHotspots", "FindHotspot", "FindMultipleHotspots", "ImageSlider", "ProgressTracker"];
 declare const INTERACTIVE_BOOK_ALLOWED_CHILD_TYPES: readonly ["Page"];
+/** Per-slide content (H5P Course Presentation slide row). Excludes ProgressTracker. */
+declare const SLIDE_ALLOWED_CHILD_TYPES: readonly ["Text", "Heading", "Image", "Scenario", "Reflection", "Quiz", "KnowledgeCheck", "TrueFalse", "FillInTheBlanks", "DragAndDrop", "DragTheWords", "MarkTheWords", "Accordion", "DialogCards", "Flashcards", "ImageHotspots", "FindHotspot", "FindMultipleHotspots", "ImageSlider"];
+declare const SLIDE_DECK_ALLOWED_CHILD_TYPES: readonly ["Slide"];
 declare const ASSESSMENT_SEQUENCE_ALLOWED_CHILD_TYPES: readonly ["TrueFalse", "FillInTheBlanks", "DragAndDrop", "DragTheWords", "MarkTheWords", "Quiz", "KnowledgeCheck", "FindHotspot", "FindMultipleHotspots"];
-type CompoundParentType = "Page" | "InteractiveBook" | "AssessmentSequence";
+type CompoundParentType = "Page" | "InteractiveBook" | "Slide" | "SlideDeck" | "AssessmentSequence";
 declare const COMPOUND_MAX_NESTING_DEPTH: Record<CompoundParentType, number>;
 declare function getAllowedChildTypes(parent: CompoundParentType): readonly string[];
 declare function isChildTypeAllowed(parent: CompoundParentType, childType: string): boolean;
@@ -349,7 +363,7 @@ declare const TELEMETRY_EVENT_CATALOG_V2: TelemetryCatalogV2Entry[];
 declare function buildTelemetryCatalogV2(): TelemetryCatalogV2Entry[];
 
 declare const telemetryCatalogV3Version: 3;
-type TelemetryCatalogV3EventName = Extract<TelemetryEventName, "book_page_viewed" | "compound_page_viewed" | "hotspot_opened" | "accordion_section_toggled" | "flashcard_flipped" | "image_slider_changed">;
+type TelemetryCatalogV3EventName = Extract<TelemetryEventName, "book_page_viewed" | "slide_viewed" | "compound_page_viewed" | "hotspot_opened" | "accordion_section_toggled" | "flashcard_flipped" | "image_slider_changed">;
 type TelemetryCatalogV3Entry = {
     name: TelemetryCatalogV3EventName;
     description: string;
@@ -369,6 +383,8 @@ declare function createTrackingClient(opts?: {
         maxBatchSize?: number;
     };
     batchSink?: TelemetryBatchSink;
+    /** Called when an event is dropped because the batch buffer is at cap (including in production). */
+    onBufferDrop?: () => void;
 }): TrackingClient;
 
 declare function createSessionId(): string;
@@ -426,6 +442,10 @@ type BuildTelemetryEventInput = (BuildTelemetryEventContext & {
     name: "book_page_viewed";
     lessonId?: LessonId;
     data: BookPageViewedData;
+}) | (BuildTelemetryEventContext & {
+    name: "slide_viewed";
+    lessonId?: LessonId;
+    data: SlideViewedData;
 }) | (BuildTelemetryEventContext & {
     name: "compound_page_viewed";
     lessonId?: LessonId;
@@ -501,11 +521,13 @@ declare const SESSION_STORAGE_KEY = "lessonkit:sessionId";
 declare function getTabSessionId(storage: StoragePort): string | null;
 declare function resolveSessionId(storage: StoragePort, provided?: string): string;
 declare function hasCourseStarted(storage: StoragePort, sessionId: string, courseId?: CourseId): boolean;
-declare function markCourseStarted(storage: StoragePort, sessionId: string, courseId?: CourseId): void;
+declare function markCourseStarted(storage: StoragePort, sessionId: string, courseId?: CourseId): boolean;
 declare function hasCourseStartedEmittedToTracking(storage: StoragePort, sessionId: string, courseId?: CourseId): boolean;
 declare function markCourseStartedEmittedToTracking(storage: StoragePort, sessionId: string, courseId?: CourseId): void;
 declare function hasCourseStartedPipelineDelivered(storage: StoragePort, sessionId: string, courseId?: CourseId): boolean;
 declare function markCourseStartedPipelineDelivered(storage: StoragePort, sessionId: string, courseId?: CourseId): void;
+/** @internal Reset shared volatile session id between tests. */
+declare function resetSharedVolatileSessionIdForTests(): void;
 declare function migrateCourseStartedMark(storage: StoragePort, fromSessionId: string, toSessionId: string, courseId?: CourseId): void;
 
 /** Plugin category — aligns with roadmap extension areas. */
@@ -623,6 +645,8 @@ type HeadlessLessonkitConfig = {
     };
     /** Plugin list or registry; hooks run on {@link HeadlessLessonkitRuntime.track} and lifecycle emits. */
     plugins?: HeadlessLessonkitPlugins;
+    /** When true, skip initial {@link PluginHost.setupAll}; host caller runs setup (React v2 provider). */
+    deferPluginSetup?: boolean;
 };
 type HeadlessRuntimePorts = {
     storage?: StoragePort;
@@ -668,4 +692,4 @@ declare function buildPluginContext(opts: {
     user?: TelemetryUser;
 }): LessonkitPluginContext;
 
-export { ACCORDION_FORBIDDEN_CHILD_TYPES, ASSESSMENT_SEQUENCE_ALLOWED_CHILD_TYPES, type AccordionSectionToggledData, type AssessmentAnsweredData, type AssessmentBaseProps, type AssessmentBehaviour, type AssessmentCompletedData, type AssessmentHandle, type AssessmentInteractionType, type AssessmentPlugin, type AssessmentResumeState, type AssessmentScoreInput, type AssessmentScoreResult, type AssessmentXAPIData, type BlockId, type BookPageViewedData, type BuildTelemetryEventInput, COMPOUND_MAX_NESTING_DEPTH, COMPOUND_RESUME_SCHEMA_VERSION, type CheckId, type ClockPort, type CompoundBaseProps, type CompoundHandle, type CompoundPageViewedData, type CompoundParentType, type CompoundResumeInput, type CompoundResumeState, type CourseId, type CourseLifecycleContext, type CourseLifecycleDeps, type EmitContext, type FlashcardFlippedData, type HeadlessLessonkitConfig, type HeadlessLessonkitRuntime, type HeadlessRuntimePorts, type HotspotOpenedData, ID_MAX_LENGTH, ID_PATTERN, INTERACTIVE_BOOK_ALLOWED_CHILD_TYPES, type IdentityIdPath, type IdentityValidationIssue, type IdentityValidationResult, type ImageSliderChangedData, type InteractionBlockRegistration, type InteractionData, type InteractionPlugin, type LessonCompletionEmitter, type LessonId, type LessonLifecycleData, type LessonkitPlugin, type LessonkitPluginContext, type LessonkitPluginKind, type LessonkitRuntimeVersion, type LessonkitUrn, type LessonkitUrnParts, type LifecyclePlugin, PAGE_ALLOWED_CHILD_TYPES, type PluginHost, type PluginIdentity, type PluginRegistry, type ProgressController, type ProgressState, type QuizAnsweredData, type QuizCompletedData, SESSION_STORAGE_KEY, type StoragePort, TELEMETRY_EVENT_CATALOG, TELEMETRY_EVENT_CATALOG_V2, TELEMETRY_EVENT_CATALOG_V3, type TelemetryBatchSink, type TelemetryCatalogEntry, type TelemetryCatalogV2Entry, type TelemetryCatalogV3Entry, type TelemetryDataFor, type TelemetryEmitFn, type TelemetryEvent, type TelemetryEventBase, type TelemetryEventName, type TelemetryPipeline, type TelemetryPipelineSink, type TelemetryPlugin, type TelemetrySink, type TelemetryUser, type TimerPort, type TrackingClient, assertNever, assertValidId, buildCourseStartedTelemetryEvent, buildLessonkitUrn, buildPluginContext, buildTelemetryCatalog, buildTelemetryCatalogV2, buildTelemetryCatalogV3, buildTelemetryEvent, clampCompoundPageIndex, clearCompoundState, completeCourseWithTelemetry, completeLessonWithTelemetry, compoundStateStorageKey, createCompoundResumeState, createDefaultClock, createGlobalTimer, createLessonkitRuntime, createNoopStorage, createPluginRegistry, createProgressController, createSessionId, createSessionStoragePort, createTelemetryPipeline, createTrackingClient, createTrackingPipelineSink, defineAssessmentPlugin, defineLifecyclePlugin, defineTelemetryPlugin, deriveId, getAllowedChildTypes, getTabSessionId, hasCourseStarted, hasCourseStartedEmittedToTracking, hasCourseStartedPipelineDelivered, isChildTypeAllowed, loadCompoundState, markCourseStarted, markCourseStartedEmittedToTracking, markCourseStartedPipelineDelivered, migrateCourseStartedMark, nowIso, parseBlockId, parseCheckId, parseCompoundResumeState, parseCourseId, parseLessonId, resetStoragePortForTests, resetTelemetryBuilderWarningsForTests, resolveSessionId, saveCompoundState, slugifyId, telemetryCatalogV2Version, telemetryCatalogV3Version, telemetryCatalogVersion, tryBuildTelemetryEvent, tryEmitCourseStarted, validateId };
+export { ACCORDION_FORBIDDEN_CHILD_TYPES, ASSESSMENT_SEQUENCE_ALLOWED_CHILD_TYPES, type AccordionSectionToggledData, type AssessmentAnsweredData, type AssessmentBaseProps, type AssessmentBehaviour, type AssessmentCompletedData, type AssessmentHandle, type AssessmentInteractionType, type AssessmentPlugin, type AssessmentResumeState, type AssessmentScoreInput, type AssessmentScoreResult, type AssessmentXAPIData, type BlockId, type BookPageViewedData, type BuildTelemetryEventInput, COMPOUND_MAX_NESTING_DEPTH, COMPOUND_RESUME_SCHEMA_VERSION, type CheckId, type ClockPort, type CompoundBaseProps, type CompoundHandle, type CompoundPageViewedData, type CompoundParentType, type CompoundResumeInput, type CompoundResumeState, type CourseId, type CourseLifecycleContext, type CourseLifecycleDeps, type EmitContext, type FlashcardFlippedData, type HeadlessLessonkitConfig, type HeadlessLessonkitRuntime, type HeadlessRuntimePorts, type HotspotOpenedData, ID_MAX_LENGTH, ID_PATTERN, INTERACTIVE_BOOK_ALLOWED_CHILD_TYPES, type IdentityIdPath, type IdentityValidationIssue, type IdentityValidationResult, type ImageSliderChangedData, type InteractionBlockRegistration, type InteractionData, type InteractionPlugin, type LessonCompletionEmitter, type LessonId, type LessonLifecycleData, type LessonkitPlugin, type LessonkitPluginContext, type LessonkitPluginKind, type LessonkitRuntimeVersion, type LessonkitUrn, type LessonkitUrnParts, type LifecyclePlugin, PAGE_ALLOWED_CHILD_TYPES, type PluginHost, type PluginIdentity, type PluginRegistry, type ProgressController, type ProgressState, type QuizAnsweredData, type QuizCompletedData, SESSION_STORAGE_KEY, SLIDE_ALLOWED_CHILD_TYPES, SLIDE_DECK_ALLOWED_CHILD_TYPES, type SlideViewedData, type StoragePort, TELEMETRY_EVENT_CATALOG, TELEMETRY_EVENT_CATALOG_V2, TELEMETRY_EVENT_CATALOG_V3, type TelemetryBatchSink, type TelemetryCatalogEntry, type TelemetryCatalogV2Entry, type TelemetryCatalogV3Entry, type TelemetryDataFor, type TelemetryEmitFn, type TelemetryEvent, type TelemetryEventBase, type TelemetryEventName, type TelemetryPipeline, type TelemetryPipelineSink, type TelemetryPlugin, type TelemetrySink, type TelemetryUser, type TimerPort, type TrackingClient, assertNever, assertValidId, buildCourseStartedTelemetryEvent, buildLessonkitUrn, buildPluginContext, buildTelemetryCatalog, buildTelemetryCatalogV2, buildTelemetryCatalogV3, buildTelemetryEvent, clampCompoundPageIndex, clearCompoundState, completeCourseWithTelemetry, completeLessonWithTelemetry, compoundStateStorageKey, createCompoundResumeState, createDefaultClock, createGlobalTimer, createLessonkitRuntime, createNoopStorage, createPluginRegistry, createProgressController, createSessionId, createSessionStoragePort, createTelemetryPipeline, createTrackingClient, createTrackingPipelineSink, defineAssessmentPlugin, defineLifecyclePlugin, defineTelemetryPlugin, deriveId, getAllowedChildTypes, getTabSessionId, hasCourseStarted, hasCourseStartedEmittedToTracking, hasCourseStartedPipelineDelivered, isChildTypeAllowed, loadCompoundState, markCourseStarted, markCourseStartedEmittedToTracking, markCourseStartedPipelineDelivered, migrateCourseStartedMark, nowIso, parseBlockId, parseCheckId, parseCompoundResumeState, parseCourseId, parseLessonId, resetSharedVolatileSessionIdForTests, resetStoragePortForTests, resetTelemetryBuilderWarningsForTests, resolveSessionId, saveCompoundState, slugifyId, telemetryCatalogV2Version, telemetryCatalogV3Version, telemetryCatalogVersion, tryBuildTelemetryEvent, tryEmitCourseStarted, validateId };

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
@@ -122,6 +141,27 @@ 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;
@@ -130,7 +170,7 @@ function parseCompoundResumeState(raw) {
   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)) {
+      if (isPlainSerializableChildState(value)) {
         childStates[key] = value;
       }
     }
@@ -144,22 +184,40 @@ function parseCompoundResumeState(raw) {
   };
 }
 
+// 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 raw = storage.getItem(compoundStateStorageKey(courseId, compoundId));
+  const key = compoundStateStorageKey(courseId, compoundId);
+  const raw = storage.getItem(key);
   if (!raw) return null;
   try {
-    return parseCompoundResumeState(JSON.parse(raw));
+    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) {
-  storage.setItem(compoundStateStorageKey(courseId, compoundId), JSON.stringify(state));
+  return storage.setItem(compoundStateStorageKey(courseId, compoundId), JSON.stringify(state));
 }
 function clearCompoundState(storage, courseId, compoundId) {
   storage.removeItem?.(compoundStateStorageKey(courseId, compoundId));
@@ -189,6 +247,28 @@ var PAGE_ALLOWED_CHILD_TYPES = [
   "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",
@@ -203,11 +283,15 @@ var ASSESSMENT_SEQUENCE_ALLOWED_CHILD_TYPES = [
 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) {
@@ -325,6 +409,14 @@ var TELEMETRY_EVENT_CATALOG_V3 = [
     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",
@@ -370,16 +462,6 @@ 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;
@@ -444,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;
@@ -487,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();
@@ -651,6 +751,20 @@ var TELEMETRY_EVENT_REGISTRY = {
       };
     }
   },
+  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("slide_viewed requires active lessonId");
+      return {
+        name: "slide_viewed",
+        ...base,
+        lessonId,
+        data: opts.data
+      };
+    }
+  },
   compound_page_viewed: {
     requiresLessonId: true,
     build: (opts, base) => {
@@ -799,8 +913,7 @@ function createDefaultClock() {
 function createNoopStorage() {
   return {
     getItem: () => null,
-    setItem: () => {
-    }
+    setItem: () => true
   };
 }
 function createMemoryBackedSessionStorage(session) {
@@ -831,8 +944,10 @@ function createMemoryBackedSessionStorage(session) {
       memory.set(key, value);
       try {
         session.setItem(key, value);
+        return true;
       } catch {
         warnPersistFailure();
+        return false;
       }
     },
     removeItem: (key) => {
@@ -857,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);
@@ -909,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;
@@ -929,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);
 }
@@ -936,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) {
@@ -957,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;
@@ -976,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)) {
@@ -998,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({
@@ -1095,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) {
@@ -1166,6 +1313,9 @@ function createLessonkitRuntime(config, ports = {}) {
     attemptId,
     user
   });
+  if (!configSnapshot.deferPluginSetup) {
+    pluginHost?.setupAll(getPluginCtx());
+  }
   const getSession = () => ({ sessionId, attemptId, user });
   const syncSessionFromConfig = (next) => {
     sessionId = resolveSessionId(storage, next.session?.sessionId);
@@ -1225,11 +1375,8 @@ function createLessonkitRuntime(config, ports = {}) {
     getProgressState: () => progress.getState(),
     getSession,
     updateConfig(next) {
-      if (next.plugins !== void 0 && next.plugins !== pluginHost) {
-        pluginHost?.disposeAll();
-        configSnapshot.plugins = next.plugins;
-        pluginHost = resolvePluginHost(configSnapshot.plugins);
-      }
+      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();
@@ -1239,6 +1386,19 @@ function createLessonkitRuntime(config, ports = {}) {
         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);
@@ -1310,6 +1470,8 @@ export {
   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,
@@ -1360,6 +1522,7 @@ export {
   parseCompoundResumeState,
   parseCourseId,
   parseLessonId,
+  resetSharedVolatileSessionIdForTests,
   resetStoragePortForTests,
   resetTelemetryBuilderWarningsForTests,
   resolveSessionId,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lessonkit/core",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "private": false,
   "description": "Shared types and telemetry primitives for LessonKit.",
   "license": "Apache-2.0",

package/telemetry-catalog.v3.json

@@ -9,6 +9,14 @@
       "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",