@lessonkit/core 1.6.0 → 1.7.1

package/dist/index.cjs

@@ -21,6 +21,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   ACCORDION_FORBIDDEN_CHILD_TYPES: () => ACCORDION_FORBIDDEN_CHILD_TYPES,
+  ASSESSMENT_17_CHILD_TYPES: () => ASSESSMENT_17_CHILD_TYPES,
   ASSESSMENT_SEQUENCE_ALLOWED_CHILD_TYPES: () => ASSESSMENT_SEQUENCE_ALLOWED_CHILD_TYPES,
   BLOCKS_14_PAGE_SLIDE: () => BLOCKS_14_PAGE_SLIDE,
   BRANCHING_SCENARIO_ALLOWED_CHILD_TYPES: () => BRANCHING_SCENARIO_ALLOWED_CHILD_TYPES,
@@ -35,6 +36,7 @@ __export(index_exports, {
   MAP_STAGE_ALLOWED_CHILD_TYPES: () => MAP_STAGE_ALLOWED_CHILD_TYPES,
   PAGE_ALLOWED_CHILD_TYPES: () => PAGE_ALLOWED_CHILD_TYPES,
   SESSION_STORAGE_KEY: () => SESSION_STORAGE_KEY,
+  SINGLE_CHOICE_SET_ALLOWED_CHILD_TYPES: () => SINGLE_CHOICE_SET_ALLOWED_CHILD_TYPES,
   SLIDE_ALLOWED_CHILD_TYPES: () => SLIDE_ALLOWED_CHILD_TYPES,
   SLIDE_DECK_ALLOWED_CHILD_TYPES: () => SLIDE_DECK_ALLOWED_CHILD_TYPES,
   TELEMETRY_EVENT_CATALOG: () => TELEMETRY_EVENT_CATALOG,
@@ -79,6 +81,7 @@ __export(index_exports, {
   hasCourseStartedXapiSent: () => hasCourseStartedXapiSent,
   isChildTypeAllowed: () => isChildTypeAllowed,
   isLifecycleTelemetryEvent: () => isLifecycleTelemetryEvent,
+  isMultiSelectMcq: () => isMultiSelectMcq,
   loadCompoundState: () => loadCompoundState,
   markCourseStarted: () => markCourseStarted,
   markCourseStartedEmittedToTracking: () => markCourseStartedEmittedToTracking,
@@ -86,6 +89,7 @@ __export(index_exports, {
   markCourseStartedXapiSent: () => markCourseStartedXapiSent,
   migrateCourseStartedMark: () => migrateCourseStartedMark,
   nowIso: () => nowIso,
+  orderChoicesByIndices: () => orderChoicesByIndices,
   parseBlockId: () => parseBlockId,
   parseCheckId: () => parseCheckId,
   parseCompoundResumeState: () => parseCompoundResumeState,
@@ -94,8 +98,12 @@ __export(index_exports, {
   resetSharedVolatileSessionIdForTests: () => resetSharedVolatileSessionIdForTests,
   resetStoragePortForTests: () => resetStoragePortForTests,
   resetTelemetryBuilderWarningsForTests: () => resetTelemetryBuilderWarningsForTests,
+  resolveMcqCorrectAnswers: () => resolveMcqCorrectAnswers,
+  resolveMcqShuffleSeed: () => resolveMcqShuffleSeed,
   resolveSessionId: () => resolveSessionId,
   saveCompoundState: () => saveCompoundState,
+  scoreMcqSelection: () => scoreMcqSelection,
+  shuffleChoiceIndices: () => shuffleChoiceIndices,
   slugifyId: () => slugifyId,
   telemetryCatalogV2Version: () => telemetryCatalogV2Version,
   telemetryCatalogV3Version: () => telemetryCatalogV3Version,
@@ -251,6 +259,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 = {}) {
@@ -366,6 +437,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",
@@ -420,7 +496,8 @@ var PAGE_ALLOWED_CHILD_TYPES = [
   "QrContent",
   "Crossword",
   "AdventCalendar",
-  "ProgressTracker"
+  "ProgressTracker",
+  ...ASSESSMENT_17_CHILD_TYPES
 ];
 var BRANCH_NODE_ALLOWED_CHILD_TYPES = [
   "Text",
@@ -464,7 +541,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"];
@@ -510,7 +588,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 = [
@@ -554,7 +633,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 = [
@@ -570,7 +650,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 = [
@@ -587,8 +669,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,
@@ -600,7 +684,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,
@@ -613,7 +698,8 @@ var COMPOUND_MAX_NESTING_DEPTH = {
   BranchingScenario: 2,
   BranchNode: 1,
   GameMap: 2,
-  MapStage: 1
+  MapStage: 1,
+  SingleChoiceSet: 1
 };
 function getAllowedChildTypes(parent) {
   return ALLOWLISTS[parent];
@@ -1793,9 +1879,15 @@ function createMemoryBackedSessionStorage(session) {
       if (!bypassCacheForKey(key) && memory.has(key)) return memory.get(key);
       try {
         const value = session.getItem(key);
-        if (value !== null) memory.set(key, value);
-        else if (bypassCacheForKey(key)) memory.delete(key);
-        return value;
+        if (value !== null) {
+          memory.set(key, value);
+          return value;
+        }
+        if (bypassCacheForKey(key) && memory.has(key)) {
+          return memory.get(key);
+        }
+        if (bypassCacheForKey(key)) memory.delete(key);
+        return null;
       } catch {
         return memory.get(key) ?? null;
       }
@@ -1808,9 +1900,7 @@ function createMemoryBackedSessionStorage(session) {
         return true;
       } catch {
         warnPersistFailure();
-        if (!bypassCacheForKey(key)) {
-          memory.set(key, value);
-        }
+        memory.set(key, value);
         return false;
       }
     },
@@ -1923,6 +2013,29 @@ function createProgressController() {
 // src/session.ts
 var SESSION_STORAGE_KEY = "lessonkit:sessionId";
 var volatileSessionIds = /* @__PURE__ */ new WeakMap();
+var volatileStorageMarks = /* @__PURE__ */ new WeakMap();
+function rememberVolatileMark(storage, key) {
+  let keys = volatileStorageMarks.get(storage);
+  if (!keys) {
+    keys = /* @__PURE__ */ new Set();
+    volatileStorageMarks.set(storage, keys);
+  }
+  keys.add(key);
+}
+function hasVolatileMark(storage, key) {
+  return volatileStorageMarks.get(storage)?.has(key) ?? false;
+}
+function clearVolatileMark(storage, key) {
+  volatileStorageMarks.get(storage)?.delete(key);
+}
+function storageHasMark(storage, key) {
+  return storage.getItem(key) === "1" || hasVolatileMark(storage, key);
+}
+function storageSetMark(storage, key) {
+  const persisted = storage.setItem(key, "1");
+  if (!persisted) rememberVolatileMark(storage, key);
+  return persisted;
+}
 function isDevEnvironment2() {
   const g = globalThis;
   return typeof g.process !== "undefined" && g.process.env?.NODE_ENV !== "production";
@@ -1938,19 +2051,23 @@ function sessionKeySegment(sessionId) {
   const validated = validateId(sessionId);
   return validated.ok ? validated.id : encodeURIComponent(sessionId);
 }
-function resolveSessionId(storage, provided) {
-  if (provided !== void 0) {
-    const trimmed = provided.trim();
-    if (trimmed.length > 0) {
-      const validated = validateId(trimmed);
-      if (validated.ok) return validated.id;
-      if (isDevEnvironment2()) {
-        console.warn(
-          `[lessonkit] Invalid sessionId "${trimmed}"; falling back to tab or generated id.`
-        );
-      }
+function resolveGeneratedSessionId(storage) {
+  const volatile = volatileSessionIds.get(storage);
+  if (volatile) return volatile;
+  const id = createSessionId();
+  const persisted = storage.setItem(SESSION_STORAGE_KEY, id);
+  if (!persisted) {
+    volatileSessionIds.set(storage, id);
+    if (isDevEnvironment2()) {
+      console.warn(
+        "[lessonkit] session id could not be persisted; using in-memory id for this storage."
+      );
     }
+    return id;
   }
+  return id;
+}
+function resolveFallbackSessionId(storage, options) {
   const existing = storage.getItem(SESSION_STORAGE_KEY);
   if (existing) {
     const trimmedExisting = existing.trim();
@@ -1962,21 +2079,37 @@ function resolveSessionId(storage, provided) {
         `[lessonkit] Invalid stored sessionId "${existing}"; generating a new id.`
       );
     }
+    const fallback = resolveGeneratedSessionId(storage);
+    options?.onInvalidSessionId?.({
+      invalidId: existing,
+      fallbackId: fallback,
+      source: "stored"
+    });
+    return fallback;
   }
-  const volatile = volatileSessionIds.get(storage);
-  if (volatile) return volatile;
-  const id = createSessionId();
-  const persisted = storage.setItem(SESSION_STORAGE_KEY, id);
-  if (!persisted) {
-    volatileSessionIds.set(storage, id);
-    if (isDevEnvironment2()) {
-      console.warn(
-        "[lessonkit] session id could not be persisted; using in-memory id for this storage."
-      );
+  return resolveGeneratedSessionId(storage);
+}
+function resolveSessionId(storage, provided, options) {
+  if (provided !== void 0) {
+    const trimmed = provided.trim();
+    if (trimmed.length > 0) {
+      const validated = validateId(trimmed);
+      if (validated.ok) return validated.id;
+      if (isDevEnvironment2()) {
+        console.warn(
+          `[lessonkit] Invalid sessionId "${trimmed}"; falling back to tab or generated id.`
+        );
+      }
+      const fallback = resolveFallbackSessionId(storage, options);
+      options?.onInvalidSessionId?.({
+        invalidId: trimmed,
+        fallbackId: fallback,
+        source: "provided"
+      });
+      return fallback;
     }
-    return id;
   }
-  return id;
+  return resolveFallbackSessionId(storage, options);
 }
 function courseStartedStorageKey(sessionId, courseId) {
   return `${COURSE_STARTED_PREFIX}${sessionKeySegment(sessionId)}:${courseId ?? ""}`;
@@ -1992,35 +2125,35 @@ function courseStartedXapiStorageKey(sessionId, courseId) {
 }
 function hasCourseStarted(storage, sessionId, courseId) {
   if (!courseId) return false;
-  return storage.getItem(courseStartedStorageKey(sessionId, courseId)) === "1";
+  return storageHasMark(storage, courseStartedStorageKey(sessionId, courseId));
 }
 function markCourseStarted(storage, sessionId, courseId) {
   if (!courseId) return false;
-  return storage.setItem(courseStartedStorageKey(sessionId, courseId), "1");
+  return storageSetMark(storage, courseStartedStorageKey(sessionId, courseId));
 }
 function hasCourseStartedEmittedToTracking(storage, sessionId, courseId) {
   if (!courseId) return false;
-  return storage.getItem(courseStartedTrackingStorageKey(sessionId, courseId)) === "1";
+  return storageHasMark(storage, courseStartedTrackingStorageKey(sessionId, courseId));
 }
 function markCourseStartedEmittedToTracking(storage, sessionId, courseId) {
   if (!courseId) return false;
-  return storage.setItem(courseStartedTrackingStorageKey(sessionId, courseId), "1");
+  return storageSetMark(storage, courseStartedTrackingStorageKey(sessionId, courseId));
 }
 function hasCourseStartedPipelineDelivered(storage, sessionId, courseId) {
   if (!courseId) return false;
-  return storage.getItem(courseStartedPipelineStorageKey(sessionId, courseId)) === "1";
+  return storageHasMark(storage, courseStartedPipelineStorageKey(sessionId, courseId));
 }
 function markCourseStartedPipelineDelivered(storage, sessionId, courseId) {
   if (!courseId) return false;
-  return storage.setItem(courseStartedPipelineStorageKey(sessionId, courseId), "1");
+  return storageSetMark(storage, courseStartedPipelineStorageKey(sessionId, courseId));
 }
 function hasCourseStartedXapiSent(storage, sessionId, courseId) {
   if (!courseId) return false;
-  return storage.getItem(courseStartedXapiStorageKey(sessionId, courseId)) === "1";
+  return storageHasMark(storage, courseStartedXapiStorageKey(sessionId, courseId));
 }
 function markCourseStartedXapiSent(storage, sessionId, courseId) {
   if (!courseId) return false;
-  return storage.setItem(courseStartedXapiStorageKey(sessionId, courseId), "1");
+  return storageSetMark(storage, courseStartedXapiStorageKey(sessionId, courseId));
 }
 function resetSharedVolatileSessionIdForTests() {
 }
@@ -2028,6 +2161,7 @@ function migrateStorageMark(storage, fromKey, toKey, hasMark) {
   if (!hasMark) return;
   if (storage.setItem(toKey, "1")) {
     storage.removeItem?.(fromKey);
+    clearVolatileMark(storage, fromKey);
   }
 }
 function migrateCourseStartedMark(storage, fromSessionId, toSessionId, courseId) {
@@ -2060,9 +2194,16 @@ function migrateCourseStartedMark(storage, fromSessionId, toSessionId, courseId)
 
 // src/runtime/courseLifecycle.ts
 var courseStartedEmitFlights = /* @__PURE__ */ new Map();
+var courseStartedEmittedInTab = /* @__PURE__ */ new Set();
 function tryEmitCourseStarted(ctx, deps, alreadyEmittedToSink) {
   const flightKey = `${ctx.sessionId}:${ctx.courseId}`;
   const marked = hasCourseStarted(ctx.storage, ctx.sessionId, ctx.courseId);
+  if (courseStartedEmittedInTab.has(flightKey)) {
+    return Promise.resolve({
+      emitted: true,
+      marked: marked || markCourseStarted(ctx.storage, ctx.sessionId, ctx.courseId)
+    });
+  }
   if (alreadyEmittedToSink) {
     const markPersisted = marked ? true : markCourseStarted(ctx.storage, ctx.sessionId, ctx.courseId);
     return Promise.resolve({
@@ -2083,6 +2224,9 @@ function tryEmitCourseStarted(ctx, deps, alreadyEmittedToSink) {
   const flight = Promise.resolve().then(() => {
     try {
       const emitted = deps.emitCourseStartedEvent(ctx);
+      if (emitted) {
+        courseStartedEmittedInTab.add(flightKey);
+      }
       const markPersisted = emitted && !marked ? markCourseStarted(ctx.storage, ctx.sessionId, ctx.courseId) : marked;
       return {
         emitted,
@@ -2490,6 +2634,7 @@ function defineLifecyclePlugin(plugin) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ACCORDION_FORBIDDEN_CHILD_TYPES,
+  ASSESSMENT_17_CHILD_TYPES,
   ASSESSMENT_SEQUENCE_ALLOWED_CHILD_TYPES,
   BLOCKS_14_PAGE_SLIDE,
   BRANCHING_SCENARIO_ALLOWED_CHILD_TYPES,
@@ -2504,6 +2649,7 @@ function defineLifecyclePlugin(plugin) {
   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,
@@ -2548,6 +2694,7 @@ function defineLifecyclePlugin(plugin) {
   hasCourseStartedXapiSent,
   isChildTypeAllowed,
   isLifecycleTelemetryEvent,
+  isMultiSelectMcq,
   loadCompoundState,
   markCourseStarted,
   markCourseStartedEmittedToTracking,
@@ -2555,6 +2702,7 @@ function defineLifecyclePlugin(plugin) {
   markCourseStartedXapiSent,
   migrateCourseStartedMark,
   nowIso,
+  orderChoicesByIndices,
   parseBlockId,
   parseCheckId,
   parseCompoundResumeState,
@@ -2563,8 +2711,12 @@ function defineLifecyclePlugin(plugin) {
   resetSharedVolatileSessionIdForTests,
   resetStoragePortForTests,
   resetTelemetryBuilderWarningsForTests,
+  resolveMcqCorrectAnswers,
+  resolveMcqShuffleSeed,
   resolveSessionId,
   saveCompoundState,
+  scoreMcqSelection,
+  shuffleChoiceIndices,
   slugifyId,
   telemetryCatalogV2Version,
   telemetryCatalogV3Version,

package/dist/index.d.cts

@@ -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.cjs';
-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.cjs';
+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.cjs';
+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.cjs';
 
 /**
  * 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 };