@lessonkit/core 1.5.0 → 1.6.0

package/dist/{testing-BFr8oEfw.d.ts → testing-CzgxF1Ru.d.ts}

@@ -21,7 +21,7 @@ declare const ID_PATTERN: RegExp;
 declare const ID_MAX_LENGTH = 64;
 
 /** H5P-aligned interaction kinds for assessment telemetry and xAPI. */
-type AssessmentInteractionType = "mcq" | "trueFalse" | "fillInBlanks" | "markTheWords" | "dragTheWords" | "dragAndDrop" | "assessmentSequence" | "findHotspot" | "findMultipleHotspots" | "summary" | "imagePairing" | "imageSequencing" | "essay" | "arithmeticQuiz" | "memoryGame";
+type AssessmentInteractionType = "mcq" | "trueFalse" | "fillInBlanks" | "markTheWords" | "dragTheWords" | "dragAndDrop" | "assessmentSequence" | "findHotspot" | "findMultipleHotspots" | "summary" | "imagePairing" | "imageSequencing" | "essay" | "arithmeticQuiz" | "memoryGame" | "combinationLock" | "crossword" | "wordSearch";
 /** Serializable resume blob for a single assessment block. */
 type AssessmentResumeState = Record<string, unknown>;
 /** Behaviour flags aligned with H5P question types. */
