@lessonkit/react 1.4.0 → 1.5.0

package/dist/index.d.cts

@@ -1,11 +1,11 @@
 import React__default from 'react';
 import * as _lessonkit_core from '@lessonkit/core';
-import { TelemetryEvent, CourseId, TelemetryUser, TrackingClient, LmsBridgeMode, LessonkitPlugin, ProgressState, StoragePort, LessonId, TelemetryEventName, TelemetryDataFor, PluginHost, McqAssessmentProps, BlockId, AssessmentAnsweredData, AssessmentCompletedData, CheckId } from '@lessonkit/core';
+import { TelemetryEvent, CourseId, TelemetryUser, TrackingClient, LmsBridgeMode, LessonkitPlugin, StoragePort, ProgressState, LessonId, TelemetryEventName, TelemetryDataFor, PluginHost, McqAssessmentProps, BlockId, AssessmentAnsweredData, AssessmentCompletedData, CheckId } from '@lessonkit/core';
 export { AssessmentAnsweredData, AssessmentBaseProps, AssessmentBehaviour, AssessmentCompletedData, AssessmentHandle, AssessmentInteractionType, AssessmentScoreInput, AssessmentScoreResult, AssessmentXAPIData, CompoundBaseProps, CompoundHandle, CompoundResumeState, InteractionBlockRegistration, LessonkitPlugin, LessonkitPluginContext, LessonkitPluginKind, LmsBridgeMode, McqAssessmentProps, PluginHost, PluginRegistry, TelemetryPipelineSink, buildTelemetryEvent, createLessonkitRuntime, createPluginRegistry, createTelemetryPipeline, defineAssessmentPlugin, defineLifecyclePlugin, defineTelemetryPlugin } from '@lessonkit/core';
 import * as _lessonkit_xapi from '@lessonkit/xapi';
 import { XAPITransport, XAPIClient } from '@lessonkit/xapi';
-export { Accordion, AccordionProps, AccordionSection, ArithmeticProblem, ArithmeticQuiz, ArithmeticQuizProps, AssessmentSequence, AssessmentSequenceProps, DialogCard, DialogCards, DialogCardsProps, DragAndDrop, DragAndDropProps, DragItem, DragTheWords, DragTheWordsProps, DropTarget, Essay, EssayProps, FillInBlankSpec, FillInTheBlanks, FillInTheBlanksProps, FindHotspot, FindHotspotProps, FindMultipleHotspots, FindMultipleHotspotsProps, Flashcard, Flashcards, FlashcardsProps, Heading, HeadingProps, HotspotSpec, HotspotTarget, Image, ImageHotspots, ImageHotspotsProps, ImagePair, ImagePairing, ImagePairingProps, ImageProps, ImageSequencing, ImageSequencingProps, ImageSlide, ImageSlider, ImageSliderProps, InformationPanel, InformationWall, InformationWallProps, InteractiveBook, InteractiveBookProps, InteractiveVideo, InteractiveVideoProps, MarkTheWords, MarkTheWordsProps, MemoryGame, MemoryGameProps, MemoryPair, Page, PageProps, ParallaxSlide, ParallaxSlideshow, ParallaxSlideshowProps, Questionnaire, QuestionnaireField, QuestionnaireProps, SequencingImage, Slide, SlideDeck, SlideDeckProps, SlideProps, Summary, SummaryProps, Text, TextProps, TimedCue, TimedCueProps, TrueFalse, TrueFalseProps, Video, VideoProps } from './blocks-entry.cjs';
-export { K as KnowledgeCheck, Q as Quiz, a as QuizProps, r as resetAssessmentWarningsForTests, b as resetQuizWarningsForTests } from './AssessmentLessonGuard-D2Plzybb.cjs';
+export { Accordion, AccordionProps, AccordionSection, ArithmeticProblem, ArithmeticQuiz, ArithmeticQuizProps, AssessmentSequence, AssessmentSequenceProps, BranchChoice, BranchChoiceProps, BranchNode, BranchNodeProps, BranchingScenario, BranchingScenarioProps, Chart, ChartDatum, ChartProps, DialogCard, DialogCards, DialogCardsProps, DragAndDrop, DragAndDropProps, DragItem, DragTheWords, DragTheWordsProps, DropTarget, Embed, EmbedProps, Essay, EssayProps, FillInBlankSpec, FillInTheBlanks, FillInTheBlanksProps, FindHotspot, FindHotspotProps, FindMultipleHotspots, FindMultipleHotspotsProps, Flashcard, Flashcards, FlashcardsProps, Heading, HeadingProps, HotspotSpec, HotspotTarget, Image, ImageHotspots, ImageHotspotsProps, ImagePair, ImagePairing, ImagePairingProps, ImageProps, ImageSequencing, ImageSequencingProps, ImageSlide, ImageSlider, ImageSliderProps, InformationPanel, InformationWall, InformationWallProps, InteractiveBook, InteractiveBookProps, InteractiveVideo, InteractiveVideoProps, MarkTheWords, MarkTheWordsProps, MemoryGame, MemoryGameProps, MemoryPair, Page, PageProps, ParallaxSlide, ParallaxSlideshow, ParallaxSlideshowProps, Questionnaire, QuestionnaireField, QuestionnaireProps, SequencingImage, Slide, SlideDeck, SlideDeckProps, SlideProps, Summary, SummaryProps, Text, TextProps, TimedCue, TimedCueProps, TrueFalse, TrueFalseProps, Video, VideoProps } from './blocks-entry.cjs';
+export { K as KnowledgeCheck, Q as Quiz, b as QuizProps, r as resetAssessmentWarningsForTests, a as resetQuizWarningsForTests } from './AssessmentLessonGuard-BzNPbjaV.cjs';
 import { LessonkitThemeV1, ThemePresetName, PartialLessonkitThemeV1 } from '@lessonkit/themes';
 export { ThemePresetName } from '@lessonkit/themes';
 
