@lessonkit/core 1.3.1 → 1.5.0

package/dist/index.d.ts

@@ -1,24 +1,5 @@
-type CourseId = string;
-type LessonId = string;
-type CheckId = string;
-type BlockId = string;
-/** Stable URN string returned by {@link buildLessonkitUrn}. */
-type LessonkitUrn = string;
-type IdentityValidationIssue = {
-    path: string;
-    message: string;
-};
-type IdentityValidationResult = {
-    ok: true;
-    id: string;
-} | {
-    ok: false;
-    issues: IdentityValidationIssue[];
-};
-type IdentityIdPath = "courseId" | "lessonId" | "checkId" | "blockId" | "id";
-/** LessonKit id format: letter first, then alphanumeric, `_`, `-`; length 1–64. */
-declare const ID_PATTERN: RegExp;
-declare const ID_MAX_LENGTH = 64;
+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-BFr8oEfw.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-BFr8oEfw.js';
 
 /**
  * Exhaustiveness helper for switch/default branches.
@@ -47,6 +28,7 @@ type LessonkitUrnParts = {
     lessonId?: LessonId;
     checkId?: CheckId;
     blockId?: BlockId;
+    nodeId?: string;
 };
 /**
  * Build a stable LessonKit URN for courses, lessons, checks, and blocks.
@@ -54,215 +36,8 @@ type LessonkitUrnParts = {
  */
 declare function buildLessonkitUrn(parts: LessonkitUrnParts): LessonkitUrn;
 
