@lessonkit/core 1.6.0 → 1.7.1

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { C as CourseId, L as LessonId, a as CheckId, B as BlockId, I as IdentityIdPath, b as IdentityValidationResult, c as LessonkitUrn, A as AssessmentResumeState, S as StoragePort, T as TelemetryEventName, d as TelemetrySink, e as TelemetryBatchSink, f as TrackingClient, g as TelemetryEvent, h as TelemetryUser, i as LessonkitPlugin, P as PluginRegistry, j as ProgressController, k as PluginHost, l as ProgressState, m as TelemetryDataFor, n as AssessmentScoreInput, o as AssessmentScoreResult, p as ClockPort, q as AssessmentPlugin, r as LifecyclePlugin, s as TelemetryPlugin, t as LessonkitPluginContext } from './testing-CzgxF1Ru.js';
-export { u as AccordionSectionToggledData, v as AssessmentAnsweredData, w as AssessmentBaseProps, x as AssessmentBehaviour, y as AssessmentCompletedData, z as AssessmentHandle, D as AssessmentInteractionType, E as AssessmentXAPIData, F as BookPageViewedData, G as BranchNodeViewedData, H as BranchSelectedData, J as BuildTelemetryEventInput, K as CompoundPageViewedData, M as CourseLifecycleContext, N as CourseLifecycleDeps, O as FlashcardFlippedData, Q as HotspotOpenedData, R as ID_MAX_LENGTH, U as ID_PATTERN, V as IdentityValidationIssue, W as ImageSliderChangedData, X as InformationWallSearchData, Y as InteractionBlockRegistration, Z as InteractionData, _ as InteractionPlugin, $ as LessonCompletionEmitter, a0 as LessonLifecycleData, a1 as LessonkitPluginKind, a2 as McqAssessmentProps, a3 as MemoryCardFlippedData, a4 as ParallaxSlideViewedData, a5 as PluginIdentity, a6 as QuestionnaireSubmittedData, a7 as QuizAnsweredData, a8 as QuizCompletedData, a9 as SESSION_STORAGE_KEY, aa as SlideViewedData, ab as TelemetryEventBase, ac as TimerPort, ad as VideoCueReachedData, ae as VideoSegmentCompletedData, af as buildCourseStartedTelemetryEvent, ag as buildTelemetryEvent, ah as completeCourseWithTelemetry, ai as completeLessonWithTelemetry, aj as createDefaultClock, ak as createGlobalTimer, al as createNoopStorage, am as createProgressController, an as createSessionStoragePort, ao as getTabSessionId, ap as hasCourseStarted, aq as hasCourseStartedEmittedToTracking, ar as hasCourseStartedPipelineDelivered, as as hasCourseStartedXapiSent, at as markCourseStarted, au as markCourseStartedEmittedToTracking, av as markCourseStartedPipelineDelivered, aw as markCourseStartedXapiSent, ax as migrateCourseStartedMark, ay as resetSharedVolatileSessionIdForTests, az as resetStoragePortForTests, aA as resetTelemetryBuilderWarningsForTests, aB as resolveSessionId, aC as tryBuildTelemetryEvent, aD as tryEmitCourseStarted } from './testing-CzgxF1Ru.js';
+import { C as CourseId, L as LessonId, a as CheckId, B as BlockId, I as IdentityIdPath, b as IdentityValidationResult, c as LessonkitUrn, M as McqAssessmentProps, 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-CQ-ZsT7D.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, N as CourseLifecycleContext, O as CourseLifecycleDeps, Q as FlashcardFlippedData, R as HotspotOpenedData, U as ID_MAX_LENGTH, V as ID_PATTERN, W as IdentityValidationIssue, X as ImageSliderChangedData, Y as InformationWallSearchData, Z as InteractionBlockRegistration, _ as InteractionData, $ as InteractionPlugin, a0 as InvalidSessionIdContext, a1 as LessonCompletionEmitter, a2 as LessonLifecycleData, a3 as LessonkitPluginKind, a4 as MemoryCardFlippedData, a5 as ParallaxSlideViewedData, a6 as PluginIdentity, a7 as QuestionnaireSubmittedData, a8 as QuizAnsweredData, a9 as QuizCompletedData, aa as ResolveSessionIdOptions, ab as SESSION_STORAGE_KEY, ac as SlideViewedData, ad as TelemetryEventBase, ae as TimerPort, af as VideoCueReachedData, ag as VideoSegmentCompletedData, ah as buildCourseStartedTelemetryEvent, ai as buildTelemetryEvent, aj as completeCourseWithTelemetry, ak as completeLessonWithTelemetry, al as createDefaultClock, am as createGlobalTimer, an as createNoopStorage, ao as createProgressController, ap as createSessionStoragePort, aq as getTabSessionId, ar as hasCourseStarted, as as hasCourseStartedEmittedToTracking, at as hasCourseStartedPipelineDelivered, au as hasCourseStartedXapiSent, av as markCourseStarted, aw as markCourseStartedEmittedToTracking, ax as markCourseStartedPipelineDelivered, ay as markCourseStartedXapiSent, az as migrateCourseStartedMark, aA as resetSharedVolatileSessionIdForTests, aB as resetStoragePortForTests, aC as resetTelemetryBuilderWarningsForTests, aD as resolveSessionId, aE as tryBuildTelemetryEvent, aF as tryEmitCourseStarted } from './testing-CQ-ZsT7D.js';
 
 /**
  * Exhaustiveness helper for switch/default branches.
@@ -36,6 +36,22 @@ type LessonkitUrnParts = {
  */
 declare function buildLessonkitUrn(parts: LessonkitUrnParts): LessonkitUrn;
 
+type McqScoreResult = {
+    score: number;
+    maxScore: number;
+    exactMatch: boolean;
+    hasWrongSelection: boolean;
+    passedThreshold: boolean;
+};
+/** Correct answer labels for scoring (multi-select uses `answers` when length > 1). */
+declare function resolveMcqCorrectAnswers(props: Pick<McqAssessmentProps, "answer" | "answers">): Set<string>;
+declare function isMultiSelectMcq(props: Pick<McqAssessmentProps, "answers">): boolean;
+declare function scoreMcqSelection(selected: string | string[] | null | undefined, correct: Set<string>, multi: boolean, passingScore?: number): McqScoreResult;
+/** Deterministic Fisher–Yates shuffle; returns display order indices. */
+declare function shuffleChoiceIndices(length: number, seed: string | number): number[];
+declare function resolveMcqShuffleSeed(props: Pick<McqAssessmentProps, "checkId" | "shuffleSeed">): string | number;
+declare function orderChoicesByIndices(choices: string[], orderIndices: number[]): string[];
+
 /** LMS parent-bridge forwarding mode for packaged course runtimes. */
 type LmsBridgeMode = "auto" | "off";
 
