@lessonkit/core 1.0.2 → 1.2.0

package/dist/index.d.cts

@@ -54,7 +54,45 @@ type LessonkitUrnParts = {
  */
 declare function buildLessonkitUrn(parts: LessonkitUrnParts): LessonkitUrn;
 
-type TelemetryEventName = "course_started" | "course_completed" | "lesson_started" | "lesson_completed" | "lesson_time_on_task" | "quiz_answered" | "quiz_completed" | "interaction";
+/** 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" | "compound_page_viewed" | "hotspot_opened" | "accordion_section_toggled" | "flashcard_flipped" | "image_slider_changed";
 type TelemetryUser = {
     id?: string;
     email?: string;
@@ -87,12 +125,54 @@ type QuizCompletedData = {
     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 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;
@@ -121,10 +201,42 @@ type TelemetryEvent = (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: "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, {
@@ -140,6 +252,78 @@ type TrackingClient = {
     dispose?: () => void | Promise<void>;
 };
 
+declare const COMPOUND_RESUME_SCHEMA_VERSION: 1;
+/** Serializable resume blob for a compound container (InteractiveBook, AssessmentSequence, …). */
+type CompoundResumeState = {
+    schemaVersion: typeof COMPOUND_RESUME_SCHEMA_VERSION;
+    activePageIndex: number;
+    /** Optional chapter index when nested inside InteractiveBook. */
+    activeChapterIndex?: number;
+    childStates: Record<string, AssessmentResumeState>;
+};
+type CompoundResumeInput = {
+    activePageIndex?: number;
+    activeChapterIndex?: number;
+    childStates?: Record<CheckId, AssessmentResumeState>;
+};
+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;
+/**
+ * Imperative handle for compound containers (H5P compound analogue).
+ * Parents aggregate child AssessmentHandle scores and persist navigation state.
+ */
+type CompoundHandle = {
+    getScore: () => number;
+    getMaxScore: () => number;
+    getAnswerGiven: () => boolean;
+    resetTask: () => void;
+    showSolutions: () => void;
+    getCurrentState: () => CompoundResumeState;
+    resume: (state: CompoundResumeState) => void;
+};
+type CompoundBaseProps = {
+    blockId: BlockId;
+};
+
+type StoragePort = {
+    getItem: (key: string) => string | null;
+    setItem: (key: string, value: string) => void;
+    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;
+declare function saveCompoundState(storage: StoragePort, courseId: CourseId, compoundId: BlockId, state: CompoundResumeState): void;
+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 INTERACTIVE_BOOK_ALLOWED_CHILD_TYPES: readonly ["Page"];
+declare const ASSESSMENT_SEQUENCE_ALLOWED_CHILD_TYPES: readonly ["TrueFalse", "FillInTheBlanks", "DragAndDrop", "DragTheWords", "MarkTheWords", "Quiz", "KnowledgeCheck", "FindHotspot", "FindMultipleHotspots"];
+type CompoundParentType = "Page" | "InteractiveBook" | "AssessmentSequence";
+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"];
+
 declare const telemetryCatalogVersion: 1;
 type TelemetryCatalogEntry = {
     name: TelemetryEventName;
@@ -152,6 +336,31 @@ type TelemetryCatalogEntry = {
 declare const TELEMETRY_EVENT_CATALOG: TelemetryCatalogEntry[];
 declare function buildTelemetryCatalog(): TelemetryCatalogEntry[];
 
+declare const telemetryCatalogV2Version: 2;
+type TelemetryCatalogV2Entry = {
+    name: Extract<TelemetryEventName, "assessment_answered" | "assessment_completed">;
+    description: string;
+    requiredFields: string[];
+    dataFields: string[];
+    xapiVerb: string;
+    urnPattern: string;
+};
+declare const TELEMETRY_EVENT_CATALOG_V2: TelemetryCatalogV2Entry[];
+declare function buildTelemetryCatalogV2(): TelemetryCatalogV2Entry[];
+
+declare const telemetryCatalogV3Version: 3;
+type TelemetryCatalogV3EventName = Extract<TelemetryEventName, "book_page_viewed" | "compound_page_viewed" | "hotspot_opened" | "accordion_section_toggled" | "flashcard_flipped" | "image_slider_changed">;
+type TelemetryCatalogV3Entry = {
+    name: TelemetryCatalogV3EventName;
+    description: string;
+    requiredFields: string[];
+    dataFields: string[];
+    xapiVerb: string;
+    urnPattern: string;
+};
+declare const TELEMETRY_EVENT_CATALOG_V3: TelemetryCatalogV3Entry[];
+declare function buildTelemetryCatalogV3(): TelemetryCatalogV3Entry[];
+
 declare function createTrackingClient(opts?: {
     sink?: TelemetrySink;
     batch?: {
@@ -201,11 +410,44 @@ type BuildTelemetryEventInput = (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: "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;
 /**
@@ -235,27 +477,6 @@ type TelemetryPipeline = {
 declare function createTelemetryPipeline(sinks: TelemetryPipelineSink[]): TelemetryPipeline;
 declare function createTrackingPipelineSink(id: string, track: (event: TelemetryEvent) => void): TelemetryPipelineSink;
 
-type StoragePort = {
-    getItem: (key: string) => string | null;
-    setItem: (key: string, value: string) => void;
-    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 ProgressState = {
     activeLessonId?: LessonId;
     completedLessonIds: ReadonlySet<LessonId>;
@@ -334,7 +555,10 @@ type AssessmentPlugin = PluginIdentity & {
     kind: "assessment";
     scoreAssessment?: (input: AssessmentScoreInput, ctx: LessonkitPluginContext) => AssessmentScoreResult | null;
 };
-/** Narrow interaction metadata plugin (ISP). */
+/**
+ * Narrow interaction metadata plugin (ISP).
+ * @experimental Not wired into PluginHost; reserved for a future release.
+ */
 type InteractionPlugin = PluginIdentity & {
     interactionBlocks?: InteractionBlockRegistration[];
 };
@@ -388,6 +612,7 @@ declare function completeCourseWithTelemetry(opts: {
 }): boolean;
 
 type LessonkitRuntimeVersion = "v1" | "v2";
+type HeadlessLessonkitPlugins = readonly LessonkitPlugin[] | PluginRegistry | null | undefined;
 type HeadlessLessonkitConfig = {
     courseId: CourseId;
     runtimeVersion?: LessonkitRuntimeVersion;
@@ -396,7 +621,8 @@ type HeadlessLessonkitConfig = {
         attemptId?: string;
         user?: TelemetryUser;
     };
-    plugins?: PluginRegistry | null;
+    /** Plugin list or registry; hooks run on {@link HeadlessLessonkitRuntime.track} and lifecycle emits. */
+    plugins?: HeadlessLessonkitPlugins;
 };
 type HeadlessRuntimePorts = {
     storage?: StoragePort;
@@ -408,6 +634,7 @@ type TelemetryEmitFn = {
 type HeadlessLessonkitRuntime = {
     readonly config: HeadlessLessonkitConfig;
     readonly progress: ProgressController;
+    readonly pluginHost: PluginHost | null;
     getProgressState: () => ProgressState;
     getSession: () => {
         sessionId: string;
@@ -419,14 +646,26 @@ type HeadlessLessonkitRuntime = {
     completeLesson: (lessonId: LessonId, emit: TelemetryEmitFn) => void;
     completeCourse: (emit: TelemetryEmitFn) => void;
     track: <N extends TelemetryEventName>(name: N, data: TelemetryDataFor<N> | undefined, emit: (event: TelemetryEvent) => void, lessonId?: LessonId) => void;
+    scoreAssessment: (input: AssessmentScoreInput, lessonId?: LessonId) => AssessmentScoreResult | null;
     resetForCourseChange: (courseId: CourseId) => void;
+    dispose: () => void;
 };
 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. */
 declare function defineTelemetryPlugin(plugin: TelemetryPlugin): LessonkitPlugin;
+/** Identity helper for assessment plugins; does not validate or register at import time. */
 declare function defineAssessmentPlugin(plugin: AssessmentPlugin): LessonkitPlugin;
+/** Identity helper for lifecycle plugins; does not validate or register at import time. */
 declare function defineLifecyclePlugin(plugin: LifecyclePlugin): LessonkitPlugin;
 
-export { type AssessmentPlugin, type AssessmentScoreInput, type AssessmentScoreResult, type BlockId, type BuildTelemetryEventInput, type CheckId, type ClockPort, type CourseId, type CourseLifecycleContext, type CourseLifecycleDeps, type EmitContext, type HeadlessLessonkitConfig, type HeadlessLessonkitRuntime, type HeadlessRuntimePorts, ID_MAX_LENGTH, ID_PATTERN, type IdentityIdPath, type IdentityValidationIssue, type IdentityValidationResult, 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, type PluginHost, type PluginIdentity, type PluginRegistry, type ProgressController, type ProgressState, type QuizAnsweredData, type QuizCompletedData, SESSION_STORAGE_KEY, type StoragePort, TELEMETRY_EVENT_CATALOG, type TelemetryBatchSink, type TelemetryCatalogEntry, 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, buildTelemetryCatalog, buildTelemetryEvent, completeCourseWithTelemetry, completeLessonWithTelemetry, createDefaultClock, createGlobalTimer, createLessonkitRuntime, createNoopStorage, createPluginRegistry, createProgressController, createSessionId, createSessionStoragePort, createTelemetryPipeline, createTrackingClient, createTrackingPipelineSink, defineAssessmentPlugin, defineLifecyclePlugin, defineTelemetryPlugin, deriveId, getTabSessionId, hasCourseStarted, hasCourseStartedEmittedToTracking, hasCourseStartedPipelineDelivered, markCourseStarted, markCourseStartedEmittedToTracking, markCourseStartedPipelineDelivered, migrateCourseStartedMark, nowIso, parseBlockId, parseCheckId, parseCourseId, parseLessonId, resetStoragePortForTests, resetTelemetryBuilderWarningsForTests, resolveSessionId, slugifyId, telemetryCatalogVersion, tryBuildTelemetryEvent, tryEmitCourseStarted, validateId };
+declare function buildPluginContext(opts: {
+    courseId: CourseId;
+    sessionId?: string;
+    attemptId?: string;
+    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, 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, resetStoragePortForTests, resetTelemetryBuilderWarningsForTests, resolveSessionId, saveCompoundState, slugifyId, telemetryCatalogV2Version, telemetryCatalogV3Version, telemetryCatalogVersion, tryBuildTelemetryEvent, tryEmitCourseStarted, validateId };