-/** H5P-aligned interaction kinds for assessment telemetry and xAPI. */
-type AssessmentInteractionType = "mcq" | "trueFalse" | "fillInBlanks" | "markTheWords" | "dragTheWords" | "dragAndDrop" | "assessmentSequence" | "findHotspot" | "findMultipleHotspots";
-/** Serializable resume blob for a single assessment block. */
-type AssessmentResumeState = Record<string, unknown>;
-/** Behaviour flags aligned with H5P question types. */
-type AssessmentBehaviour = {
-    enableRetry?: boolean;
-    enableSolutionsButton?: boolean;
-    autoCheck?: boolean;
-};
-/** Payload for xAPI mapping from assessment components. */
-type AssessmentXAPIData = {
-    checkId: CheckId;
-    interactionType: AssessmentInteractionType;
-    response?: string | string[] | boolean | Record<string, unknown>;
-    correct?: boolean;
-    score?: number;
-    maxScore?: number;
-};
-/**
- * Imperative handle for scored blocks (H5P question-type contract analogue).
- * Parent containers (`AssessmentSequence`, future compounds) may call these methods.
- */
-type AssessmentHandle = {
-    getScore: () => number;
-    getMaxScore: () => number;
-    getAnswerGiven: () => boolean;
-    resetTask: () => void;
-    showSolutions: () => void;
-    getXAPIData: () => AssessmentXAPIData;
-    getCurrentState?: () => AssessmentResumeState;
-    resume?: (state: AssessmentResumeState) => void;
-};
-type AssessmentBaseProps = AssessmentBehaviour & {
-    checkId: CheckId;
-    passingScore?: number;
-};
-
-type TelemetryEventName = "course_started" | "course_completed" | "lesson_started" | "lesson_completed" | "lesson_time_on_task" | "quiz_answered" | "quiz_completed" | "assessment_answered" | "assessment_completed" | "interaction" | "book_page_viewed" | "slide_viewed" | "compound_page_viewed" | "hotspot_opened" | "accordion_section_toggled" | "flashcard_flipped" | "image_slider_changed";
-type TelemetryUser = {
-    id?: string;
-    email?: string;
-    name?: string;
-    [key: string]: unknown;
-};
-type TelemetryEventBase = {
-    timestamp: string;
-    courseId: CourseId;
-    sessionId?: string;
-    attemptId?: string;
-    user?: TelemetryUser;
-};
-type LessonLifecycleData = {
-    lessonId: LessonId;
-    durationMs?: number;
-    success?: boolean;
-    score?: number;
-    maxScore?: number;
-};
-type QuizAnsweredData = {
-    checkId: CheckId;
-    question: string;
-    choice: string;
-    correct: boolean;
-};
-type QuizCompletedData = {
-    checkId: CheckId;
-    score?: number;
-    maxScore?: number;
-    passingScore?: number;
-};
-type AssessmentAnsweredData = {
-    checkId: CheckId;
-    interactionType: AssessmentInteractionType;
-    question?: string;
-    response?: string | string[] | boolean | Record<string, unknown>;
-    correct?: boolean;
-};
-type AssessmentCompletedData = {
-    checkId: CheckId;
-    interactionType: AssessmentInteractionType;
-    score?: number;
-    maxScore?: number;
-    passingScore?: number;
-};
-type InteractionData = {
-    kind?: string;
-    blockId?: BlockId;
-    payload?: Record<string, unknown>;
-    [key: string]: unknown;
-};
-type BookPageViewedData = {
-    blockId: BlockId;
-    pageIndex: number;
-    pageTitle?: string;
-};
-type SlideViewedData = {
-    blockId: BlockId;
-    slideIndex: number;
-    slideTitle?: string;
-};
-type CompoundPageViewedData = {
-    blockId: BlockId;
-    pageIndex: number;
-    parentType?: string;
-};
-type HotspotOpenedData = {
-    blockId: BlockId;
-    hotspotId: string;
-};
-type AccordionSectionToggledData = {
-    blockId: BlockId;
-    sectionId: string;
-    expanded: boolean;
-};
-type FlashcardFlippedData = {
-    blockId: BlockId;
-    cardIndex: number;
-    face: "front" | "back";
-};
-type ImageSliderChangedData = {
-    blockId: BlockId;
-    slideIndex: number;
-};
-type TelemetryEvent = (TelemetryEventBase & {
-    name: "course_started";
-    lessonId?: LessonId;
-    data?: undefined;
-}) | (TelemetryEventBase & {
-    name: "course_completed";
-    lessonId?: LessonId;
-    data?: undefined;
-}) | (TelemetryEventBase & {
-    name: "lesson_started";
-    lessonId: LessonId;
-    data: LessonLifecycleData;
-}) | (TelemetryEventBase & {
-    name: "lesson_completed";
-    lessonId: LessonId;
-    data: LessonLifecycleData;
-}) | (TelemetryEventBase & {
-    name: "lesson_time_on_task";
-    lessonId: LessonId;
-    data: LessonLifecycleData;
-}) | (TelemetryEventBase & {
-    name: "quiz_answered";
-    lessonId: LessonId;
-    data: QuizAnsweredData;
-}) | (TelemetryEventBase & {
-    name: "quiz_completed";
-    lessonId: LessonId;
-    data: QuizCompletedData;
-}) | (TelemetryEventBase & {
-    name: "assessment_answered";
-    lessonId: LessonId;
-    data: AssessmentAnsweredData;
-}) | (TelemetryEventBase & {
-    name: "assessment_completed";
-    lessonId: LessonId;
-    data: AssessmentCompletedData;
-}) | (TelemetryEventBase & {
-    name: "interaction";
-    lessonId?: LessonId;
-    data?: InteractionData;
-}) | (TelemetryEventBase & {
-    name: "book_page_viewed";
-    lessonId: LessonId;
-    data: BookPageViewedData;
-}) | (TelemetryEventBase & {
-    name: "slide_viewed";
-    lessonId: LessonId;
-    data: SlideViewedData;
-}) | (TelemetryEventBase & {
-    name: "compound_page_viewed";
-    lessonId: LessonId;
-    data: CompoundPageViewedData;
-}) | (TelemetryEventBase & {
-    name: "hotspot_opened";
-    lessonId?: LessonId;
-    data: HotspotOpenedData;
-}) | (TelemetryEventBase & {
-    name: "accordion_section_toggled";
-    lessonId?: LessonId;
-    data: AccordionSectionToggledData;
-}) | (TelemetryEventBase & {
-    name: "flashcard_flipped";
-    lessonId?: LessonId;
-    data: FlashcardFlippedData;
-}) | (TelemetryEventBase & {
-    name: "image_slider_changed";
-    lessonId?: LessonId;
-    data: ImageSliderChangedData;
-});
-/** Payload shape for a telemetry event name. */
-type TelemetryDataFor<N extends TelemetryEventName> = Extract<TelemetryEvent, {
-    name: N;
-}> extends {
-    data?: infer D;
-} ? D : never;
-type TelemetrySink = (event: TelemetryEvent) => void | Promise<void>;
-type TelemetryBatchSink = (events: TelemetryEvent[]) => void | Promise<void>;
-type TrackingClient = {
-    track: (event: TelemetryEvent) => void;
-    /** Resolves to true when all buffered events were delivered; false when a sink failure re-queued events. */
-    flush?: () => void | Promise<boolean>;
-    /** Best-effort synchronous flush for pagehide (keepalive batch sink when configured). */
-    flushOnExit?: () => void;
-    dispose?: () => void | Promise<void>;
-};
+/** LMS parent-bridge forwarding mode for packaged course runtimes. */
+type LmsBridgeMode = "auto" | "off";
 
 declare const COMPOUND_RESUME_SCHEMA_VERSION: 1;
 /** Serializable resume blob for a compound container (InteractiveBook, AssessmentSequence, …). */
