@lessonkit/core 1.4.0 → 1.6.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { p as CourseId, E as LessonId, C as CheckId, B as BlockId, t as IdentityIdPath, v as IdentityValidationResult, N as LessonkitUrn, h as AssessmentResumeState, a0 as StoragePort, a5 as TelemetryEventName, a7 as TelemetrySink, a1 as TelemetryBatchSink, aa as TrackingClient, a3 as TelemetryEvent, a8 as TelemetryUser, J as LessonkitPlugin, U as PluginRegistry, V as ProgressController, S as PluginHost, W as ProgressState, a2 as TelemetryDataFor, i as AssessmentScoreInput, j as AssessmentScoreResult, n as ClockPort, g as AssessmentPlugin, O as LifecyclePlugin, a6 as TelemetryPlugin, K as LessonkitPluginContext } from './testing-BhVGckZ5.cjs';
-export { A as AccordionSectionToggledData, a as AssessmentAnsweredData, b as AssessmentBaseProps, c as AssessmentBehaviour, d as AssessmentCompletedData, e as AssessmentHandle, f as AssessmentInteractionType, k as AssessmentXAPIData, l as BookPageViewedData, m as BuildTelemetryEventInput, o as CompoundPageViewedData, q as CourseLifecycleContext, r as CourseLifecycleDeps, F as FlashcardFlippedData, H as HotspotOpenedData, I as ID_MAX_LENGTH, s as ID_PATTERN, u as IdentityValidationIssue, w as ImageSliderChangedData, x as InformationWallSearchData, y as InteractionBlockRegistration, z as InteractionData, D as InteractionPlugin, L as LessonCompletionEmitter, G as LessonLifecycleData, M as LessonkitPluginKind, P as McqAssessmentProps, Q as MemoryCardFlippedData, R as ParallaxSlideViewedData, T as PluginIdentity, X as QuestionnaireSubmittedData, Y as QuizAnsweredData, Z as QuizCompletedData, _ as SESSION_STORAGE_KEY, $ as SlideViewedData, a4 as TelemetryEventBase, a9 as TimerPort, ab as VideoCueReachedData, ac as VideoSegmentCompletedData, ad as buildCourseStartedTelemetryEvent, ae as buildTelemetryEvent, af as completeCourseWithTelemetry, ag as completeLessonWithTelemetry, ah as createDefaultClock, ai as createGlobalTimer, aj as createNoopStorage, ak as createProgressController, al as createSessionStoragePort, am as getTabSessionId, an as hasCourseStarted, ao as hasCourseStartedEmittedToTracking, ap as hasCourseStartedPipelineDelivered, aq as markCourseStarted, ar as markCourseStartedEmittedToTracking, as as markCourseStartedPipelineDelivered, at as migrateCourseStartedMark, av as resetSharedVolatileSessionIdForTests, aw as resetStoragePortForTests, ax as resetTelemetryBuilderWarningsForTests, ay as resolveSessionId, az as tryBuildTelemetryEvent, aA as tryEmitCourseStarted } from './testing-BhVGckZ5.cjs';
+import { C as CourseId, L as LessonId, a as CheckId, B as BlockId, I as IdentityIdPath, b as IdentityValidationResult, c as LessonkitUrn, A as AssessmentResumeState, S as StoragePort, T as TelemetryEventName, d as TelemetrySink, e as TelemetryBatchSink, f as TrackingClient, g as TelemetryEvent, h as TelemetryUser, i as LessonkitPlugin, P as PluginRegistry, j as ProgressController, k as PluginHost, l as ProgressState, m as TelemetryDataFor, n as AssessmentScoreInput, o as AssessmentScoreResult, p as ClockPort, q as AssessmentPlugin, r as LifecyclePlugin, s as TelemetryPlugin, t as LessonkitPluginContext } from './testing-CzgxF1Ru.cjs';
+export { u as AccordionSectionToggledData, v as AssessmentAnsweredData, w as AssessmentBaseProps, x as AssessmentBehaviour, y as AssessmentCompletedData, z as AssessmentHandle, D as AssessmentInteractionType, E as AssessmentXAPIData, F as BookPageViewedData, G as BranchNodeViewedData, H as BranchSelectedData, J as BuildTelemetryEventInput, K as CompoundPageViewedData, M as CourseLifecycleContext, N as CourseLifecycleDeps, O as FlashcardFlippedData, Q as HotspotOpenedData, R as ID_MAX_LENGTH, U as ID_PATTERN, V as IdentityValidationIssue, W as ImageSliderChangedData, X as InformationWallSearchData, Y as InteractionBlockRegistration, Z as InteractionData, _ as InteractionPlugin, $ as LessonCompletionEmitter, a0 as LessonLifecycleData, a1 as LessonkitPluginKind, a2 as McqAssessmentProps, a3 as MemoryCardFlippedData, a4 as ParallaxSlideViewedData, a5 as PluginIdentity, a6 as QuestionnaireSubmittedData, a7 as QuizAnsweredData, a8 as QuizCompletedData, a9 as SESSION_STORAGE_KEY, aa as SlideViewedData, ab as TelemetryEventBase, ac as TimerPort, ad as VideoCueReachedData, ae as VideoSegmentCompletedData, af as buildCourseStartedTelemetryEvent, ag as buildTelemetryEvent, ah as completeCourseWithTelemetry, ai as completeLessonWithTelemetry, aj as createDefaultClock, ak as createGlobalTimer, al as createNoopStorage, am as createProgressController, an as createSessionStoragePort, ao as getTabSessionId, ap as hasCourseStarted, aq as hasCourseStartedEmittedToTracking, ar as hasCourseStartedPipelineDelivered, as as hasCourseStartedXapiSent, at as markCourseStarted, au as markCourseStartedEmittedToTracking, av as markCourseStartedPipelineDelivered, aw as markCourseStartedXapiSent, ax as migrateCourseStartedMark, ay as resetSharedVolatileSessionIdForTests, az as resetStoragePortForTests, aA as resetTelemetryBuilderWarningsForTests, aB as resolveSessionId, aC as tryBuildTelemetryEvent, aD as tryEmitCourseStarted } from './testing-CzgxF1Ru.cjs';
 
 /**
  * Exhaustiveness helper for switch/default branches.
@@ -28,6 +28,7 @@ type LessonkitUrnParts = {
     lessonId?: LessonId;
     checkId?: CheckId;
     blockId?: BlockId;
+    nodeId?: string;
 };
 /**
  * Build a stable LessonKit URN for courses, lessons, checks, and blocks.
@@ -55,7 +56,12 @@ type CompoundResumeInput = {
 declare function createCompoundResumeState(input?: CompoundResumeInput): CompoundResumeState;
 /** Clamp page index to valid range for a compound with `pageCount` pages. */
 declare function clampCompoundPageIndex(index: number, pageCount: number): number;
