@lessonkit/core 1.5.0 → 1.6.0

package/dist/index.js

@@ -36,7 +36,7 @@ import {
   tryEmitCourseStarted,
   validateId,
   warnDev
-} from "./chunk-KFXFQ6B2.js";
+} from "./chunk-NGCHHJSM.js";
 
 // src/assertNever.ts
 function assertNever(value, message = "Unexpected value") {
@@ -117,7 +117,7 @@ function buildLessonkitUrn(parts) {
     urn += `:block:${blockId}`;
   }
   if (parts.nodeId !== void 0) {
-    const nodeId = assertValidId(parts.nodeId, "blockId");
+    const nodeId = assertValidId(parts.nodeId, "nodeId");
     if (parts.blockId === void 0) {
       throw new Error("buildLessonkitUrn: nodeId requires blockId");
     }
@@ -187,9 +187,11 @@ function parseCompoundResumeState(raw, opts) {
     opts?.onDroppedChildKeys?.(droppedChildKeys);
   }
   const activeChapterIndex = typeof obj.activeChapterIndex === "number" && Number.isFinite(obj.activeChapterIndex) ? obj.activeChapterIndex : void 0;
+  const rawPageIndex = Math.max(0, Math.floor(obj.activePageIndex));
+  const activePageIndex = typeof opts?.pageCount === "number" && opts.pageCount > 0 ? clampCompoundPageIndex(rawPageIndex, opts.pageCount) : rawPageIndex;
   return {
     schemaVersion: COMPOUND_RESUME_SCHEMA_VERSION,
-    activePageIndex: Math.max(0, Math.floor(obj.activePageIndex)),
+    activePageIndex,
     ...activeChapterIndex !== void 0 ? { activeChapterIndex: Math.max(0, Math.floor(activeChapterIndex)) } : {},
     childStates
   };
@@ -273,6 +275,16 @@ var PAGE_ALLOWED_CHILD_TYPES = [
   "ImageSlider",
   "Embed",
   "Chart",
+  "Table",
+  "ImageJuxtaposition",
+  "Timeline",
+  "ImageSequence",
+  "Collage",
+  "AudioRecorder",
+  "CombinationLock",
+  "QrContent",
+  "Crossword",
+  "AdventCalendar",
   "ProgressTracker"
 ];
 var BRANCH_NODE_ALLOWED_CHILD_TYPES = [
@@ -307,9 +319,64 @@ var BRANCH_NODE_ALLOWED_CHILD_TYPES = [
   "ImageSlider",
   "Embed",
   "Chart",
+  "Table",
+  "ImageJuxtaposition",
+  "Timeline",
+  "ImageSequence",
+  "Collage",
+  "AudioRecorder",
+  "CombinationLock",
+  "QrContent",
+  "Crossword",
+  "AdventCalendar",
   "BranchChoice"
 ];
 var BRANCHING_SCENARIO_ALLOWED_CHILD_TYPES = ["BranchNode"];
+var GAME_MAP_ALLOWED_CHILD_TYPES = ["MapStage"];
+var MAP_STAGE_ALLOWED_CHILD_TYPES = [
+  "Text",
+  "Heading",
+  "Image",
+  "Video",
+  "Scenario",
+  "Reflection",
+  "Quiz",
+  "KnowledgeCheck",
+  "TrueFalse",
+  "FillInTheBlanks",
+  "DragAndDrop",
+  "DragTheWords",
+  "MarkTheWords",
+  "Summary",
+  "ImagePairing",
+  "ImageSequencing",
+  "MemoryGame",
+  "InformationWall",
+  "ParallaxSlideshow",
+  "Questionnaire",
+  "Essay",
+  "ArithmeticQuiz",
+  "Accordion",
+  "DialogCards",
+  "Flashcards",
+  "ImageHotspots",
+  "FindHotspot",
+  "FindMultipleHotspots",
+  "ImageSlider",
+  "Embed",
+  "Chart",
+  "Table",
+  "ImageJuxtaposition",
+  "Timeline",
+  "ImageSequence",
+  "Collage",
+  "AudioRecorder",
+  "CombinationLock",
+  "QrContent",
+  "Crossword",
+  "AdventCalendar",
+  "MapExit"
+];
 var INTERACTIVE_BOOK_ALLOWED_CHILD_TYPES = ["Page"];
 var SLIDE_ALLOWED_CHILD_TYPES = [
   "Text",
@@ -342,7 +409,17 @@ var SLIDE_ALLOWED_CHILD_TYPES = [
   "FindMultipleHotspots",
   "ImageSlider",
   "Embed",
-  "Chart"
+  "Chart",
+  "Table",
+  "ImageJuxtaposition",
+  "Timeline",
+  "ImageSequence",
+  "Collage",
+  "AudioRecorder",
+  "CombinationLock",
+  "QrContent",
+  "Crossword",
+  "AdventCalendar"
 ];
 var SLIDE_DECK_ALLOWED_CHILD_TYPES = ["Slide"];
 var TIMED_CUE_ALLOWED_CHILD_TYPES = [
@@ -386,7 +463,9 @@ var ALLOWLISTS = {
   InteractiveVideo: INTERACTIVE_VIDEO_ALLOWED_CHILD_TYPES,
   AssessmentSequence: ASSESSMENT_SEQUENCE_ALLOWED_CHILD_TYPES,
   BranchingScenario: BRANCHING_SCENARIO_ALLOWED_CHILD_TYPES,
-  BranchNode: BRANCH_NODE_ALLOWED_CHILD_TYPES
+  BranchNode: BRANCH_NODE_ALLOWED_CHILD_TYPES,
+  GameMap: GAME_MAP_ALLOWED_CHILD_TYPES,
+  MapStage: MAP_STAGE_ALLOWED_CHILD_TYPES
 };
 var COMPOUND_MAX_NESTING_DEPTH = {
   Page: 1,
@@ -397,7 +476,9 @@ var COMPOUND_MAX_NESTING_DEPTH = {
   InteractiveVideo: 2,
   AssessmentSequence: 1,
   BranchingScenario: 2,
-  BranchNode: 1
+  BranchNode: 1,
+  GameMap: 2,
+  MapStage: 1
 };
 function getAllowedChildTypes(parent) {
   return ALLOWLISTS[parent];
@@ -702,6 +783,78 @@ var TELEMETRY_EVENT_CATALOG_V3 = [
     dataFields: ["blockId", "fromNodeId", "toNodeId", "label", "scoreWeight"],
     xapiVerb: "http://adlnet.gov/expapi/verbs/answered",
     urnPattern: "urn:lessonkit:course:{courseId}:lesson:{lessonId}:block:{blockId}:node:{toNodeId}"
+  },
+  {
+    name: "image_juxtaposition_changed",
+    description: "Learner adjusted the before/after divider",
+    requiredFields: ["courseId", "sessionId", "timestamp"],
+    dataFields: ["blockId", "position"],
+    xapiVerb: "http://adlnet.gov/expapi/verbs/interacted",
+    urnPattern: "urn:lessonkit:course:{courseId}:lesson:{lessonId}:block:{blockId}"
+  },
+  {
+    name: "timeline_event_viewed",
+    description: "Learner focused a timeline event",
+    requiredFields: ["courseId", "sessionId", "timestamp"],
+    dataFields: ["blockId", "eventId"],
+    xapiVerb: "http://adlnet.gov/expapi/verbs/experienced",
+    urnPattern: "urn:lessonkit:course:{courseId}:lesson:{lessonId}:block:{blockId}"
+  },
+  {
+    name: "image_sequence_changed",
+    description: "Learner changed the image sequence frame",
+    requiredFields: ["courseId", "sessionId", "timestamp"],
+    dataFields: ["blockId", "frameIndex"],
+    xapiVerb: "http://adlnet.gov/expapi/verbs/interacted",
+    urnPattern: "urn:lessonkit:course:{courseId}:lesson:{lessonId}:block:{blockId}"
+  },
+  {
+    name: "audio_recording_started",
+    description: "Learner started an audio recording",
+    requiredFields: ["courseId", "sessionId", "timestamp"],
+    dataFields: ["blockId"],
+    xapiVerb: "http://adlnet.gov/expapi/verbs/interacted",
+    urnPattern: "urn:lessonkit:course:{courseId}:lesson:{lessonId}:block:{blockId}"
+  },
+  {
+    name: "audio_recording_completed",
+    description: "Learner completed an audio recording",
+    requiredFields: ["courseId", "sessionId", "timestamp"],
+    dataFields: ["blockId"],
+    xapiVerb: "http://adlnet.gov/expapi/verbs/completed",
+    urnPattern: "urn:lessonkit:course:{courseId}:lesson:{lessonId}:block:{blockId}"
+  },
+  {
+    name: "qr_content_revealed",
+    description: "Learner revealed QR hidden content",
+    requiredFields: ["courseId", "sessionId", "timestamp"],
+    dataFields: ["blockId"],
+    xapiVerb: "http://adlnet.gov/expapi/verbs/experienced",
+    urnPattern: "urn:lessonkit:course:{courseId}:lesson:{lessonId}:block:{blockId}"
+  },
+  {
+    name: "advent_door_opened",
+    description: "Learner opened an advent calendar door",
+    requiredFields: ["courseId", "sessionId", "timestamp"],
+    dataFields: ["blockId", "doorId", "day"],
+    xapiVerb: "http://adlnet.gov/expapi/verbs/interacted",
+    urnPattern: "urn:lessonkit:course:{courseId}:lesson:{lessonId}:block:{blockId}"
+  },
+  {
+    name: "map_stage_viewed",
+    description: "Learner viewed a stage in a GameMap",
+    requiredFields: ["courseId", "lessonId", "sessionId", "timestamp"],
+    dataFields: ["blockId", "stageId", "stageIndex", "stageLabel"],
+    xapiVerb: "http://adlnet.gov/expapi/verbs/experienced",
+    urnPattern: "urn:lessonkit:course:{courseId}:lesson:{lessonId}:block:{blockId}:stage:{stageId}"
+  },
+  {
+    name: "map_exit_selected",
+    description: "Learner selected a map exit in a GameMap",
+    requiredFields: ["courseId", "lessonId", "sessionId", "timestamp"],
+    dataFields: ["blockId", "fromStageId", "toStageId", "label", "scoreWeight"],
+    xapiVerb: "http://adlnet.gov/expapi/verbs/answered",
+    urnPattern: "urn:lessonkit:course:{courseId}:lesson:{lessonId}:block:{blockId}:stage:{toStageId}"
   }
 ];
 function buildTelemetryCatalogV3() {
@@ -798,6 +951,10 @@ function createTrackingClient(opts) {
   const runFlush = () => {
     if (!buffer.length) return Promise.resolve(true);
     const events = buffer.splice(0, buffer.length);
+    for (const event of events) {
+      const key = eventDedupKey(event);
+      if (key) pendingDeliverIds.add(key);
+    }
     let succeeded = false;
     return Promise.resolve().then(async () => {
       if (batchSink) {
@@ -807,7 +964,7 @@ function createTrackingClient(opts) {
           try {
             await sink?.(events[i]);
           } catch {
-            buffer.unshift(...events.slice(i));
+            buffer.unshift(...events);
             return;
           }
         }
@@ -1142,6 +1299,10 @@ function resolvePluginHost(plugins) {
   if (Array.isArray(plugins) && plugins.length > 0) return createPluginRegistry(plugins);
   return null;
 }
+function pluginListFingerprint(plugins) {
+  if (!plugins || !Array.isArray(plugins)) return null;
+  return plugins.map((p) => `${p.id}\0${p.version ?? ""}`).join("\n");
+}
 function warnRuntimeV1Deprecated() {
   const g = globalThis;
   if (typeof g.process !== "undefined" && g.process.env?.NODE_ENV === "production") return;
@@ -1154,12 +1315,19 @@ function createLessonkitRuntime(config, ports = {}) {
   const storage = ports.storage ?? createSessionStoragePort();
   const clock = ports.clock ?? createDefaultClock();
   const configSnapshot = { ...config };
+  const hasExplicitSessionId = Boolean(configSnapshot.session?.sessionId?.trim());
+  let autoSessionId;
   let sessionId = resolveSessionId(storage, configSnapshot.session?.sessionId);
+  if (!hasExplicitSessionId) {
+    autoSessionId = sessionId;
+  }
   let attemptId = configSnapshot.session?.attemptId;
   let user = configSnapshot.session?.user;
   let courseId = configSnapshot.courseId;
+  let configuredSessionId = configSnapshot.session?.sessionId;
   let progress = createProgressController();
   let pluginHost = resolvePluginHost(configSnapshot.plugins);
+  let pluginFingerprint = pluginListFingerprint(configSnapshot.plugins);
   let disposed = false;
   const getPluginCtx = () => buildPluginContext({
     courseId,
@@ -1171,12 +1339,6 @@ function createLessonkitRuntime(config, ports = {}) {
     pluginHost?.setupAll(getPluginCtx());
   }
   const getSession = () => ({ sessionId, attemptId, user });
-  const syncSessionFromConfig = (next) => {
-    sessionId = resolveSessionId(storage, next.session?.sessionId);
-    attemptId = next.session?.attemptId;
-    user = next.session?.user;
-    courseId = next.courseId;
-  };
   const applyPluginsToEvent = (event) => {
     if (!pluginHost) return event;
     return pluginHost.runTelemetry(event, getPluginCtx());
@@ -1198,7 +1360,6 @@ function createLessonkitRuntime(config, ports = {}) {
     const event = buildAndApply(name, data, lessonId);
     if (event) emitFn(event);
   };
-  syncSessionFromConfig(configSnapshot);
   const track = (name, data, emit, lessonId) => {
     if (disposed) return;
     const event = buildAndApply(name, data, lessonId);
@@ -1240,21 +1401,52 @@ function createLessonkitRuntime(config, ports = {}) {
       if (next.autoCompleteOnLessonSwitch !== void 0) {
         configSnapshot.autoCompleteOnLessonSwitch = next.autoCompleteOnLessonSwitch;
       }
+      if (next.courseId !== void 0) {
+        courseId = next.courseId;
+      }
       if (next.session !== void 0) {
+        const previousSessionId = sessionId;
         configSnapshot.session = { ...configSnapshot.session, ...next.session };
+        const explicitSessionId = configSnapshot.session?.sessionId?.trim();
+        if (explicitSessionId) {
+          sessionId = resolveSessionId(storage, explicitSessionId);
+          autoSessionId = void 0;
+        } else {
+          sessionId = autoSessionId ?? resolveSessionId(storage, void 0);
+          if (!autoSessionId) autoSessionId = sessionId;
+        }
+        attemptId = configSnapshot.session?.attemptId;
+        user = configSnapshot.session?.user;
+        if (previousSessionId !== sessionId) {
+          const prevExplicit = configuredSessionId?.trim();
+          const nextExplicit = configSnapshot.session?.sessionId?.trim();
+          const isExplicitLearnerSwap = Boolean(prevExplicit) && Boolean(nextExplicit) && prevExplicit !== nextExplicit;
+          if (!isExplicitLearnerSwap) {
+            migrateCourseStartedMark(storage, previousSessionId, sessionId, courseId);
+          }
+        }
+        configuredSessionId = configSnapshot.session?.sessionId;
       }
-      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 !== configSnapshot.plugins) {
-        pluginHost?.disposeAll();
-        configSnapshot.plugins = next.plugins;
-        pluginHost = resolvePluginHost(configSnapshot.plugins);
         if (!configSnapshot.deferPluginSetup) {
+          pluginHost?.disposeAll();
           pluginHost?.setupAll(getPluginCtx());
         }
+      }
+      if (next.plugins !== void 0) {
+        const nextFingerprint = pluginListFingerprint(next.plugins);
+        const pluginsChanged = next.plugins !== configSnapshot.plugins || nextFingerprint !== null && nextFingerprint !== pluginFingerprint;
+        if (pluginsChanged) {
+          pluginHost?.disposeAll();
+          configSnapshot.plugins = next.plugins;
+          pluginFingerprint = nextFingerprint;
+          pluginHost = resolvePluginHost(configSnapshot.plugins);
+          if (!configSnapshot.deferPluginSetup) {
+            pluginHost?.setupAll(getPluginCtx());
+          }
+        }
       } else if (next.session !== void 0 && sessionKeyBefore !== sessionKeyAfter && pluginHost && !configSnapshot.deferPluginSetup) {
         pluginHost.disposeAll();
         pluginHost.setupAll(getPluginCtx());
@@ -1309,15 +1501,17 @@ function createLessonkitRuntime(config, ports = {}) {
       configSnapshot.courseId = nextCourseId;
       courseId = nextCourseId;
       progress = createProgressController();
-      pluginHost?.disposeAll();
       if (!configSnapshot.deferPluginSetup) {
+        pluginHost?.disposeAll();
         pluginHost?.setupAll(getPluginCtx());
       }
     },
     dispose() {
       if (disposed) return;
       disposed = true;
-      pluginHost?.disposeAll();
+      if (!configSnapshot.deferPluginSetup) {
+        pluginHost?.disposeAll();
+      }
     }
   };
 }
@@ -1340,10 +1534,12 @@ export {
   BRANCH_NODE_ALLOWED_CHILD_TYPES,
   COMPOUND_MAX_NESTING_DEPTH,
   COMPOUND_RESUME_SCHEMA_VERSION,
+  GAME_MAP_ALLOWED_CHILD_TYPES,
   ID_MAX_LENGTH,
   ID_PATTERN,
   INTERACTIVE_BOOK_ALLOWED_CHILD_TYPES,
   INTERACTIVE_VIDEO_ALLOWED_CHILD_TYPES,
+  MAP_STAGE_ALLOWED_CHILD_TYPES,
   PAGE_ALLOWED_CHILD_TYPES,
   SESSION_STORAGE_KEY,
   SLIDE_ALLOWED_CHILD_TYPES,

package/dist/{testing-BFr8oEfw.d.cts → testing-CzgxF1Ru.d.cts}

@@ -21,7 +21,7 @@ declare const ID_PATTERN: RegExp;
 declare const ID_MAX_LENGTH = 64;
 
 /** H5P-aligned interaction kinds for assessment telemetry and xAPI. */
-type AssessmentInteractionType = "mcq" | "trueFalse" | "fillInBlanks" | "markTheWords" | "dragTheWords" | "dragAndDrop" | "assessmentSequence" | "findHotspot" | "findMultipleHotspots" | "summary" | "imagePairing" | "imageSequencing" | "essay" | "arithmeticQuiz" | "memoryGame";
+type AssessmentInteractionType = "mcq" | "trueFalse" | "fillInBlanks" | "markTheWords" | "dragTheWords" | "dragAndDrop" | "assessmentSequence" | "findHotspot" | "findMultipleHotspots" | "summary" | "imagePairing" | "imageSequencing" | "essay" | "arithmeticQuiz" | "memoryGame" | "combinationLock" | "crossword" | "wordSearch";
 /** Serializable resume blob for a single assessment block. */
 type AssessmentResumeState = Record<string, unknown>;
 /** Behaviour flags aligned with H5P question types. */
@@ -65,7 +65,7 @@ type McqAssessmentProps = AssessmentBaseProps & {
     answer: string;
 };
 
-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" | "video_cue_reached" | "video_segment_completed" | "memory_card_flipped" | "information_wall_search" | "parallax_slide_viewed" | "questionnaire_submitted" | "branch_node_viewed" | "branch_selected";
+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" | "video_cue_reached" | "video_segment_completed" | "memory_card_flipped" | "information_wall_search" | "parallax_slide_viewed" | "questionnaire_submitted" | "branch_node_viewed" | "branch_selected" | "image_juxtaposition_changed" | "timeline_event_viewed" | "image_sequence_changed" | "audio_recording_started" | "audio_recording_completed" | "qr_content_revealed" | "advent_door_opened" | "map_stage_viewed" | "map_exit_selected";
 type TelemetryUser = {
     id?: string;
     email?: string;
@@ -196,6 +196,42 @@ type BranchSelectedData = {
     label: string;
     scoreWeight?: number;
 };
+type ImageJuxtapositionChangedData = {
+    blockId: BlockId;
+    position: number;
+};
+type TimelineEventViewedData = {
+    blockId: BlockId;
+    eventId: string;
+};
+type ImageSequenceChangedData = {
+    blockId: BlockId;
+    frameIndex: number;
+};
+type AudioRecordingData = {
+    blockId: BlockId;
+};
+type QrContentRevealedData = {
+    blockId: BlockId;
+};
+type AdventDoorOpenedData = {
+    blockId: BlockId;
+    doorId: string;
+    day: number;
+};
+type MapStageViewedData = {
+    blockId: BlockId;
+    stageId: string;
+    stageIndex: number;
+    stageLabel?: string;
+};
+type MapExitSelectedData = {
+    blockId: BlockId;
+    fromStageId: string;
+    toStageId: string;
+    label: string;
+    scoreWeight?: number;
+};
 type TelemetryEvent = (TelemetryEventBase & {
     name: "course_started";
     lessonId?: LessonId;
@@ -296,6 +332,42 @@ type TelemetryEvent = (TelemetryEventBase & {
     name: "branch_selected";
     lessonId: LessonId;
     data: BranchSelectedData;
+}) | (TelemetryEventBase & {
+    name: "image_juxtaposition_changed";
+    lessonId?: LessonId;
+    data: ImageJuxtapositionChangedData;
+}) | (TelemetryEventBase & {
+    name: "timeline_event_viewed";
+    lessonId?: LessonId;
+    data: TimelineEventViewedData;
+}) | (TelemetryEventBase & {
+    name: "image_sequence_changed";
+    lessonId?: LessonId;
+    data: ImageSequenceChangedData;
+}) | (TelemetryEventBase & {
+    name: "audio_recording_started";
+    lessonId?: LessonId;
+    data: AudioRecordingData;
+}) | (TelemetryEventBase & {
+    name: "audio_recording_completed";
+    lessonId?: LessonId;
+    data: AudioRecordingData;
+}) | (TelemetryEventBase & {
+    name: "qr_content_revealed";
+    lessonId?: LessonId;
+    data: QrContentRevealedData;
+}) | (TelemetryEventBase & {
+    name: "advent_door_opened";
+    lessonId?: LessonId;
+    data: AdventDoorOpenedData;
+}) | (TelemetryEventBase & {
+    name: "map_stage_viewed";
+    lessonId: LessonId;
+    data: MapStageViewedData;
+}) | (TelemetryEventBase & {
+    name: "map_exit_selected";
+    lessonId: LessonId;
+    data: MapExitSelectedData;
 });
 /** Payload shape for a telemetry event name. */
 type TelemetryDataFor<N extends TelemetryEventName> = Extract<TelemetryEvent, {
@@ -446,6 +518,42 @@ type BuildTelemetryEventInput = (BuildTelemetryEventContext & {
     name: "branch_selected";
     lessonId?: LessonId;
     data: BranchSelectedData;
+}) | (BuildTelemetryEventContext & {
+    name: "image_juxtaposition_changed";
+    lessonId?: LessonId;
+    data: ImageJuxtapositionChangedData;
+}) | (BuildTelemetryEventContext & {
+    name: "timeline_event_viewed";
+    lessonId?: LessonId;
+    data: TimelineEventViewedData;
+}) | (BuildTelemetryEventContext & {
+    name: "image_sequence_changed";
+    lessonId?: LessonId;
+    data: ImageSequenceChangedData;
+}) | (BuildTelemetryEventContext & {
+    name: "audio_recording_started";
+    lessonId?: LessonId;
+    data: AudioRecordingData;
+}) | (BuildTelemetryEventContext & {
+    name: "audio_recording_completed";
+    lessonId?: LessonId;
+    data: AudioRecordingData;
+}) | (BuildTelemetryEventContext & {
+    name: "qr_content_revealed";
+    lessonId?: LessonId;
+    data: QrContentRevealedData;
+}) | (BuildTelemetryEventContext & {
+    name: "advent_door_opened";
+    lessonId?: LessonId;
+    data: AdventDoorOpenedData;
+}) | (BuildTelemetryEventContext & {
+    name: "map_stage_viewed";
+    lessonId?: LessonId;
+    data: MapStageViewedData;
+}) | (BuildTelemetryEventContext & {
+    name: "map_exit_selected";
+    lessonId?: LessonId;
+    data: MapExitSelectedData;
 });
 
 /** Reset dev-warning state (tests only). */
@@ -453,6 +561,18 @@ declare function resetTelemetryBuilderWarningsForTests(): void;
 /**
  * Build a typed telemetry event from a catalog event name and context.
  * Validates lesson-scoped events require `lessonId`.
+ *
+ * @example
+ * ```ts
+ * import { buildTelemetryEvent } from "@lessonkit/core";
+ *
+ * const event = buildTelemetryEvent({
+ *   name: "lesson_completed",
+ *   courseId: "sec-101",
+ *   lessonId: "phishing-101",
+ *   sessionId: "tab-abc",
+ * });
+ * ```
  */
 declare function buildTelemetryEvent(opts: BuildTelemetryEventInput): TelemetryEvent;
 /**
@@ -592,12 +712,38 @@ declare function tryEmitCourseStarted(ctx: CourseLifecycleContext, deps: CourseL
 }>;
 declare function buildCourseStartedTelemetryEvent(ctx: CourseLifecycleContext): TelemetryEvent;
 type LessonCompletionEmitter = (lessonId: LessonId, durationMs?: number) => void;
+/**
+ * Mark a lesson complete in progress state and emit `lesson_completed` when newly completed.
+ *
+ * @example
+ * ```ts
+ * completeLessonWithTelemetry({
+ *   progress,
+ *   lessonId: "lesson-1",
+ *   nowMs: Date.now(),
+ *   emitLessonCompleted: (id, durationMs) => track("lesson_completed", { lessonId: id, durationMs }),
+ * });
+ * ```
+ */
 declare function completeLessonWithTelemetry(opts: {
     progress: ProgressController;
     lessonId: LessonId;
     nowMs: number;
     emitLessonCompleted: LessonCompletionEmitter;
 }): boolean;
+/**
+ * Complete the active lesson (if any), then mark the course complete and emit `course_completed`.
+ *
+ * @example
+ * ```ts
+ * completeCourseWithTelemetry({
+ *   progress,
+ *   nowMs: Date.now(),
+ *   emitLessonCompleted: (id) => track("lesson_completed", { lessonId: id }),
+ *   emitCourseCompleted: () => track("course_completed", {}),
+ * });
+ * ```
+ */
 declare function completeCourseWithTelemetry(opts: {
     progress: ProgressController;
     nowMs: number;