@@ -281,7 +56,10 @@ 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;
+};
+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.
@@ -299,46 +77,52 @@ type CompoundBaseProps = {
     blockId: BlockId;
 };
 
-type StoragePort = {
-    getItem: (key: string) => string | null;
-    /** Returns false when the value could not be durably persisted (e.g. sessionStorage quota). */
-    setItem: (key: string, value: string) => boolean;
-    removeItem?: (key: string) => void;
-    /** @internal Test helper to clear in-memory fallback state. */
-    resetForTests?: () => void;
-};
-type ClockPort = {
-    nowMs: () => number;
-    nowIso: () => string;
-};
-type TimerPort = {
-    setInterval: (fn: () => void, ms: number) => ReturnType<typeof globalThis.setInterval>;
-    clearInterval: (id: ReturnType<typeof globalThis.setInterval>) => void;
-};
-declare function createDefaultClock(): ClockPort;
-declare function createNoopStorage(): StoragePort;
-declare function resetStoragePortForTests(storage: StoragePort): void;
-declare function createSessionStoragePort(): StoragePort;
-declare function createGlobalTimer(): TimerPort;
-
 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", "Scenario", "Reflection", "Quiz", "KnowledgeCheck", "TrueFalse", "FillInTheBlanks", "DragAndDrop", "DragTheWords", "MarkTheWords", "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", "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", "BranchChoice"];
+declare const BRANCHING_SCENARIO_ALLOWED_CHILD_TYPES: readonly ["BranchNode"];
 declare const INTERACTIVE_BOOK_ALLOWED_CHILD_TYPES: readonly ["Page"];
 /** Per-slide content (H5P Course Presentation slide row). Excludes ProgressTracker. */
-declare const SLIDE_ALLOWED_CHILD_TYPES: readonly ["Text", "Heading", "Image", "Scenario", "Reflection", "Quiz", "KnowledgeCheck", "TrueFalse", "FillInTheBlanks", "DragAndDrop", "DragTheWords", "MarkTheWords", "Accordion", "DialogCards", "Flashcards", "ImageHotspots", "FindHotspot", "FindMultipleHotspots", "ImageSlider"];
+declare const SLIDE_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"];
 declare const SLIDE_DECK_ALLOWED_CHILD_TYPES: readonly ["Slide"];
