@lessonkit/core 1.3.0 → 1.4.0

package/dist/testing-BhVGckZ5.d.ts

@@ -0,0 +1,569 @@
+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;
+
+/** 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";
+/** 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;
+};
+/** MCQ assessment props shared by React components and LMS packaging descriptors. */
+type McqAssessmentProps = AssessmentBaseProps & {
+    kind?: "mcq";
+    question: string;
+    choices: string[];
+    answer: string;
+};
+
+type TelemetryEventName = "course_started" | "course_completed" | "lesson_started" | "lesson_completed" | "lesson_time_on_task" | "quiz_answered" | "quiz_completed" | "assessment_answered" | "assessment_completed" | "interaction" | "book_page_viewed" | "slide_viewed" | "compound_page_viewed" | "hotspot_opened" | "accordion_section_toggled" | "flashcard_flipped" | "image_slider_changed" | "video_cue_reached" | "video_segment_completed" | "memory_card_flipped" | "information_wall_search" | "parallax_slide_viewed" | "questionnaire_submitted";
+type 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 VideoCueReachedData = {
+    blockId: BlockId;
+    cueIndex: number;
+    atSeconds: number;
+    cueLabel?: string;
+};
+type VideoSegmentCompletedData = {
+    blockId: BlockId;
+    segmentIndex: number;
+    atSeconds: number;
+    segmentLabel?: string;
+};
+type MemoryCardFlippedData = {
+    blockId: BlockId;
+    cardIndex: number;
+    face: "front" | "back";
+};
+type InformationWallSearchData = {
+    blockId: BlockId;
+    query: string;
+    resultCount: number;
+};
+type ParallaxSlideViewedData = {
+    blockId: BlockId;
+    slideIndex: number;
+};
+type QuestionnaireSubmittedData = {
+    blockId: BlockId;
+    fieldCount: 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;
+}) | (TelemetryEventBase & {
+    name: "video_cue_reached";
+    lessonId: LessonId;
+    data: VideoCueReachedData;
+}) | (TelemetryEventBase & {
+    name: "video_segment_completed";
+    lessonId: LessonId;
+    data: VideoSegmentCompletedData;
+}) | (TelemetryEventBase & {
+    name: "memory_card_flipped";
+    lessonId?: LessonId;
+    data: MemoryCardFlippedData;
+}) | (TelemetryEventBase & {
+    name: "information_wall_search";
+    lessonId?: LessonId;
+    data: InformationWallSearchData;
+}) | (TelemetryEventBase & {
+    name: "parallax_slide_viewed";
+    lessonId?: LessonId;
+    data: ParallaxSlideViewedData;
+}) | (TelemetryEventBase & {
+    name: "questionnaire_submitted";
+    lessonId: LessonId;
+    data: QuestionnaireSubmittedData;
+});
+/** 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;
+    /** Delivers one event and resolves to true only when the sink accepted it (batch: includes flush). */
+    deliver?: (event: TelemetryEvent) => Promise<boolean>;
+    /** Resolves to true when all buffered events were delivered; false when a sink failure re-queued events. */
+    flush?: () => void | Promise<boolean>;
+    /** Best-effort synchronous flush for pagehide (keepalive batch sink when configured). */
+    flushOnExit?: () => void;
+    dispose?: () => void | Promise<void>;
+};
+
+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;
+
+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;
+}) | (BuildTelemetryEventContext & {
+    name: "video_cue_reached";
+    lessonId?: LessonId;
+    data: VideoCueReachedData;
+}) | (BuildTelemetryEventContext & {
+    name: "video_segment_completed";
+    lessonId?: LessonId;
+    data: VideoSegmentCompletedData;
+}) | (BuildTelemetryEventContext & {
+    name: "memory_card_flipped";
+    lessonId?: LessonId;
+    data: MemoryCardFlippedData;
+}) | (BuildTelemetryEventContext & {
+    name: "information_wall_search";
+    lessonId?: LessonId;
+    data: InformationWallSearchData;
+}) | (BuildTelemetryEventContext & {
+    name: "parallax_slide_viewed";
+    lessonId?: LessonId;
+    data: ParallaxSlideViewedData;
+}) | (BuildTelemetryEventContext & {
+    name: "questionnaire_submitted";
+    lessonId?: LessonId;
+    data: QuestionnaireSubmittedData;
+});
+
+/** 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 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;
+
+/** @internal Reset in-flight course_started guard between tests. */
+declare function resetCourseStartedEmitFlightForTests(): void;
+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;
+
+export { type SlideViewedData as $, type AccordionSectionToggledData as A, type BlockId as B, type CheckId as C, type InteractionPlugin as D, type LessonId as E, type FlashcardFlippedData as F, type LessonLifecycleData as G, type HotspotOpenedData as H, ID_MAX_LENGTH as I, type LessonkitPlugin as J, type LessonkitPluginContext as K, type LessonCompletionEmitter as L, type LessonkitPluginKind as M, type LessonkitUrn as N, type LifecyclePlugin as O, type McqAssessmentProps as P, type MemoryCardFlippedData as Q, type ParallaxSlideViewedData as R, type PluginHost as S, type PluginIdentity as T, type PluginRegistry as U, type ProgressController as V, type ProgressState as W, type QuestionnaireSubmittedData as X, type QuizAnsweredData as Y, type QuizCompletedData as Z, SESSION_STORAGE_KEY as _, type AssessmentAnsweredData as a, type StoragePort as a0, type TelemetryBatchSink as a1, type TelemetryDataFor as a2, type TelemetryEvent as a3, type TelemetryEventBase as a4, type TelemetryEventName as a5, type TelemetryPlugin as a6, type TelemetrySink as a7, type TelemetryUser as a8, type TimerPort as a9, tryEmitCourseStarted as aA, type TrackingClient as aa, type VideoCueReachedData as ab, type VideoSegmentCompletedData as ac, buildCourseStartedTelemetryEvent as ad, buildTelemetryEvent as ae, completeCourseWithTelemetry as af, completeLessonWithTelemetry as ag, createDefaultClock as ah, createGlobalTimer as ai, createNoopStorage as aj, createProgressController as ak, createSessionStoragePort as al, getTabSessionId as am, hasCourseStarted as an, hasCourseStartedEmittedToTracking as ao, hasCourseStartedPipelineDelivered as ap, markCourseStarted as aq, markCourseStartedEmittedToTracking as ar, markCourseStartedPipelineDelivered as as, migrateCourseStartedMark as at, resetCourseStartedEmitFlightForTests as au, resetSharedVolatileSessionIdForTests as av, resetStoragePortForTests as aw, resetTelemetryBuilderWarningsForTests as ax, resolveSessionId as ay, tryBuildTelemetryEvent as az, type AssessmentBaseProps as b, type AssessmentBehaviour as c, type AssessmentCompletedData as d, type AssessmentHandle as e, type AssessmentInteractionType as f, type AssessmentPlugin as g, type AssessmentResumeState as h, type AssessmentScoreInput as i, type AssessmentScoreResult as j, type AssessmentXAPIData as k, type BookPageViewedData as l, type BuildTelemetryEventInput as m, type ClockPort as n, type CompoundPageViewedData as o, type CourseId as p, type CourseLifecycleContext as q, type CourseLifecycleDeps as r, ID_PATTERN as s, type IdentityIdPath as t, type IdentityValidationIssue as u, type IdentityValidationResult as v, type ImageSliderChangedData as w, type InformationWallSearchData as x, type InteractionBlockRegistration as y, type InteractionData as z };