@@ -65,7 +65,7 @@ type McqAssessmentProps = AssessmentBaseProps & {
     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" | "branch_node_viewed" | "branch_selected";
+type TelemetryEventName = "course_started" | "course_completed" | "lesson_started" | "lesson_completed" | "lesson_time_on_task" | "quiz_answered" | "quiz_completed" | "assessment_answered" | "assessment_completed" | "interaction" | "book_page_viewed" | "slide_viewed" | "compound_page_viewed" | "hotspot_opened" | "accordion_section_toggled" | "flashcard_flipped" | "image_slider_changed" | "video_cue_reached" | "video_segment_completed" | "memory_card_flipped" | "information_wall_search" | "parallax_slide_viewed" | "questionnaire_submitted" | "branch_node_viewed" | "branch_selected" | "image_juxtaposition_changed" | "timeline_event_viewed" | "image_sequence_changed" | "audio_recording_started" | "audio_recording_completed" | "qr_content_revealed" | "advent_door_opened" | "map_stage_viewed" | "map_exit_selected";
 type TelemetryUser = {
     id?: string;
     email?: string;
@@ -196,6 +196,42 @@ type BranchSelectedData = {
     label: string;
     scoreWeight?: number;
 };
+type ImageJuxtapositionChangedData = {
+    blockId: BlockId;
+    position: number;
+};
+type TimelineEventViewedData = {
+    blockId: BlockId;
+    eventId: string;
+};
+type ImageSequenceChangedData = {
+    blockId: BlockId;
+    frameIndex: number;
+};
+type AudioRecordingData = {
+    blockId: BlockId;
+};
+type QrContentRevealedData = {
+    blockId: BlockId;
+};
+type AdventDoorOpenedData = {
+    blockId: BlockId;
+    doorId: string;
+    day: number;
+};
+type MapStageViewedData = {
+    blockId: BlockId;
+    stageId: string;
+    stageIndex: number;
+    stageLabel?: string;
+};
+type MapExitSelectedData = {
+    blockId: BlockId;
+    fromStageId: string;
+    toStageId: string;
+    label: string;
+    scoreWeight?: number;
+};
 type TelemetryEvent = (TelemetryEventBase & {
     name: "course_started";
     lessonId?: LessonId;
@@ -296,6 +332,42 @@ type TelemetryEvent = (TelemetryEventBase & {
     name: "branch_selected";
     lessonId: LessonId;
     data: BranchSelectedData;
+}) | (TelemetryEventBase & {
+    name: "image_juxtaposition_changed";
+    lessonId?: LessonId;
+    data: ImageJuxtapositionChangedData;
+}) | (TelemetryEventBase & {
+    name: "timeline_event_viewed";
+    lessonId?: LessonId;
+    data: TimelineEventViewedData;
+}) | (TelemetryEventBase & {
+    name: "image_sequence_changed";
+    lessonId?: LessonId;
+    data: ImageSequenceChangedData;
+}) | (TelemetryEventBase & {
+    name: "audio_recording_started";
+    lessonId?: LessonId;
+    data: AudioRecordingData;
+}) | (TelemetryEventBase & {
+    name: "audio_recording_completed";
+    lessonId?: LessonId;
+    data: AudioRecordingData;
+}) | (TelemetryEventBase & {
+    name: "qr_content_revealed";
+    lessonId?: LessonId;
+    data: QrContentRevealedData;
+}) | (TelemetryEventBase & {
+    name: "advent_door_opened";
+    lessonId?: LessonId;
+    data: AdventDoorOpenedData;
+}) | (TelemetryEventBase & {
+    name: "map_stage_viewed";
+    lessonId: LessonId;
+    data: MapStageViewedData;
+}) | (TelemetryEventBase & {
+    name: "map_exit_selected";
+    lessonId: LessonId;
+    data: MapExitSelectedData;
 });
 /** Payload shape for a telemetry event name. */
 type TelemetryDataFor<N extends TelemetryEventName> = Extract<TelemetryEvent, {
@@ -446,6 +518,42 @@ type BuildTelemetryEventInput = (BuildTelemetryEventContext & {
     name: "branch_selected";
     lessonId?: LessonId;
     data: BranchSelectedData;
+}) | (BuildTelemetryEventContext & {
+    name: "image_juxtaposition_changed";
+    lessonId?: LessonId;
+    data: ImageJuxtapositionChangedData;
+}) | (BuildTelemetryEventContext & {
+    name: "timeline_event_viewed";
+    lessonId?: LessonId;
+    data: TimelineEventViewedData;
+}) | (BuildTelemetryEventContext & {
+    name: "image_sequence_changed";
+    lessonId?: LessonId;
+    data: ImageSequenceChangedData;
+}) | (BuildTelemetryEventContext & {
+    name: "audio_recording_started";
+    lessonId?: LessonId;
+    data: AudioRecordingData;
+}) | (BuildTelemetryEventContext & {
+    name: "audio_recording_completed";
+    lessonId?: LessonId;
+    data: AudioRecordingData;
+}) | (BuildTelemetryEventContext & {
+    name: "qr_content_revealed";
+    lessonId?: LessonId;
+    data: QrContentRevealedData;
+}) | (BuildTelemetryEventContext & {
+    name: "advent_door_opened";
+    lessonId?: LessonId;
+    data: AdventDoorOpenedData;
+}) | (BuildTelemetryEventContext & {
+    name: "map_stage_viewed";
+    lessonId?: LessonId;
+    data: MapStageViewedData;
+}) | (BuildTelemetryEventContext & {
+    name: "map_exit_selected";
+    lessonId?: LessonId;
+    data: MapExitSelectedData;
 });
 
 /** Reset dev-warning state (tests only). */
@@ -453,6 +561,18 @@ declare function resetTelemetryBuilderWarningsForTests(): void;
 /**
  * Build a typed telemetry event from a catalog event name and context.
  * Validates lesson-scoped events require `lessonId`.
+ *
+ * @example
+ * ```ts
+ * import { buildTelemetryEvent } from "@lessonkit/core";
+ *
+ * const event = buildTelemetryEvent({
+ *   name: "lesson_completed",
+ *   courseId: "sec-101",
+ *   lessonId: "phishing-101",
+ *   sessionId: "tab-abc",
+ * });
+ * ```
  */
 declare function buildTelemetryEvent(opts: BuildTelemetryEventInput): TelemetryEvent;
 /**
@@ -592,12 +712,38 @@ declare function tryEmitCourseStarted(ctx: CourseLifecycleContext, deps: CourseL
 }>;
 declare function buildCourseStartedTelemetryEvent(ctx: CourseLifecycleContext): TelemetryEvent;
 type LessonCompletionEmitter = (lessonId: LessonId, durationMs?: number) => void;
+/**
+ * Mark a lesson complete in progress state and emit `lesson_completed` when newly completed.
+ *
+ * @example
+ * ```ts
+ * completeLessonWithTelemetry({
+ *   progress,
+ *   lessonId: "lesson-1",
+ *   nowMs: Date.now(),
+ *   emitLessonCompleted: (id, durationMs) => track("lesson_completed", { lessonId: id, durationMs }),
+ * });
+ * ```
+ */
 declare function completeLessonWithTelemetry(opts: {
     progress: ProgressController;
     lessonId: LessonId;
     nowMs: number;
     emitLessonCompleted: LessonCompletionEmitter;
 }): boolean;
+/**
+ * Complete the active lesson (if any), then mark the course complete and emit `course_completed`.
+ *
+ * @example
+ * ```ts
+ * completeCourseWithTelemetry({
+ *   progress,
+ *   nowMs: Date.now(),
+ *   emitLessonCompleted: (id) => track("lesson_completed", { lessonId: id }),
+ *   emitCourseCompleted: () => track("course_completed", {}),
+ * });
+ * ```
+ */
 declare function completeCourseWithTelemetry(opts: {
     progress: ProgressController;
     nowMs: number;

package/dist/testing.d.cts

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

package/dist/testing.d.ts

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

package/dist/testing.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lessonkit/core",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "private": false,
   "description": "Shared types and telemetry primitives for LessonKit.",
   "license": "Apache-2.0",

package/telemetry-catalog.v3.json

@@ -249,6 +249,146 @@
       ],
       "xapiVerb": "http://adlnet.gov/expapi/verbs/answered",
       "urnPattern": "urn:lessonkit:course:{courseId}:lesson:{lessonId}:block:{blockId}:node:{toNodeId}"
+    },
+    {
+      "name": "image_juxtaposition_changed",
+      "description": "Learner adjusted the before/after divider",
+      "requiredFields": [
+        "courseId",
+        "sessionId",
+        "timestamp"
+      ],
+      "dataFields": [
+        "blockId",
+        "position"
+      ],
+      "xapiVerb": "http://adlnet.gov/expapi/verbs/interacted",
+      "urnPattern": "urn:lessonkit:course:{courseId}:lesson:{lessonId}:block:{blockId}"
+    },
+    {
+      "name": "timeline_event_viewed",
+      "description": "Learner focused a timeline event",
+      "requiredFields": [
+        "courseId",
+        "sessionId",
+        "timestamp"
+      ],
+      "dataFields": [
+        "blockId",
+        "eventId"
+      ],
+      "xapiVerb": "http://adlnet.gov/expapi/verbs/experienced",
+      "urnPattern": "urn:lessonkit:course:{courseId}:lesson:{lessonId}:block:{blockId}"
+    },
+    {
+      "name": "image_sequence_changed",
+      "description": "Learner changed the image sequence frame",
+      "requiredFields": [
+        "courseId",
+        "sessionId",
+        "timestamp"
+      ],
+      "dataFields": [
+        "blockId",
+        "frameIndex"
+      ],
+      "xapiVerb": "http://adlnet.gov/expapi/verbs/interacted",
+      "urnPattern": "urn:lessonkit:course:{courseId}:lesson:{lessonId}:block:{blockId}"
+    },
+    {
+      "name": "audio_recording_started",
+      "description": "Learner started an audio recording",
+      "requiredFields": [
+        "courseId",
+        "sessionId",
+        "timestamp"
+      ],
+      "dataFields": [
+        "blockId"
+      ],
+      "xapiVerb": "http://adlnet.gov/expapi/verbs/interacted",
+      "urnPattern": "urn:lessonkit:course:{courseId}:lesson:{lessonId}:block:{blockId}"
+    },
+    {
+      "name": "audio_recording_completed",
+      "description": "Learner completed an audio recording",
+      "requiredFields": [
+        "courseId",
+        "sessionId",
+        "timestamp"
+      ],
+      "dataFields": [
+        "blockId"
+      ],
+      "xapiVerb": "http://adlnet.gov/expapi/verbs/completed",
+      "urnPattern": "urn:lessonkit:course:{courseId}:lesson:{lessonId}:block:{blockId}"
+    },
+    {
+      "name": "qr_content_revealed",
+      "description": "Learner revealed QR hidden content",
+      "requiredFields": [
+        "courseId",
+        "sessionId",
+        "timestamp"
+      ],
+      "dataFields": [
+        "blockId"
+      ],
+      "xapiVerb": "http://adlnet.gov/expapi/verbs/experienced",
+      "urnPattern": "urn:lessonkit:course:{courseId}:lesson:{lessonId}:block:{blockId}"
+    },
+    {
+      "name": "advent_door_opened",
+      "description": "Learner opened an advent calendar door",
+      "requiredFields": [
+        "courseId",
+        "sessionId",
+        "timestamp"
+      ],
+      "dataFields": [
+        "blockId",
+        "doorId",
+        "day"
+      ],
+      "xapiVerb": "http://adlnet.gov/expapi/verbs/interacted",
+      "urnPattern": "urn:lessonkit:course:{courseId}:lesson:{lessonId}:block:{blockId}"
+    },
+    {
+      "name": "map_stage_viewed",
+      "description": "Learner viewed a stage in a GameMap",
+      "requiredFields": [
+        "courseId",
+        "lessonId",
+        "sessionId",
+        "timestamp"
+      ],
+      "dataFields": [
+        "blockId",
+        "stageId",
+        "stageIndex",
+        "stageLabel"
+      ],
+      "xapiVerb": "http://adlnet.gov/expapi/verbs/experienced",
+      "urnPattern": "urn:lessonkit:course:{courseId}:lesson:{lessonId}:block:{blockId}:stage:{stageId}"
+    },
+    {
+      "name": "map_exit_selected",
+      "description": "Learner selected a map exit in a GameMap",
+      "requiredFields": [
+        "courseId",
+        "lessonId",
+        "sessionId",
+        "timestamp"
+      ],
+      "dataFields": [
+        "blockId",
+        "fromStageId",
+        "toStageId",
+        "label",
+        "scoreWeight"
+      ],
+      "xapiVerb": "http://adlnet.gov/expapi/verbs/answered",
+      "urnPattern": "urn:lessonkit:course:{courseId}:lesson:{lessonId}:block:{blockId}:stage:{toStageId}"
     }
   ]
 }