-declare const ASSESSMENT_SEQUENCE_ALLOWED_CHILD_TYPES: readonly ["TrueFalse", "FillInTheBlanks", "DragAndDrop", "DragTheWords", "MarkTheWords", "Quiz", "KnowledgeCheck", "FindHotspot", "FindMultipleHotspots"];
-type CompoundParentType = "Page" | "InteractiveBook" | "Slide" | "SlideDeck" | "AssessmentSequence";
+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" | "BranchingScenario" | "BranchNode";
 declare const COMPOUND_MAX_NESTING_DEPTH: Record<CompoundParentType, number>;
 declare function getAllowedChildTypes(parent: CompoundParentType): readonly string[];
 declare function isChildTypeAllowed(parent: CompoundParentType, childType: string): boolean;
 /** Blocks that must not nest inside Accordion (policy: no accordion-in-accordion). */
 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 = {
@@ -365,7 +149,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">;
+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">;
 type TelemetryCatalogV3Entry = {
     name: TelemetryCatalogV3EventName;
     description: string;
@@ -377,6 +161,14 @@ 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.
+ */
 declare function createTrackingClient(opts?: {
     sink?: TelemetrySink;
     batch?: {
@@ -395,95 +187,6 @@ declare function createSessionId(): string;
 
 declare function nowIso(): string;
 
-type BuildTelemetryEventContext = {
-    courseId: CourseId;
-    sessionId?: string;
-    attemptId?: string;
-    user?: TelemetryUser;
-    timestamp?: string;
-};
-type BuildTelemetryEventInput = (BuildTelemetryEventContext & {
-    name: "course_started";
-    lessonId?: LessonId;
-    data?: undefined;
-}) | (BuildTelemetryEventContext & {
-    name: "course_completed";
-    lessonId?: LessonId;
-    data?: undefined;
-}) | (BuildTelemetryEventContext & {
-    name: "lesson_started";
-    lessonId?: LessonId;
-    data?: LessonLifecycleData;
-}) | (BuildTelemetryEventContext & {
-    name: "lesson_completed";
-    lessonId?: LessonId;
-    data?: LessonLifecycleData;
-}) | (BuildTelemetryEventContext & {
-    name: "lesson_time_on_task";
-    lessonId?: LessonId;
-    data?: LessonLifecycleData;
-}) | (BuildTelemetryEventContext & {
-    name: "quiz_answered";
-    lessonId?: LessonId;
-    data: QuizAnsweredData;
-}) | (BuildTelemetryEventContext & {
-    name: "quiz_completed";
-    lessonId?: LessonId;
-    data: QuizCompletedData;
-}) | (BuildTelemetryEventContext & {
-    name: "assessment_answered";
-    lessonId?: LessonId;
-    data: AssessmentAnsweredData;
-}) | (BuildTelemetryEventContext & {
-    name: "assessment_completed";
-    lessonId?: LessonId;
-    data: AssessmentCompletedData;
-}) | (BuildTelemetryEventContext & {
-    name: "interaction";
-    lessonId?: LessonId;
-    data?: InteractionData;
-}) | (BuildTelemetryEventContext & {
-    name: "book_page_viewed";
-    lessonId?: LessonId;
-    data: BookPageViewedData;
-}) | (BuildTelemetryEventContext & {
-    name: "slide_viewed";
-    lessonId?: LessonId;
-    data: SlideViewedData;
-}) | (BuildTelemetryEventContext & {
-    name: "compound_page_viewed";
-    lessonId?: LessonId;
-    data: CompoundPageViewedData;
-}) | (BuildTelemetryEventContext & {
-    name: "hotspot_opened";
-    lessonId?: LessonId;
-    data: HotspotOpenedData;
-}) | (BuildTelemetryEventContext & {
-    name: "accordion_section_toggled";
-    lessonId?: LessonId;
-    data: AccordionSectionToggledData;
-}) | (BuildTelemetryEventContext & {
-    name: "flashcard_flipped";
-    lessonId?: LessonId;
-    data: FlashcardFlippedData;
-}) | (BuildTelemetryEventContext & {
-    name: "image_slider_changed";
-    lessonId?: LessonId;
-    data: ImageSliderChangedData;
-});
-
-/** Reset dev-warning state (tests only). */
-declare function resetTelemetryBuilderWarningsForTests(): void;
-/**
- * Build a typed telemetry event from a catalog event name and context.
- * Validates lesson-scoped events require `lessonId`.
- */
-declare function buildTelemetryEvent(opts: BuildTelemetryEventInput): TelemetryEvent;
-/**
- * Like `buildTelemetryEvent`, but returns null (with a dev warning) when quiz events lack an active lesson.
- */
-declare function tryBuildTelemetryEvent(opts: BuildTelemetryEventInput): TelemetryEvent | null;
-
 type EmitContext = {
     courseId: CourseId;
     sessionId?: string;
@@ -498,145 +201,10 @@ type TelemetryPipeline = {
     readonly sinks: readonly TelemetryPipelineSink[];
     emit(event: TelemetryEvent, ctx?: EmitContext): void | Promise<void>;
 };
+declare function isLifecycleTelemetryEvent(name: TelemetryEventName): boolean;
 declare function createTelemetryPipeline(sinks: TelemetryPipelineSink[]): TelemetryPipeline;
 declare function createTrackingPipelineSink(id: string, track: (event: TelemetryEvent) => void): TelemetryPipelineSink;
 
-type ProgressState = {
-    activeLessonId?: LessonId;
-    completedLessonIds: ReadonlySet<LessonId>;
-    courseCompleted: boolean;
-};
-type ProgressController = {
-    getState: () => ProgressState;
-    setActiveLesson: (lessonId: LessonId, startedAtMs: number) => {
-        previousLessonId?: LessonId;
-    };
-    completeLesson: (lessonId: LessonId, completedAtMs: number) => {
-        durationMs?: number;
-        didComplete: boolean;
-    };
-    completeCourse: () => {
-        didComplete: boolean;
-    };
-};
-declare function createProgressController(): ProgressController;
-
-declare const SESSION_STORAGE_KEY = "lessonkit:sessionId";
-declare function getTabSessionId(storage: StoragePort): string | null;
-declare function resolveSessionId(storage: StoragePort, provided?: string): string;
-declare function hasCourseStarted(storage: StoragePort, sessionId: string, courseId?: CourseId): boolean;
-declare function markCourseStarted(storage: StoragePort, sessionId: string, courseId?: CourseId): boolean;
-declare function hasCourseStartedEmittedToTracking(storage: StoragePort, sessionId: string, courseId?: CourseId): boolean;
-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 resetSharedVolatileSessionIdForTests(): void;
-declare function migrateCourseStartedMark(storage: StoragePort, fromSessionId: string, toSessionId: string, courseId?: CourseId): void;
-
-/** Plugin category — aligns with roadmap extension areas. */
-type LessonkitPluginKind = "analytics" | "lms" | "assessment" | "interaction" | "ai";
-type LessonkitPluginContext = {
-    courseId: CourseId;
-    sessionId?: string;
-    attemptId?: string;
-    user?: TelemetryUser;
-};
-type AssessmentScoreInput = {
-    checkId: CheckId;
-    lessonId?: LessonId;
-    response: unknown;
-};
-type AssessmentScoreResult = {
-    score: number;
-    maxScore?: number;
-    passed?: boolean;
-    feedback?: string;
-};
-/** Metadata for custom interaction blocks (renderer wiring stays in app code until 1.0). */
-type InteractionBlockRegistration = {
-    blockType: string;
-    catalogVersion?: string;
-    description?: string;
-};
-type PluginIdentity = {
-    id: string;
-    version: string;
-    kind: LessonkitPluginKind;
-    name?: string;
-};
-/** Narrow telemetry plugin contract (ISP). */
-type TelemetryPlugin = PluginIdentity & {
-    onTelemetry?: (event: TelemetryEvent, ctx: LessonkitPluginContext) => TelemetryEvent | null;
-    onTelemetryBatch?: (events: TelemetryEvent[], ctx: LessonkitPluginContext) => void;
-    wrapTrackingSink?: (sink: TelemetrySink, ctx: LessonkitPluginContext) => TelemetrySink;
-};
-/** Narrow lifecycle plugin contract (ISP). */
-type LifecyclePlugin = PluginIdentity & {
-    setup?: (ctx: LessonkitPluginContext) => void;
-    dispose?: () => void;
-};
-/** Narrow assessment plugin contract (ISP). */
-type AssessmentPlugin = PluginIdentity & {
-    kind: "assessment";
-    scoreAssessment?: (input: AssessmentScoreInput, ctx: LessonkitPluginContext) => AssessmentScoreResult | null;
-};
-/**
- * Narrow interaction metadata plugin (ISP).
- * @experimental Not wired into PluginHost; reserved for a future release.
- */
-type InteractionPlugin = PluginIdentity & {
-    interactionBlocks?: InteractionBlockRegistration[];
-};
-/**
- * Combined plugin contract (v1). Prefer segregated types for new plugins.
- * @deprecated Prefer `TelemetryPlugin`, `AssessmentPlugin`, or `LifecyclePlugin` via `define*Plugin`.
- */
-type LessonkitPlugin = PluginIdentity & Partial<Pick<TelemetryPlugin, "onTelemetry" | "onTelemetryBatch" | "wrapTrackingSink"> & Pick<LifecyclePlugin, "setup" | "dispose"> & Pick<AssessmentPlugin, "scoreAssessment"> & Pick<InteractionPlugin, "interactionBlocks">>;
-type PluginHost = {
-    readonly plugins: readonly LessonkitPlugin[];
-    setupAll: (ctx: LessonkitPluginContext) => void;
-    disposeAll: () => void;
-    runTelemetry: (event: TelemetryEvent, ctx: LessonkitPluginContext) => TelemetryEvent | null;
-    runTelemetryBatch: (events: TelemetryEvent[], ctx: LessonkitPluginContext) => TelemetryEvent[];
-    deliverTelemetryBatch: (events: TelemetryEvent[], ctx: LessonkitPluginContext) => TelemetryEvent[];
-    composeTrackingSink: (sink: TelemetrySink | undefined, ctx: LessonkitPluginContext | (() => LessonkitPluginContext)) => TelemetrySink | undefined;
-    scoreAssessment: (input: AssessmentScoreInput, ctx: LessonkitPluginContext) => AssessmentScoreResult | null;
-};
-/** Segregated plugin registry (ISP + SRP). */
-type PluginRegistry = PluginHost;
-
-type CourseLifecycleContext = {
-    courseId: CourseId;
-    sessionId: string;
-    attemptId?: string;
-    user?: TelemetryUser;
-    storage: StoragePort;
-    pluginHost: PluginRegistry | null;
-    lxpackBridge: "auto" | "off";
-};
-type CourseLifecycleDeps = {
-    emitCourseStartedEvent: (ctx: CourseLifecycleContext) => boolean;
-};
-declare function tryEmitCourseStarted(ctx: CourseLifecycleContext, deps: CourseLifecycleDeps, alreadyEmittedToSink: boolean): {
-    emitted: boolean;
-    marked: boolean;
-};
-declare function buildCourseStartedTelemetryEvent(ctx: CourseLifecycleContext): TelemetryEvent;
-type LessonCompletionEmitter = (lessonId: LessonId, durationMs?: number) => void;
-declare function completeLessonWithTelemetry(opts: {
-    progress: ProgressController;
-    lessonId: LessonId;
-    nowMs: number;
-    emitLessonCompleted: LessonCompletionEmitter;
-}): boolean;
-declare function completeCourseWithTelemetry(opts: {
-    progress: ProgressController;
-    nowMs: number;
-    emitLessonCompleted: LessonCompletionEmitter;
-    emitCourseCompleted: () => void;
-}): boolean;
-
 type LessonkitRuntimeVersion = "v1" | "v2";
 type HeadlessLessonkitPlugins = readonly LessonkitPlugin[] | PluginRegistry | null | undefined;
 type HeadlessLessonkitConfig = {
@@ -647,6 +215,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). */
@@ -656,9 +226,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;
@@ -670,6 +239,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;
@@ -678,6 +249,10 @@ 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).
+ */
 declare function createLessonkitRuntime(config: HeadlessLessonkitConfig, ports?: HeadlessRuntimePorts): HeadlessLessonkitRuntime;
 
 declare function createPluginRegistry(plugins?: readonly LessonkitPlugin[]): PluginRegistry;
@@ -696,4 +271,4 @@ declare function buildPluginContext(opts: {
     user?: TelemetryUser;
 }): LessonkitPluginContext;
 
-export { ACCORDION_FORBIDDEN_CHILD_TYPES, ASSESSMENT_SEQUENCE_ALLOWED_CHILD_TYPES, type AccordionSectionToggledData, type AssessmentAnsweredData, type AssessmentBaseProps, type AssessmentBehaviour, type AssessmentCompletedData, type AssessmentHandle, type AssessmentInteractionType, type AssessmentPlugin, type AssessmentResumeState, type AssessmentScoreInput, type AssessmentScoreResult, type AssessmentXAPIData, type BlockId, type BookPageViewedData, type BuildTelemetryEventInput, COMPOUND_MAX_NESTING_DEPTH, COMPOUND_RESUME_SCHEMA_VERSION, type CheckId, type ClockPort, type CompoundBaseProps, type CompoundHandle, type CompoundPageViewedData, type CompoundParentType, type CompoundResumeInput, type CompoundResumeState, type CourseId, type CourseLifecycleContext, type CourseLifecycleDeps, type EmitContext, type FlashcardFlippedData, type HeadlessLessonkitConfig, type HeadlessLessonkitRuntime, type HeadlessRuntimePorts, type HotspotOpenedData, ID_MAX_LENGTH, ID_PATTERN, INTERACTIVE_BOOK_ALLOWED_CHILD_TYPES, type IdentityIdPath, type IdentityValidationIssue, type IdentityValidationResult, type ImageSliderChangedData, type InteractionBlockRegistration, type InteractionData, type InteractionPlugin, type LessonCompletionEmitter, type LessonId, type LessonLifecycleData, type LessonkitPlugin, type LessonkitPluginContext, type LessonkitPluginKind, type LessonkitRuntimeVersion, type LessonkitUrn, type LessonkitUrnParts, type LifecyclePlugin, PAGE_ALLOWED_CHILD_TYPES, type PluginHost, type PluginIdentity, type PluginRegistry, type ProgressController, type ProgressState, type QuizAnsweredData, type QuizCompletedData, SESSION_STORAGE_KEY, SLIDE_ALLOWED_CHILD_TYPES, SLIDE_DECK_ALLOWED_CHILD_TYPES, type SlideViewedData, type StoragePort, TELEMETRY_EVENT_CATALOG, TELEMETRY_EVENT_CATALOG_V2, TELEMETRY_EVENT_CATALOG_V3, type TelemetryBatchSink, type TelemetryCatalogEntry, type TelemetryCatalogV2Entry, type TelemetryCatalogV3Entry, type TelemetryDataFor, type TelemetryEmitFn, type TelemetryEvent, type TelemetryEventBase, type TelemetryEventName, type TelemetryPipeline, type TelemetryPipelineSink, type TelemetryPlugin, type TelemetrySink, type TelemetryUser, type TimerPort, type TrackingClient, assertNever, assertValidId, buildCourseStartedTelemetryEvent, buildLessonkitUrn, buildPluginContext, buildTelemetryCatalog, buildTelemetryCatalogV2, buildTelemetryCatalogV3, buildTelemetryEvent, clampCompoundPageIndex, clearCompoundState, completeCourseWithTelemetry, completeLessonWithTelemetry, compoundStateStorageKey, createCompoundResumeState, createDefaultClock, createGlobalTimer, createLessonkitRuntime, createNoopStorage, createPluginRegistry, createProgressController, createSessionId, createSessionStoragePort, createTelemetryPipeline, createTrackingClient, createTrackingPipelineSink, defineAssessmentPlugin, defineLifecyclePlugin, defineTelemetryPlugin, deriveId, getAllowedChildTypes, getTabSessionId, hasCourseStarted, hasCourseStartedEmittedToTracking, hasCourseStartedPipelineDelivered, isChildTypeAllowed, loadCompoundState, markCourseStarted, markCourseStartedEmittedToTracking, markCourseStartedPipelineDelivered, migrateCourseStartedMark, nowIso, parseBlockId, parseCheckId, parseCompoundResumeState, parseCourseId, parseLessonId, resetSharedVolatileSessionIdForTests, resetStoragePortForTests, resetTelemetryBuilderWarningsForTests, resolveSessionId, saveCompoundState, slugifyId, telemetryCatalogV2Version, telemetryCatalogV3Version, telemetryCatalogVersion, tryBuildTelemetryEvent, tryEmitCourseStarted, validateId };
+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, 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, 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 };