@@ -22,10 +22,29 @@ type LessonkitObservabilityConfig = {
     onTelemetryBufferDrop?: () => void;
     /** LMS bridge missing for a completion-related telemetry event (`bridge: auto`). */
     onLxpackBridgeMiss?: (event: TelemetryEvent) => void;
+    /** LMS bridge host threw while forwarding telemetry (`bridge: auto`). */
+    onLxpackBridgeError?: (err: unknown) => void;
     /** xAPI transport failure after retries (statement re-queued). */
     onXapiTransportError?: (err: unknown) => void;
+    /** Telemetry → xAPI mapping failure (statement skipped). */
+    onXapiMappingError?: (err: unknown) => void;
+    /** Compound child resume incomplete after hydration retries. */
+    onCompoundHydrationPartial?: (ctx: {
+        compoundId: string;
+        missingCheckIds: string[];
+    }) => void;
+    /** Corrupt compound resume blob or invalid child states stripped on load. */
+    onCompoundResumeCorrupt?: (ctx: {
+        compoundId: string;
+        droppedChildKeys?: string[];
+        corrupt?: boolean;
+    }) => void;
 };
 
+/**
+ * Runtime configuration for {@link LessonkitProvider} and {@link Course}.
+ * Pass tracking, xAPI, LMS bridge, observability hooks, and plugins here.
+ */
 type LessonkitConfig = {
     courseId: CourseId;
     session?: {
@@ -39,6 +58,12 @@ type LessonkitConfig = {
         enabled?: boolean;
         sink?: (event: Parameters<TrackingClient["track"]>[0]) => void | Promise<void>;
         batchSink?: (events: Parameters<TrackingClient["track"]>[0][]) => void | Promise<void>;
+        /** Factory for a custom tracking client (alternative to sink/batchSink). */
+        createClient?: () => TrackingClient;
+        /** Explicit opt-in for console sinks in production builds. */
+        consoleSink?: boolean;
+        /** Re-emit assessment telemetry when restoring session state (default false). */
+        replayResumeEvents?: boolean;
         /** Keepalive batch delivery for pagehide (e.g. from createFetchBatchSink). */
         exitBatchSink?: (events: Parameters<TrackingClient["track"]>[0][]) => void | Promise<void>;
         batch?: {
@@ -50,6 +75,8 @@ type LessonkitConfig = {
     xapi?: {
         enabled?: boolean;
         transport?: XAPITransport;
+        /** Explicit opt-in for console transport in production builds. */
+        consoleTransport?: boolean;
         /** Keepalive transport for pagehide (e.g. from createFetchTransport). */
         exitTransport?: _lessonkit_xapi.XAPIExitTransport;
         /** Abort in-flight transport by statement id (e.g. from createFetchTransport). */
@@ -59,6 +86,8 @@ type LessonkitConfig = {
     lxpack?: {
         /** Forward completion events to `window.parent.lxpackBridge.v1` when embedded (default `auto`). */
         bridge?: LmsBridgeMode;
+        /** Parent-frame origins allowed to receive bridge calls when `bridge` is `auto`. */
+        allowedParentOrigins?: string[];
     };
     /** Framework plugins (analytics, LMS, assessment, interaction, AI). */
     plugins?: LessonkitPlugin[];
@@ -68,6 +97,22 @@ type LessonkitConfig = {
     sinks?: _lessonkit_core.TelemetryPipelineSink[];
     /** Production hooks for sink failures, xAPI queue depth, and LMS bridge misses. */
     observability?: LessonkitObservabilityConfig;
+    /** Optional storage port override (default: per-provider sessionStorage-backed port). */
+    storage?: StoragePort;
+    /** Embed block security defaults. */
+    embed?: {
+        /** Strip `allow-popups` from iframe sandbox in production builds (default true). */
+        restrictPopupsInProduction?: boolean;
+        /** Hostnames allowed to bypass the production private-network media/embed blocklist. */
+        allowedHosts?: string[];
+    };
+    /**
+     * Non-production preview options. `allowConsoleTelemetry` skips production guard
+     * checks for console sinks (docs demos only — not for shipped LMS courses).
+     */
+    preview?: {
+        allowConsoleTelemetry?: boolean;
+    };
 };
 
 type LessonkitProviderProps = {
@@ -95,6 +140,10 @@ type LessonkitRuntime = {
     }) => void;
     plugins: PluginHost | null;
 };
+/**
+ * Root runtime provider for telemetry, xAPI, progress, and LMS bridge forwarding.
+ * Prefer wrapping with {@link Course} unless you need a custom layout.
+ */
 declare function LessonkitProvider(props: LessonkitProviderProps): React__default.JSX.Element;
 
 type CourseProps = {
@@ -126,7 +175,27 @@ type KnowledgeCheckProps = McqAssessmentProps;
 type ProgressTrackerProps = {
     totalLessons?: number;
 };
+/**
+ * Top-level course shell. Wraps {@link LessonkitProvider} and renders a semantic section with title.
+ *
+ * @example
+ * ```tsx
+ * <Course title="Security 101" courseId="sec-101" config={courseConfig}>
+ *   <Lesson title="Phishing" lessonId="phishing-101">…</Lesson>
+ * </Course>
+ * ```
+ */
 declare function Course(props: CourseProps): React__default.JSX.Element;
+/**
+ * Lesson container. Sets the active lesson on mount and emits lesson lifecycle telemetry.
+ *
+ * @example
+ * ```tsx
+ * <Lesson title="Phishing" lessonId="phishing-101">
+ *   <Scenario>…</Scenario>
+ * </Lesson>
+ * ```
+ */
 declare function Lesson(props: LessonProps): React__default.JSX.Element;
 declare function Scenario(props: ScenarioProps): React__default.JSX.Element;
 declare function Reflection(props: ReflectionProps): React__default.JSX.Element;
@@ -138,7 +207,9 @@ declare function useAssessmentState(enclosingLessonId?: LessonId): {
 };
 
 declare function useLessonkit(): LessonkitRuntime;
+/** Read course progress state (completed lessons, active lesson). */
 declare function useProgress(): _lessonkit_core.ProgressState;
+/** Emit typed telemetry events from custom UI (`track("interaction", …)`). */
 declare function useTracking(): {
     track: <N extends _lessonkit_core.TelemetryEventName>(name: N, data?: _lessonkit_core.TelemetryDataFor<N>, opts?: {
         lessonId?: LessonId;
@@ -171,7 +242,7 @@ declare function shouldEnforceProductionGuard(): boolean;
  * Throws in production when course config still uses dev-only console sinks or
  * omits observability hooks while telemetry/xAPI are enabled.
  */
-declare function assertProductionCourseConfig(config: Pick<LessonkitConfig, "tracking" | "xapi" | "observability" | "lxpack">): void;
+declare function assertProductionCourseConfig(config: Pick<LessonkitConfig, "tracking" | "xapi" | "observability" | "lxpack" | "preview">): void;
 
 type ThemeMode = "light" | "dark" | "system";
 type ThemeResolvedMode = "light" | "dark";
@@ -193,6 +264,22 @@ type ThemeContextValue = {
 declare function ThemeProvider(props: ThemeProviderProps): React__default.JSX.Element;
 declare function useTheme(): ThemeContextValue;
 
+type BranchingScenarioContextValue = {
+    compoundBlockId: string;
+    activeNodeId: string;
+    visitedNodeIds: readonly string[];
+    visitedLabels: readonly string[];
+    navigateToNode: (opts: {
+        fromNodeId: string;
+        toNodeId: string;
+        label: string;
+        scoreWeight?: number;
+    }) => void;
+    isTerminal: boolean;
+    choicesLocked: boolean;
+};
+declare function useBranchingScenario(): BranchingScenarioContextValue;
+
 declare const blockCatalogVersion: 1;
 declare const blockCatalogV2Version: 2;
 declare const blockCatalogV3Version: 3;
@@ -454,4 +541,4 @@ type BuildBlockCatalogOptions = {
 declare function buildBlockCatalog(opts?: BuildBlockCatalogOptions): BlockCatalogEntry[] | BlockCatalogEntryV2[] | BlockCatalogEntryV3[];
 declare function getBlockCatalogEntry(type: string, opts?: BuildBlockCatalogOptions): BlockCatalogEntry | BlockCatalogEntryV2 | BlockCatalogEntryV3 | undefined;
 
-export { BLOCK_CATALOG, BLOCK_CATALOG_V2, BLOCK_CATALOG_V3, type BlockCatalogEntry, type BlockCatalogEntryV2, type BlockCatalogEntryV3, type BlockPropSpec, Course, type CourseProps, type KnowledgeCheckProps, Lesson, type LessonProps, type LessonkitConfig, type LessonkitObservabilityConfig, LessonkitProvider, type LessonkitProviderProps, type LessonkitRuntime, ProgressTracker, type ProgressTrackerProps, Reflection, type ReflectionProps, Scenario, type ScenarioProps, type ThemeContextValue, type ThemeMode, ThemeProvider, type ThemeProviderProps, type ThemeResolvedMode, assertProductionCourseConfig, blockCatalogV2Version, blockCatalogV3Version, blockCatalogVersion, buildBlockCatalog, getBlockCatalogEntry, shouldEnforceProductionGuard, useAssessmentState, useCompletion, useLessonkit, useProgress, useQuizState, useTheme, useTracking };
+export { BLOCK_CATALOG, BLOCK_CATALOG_V2, BLOCK_CATALOG_V3, type BlockCatalogEntry, type BlockCatalogEntryV2, type BlockCatalogEntryV3, type BlockPropSpec, Course, type CourseProps, type KnowledgeCheckProps, Lesson, type LessonProps, type LessonkitConfig, type LessonkitObservabilityConfig, LessonkitProvider, type LessonkitProviderProps, type LessonkitRuntime, ProgressTracker, type ProgressTrackerProps, Reflection, type ReflectionProps, Scenario, type ScenarioProps, type ThemeContextValue, type ThemeMode, ThemeProvider, type ThemeProviderProps, type ThemeResolvedMode, assertProductionCourseConfig, blockCatalogV2Version, blockCatalogV3Version, blockCatalogVersion, buildBlockCatalog, getBlockCatalogEntry, shouldEnforceProductionGuard, useAssessmentState, useBranchingScenario, useCompletion, useLessonkit, useProgress, useQuizState, useTheme, useTracking };

package/dist/index.d.ts

@@ -1,11 +1,11 @@
 import React__default from 'react';
 import * as _lessonkit_core from '@lessonkit/core';
-import { TelemetryEvent, CourseId, TelemetryUser, TrackingClient, LmsBridgeMode, LessonkitPlugin, ProgressState, StoragePort, LessonId, TelemetryEventName, TelemetryDataFor, PluginHost, McqAssessmentProps, BlockId, AssessmentAnsweredData, AssessmentCompletedData, CheckId } from '@lessonkit/core';
+import { TelemetryEvent, CourseId, TelemetryUser, TrackingClient, LmsBridgeMode, LessonkitPlugin, StoragePort, ProgressState, LessonId, TelemetryEventName, TelemetryDataFor, PluginHost, McqAssessmentProps, BlockId, AssessmentAnsweredData, AssessmentCompletedData, CheckId } from '@lessonkit/core';
 export { AssessmentAnsweredData, AssessmentBaseProps, AssessmentBehaviour, AssessmentCompletedData, AssessmentHandle, AssessmentInteractionType, AssessmentScoreInput, AssessmentScoreResult, AssessmentXAPIData, CompoundBaseProps, CompoundHandle, CompoundResumeState, InteractionBlockRegistration, LessonkitPlugin, LessonkitPluginContext, LessonkitPluginKind, LmsBridgeMode, McqAssessmentProps, PluginHost, PluginRegistry, TelemetryPipelineSink, buildTelemetryEvent, createLessonkitRuntime, createPluginRegistry, createTelemetryPipeline, defineAssessmentPlugin, defineLifecyclePlugin, defineTelemetryPlugin } from '@lessonkit/core';
 import * as _lessonkit_xapi from '@lessonkit/xapi';
 import { XAPITransport, XAPIClient } from '@lessonkit/xapi';
-export { Accordion, AccordionProps, AccordionSection, ArithmeticProblem, ArithmeticQuiz, ArithmeticQuizProps, AssessmentSequence, AssessmentSequenceProps, DialogCard, DialogCards, DialogCardsProps, DragAndDrop, DragAndDropProps, DragItem, DragTheWords, DragTheWordsProps, DropTarget, Essay, EssayProps, FillInBlankSpec, FillInTheBlanks, FillInTheBlanksProps, FindHotspot, FindHotspotProps, FindMultipleHotspots, FindMultipleHotspotsProps, Flashcard, Flashcards, FlashcardsProps, Heading, HeadingProps, HotspotSpec, HotspotTarget, Image, ImageHotspots, ImageHotspotsProps, ImagePair, ImagePairing, ImagePairingProps, ImageProps, ImageSequencing, ImageSequencingProps, ImageSlide, ImageSlider, ImageSliderProps, InformationPanel, InformationWall, InformationWallProps, InteractiveBook, InteractiveBookProps, InteractiveVideo, InteractiveVideoProps, MarkTheWords, MarkTheWordsProps, MemoryGame, MemoryGameProps, MemoryPair, Page, PageProps, ParallaxSlide, ParallaxSlideshow, ParallaxSlideshowProps, Questionnaire, QuestionnaireField, QuestionnaireProps, SequencingImage, Slide, SlideDeck, SlideDeckProps, SlideProps, Summary, SummaryProps, Text, TextProps, TimedCue, TimedCueProps, TrueFalse, TrueFalseProps, Video, VideoProps } from './blocks-entry.js';
-export { K as KnowledgeCheck, Q as Quiz, a as QuizProps, r as resetAssessmentWarningsForTests, b as resetQuizWarningsForTests } from './AssessmentLessonGuard-D2Plzybb.js';
+export { Accordion, AccordionProps, AccordionSection, ArithmeticProblem, ArithmeticQuiz, ArithmeticQuizProps, AssessmentSequence, AssessmentSequenceProps, BranchChoice, BranchChoiceProps, BranchNode, BranchNodeProps, BranchingScenario, BranchingScenarioProps, Chart, ChartDatum, ChartProps, DialogCard, DialogCards, DialogCardsProps, DragAndDrop, DragAndDropProps, DragItem, DragTheWords, DragTheWordsProps, DropTarget, Embed, EmbedProps, Essay, EssayProps, FillInBlankSpec, FillInTheBlanks, FillInTheBlanksProps, FindHotspot, FindHotspotProps, FindMultipleHotspots, FindMultipleHotspotsProps, Flashcard, Flashcards, FlashcardsProps, Heading, HeadingProps, HotspotSpec, HotspotTarget, Image, ImageHotspots, ImageHotspotsProps, ImagePair, ImagePairing, ImagePairingProps, ImageProps, ImageSequencing, ImageSequencingProps, ImageSlide, ImageSlider, ImageSliderProps, InformationPanel, InformationWall, InformationWallProps, InteractiveBook, InteractiveBookProps, InteractiveVideo, InteractiveVideoProps, MarkTheWords, MarkTheWordsProps, MemoryGame, MemoryGameProps, MemoryPair, Page, PageProps, ParallaxSlide, ParallaxSlideshow, ParallaxSlideshowProps, Questionnaire, QuestionnaireField, QuestionnaireProps, SequencingImage, Slide, SlideDeck, SlideDeckProps, SlideProps, Summary, SummaryProps, Text, TextProps, TimedCue, TimedCueProps, TrueFalse, TrueFalseProps, Video, VideoProps } from './blocks-entry.js';
+export { K as KnowledgeCheck, Q as Quiz, b as QuizProps, r as resetAssessmentWarningsForTests, a as resetQuizWarningsForTests } from './AssessmentLessonGuard-BzNPbjaV.js';
 import { LessonkitThemeV1, ThemePresetName, PartialLessonkitThemeV1 } from '@lessonkit/themes';
 export { ThemePresetName } from '@lessonkit/themes';
 
@@ -22,10 +22,29 @@ type LessonkitObservabilityConfig = {
     onTelemetryBufferDrop?: () => void;
     /** LMS bridge missing for a completion-related telemetry event (`bridge: auto`). */
     onLxpackBridgeMiss?: (event: TelemetryEvent) => void;
+    /** LMS bridge host threw while forwarding telemetry (`bridge: auto`). */
+    onLxpackBridgeError?: (err: unknown) => void;
     /** xAPI transport failure after retries (statement re-queued). */
     onXapiTransportError?: (err: unknown) => void;
+    /** Telemetry → xAPI mapping failure (statement skipped). */
+    onXapiMappingError?: (err: unknown) => void;
+    /** Compound child resume incomplete after hydration retries. */
+    onCompoundHydrationPartial?: (ctx: {
+        compoundId: string;
+        missingCheckIds: string[];
+    }) => void;
+    /** Corrupt compound resume blob or invalid child states stripped on load. */
+    onCompoundResumeCorrupt?: (ctx: {
+        compoundId: string;
+        droppedChildKeys?: string[];
+        corrupt?: boolean;
+    }) => void;
 };
 
+/**
+ * Runtime configuration for {@link LessonkitProvider} and {@link Course}.
+ * Pass tracking, xAPI, LMS bridge, observability hooks, and plugins here.
+ */
 type LessonkitConfig = {
     courseId: CourseId;
     session?: {
@@ -39,6 +58,12 @@ type LessonkitConfig = {
         enabled?: boolean;
         sink?: (event: Parameters<TrackingClient["track"]>[0]) => void | Promise<void>;
         batchSink?: (events: Parameters<TrackingClient["track"]>[0][]) => void | Promise<void>;
+        /** Factory for a custom tracking client (alternative to sink/batchSink). */
+        createClient?: () => TrackingClient;
+        /** Explicit opt-in for console sinks in production builds. */
+        consoleSink?: boolean;
+        /** Re-emit assessment telemetry when restoring session state (default false). */
+        replayResumeEvents?: boolean;
         /** Keepalive batch delivery for pagehide (e.g. from createFetchBatchSink). */
         exitBatchSink?: (events: Parameters<TrackingClient["track"]>[0][]) => void | Promise<void>;
         batch?: {
@@ -50,6 +75,8 @@ type LessonkitConfig = {
     xapi?: {
         enabled?: boolean;
         transport?: XAPITransport;
+        /** Explicit opt-in for console transport in production builds. */
+        consoleTransport?: boolean;
         /** Keepalive transport for pagehide (e.g. from createFetchTransport). */
         exitTransport?: _lessonkit_xapi.XAPIExitTransport;
         /** Abort in-flight transport by statement id (e.g. from createFetchTransport). */
@@ -59,6 +86,8 @@ type LessonkitConfig = {
     lxpack?: {
         /** Forward completion events to `window.parent.lxpackBridge.v1` when embedded (default `auto`). */
         bridge?: LmsBridgeMode;
+        /** Parent-frame origins allowed to receive bridge calls when `bridge` is `auto`. */
+        allowedParentOrigins?: string[];
     };
     /** Framework plugins (analytics, LMS, assessment, interaction, AI). */
     plugins?: LessonkitPlugin[];
@@ -68,6 +97,22 @@ type LessonkitConfig = {
     sinks?: _lessonkit_core.TelemetryPipelineSink[];
     /** Production hooks for sink failures, xAPI queue depth, and LMS bridge misses. */
     observability?: LessonkitObservabilityConfig;
+    /** Optional storage port override (default: per-provider sessionStorage-backed port). */
+    storage?: StoragePort;
+    /** Embed block security defaults. */
+    embed?: {
+        /** Strip `allow-popups` from iframe sandbox in production builds (default true). */
+        restrictPopupsInProduction?: boolean;
+        /** Hostnames allowed to bypass the production private-network media/embed blocklist. */
+        allowedHosts?: string[];
+    };
+    /**
+     * Non-production preview options. `allowConsoleTelemetry` skips production guard
+     * checks for console sinks (docs demos only — not for shipped LMS courses).
+     */
+    preview?: {
+        allowConsoleTelemetry?: boolean;
+    };
 };
 
 type LessonkitProviderProps = {
@@ -95,6 +140,10 @@ type LessonkitRuntime = {
     }) => void;
     plugins: PluginHost | null;
 };
+/**
+ * Root runtime provider for telemetry, xAPI, progress, and LMS bridge forwarding.
+ * Prefer wrapping with {@link Course} unless you need a custom layout.
+ */
 declare function LessonkitProvider(props: LessonkitProviderProps): React__default.JSX.Element;
 
 type CourseProps = {
@@ -126,7 +175,27 @@ type KnowledgeCheckProps = McqAssessmentProps;
 type ProgressTrackerProps = {
     totalLessons?: number;
 };
+/**
+ * Top-level course shell. Wraps {@link LessonkitProvider} and renders a semantic section with title.
+ *
+ * @example
+ * ```tsx
+ * <Course title="Security 101" courseId="sec-101" config={courseConfig}>
+ *   <Lesson title="Phishing" lessonId="phishing-101">…</Lesson>
+ * </Course>
+ * ```
+ */
 declare function Course(props: CourseProps): React__default.JSX.Element;
+/**
+ * Lesson container. Sets the active lesson on mount and emits lesson lifecycle telemetry.
+ *
+ * @example
+ * ```tsx
+ * <Lesson title="Phishing" lessonId="phishing-101">
+ *   <Scenario>…</Scenario>
+ * </Lesson>
+ * ```
+ */
 declare function Lesson(props: LessonProps): React__default.JSX.Element;
 declare function Scenario(props: ScenarioProps): React__default.JSX.Element;
 declare function Reflection(props: ReflectionProps): React__default.JSX.Element;
@@ -138,7 +207,9 @@ declare function useAssessmentState(enclosingLessonId?: LessonId): {
 };
 
 declare function useLessonkit(): LessonkitRuntime;
+/** Read course progress state (completed lessons, active lesson). */
 declare function useProgress(): _lessonkit_core.ProgressState;
+/** Emit typed telemetry events from custom UI (`track("interaction", …)`). */
 declare function useTracking(): {
     track: <N extends _lessonkit_core.TelemetryEventName>(name: N, data?: _lessonkit_core.TelemetryDataFor<N>, opts?: {
         lessonId?: LessonId;
@@ -171,7 +242,7 @@ declare function shouldEnforceProductionGuard(): boolean;
  * Throws in production when course config still uses dev-only console sinks or
  * omits observability hooks while telemetry/xAPI are enabled.
  */
-declare function assertProductionCourseConfig(config: Pick<LessonkitConfig, "tracking" | "xapi" | "observability" | "lxpack">): void;
+declare function assertProductionCourseConfig(config: Pick<LessonkitConfig, "tracking" | "xapi" | "observability" | "lxpack" | "preview">): void;
 
 type ThemeMode = "light" | "dark" | "system";
 type ThemeResolvedMode = "light" | "dark";
@@ -193,6 +264,22 @@ type ThemeContextValue = {
 declare function ThemeProvider(props: ThemeProviderProps): React__default.JSX.Element;
 declare function useTheme(): ThemeContextValue;
 
+type BranchingScenarioContextValue = {
+    compoundBlockId: string;
+    activeNodeId: string;
+    visitedNodeIds: readonly string[];
+    visitedLabels: readonly string[];
+    navigateToNode: (opts: {
+        fromNodeId: string;
+        toNodeId: string;
+        label: string;
+        scoreWeight?: number;
+    }) => void;
+    isTerminal: boolean;
+    choicesLocked: boolean;
+};
+declare function useBranchingScenario(): BranchingScenarioContextValue;
+
 declare const blockCatalogVersion: 1;
 declare const blockCatalogV2Version: 2;
 declare const blockCatalogV3Version: 3;
@@ -454,4 +541,4 @@ type BuildBlockCatalogOptions = {
 declare function buildBlockCatalog(opts?: BuildBlockCatalogOptions): BlockCatalogEntry[] | BlockCatalogEntryV2[] | BlockCatalogEntryV3[];
 declare function getBlockCatalogEntry(type: string, opts?: BuildBlockCatalogOptions): BlockCatalogEntry | BlockCatalogEntryV2 | BlockCatalogEntryV3 | undefined;
 
-export { BLOCK_CATALOG, BLOCK_CATALOG_V2, BLOCK_CATALOG_V3, type BlockCatalogEntry, type BlockCatalogEntryV2, type BlockCatalogEntryV3, type BlockPropSpec, Course, type CourseProps, type KnowledgeCheckProps, Lesson, type LessonProps, type LessonkitConfig, type LessonkitObservabilityConfig, LessonkitProvider, type LessonkitProviderProps, type LessonkitRuntime, ProgressTracker, type ProgressTrackerProps, Reflection, type ReflectionProps, Scenario, type ScenarioProps, type ThemeContextValue, type ThemeMode, ThemeProvider, type ThemeProviderProps, type ThemeResolvedMode, assertProductionCourseConfig, blockCatalogV2Version, blockCatalogV3Version, blockCatalogVersion, buildBlockCatalog, getBlockCatalogEntry, shouldEnforceProductionGuard, useAssessmentState, useCompletion, useLessonkit, useProgress, useQuizState, useTheme, useTracking };
+export { BLOCK_CATALOG, BLOCK_CATALOG_V2, BLOCK_CATALOG_V3, type BlockCatalogEntry, type BlockCatalogEntryV2, type BlockCatalogEntryV3, type BlockPropSpec, Course, type CourseProps, type KnowledgeCheckProps, Lesson, type LessonProps, type LessonkitConfig, type LessonkitObservabilityConfig, LessonkitProvider, type LessonkitProviderProps, type LessonkitRuntime, ProgressTracker, type ProgressTrackerProps, Reflection, type ReflectionProps, Scenario, type ScenarioProps, type ThemeContextValue, type ThemeMode, ThemeProvider, type ThemeProviderProps, type ThemeResolvedMode, assertProductionCourseConfig, blockCatalogV2Version, blockCatalogV3Version, blockCatalogVersion, buildBlockCatalog, getBlockCatalogEntry, shouldEnforceProductionGuard, useAssessmentState, useBranchingScenario, useCompletion, useLessonkit, useProgress, useQuizState, useTheme, useTracking };

package/dist/index.js

@@ -2,9 +2,14 @@ import {
   Accordion,
   ArithmeticQuiz,
   AssessmentSequence,
+  BranchChoice,
+  BranchNode,
+  BranchingScenario,
+  Chart,
   DialogCards,
   DragAndDrop,
   DragTheWords,
+  Embed,
   Essay,
   FillInTheBlanks,
   FindHotspot,
@@ -30,15 +35,16 @@ import {
   Text,
   TimedCue,
   TrueFalse,
-  Video
-} from "./chunk-4LQ4TTEE.js";
+  Video,
+  useBranchingScenario
+} from "./chunk-5P23C2W3.js";
 import {
   KnowledgeCheck,
   Quiz,
   getLessonMountCount,
   registerLessonMount,
   resetQuizWarningsForTests
-} from "./chunk-UUTXECVW.js";
+} from "./chunk-ELGQ4XI3.js";
 import {
   LessonContext,
   LessonkitProvider,
@@ -52,7 +58,7 @@ import {
   useProgress,
   useQuizState,
   useTracking
-} from "./chunk-TDM3ARE7.js";
+} from "./chunk-7TJQJFYR.js";
 
 // src/components.tsx
 import { useEffect, useId, useMemo, useRef, useState } from "react";
@@ -313,6 +319,8 @@ function useTheme() {
 // src/catalogV3Entries.ts
 import {
   ASSESSMENT_SEQUENCE_ALLOWED_CHILD_TYPES,
+  BRANCHING_SCENARIO_ALLOWED_CHILD_TYPES,
+  BRANCH_NODE_ALLOWED_CHILD_TYPES,
   INTERACTIVE_BOOK_ALLOWED_CHILD_TYPES,
   INTERACTIVE_VIDEO_ALLOWED_CHILD_TYPES,
   PAGE_ALLOWED_CHILD_TYPES,
@@ -329,7 +337,9 @@ var COMPOUND_PARENTS = [
   "SlideDeck",
   "TimedCue",
   "InteractiveVideo",
-  "AssessmentSequence"
+  "AssessmentSequence",
+  "BranchingScenario",
+  "BranchNode"
 ];
 function extendParents(entry) {
   if (!entry.parentConstraints?.length) return entry;
@@ -548,6 +558,110 @@ var v3CompoundAndContentEntries = [
     theming: { surface: "global-inherit", stylingNotes: "Video + overlay." },
     telemetry: { emits: ["video_cue_reached", "video_segment_completed"], requiresActiveLesson: true }
   },
+  {
+    type: "BranchNode",
+    category: "container",
+    compoundContract: true,
+    h5pMachineName: "H5P.BranchingScenario",
+    h5pAlias: "Branching Scenario node",
+    description: "Graph node in a BranchingScenario with content and choices.",
+    allowedChildTypes: [...BRANCH_NODE_ALLOWED_CHILD_TYPES],
+    maxNestingDepth: COMPOUND_MAX_NESTING_DEPTH.BranchNode,
+    props: [
+      { name: "nodeId", type: "string", required: true, description: "Unique node id within the scenario." },
+      { name: "title", type: "string", required: false, description: "Node title." },
+      { name: "terminal", type: "boolean", required: false, description: "End state node." },
+      { name: "children", type: "ReactNode", required: true, description: "Content and BranchChoice controls." }
+    ],
+    requiredIds: [],
+    parentConstraints: ["BranchingScenario"],
+    a11y: { element: "section", ariaLabel: "Branch node", keyboard: "Branch choices are buttons.", notes: "H5P Branching Scenario node." },
+    theming: { surface: "global-inherit", stylingNotes: "Node panel." },
+    telemetry: { emits: ["branch_node_viewed"], requiresActiveLesson: true }
+  },
+  {
+    type: "BranchChoice",
+    category: "content",
+    h5pMachineName: "H5P.BranchingScenario",
+    h5pAlias: "Branching Scenario choice",
+    description: "Transition control linking to a target BranchNode.",
+    props: [
+      { name: "label", type: "string", required: true, description: "Choice label." },
+      { name: "targetNodeId", type: "string", required: true, description: "Target node id." },
+      { name: "scoreWeight", type: "number", required: false, description: "Optional choice score weight." },
+      { name: "disabled", type: "boolean", required: false, description: "Disable choice." }
+    ],
+    requiredIds: [],
+    parentConstraints: ["BranchNode"],
+    a11y: { element: "button", ariaLabel: "Branch choice", keyboard: "Activate to follow branch.", notes: "Radio group pattern." },
+    theming: { surface: "global-inherit", stylingNotes: "Choice button." },
+    telemetry: { emits: ["branch_selected"], requiresActiveLesson: true }
+  },
+  {
+    type: "BranchingScenario",
+    category: "container",
+    compoundContract: true,
+    h5pMachineName: "H5P.BranchingScenario",
+    h5pAlias: "Branching Scenario",
+    description: "Graph-based branching narrative with scored paths.",
+    allowedChildTypes: [...BRANCHING_SCENARIO_ALLOWED_CHILD_TYPES],
+    maxNestingDepth: COMPOUND_MAX_NESTING_DEPTH.BranchingScenario,
+    props: [
+      { name: "blockId", type: "BlockId", required: true, description: "Stable block id." },
+      { name: "title", type: "string", required: true, description: "Scenario title." },
+      { name: "startNodeId", type: "string", required: true, description: "Entry node id." },
+      { name: "showPathScore", type: "boolean", required: false, description: "Show visited-path score." },
+      { name: "showPathRecap", type: "boolean", required: false, description: "Show path recap on terminal nodes." },
+      { name: "children", type: "BranchNode[]", required: true, description: "Branch nodes." }
+    ],
+    requiredIds: ["blockId"],
+    parentConstraints: ["Lesson"],
+    a11y: {
+      element: "section",
+      ariaLabel: "Branching scenario",
+      keyboard: "Branch choices; assessments in nodes.",
+      notes: "H5P Branching Scenario equivalent."
+    },
+    theming: { surface: "global-inherit", stylingNotes: "Scenario chrome." },
+    telemetry: { emits: ["branch_node_viewed", "branch_selected"], requiresActiveLesson: true }
+  },
+  {
+    type: "Embed",
+    category: "content",
+    h5pMachineName: "H5P.IFrameEmbed",
+    h5pAlias: "Iframe Embedder",
+    description: "Sandboxed iframe embed with restrictive defaults.",
+    props: [
+      { name: "blockId", type: "BlockId", required: true, description: "Stable block id." },
+      { name: "src", type: "string", required: true, description: "Embed URL." },
+      { name: "title", type: "string", required: true, description: "Accessible title." },
+      { name: "allow", type: "string", required: false, description: "Extra sandbox allow tokens." },
+      { name: "aspectRatio", type: "string", required: false, description: "CSS aspect-ratio." }
+    ],
+    requiredIds: ["blockId"],
+    parentConstraints: [...COMPOUND_PARENTS],
+    a11y: { element: "iframe", ariaLabel: "Embedded content", keyboard: "Focus enters iframe.", notes: "Sandboxed; opt-in allow list." },
+    theming: { surface: "global-inherit", stylingNotes: "Responsive iframe." },
+    telemetry: { emits: ["interaction"] }
+  },
+  {
+    type: "Chart",
+    category: "content",
+    h5pMachineName: "H5P.Chart",
+    h5pAlias: "Chart",
+    description: "Simple bar or pie chart with accessible data table.",
+    props: [
+      { name: "blockId", type: "BlockId", required: true, description: "Stable block id." },
+      { name: "type", type: "bar | pie", required: true, description: "Chart type." },
+      { name: "data", type: "ChartDatum[]", required: true, description: "Chart data." },
+      { name: "title", type: "string", required: false, description: "Chart title." }
+    ],
+    requiredIds: ["blockId"],
+    parentConstraints: [...COMPOUND_PARENTS],
+    a11y: { element: "figure", ariaLabel: "Chart", keyboard: "Data table fallback.", notes: "Table exposes values to screen readers." },
+    theming: { surface: "global-inherit", stylingNotes: "Simple SVG/CSS chart." },
+    telemetry: { emits: ["interaction"] }
+  },
   {
     type: "Questionnaire",
     category: "content",
@@ -1231,10 +1345,15 @@ export {
   BLOCK_CATALOG,
   BLOCK_CATALOG_V2,
   BLOCK_CATALOG_V3,
+  BranchChoice,
+  BranchNode,
+  BranchingScenario,
+  Chart,
   Course,
   DialogCards,
   DragAndDrop,
   DragTheWords,
+  Embed,
   Essay,
   FillInTheBlanks,
   FindHotspot,
@@ -1286,6 +1405,7 @@ export {
   resetQuizWarningsForTests,
   shouldEnforceProductionGuard,
   useAssessmentState,
+  useBranchingScenario,
   useCompletion,
   useLessonkit,
   useProgress,