-declare function parseCompoundResumeState(raw: unknown): CompoundResumeState | null;
+type ParseCompoundResumeStateOptions = {
+    onDroppedChildKeys?: (keys: string[]) => void;
+    /** When set, clamps `activePageIndex` to `[0, pageCount - 1]`. */
+    pageCount?: number;
+};
+declare function parseCompoundResumeState(raw: unknown, opts?: ParseCompoundResumeStateOptions): CompoundResumeState | null;
 /**
  * Imperative handle for compound containers (H5P compound analogue).
  * Parents aggregate child AssessmentHandle scores and persist navigation state.
@@ -74,20 +80,29 @@ type CompoundBaseProps = {
 };
 
 declare function compoundStateStorageKey(courseId: CourseId, compoundId: BlockId): string;
-declare function loadCompoundState(storage: StoragePort, courseId: CourseId, compoundId: BlockId): CompoundResumeState | null;
+type LoadCompoundStateOptions = ParseCompoundResumeStateOptions & {
+    onCorrupt?: () => void;
+};
+declare function loadCompoundState(storage: StoragePort, courseId: CourseId, compoundId: BlockId, opts?: LoadCompoundStateOptions): CompoundResumeState | null;
 declare function saveCompoundState(storage: StoragePort, courseId: CourseId, compoundId: BlockId, state: CompoundResumeState): boolean;
 declare function clearCompoundState(storage: StoragePort, courseId: CourseId, compoundId: BlockId): void;
 
 /** Canonical compound child allowlists (H5P sub-content curation). */
-declare const PAGE_ALLOWED_CHILD_TYPES: readonly ["Text", "Heading", "Image", "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", "ProgressTracker"];
+declare const PAGE_ALLOWED_CHILD_TYPES: readonly ["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", "ProgressTracker"];
+/** Branch node content (Page-like minus ProgressTracker). */
+declare const BRANCH_NODE_ALLOWED_CHILD_TYPES: readonly ["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", "BranchChoice"];
+declare const BRANCHING_SCENARIO_ALLOWED_CHILD_TYPES: readonly ["BranchNode"];
+declare const GAME_MAP_ALLOWED_CHILD_TYPES: readonly ["MapStage"];
+/** Map stage content (BranchNode parity; WordSearch excluded from compounds). */
+declare const MAP_STAGE_ALLOWED_CHILD_TYPES: readonly ["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"];
 declare const INTERACTIVE_BOOK_ALLOWED_CHILD_TYPES: readonly ["Page"];
 /** Per-slide content (H5P Course Presentation slide row). Excludes ProgressTracker. */
-declare const SLIDE_ALLOWED_CHILD_TYPES: readonly ["Text", "Heading", "Image", "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"];
+declare const SLIDE_ALLOWED_CHILD_TYPES: readonly ["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"];
 declare const SLIDE_DECK_ALLOWED_CHILD_TYPES: readonly ["Slide"];
 declare const TIMED_CUE_ALLOWED_CHILD_TYPES: readonly ["Text", "Heading", "Image", "Quiz", "TrueFalse", "FillInTheBlanks", "Summary", "ImagePairing", "ImageSequencing", "MemoryGame", "Questionnaire", "Essay", "ArithmeticQuiz"];
 declare const INTERACTIVE_VIDEO_ALLOWED_CHILD_TYPES: readonly ["TimedCue"];
 declare const ASSESSMENT_SEQUENCE_ALLOWED_CHILD_TYPES: readonly ["TrueFalse", "FillInTheBlanks", "DragAndDrop", "DragTheWords", "MarkTheWords", "Quiz", "KnowledgeCheck", "FindHotspot", "FindMultipleHotspots", "Summary", "ImagePairing", "ImageSequencing", "ArithmeticQuiz", "Essay"];
-type CompoundParentType = "Page" | "InteractiveBook" | "Slide" | "SlideDeck" | "TimedCue" | "InteractiveVideo" | "AssessmentSequence";
+type CompoundParentType = "Page" | "InteractiveBook" | "Slide" | "SlideDeck" | "TimedCue" | "InteractiveVideo" | "AssessmentSequence" | "BranchingScenario" | "BranchNode" | "GameMap" | "MapStage";
 declare const COMPOUND_MAX_NESTING_DEPTH: Record<CompoundParentType, number>;
 declare function getAllowedChildTypes(parent: CompoundParentType): readonly string[];
 declare function isChildTypeAllowed(parent: CompoundParentType, childType: string): boolean;
@@ -96,6 +111,24 @@ declare const ACCORDION_FORBIDDEN_CHILD_TYPES: readonly ["Accordion"];
 /** New 1.4 blocks added to Page and Slide allowlists (for docs/tests). */
 declare const BLOCKS_14_PAGE_SLIDE: readonly ["Video", "Summary", "ImagePairing", "ImageSequencing", "MemoryGame", "InformationWall", "ParallaxSlideshow", "Questionnaire", "Essay", "ArithmeticQuiz"];
 