@@ -88,21 +104,24 @@ declare function saveCompoundState(storage: StoragePort, courseId: CourseId, com
 declare function clearCompoundState(storage: StoragePort, courseId: CourseId, compoundId: BlockId): void;
 
 /** Canonical compound child allowlists (H5P sub-content curation). */
-declare const PAGE_ALLOWED_CHILD_TYPES: readonly ["Text", "Heading", "Image", "Video", "Scenario", "Reflection", "Quiz", "KnowledgeCheck", "TrueFalse", "FillInTheBlanks", "DragAndDrop", "DragTheWords", "MarkTheWords", "Summary", "ImagePairing", "ImageSequencing", "MemoryGame", "InformationWall", "ParallaxSlideshow", "Questionnaire", "Essay", "ArithmeticQuiz", "Accordion", "DialogCards", "Flashcards", "ImageHotspots", "FindHotspot", "FindMultipleHotspots", "ImageSlider", "Embed", "Chart", "Table", "ImageJuxtaposition", "Timeline", "ImageSequence", "Collage", "AudioRecorder", "CombinationLock", "QrContent", "Crossword", "AdventCalendar", "ProgressTracker"];
+/** Tier B P1 assessments shipped in framework 1.7.0. */
+declare const ASSESSMENT_17_CHILD_TYPES: readonly ["SortParagraphs", "GuessTheAnswer", "MultimediaChoice"];
+declare const PAGE_ALLOWED_CHILD_TYPES: readonly ["Text", "Heading", "Image", "Video", "Scenario", "Reflection", "Quiz", "KnowledgeCheck", "TrueFalse", "FillInTheBlanks", "DragAndDrop", "DragTheWords", "MarkTheWords", "Summary", "ImagePairing", "ImageSequencing", "MemoryGame", "InformationWall", "ParallaxSlideshow", "Questionnaire", "Essay", "ArithmeticQuiz", "Accordion", "DialogCards", "Flashcards", "ImageHotspots", "FindHotspot", "FindMultipleHotspots", "ImageSlider", "Embed", "Chart", "Table", "ImageJuxtaposition", "Timeline", "ImageSequence", "Collage", "AudioRecorder", "CombinationLock", "QrContent", "Crossword", "AdventCalendar", "ProgressTracker", "SortParagraphs", "GuessTheAnswer", "MultimediaChoice"];
 /** Branch node content (Page-like minus ProgressTracker). */
-declare const BRANCH_NODE_ALLOWED_CHILD_TYPES: readonly ["Text", "Heading", "Image", "Video", "Scenario", "Reflection", "Quiz", "KnowledgeCheck", "TrueFalse", "FillInTheBlanks", "DragAndDrop", "DragTheWords", "MarkTheWords", "Summary", "ImagePairing", "ImageSequencing", "MemoryGame", "InformationWall", "ParallaxSlideshow", "Questionnaire", "Essay", "ArithmeticQuiz", "Accordion", "DialogCards", "Flashcards", "ImageHotspots", "FindHotspot", "FindMultipleHotspots", "ImageSlider", "Embed", "Chart", "Table", "ImageJuxtaposition", "Timeline", "ImageSequence", "Collage", "AudioRecorder", "CombinationLock", "QrContent", "Crossword", "AdventCalendar", "BranchChoice"];
+declare const BRANCH_NODE_ALLOWED_CHILD_TYPES: readonly ["Text", "Heading", "Image", "Video", "Scenario", "Reflection", "Quiz", "KnowledgeCheck", "TrueFalse", "FillInTheBlanks", "DragAndDrop", "DragTheWords", "MarkTheWords", "Summary", "ImagePairing", "ImageSequencing", "MemoryGame", "InformationWall", "ParallaxSlideshow", "Questionnaire", "Essay", "ArithmeticQuiz", "Accordion", "DialogCards", "Flashcards", "ImageHotspots", "FindHotspot", "FindMultipleHotspots", "ImageSlider", "Embed", "Chart", "Table", "ImageJuxtaposition", "Timeline", "ImageSequence", "Collage", "AudioRecorder", "CombinationLock", "QrContent", "Crossword", "AdventCalendar", "BranchChoice", "SortParagraphs", "GuessTheAnswer", "MultimediaChoice"];
 declare const BRANCHING_SCENARIO_ALLOWED_CHILD_TYPES: readonly ["BranchNode"];
 declare const GAME_MAP_ALLOWED_CHILD_TYPES: readonly ["MapStage"];
 /** Map stage content (BranchNode parity; WordSearch excluded from compounds). */
-declare const MAP_STAGE_ALLOWED_CHILD_TYPES: readonly ["Text", "Heading", "Image", "Video", "Scenario", "Reflection", "Quiz", "KnowledgeCheck", "TrueFalse", "FillInTheBlanks", "DragAndDrop", "DragTheWords", "MarkTheWords", "Summary", "ImagePairing", "ImageSequencing", "MemoryGame", "InformationWall", "ParallaxSlideshow", "Questionnaire", "Essay", "ArithmeticQuiz", "Accordion", "DialogCards", "Flashcards", "ImageHotspots", "FindHotspot", "FindMultipleHotspots", "ImageSlider", "Embed", "Chart", "Table", "ImageJuxtaposition", "Timeline", "ImageSequence", "Collage", "AudioRecorder", "CombinationLock", "QrContent", "Crossword", "AdventCalendar", "MapExit"];
+declare const MAP_STAGE_ALLOWED_CHILD_TYPES: readonly ["Text", "Heading", "Image", "Video", "Scenario", "Reflection", "Quiz", "KnowledgeCheck", "TrueFalse", "FillInTheBlanks", "DragAndDrop", "DragTheWords", "MarkTheWords", "Summary", "ImagePairing", "ImageSequencing", "MemoryGame", "InformationWall", "ParallaxSlideshow", "Questionnaire", "Essay", "ArithmeticQuiz", "Accordion", "DialogCards", "Flashcards", "ImageHotspots", "FindHotspot", "FindMultipleHotspots", "ImageSlider", "Embed", "Chart", "Table", "ImageJuxtaposition", "Timeline", "ImageSequence", "Collage", "AudioRecorder", "CombinationLock", "QrContent", "Crossword", "AdventCalendar", "MapExit", "SortParagraphs", "GuessTheAnswer", "MultimediaChoice"];
 declare const INTERACTIVE_BOOK_ALLOWED_CHILD_TYPES: readonly ["Page"];
 /** Per-slide content (H5P Course Presentation slide row). Excludes ProgressTracker. */
-declare const SLIDE_ALLOWED_CHILD_TYPES: readonly ["Text", "Heading", "Image", "Video", "Scenario", "Reflection", "Quiz", "KnowledgeCheck", "TrueFalse", "FillInTheBlanks", "DragAndDrop", "DragTheWords", "MarkTheWords", "Summary", "ImagePairing", "ImageSequencing", "MemoryGame", "InformationWall", "ParallaxSlideshow", "Questionnaire", "Essay", "ArithmeticQuiz", "Accordion", "DialogCards", "Flashcards", "ImageHotspots", "FindHotspot", "FindMultipleHotspots", "ImageSlider", "Embed", "Chart", "Table", "ImageJuxtaposition", "Timeline", "ImageSequence", "Collage", "AudioRecorder", "CombinationLock", "QrContent", "Crossword", "AdventCalendar"];
+declare const SLIDE_ALLOWED_CHILD_TYPES: readonly ["Text", "Heading", "Image", "Video", "Scenario", "Reflection", "Quiz", "KnowledgeCheck", "TrueFalse", "FillInTheBlanks", "DragAndDrop", "DragTheWords", "MarkTheWords", "Summary", "ImagePairing", "ImageSequencing", "MemoryGame", "InformationWall", "ParallaxSlideshow", "Questionnaire", "Essay", "ArithmeticQuiz", "Accordion", "DialogCards", "Flashcards", "ImageHotspots", "FindHotspot", "FindMultipleHotspots", "ImageSlider", "Embed", "Chart", "Table", "ImageJuxtaposition", "Timeline", "ImageSequence", "Collage", "AudioRecorder", "CombinationLock", "QrContent", "Crossword", "AdventCalendar", "SortParagraphs", "GuessTheAnswer", "MultimediaChoice"];
 declare const SLIDE_DECK_ALLOWED_CHILD_TYPES: readonly ["Slide"];
-declare const TIMED_CUE_ALLOWED_CHILD_TYPES: readonly ["Text", "Heading", "Image", "Quiz", "TrueFalse", "FillInTheBlanks", "Summary", "ImagePairing", "ImageSequencing", "MemoryGame", "Questionnaire", "Essay", "ArithmeticQuiz"];
+declare const TIMED_CUE_ALLOWED_CHILD_TYPES: readonly ["Text", "Heading", "Image", "Quiz", "TrueFalse", "FillInTheBlanks", "Summary", "ImagePairing", "ImageSequencing", "MemoryGame", "Questionnaire", "Essay", "ArithmeticQuiz", "MultimediaChoice", "GuessTheAnswer"];
 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" | "GameMap" | "MapStage";
+declare const ASSESSMENT_SEQUENCE_ALLOWED_CHILD_TYPES: readonly ["TrueFalse", "FillInTheBlanks", "DragAndDrop", "DragTheWords", "MarkTheWords", "Quiz", "KnowledgeCheck", "FindHotspot", "FindMultipleHotspots", "Summary", "ImagePairing", "ImageSequencing", "ArithmeticQuiz", "Essay", "SortParagraphs", "GuessTheAnswer", "MultimediaChoice"];
+declare const SINGLE_CHOICE_SET_ALLOWED_CHILD_TYPES: readonly ["Quiz", "KnowledgeCheck"];
+type CompoundParentType = "Page" | "InteractiveBook" | "Slide" | "SlideDeck" | "TimedCue" | "InteractiveVideo" | "AssessmentSequence" | "BranchingScenario" | "BranchNode" | "GameMap" | "MapStage" | "SingleChoiceSet";
 declare const COMPOUND_MAX_NESTING_DEPTH: Record<CompoundParentType, number>;
 declare function getAllowedChildTypes(parent: CompoundParentType): readonly string[];
 declare function isChildTypeAllowed(parent: CompoundParentType, childType: string): boolean;
@@ -290,9 +309,23 @@ type HeadlessLessonkitRuntime = {
  * runtime.setActiveLesson("lesson-1");
  * runtime.track("interaction", { label: "opened" }, { lessonId: "lesson-1" });
  * ```
+ *
+ * @throws When plugin registry setup fails or tracking batch config is invalid (same rules as React provider).
  */
 declare function createLessonkitRuntime(config: HeadlessLessonkitConfig, ports?: HeadlessRuntimePorts): HeadlessLessonkitRuntime;
 
+/**
+ * Register framework plugins (telemetry, assessment scoring, lifecycle hooks).
+ *
+ * @example
+ * ```ts
+ * import { createPluginRegistry, defineTelemetryPlugin } from "@lessonkit/core";
+ *
+ * const plugins = createPluginRegistry([
+ *   defineTelemetryPlugin({ id: "analytics-bridge", setup: () => {} }),
+ * ]);
+ * ```
+ */
 declare function createPluginRegistry(plugins?: readonly LessonkitPlugin[]): PluginRegistry;
 
 /**
@@ -354,4 +387,4 @@ declare function buildPluginContext(opts: {
     user?: TelemetryUser;
 }): LessonkitPluginContext;
 
-export { ACCORDION_FORBIDDEN_CHILD_TYPES, ASSESSMENT_SEQUENCE_ALLOWED_CHILD_TYPES, AssessmentPlugin, AssessmentResumeState, AssessmentScoreInput, AssessmentScoreResult, BLOCKS_14_PAGE_SLIDE, BRANCHING_SCENARIO_ALLOWED_CHILD_TYPES, BRANCH_NODE_ALLOWED_CHILD_TYPES, BlockId, type BranchGraphNodeInput, type BranchGraphValidationIssue, type BranchGraphValidationResult, COMPOUND_MAX_NESTING_DEPTH, COMPOUND_RESUME_SCHEMA_VERSION, CheckId, ClockPort, type CompoundBaseProps, type CompoundHandle, type CompoundParentType, type CompoundResumeInput, type CompoundResumeState, CourseId, type EmitContext, GAME_MAP_ALLOWED_CHILD_TYPES, type HeadlessLessonkitConfig, type HeadlessLessonkitRuntime, type HeadlessRuntimePorts, INTERACTIVE_BOOK_ALLOWED_CHILD_TYPES, INTERACTIVE_VIDEO_ALLOWED_CHILD_TYPES, IdentityIdPath, IdentityValidationResult, LessonId, LessonkitPlugin, LessonkitPluginContext, type LessonkitRuntimeVersion, LessonkitUrn, type LessonkitUrnParts, LifecyclePlugin, type LmsBridgeMode, type LoadCompoundStateOptions, MAP_STAGE_ALLOWED_CHILD_TYPES, PAGE_ALLOWED_CHILD_TYPES, type ParseCompoundResumeStateOptions, PluginHost, PluginRegistry, ProgressController, ProgressState, SLIDE_ALLOWED_CHILD_TYPES, SLIDE_DECK_ALLOWED_CHILD_TYPES, StoragePort, TELEMETRY_EVENT_CATALOG, TELEMETRY_EVENT_CATALOG_V2, TELEMETRY_EVENT_CATALOG_V3, TIMED_CUE_ALLOWED_CHILD_TYPES, TelemetryBatchSink, type TelemetryCatalogEntry, type TelemetryCatalogV2Entry, type TelemetryCatalogV3Entry, TelemetryDataFor, type TelemetryEmitFn, TelemetryEvent, TelemetryEventName, type TelemetryPipeline, type TelemetryPipelineSink, TelemetryPlugin, TelemetrySink, TelemetryUser, TrackingClient, assertNever, assertValidId, buildLessonkitUrn, buildPluginContext, buildTelemetryCatalog, buildTelemetryCatalogV2, buildTelemetryCatalogV3, clampCompoundPageIndex, clearCompoundState, compoundStateStorageKey, createCompoundResumeState, createLessonkitRuntime, createPluginRegistry, createSessionId, createTelemetryPipeline, createTrackingClient, createTrackingPipelineSink, defineAssessmentPlugin, defineLifecyclePlugin, defineTelemetryPlugin, deriveId, getAllowedChildTypes, isChildTypeAllowed, isLifecycleTelemetryEvent, loadCompoundState, nowIso, parseBlockId, parseCheckId, parseCompoundResumeState, parseCourseId, parseLessonId, saveCompoundState, slugifyId, telemetryCatalogV2Version, telemetryCatalogV3Version, telemetryCatalogVersion, validateBranchGraph, validateId };
+export { ACCORDION_FORBIDDEN_CHILD_TYPES, ASSESSMENT_17_CHILD_TYPES, ASSESSMENT_SEQUENCE_ALLOWED_CHILD_TYPES, AssessmentPlugin, AssessmentResumeState, AssessmentScoreInput, AssessmentScoreResult, BLOCKS_14_PAGE_SLIDE, BRANCHING_SCENARIO_ALLOWED_CHILD_TYPES, BRANCH_NODE_ALLOWED_CHILD_TYPES, BlockId, type BranchGraphNodeInput, type BranchGraphValidationIssue, type BranchGraphValidationResult, COMPOUND_MAX_NESTING_DEPTH, COMPOUND_RESUME_SCHEMA_VERSION, CheckId, ClockPort, type CompoundBaseProps, type CompoundHandle, type CompoundParentType, type CompoundResumeInput, type CompoundResumeState, CourseId, type EmitContext, GAME_MAP_ALLOWED_CHILD_TYPES, type HeadlessLessonkitConfig, type HeadlessLessonkitRuntime, type HeadlessRuntimePorts, INTERACTIVE_BOOK_ALLOWED_CHILD_TYPES, INTERACTIVE_VIDEO_ALLOWED_CHILD_TYPES, IdentityIdPath, IdentityValidationResult, LessonId, LessonkitPlugin, LessonkitPluginContext, type LessonkitRuntimeVersion, LessonkitUrn, type LessonkitUrnParts, LifecyclePlugin, type LmsBridgeMode, type LoadCompoundStateOptions, MAP_STAGE_ALLOWED_CHILD_TYPES, McqAssessmentProps, type McqScoreResult, PAGE_ALLOWED_CHILD_TYPES, type ParseCompoundResumeStateOptions, PluginHost, PluginRegistry, ProgressController, ProgressState, SINGLE_CHOICE_SET_ALLOWED_CHILD_TYPES, 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, isMultiSelectMcq, loadCompoundState, nowIso, orderChoicesByIndices, parseBlockId, parseCheckId, parseCompoundResumeState, parseCourseId, parseLessonId, resolveMcqCorrectAnswers, resolveMcqShuffleSeed, saveCompoundState, scoreMcqSelection, shuffleChoiceIndices, slugifyId, telemetryCatalogV2Version, telemetryCatalogV3Version, telemetryCatalogVersion, validateBranchGraph, validateId };

package/dist/index.js

@@ -36,7 +36,7 @@ import {
   tryEmitCourseStarted,
   validateId,
   warnDev
-} from "./chunk-NGCHHJSM.js";
+} from "./chunk-DTJGIMUU.js";
 
 // src/assertNever.ts
 function assertNever(value, message = "Unexpected value") {
@@ -126,6 +126,69 @@ function buildLessonkitUrn(parts) {
   return urn;
 }
 
+// src/mcqAssessment.ts
+function resolveMcqCorrectAnswers(props) {
+  if (props.answers && props.answers.length > 1) {
+    return new Set(props.answers.map((a) => a.trim()).filter(Boolean));
+  }
+  const single = props.answers?.[0]?.trim() ?? props.answer.trim();
+  return new Set(single ? [single] : []);
+}
+function isMultiSelectMcq(props) {
+  return (props.answers?.length ?? 0) > 1;
+}
+function scoreMcqSelection(selected, correct, multi, passingScore) {
+  const maxScore = multi ? Math.max(correct.size, 1) : 1;
+  if (!selected || Array.isArray(selected) && selected.length === 0) {
+    return {
+      score: 0,
+      maxScore,
+      exactMatch: false,
+      hasWrongSelection: false,
+      passedThreshold: false
+    };
+  }
+  const selectedSet = new Set(
+    (Array.isArray(selected) ? selected : [selected]).map((s) => s.trim()).filter(Boolean)
+  );
+  let score = 0;
+  for (const label of selectedSet) {
+    if (correct.has(label)) score += 1;
+  }
+  const hasWrongSelection = [...selectedSet].some((label) => !correct.has(label));
+  const exactMatch = !hasWrongSelection && selectedSet.size === correct.size && [...correct].every((label) => selectedSet.has(label));
+  const threshold = passingScore ?? maxScore;
+  const passedThreshold = score >= threshold && !hasWrongSelection;
+  return { score, maxScore, exactMatch, hasWrongSelection, passedThreshold };
+}
+function hashSeedToNumber(seed) {
+  if (typeof seed === "number" && Number.isFinite(seed)) return Math.abs(Math.trunc(seed)) || 1;
+  let hash = 2166136261;
+  const text = String(seed);
+  for (let i = 0; i < text.length; i += 1) {
+    hash ^= text.charCodeAt(i);
+    hash = Math.imul(hash, 16777619);
+  }
+  return hash >>> 0 || 1;
+}
+function shuffleChoiceIndices(length, seed) {
+  const indices = Array.from({ length }, (_, i) => i);
+  if (length <= 1) return indices;
+  let state = hashSeedToNumber(seed);
+  for (let i = length - 1; i > 0; i -= 1) {
+    state = Math.imul(state, 1664525) + 1013904223 >>> 0;
+    const j = state % (i + 1);
+    [indices[i], indices[j]] = [indices[j], indices[i]];
+  }
+  return indices;
+}
+function resolveMcqShuffleSeed(props) {
+  return props.shuffleSeed ?? props.checkId;
+}
+function orderChoicesByIndices(choices, orderIndices) {
+  return orderIndices.map((index) => choices[index] ?? "").filter((c) => c.length > 0);
+}
+
 // src/compound.ts
 var COMPOUND_RESUME_SCHEMA_VERSION = 1;
 function createCompoundResumeState(input = {}) {
@@ -231,6 +294,11 @@ function clearCompoundState(storage, courseId, compoundId) {
 }
 
 // src/compoundAllowlists.ts
+var ASSESSMENT_17_CHILD_TYPES = [
+  "SortParagraphs",
+  "GuessTheAnswer",
+  "MultimediaChoice"
+];
 var PAGE_AND_SLIDE_14_BLOCKS = [
   "Video",
   "Summary",
@@ -285,7 +353,8 @@ var PAGE_ALLOWED_CHILD_TYPES = [
   "QrContent",
   "Crossword",
   "AdventCalendar",
-  "ProgressTracker"
+  "ProgressTracker",
+  ...ASSESSMENT_17_CHILD_TYPES
 ];
 var BRANCH_NODE_ALLOWED_CHILD_TYPES = [
   "Text",
@@ -329,7 +398,8 @@ var BRANCH_NODE_ALLOWED_CHILD_TYPES = [
   "QrContent",
   "Crossword",
   "AdventCalendar",
-  "BranchChoice"
+  "BranchChoice",
+  ...ASSESSMENT_17_CHILD_TYPES
 ];
 var BRANCHING_SCENARIO_ALLOWED_CHILD_TYPES = ["BranchNode"];
 var GAME_MAP_ALLOWED_CHILD_TYPES = ["MapStage"];
@@ -375,7 +445,8 @@ var MAP_STAGE_ALLOWED_CHILD_TYPES = [
   "QrContent",
   "Crossword",
   "AdventCalendar",
-  "MapExit"
+  "MapExit",
+  ...ASSESSMENT_17_CHILD_TYPES
 ];
 var INTERACTIVE_BOOK_ALLOWED_CHILD_TYPES = ["Page"];
 var SLIDE_ALLOWED_CHILD_TYPES = [
@@ -419,7 +490,8 @@ var SLIDE_ALLOWED_CHILD_TYPES = [
   "CombinationLock",
   "QrContent",
   "Crossword",
-  "AdventCalendar"
+  "AdventCalendar",
+  ...ASSESSMENT_17_CHILD_TYPES
 ];
 var SLIDE_DECK_ALLOWED_CHILD_TYPES = ["Slide"];
 var TIMED_CUE_ALLOWED_CHILD_TYPES = [
@@ -435,7 +507,9 @@ var TIMED_CUE_ALLOWED_CHILD_TYPES = [
   "MemoryGame",
   "Questionnaire",
   "Essay",
-  "ArithmeticQuiz"
+  "ArithmeticQuiz",
+  "MultimediaChoice",
+  "GuessTheAnswer"
 ];
 var INTERACTIVE_VIDEO_ALLOWED_CHILD_TYPES = ["TimedCue"];
 var ASSESSMENT_SEQUENCE_ALLOWED_CHILD_TYPES = [
@@ -452,8 +526,10 @@ var ASSESSMENT_SEQUENCE_ALLOWED_CHILD_TYPES = [
   "ImagePairing",
   "ImageSequencing",
   "ArithmeticQuiz",
-  "Essay"
+  "Essay",
+  ...ASSESSMENT_17_CHILD_TYPES
 ];
+var SINGLE_CHOICE_SET_ALLOWED_CHILD_TYPES = ["Quiz", "KnowledgeCheck"];
 var ALLOWLISTS = {
   Page: PAGE_ALLOWED_CHILD_TYPES,
   InteractiveBook: INTERACTIVE_BOOK_ALLOWED_CHILD_TYPES,
@@ -465,7 +541,8 @@ var ALLOWLISTS = {
   BranchingScenario: BRANCHING_SCENARIO_ALLOWED_CHILD_TYPES,
   BranchNode: BRANCH_NODE_ALLOWED_CHILD_TYPES,
   GameMap: GAME_MAP_ALLOWED_CHILD_TYPES,
-  MapStage: MAP_STAGE_ALLOWED_CHILD_TYPES
+  MapStage: MAP_STAGE_ALLOWED_CHILD_TYPES,
+  SingleChoiceSet: SINGLE_CHOICE_SET_ALLOWED_CHILD_TYPES
 };
 var COMPOUND_MAX_NESTING_DEPTH = {
   Page: 1,
@@ -478,7 +555,8 @@ var COMPOUND_MAX_NESTING_DEPTH = {
   BranchingScenario: 2,
   BranchNode: 1,
   GameMap: 2,
-  MapStage: 1
+  MapStage: 1,
+  SingleChoiceSet: 1
 };
 function getAllowedChildTypes(parent) {
   return ALLOWLISTS[parent];
@@ -1528,6 +1606,7 @@ function defineLifecyclePlugin(plugin) {
 }
 export {
   ACCORDION_FORBIDDEN_CHILD_TYPES,
+  ASSESSMENT_17_CHILD_TYPES,
   ASSESSMENT_SEQUENCE_ALLOWED_CHILD_TYPES,
   BLOCKS_14_PAGE_SLIDE,
   BRANCHING_SCENARIO_ALLOWED_CHILD_TYPES,
@@ -1542,6 +1621,7 @@ export {
   MAP_STAGE_ALLOWED_CHILD_TYPES,
   PAGE_ALLOWED_CHILD_TYPES,
   SESSION_STORAGE_KEY,
+  SINGLE_CHOICE_SET_ALLOWED_CHILD_TYPES,
   SLIDE_ALLOWED_CHILD_TYPES,
   SLIDE_DECK_ALLOWED_CHILD_TYPES,
   TELEMETRY_EVENT_CATALOG,
@@ -1586,6 +1666,7 @@ export {
   hasCourseStartedXapiSent,
   isChildTypeAllowed,
   isLifecycleTelemetryEvent,
+  isMultiSelectMcq,
   loadCompoundState,
   markCourseStarted,
   markCourseStartedEmittedToTracking,
@@ -1593,6 +1674,7 @@ export {
   markCourseStartedXapiSent,
   migrateCourseStartedMark,
   nowIso,
+  orderChoicesByIndices,
   parseBlockId,
   parseCheckId,
   parseCompoundResumeState,
@@ -1601,8 +1683,12 @@ export {
   resetSharedVolatileSessionIdForTests,
   resetStoragePortForTests,
   resetTelemetryBuilderWarningsForTests,
+  resolveMcqCorrectAnswers,
+  resolveMcqShuffleSeed,
   resolveSessionId,
   saveCompoundState,
+  scoreMcqSelection,
+  shuffleChoiceIndices,
   slugifyId,
   telemetryCatalogV2Version,
   telemetryCatalogV3Version,

package/dist/{testing-CzgxF1Ru.d.cts → testing-CQ-ZsT7D.d.cts}

@@ -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" | "combinationLock" | "crossword" | "wordSearch";
+type AssessmentInteractionType = "mcq" | "trueFalse" | "fillInBlanks" | "markTheWords" | "dragTheWords" | "dragAndDrop" | "assessmentSequence" | "findHotspot" | "findMultipleHotspots" | "summary" | "imagePairing" | "imageSequencing" | "essay" | "arithmeticQuiz" | "memoryGame" | "combinationLock" | "crossword" | "wordSearch" | "sortParagraphs" | "guessTheAnswer";
 /** Serializable resume blob for a single assessment block. */
 type AssessmentResumeState = Record<string, unknown>;
 /** Behaviour flags aligned with H5P question types. */
@@ -57,12 +57,34 @@ type AssessmentBaseProps = AssessmentBehaviour & {
     checkId: CheckId;
     passingScore?: number;
 };
-/** MCQ assessment props shared by React components and LMS packaging descriptors. */
+/**
+ * MCQ assessment props shared by React components and LMS packaging descriptors.
+ *
+ * @example
+ * ```tsx
+ * const props: McqAssessmentProps = {
+ *   checkId: "verify-sender",
+ *   question: "First step for a suspicious email?",
+ *   choices: ["Open attachment", "Verify sender"],
+ *   answer: "Verify sender",
+ *   passingScore: 1,
+ * };
+ * ```
+ */
 type McqAssessmentProps = AssessmentBaseProps & {
     kind?: "mcq";
     question: string;
     choices: string[];
+    /** Single correct choice (required for backward compatibility). */
     answer: string;
+    /** When length > 1, enables multi-select checkbox mode. */
+    answers?: string[];
+    /** Randomize choice display order in the SPA (stable when `shuffleSeed` set). */
+    shuffleChoices?: boolean;
+    /** Seed for deterministic shuffle; defaults to `checkId`. */
+    shuffleSeed?: string | number;
+    /** Per-choice feedback announced on selection; keys match choice labels. */
+    choiceFeedback?: Record<string, 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" | "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";
@@ -602,8 +624,20 @@ type ProgressController = {
 declare function createProgressController(): ProgressController;
 
 declare const SESSION_STORAGE_KEY = "lessonkit:sessionId";
+type InvalidSessionIdContext = {
+    /** The invalid id that was rejected. */
+    invalidId: string;
+    /** Id actually used after fallback. */
+    fallbackId: string;
+    /** Whether the invalid id came from config or from stored tab state. */
+    source: "provided" | "stored";
+};
+type ResolveSessionIdOptions = {
+    /** Invoked when an invalid session id is replaced by a tab or generated id. */
+    onInvalidSessionId?: (ctx: InvalidSessionIdContext) => void;
+};
 declare function getTabSessionId(storage: StoragePort): string | null;
-declare function resolveSessionId(storage: StoragePort, provided?: string): string;
+declare function resolveSessionId(storage: StoragePort, provided?: string, options?: ResolveSessionIdOptions): 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;
@@ -751,4 +785,4 @@ declare function completeCourseWithTelemetry(opts: {
     emitCourseCompleted: () => void;
 }): boolean;
 
-export { type LessonCompletionEmitter as $, type AssessmentResumeState as A, type BlockId as B, type CourseId as C, type AssessmentInteractionType as D, type AssessmentXAPIData as E, type BookPageViewedData as F, type BranchNodeViewedData as G, type BranchSelectedData as H, type IdentityIdPath as I, type BuildTelemetryEventInput as J, type CompoundPageViewedData as K, type LessonId as L, type CourseLifecycleContext as M, type CourseLifecycleDeps as N, type FlashcardFlippedData as O, type PluginRegistry as P, type HotspotOpenedData as Q, ID_MAX_LENGTH as R, type StoragePort as S, type TelemetryEventName as T, ID_PATTERN as U, type IdentityValidationIssue as V, type ImageSliderChangedData as W, type InformationWallSearchData as X, type InteractionBlockRegistration as Y, type InteractionData as Z, type InteractionPlugin as _, type CheckId as a, type LessonLifecycleData as a0, type LessonkitPluginKind as a1, type McqAssessmentProps as a2, type MemoryCardFlippedData as a3, type ParallaxSlideViewedData as a4, type PluginIdentity as a5, type QuestionnaireSubmittedData as a6, type QuizAnsweredData as a7, type QuizCompletedData as a8, SESSION_STORAGE_KEY as a9, resetTelemetryBuilderWarningsForTests as aA, resolveSessionId as aB, tryBuildTelemetryEvent as aC, tryEmitCourseStarted as aD, resetCourseStartedEmitFlightForTests as aE, type SlideViewedData as aa, type TelemetryEventBase as ab, type TimerPort as ac, type VideoCueReachedData as ad, type VideoSegmentCompletedData as ae, buildCourseStartedTelemetryEvent as af, buildTelemetryEvent as ag, completeCourseWithTelemetry as ah, completeLessonWithTelemetry as ai, createDefaultClock as aj, createGlobalTimer as ak, createNoopStorage as al, createProgressController as am, createSessionStoragePort as an, getTabSessionId as ao, hasCourseStarted as ap, hasCourseStartedEmittedToTracking as aq, hasCourseStartedPipelineDelivered as ar, hasCourseStartedXapiSent as as, markCourseStarted as at, markCourseStartedEmittedToTracking as au, markCourseStartedPipelineDelivered as av, markCourseStartedXapiSent as aw, migrateCourseStartedMark as ax, resetSharedVolatileSessionIdForTests as ay, resetStoragePortForTests as az, type IdentityValidationResult as b, type LessonkitUrn as c, type TelemetrySink as d, type TelemetryBatchSink as e, type TrackingClient as f, type TelemetryEvent as g, type TelemetryUser as h, type LessonkitPlugin as i, type ProgressController as j, type PluginHost as k, type ProgressState as l, type TelemetryDataFor as m, type AssessmentScoreInput as n, type AssessmentScoreResult as o, type ClockPort as p, type AssessmentPlugin as q, type LifecyclePlugin as r, type TelemetryPlugin as s, type LessonkitPluginContext as t, type AccordionSectionToggledData as u, type AssessmentAnsweredData as v, type AssessmentBaseProps as w, type AssessmentBehaviour as x, type AssessmentCompletedData as y, type AssessmentHandle as z };
+export { type InteractionPlugin as $, type AssessmentResumeState as A, type BlockId as B, type CourseId as C, type AssessmentInteractionType as D, type AssessmentXAPIData as E, type BookPageViewedData as F, type BranchNodeViewedData as G, type BranchSelectedData as H, type IdentityIdPath as I, type BuildTelemetryEventInput as J, type CompoundPageViewedData as K, type LessonId as L, type McqAssessmentProps as M, type CourseLifecycleContext as N, type CourseLifecycleDeps as O, type PluginRegistry as P, type FlashcardFlippedData as Q, type HotspotOpenedData as R, type StoragePort as S, type TelemetryEventName as T, ID_MAX_LENGTH as U, ID_PATTERN as V, type IdentityValidationIssue as W, type ImageSliderChangedData as X, type InformationWallSearchData as Y, type InteractionBlockRegistration as Z, type InteractionData as _, type CheckId as a, type InvalidSessionIdContext as a0, type LessonCompletionEmitter as a1, type LessonLifecycleData as a2, type LessonkitPluginKind as a3, type MemoryCardFlippedData as a4, type ParallaxSlideViewedData as a5, type PluginIdentity as a6, type QuestionnaireSubmittedData as a7, type QuizAnsweredData as a8, type QuizCompletedData as a9, resetSharedVolatileSessionIdForTests as aA, resetStoragePortForTests as aB, resetTelemetryBuilderWarningsForTests as aC, resolveSessionId as aD, tryBuildTelemetryEvent as aE, tryEmitCourseStarted as aF, resetCourseStartedEmitFlightForTests as aG, type ResolveSessionIdOptions as aa, SESSION_STORAGE_KEY as ab, type SlideViewedData as ac, type TelemetryEventBase as ad, type TimerPort as ae, type VideoCueReachedData as af, type VideoSegmentCompletedData as ag, buildCourseStartedTelemetryEvent as ah, buildTelemetryEvent as ai, completeCourseWithTelemetry as aj, completeLessonWithTelemetry as ak, createDefaultClock as al, createGlobalTimer as am, createNoopStorage as an, createProgressController as ao, createSessionStoragePort as ap, getTabSessionId as aq, hasCourseStarted as ar, hasCourseStartedEmittedToTracking as as, hasCourseStartedPipelineDelivered as at, hasCourseStartedXapiSent as au, markCourseStarted as av, markCourseStartedEmittedToTracking as aw, markCourseStartedPipelineDelivered as ax, markCourseStartedXapiSent as ay, migrateCourseStartedMark as az, type IdentityValidationResult as b, type LessonkitUrn as c, type TelemetrySink as d, type TelemetryBatchSink as e, type TrackingClient as f, type TelemetryEvent as g, type TelemetryUser as h, type LessonkitPlugin as i, type ProgressController as j, type PluginHost as k, type ProgressState as l, type TelemetryDataFor as m, type AssessmentScoreInput as n, type AssessmentScoreResult as o, type ClockPort as p, type AssessmentPlugin as q, type LifecyclePlugin as r, type TelemetryPlugin as s, type LessonkitPluginContext as t, type AccordionSectionToggledData as u, type AssessmentAnsweredData as v, type AssessmentBaseProps as w, type AssessmentBehaviour as x, type AssessmentCompletedData as y, type AssessmentHandle as z };

package/dist/{testing-CzgxF1Ru.d.ts → testing-CQ-ZsT7D.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" | "combinationLock" | "crossword" | "wordSearch";
+type AssessmentInteractionType = "mcq" | "trueFalse" | "fillInBlanks" | "markTheWords" | "dragTheWords" | "dragAndDrop" | "assessmentSequence" | "findHotspot" | "findMultipleHotspots" | "summary" | "imagePairing" | "imageSequencing" | "essay" | "arithmeticQuiz" | "memoryGame" | "combinationLock" | "crossword" | "wordSearch" | "sortParagraphs" | "guessTheAnswer";
 /** Serializable resume blob for a single assessment block. */
 type AssessmentResumeState = Record<string, unknown>;
 /** Behaviour flags aligned with H5P question types. */
@@ -57,12 +57,34 @@ type AssessmentBaseProps = AssessmentBehaviour & {
     checkId: CheckId;
     passingScore?: number;
 };
-/** MCQ assessment props shared by React components and LMS packaging descriptors. */
+/**
+ * MCQ assessment props shared by React components and LMS packaging descriptors.
+ *
+ * @example
+ * ```tsx
+ * const props: McqAssessmentProps = {
+ *   checkId: "verify-sender",
+ *   question: "First step for a suspicious email?",
+ *   choices: ["Open attachment", "Verify sender"],
+ *   answer: "Verify sender",
+ *   passingScore: 1,
+ * };
+ * ```
+ */
 type McqAssessmentProps = AssessmentBaseProps & {
     kind?: "mcq";
     question: string;
     choices: string[];
+    /** Single correct choice (required for backward compatibility). */
     answer: string;
+    /** When length > 1, enables multi-select checkbox mode. */
+    answers?: string[];
+    /** Randomize choice display order in the SPA (stable when `shuffleSeed` set). */
+    shuffleChoices?: boolean;
+    /** Seed for deterministic shuffle; defaults to `checkId`. */
+    shuffleSeed?: string | number;
+    /** Per-choice feedback announced on selection; keys match choice labels. */
+    choiceFeedback?: Record<string, 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" | "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";
@@ -602,8 +624,20 @@ type ProgressController = {
 declare function createProgressController(): ProgressController;
 
 declare const SESSION_STORAGE_KEY = "lessonkit:sessionId";
+type InvalidSessionIdContext = {
+    /** The invalid id that was rejected. */
+    invalidId: string;
+    /** Id actually used after fallback. */
+    fallbackId: string;
+    /** Whether the invalid id came from config or from stored tab state. */
+    source: "provided" | "stored";
+};
+type ResolveSessionIdOptions = {
+    /** Invoked when an invalid session id is replaced by a tab or generated id. */
+    onInvalidSessionId?: (ctx: InvalidSessionIdContext) => void;
+};
 declare function getTabSessionId(storage: StoragePort): string | null;
-declare function resolveSessionId(storage: StoragePort, provided?: string): string;
+declare function resolveSessionId(storage: StoragePort, provided?: string, options?: ResolveSessionIdOptions): 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;
@@ -751,4 +785,4 @@ declare function completeCourseWithTelemetry(opts: {
     emitCourseCompleted: () => void;
 }): boolean;
 
-export { type LessonCompletionEmitter as $, type AssessmentResumeState as A, type BlockId as B, type CourseId as C, type AssessmentInteractionType as D, type AssessmentXAPIData as E, type BookPageViewedData as F, type BranchNodeViewedData as G, type BranchSelectedData as H, type IdentityIdPath as I, type BuildTelemetryEventInput as J, type CompoundPageViewedData as K, type LessonId as L, type CourseLifecycleContext as M, type CourseLifecycleDeps as N, type FlashcardFlippedData as O, type PluginRegistry as P, type HotspotOpenedData as Q, ID_MAX_LENGTH as R, type StoragePort as S, type TelemetryEventName as T, ID_PATTERN as U, type IdentityValidationIssue as V, type ImageSliderChangedData as W, type InformationWallSearchData as X, type InteractionBlockRegistration as Y, type InteractionData as Z, type InteractionPlugin as _, type CheckId as a, type LessonLifecycleData as a0, type LessonkitPluginKind as a1, type McqAssessmentProps as a2, type MemoryCardFlippedData as a3, type ParallaxSlideViewedData as a4, type PluginIdentity as a5, type QuestionnaireSubmittedData as a6, type QuizAnsweredData as a7, type QuizCompletedData as a8, SESSION_STORAGE_KEY as a9, resetTelemetryBuilderWarningsForTests as aA, resolveSessionId as aB, tryBuildTelemetryEvent as aC, tryEmitCourseStarted as aD, resetCourseStartedEmitFlightForTests as aE, type SlideViewedData as aa, type TelemetryEventBase as ab, type TimerPort as ac, type VideoCueReachedData as ad, type VideoSegmentCompletedData as ae, buildCourseStartedTelemetryEvent as af, buildTelemetryEvent as ag, completeCourseWithTelemetry as ah, completeLessonWithTelemetry as ai, createDefaultClock as aj, createGlobalTimer as ak, createNoopStorage as al, createProgressController as am, createSessionStoragePort as an, getTabSessionId as ao, hasCourseStarted as ap, hasCourseStartedEmittedToTracking as aq, hasCourseStartedPipelineDelivered as ar, hasCourseStartedXapiSent as as, markCourseStarted as at, markCourseStartedEmittedToTracking as au, markCourseStartedPipelineDelivered as av, markCourseStartedXapiSent as aw, migrateCourseStartedMark as ax, resetSharedVolatileSessionIdForTests as ay, resetStoragePortForTests as az, type IdentityValidationResult as b, type LessonkitUrn as c, type TelemetrySink as d, type TelemetryBatchSink as e, type TrackingClient as f, type TelemetryEvent as g, type TelemetryUser as h, type LessonkitPlugin as i, type ProgressController as j, type PluginHost as k, type ProgressState as l, type TelemetryDataFor as m, type AssessmentScoreInput as n, type AssessmentScoreResult as o, type ClockPort as p, type AssessmentPlugin as q, type LifecyclePlugin as r, type TelemetryPlugin as s, type LessonkitPluginContext as t, type AccordionSectionToggledData as u, type AssessmentAnsweredData as v, type AssessmentBaseProps as w, type AssessmentBehaviour as x, type AssessmentCompletedData as y, type AssessmentHandle as z };
+export { type InteractionPlugin as $, type AssessmentResumeState as A, type BlockId as B, type CourseId as C, type AssessmentInteractionType as D, type AssessmentXAPIData as E, type BookPageViewedData as F, type BranchNodeViewedData as G, type BranchSelectedData as H, type IdentityIdPath as I, type BuildTelemetryEventInput as J, type CompoundPageViewedData as K, type LessonId as L, type McqAssessmentProps as M, type CourseLifecycleContext as N, type CourseLifecycleDeps as O, type PluginRegistry as P, type FlashcardFlippedData as Q, type HotspotOpenedData as R, type StoragePort as S, type TelemetryEventName as T, ID_MAX_LENGTH as U, ID_PATTERN as V, type IdentityValidationIssue as W, type ImageSliderChangedData as X, type InformationWallSearchData as Y, type InteractionBlockRegistration as Z, type InteractionData as _, type CheckId as a, type InvalidSessionIdContext as a0, type LessonCompletionEmitter as a1, type LessonLifecycleData as a2, type LessonkitPluginKind as a3, type MemoryCardFlippedData as a4, type ParallaxSlideViewedData as a5, type PluginIdentity as a6, type QuestionnaireSubmittedData as a7, type QuizAnsweredData as a8, type QuizCompletedData as a9, resetSharedVolatileSessionIdForTests as aA, resetStoragePortForTests as aB, resetTelemetryBuilderWarningsForTests as aC, resolveSessionId as aD, tryBuildTelemetryEvent as aE, tryEmitCourseStarted as aF, resetCourseStartedEmitFlightForTests as aG, type ResolveSessionIdOptions as aa, SESSION_STORAGE_KEY as ab, type SlideViewedData as ac, type TelemetryEventBase as ad, type TimerPort as ae, type VideoCueReachedData as af, type VideoSegmentCompletedData as ag, buildCourseStartedTelemetryEvent as ah, buildTelemetryEvent as ai, completeCourseWithTelemetry as aj, completeLessonWithTelemetry as ak, createDefaultClock as al, createGlobalTimer as am, createNoopStorage as an, createProgressController as ao, createSessionStoragePort as ap, getTabSessionId as aq, hasCourseStarted as ar, hasCourseStartedEmittedToTracking as as, hasCourseStartedPipelineDelivered as at, hasCourseStartedXapiSent as au, markCourseStarted as av, markCourseStartedEmittedToTracking as aw, markCourseStartedPipelineDelivered as ax, markCourseStartedXapiSent as ay, migrateCourseStartedMark as az, type IdentityValidationResult as b, type LessonkitUrn as c, type TelemetrySink as d, type TelemetryBatchSink as e, type TrackingClient as f, type TelemetryEvent as g, type TelemetryUser as h, type LessonkitPlugin as i, type ProgressController as j, type PluginHost as k, type ProgressState as l, type TelemetryDataFor as m, type AssessmentScoreInput as n, type AssessmentScoreResult as o, type ClockPort as p, type AssessmentPlugin as q, type LifecyclePlugin as r, type TelemetryPlugin as s, type LessonkitPluginContext as t, type AccordionSectionToggledData as u, type AssessmentAnsweredData as v, type AssessmentBaseProps as w, type AssessmentBehaviour as x, type AssessmentCompletedData as y, type AssessmentHandle as z };

package/dist/testing.cjs

@@ -46,8 +46,10 @@ function resetSharedVolatileSessionIdForTests() {
 
 // src/runtime/courseLifecycle.ts
 var courseStartedEmitFlights = /* @__PURE__ */ new Map();
+var courseStartedEmittedInTab = /* @__PURE__ */ new Set();
 function resetCourseStartedEmitFlightForTests() {
   courseStartedEmitFlights.clear();
+  courseStartedEmittedInTab.clear();
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/testing.d.cts

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

package/dist/testing.d.ts

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

package/dist/testing.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lessonkit/core",
-  "version": "1.6.0",
+  "version": "1.7.1",
   "private": false,
   "description": "Shared types and telemetry primitives for LessonKit.",
   "license": "Apache-2.0",
@@ -48,8 +48,8 @@
     "identity-contract.v1.json"
   ],
   "scripts": {
-    "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",
+    "build": "tsup src/index.ts src/testing.ts --format esm,cjs --dts --tsconfig tsconfig.build.json",
+    "dev": "tsup src/index.ts src/testing.ts --format esm,cjs --dts --watch --tsconfig tsconfig.build.json",
     "prepublishOnly": "npm run build",
     "typecheck": "tsc -p tsconfig.json",
     "test": "vitest run --passWithNoTests",