@lessonkit/core 1.4.0 → 1.6.0

package/dist/{testing-BhVGckZ5.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";
+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;
@@ -75,6 +75,8 @@ type TelemetryUser = {
 type TelemetryEventBase = {
     timestamp: string;
     courseId: CourseId;
+    /** Optional stable id for sink deduplication (e.g. deliver retry). */
+    id?: string;
     sessionId?: string;
     attemptId?: string;
     user?: TelemetryUser;
@@ -181,6 +183,55 @@ type QuestionnaireSubmittedData = {
     blockId: BlockId;
     fieldCount: number;
 };
+type BranchNodeViewedData = {
+    blockId: BlockId;
+    nodeId: string;
+    nodeIndex: number;
+    nodeTitle?: string;
+};
+type BranchSelectedData = {
+    blockId: BlockId;
+    fromNodeId: string;
+    toNodeId: string;
+    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;
@@ -273,6 +324,50 @@ type TelemetryEvent = (TelemetryEventBase & {
     name: "questionnaire_submitted";
     lessonId: LessonId;
     data: QuestionnaireSubmittedData;
+}) | (TelemetryEventBase & {
+    name: "branch_node_viewed";
+    lessonId: LessonId;
+    data: BranchNodeViewedData;
+}) | (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, {
@@ -283,7 +378,8 @@ type TelemetryDataFor<N extends TelemetryEventName> = Extract<TelemetryEvent, {
 type TelemetrySink = (event: TelemetryEvent) => void | Promise<void>;
 type TelemetryBatchSink = (events: TelemetryEvent[]) => void | Promise<void>;
 type TrackingClient = {
-    track: (event: TelemetryEvent) => void;
+    /** Returns false when the event was dropped (e.g. buffer cap or after dispose). */
+    track: (event: TelemetryEvent) => boolean;
     /** Delivers one event and resolves to true only when the sink accepted it (batch: includes flush). */
     deliver?: (event: TelemetryEvent) => Promise<boolean>;
     /** Resolves to true when all buffered events were delivered; false when a sink failure re-queued events. */
@@ -414,6 +510,50 @@ type BuildTelemetryEventInput = (BuildTelemetryEventContext & {
     name: "questionnaire_submitted";
     lessonId?: LessonId;
     data: QuestionnaireSubmittedData;
+}) | (BuildTelemetryEventContext & {
+    name: "branch_node_viewed";
+    lessonId?: LessonId;
+    data: BranchNodeViewedData;
+}) | (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). */
@@ -421,10 +561,23 @@ 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;
 /**
- * Like `buildTelemetryEvent`, but returns null (with a dev warning) when quiz events lack an active lesson.
+ * Like `buildTelemetryEvent`, but returns null when lesson-scoped events lack `lessonId`
+ * (with dev warnings for quiz/assessment events).
  */
 declare function tryBuildTelemetryEvent(opts: BuildTelemetryEventInput): TelemetryEvent | null;
 
@@ -457,7 +610,9 @@ declare function hasCourseStartedEmittedToTracking(storage: StoragePort, session
 declare function markCourseStartedEmittedToTracking(storage: StoragePort, sessionId: string, courseId?: CourseId): boolean;
 declare function hasCourseStartedPipelineDelivered(storage: StoragePort, sessionId: string, courseId?: CourseId): boolean;
 declare function markCourseStartedPipelineDelivered(storage: StoragePort, sessionId: string, courseId?: CourseId): boolean;
-/** @internal Reset shared volatile session id between tests. */
+declare function hasCourseStartedXapiSent(storage: StoragePort, sessionId: string, courseId?: CourseId): boolean;
+declare function markCourseStartedXapiSent(storage: StoragePort, sessionId: string, courseId?: CourseId): boolean;
+/** @internal Reset volatile session ids between tests. */
 declare function resetSharedVolatileSessionIdForTests(): void;
 declare function migrateCourseStartedMark(storage: StoragePort, fromSessionId: string, toSessionId: string, courseId?: CourseId): void;
 
@@ -547,18 +702,48 @@ type CourseLifecycleContext = {
 type CourseLifecycleDeps = {
     emitCourseStartedEvent: (ctx: CourseLifecycleContext) => boolean;
 };
-declare function tryEmitCourseStarted(ctx: CourseLifecycleContext, deps: CourseLifecycleDeps, alreadyEmittedToSink: boolean): {
+/**
+ * Emit `course_started` once per tab session when tracking/xAPI are active.
+ * Coalesces concurrent calls via an in-flight guard.
+ */
+declare function tryEmitCourseStarted(ctx: CourseLifecycleContext, deps: CourseLifecycleDeps, alreadyEmittedToSink: boolean): Promise<{
     emitted: boolean;
     marked: boolean;
-};
+}>;
 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;
@@ -566,4 +751,4 @@ declare function completeCourseWithTelemetry(opts: {
     emitCourseCompleted: () => void;
 }): boolean;
 
-export { type SlideViewedData as $, type AccordionSectionToggledData as A, type BlockId as B, type CheckId as C, type InteractionPlugin as D, type LessonId as E, type FlashcardFlippedData as F, type LessonLifecycleData as G, type HotspotOpenedData as H, ID_MAX_LENGTH as I, type LessonkitPlugin as J, type LessonkitPluginContext as K, type LessonCompletionEmitter as L, type LessonkitPluginKind as M, type LessonkitUrn as N, type LifecyclePlugin as O, type McqAssessmentProps as P, type MemoryCardFlippedData as Q, type ParallaxSlideViewedData as R, type PluginHost as S, type PluginIdentity as T, type PluginRegistry as U, type ProgressController as V, type ProgressState as W, type QuestionnaireSubmittedData as X, type QuizAnsweredData as Y, type QuizCompletedData as Z, SESSION_STORAGE_KEY as _, type AssessmentAnsweredData as a, type StoragePort as a0, type TelemetryBatchSink as a1, type TelemetryDataFor as a2, type TelemetryEvent as a3, type TelemetryEventBase as a4, type TelemetryEventName as a5, type TelemetryPlugin as a6, type TelemetrySink as a7, type TelemetryUser as a8, type TimerPort as a9, tryEmitCourseStarted as aA, type TrackingClient as aa, type VideoCueReachedData as ab, type VideoSegmentCompletedData as ac, buildCourseStartedTelemetryEvent as ad, buildTelemetryEvent as ae, completeCourseWithTelemetry as af, completeLessonWithTelemetry as ag, createDefaultClock as ah, createGlobalTimer as ai, createNoopStorage as aj, createProgressController as ak, createSessionStoragePort as al, getTabSessionId as am, hasCourseStarted as an, hasCourseStartedEmittedToTracking as ao, hasCourseStartedPipelineDelivered as ap, markCourseStarted as aq, markCourseStartedEmittedToTracking as ar, markCourseStartedPipelineDelivered as as, migrateCourseStartedMark as at, resetCourseStartedEmitFlightForTests as au, resetSharedVolatileSessionIdForTests as av, resetStoragePortForTests as aw, resetTelemetryBuilderWarningsForTests as ax, resolveSessionId as ay, tryBuildTelemetryEvent as az, type AssessmentBaseProps as b, type AssessmentBehaviour as c, type AssessmentCompletedData as d, type AssessmentHandle as e, type AssessmentInteractionType as f, type AssessmentPlugin as g, type AssessmentResumeState as h, type AssessmentScoreInput as i, type AssessmentScoreResult as j, type AssessmentXAPIData as k, type BookPageViewedData as l, type BuildTelemetryEventInput as m, type ClockPort as n, type CompoundPageViewedData as o, type CourseId as p, type CourseLifecycleContext as q, type CourseLifecycleDeps as r, ID_PATTERN as s, type IdentityIdPath as t, type IdentityValidationIssue as u, type IdentityValidationResult as v, type ImageSliderChangedData as w, type InformationWallSearchData as x, type InteractionBlockRegistration as y, type InteractionData as z };
+export { type LessonCompletionEmitter as $, type AssessmentResumeState as A, type BlockId as B, type CourseId as C, type AssessmentInteractionType as D, type AssessmentXAPIData as E, type BookPageViewedData as F, type BranchNodeViewedData as G, type BranchSelectedData as H, type IdentityIdPath as I, type BuildTelemetryEventInput as J, type CompoundPageViewedData as K, type LessonId as L, type CourseLifecycleContext as M, type CourseLifecycleDeps as N, type FlashcardFlippedData as O, type PluginRegistry as P, type HotspotOpenedData as Q, ID_MAX_LENGTH as R, type StoragePort as S, type TelemetryEventName as T, ID_PATTERN as U, type IdentityValidationIssue as V, type ImageSliderChangedData as W, type InformationWallSearchData as X, type InteractionBlockRegistration as Y, type InteractionData as Z, type InteractionPlugin as _, type CheckId as a, type LessonLifecycleData as a0, type LessonkitPluginKind as a1, type McqAssessmentProps as a2, type MemoryCardFlippedData as a3, type ParallaxSlideViewedData as a4, type PluginIdentity as a5, type QuestionnaireSubmittedData as a6, type QuizAnsweredData as a7, type QuizCompletedData as a8, SESSION_STORAGE_KEY as a9, resetTelemetryBuilderWarningsForTests as aA, resolveSessionId as aB, tryBuildTelemetryEvent as aC, tryEmitCourseStarted as aD, resetCourseStartedEmitFlightForTests as aE, type SlideViewedData as aa, type TelemetryEventBase as ab, type TimerPort as ac, type VideoCueReachedData as ad, type VideoSegmentCompletedData as ae, buildCourseStartedTelemetryEvent as af, buildTelemetryEvent as ag, completeCourseWithTelemetry as ah, completeLessonWithTelemetry as ai, createDefaultClock as aj, createGlobalTimer as ak, createNoopStorage as al, createProgressController as am, createSessionStoragePort as an, getTabSessionId as ao, hasCourseStarted as ap, hasCourseStartedEmittedToTracking as aq, hasCourseStartedPipelineDelivered as ar, hasCourseStartedXapiSent as as, markCourseStarted as at, markCourseStartedEmittedToTracking as au, markCourseStartedPipelineDelivered as av, markCourseStartedXapiSent as aw, migrateCourseStartedMark as ax, resetSharedVolatileSessionIdForTests as ay, resetStoragePortForTests as az, type IdentityValidationResult as b, type LessonkitUrn as c, type TelemetrySink as d, type TelemetryBatchSink as e, type TrackingClient as f, type TelemetryEvent as g, type TelemetryUser as h, type LessonkitPlugin as i, type ProgressController as j, type PluginHost as k, type ProgressState as l, type TelemetryDataFor as m, type AssessmentScoreInput as n, type AssessmentScoreResult as o, type ClockPort as p, type AssessmentPlugin as q, type LifecyclePlugin as r, type TelemetryPlugin as s, type LessonkitPluginContext as t, type AccordionSectionToggledData as u, type AssessmentAnsweredData as v, type AssessmentBaseProps as w, type AssessmentBehaviour as x, type AssessmentCompletedData as y, type AssessmentHandle as z };

package/dist/{testing-BhVGckZ5.d.ts → testing-CzgxF1Ru.d.ts}

@@ -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";
+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;
@@ -75,6 +75,8 @@ type TelemetryUser = {
 type TelemetryEventBase = {
     timestamp: string;
     courseId: CourseId;
+    /** Optional stable id for sink deduplication (e.g. deliver retry). */
+    id?: string;
     sessionId?: string;
     attemptId?: string;
     user?: TelemetryUser;
@@ -181,6 +183,55 @@ type QuestionnaireSubmittedData = {
     blockId: BlockId;
     fieldCount: number;
 };
+type BranchNodeViewedData = {
+    blockId: BlockId;
+    nodeId: string;
+    nodeIndex: number;
+    nodeTitle?: string;
+};
+type BranchSelectedData = {
+    blockId: BlockId;
+    fromNodeId: string;
+    toNodeId: string;
+    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;
@@ -273,6 +324,50 @@ type TelemetryEvent = (TelemetryEventBase & {
     name: "questionnaire_submitted";
     lessonId: LessonId;
     data: QuestionnaireSubmittedData;
+}) | (TelemetryEventBase & {
+    name: "branch_node_viewed";
+    lessonId: LessonId;
+    data: BranchNodeViewedData;
+}) | (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, {
@@ -283,7 +378,8 @@ type TelemetryDataFor<N extends TelemetryEventName> = Extract<TelemetryEvent, {
 type TelemetrySink = (event: TelemetryEvent) => void | Promise<void>;
 type TelemetryBatchSink = (events: TelemetryEvent[]) => void | Promise<void>;
 type TrackingClient = {
-    track: (event: TelemetryEvent) => void;
+    /** Returns false when the event was dropped (e.g. buffer cap or after dispose). */
+    track: (event: TelemetryEvent) => boolean;
     /** Delivers one event and resolves to true only when the sink accepted it (batch: includes flush). */
     deliver?: (event: TelemetryEvent) => Promise<boolean>;
     /** Resolves to true when all buffered events were delivered; false when a sink failure re-queued events. */
@@ -414,6 +510,50 @@ type BuildTelemetryEventInput = (BuildTelemetryEventContext & {
     name: "questionnaire_submitted";
     lessonId?: LessonId;
     data: QuestionnaireSubmittedData;
+}) | (BuildTelemetryEventContext & {
+    name: "branch_node_viewed";
+    lessonId?: LessonId;
+    data: BranchNodeViewedData;
+}) | (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). */
@@ -421,10 +561,23 @@ 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;
 /**
- * Like `buildTelemetryEvent`, but returns null (with a dev warning) when quiz events lack an active lesson.
+ * Like `buildTelemetryEvent`, but returns null when lesson-scoped events lack `lessonId`
+ * (with dev warnings for quiz/assessment events).
  */
 declare function tryBuildTelemetryEvent(opts: BuildTelemetryEventInput): TelemetryEvent | null;
 
@@ -457,7 +610,9 @@ declare function hasCourseStartedEmittedToTracking(storage: StoragePort, session
 declare function markCourseStartedEmittedToTracking(storage: StoragePort, sessionId: string, courseId?: CourseId): boolean;
 declare function hasCourseStartedPipelineDelivered(storage: StoragePort, sessionId: string, courseId?: CourseId): boolean;
 declare function markCourseStartedPipelineDelivered(storage: StoragePort, sessionId: string, courseId?: CourseId): boolean;
-/** @internal Reset shared volatile session id between tests. */
+declare function hasCourseStartedXapiSent(storage: StoragePort, sessionId: string, courseId?: CourseId): boolean;
+declare function markCourseStartedXapiSent(storage: StoragePort, sessionId: string, courseId?: CourseId): boolean;
+/** @internal Reset volatile session ids between tests. */
 declare function resetSharedVolatileSessionIdForTests(): void;
 declare function migrateCourseStartedMark(storage: StoragePort, fromSessionId: string, toSessionId: string, courseId?: CourseId): void;
 
@@ -547,18 +702,48 @@ type CourseLifecycleContext = {
 type CourseLifecycleDeps = {
     emitCourseStartedEvent: (ctx: CourseLifecycleContext) => boolean;
 };
-declare function tryEmitCourseStarted(ctx: CourseLifecycleContext, deps: CourseLifecycleDeps, alreadyEmittedToSink: boolean): {
+/**
+ * Emit `course_started` once per tab session when tracking/xAPI are active.
+ * Coalesces concurrent calls via an in-flight guard.
+ */
+declare function tryEmitCourseStarted(ctx: CourseLifecycleContext, deps: CourseLifecycleDeps, alreadyEmittedToSink: boolean): Promise<{
     emitted: boolean;
     marked: boolean;
-};
+}>;
 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;
@@ -566,4 +751,4 @@ declare function completeCourseWithTelemetry(opts: {
     emitCourseCompleted: () => void;
 }): boolean;
 
-export { type SlideViewedData as $, type AccordionSectionToggledData as A, type BlockId as B, type CheckId as C, type InteractionPlugin as D, type LessonId as E, type FlashcardFlippedData as F, type LessonLifecycleData as G, type HotspotOpenedData as H, ID_MAX_LENGTH as I, type LessonkitPlugin as J, type LessonkitPluginContext as K, type LessonCompletionEmitter as L, type LessonkitPluginKind as M, type LessonkitUrn as N, type LifecyclePlugin as O, type McqAssessmentProps as P, type MemoryCardFlippedData as Q, type ParallaxSlideViewedData as R, type PluginHost as S, type PluginIdentity as T, type PluginRegistry as U, type ProgressController as V, type ProgressState as W, type QuestionnaireSubmittedData as X, type QuizAnsweredData as Y, type QuizCompletedData as Z, SESSION_STORAGE_KEY as _, type AssessmentAnsweredData as a, type StoragePort as a0, type TelemetryBatchSink as a1, type TelemetryDataFor as a2, type TelemetryEvent as a3, type TelemetryEventBase as a4, type TelemetryEventName as a5, type TelemetryPlugin as a6, type TelemetrySink as a7, type TelemetryUser as a8, type TimerPort as a9, tryEmitCourseStarted as aA, type TrackingClient as aa, type VideoCueReachedData as ab, type VideoSegmentCompletedData as ac, buildCourseStartedTelemetryEvent as ad, buildTelemetryEvent as ae, completeCourseWithTelemetry as af, completeLessonWithTelemetry as ag, createDefaultClock as ah, createGlobalTimer as ai, createNoopStorage as aj, createProgressController as ak, createSessionStoragePort as al, getTabSessionId as am, hasCourseStarted as an, hasCourseStartedEmittedToTracking as ao, hasCourseStartedPipelineDelivered as ap, markCourseStarted as aq, markCourseStartedEmittedToTracking as ar, markCourseStartedPipelineDelivered as as, migrateCourseStartedMark as at, resetCourseStartedEmitFlightForTests as au, resetSharedVolatileSessionIdForTests as av, resetStoragePortForTests as aw, resetTelemetryBuilderWarningsForTests as ax, resolveSessionId as ay, tryBuildTelemetryEvent as az, type AssessmentBaseProps as b, type AssessmentBehaviour as c, type AssessmentCompletedData as d, type AssessmentHandle as e, type AssessmentInteractionType as f, type AssessmentPlugin as g, type AssessmentResumeState as h, type AssessmentScoreInput as i, type AssessmentScoreResult as j, type AssessmentXAPIData as k, type BookPageViewedData as l, type BuildTelemetryEventInput as m, type ClockPort as n, type CompoundPageViewedData as o, type CourseId as p, type CourseLifecycleContext as q, type CourseLifecycleDeps as r, ID_PATTERN as s, type IdentityIdPath as t, type IdentityValidationIssue as u, type IdentityValidationResult as v, type ImageSliderChangedData as w, type InformationWallSearchData as x, type InteractionBlockRegistration as y, type InteractionData as z };
+export { type LessonCompletionEmitter as $, type AssessmentResumeState as A, type BlockId as B, type CourseId as C, type AssessmentInteractionType as D, type AssessmentXAPIData as E, type BookPageViewedData as F, type BranchNodeViewedData as G, type BranchSelectedData as H, type IdentityIdPath as I, type BuildTelemetryEventInput as J, type CompoundPageViewedData as K, type LessonId as L, type CourseLifecycleContext as M, type CourseLifecycleDeps as N, type FlashcardFlippedData as O, type PluginRegistry as P, type HotspotOpenedData as Q, ID_MAX_LENGTH as R, type StoragePort as S, type TelemetryEventName as T, ID_PATTERN as U, type IdentityValidationIssue as V, type ImageSliderChangedData as W, type InformationWallSearchData as X, type InteractionBlockRegistration as Y, type InteractionData as Z, type InteractionPlugin as _, type CheckId as a, type LessonLifecycleData as a0, type LessonkitPluginKind as a1, type McqAssessmentProps as a2, type MemoryCardFlippedData as a3, type ParallaxSlideViewedData as a4, type PluginIdentity as a5, type QuestionnaireSubmittedData as a6, type QuizAnsweredData as a7, type QuizCompletedData as a8, SESSION_STORAGE_KEY as a9, resetTelemetryBuilderWarningsForTests as aA, resolveSessionId as aB, tryBuildTelemetryEvent as aC, tryEmitCourseStarted as aD, resetCourseStartedEmitFlightForTests as aE, type SlideViewedData as aa, type TelemetryEventBase as ab, type TimerPort as ac, type VideoCueReachedData as ad, type VideoSegmentCompletedData as ae, buildCourseStartedTelemetryEvent as af, buildTelemetryEvent as ag, completeCourseWithTelemetry as ah, completeLessonWithTelemetry as ai, createDefaultClock as aj, createGlobalTimer as ak, createNoopStorage as al, createProgressController as am, createSessionStoragePort as an, getTabSessionId as ao, hasCourseStarted as ap, hasCourseStartedEmittedToTracking as aq, hasCourseStartedPipelineDelivered as ar, hasCourseStartedXapiSent as as, markCourseStarted as at, markCourseStartedEmittedToTracking as au, markCourseStartedPipelineDelivered as av, markCourseStartedXapiSent as aw, migrateCourseStartedMark as ax, resetSharedVolatileSessionIdForTests as ay, resetStoragePortForTests as az, type IdentityValidationResult as b, type LessonkitUrn as c, type TelemetrySink as d, type TelemetryBatchSink as e, type TrackingClient as f, type TelemetryEvent as g, type TelemetryUser as h, type LessonkitPlugin as i, type ProgressController as j, type PluginHost as k, type ProgressState as l, type TelemetryDataFor as m, type AssessmentScoreInput as n, type AssessmentScoreResult as o, type ClockPort as p, type AssessmentPlugin as q, type LifecyclePlugin as r, type TelemetryPlugin as s, type LessonkitPluginContext as t, type AccordionSectionToggledData as u, type AssessmentAnsweredData as v, type AssessmentBaseProps as w, type AssessmentBehaviour as x, type AssessmentCompletedData as y, type AssessmentHandle as z };

package/dist/testing.cjs

@@ -41,13 +41,11 @@ function resetStoragePortForTests(storage) {
 }
 
 // src/session.ts
-var sharedVolatileSessionId = null;
 function resetSharedVolatileSessionIdForTests() {
-  sharedVolatileSessionId = null;
 }
 
 // src/runtime/courseLifecycle.ts
-var courseStartedEmitFlights = /* @__PURE__ */ new Set();
+var courseStartedEmitFlights = /* @__PURE__ */ new Map();
 function resetCourseStartedEmitFlightForTests() {
   courseStartedEmitFlights.clear();
 }

package/dist/testing.d.cts

@@ -1 +1 @@
-export { au as resetCourseStartedEmitFlightForTests, av as resetSharedVolatileSessionIdForTests, aw as resetStoragePortForTests, ax as resetTelemetryBuilderWarningsForTests } from './testing-BhVGckZ5.cjs';
+export { aE as resetCourseStartedEmitFlightForTests, ay as resetSharedVolatileSessionIdForTests, az as resetStoragePortForTests, aA as resetTelemetryBuilderWarningsForTests } from './testing-CzgxF1Ru.cjs';

package/dist/testing.d.ts

@@ -1 +1 @@
-export { au as resetCourseStartedEmitFlightForTests, av as resetSharedVolatileSessionIdForTests, aw as resetStoragePortForTests, ax as resetTelemetryBuilderWarningsForTests } from './testing-BhVGckZ5.js';
+export { aE as resetCourseStartedEmitFlightForTests, ay as resetSharedVolatileSessionIdForTests, az as resetStoragePortForTests, aA as resetTelemetryBuilderWarningsForTests } from './testing-CzgxF1Ru.js';

package/dist/testing.js

@@ -3,7 +3,7 @@ import {
   resetSharedVolatileSessionIdForTests,
   resetStoragePortForTests,
   resetTelemetryBuilderWarningsForTests
-} from "./chunk-PEWFPVQ6.js";
+} from "./chunk-NGCHHJSM.js";
 export {
   resetCourseStartedEmitFlightForTests,
   resetSharedVolatileSessionIdForTests,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lessonkit/core",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "private": false,
   "description": "Shared types and telemetry primitives for LessonKit.",
   "license": "Apache-2.0",
@@ -54,12 +54,12 @@
     "typecheck": "tsc -p tsconfig.json",
     "test": "vitest run --passWithNoTests",
     "test:coverage": "vitest run --coverage --passWithNoTests=false",
-    "lint": "echo \"(no lint configured yet)\""
+    "lint": "eslint --max-warnings 0 \"src/**/*.{ts,tsx}\" \"test/**/*.{ts,tsx}\""
   },
   "devDependencies": {
     "@types/node": "^25.9.2",
     "tsup": "^8.5.0",
-    "typescript": "^5.8.3",
+    "typescript": "^6.0.3",
     "vitest": "^4.1.8"
   }
 }