+type BranchGraphNodeInput = {
+    nodeId: string;
+    choices: readonly {
+        targetNodeId: string;
+    }[];
+};
+type BranchGraphValidationIssue = {
+    code: "duplicate_node_id" | "start_not_found" | "start_no_choices" | "unknown_target" | "unreachable_node" | "empty_graph";
+    message: string;
+    nodeId?: string;
+};
+type BranchGraphValidationResult = {
+    ok: boolean;
+    issues: BranchGraphValidationIssue[];
+    reachableNodeIds: string[];
+};
+declare function validateBranchGraph(startNodeId: string, nodes: readonly BranchGraphNodeInput[]): BranchGraphValidationResult;
+
 declare const telemetryCatalogVersion: 1;
 type TelemetryCatalogEntry = {
     name: TelemetryEventName;
@@ -121,7 +154,7 @@ declare const TELEMETRY_EVENT_CATALOG_V2: TelemetryCatalogV2Entry[];
 declare function buildTelemetryCatalogV2(): TelemetryCatalogV2Entry[];
 
 declare const telemetryCatalogV3Version: 3;
-type TelemetryCatalogV3EventName = Extract<TelemetryEventName, "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 TelemetryCatalogV3EventName = Extract<TelemetryEventName, "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 TelemetryCatalogV3Entry = {
     name: TelemetryCatalogV3EventName;
     description: string;
@@ -133,6 +166,25 @@ type TelemetryCatalogV3Entry = {
 declare const TELEMETRY_EVENT_CATALOG_V3: TelemetryCatalogV3Entry[];
 declare function buildTelemetryCatalogV3(): TelemetryCatalogV3Entry[];
 
+/**
+ * Creates a client that buffers telemetry and flushes in batches.
+ *
+ * **Delivery semantics:** batch mode is at-least-once. A failed flush re-queues the batch for
+ * retry; `flushOnExit` and periodic flushes may deliver the same events more than once unless
+ * the sink deduplicates. Events currently owned by an in-flight `batchSink` call are not included
+ * in `flushOnExit` to avoid duplicate delivery on page unload.
+ *
+ * @example
+ * ```ts
+ * import { createTrackingClient } from "@lessonkit/core";
+ *
+ * const tracking = createTrackingClient({
+ *   sink: (event) => console.log(event.name, event),
+ *   batch: { enabled: true, flushIntervalMs: 5000 },
+ * });
+ * tracking.track({ name: "course_started", courseId: "c1", sessionId: "s1" });
+ * ```
+ */
 declare function createTrackingClient(opts?: {
     sink?: TelemetrySink;
     batch?: {
@@ -165,6 +217,20 @@ type TelemetryPipeline = {
     readonly sinks: readonly TelemetryPipelineSink[];
     emit(event: TelemetryEvent, ctx?: EmitContext): void | Promise<void>;
 };
+declare function isLifecycleTelemetryEvent(name: TelemetryEventName): boolean;
+/**
+ * Compose multiple telemetry sinks behind a single `emit` call.
+ *
+ * @example
+ * ```ts
+ * import { createTelemetryPipeline, createTrackingPipelineSink } from "@lessonkit/core";
+ *
+ * const pipeline = createTelemetryPipeline([
+ *   createTrackingPipelineSink("console", (e) => console.log(e.name)),
+ * ]);
+ * await pipeline.emit(event, { courseId: "c1", sessionId: "s1" });
+ * ```
+ */
 declare function createTelemetryPipeline(sinks: TelemetryPipelineSink[]): TelemetryPipeline;
 declare function createTrackingPipelineSink(id: string, track: (event: TelemetryEvent) => void): TelemetryPipelineSink;
 
@@ -178,6 +244,8 @@ type HeadlessLessonkitConfig = {
         attemptId?: string;
         user?: TelemetryUser;
     };
+    /** When true (default), switching lessons auto-completes the previous in-progress lesson. */
+    autoCompleteOnLessonSwitch?: boolean;
     /** Plugin list or registry; hooks run on {@link HeadlessLessonkitRuntime.track} and lifecycle emits. */
     plugins?: HeadlessLessonkitPlugins;
     /** When true, skip initial {@link PluginHost.setupAll}; host caller runs setup (React v2 provider). */
@@ -187,9 +255,8 @@ type HeadlessRuntimePorts = {
     storage?: StoragePort;
     clock?: ClockPort;
 };
-type TelemetryEmitFn = {
-    <N extends TelemetryEventName>(name: N, data?: TelemetryDataFor<N>, lessonId?: LessonId): void;
-};
+/** Delivers a fully-built lifecycle telemetry event (plugins already applied). */
+type TelemetryEmitFn = (event: TelemetryEvent) => void;
 type HeadlessLessonkitRuntime = {
     readonly config: HeadlessLessonkitConfig;
     readonly progress: ProgressController;
@@ -201,6 +268,8 @@ type HeadlessLessonkitRuntime = {
         user?: TelemetryUser;
     };
     updateConfig: (next: Partial<HeadlessLessonkitConfig>) => void;
+    /** Move course-started dedupe marks between session ids (e.g. LMS anonymous → authenticated handoff). */
+    migrateSessionMarks: (fromSessionId: string, toSessionId: string) => void;
     setActiveLesson: (lessonId: LessonId, emit: TelemetryEmitFn) => void;
     completeLesson: (lessonId: LessonId, emit: TelemetryEmitFn) => void;
     completeCourse: (emit: TelemetryEmitFn) => void;
@@ -209,15 +278,73 @@ type HeadlessLessonkitRuntime = {
     resetForCourseChange: (courseId: CourseId) => void;
     dispose: () => void;
 };
+/**
+ * Create a headless LessonKit runtime for non-React tooling and tests.
+ * Powers `LessonkitProvider` from `@lessonkit/react` when `runtimeVersion` is `"v2"` (default).
+ *
+ * @example
+ * ```ts
+ * import { createLessonkitRuntime } from "@lessonkit/core";
+ *
+ * const runtime = createLessonkitRuntime({ courseId: "demo-course" });
+ * runtime.setActiveLesson("lesson-1");
+ * runtime.track("interaction", { label: "opened" }, { lessonId: "lesson-1" });
+ * ```
+ */
 declare function createLessonkitRuntime(config: HeadlessLessonkitConfig, ports?: HeadlessRuntimePorts): HeadlessLessonkitRuntime;
 
 declare function createPluginRegistry(plugins?: readonly LessonkitPlugin[]): PluginRegistry;
 
-/** Identity helper for telemetry plugins; does not validate or register at import time. */
+/**
+ * Identity helper for telemetry plugins; does not validate or register at import time.
+ *
+ * @example
+ * ```ts
+ * import { defineTelemetryPlugin } from "@lessonkit/core";
+ *
+ * const analytics = defineTelemetryPlugin({
+ *   id: "console-analytics",
+ *   kind: "telemetry",
+ *   onEvent(event) {
+ *     console.log(event.name);
+ *   },
+ * });
+ * ```
+ */
 declare function defineTelemetryPlugin(plugin: TelemetryPlugin): LessonkitPlugin;
-/** Identity helper for assessment plugins; does not validate or register at import time. */
+/**
+ * Identity helper for assessment plugins; does not validate or register at import time.
+ *
+ * @example
+ * ```ts
+ * import { defineAssessmentPlugin } from "@lessonkit/core";
+ *
+ * const grader = defineAssessmentPlugin({
+ *   id: "essay-grader",
+ *   kind: "assessment",
+ *   score(input) {
+ *     return { score: input.rawScore ?? 0, maxScore: 1, passed: true };
+ *   },
+ * });
+ * ```
+ */
 declare function defineAssessmentPlugin(plugin: AssessmentPlugin): LessonkitPlugin;
-/** Identity helper for lifecycle plugins; does not validate or register at import time. */
+/**
+ * Identity helper for lifecycle plugins; does not validate or register at import time.
+ *
+ * @example
+ * ```ts
+ * import { defineLifecyclePlugin } from "@lessonkit/core";
+ *
+ * const onComplete = defineLifecyclePlugin({
+ *   id: "completion-hook",
+ *   kind: "lifecycle",
+ *   onCourseCompleted() {
+ *     window.parent.postMessage({ type: "course-done" }, "*");
+ *   },
+ * });
+ * ```
+ */
 declare function defineLifecyclePlugin(plugin: LifecyclePlugin): LessonkitPlugin;
 
 declare function buildPluginContext(opts: {
@@ -227,4 +354,4 @@ declare function buildPluginContext(opts: {
     user?: TelemetryUser;
 }): LessonkitPluginContext;
 
-export { ACCORDION_FORBIDDEN_CHILD_TYPES, ASSESSMENT_SEQUENCE_ALLOWED_CHILD_TYPES, AssessmentPlugin, AssessmentResumeState, AssessmentScoreInput, AssessmentScoreResult, BLOCKS_14_PAGE_SLIDE, BlockId, COMPOUND_MAX_NESTING_DEPTH, COMPOUND_RESUME_SCHEMA_VERSION, CheckId, ClockPort, type CompoundBaseProps, type CompoundHandle, type CompoundParentType, type CompoundResumeInput, type CompoundResumeState, CourseId, type EmitContext, type HeadlessLessonkitConfig, type HeadlessLessonkitRuntime, type HeadlessRuntimePorts, INTERACTIVE_BOOK_ALLOWED_CHILD_TYPES, INTERACTIVE_VIDEO_ALLOWED_CHILD_TYPES, IdentityIdPath, IdentityValidationResult, LessonId, LessonkitPlugin, LessonkitPluginContext, type LessonkitRuntimeVersion, LessonkitUrn, type LessonkitUrnParts, LifecyclePlugin, type LmsBridgeMode, PAGE_ALLOWED_CHILD_TYPES, PluginHost, PluginRegistry, ProgressController, ProgressState, SLIDE_ALLOWED_CHILD_TYPES, SLIDE_DECK_ALLOWED_CHILD_TYPES, StoragePort, TELEMETRY_EVENT_CATALOG, TELEMETRY_EVENT_CATALOG_V2, TELEMETRY_EVENT_CATALOG_V3, TIMED_CUE_ALLOWED_CHILD_TYPES, TelemetryBatchSink, type TelemetryCatalogEntry, type TelemetryCatalogV2Entry, type TelemetryCatalogV3Entry, TelemetryDataFor, type TelemetryEmitFn, TelemetryEvent, TelemetryEventName, type TelemetryPipeline, type TelemetryPipelineSink, TelemetryPlugin, TelemetrySink, TelemetryUser, TrackingClient, assertNever, assertValidId, buildLessonkitUrn, buildPluginContext, buildTelemetryCatalog, buildTelemetryCatalogV2, buildTelemetryCatalogV3, clampCompoundPageIndex, clearCompoundState, compoundStateStorageKey, createCompoundResumeState, createLessonkitRuntime, createPluginRegistry, createSessionId, createTelemetryPipeline, createTrackingClient, createTrackingPipelineSink, defineAssessmentPlugin, defineLifecyclePlugin, defineTelemetryPlugin, deriveId, getAllowedChildTypes, isChildTypeAllowed, loadCompoundState, nowIso, parseBlockId, parseCheckId, parseCompoundResumeState, parseCourseId, parseLessonId, saveCompoundState, slugifyId, telemetryCatalogV2Version, telemetryCatalogV3Version, telemetryCatalogVersion, validateId };
+export { ACCORDION_FORBIDDEN_CHILD_TYPES, ASSESSMENT_SEQUENCE_ALLOWED_CHILD_TYPES, AssessmentPlugin, AssessmentResumeState, AssessmentScoreInput, AssessmentScoreResult, BLOCKS_14_PAGE_SLIDE, BRANCHING_SCENARIO_ALLOWED_CHILD_TYPES, BRANCH_NODE_ALLOWED_CHILD_TYPES, BlockId, type BranchGraphNodeInput, type BranchGraphValidationIssue, type BranchGraphValidationResult, COMPOUND_MAX_NESTING_DEPTH, COMPOUND_RESUME_SCHEMA_VERSION, CheckId, ClockPort, type CompoundBaseProps, type CompoundHandle, type CompoundParentType, type CompoundResumeInput, type CompoundResumeState, CourseId, type EmitContext, GAME_MAP_ALLOWED_CHILD_TYPES, type HeadlessLessonkitConfig, type HeadlessLessonkitRuntime, type HeadlessRuntimePorts, INTERACTIVE_BOOK_ALLOWED_CHILD_TYPES, INTERACTIVE_VIDEO_ALLOWED_CHILD_TYPES, IdentityIdPath, IdentityValidationResult, LessonId, LessonkitPlugin, LessonkitPluginContext, type LessonkitRuntimeVersion, LessonkitUrn, type LessonkitUrnParts, LifecyclePlugin, type LmsBridgeMode, type LoadCompoundStateOptions, MAP_STAGE_ALLOWED_CHILD_TYPES, PAGE_ALLOWED_CHILD_TYPES, type ParseCompoundResumeStateOptions, PluginHost, PluginRegistry, ProgressController, ProgressState, SLIDE_ALLOWED_CHILD_TYPES, SLIDE_DECK_ALLOWED_CHILD_TYPES, StoragePort, TELEMETRY_EVENT_CATALOG, TELEMETRY_EVENT_CATALOG_V2, TELEMETRY_EVENT_CATALOG_V3, TIMED_CUE_ALLOWED_CHILD_TYPES, TelemetryBatchSink, type TelemetryCatalogEntry, type TelemetryCatalogV2Entry, type TelemetryCatalogV3Entry, TelemetryDataFor, type TelemetryEmitFn, TelemetryEvent, TelemetryEventName, type TelemetryPipeline, type TelemetryPipelineSink, TelemetryPlugin, TelemetrySink, TelemetryUser, TrackingClient, assertNever, assertValidId, buildLessonkitUrn, buildPluginContext, buildTelemetryCatalog, buildTelemetryCatalogV2, buildTelemetryCatalogV3, clampCompoundPageIndex, clearCompoundState, compoundStateStorageKey, createCompoundResumeState, createLessonkitRuntime, createPluginRegistry, createSessionId, createTelemetryPipeline, createTrackingClient, createTrackingPipelineSink, defineAssessmentPlugin, defineLifecyclePlugin, defineTelemetryPlugin, deriveId, getAllowedChildTypes, isChildTypeAllowed, isLifecycleTelemetryEvent, loadCompoundState, nowIso, parseBlockId, parseCheckId, parseCompoundResumeState, parseCourseId, parseLessonId, saveCompoundState, slugifyId, telemetryCatalogV2Version, telemetryCatalogV3Version, telemetryCatalogVersion, validateBranchGraph, validateId };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { p as CourseId, E as LessonId, C as CheckId, B as BlockId, t as IdentityIdPath, v as IdentityValidationResult, N as LessonkitUrn, h as AssessmentResumeState, a0 as StoragePort, a5 as TelemetryEventName, a7 as TelemetrySink, a1 as TelemetryBatchSink, aa as TrackingClient, a3 as TelemetryEvent, a8 as TelemetryUser, J as LessonkitPlugin, U as PluginRegistry, V as ProgressController, S as PluginHost, W as ProgressState, a2 as TelemetryDataFor, i as AssessmentScoreInput, j as AssessmentScoreResult, n as ClockPort, g as AssessmentPlugin, O as LifecyclePlugin, a6 as TelemetryPlugin, K as LessonkitPluginContext } from './testing-BhVGckZ5.js';
-export { A as AccordionSectionToggledData, a as AssessmentAnsweredData, b as AssessmentBaseProps, c as AssessmentBehaviour, d as AssessmentCompletedData, e as AssessmentHandle, f as AssessmentInteractionType, k as AssessmentXAPIData, l as BookPageViewedData, m as BuildTelemetryEventInput, o as CompoundPageViewedData, q as CourseLifecycleContext, r as CourseLifecycleDeps, F as FlashcardFlippedData, H as HotspotOpenedData, I as ID_MAX_LENGTH, s as ID_PATTERN, u as IdentityValidationIssue, w as ImageSliderChangedData, x as InformationWallSearchData, y as InteractionBlockRegistration, z as InteractionData, D as InteractionPlugin, L as LessonCompletionEmitter, G as LessonLifecycleData, M as LessonkitPluginKind, P as McqAssessmentProps, Q as MemoryCardFlippedData, R as ParallaxSlideViewedData, T as PluginIdentity, X as QuestionnaireSubmittedData, Y as QuizAnsweredData, Z as QuizCompletedData, _ as SESSION_STORAGE_KEY, $ as SlideViewedData, a4 as TelemetryEventBase, a9 as TimerPort, ab as VideoCueReachedData, ac as VideoSegmentCompletedData, ad as buildCourseStartedTelemetryEvent, ae as buildTelemetryEvent, af as completeCourseWithTelemetry, ag as completeLessonWithTelemetry, ah as createDefaultClock, ai as createGlobalTimer, aj as createNoopStorage, ak as createProgressController, al as createSessionStoragePort, am as getTabSessionId, an as hasCourseStarted, ao as hasCourseStartedEmittedToTracking, ap as hasCourseStartedPipelineDelivered, aq as markCourseStarted, ar as markCourseStartedEmittedToTracking, as as markCourseStartedPipelineDelivered, at as migrateCourseStartedMark, av as resetSharedVolatileSessionIdForTests, aw as resetStoragePortForTests, ax as resetTelemetryBuilderWarningsForTests, ay as resolveSessionId, az as tryBuildTelemetryEvent, aA as tryEmitCourseStarted } from './testing-BhVGckZ5.js';
+import { C as CourseId, L as LessonId, a as CheckId, B as BlockId, I as IdentityIdPath, b as IdentityValidationResult, c as LessonkitUrn, A as AssessmentResumeState, S as StoragePort, T as TelemetryEventName, d as TelemetrySink, e as TelemetryBatchSink, f as TrackingClient, g as TelemetryEvent, h as TelemetryUser, i as LessonkitPlugin, P as PluginRegistry, j as ProgressController, k as PluginHost, l as ProgressState, m as TelemetryDataFor, n as AssessmentScoreInput, o as AssessmentScoreResult, p as ClockPort, q as AssessmentPlugin, r as LifecyclePlugin, s as TelemetryPlugin, t as LessonkitPluginContext } from './testing-CzgxF1Ru.js';
+export { u as AccordionSectionToggledData, v as AssessmentAnsweredData, w as AssessmentBaseProps, x as AssessmentBehaviour, y as AssessmentCompletedData, z as AssessmentHandle, D as AssessmentInteractionType, E as AssessmentXAPIData, F as BookPageViewedData, G as BranchNodeViewedData, H as BranchSelectedData, J as BuildTelemetryEventInput, K as CompoundPageViewedData, M as CourseLifecycleContext, N as CourseLifecycleDeps, O as FlashcardFlippedData, Q as HotspotOpenedData, R as ID_MAX_LENGTH, U as ID_PATTERN, V as IdentityValidationIssue, W as ImageSliderChangedData, X as InformationWallSearchData, Y as InteractionBlockRegistration, Z as InteractionData, _ as InteractionPlugin, $ as LessonCompletionEmitter, a0 as LessonLifecycleData, a1 as LessonkitPluginKind, a2 as McqAssessmentProps, a3 as MemoryCardFlippedData, a4 as ParallaxSlideViewedData, a5 as PluginIdentity, a6 as QuestionnaireSubmittedData, a7 as QuizAnsweredData, a8 as QuizCompletedData, a9 as SESSION_STORAGE_KEY, aa as SlideViewedData, ab as TelemetryEventBase, ac as TimerPort, ad as VideoCueReachedData, ae as VideoSegmentCompletedData, af as buildCourseStartedTelemetryEvent, ag as buildTelemetryEvent, ah as completeCourseWithTelemetry, ai as completeLessonWithTelemetry, aj as createDefaultClock, ak as createGlobalTimer, al as createNoopStorage, am as createProgressController, an as createSessionStoragePort, ao as getTabSessionId, ap as hasCourseStarted, aq as hasCourseStartedEmittedToTracking, ar as hasCourseStartedPipelineDelivered, as as hasCourseStartedXapiSent, at as markCourseStarted, au as markCourseStartedEmittedToTracking, av as markCourseStartedPipelineDelivered, aw as markCourseStartedXapiSent, ax as migrateCourseStartedMark, ay as resetSharedVolatileSessionIdForTests, az as resetStoragePortForTests, aA as resetTelemetryBuilderWarningsForTests, aB as resolveSessionId, aC as tryBuildTelemetryEvent, aD as tryEmitCourseStarted } from './testing-CzgxF1Ru.js';
 
 /**
  * Exhaustiveness helper for switch/default branches.
@@ -28,6 +28,7 @@ type LessonkitUrnParts = {
     lessonId?: LessonId;
     checkId?: CheckId;
     blockId?: BlockId;
+    nodeId?: string;
 };
 /**
  * Build a stable LessonKit URN for courses, lessons, checks, and blocks.
@@ -55,7 +56,12 @@ type CompoundResumeInput = {
 declare function createCompoundResumeState(input?: CompoundResumeInput): CompoundResumeState;
 /** Clamp page index to valid range for a compound with `pageCount` pages. */
 declare function clampCompoundPageIndex(index: number, pageCount: number): number;
-declare function parseCompoundResumeState(raw: unknown): CompoundResumeState | null;
+type ParseCompoundResumeStateOptions = {
+    onDroppedChildKeys?: (keys: string[]) => void;
+    /** When set, clamps `activePageIndex` to `[0, pageCount - 1]`. */
+    pageCount?: number;
+};
+declare function parseCompoundResumeState(raw: unknown, opts?: ParseCompoundResumeStateOptions): CompoundResumeState | null;
 /**
  * Imperative handle for compound containers (H5P compound analogue).
  * Parents aggregate child AssessmentHandle scores and persist navigation state.
@@ -74,20 +80,29 @@ type CompoundBaseProps = {
 };
 
 declare function compoundStateStorageKey(courseId: CourseId, compoundId: BlockId): string;
-declare function loadCompoundState(storage: StoragePort, courseId: CourseId, compoundId: BlockId): CompoundResumeState | null;
+type LoadCompoundStateOptions = ParseCompoundResumeStateOptions & {
+    onCorrupt?: () => void;
+};
+declare function loadCompoundState(storage: StoragePort, courseId: CourseId, compoundId: BlockId, opts?: LoadCompoundStateOptions): CompoundResumeState | null;
 declare function saveCompoundState(storage: StoragePort, courseId: CourseId, compoundId: BlockId, state: CompoundResumeState): boolean;
 declare function clearCompoundState(storage: StoragePort, courseId: CourseId, compoundId: BlockId): void;
 
 /** Canonical compound child allowlists (H5P sub-content curation). */
-declare const PAGE_ALLOWED_CHILD_TYPES: readonly ["Text", "Heading", "Image", "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", "ProgressTracker"];
+declare const PAGE_ALLOWED_CHILD_TYPES: readonly ["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", "ProgressTracker"];
+/** Branch node content (Page-like minus ProgressTracker). */
+declare const BRANCH_NODE_ALLOWED_CHILD_TYPES: readonly ["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", "BranchChoice"];
+declare const BRANCHING_SCENARIO_ALLOWED_CHILD_TYPES: readonly ["BranchNode"];
+declare const GAME_MAP_ALLOWED_CHILD_TYPES: readonly ["MapStage"];
+/** Map stage content (BranchNode parity; WordSearch excluded from compounds). */
+declare const MAP_STAGE_ALLOWED_CHILD_TYPES: readonly ["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"];
 declare const INTERACTIVE_BOOK_ALLOWED_CHILD_TYPES: readonly ["Page"];
 /** Per-slide content (H5P Course Presentation slide row). Excludes ProgressTracker. */
-declare const SLIDE_ALLOWED_CHILD_TYPES: readonly ["Text", "Heading", "Image", "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"];
+declare const SLIDE_ALLOWED_CHILD_TYPES: readonly ["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"];
 declare const SLIDE_DECK_ALLOWED_CHILD_TYPES: readonly ["Slide"];
 declare const TIMED_CUE_ALLOWED_CHILD_TYPES: readonly ["Text", "Heading", "Image", "Quiz", "TrueFalse", "FillInTheBlanks", "Summary", "ImagePairing", "ImageSequencing", "MemoryGame", "Questionnaire", "Essay", "ArithmeticQuiz"];
 declare const INTERACTIVE_VIDEO_ALLOWED_CHILD_TYPES: readonly ["TimedCue"];
 declare const ASSESSMENT_SEQUENCE_ALLOWED_CHILD_TYPES: readonly ["TrueFalse", "FillInTheBlanks", "DragAndDrop", "DragTheWords", "MarkTheWords", "Quiz", "KnowledgeCheck", "FindHotspot", "FindMultipleHotspots", "Summary", "ImagePairing", "ImageSequencing", "ArithmeticQuiz", "Essay"];
-type CompoundParentType = "Page" | "InteractiveBook" | "Slide" | "SlideDeck" | "TimedCue" | "InteractiveVideo" | "AssessmentSequence";
+type CompoundParentType = "Page" | "InteractiveBook" | "Slide" | "SlideDeck" | "TimedCue" | "InteractiveVideo" | "AssessmentSequence" | "BranchingScenario" | "BranchNode" | "GameMap" | "MapStage";
 declare const COMPOUND_MAX_NESTING_DEPTH: Record<CompoundParentType, number>;
 declare function getAllowedChildTypes(parent: CompoundParentType): readonly string[];
 declare function isChildTypeAllowed(parent: CompoundParentType, childType: string): boolean;
@@ -96,6 +111,24 @@ declare const ACCORDION_FORBIDDEN_CHILD_TYPES: readonly ["Accordion"];
 /** New 1.4 blocks added to Page and Slide allowlists (for docs/tests). */
 declare const BLOCKS_14_PAGE_SLIDE: readonly ["Video", "Summary", "ImagePairing", "ImageSequencing", "MemoryGame", "InformationWall", "ParallaxSlideshow", "Questionnaire", "Essay", "ArithmeticQuiz"];
 
+type BranchGraphNodeInput = {
+    nodeId: string;
+    choices: readonly {
+        targetNodeId: string;
+    }[];
+};
+type BranchGraphValidationIssue = {
+    code: "duplicate_node_id" | "start_not_found" | "start_no_choices" | "unknown_target" | "unreachable_node" | "empty_graph";
+    message: string;
+    nodeId?: string;
+};
+type BranchGraphValidationResult = {
+    ok: boolean;
+    issues: BranchGraphValidationIssue[];
+    reachableNodeIds: string[];
+};
+declare function validateBranchGraph(startNodeId: string, nodes: readonly BranchGraphNodeInput[]): BranchGraphValidationResult;
+
 declare const telemetryCatalogVersion: 1;
 type TelemetryCatalogEntry = {
     name: TelemetryEventName;
@@ -121,7 +154,7 @@ declare const TELEMETRY_EVENT_CATALOG_V2: TelemetryCatalogV2Entry[];
 declare function buildTelemetryCatalogV2(): TelemetryCatalogV2Entry[];
 
 declare const telemetryCatalogV3Version: 3;
-type TelemetryCatalogV3EventName = Extract<TelemetryEventName, "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 TelemetryCatalogV3EventName = Extract<TelemetryEventName, "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 TelemetryCatalogV3Entry = {
     name: TelemetryCatalogV3EventName;
     description: string;
@@ -133,6 +166,25 @@ type TelemetryCatalogV3Entry = {
 declare const TELEMETRY_EVENT_CATALOG_V3: TelemetryCatalogV3Entry[];
 declare function buildTelemetryCatalogV3(): TelemetryCatalogV3Entry[];
 
+/**
+ * Creates a client that buffers telemetry and flushes in batches.
+ *
+ * **Delivery semantics:** batch mode is at-least-once. A failed flush re-queues the batch for
+ * retry; `flushOnExit` and periodic flushes may deliver the same events more than once unless
+ * the sink deduplicates. Events currently owned by an in-flight `batchSink` call are not included
+ * in `flushOnExit` to avoid duplicate delivery on page unload.
+ *
+ * @example
+ * ```ts
+ * import { createTrackingClient } from "@lessonkit/core";
+ *
+ * const tracking = createTrackingClient({
+ *   sink: (event) => console.log(event.name, event),
+ *   batch: { enabled: true, flushIntervalMs: 5000 },
+ * });
+ * tracking.track({ name: "course_started", courseId: "c1", sessionId: "s1" });
+ * ```
+ */
 declare function createTrackingClient(opts?: {
     sink?: TelemetrySink;
     batch?: {
@@ -165,6 +217,20 @@ type TelemetryPipeline = {
     readonly sinks: readonly TelemetryPipelineSink[];
     emit(event: TelemetryEvent, ctx?: EmitContext): void | Promise<void>;
 };
+declare function isLifecycleTelemetryEvent(name: TelemetryEventName): boolean;
+/**
+ * Compose multiple telemetry sinks behind a single `emit` call.
+ *
+ * @example
+ * ```ts
+ * import { createTelemetryPipeline, createTrackingPipelineSink } from "@lessonkit/core";
+ *
+ * const pipeline = createTelemetryPipeline([
+ *   createTrackingPipelineSink("console", (e) => console.log(e.name)),
+ * ]);
+ * await pipeline.emit(event, { courseId: "c1", sessionId: "s1" });
+ * ```
+ */
 declare function createTelemetryPipeline(sinks: TelemetryPipelineSink[]): TelemetryPipeline;
 declare function createTrackingPipelineSink(id: string, track: (event: TelemetryEvent) => void): TelemetryPipelineSink;
 
@@ -178,6 +244,8 @@ type HeadlessLessonkitConfig = {
         attemptId?: string;
         user?: TelemetryUser;
     };
+    /** When true (default), switching lessons auto-completes the previous in-progress lesson. */
+    autoCompleteOnLessonSwitch?: boolean;
     /** Plugin list or registry; hooks run on {@link HeadlessLessonkitRuntime.track} and lifecycle emits. */
     plugins?: HeadlessLessonkitPlugins;
     /** When true, skip initial {@link PluginHost.setupAll}; host caller runs setup (React v2 provider). */
@@ -187,9 +255,8 @@ type HeadlessRuntimePorts = {
     storage?: StoragePort;
     clock?: ClockPort;
 };
-type TelemetryEmitFn = {
-    <N extends TelemetryEventName>(name: N, data?: TelemetryDataFor<N>, lessonId?: LessonId): void;
-};
+/** Delivers a fully-built lifecycle telemetry event (plugins already applied). */
+type TelemetryEmitFn = (event: TelemetryEvent) => void;
 type HeadlessLessonkitRuntime = {
     readonly config: HeadlessLessonkitConfig;
     readonly progress: ProgressController;
@@ -201,6 +268,8 @@ type HeadlessLessonkitRuntime = {
         user?: TelemetryUser;
     };
     updateConfig: (next: Partial<HeadlessLessonkitConfig>) => void;
+    /** Move course-started dedupe marks between session ids (e.g. LMS anonymous → authenticated handoff). */
+    migrateSessionMarks: (fromSessionId: string, toSessionId: string) => void;
     setActiveLesson: (lessonId: LessonId, emit: TelemetryEmitFn) => void;
     completeLesson: (lessonId: LessonId, emit: TelemetryEmitFn) => void;
     completeCourse: (emit: TelemetryEmitFn) => void;
@@ -209,15 +278,73 @@ type HeadlessLessonkitRuntime = {
     resetForCourseChange: (courseId: CourseId) => void;
     dispose: () => void;
 };
+/**
+ * Create a headless LessonKit runtime for non-React tooling and tests.
+ * Powers `LessonkitProvider` from `@lessonkit/react` when `runtimeVersion` is `"v2"` (default).
+ *
+ * @example
+ * ```ts
+ * import { createLessonkitRuntime } from "@lessonkit/core";
+ *
+ * const runtime = createLessonkitRuntime({ courseId: "demo-course" });
+ * runtime.setActiveLesson("lesson-1");
+ * runtime.track("interaction", { label: "opened" }, { lessonId: "lesson-1" });
+ * ```
+ */
 declare function createLessonkitRuntime(config: HeadlessLessonkitConfig, ports?: HeadlessRuntimePorts): HeadlessLessonkitRuntime;
 
 declare function createPluginRegistry(plugins?: readonly LessonkitPlugin[]): PluginRegistry;
 
-/** Identity helper for telemetry plugins; does not validate or register at import time. */
+/**
+ * Identity helper for telemetry plugins; does not validate or register at import time.
+ *
+ * @example
+ * ```ts
+ * import { defineTelemetryPlugin } from "@lessonkit/core";
+ *
+ * const analytics = defineTelemetryPlugin({
+ *   id: "console-analytics",
+ *   kind: "telemetry",
+ *   onEvent(event) {
+ *     console.log(event.name);
+ *   },
+ * });
+ * ```
+ */
 declare function defineTelemetryPlugin(plugin: TelemetryPlugin): LessonkitPlugin;
-/** Identity helper for assessment plugins; does not validate or register at import time. */
+/**
+ * Identity helper for assessment plugins; does not validate or register at import time.
+ *
+ * @example
+ * ```ts
+ * import { defineAssessmentPlugin } from "@lessonkit/core";
+ *
+ * const grader = defineAssessmentPlugin({
+ *   id: "essay-grader",
+ *   kind: "assessment",
+ *   score(input) {
+ *     return { score: input.rawScore ?? 0, maxScore: 1, passed: true };
+ *   },
+ * });
+ * ```
+ */
 declare function defineAssessmentPlugin(plugin: AssessmentPlugin): LessonkitPlugin;
-/** Identity helper for lifecycle plugins; does not validate or register at import time. */
+/**
+ * Identity helper for lifecycle plugins; does not validate or register at import time.
+ *
+ * @example
+ * ```ts
+ * import { defineLifecyclePlugin } from "@lessonkit/core";
+ *
+ * const onComplete = defineLifecyclePlugin({
+ *   id: "completion-hook",
+ *   kind: "lifecycle",
+ *   onCourseCompleted() {
+ *     window.parent.postMessage({ type: "course-done" }, "*");
+ *   },
+ * });
+ * ```
+ */
 declare function defineLifecyclePlugin(plugin: LifecyclePlugin): LessonkitPlugin;
 
 declare function buildPluginContext(opts: {
@@ -227,4 +354,4 @@ declare function buildPluginContext(opts: {
     user?: TelemetryUser;
 }): LessonkitPluginContext;
 
-export { ACCORDION_FORBIDDEN_CHILD_TYPES, ASSESSMENT_SEQUENCE_ALLOWED_CHILD_TYPES, AssessmentPlugin, AssessmentResumeState, AssessmentScoreInput, AssessmentScoreResult, BLOCKS_14_PAGE_SLIDE, BlockId, COMPOUND_MAX_NESTING_DEPTH, COMPOUND_RESUME_SCHEMA_VERSION, CheckId, ClockPort, type CompoundBaseProps, type CompoundHandle, type CompoundParentType, type CompoundResumeInput, type CompoundResumeState, CourseId, type EmitContext, type HeadlessLessonkitConfig, type HeadlessLessonkitRuntime, type HeadlessRuntimePorts, INTERACTIVE_BOOK_ALLOWED_CHILD_TYPES, INTERACTIVE_VIDEO_ALLOWED_CHILD_TYPES, IdentityIdPath, IdentityValidationResult, LessonId, LessonkitPlugin, LessonkitPluginContext, type LessonkitRuntimeVersion, LessonkitUrn, type LessonkitUrnParts, LifecyclePlugin, type LmsBridgeMode, PAGE_ALLOWED_CHILD_TYPES, PluginHost, PluginRegistry, ProgressController, ProgressState, SLIDE_ALLOWED_CHILD_TYPES, SLIDE_DECK_ALLOWED_CHILD_TYPES, StoragePort, TELEMETRY_EVENT_CATALOG, TELEMETRY_EVENT_CATALOG_V2, TELEMETRY_EVENT_CATALOG_V3, TIMED_CUE_ALLOWED_CHILD_TYPES, TelemetryBatchSink, type TelemetryCatalogEntry, type TelemetryCatalogV2Entry, type TelemetryCatalogV3Entry, TelemetryDataFor, type TelemetryEmitFn, TelemetryEvent, TelemetryEventName, type TelemetryPipeline, type TelemetryPipelineSink, TelemetryPlugin, TelemetrySink, TelemetryUser, TrackingClient, assertNever, assertValidId, buildLessonkitUrn, buildPluginContext, buildTelemetryCatalog, buildTelemetryCatalogV2, buildTelemetryCatalogV3, clampCompoundPageIndex, clearCompoundState, compoundStateStorageKey, createCompoundResumeState, createLessonkitRuntime, createPluginRegistry, createSessionId, createTelemetryPipeline, createTrackingClient, createTrackingPipelineSink, defineAssessmentPlugin, defineLifecyclePlugin, defineTelemetryPlugin, deriveId, getAllowedChildTypes, isChildTypeAllowed, loadCompoundState, nowIso, parseBlockId, parseCheckId, parseCompoundResumeState, parseCourseId, parseLessonId, saveCompoundState, slugifyId, telemetryCatalogV2Version, telemetryCatalogV3Version, telemetryCatalogVersion, validateId };
+export { ACCORDION_FORBIDDEN_CHILD_TYPES, ASSESSMENT_SEQUENCE_ALLOWED_CHILD_TYPES, AssessmentPlugin, AssessmentResumeState, AssessmentScoreInput, AssessmentScoreResult, BLOCKS_14_PAGE_SLIDE, BRANCHING_SCENARIO_ALLOWED_CHILD_TYPES, BRANCH_NODE_ALLOWED_CHILD_TYPES, BlockId, type BranchGraphNodeInput, type BranchGraphValidationIssue, type BranchGraphValidationResult, COMPOUND_MAX_NESTING_DEPTH, COMPOUND_RESUME_SCHEMA_VERSION, CheckId, ClockPort, type CompoundBaseProps, type CompoundHandle, type CompoundParentType, type CompoundResumeInput, type CompoundResumeState, CourseId, type EmitContext, GAME_MAP_ALLOWED_CHILD_TYPES, type HeadlessLessonkitConfig, type HeadlessLessonkitRuntime, type HeadlessRuntimePorts, INTERACTIVE_BOOK_ALLOWED_CHILD_TYPES, INTERACTIVE_VIDEO_ALLOWED_CHILD_TYPES, IdentityIdPath, IdentityValidationResult, LessonId, LessonkitPlugin, LessonkitPluginContext, type LessonkitRuntimeVersion, LessonkitUrn, type LessonkitUrnParts, LifecyclePlugin, type LmsBridgeMode, type LoadCompoundStateOptions, MAP_STAGE_ALLOWED_CHILD_TYPES, PAGE_ALLOWED_CHILD_TYPES, type ParseCompoundResumeStateOptions, PluginHost, PluginRegistry, ProgressController, ProgressState, SLIDE_ALLOWED_CHILD_TYPES, SLIDE_DECK_ALLOWED_CHILD_TYPES, StoragePort, TELEMETRY_EVENT_CATALOG, TELEMETRY_EVENT_CATALOG_V2, TELEMETRY_EVENT_CATALOG_V3, TIMED_CUE_ALLOWED_CHILD_TYPES, TelemetryBatchSink, type TelemetryCatalogEntry, type TelemetryCatalogV2Entry, type TelemetryCatalogV3Entry, TelemetryDataFor, type TelemetryEmitFn, TelemetryEvent, TelemetryEventName, type TelemetryPipeline, type TelemetryPipelineSink, TelemetryPlugin, TelemetrySink, TelemetryUser, TrackingClient, assertNever, assertValidId, buildLessonkitUrn, buildPluginContext, buildTelemetryCatalog, buildTelemetryCatalogV2, buildTelemetryCatalogV3, clampCompoundPageIndex, clearCompoundState, compoundStateStorageKey, createCompoundResumeState, createLessonkitRuntime, createPluginRegistry, createSessionId, createTelemetryPipeline, createTrackingClient, createTrackingPipelineSink, defineAssessmentPlugin, defineLifecyclePlugin, defineTelemetryPlugin, deriveId, getAllowedChildTypes, isChildTypeAllowed, isLifecycleTelemetryEvent, loadCompoundState, nowIso, parseBlockId, parseCheckId, parseCompoundResumeState, parseCourseId, parseLessonId, saveCompoundState, slugifyId, telemetryCatalogV2Version, telemetryCatalogV3Version, telemetryCatalogVersion, validateBranchGraph, validateId };