package/dist/testing.cjs

@@ -0,0 +1,60 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/testing.ts
+var testing_exports = {};
+__export(testing_exports, {
+  resetCourseStartedEmitFlightForTests: () => resetCourseStartedEmitFlightForTests,
+  resetSharedVolatileSessionIdForTests: () => resetSharedVolatileSessionIdForTests,
+  resetStoragePortForTests: () => resetStoragePortForTests,
+  resetTelemetryBuilderWarningsForTests: () => resetTelemetryBuilderWarningsForTests
+});
+module.exports = __toCommonJS(testing_exports);
+
+// src/telemetryBuilder.ts
+var warnedMissingQuizLesson = false;
+var warnedMissingAssessmentLesson = false;
+function resetTelemetryBuilderWarningsForTests() {
+  warnedMissingQuizLesson = false;
+  warnedMissingAssessmentLesson = false;
+}
+
+// src/ports.ts
+function resetStoragePortForTests(storage) {
+  storage.resetForTests?.();
+}
+
+// src/session.ts
+var sharedVolatileSessionId = null;
+function resetSharedVolatileSessionIdForTests() {
+  sharedVolatileSessionId = null;
+}
+
+// src/runtime/courseLifecycle.ts
+var courseStartedEmitFlights = /* @__PURE__ */ new Set();
+function resetCourseStartedEmitFlightForTests() {
+  courseStartedEmitFlights.clear();
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  resetCourseStartedEmitFlightForTests,
+  resetSharedVolatileSessionIdForTests,
+  resetStoragePortForTests,
+  resetTelemetryBuilderWarningsForTests
+});

package/dist/testing.d.cts

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

package/dist/testing.d.ts

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

package/dist/testing.js

@@ -0,0 +1,12 @@
+import {
+  resetCourseStartedEmitFlightForTests,
+  resetSharedVolatileSessionIdForTests,
+  resetStoragePortForTests,
+  resetTelemetryBuilderWarningsForTests
+} from "./chunk-PEWFPVQ6.js";
+export {
+  resetCourseStartedEmitFlightForTests,
+  resetSharedVolatileSessionIdForTests,
+  resetStoragePortForTests,
+  resetTelemetryBuilderWarningsForTests
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lessonkit/core",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "private": false,
   "description": "Shared types and telemetry primitives for LessonKit.",
   "license": "Apache-2.0",
@@ -30,6 +30,11 @@
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
     },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.js",
+      "require": "./dist/testing.cjs"
+    },
     "./telemetry-catalog.v1.json": "./telemetry-catalog.v1.json",
     "./telemetry-catalog.v2.json": "./telemetry-catalog.v2.json",
     "./telemetry-catalog.v3.json": "./telemetry-catalog.v3.json",
@@ -43,8 +48,8 @@
     "identity-contract.v1.json"
   ],
   "scripts": {
-    "build": "tsup src/index.ts --format esm,cjs --dts",
-    "dev": "tsup src/index.ts --format esm,cjs --dts --watch",
+    "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",
     "prepublishOnly": "npm run build",
     "typecheck": "tsc -p tsconfig.json",
     "test": "vitest run --passWithNoTests",
@@ -52,7 +57,7 @@
     "lint": "echo \"(no lint configured yet)\""
   },
   "devDependencies": {
-    "@types/node": "^22.13.10",
+    "@types/node": "^25.9.2",
     "tsup": "^8.5.0",
     "typescript": "^5.8.3",
     "vitest": "^4.1.8"