@lessonkit/core 1.5.0 → 1.7.0

package/dist/{testing-BFr8oEfw.d.cts → testing-CQ-ZsT7D.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" | "sortParagraphs" | "guessTheAnswer";
 /** Serializable resume blob for a single assessment block. */
 type AssessmentResumeState = Record<string, unknown>;
 /** Behaviour flags aligned with H5P question types. */
@@ -57,15 +57,37 @@ type AssessmentBaseProps = AssessmentBehaviour & {
     checkId: CheckId;
     passingScore?: number;
 };
-/** MCQ assessment props shared by React components and LMS packaging descriptors. */
+/**
+ * MCQ assessment props shared by React components and LMS packaging descriptors.
+ *
+ * @example
+ * ```tsx
+ * const props: McqAssessmentProps = {
+ *   checkId: "verify-sender",
+ *   question: "First step for a suspicious email?",
+ *   choices: ["Open attachment", "Verify sender"],
+ *   answer: "Verify sender",
+ *   passingScore: 1,
+ * };
+ * ```
+ */
 type McqAssessmentProps = AssessmentBaseProps & {
     kind?: "mcq";
     question: string;
     choices: string[];
+    /** Single correct choice (required for backward compatibility). */
     answer: string;
+    /** When length > 1, enables multi-select checkbox mode. */
+    answers?: string[];
+    /** Randomize choice display order in the SPA (stable when `shuffleSeed` set). */
+    shuffleChoices?: boolean;
+    /** Seed for deterministic shuffle; defaults to `checkId`. */
+    shuffleSeed?: string | number;
+    /** Per-choice feedback announced on selection; keys match choice labels. */
+    choiceFeedback?: Record<string, 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 +218,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 +354,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 +540,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 +583,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;
 /**
@@ -482,8 +624,20 @@ type ProgressController = {
 declare function createProgressController(): ProgressController;
 
 declare const SESSION_STORAGE_KEY = "lessonkit:sessionId";
+type InvalidSessionIdContext = {
+    /** The invalid id that was rejected. */
+    invalidId: string;
+    /** Id actually used after fallback. */
+    fallbackId: string;
+    /** Whether the invalid id came from config or from stored tab state. */
+    source: "provided" | "stored";
+};
+type ResolveSessionIdOptions = {
+    /** Invoked when an invalid session id is replaced by a tab or generated id. */
+    onInvalidSessionId?: (ctx: InvalidSessionIdContext) => void;
+};
 declare function getTabSessionId(storage: StoragePort): string | null;
-declare function resolveSessionId(storage: StoragePort, provided?: string): string;
+declare function resolveSessionId(storage: StoragePort, provided?: string, options?: ResolveSessionIdOptions): string;
 declare function hasCourseStarted(storage: StoragePort, sessionId: string, courseId?: CourseId): boolean;
 declare function markCourseStarted(storage: StoragePort, sessionId: string, courseId?: CourseId): boolean;
 declare function hasCourseStartedEmittedToTracking(storage: StoragePort, sessionId: string, courseId?: CourseId): boolean;
@@ -592,12 +746,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;
@@ -605,4 +785,4 @@ declare function completeCourseWithTelemetry(opts: {
     emitCourseCompleted: () => void;
 }): boolean;
 
-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 };
+export { type InteractionPlugin 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 McqAssessmentProps as M, type CourseLifecycleContext as N, type CourseLifecycleDeps as O, type PluginRegistry as P, type FlashcardFlippedData as Q, type HotspotOpenedData as R, type StoragePort as S, type TelemetryEventName as T, ID_MAX_LENGTH as U, ID_PATTERN as V, type IdentityValidationIssue as W, type ImageSliderChangedData as X, type InformationWallSearchData as Y, type InteractionBlockRegistration as Z, type InteractionData as _, type CheckId as a, type InvalidSessionIdContext as a0, type LessonCompletionEmitter as a1, type LessonLifecycleData as a2, type LessonkitPluginKind as a3, type MemoryCardFlippedData as a4, type ParallaxSlideViewedData as a5, type PluginIdentity as a6, type QuestionnaireSubmittedData as a7, type QuizAnsweredData as a8, type QuizCompletedData as a9, resetSharedVolatileSessionIdForTests as aA, resetStoragePortForTests as aB, resetTelemetryBuilderWarningsForTests as aC, resolveSessionId as aD, tryBuildTelemetryEvent as aE, tryEmitCourseStarted as aF, resetCourseStartedEmitFlightForTests as aG, type ResolveSessionIdOptions as aa, SESSION_STORAGE_KEY as ab, type SlideViewedData as ac, type TelemetryEventBase as ad, type TimerPort as ae, type VideoCueReachedData as af, type VideoSegmentCompletedData as ag, buildCourseStartedTelemetryEvent as ah, buildTelemetryEvent as ai, completeCourseWithTelemetry as aj, completeLessonWithTelemetry as ak, createDefaultClock as al, createGlobalTimer as am, createNoopStorage as an, createProgressController as ao, createSessionStoragePort as ap, getTabSessionId as aq, hasCourseStarted as ar, hasCourseStartedEmittedToTracking as as, hasCourseStartedPipelineDelivered as at, hasCourseStartedXapiSent as au, markCourseStarted as av, markCourseStartedEmittedToTracking as aw, markCourseStartedPipelineDelivered as ax, markCourseStartedXapiSent as ay, migrateCourseStartedMark 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-BFr8oEfw.d.ts → testing-CQ-ZsT7D.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" | "sortParagraphs" | "guessTheAnswer";
 /** Serializable resume blob for a single assessment block. */
 type AssessmentResumeState = Record<string, unknown>;
 /** Behaviour flags aligned with H5P question types. */
@@ -57,15 +57,37 @@ type AssessmentBaseProps = AssessmentBehaviour & {
     checkId: CheckId;
     passingScore?: number;
 };
-/** MCQ assessment props shared by React components and LMS packaging descriptors. */
+/**
+ * MCQ assessment props shared by React components and LMS packaging descriptors.
+ *
+ * @example
+ * ```tsx
+ * const props: McqAssessmentProps = {
+ *   checkId: "verify-sender",
+ *   question: "First step for a suspicious email?",
+ *   choices: ["Open attachment", "Verify sender"],
+ *   answer: "Verify sender",
+ *   passingScore: 1,
+ * };
+ * ```
+ */
 type McqAssessmentProps = AssessmentBaseProps & {
     kind?: "mcq";
     question: string;
     choices: string[];
+    /** Single correct choice (required for backward compatibility). */
     answer: string;
+    /** When length > 1, enables multi-select checkbox mode. */
+    answers?: string[];
+    /** Randomize choice display order in the SPA (stable when `shuffleSeed` set). */
+    shuffleChoices?: boolean;
+    /** Seed for deterministic shuffle; defaults to `checkId`. */
+    shuffleSeed?: string | number;
+    /** Per-choice feedback announced on selection; keys match choice labels. */
+    choiceFeedback?: Record<string, 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 +218,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 +354,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 +540,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 +583,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;
 /**
@@ -482,8 +624,20 @@ type ProgressController = {
 declare function createProgressController(): ProgressController;
 
 declare const SESSION_STORAGE_KEY = "lessonkit:sessionId";
+type InvalidSessionIdContext = {
+    /** The invalid id that was rejected. */
+    invalidId: string;
+    /** Id actually used after fallback. */
+    fallbackId: string;
+    /** Whether the invalid id came from config or from stored tab state. */
+    source: "provided" | "stored";
+};
+type ResolveSessionIdOptions = {
+    /** Invoked when an invalid session id is replaced by a tab or generated id. */
+    onInvalidSessionId?: (ctx: InvalidSessionIdContext) => void;
+};
 declare function getTabSessionId(storage: StoragePort): string | null;
-declare function resolveSessionId(storage: StoragePort, provided?: string): string;
+declare function resolveSessionId(storage: StoragePort, provided?: string, options?: ResolveSessionIdOptions): string;
 declare function hasCourseStarted(storage: StoragePort, sessionId: string, courseId?: CourseId): boolean;
 declare function markCourseStarted(storage: StoragePort, sessionId: string, courseId?: CourseId): boolean;
 declare function hasCourseStartedEmittedToTracking(storage: StoragePort, sessionId: string, courseId?: CourseId): boolean;
@@ -592,12 +746,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;
@@ -605,4 +785,4 @@ declare function completeCourseWithTelemetry(opts: {
     emitCourseCompleted: () => void;
 }): boolean;
 
-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 };
+export { type InteractionPlugin 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 McqAssessmentProps as M, type CourseLifecycleContext as N, type CourseLifecycleDeps as O, type PluginRegistry as P, type FlashcardFlippedData as Q, type HotspotOpenedData as R, type StoragePort as S, type TelemetryEventName as T, ID_MAX_LENGTH as U, ID_PATTERN as V, type IdentityValidationIssue as W, type ImageSliderChangedData as X, type InformationWallSearchData as Y, type InteractionBlockRegistration as Z, type InteractionData as _, type CheckId as a, type InvalidSessionIdContext as a0, type LessonCompletionEmitter as a1, type LessonLifecycleData as a2, type LessonkitPluginKind as a3, type MemoryCardFlippedData as a4, type ParallaxSlideViewedData as a5, type PluginIdentity as a6, type QuestionnaireSubmittedData as a7, type QuizAnsweredData as a8, type QuizCompletedData as a9, resetSharedVolatileSessionIdForTests as aA, resetStoragePortForTests as aB, resetTelemetryBuilderWarningsForTests as aC, resolveSessionId as aD, tryBuildTelemetryEvent as aE, tryEmitCourseStarted as aF, resetCourseStartedEmitFlightForTests as aG, type ResolveSessionIdOptions as aa, SESSION_STORAGE_KEY as ab, type SlideViewedData as ac, type TelemetryEventBase as ad, type TimerPort as ae, type VideoCueReachedData as af, type VideoSegmentCompletedData as ag, buildCourseStartedTelemetryEvent as ah, buildTelemetryEvent as ai, completeCourseWithTelemetry as aj, completeLessonWithTelemetry as ak, createDefaultClock as al, createGlobalTimer as am, createNoopStorage as an, createProgressController as ao, createSessionStoragePort as ap, getTabSessionId as aq, hasCourseStarted as ar, hasCourseStartedEmittedToTracking as as, hasCourseStartedPipelineDelivered as at, hasCourseStartedXapiSent as au, markCourseStarted as av, markCourseStartedEmittedToTracking as aw, markCourseStartedPipelineDelivered as ax, markCourseStartedXapiSent as ay, migrateCourseStartedMark 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

@@ -46,8 +46,10 @@ function resetSharedVolatileSessionIdForTests() {
 
 // src/runtime/courseLifecycle.ts
 var courseStartedEmitFlights = /* @__PURE__ */ new Map();
+var courseStartedEmittedInTab = /* @__PURE__ */ new Set();
 function resetCourseStartedEmitFlightForTests() {
   courseStartedEmitFlights.clear();
+  courseStartedEmittedInTab.clear();
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/testing.d.cts

@@ -1 +1 @@
-export { aE as resetCourseStartedEmitFlightForTests, ay as resetSharedVolatileSessionIdForTests, az as resetStoragePortForTests, aA as resetTelemetryBuilderWarningsForTests } from './testing-BFr8oEfw.cjs';
+export { aG as resetCourseStartedEmitFlightForTests, aA as resetSharedVolatileSessionIdForTests, aB as resetStoragePortForTests, aC as resetTelemetryBuilderWarningsForTests } from './testing-CQ-ZsT7D.cjs';

package/dist/testing.d.ts

@@ -1 +1 @@
-export { aE as resetCourseStartedEmitFlightForTests, ay as resetSharedVolatileSessionIdForTests, az as resetStoragePortForTests, aA as resetTelemetryBuilderWarningsForTests } from './testing-BFr8oEfw.js';
+export { aG as resetCourseStartedEmitFlightForTests, aA as resetSharedVolatileSessionIdForTests, aB as resetStoragePortForTests, aC as resetTelemetryBuilderWarningsForTests } from './testing-CQ-ZsT7D.js';

package/dist/testing.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lessonkit/core",
-  "version": "1.5.0",
+  "version": "1.7.0",
   "private": false,
   "description": "Shared types and telemetry primitives for LessonKit.",
   "license": "Apache-2.0",
@@ -48,8 +48,8 @@
     "identity-contract.v1.json"
   ],
   "scripts": {
-    "build": "tsup src/index.ts src/testing.ts --format esm,cjs --dts",
-    "dev": "tsup src/index.ts src/testing.ts --format esm,cjs --dts --watch",
+    "build": "tsup src/index.ts src/testing.ts --format esm,cjs --dts --tsconfig tsconfig.build.json",
+    "dev": "tsup src/index.ts src/testing.ts --format esm,cjs --dts --watch --tsconfig tsconfig.build.json",
     "prepublishOnly": "npm run build",
     "typecheck": "tsc -p tsconfig.json",
     "test": "vitest run --passWithNoTests",