@ct-player/embed 1.1.11 → 1.2.1

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import * as react from 'react';
-import react__default from 'react';
+import * as React__default from 'react';
+import React__default__default from 'react';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import Hls from 'hls.js';
 
@@ -11,7 +11,7 @@ import Hls from 'hls.js';
 /**
  * All possible event types in the .ct format
  */
-type CTEventType = 'init' | 'code' | 'code_edit' | 'language' | 'terminal' | 'terminal_input' | 'stroke_start' | 'whiteboard_points' | 'stroke_end' | 'whiteboard_stroke' | 'whiteboard_clear' | 'whiteboard_undo' | 'whiteboard' | 'whiteboard_point' | 'excalidraw_scene' | 'excalidraw_clear' | 'document_load' | 'document_page' | 'document_zoom' | 'document_scroll' | 'document_clear' | 'file_create' | 'file_update' | 'file_delete' | 'file_rename' | 'file_switch' | 'folder_create' | 'folder_delete' | 'file_select' | 'file_change' | 'file_creation_start' | 'file_creation_input' | 'file_creation_cancel' | 'file_rename_start' | 'file_rename_input' | 'file_rename_cancel' | 'folder_toggle' | 'cursor_move' | 'cursor_click' | 'cursor_enter' | 'cursor_leave' | 'file_hover' | 'text_select' | 'editor_cursor' | 'tool_switch' | 'tool' | 'marker';
+type CTEventType = 'init' | 'code' | 'code_edit' | 'language' | 'terminal' | 'terminal_input' | 'stroke_start' | 'whiteboard_points' | 'stroke_end' | 'whiteboard_stroke' | 'whiteboard_clear' | 'whiteboard_undo' | 'whiteboard' | 'whiteboard_point' | 'excalidraw_scene' | 'excalidraw_clear' | 'excalidraw_pointer' | 'overlay_scene' | 'overlay_clear' | 'overlay_pointer' | 'document_load' | 'document_page' | 'document_zoom' | 'document_scroll' | 'document_clear' | 'file_create' | 'file_update' | 'file_delete' | 'file_rename' | 'file_switch' | 'folder_create' | 'folder_delete' | 'file_select' | 'file_change' | 'file_creation_start' | 'file_creation_input' | 'file_creation_cancel' | 'file_rename_start' | 'file_rename_input' | 'file_rename_cancel' | 'folder_toggle' | 'cursor_move' | 'cursor_click' | 'cursor_enter' | 'cursor_leave' | 'file_hover' | 'text_select' | 'editor_cursor' | 'tool_switch' | 'tool' | 'marker' | 'webcam_state' | 'content_dimensions';
 /**
  * Base event structure with generic type parameter
  */
@@ -27,7 +27,7 @@ interface CTEventBase<T extends CTEventType = CTEventType> {
  * Discriminated union of all event types.
  * This enables proper type narrowing in switch statements.
  */
-type CTEvent = CTEventBase<'init'> | CTEventBase<'code'> | CTEventBase<'code_edit'> | CTEventBase<'language'> | CTEventBase<'terminal'> | CTEventBase<'terminal_input'> | CTEventBase<'stroke_start'> | CTEventBase<'whiteboard_points'> | CTEventBase<'stroke_end'> | CTEventBase<'whiteboard_stroke'> | CTEventBase<'whiteboard_clear'> | CTEventBase<'whiteboard_undo'> | CTEventBase<'whiteboard'> | CTEventBase<'whiteboard_point'> | CTEventBase<'excalidraw_scene'> | CTEventBase<'excalidraw_clear'> | CTEventBase<'document_load'> | CTEventBase<'document_page'> | CTEventBase<'document_zoom'> | CTEventBase<'document_scroll'> | CTEventBase<'document_clear'> | CTEventBase<'file_create'> | CTEventBase<'file_update'> | CTEventBase<'file_delete'> | CTEventBase<'file_rename'> | CTEventBase<'file_switch'> | CTEventBase<'folder_create'> | CTEventBase<'folder_delete'> | CTEventBase<'file_select'> | CTEventBase<'file_change'> | CTEventBase<'file_creation_start'> | CTEventBase<'file_creation_input'> | CTEventBase<'file_creation_cancel'> | CTEventBase<'file_rename_start'> | CTEventBase<'file_rename_input'> | CTEventBase<'file_rename_cancel'> | CTEventBase<'folder_toggle'> | CTEventBase<'cursor_move'> | CTEventBase<'cursor_click'> | CTEventBase<'cursor_enter'> | CTEventBase<'cursor_leave'> | CTEventBase<'file_hover'> | CTEventBase<'text_select'> | CTEventBase<'editor_cursor'> | CTEventBase<'tool_switch'> | CTEventBase<'tool'> | CTEventBase<'marker'>;
+type CTEvent = CTEventBase<'init'> | CTEventBase<'code'> | CTEventBase<'code_edit'> | CTEventBase<'language'> | CTEventBase<'terminal'> | CTEventBase<'terminal_input'> | CTEventBase<'stroke_start'> | CTEventBase<'whiteboard_points'> | CTEventBase<'stroke_end'> | CTEventBase<'whiteboard_stroke'> | CTEventBase<'whiteboard_clear'> | CTEventBase<'whiteboard_undo'> | CTEventBase<'whiteboard'> | CTEventBase<'whiteboard_point'> | CTEventBase<'excalidraw_scene'> | CTEventBase<'excalidraw_clear'> | CTEventBase<'excalidraw_pointer'> | CTEventBase<'overlay_scene'> | CTEventBase<'overlay_clear'> | CTEventBase<'overlay_pointer'> | CTEventBase<'document_load'> | CTEventBase<'document_page'> | CTEventBase<'document_zoom'> | CTEventBase<'document_scroll'> | CTEventBase<'document_clear'> | CTEventBase<'file_create'> | CTEventBase<'file_update'> | CTEventBase<'file_delete'> | CTEventBase<'file_rename'> | CTEventBase<'file_switch'> | CTEventBase<'folder_create'> | CTEventBase<'folder_delete'> | CTEventBase<'file_select'> | CTEventBase<'file_change'> | CTEventBase<'file_creation_start'> | CTEventBase<'file_creation_input'> | CTEventBase<'file_creation_cancel'> | CTEventBase<'file_rename_start'> | CTEventBase<'file_rename_input'> | CTEventBase<'file_rename_cancel'> | CTEventBase<'folder_toggle'> | CTEventBase<'cursor_move'> | CTEventBase<'cursor_click'> | CTEventBase<'cursor_enter'> | CTEventBase<'cursor_leave'> | CTEventBase<'file_hover'> | CTEventBase<'text_select'> | CTEventBase<'editor_cursor'> | CTEventBase<'tool_switch'> | CTEventBase<'tool'> | CTEventBase<'marker'> | CTEventBase<'webcam_state'> | CTEventBase<'content_dimensions'>;
 /**
  * Mapping of event types to their data structures
  */
@@ -46,6 +46,10 @@ interface CTEventDataMap {
     whiteboard_undo: WhiteboardUndoEventData;
     excalidraw_scene: ExcalidrawSceneEventData;
     excalidraw_clear: ExcalidrawClearEventData;
+    excalidraw_pointer: ExcalidrawPointerEventData;
+    overlay_scene: ExcalidrawSceneEventData;
+    overlay_clear: ExcalidrawClearEventData;
+    overlay_pointer: ExcalidrawPointerEventData;
     document_load: DocumentLoadEventData;
     document_page: DocumentPageEventData;
     document_zoom: DocumentZoomEventData;
@@ -74,6 +78,8 @@ interface CTEventDataMap {
     editor_cursor: EditorCursorEventData;
     tool_switch: ToolSwitchEventData;
     marker: MarkerEventData;
+    webcam_state: WebcamStateEventData;
+    content_dimensions: ContentDimensionsEventData;
     tool: ToolEventData;
     whiteboard: WhiteboardEventData;
     whiteboard_point: WhiteboardPointEventData;
@@ -221,6 +227,10 @@ interface InitEventData {
         x: number;
         y: number;
     };
+    contentDimensions?: {
+        width: number;
+        height: number;
+    };
 }
 /**
  * Code content change
@@ -380,6 +390,15 @@ interface ExcalidrawSceneEventData {
  */
 interface ExcalidrawClearEventData {
 }
+/**
+ * Excalidraw pointer update (laser pointer, tool changes)
+ */
+interface ExcalidrawPointerEventData {
+    x: number;
+    y: number;
+    tool: 'pointer' | 'laser';
+    button: 'down' | 'up';
+}
 /**
  * Load document
  */
@@ -587,7 +606,22 @@ interface ToolSwitchEventData {
 interface MarkerEventData {
     id: string;
     label: string;
-    type: 'chapter' | 'highlight' | 'quiz' | 'note';
+    type: 'chapter' | 'bookmark' | 'quiz' | 'note';
+}
+/**
+ * Webcam state event for maximize/minimize during recording
+ */
+interface WebcamStateEventData {
+    /** Whether the webcam is maximized (full overlay) */
+    maximized: boolean;
+}
+/**
+ * Content dimensions event — captures the recording container size
+ * for accurate cursor alignment during playback
+ */
+interface ContentDimensionsEventData {
+    width: number;
+    height: number;
 }
 /**
  * Legacy tool event (same as tool_switch)
@@ -683,6 +717,32 @@ interface PlaybackState$1 {
     textSelection: TextSelectionState | null;
     /** Editor typing cursor (caret) position */
     editorCursor: EditorCursorState | null;
+    /** Whether webcam is in maximized (full overlay) mode */
+    webcamMaximized: boolean;
+    /** Content area dimensions from the recording session.
+     *  Used to correctly position the cursor overlay during playback when
+     *  the player container is a different size than the recording container.
+     *  Without this, the cursor diverges from Excalidraw's absolute coordinates. */
+    contentDimensions: {
+        width: number;
+        height: number;
+    } | null;
+    /** Excalidraw pointer state (for laser pointer playback) */
+    excalidrawPointer: {
+        x: number;
+        y: number;
+        tool: 'pointer' | 'laser';
+        button: 'down' | 'up';
+    } | null;
+    /** Drawing overlay scene (floating overlay on non-whiteboard panels) */
+    overlayScene: ExcalidrawScene | null;
+    /** Drawing overlay pointer state (laser pointer on overlay) */
+    overlayPointer: {
+        x: number;
+        y: number;
+        tool: 'pointer' | 'laser';
+        button: 'down' | 'up';
+    } | null;
 }
 /**
  * State for file/folder creation UI display during playback
@@ -1071,7 +1131,7 @@ interface CTManifest {
     media: CTMediaInfo;
     /** Events reference (chunked in v1.1.0+, single file in v1.0.0) */
     events: CTEventsInfo;
-    /** Chapter/highlight markers */
+    /** Chapter/bookmark markers */
     markers: CTMarker[];
     /** Optional embedded assets */
     assets?: CTAssets;
@@ -1144,7 +1204,7 @@ interface CTWaveformInfo {
     samplesPerSecond: number;
 }
 /**
- * Chapter/highlight marker
+ * Chapter/bookmark marker
  */
 interface CTMarker {
     /** Unique identifier */
@@ -1155,13 +1215,16 @@ interface CTMarker {
     label: string;
     /** Marker type */
     type: CTMarkerType;
-    /** Type-specific additional data */
+    /**
+     * Type-specific additional data.
+     * When `type === 'quiz'`, this should conform to {@link MCQMarkerData}.
+     */
     data?: Record<string, unknown>;
 }
 /**
  * Marker types
  */
-type CTMarkerType = 'chapter' | 'highlight' | 'quiz' | 'note';
+type CTMarkerType = 'chapter' | 'bookmark' | 'quiz' | 'note';
 /**
  * Embedded assets manifest
  */
@@ -1551,6 +1614,21 @@ interface IDEPanelProps extends BasePanelProps {
         line: number;
         column: number;
     }) => void;
+    /**
+     * Called when user interacts with the IDE (clicks explorer, terminal, etc).
+     * Use this to pause playback when user starts interacting.
+     */
+    onInteractionStart?: () => void;
+    /** Whether to show AI inline suggestions (recording mode only). Default: false */
+    aiSuggestionsEnabled?: boolean;
+    /** API endpoint URL for AI completions. Default: '/api/ai/complete' */
+    aiSuggestionsEndpoint?: string;
+    /** Debounce delay in ms before requesting a completion. Default: 300 */
+    aiSuggestionsDebounceMs?: number;
+    /** Whether the AI debug feature is available. Default: false */
+    aiDebugEnabled?: boolean;
+    /** API endpoint for AI debug analysis. Default: '/api/ai/debug' */
+    aiDebugEndpoint?: string;
 }
 /**
  * Excalidraw scene structure (simplified)
@@ -1570,6 +1648,22 @@ interface WhiteboardPanelProps extends BasePanelProps {
     onSceneChange?: (scene: WhiteboardScene) => void;
     /** Called when scene is cleared */
     onSceneClear?: () => void;
+    /** Called when pointer updates (laser pointer, drawing pointer) */
+    onPointerUpdate?: (payload: {
+        pointer: {
+            x: number;
+            y: number;
+            tool: 'pointer' | 'laser';
+        };
+        button: 'down' | 'up';
+    }) => void;
+    /** Excalidraw pointer state for playback (laser trail rendering) */
+    pointerState?: {
+        x: number;
+        y: number;
+        tool: 'pointer' | 'laser';
+        button: 'down' | 'up';
+    } | null;
     /** Show Excalidraw toolbar */
     showToolbar?: boolean;
     /** Background color */
@@ -1647,6 +1741,8 @@ interface DocumentPanelProps extends BasePanelProps {
     allowMultiple?: boolean;
     /** Background color */
     backgroundColor?: string;
+    /** Base URL for asset upload endpoint (e.g. '/api/assets'). PPTX files are uploaded here to get a public URL for iframe embedding. */
+    assetUploadUrl?: string;
 }
 /**
  * Terminal component props
@@ -1763,13 +1859,15 @@ interface ToolSidebarProps {
     tools?: ToolType[];
     /** Additional CSS classes */
     className?: string;
+    /** Inline styles (e.g. background override) */
+    style?: React.CSSProperties;
 }
 
-declare function ToolSidebar({ activeTool, onToolChange, tools, className, }: ToolSidebarProps): react_jsx_runtime.JSX.Element;
+declare function ToolSidebar({ activeTool, onToolChange, tools, className, style, }: ToolSidebarProps): react_jsx_runtime.JSX.Element;
 
-declare function WhiteboardPanel({ scene, onSceneChange, onSceneClear, mode, isPlaying, onInteract, showToolbar, backgroundColor, className, }: WhiteboardPanelProps): react_jsx_runtime.JSX.Element;
+declare function WhiteboardPanel({ scene, onSceneChange, onSceneClear, onPointerUpdate, pointerState, mode, isPlaying, onInteract, showToolbar, backgroundColor, className, }: WhiteboardPanelProps): react_jsx_runtime.JSX.Element;
 
-declare function DocumentPanel({ documentData, documents: externalDocuments, activeDocumentId: externalActiveId, currentPage, zoom, scrollPosition, onDocumentLoad, onDocumentSelect, onDocumentRemove, onPageChange, onZoomChange, onScrollChange, onDocumentClear, mode, isPlaying, onInteract, showTabBar, showToolbar, showPageIndicator, allowUpload, allowMultiple, backgroundColor, className, }: DocumentPanelProps): react_jsx_runtime.JSX.Element;
+declare function DocumentPanel({ documentData, documents: externalDocuments, activeDocumentId: externalActiveId, currentPage, zoom, scrollPosition, onDocumentLoad, onDocumentSelect, onDocumentRemove, onPageChange, onZoomChange, onScrollChange, onDocumentClear, mode, isPlaying, onInteract, showTabBar, showToolbar, showPageIndicator, allowUpload, allowMultiple, backgroundColor, assetUploadUrl, className, }: DocumentPanelProps): react_jsx_runtime.JSX.Element;
 
 interface VirtualFileSystem {
     getFileTree: () => FileSystemEntry;
@@ -1784,103 +1882,62 @@ interface VirtualFileSystem {
     notifyChanged?: () => void;
     mkdir?: (path: string) => void;
 }
-declare function IDEPanel({ fileSystem, tree: externalTree, files: externalFiles, code: externalCode, language: externalLanguage, currentFile: externalCurrentFile, onCodeChange, onFileChange, onFileCreate, onFileDelete, onFileRename, onFileSelect, onFolderCreate, onFolderDelete, onTerminalCommand, onTerminalClear, onTerminalAddLines, fileCreationState, onFileCreationStart, onFileCreationInput, onFileCreationCancel, fileRenamingState, onFileRenameStart, onFileRenameInput, onFileRenameCancel, expandedFoldersState, onFolderToggle, terminalLines: externalTerminalLines, terminalInput: externalTerminalInput, onTerminalInputChange, onExecute, onTerminalExecute, mode, isPlaying, defaultShowExplorer, defaultShowTerminal, showRunButton, interactiveLabel, initialFiles, initialActiveFile, hoveredFile, onFileHover, textSelection, onTextSelect, editorCursor, onEditorCursorChange }: IDEPanelProps & {
+declare function IDEPanel({ fileSystem, tree: externalTree, files: externalFiles, code: externalCode, language: externalLanguage, currentFile: externalCurrentFile, onCodeChange, onFileChange, onFileCreate, onFileDelete, onFileRename, onFileSelect, onFolderCreate, onFolderDelete, onTerminalCommand, onTerminalClear, onTerminalAddLines, fileCreationState, onFileCreationStart, onFileCreationInput, onFileCreationCancel, fileRenamingState, onFileRenameStart, onFileRenameInput, onFileRenameCancel, expandedFoldersState, onFolderToggle, terminalLines: externalTerminalLines, terminalInput: externalTerminalInput, onTerminalInputChange, onExecute, onTerminalExecute, mode, isPlaying, defaultShowExplorer, defaultShowTerminal, showRunButton, interactiveLabel, initialFiles, initialActiveFile, hoveredFile, onFileHover, textSelection, onTextSelect, editorCursor, onEditorCursorChange, onInteractionStart, aiSuggestionsEnabled, aiSuggestionsEndpoint, aiSuggestionsDebounceMs, aiDebugEnabled, aiDebugEndpoint, }: IDEPanelProps & {
     fileSystem?: VirtualFileSystem;
 }): react_jsx_runtime.JSX.Element;
 
 declare function FileExplorer({ tree, selectedFile, expandedFolders, fileCreation, fileRenaming, mode, isPlaying, hoveredFile, onFileHover, onFileSelect, onFileCreate, onFolderCreate, onFileDelete, onFileRename, onFolderToggle, onFileCreationStart, onFileCreationInput, onFileCreationCancel, onFileRenameStart, onFileRenameInput, onFileRenameCancel, className, }: FileExplorerProps): react_jsx_runtime.JSX.Element;
 
-declare const Terminal: react.ForwardRefExoticComponent<TerminalProps & react.RefAttributes<TerminalRef>>;
+declare const Terminal: React__default.ForwardRefExoticComponent<TerminalProps & React__default.RefAttributes<TerminalRef>>;
 
 /**
- * Active tool type - matches ToolType from @ct-courses/ui
+ * Learner Branch Types
+ *
+ * A branch is a saved snapshot of the learner's code edits at a specific
+ * moment in the instructor's timeline. Branches are learner-side only —
+ * they never modify the .ct file, events, or manifest.
+ *
+ * @packageDocumentation
  */
-type ActiveTool$1 = ToolType;
 /**
- * Props for the CoursePlayer component
+ * A point-in-time capture of the IDE state.
+ * Used for both the instructor's original state and the learner's edited state.
  */
-interface CoursePlayerProps {
-    /** Pre-loaded recording data */
-    recording?: CTRecording;
-    /** URL to a .ct file */
-    recordingUrl?: string;
-    /** Recording ID to fetch from API */
-    recordingId?: string;
-    /** Base API URL for fetching recordings */
-    apiUrl?: string;
-    /** Authentication token */
-    authToken?: string;
-    /** Go-Judge server URL */
-    goJudgeUrl?: string;
-    /** Go-Judge API key */
-    goJudgeApiKey?: string;
-    /** Theme setting */
-    theme?: 'light' | 'dark' | 'system';
-    /** Aspect ratio of the player */
-    aspectRatio?: '16:9' | '4:3' | 'auto';
-    /** Show playback controls toolbar */
-    showToolbar?: boolean;
-    /** Show timeline below player */
-    showTimeline?: boolean;
-    /** Show chapter markers */
-    showChapters?: boolean;
-    /** Show tool sidebar */
-    showToolSidebar?: boolean;
-    /** Auto-play when loaded */
-    autoPlay?: boolean;
-    /** Default playback speed */
-    defaultSpeed?: number;
-    /** Allow fullscreen mode */
-    allowFullscreen?: boolean;
-    /** Default active tool */
-    defaultTool?: ActiveTool$1;
-    /** Called when player is ready */
-    onReady?: () => void;
-    /** Called when playback starts */
-    onPlay?: () => void;
-    /** Called when playback pauses */
-    onPause?: () => void;
-    /** Called on progress update */
-    onProgress?: (time: number, duration: number) => void;
-    /** Called when playback completes */
-    onComplete?: () => void;
-    /** Called on error */
-    onError?: (error: Error) => void;
-    /** Called when entering interactive mode */
-    onInteractionStart?: () => void;
-    /** Called when exiting interactive mode */
-    onInteractionEnd?: (code: string) => void;
-    /** Called when tool changes */
-    onToolChange?: (tool: string) => void;
+interface BranchSnapshot {
+    /** Active file's code content */
+    code: string;
+    /** Programming language at snapshot time */
+    language: string;
+    /** Which file tab was active (null if single-file mode) */
+    currentFile: string | null;
+    /** Full file system snapshot — path → content */
+    fileSystem: Record<string, string>;
+    /** Terminal output lines if any existed */
+    terminalOutput?: string[];
+    /** Which tool panel was open (code / terminal / whiteboard / document) */
+    activeTool: string;
+    /** Folder paths created by the learner during interactive mode */
+    folders?: string[];
 }
 /**
- * Imperative handle for CoursePlayer
+ * A learner branch — a saved code snapshot at a point in the timeline.
  */
-interface CoursePlayerRef {
-    play(): void;
-    pause(): void;
-    seek(timeMs: number): void;
-    setSpeed(speed: number): void;
-    getCurrentTime(): number;
-    getDuration(): number;
-    getState(): PlaybackState$1;
-    enterInteractiveMode(): void;
-    exitInteractiveMode(): void;
-    setActiveTool(tool: ActiveTool$1): void;
+interface LearnerBranch {
+    /** Unique branch ID (crypto.randomUUID) */
+    id: string;
+    /** Lesson/recording this branch belongs to */
+    lessonId: string;
+    /** Playback time in milliseconds where the learner paused */
+    timeMs: number;
+    /** Instructor's state at that moment (for comparison / restoring) */
+    originalState: BranchSnapshot;
+    /** Learner's edited state */
+    learnerState: BranchSnapshot;
+    /** ISO timestamp of when the branch was created */
+    createdAt: string;
+    /** User-provided label, defaults to "Branch at MM:SS" */
+    label?: string;
 }
-/**
- * CoursePlayer component
- */
-declare const CoursePlayer: react.ForwardRefExoticComponent<CoursePlayerProps & react.RefAttributes<CoursePlayerRef>>;
-
-/**
- * CT-Courses Player - Remote Streaming Types
- *
- * Types for streaming playback from a remote CDN/R2 storage.
- * These types match the streaming service manifest structure.
- *
- * @packageDocumentation
- */
 
 /**
  * Audio quality level information
@@ -1908,6 +1965,40 @@ interface StreamingRecordingInfo {
     /** Creation timestamp (ISO 8601) */
     createdAt: string;
 }
+/**
+ * Video quality level information
+ */
+interface VideoQuality {
+    /** Quality name (low, medium, high) */
+    name: string;
+    /** Bitrate in bits per second */
+    bitrate: number;
+    /** Video width in pixels */
+    width: number;
+    /** Video height in pixels */
+    height: number;
+    /** URL to the quality-specific playlist */
+    playlistUrl?: string;
+}
+/**
+ * Video streaming configuration (webcam overlay)
+ */
+interface StreamingVideoConfig {
+    /** Video type (always 'hls' for adaptive streaming) */
+    type: 'hls';
+    /** URL to the HLS master playlist */
+    masterPlaylistUrl: string;
+    /** Available quality levels */
+    qualities: VideoQuality[];
+    /** Video duration in seconds */
+    duration: number;
+    /** Video width in pixels */
+    width: number;
+    /** Video height in pixels */
+    height: number;
+    /** Video codec */
+    codec: string;
+}
 /**
  * Audio streaming configuration
  */
@@ -1947,6 +2038,32 @@ interface StreamingConfig {
     /** Maximum buffer to maintain (ms) */
     maxBufferMs: number;
 }
+/**
+ * An interaction point from the streaming manifest (CDN-safe).
+ * Options intentionally omit `isCorrect` — answers validated server-side only.
+ */
+interface InteractionPointManifest {
+    /** Marker ID from the .ct manifest */
+    id: string;
+    /** Interaction type (only 'mcq' for now) */
+    type: 'mcq';
+    /** Time position in milliseconds */
+    timeMs: number;
+    /** Whether to pause playback when this point is reached */
+    pausePlayback: boolean;
+    /** MCQ question data (without isCorrect on options) */
+    mcq: {
+        question: string;
+        options: {
+            id: string;
+            text: string;
+        }[];
+        explanation?: string;
+        allowRetry: boolean;
+        shuffleOptions: boolean;
+        timeoutSeconds: number | null;
+    };
+}
 /**
  * Complete streaming manifest structure
  * This is the main entry point returned by the streaming service.
@@ -1960,10 +2077,18 @@ interface StreamingManifest {
     recording: StreamingRecordingInfo;
     /** Audio streaming configuration */
     audio: StreamingAudioConfig;
+    /** Video streaming configuration (present when webcam was recorded) */
+    video?: StreamingVideoConfig;
     /** Events streaming configuration */
     events: StreamingEventsConfig;
     /** Streaming playback hints */
     streaming: StreamingConfig;
+    /**
+     * Interaction points extracted from .ct manifest quiz markers.
+     * Options omit `isCorrect` — answers are validated server-side only.
+     * Absent or empty when the recording has no quiz markers.
+     */
+    interactionPoints?: InteractionPointManifest[];
 }
 /**
  * Options for useRemoteStreamingPlayback hook
@@ -2038,8 +2163,10 @@ interface RemoteStreamingPlaybackState {
     isPlaying: boolean;
     /** Current playback speed */
     speed: number;
-    /** Whether the player is ready */
+    /** Whether the player is ready (UI can render — audio+events loaded) */
     isReady: boolean;
+    /** Whether ALL sources are loaded and synced (audio+video+events) */
+    allSourcesReady: boolean;
     /** Whether currently buffering */
     isBuffering: boolean;
     /** Buffer health information */
@@ -2065,6 +2192,16 @@ interface RemoteStreamingPlaybackControls {
     setSpeed(speed: number): void;
     /** Get the audio element for custom controls */
     getAudioElement(): HTMLAudioElement | null;
+    /** Get the video element for webcam overlay (null if no video) */
+    getVideoElement(): HTMLVideoElement | null;
+    /** Attach HLS video player to a video element (from WebcamOverlay onVideoRef) */
+    initVideoHls(videoElement: HTMLVideoElement | null): void;
+    /** Get available webcam video quality levels */
+    getVideoQualityLevels(): HLSQualityLevel[];
+    /** Set webcam video quality level (-1 for auto) */
+    setVideoQualityLevel(index: number): void;
+    /** Get current webcam video quality level (-1 = auto) */
+    getVideoQualityLevel(): number;
 }
 /**
  * HLS player configuration
@@ -2089,81 +2226,12 @@ interface HLSQualityLevel {
     bitrate: number;
     /** Codec string */
     codecs: string;
+    /** Video width (0 if audio-only) */
+    width?: number;
+    /** Video height (0 if audio-only) */
+    height?: number;
 }
 
-type ActiveTool = ToolType;
-/**
- * Props for StreamingCoursePlayer
- */
-interface StreamingCoursePlayerProps {
-    /** URL to the streaming manifest.json */
-    manifestUrl: string;
-    /** Theme setting */
-    theme?: 'light' | 'dark' | 'system';
-    /** Aspect ratio of the player */
-    aspectRatio?: '16:9' | '4:3' | 'auto';
-    /** Show playback controls toolbar */
-    showToolbar?: boolean;
-    /** Show tool sidebar */
-    showToolSidebar?: boolean;
-    /** Auto-play when loaded */
-    autoPlay?: boolean;
-    /** Default playback speed */
-    defaultSpeed?: number;
-    /** Allow fullscreen mode */
-    allowFullscreen?: boolean;
-    /** Default active tool */
-    defaultTool?: ActiveTool;
-    /** Maximum chunks to cache */
-    maxCacheSize?: number;
-    /** Additional CSS class */
-    className?: string;
-    /** Called when player is ready */
-    onReady?: () => void;
-    /** Called when playback starts */
-    onPlay?: () => void;
-    /** Called when playback pauses */
-    onPause?: () => void;
-    /** Called on progress update */
-    onProgress?: (time: number, duration: number) => void;
-    /** Called when playback completes */
-    onComplete?: () => void;
-    /** Called on error */
-    onError?: (error: Error) => void;
-    /** Called when buffering state changes */
-    onBuffering?: (isBuffering: boolean) => void;
-    /** Called when tool changes */
-    onToolChange?: (tool: string) => void;
-    /** Go-Judge server URL */
-    goJudgeUrl?: string;
-    /** Go-Judge API key */
-    goJudgeApiKey?: string;
-    /** Show chapter markers */
-    showChapters?: boolean;
-    /** Called when entering interactive mode */
-    onInteractionStart?: () => void;
-    /** Called when exiting interactive mode */
-    onInteractionEnd?: (code: string) => void;
-}
-/**
- * Imperative handle for StreamingCoursePlayer
- */
-interface StreamingCoursePlayerRef {
-    play(): void;
-    pause(): void;
-    seek(timeMs: number): Promise<void>;
-    setSpeed(speed: number): void;
-    getCurrentTime(): number;
-    getDuration(): number;
-    getState(): PlaybackState$1;
-    enterInteractiveMode(): void;
-    exitInteractiveMode(): void;
-    setActiveTool(tool: ActiveTool): void;
-    getManifest(): StreamingManifest | null;
-    getBufferHealth(): RemoteBufferHealth;
-}
-declare const StreamingCoursePlayer: react.ForwardRefExoticComponent<StreamingCoursePlayerProps & react.RefAttributes<StreamingCoursePlayerRef>>;
-
 /**
  * @ct-courses/player - Type Definitions
  */
@@ -2406,33 +2474,275 @@ interface VolumeControlProps {
     onMuteToggle: () => void;
     className?: string;
 }
-
 /**
- * usePlayback Hook
- *
- * Core playback engine hook using @ct-courses/core StateEngine.
- * Supports audio synchronization as master clock (no video/webcam).
- *
- * CRITICAL SYNC ARCHITECTURE:
- * - AUDIO is the MASTER CLOCK when media exists
- * - Events are applied based on audio.currentTime
- * - Without media, use requestAnimationFrame timing
+ * Client-side interaction point (no isCorrect — answers validated server-side).
+ * Mirrors InteractionPointManifest from streaming.ts but usable without a manifest.
+ */
+interface InteractionPoint {
+    /** Unique identifier */
+    id: string;
+    /** Interaction type */
+    type: 'mcq';
+    /** Time position in milliseconds */
+    timeMs: number;
+    /** Whether to pause playback when this point is reached */
+    pausePlayback: boolean;
+    /** MCQ question data */
+    mcq: {
+        question: string;
+        options: {
+            id: string;
+            text: string;
+        }[];
+        explanation?: string;
+        allowRetry: boolean;
+        shuffleOptions: boolean;
+        timeoutSeconds: number | null;
+    };
+}
+/**
+ * MCQ answer submission from the player
+ */
+interface MCQSubmission {
+    /** The interaction point ID */
+    pointId: string;
+    /** Selected option IDs */
+    selectedOptionIds: string[];
+}
+/**
+ * MCQ answer result returned from the host app's callback
  */
+interface MCQResult {
+    /** Whether the answer was correct */
+    correct: boolean;
+    /** Optional explanation text */
+    explanation?: string;
+    /** Correct option IDs (revealed after answering) */
+    correctOptionIds?: string[];
+}
 
 /**
- * Playback state returned by the hook
+ * Active tool type - matches ToolType from @ct-courses/ui
  */
-interface PlaybackHookState {
-    /** Current playback state */
-    state: PlaybackState$1;
-    /** Current time in milliseconds */
-    currentTime: number;
-    /** Total duration in milliseconds */
-    duration: number;
-    /** Whether currently playing */
-    isPlaying: boolean;
-    /** Current playback speed */
-    speed: number;
+type ActiveTool$1 = ToolType;
+/**
+ * Props for the CoursePlayer component
+ */
+interface CoursePlayerProps {
+    /** Pre-loaded recording data */
+    recording?: CTRecording;
+    /** URL to a .ct file */
+    recordingUrl?: string;
+    /** Recording ID to fetch from API */
+    recordingId?: string;
+    /** Base API URL for fetching recordings */
+    apiUrl?: string;
+    /** Authentication token */
+    authToken?: string;
+    /** Go-Judge server URL */
+    goJudgeUrl?: string;
+    /** Go-Judge API key */
+    goJudgeApiKey?: string;
+    /** Theme setting */
+    theme?: "light" | "dark" | "system";
+    /** Aspect ratio of the player */
+    aspectRatio?: "16:9" | "4:3" | "auto";
+    /** Show playback controls toolbar */
+    showToolbar?: boolean;
+    /** Show timeline below player */
+    showTimeline?: boolean;
+    /** Show chapter markers */
+    showChapters?: boolean;
+    /** Show tool sidebar */
+    showToolSidebar?: boolean;
+    /** Auto-play when loaded */
+    autoPlay?: boolean;
+    /** Default playback speed */
+    defaultSpeed?: number;
+    /** Allow fullscreen mode */
+    allowFullscreen?: boolean;
+    /** Default active tool */
+    defaultTool?: ActiveTool$1;
+    /** Called when player is ready */
+    onReady?: () => void;
+    /** Called when playback starts */
+    onPlay?: () => void;
+    /** Called when playback pauses */
+    onPause?: () => void;
+    /** Called on progress update */
+    onProgress?: (time: number, duration: number) => void;
+    /** Called when playback completes */
+    onComplete?: () => void;
+    /** Called on error */
+    onError?: (error: Error) => void;
+    /** Called when entering interactive mode */
+    onInteractionStart?: () => void;
+    /** Called when exiting interactive mode */
+    onInteractionEnd?: (code: string) => void;
+    /** Called when tool changes */
+    onToolChange?: (tool: string) => void;
+    /** Interaction points (MCQs) to display during playback */
+    interactionPoints?: InteractionPoint[];
+    /** Pre-answered point IDs (skip these MCQs) */
+    answeredPointIds?: Set<string>;
+    /** Called when a learner submits an MCQ answer. Host app validates server-side. */
+    onSubmitAnswer?: (pointId: string, selectedOptionIds: string[]) => Promise<MCQResult>;
+    /** Info about the next lesson for auto-advance overlay */
+    nextLesson?: {
+        id: string;
+        title: string;
+    } | null;
+    /** Called when the player wants to navigate to the next lesson */
+    onNavigateToLesson?: (lessonId: string) => void;
+    /** Called when the current lesson completes (before transition) */
+    onLessonComplete?: () => void;
+    /** Lesson ID used to scope saved branches in localStorage */
+    lessonId?: string;
+    /** Enable the branch save feature (default: true) */
+    enableBranches?: boolean;
+    /** Called after a branch is saved */
+    onBranchSave?: (branch: LearnerBranch) => void;
+    /** Called when a learner restores a saved branch */
+    onBranchRestore?: (branch: LearnerBranch) => void;
+    /** Called after a branch is deleted */
+    onBranchDelete?: (branchId: string) => void;
+    /** Maximum branches per lesson (default: 50) */
+    maxBranches?: number;
+}
+/**
+ * Imperative handle for CoursePlayer
+ */
+interface CoursePlayerRef {
+    play(): void;
+    pause(): void;
+    seek(timeMs: number): void;
+    setSpeed(speed: number): void;
+    getCurrentTime(): number;
+    getDuration(): number;
+    getState(): PlaybackState$1;
+    enterInteractiveMode(): void;
+    exitInteractiveMode(): void;
+    setActiveTool(tool: ActiveTool$1): void;
+}
+/**
+ * CoursePlayer component
+ */
+declare const CoursePlayer: React__default.ForwardRefExoticComponent<CoursePlayerProps & React__default.RefAttributes<CoursePlayerRef>>;
+
+type ActiveTool = ToolType;
+/**
+ * Props for StreamingCoursePlayer
+ */
+interface StreamingCoursePlayerProps {
+    /** URL to the streaming manifest.json */
+    manifestUrl: string;
+    /** Theme setting */
+    theme?: "light" | "dark" | "system";
+    /** Aspect ratio of the player */
+    aspectRatio?: "16:9" | "4:3" | "auto";
+    /** Show playback controls toolbar */
+    showToolbar?: boolean;
+    /** Show tool sidebar */
+    showToolSidebar?: boolean;
+    /** Auto-play when loaded */
+    autoPlay?: boolean;
+    /** Default playback speed */
+    defaultSpeed?: number;
+    /** Allow fullscreen mode */
+    allowFullscreen?: boolean;
+    /** Default active tool */
+    defaultTool?: ActiveTool;
+    /** Maximum chunks to cache */
+    maxCacheSize?: number;
+    /** Additional CSS class */
+    className?: string;
+    /** Called when player is ready */
+    onReady?: () => void;
+    /** Called when playback starts */
+    onPlay?: () => void;
+    /** Called when playback pauses */
+    onPause?: () => void;
+    /** Called on progress update */
+    onProgress?: (time: number, duration: number) => void;
+    /** Called when playback completes */
+    onComplete?: () => void;
+    /** Called on error */
+    onError?: (error: Error) => void;
+    /** Called when buffering state changes */
+    onBuffering?: (isBuffering: boolean) => void;
+    /** Called when tool changes */
+    onToolChange?: (tool: string) => void;
+    /** Go-Judge server URL */
+    goJudgeUrl?: string;
+    /** Go-Judge API key */
+    goJudgeApiKey?: string;
+    /** Show chapter markers */
+    showChapters?: boolean;
+    /** Called when entering interactive mode */
+    onInteractionStart?: () => void;
+    /** Called when exiting interactive mode */
+    onInteractionEnd?: (code: string) => void;
+    /** Interaction points (MCQs) to display during playback */
+    interactionPoints?: InteractionPoint[];
+    /** Pre-answered point IDs (skip these MCQs) */
+    answeredPointIds?: Set<string>;
+    /** Called when a learner submits an MCQ answer. Host app validates server-side. */
+    onSubmitAnswer?: (pointId: string, selectedOptionIds: string[]) => Promise<MCQResult>;
+    /** Info about the next lesson for auto-advance overlay */
+    nextLesson?: {
+        id: string;
+        title: string;
+    } | null;
+    /** Called when the player wants to navigate to the next lesson */
+    onNavigateToLesson?: (lessonId: string) => void;
+    /** Called when the current lesson completes (before transition) */
+    onLessonComplete?: () => void;
+}
+/**
+ * Imperative handle for StreamingCoursePlayer
+ */
+interface StreamingCoursePlayerRef {
+    play(): void;
+    pause(): void;
+    seek(timeMs: number): Promise<void>;
+    setSpeed(speed: number): void;
+    getCurrentTime(): number;
+    getDuration(): number;
+    getState(): PlaybackState$1;
+    enterInteractiveMode(): void;
+    exitInteractiveMode(): void;
+    setActiveTool(tool: ActiveTool): void;
+    getManifest(): StreamingManifest | null;
+    getBufferHealth(): RemoteBufferHealth;
+}
+declare const StreamingCoursePlayer: React__default.ForwardRefExoticComponent<StreamingCoursePlayerProps & React__default.RefAttributes<StreamingCoursePlayerRef>>;
+
+/**
+ * usePlayback Hook
+ *
+ * Core playback engine hook using @ct-courses/core StateEngine.
+ * Supports audio synchronization as master clock (no video/webcam).
+ *
+ * CRITICAL SYNC ARCHITECTURE:
+ * - AUDIO is the MASTER CLOCK when media exists
+ * - Events are applied based on audio.currentTime
+ * - Without media, use requestAnimationFrame timing
+ */
+
+/**
+ * Playback state returned by the hook
+ */
+interface PlaybackHookState {
+    /** Current playback state */
+    state: PlaybackState$1;
+    /** Current time in milliseconds */
+    currentTime: number;
+    /** Total duration in milliseconds */
+    duration: number;
+    /** Whether currently playing */
+    isPlaying: boolean;
+    /** Current playback speed */
+    speed: number;
     /** Whether recording is loaded */
     isLoaded: boolean;
     /** Volume level (0-1) */
@@ -2453,6 +2763,7 @@ interface PlaybackControls {
     setVolume(volume: number): void;
     setMuted(muted: boolean): void;
     setAudioElement(audio: HTMLAudioElement | null): void;
+    setVideoElement(video: HTMLVideoElement | null): void;
     enterInteractiveMode(): void;
     exitInteractiveMode(): void;
     setInteractiveCode(code: string): void;
@@ -2466,6 +2777,10 @@ interface PlaybackControls {
         x: number;
         y: number;
     }): void;
+    /** Inject a full branch snapshot into the interactive state. Only works when isInteracting is true. */
+    injectInteractiveState(snapshot: BranchSnapshot): void;
+    /** Get the engine's (instructor's) state at a given time, without affecting playback position. */
+    getEngineStateAtTime(timeMs: number): PlaybackState$1 | null;
 }
 /**
  * Options for usePlayback hook
@@ -2712,21 +3027,233 @@ declare function useAudioSync(options: UseAudioSyncOptions): AudioSyncState & {
  * Hook for managing audio element lifecycle
  */
 declare function useAudioElement(src: string | null): {
-    audioRef: react.MutableRefObject<HTMLAudioElement | null>;
+    audioRef: React__default.MutableRefObject<HTMLAudioElement | null>;
+    isLoaded: boolean;
+    error: Error | null;
+    duration: number;
+};
+
+/**
+ * useVideoSync Hook
+ *
+ * Synchronizes video playback with event state.
+ * Handles video/event drift and maintains sync within tolerance.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Video sync state
+ */
+interface VideoSyncState {
+    /** Current video time in ms */
+    videoTime: number;
+    /** Current event time in ms */
+    eventTime: number;
+    /** Drift between video and events (ms) */
+    drift: number;
+    /** Is sync healthy (within tolerance) */
+    isSynced: boolean;
+    /** Is video loaded */
+    isVideoReady: boolean;
+}
+/**
+ * Video sync controls
+ */
+interface VideoSyncControls {
+    /** Sync events to video time */
+    syncToVideo(): void;
+    /** Sync video to event time */
+    syncVideoTo(timeMs: number): void;
+    /** Force resync */
+    forceResync(): void;
+}
+/**
+ * Options for useVideoSync hook
+ */
+interface UseVideoSyncOptions {
+    /** Reference to video element */
+    videoRef: React.RefObject<HTMLVideoElement>;
+    /** Current event time */
+    eventTime: number;
+    /** Is currently playing */
+    isPlaying: boolean;
+    /** Playback speed */
+    speed: number;
+    /** Maximum allowed drift in ms before resync (default: 500ms) */
+    driftTolerance?: number;
+    /** Callback when video time updates */
+    onVideoTimeUpdate?: (timeMs: number) => void;
+    /** Callback when sync is lost */
+    onSyncLost?: (drift: number) => void;
+    /** Callback when sync is restored */
+    onSyncRestored?: () => void;
+}
+/**
+ * Hook for synchronizing video playback with event state
+ */
+declare function useVideoSync(options: UseVideoSyncOptions): VideoSyncState & {
+    controls: VideoSyncControls;
+};
+/**
+ * Hook for managing video element lifecycle
+ */
+declare function useVideoElement(src: string | null): {
+    videoRef: React__default.MutableRefObject<HTMLVideoElement | null>;
     isLoaded: boolean;
     error: Error | null;
     duration: number;
 };
-/** @deprecated Use AudioSyncState instead */
-type VideoSyncState = AudioSyncState;
-/** @deprecated Use AudioSyncControls instead */
-type VideoSyncControls = AudioSyncControls;
-/** @deprecated Use UseAudioSyncOptions instead */
-type UseVideoSyncOptions = UseAudioSyncOptions;
-/** @deprecated Use useAudioSync instead */
-declare const useVideoSync: typeof useAudioSync;
-/** @deprecated Use useAudioElement instead */
-declare const useVideoElement: typeof useAudioElement;
+
+/**
+ * useInteractionPoints — monitors playback time and triggers MCQ pauses.
+ *
+ * The hook is player-mode agnostic: it only needs the current time (ms),
+ * a pause callback, and a play callback.  Both CoursePlayer and
+ * StreamingCoursePlayer can use it.
+ *
+ * Edge cases handled:
+ * - Seek past unanswered MCQ → still triggers (first unanswered point ≤ currentTime)
+ * - Seek backwards past a triggered-but-unanswered point → re-evaluates
+ * - Multiple MCQs at exact same time → triggers in array order
+ * - Race: activePoint takes priority — no duplicate triggers while overlay is open
+ *
+ * @packageDocumentation
+ */
+
+interface UseInteractionPointsOptions {
+    /** Sorted interaction points (ascending by timeMs) */
+    interactionPoints: InteractionPoint[];
+    /** Current playback time in milliseconds */
+    currentTimeMs: number;
+    /** Callback to pause playback */
+    pause: () => void;
+    /** Callback to resume playback */
+    play: () => void;
+    /** Pre-loaded set of already-answered point IDs */
+    initialAnsweredPointIds?: Set<string>;
+}
+interface UseInteractionPointsResult {
+    /** The interaction point currently requiring attention, or null */
+    activePoint: InteractionPoint | null;
+    /** Dismiss the active point (adds to answered, resumes playback) */
+    dismissPoint: () => void;
+    /** Mark a point as answered without dismissing (for pre-loading state) */
+    markAnswered: (pointId: string) => void;
+    /** Set of all answered point IDs */
+    answeredPointIds: Set<string>;
+}
+declare function useInteractionPoints({ interactionPoints, currentTimeMs, pause, play, initialAnsweredPointIds, }: UseInteractionPointsOptions): UseInteractionPointsResult;
+
+/**
+ * useBranching — manages lesson-to-lesson transition with auto-advance countdown.
+ *
+ * @packageDocumentation
+ */
+interface UseBranchingOptions {
+    /** Next lesson info (null = course complete) */
+    nextLesson: {
+        id: string;
+        title: string;
+    } | null;
+    /** Seconds before auto-navigating (default 5) */
+    autoAdvanceSeconds?: number;
+    /** Called when auto-advance or manual skip triggers navigation */
+    onNavigate: (lessonId: string) => void;
+}
+interface UseBranchingResult {
+    /** Whether the transition overlay is active */
+    isTransitioning: boolean;
+    /** Current countdown value (seconds remaining, 0 = done) */
+    countdown: number;
+    /** Start the transition overlay + countdown */
+    startTransition: () => void;
+    /** Skip the countdown and navigate immediately */
+    skipToNext: () => void;
+    /** Pause the auto-advance but keep the overlay visible */
+    cancelAutoAdvance: () => void;
+}
+declare function useBranching({ nextLesson, autoAdvanceSeconds, onNavigate, }: UseBranchingOptions): UseBranchingResult;
+
+/**
+ * useBranches — manages learner branch state for a single lesson.
+ *
+ * Handles save / delete / rename / restore of learner code snapshots,
+ * persisted to localStorage via branchStorage utilities.
+ *
+ * @packageDocumentation
+ */
+
+interface UseBranchesOptions {
+    /** Lesson/recording ID — branches are scoped to this. Undefined = feature disabled. */
+    lessonId: string | undefined;
+    /** Returns current playback time in milliseconds */
+    getCurrentTimeMs: () => number;
+    /** Captures the learner's current IDE state (interactive mode state) */
+    getCurrentState: () => BranchSnapshot;
+    /** Captures the instructor's state at the current time from the engine */
+    getOriginalState: () => BranchSnapshot;
+    /** Called when the learner wants to restore a branch (parent orchestrates seek + inject) */
+    onRestoreBranch?: (branch: LearnerBranch) => void;
+    /** Called after a branch is successfully saved (for analytics / callbacks) */
+    onBranchSaved?: (branch: LearnerBranch) => void;
+    /** Called after a branch is deleted */
+    onBranchDeleted?: (branchId: string) => void;
+    /** Maximum branches per lesson (default 50) */
+    maxBranches?: number;
+}
+interface UseBranchesResult {
+    /** All branches for the current lesson, sorted oldest-first */
+    branches: LearnerBranch[];
+    /** Number of saved branches */
+    branchCount: number;
+    /** Whether the feature is enabled (lessonId is defined) */
+    enabled: boolean;
+    /** Save a new branch from the current interactive state. Returns the created branch, or null if disabled / duplicate. */
+    saveBranch: (label?: string) => LearnerBranch | null;
+    /** Delete a branch by ID */
+    deleteBranch: (branchId: string) => void;
+    /** Rename a branch */
+    renameBranch: (branchId: string, label: string) => void;
+    /** Restore a branch — delegates to parent via onRestoreBranch callback */
+    restoreBranch: (branchId: string) => void;
+    /** Check if a branch at this timeMs with this code already exists (duplicate detection) */
+    isDuplicate: (timeMs: number, code: string) => boolean;
+}
+declare function useBranches(options: UseBranchesOptions): UseBranchesResult;
+
+/**
+ * Branch Storage — localStorage CRUD helpers
+ *
+ * Persists learner branches as JSON arrays keyed by lesson ID.
+ * Key format: `ct-branches:<lessonId>`
+ *
+ * Pure functions — no React, no hooks.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Load all branches for a lesson from localStorage.
+ * Returns empty array if nothing stored or on parse error.
+ * Sorted by `createdAt` ascending (oldest first).
+ */
+declare function loadBranches(lessonId: string): LearnerBranch[];
+/**
+ * Persist a new branch. Caps at `maxBranches` per lesson (drops oldest).
+ */
+declare function saveBranch(lessonId: string, branch: LearnerBranch, maxBranches?: number): void;
+/**
+ * Delete a single branch by ID.
+ */
+declare function deleteBranch(lessonId: string, branchId: string): void;
+/**
+ * Update the label of an existing branch.
+ */
+declare function updateBranchLabel(lessonId: string, branchId: string, label: string): void;
+/**
+ * Format milliseconds as "MM:SS" for default branch labels.
+ */
+declare function formatBranchTime(ms: number): string;
 
 /**
  * HLS Loader Utility
@@ -2757,6 +3284,29 @@ interface HLSPlayerInstance {
     /** Remove event listener */
     off: (event: string, callback: (...args: unknown[]) => void) => void;
 }
+/**
+ * HLS video player instance (mirrors HLSPlayerInstance but for video elements)
+ */
+interface HLSVideoPlayerInstance {
+    /** The HLS.js instance (null if using native HLS) */
+    hls: Hls | null;
+    /** The video element */
+    videoElement: HTMLVideoElement;
+    /** Whether this is using native HLS (Safari) */
+    isNative: boolean;
+    /** Destroy and cleanup */
+    destroy: () => void;
+    /** Get current quality levels */
+    getQualityLevels: () => HLSQualityLevel[];
+    /** Set quality level (-1 for auto) */
+    setQualityLevel: (index: number) => void;
+    /** Get current quality level */
+    getCurrentQualityLevel: () => number;
+    /** Add event listener for HLS events */
+    on: (event: string, callback: (...args: unknown[]) => void) => void;
+    /** Remove event listener */
+    off: (event: string, callback: (...args: unknown[]) => void) => void;
+}
 interface HLSEvents {
     /** Manifest has been parsed and is ready */
     MANIFEST_PARSED: 'hlsManifestParsed';
@@ -2795,12 +3345,19 @@ declare function createHlsPlayer(audioElement: HTMLAudioElement, masterPlaylistU
 /**
  * Destroy an HLS player instance safely
  */
-declare function destroyHlsPlayer(player: HLSPlayerInstance | null): void;
+declare function destroyHlsPlayer(player: HLSPlayerInstance | HLSVideoPlayerInstance | null): void;
 
 interface Marker$1 {
     time: number;
     label?: string;
-    type?: 'chapter' | 'highlight';
+    type?: "chapter" | "bookmark" | "quiz";
+}
+interface VideoQualityLevel {
+    index: number;
+    bitrate: number;
+    codecs: string;
+    width?: number;
+    height?: number;
 }
 interface PlayerControlsProps {
     isPlaying: boolean;
@@ -2811,6 +3368,9 @@ interface PlayerControlsProps {
     playbackSpeed: number;
     markers?: Marker$1[];
     isFullscreen?: boolean;
+    videoQualityLevels?: VideoQualityLevel[];
+    videoQualityLevel?: number;
+    onVideoQualityChange?: (index: number) => void;
     onPlayPause: () => void;
     onSeek: (timeMs: number) => void;
     onSeekStart?: () => void;
@@ -2821,11 +3381,28 @@ interface PlayerControlsProps {
     onMuteToggle: () => void;
     onSpeedChange: (speed: number) => void;
     onFullscreenToggle?: () => void;
+    /** Called when the user interacts with the code editor area while playing.
+     *  The parent should pause playback when this fires. */
+    onEditorInteraction?: () => void;
+    /** Interaction points — purple dots rendered on the seek bar */
+    interactionPoints?: InteractionPoint[];
+    /** Saved learner branches — green diamond markers on the progress bar */
+    branches?: LearnerBranch[];
+    /** Callback when a branch marker is clicked */
+    onBranchClick?: (branch: LearnerBranch) => void;
+    /** Number of saved branches (for badge) */
+    branchCount?: number;
+    /** Whether the branch panel is currently open */
+    isBranchPanelOpen?: boolean;
+    /** Toggle the branch panel */
+    onBranchPanelToggle?: () => void;
+    /** Whether the learner is in interactive/editing mode */
+    isInteractive?: boolean;
     showMarkers?: boolean;
     compact?: boolean;
-    containerRef?: react__default.RefObject<HTMLElement>;
+    containerRef?: React__default__default.RefObject<HTMLElement>;
 }
-declare function PlayerControls({ isPlaying, currentTime, duration, volume, muted, playbackSpeed, markers, isFullscreen, onPlayPause, onSeek, onSeekStart, onSeekEnd, onSkip, onRestart, onVolumeChange, onMuteToggle, onSpeedChange, onFullscreenToggle, showMarkers, compact, }: PlayerControlsProps): react_jsx_runtime.JSX.Element;
+declare function PlayerControls({ isPlaying, currentTime, duration, volume, muted, playbackSpeed, markers, isFullscreen, videoQualityLevels, videoQualityLevel, onVideoQualityChange, onPlayPause, onSeek, onSeekStart, onSeekEnd, onSkip, onRestart, onVolumeChange, onMuteToggle, onSpeedChange, onFullscreenToggle, onEditorInteraction, interactionPoints, branches, onBranchClick, branchCount, isBranchPanelOpen, onBranchPanelToggle, isInteractive, showMarkers, compact, }: PlayerControlsProps): react_jsx_runtime.JSX.Element;
 
 /**
  * Timeline Component
@@ -2842,7 +3419,7 @@ interface Marker {
     id: string;
     time: number;
     label: string;
-    type: 'chapter' | 'highlight' | 'quiz' | 'note' | 'bookmark' | 'error';
+    type: 'chapter' | 'bookmark' | 'quiz' | 'note' | 'error';
     description?: string;
 }
 /**
@@ -2897,6 +3474,128 @@ interface TimelineProps {
  */
 declare function Timeline({ currentTime, duration, markers, chunks, buffered, onSeek, onMarkerClick, theme, showChapterLabels, showBufferStatus, showChunkIndicators, compact, }: TimelineProps): JSX.Element;
 
+/**
+ * MCQOverlay — full-area overlay that renders a multiple-choice question
+ * on top of the player content.
+ *
+ * Phases: Question → Loading → Feedback (with optional retry).
+ * Handles timeout countdown, focus trapping, and keyboard navigation.
+ *
+ * @packageDocumentation
+ */
+
+interface MCQOverlayProps {
+    /** The interaction point to display */
+    point: InteractionPoint;
+    /** Called when the learner submits an answer. Returns result from host app. */
+    onSubmit: (selectedOptionIds: string[]) => Promise<MCQResult>;
+    /** Called when the learner is done (correct answer, or gave up) */
+    onDismiss: () => void;
+    /** Optional extra class name for the outer container */
+    className?: string;
+}
+declare const MCQOverlay: React__default__default.FC<MCQOverlayProps>;
+
+/**
+ * BranchTransition — end-of-lesson overlay with auto-advance countdown.
+ *
+ * Shows "Next: [title]" with countdown + skip/cancel, or a "Course Complete"
+ * message when there's no next lesson.
+ *
+ * @packageDocumentation
+ */
+
+interface BranchTransitionProps {
+    /** Title of the next lesson */
+    nextLessonTitle: string;
+    /** Countdown seconds remaining */
+    countdown: number;
+    /** Skip countdown and navigate immediately */
+    onSkip: () => void;
+    /** Stop auto-advance (stay on current lesson) */
+    onCancel: () => void;
+    /** If true, show "Course Complete" instead of next lesson */
+    isComplete?: boolean;
+}
+declare const BranchTransition: React__default__default.FC<BranchTransitionProps>;
+
+/**
+ * SaveBranchButton — floating pill button shown in the top-right of the IDE
+ * panel when the learner is in interactive mode and has made code changes.
+ *
+ * @packageDocumentation
+ */
+
+interface SaveBranchButtonProps {
+    /** Whether the button should be visible */
+    visible: boolean;
+    /** Called when the learner clicks "Save Branch" */
+    onSave: () => void;
+    /** Whether the max branch limit has been reached */
+    limitReached?: boolean;
+}
+declare const SaveBranchButton: React__default__default.FC<SaveBranchButtonProps>;
+
+/**
+ * BranchSavedToast — brief confirmation toast shown after saving a branch.
+ *
+ * Slides up, holds, then fades out automatically.
+ *
+ * @packageDocumentation
+ */
+
+interface BranchSavedToastProps {
+    /** Whether to show the toast */
+    visible: boolean;
+    /** Called when the toast fully disappears */
+    onDismiss: () => void;
+    /** Optional message override (defaults to "Branch saved") */
+    message?: string;
+    /** Show as a duplicate/error toast instead of success */
+    variant?: "success" | "duplicate";
+}
+declare const BranchSavedToast: React__default__default.FC<BranchSavedToastProps>;
+
+/**
+ * UnsavedBranchPrompt — tooltip-style popup that appears near the play button
+ * when the learner exits interactive mode with unsaved code changes.
+ *
+ * Offers "Save & Resume" or "Discard & Resume". Auto-dismisses after 5 seconds.
+ *
+ * @packageDocumentation
+ */
+
+interface UnsavedBranchPromptProps {
+    /** Whether to show the prompt */
+    visible: boolean;
+    /** Called when the user chooses "Save & Resume" */
+    onSaveAndResume: () => void;
+    /** Called when the user chooses "Discard & Resume" or prompt auto-dismisses */
+    onDiscardAndResume: () => void;
+}
+declare const UnsavedBranchPrompt: React__default__default.FC<UnsavedBranchPromptProps>;
+
+interface BranchPanelProps {
+    /** Whether the panel is visible */
+    visible: boolean;
+    /** All branches for the current lesson */
+    branches: LearnerBranch[];
+    /** Close the panel */
+    onClose: () => void;
+    /** Restore a branch (seek + interactive + inject) */
+    onRestore: (branch: LearnerBranch) => void;
+    /** Delete a branch by id */
+    onDelete: (branchId: string) => void;
+    /** Rename a branch */
+    onRename: (branchId: string, newLabel: string) => void;
+    /** Maximum branches per lesson (for limit warning) */
+    maxBranches?: number;
+    /** Ref to the anchor element for fixed positioning */
+    anchorRef?: React__default__default.RefObject<HTMLDivElement>;
+}
+declare function BranchPanelInner({ visible, branches, onClose, onRestore, onDelete, onRename, maxBranches, anchorRef, }: BranchPanelProps): react_jsx_runtime.JSX.Element | null;
+declare const BranchPanel: React__default__default.MemoExoticComponent<typeof BranchPanelInner>;
+
 /**
  * AudioOverlay Component
  *
@@ -2908,11 +3607,11 @@ declare function Timeline({ currentTime, duration, markers, chunks, buffered, on
 /**
  * Overlay position presets
  */
-type OverlayPosition = 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left' | 'custom';
+type OverlayPosition$1 = 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left' | 'custom';
 /**
  * Custom position
  */
-interface CustomPosition {
+interface CustomPosition$1 {
     x: number;
     y: number;
 }
@@ -2929,9 +3628,9 @@ interface AudioOverlayProps {
     /** Playback rate */
     playbackRate?: number;
     /** Overlay position preset */
-    position?: OverlayPosition;
+    position?: OverlayPosition$1;
     /** Custom position (when position='custom') */
-    customPosition?: CustomPosition;
+    customPosition?: CustomPosition$1;
     /** Whether to show the overlay */
     visible?: boolean;
     /** Enable dragging */
@@ -2941,7 +3640,7 @@ interface AudioOverlayProps {
     /** Opacity (0-1) */
     opacity?: number;
     /** On position change callback */
-    onPositionChange?: (position: CustomPosition) => void;
+    onPositionChange?: (position: CustomPosition$1) => void;
     /** Callback to pass audio element reference for sync */
     onAudioRef?: (audio: HTMLAudioElement | null) => void;
     /** Whether audio is muted */
@@ -2960,4 +3659,55 @@ interface AudioOverlayProps {
  */
 declare function AudioOverlay({ src, currentTime: _currentTime, isPlaying: _isPlaying, playbackRate: _playbackRate, position, customPosition, visible, draggable, showControls, opacity, onPositionChange, onAudioRef, muted: _muted, volume: _volume, syncTolerance: _syncTolerance, }: AudioOverlayProps): JSX.Element | null;
 
-export { AudioOverlay, type AudioOverlayProps, type AudioQuality, type AudioSyncControls, type AudioSyncState, type BackendAdapter, type BufferHealth, type CTEvent, type CTManifest, type CTMarker, type CTReadOptions, type CTRecording, CoursePlayer, type CoursePlayerProps, type CoursePlayerRef, type CursorPosition, type CustomPosition, DocumentPanel, type DocumentPanelProps, FileExplorer, type FileExplorerProps, type FileSystemSnapshot, type HLSPlayerInstance, HLS_EVENTS, IDEPanel, type IDEPanelProps, type InternalEvent, type InternalRecording, type OverlayPosition, type PanelMode, type PlaybackControls$1 as PlaybackControls, type PlaybackEngineConfig, type PlaybackHookState, type PlaybackState, PlayerControls, type PlayerControlsProps$1 as PlayerControlsProps, type PlayerProps, type PlayerRef, type RecordingMarker, type RemoteBufferHealth, type RemoteStreamingMetrics, type RemoteStreamingPlaybackControls, type RemoteStreamingPlaybackState, type SpeedSelectorProps, type StreamingAudioConfig, type StreamingConfig, StreamingCoursePlayer, type StreamingCoursePlayerProps, type StreamingCoursePlayerRef, type StreamingEventsConfig, type StreamingManifest, type StreamingMetrics, type StreamingPlaybackControls, type StreamingPlaybackState, type StreamingRecordingInfo, Terminal, type TerminalLineData, type TerminalProps, Timeline, type TimelineProps$1 as TimelineProps, ToolSidebar, type ToolSidebarProps, type ToolType, type UseAudioSyncOptions, type UsePlaybackEngineResult, type UsePlaybackOptions, type UseRemoteStreamingPlaybackOptions, type UseVideoSyncOptions, type ValidationResult$1 as ValidationResult, type VideoSyncControls, type VideoSyncState, type VolumeControlProps, AudioOverlay as WebcamOverlay, type AudioOverlayProps as WebcamOverlayProps, WhiteboardPanel, type WhiteboardPanelProps, type WriteCTOptions, canPlayHls, createEmptyRecording, createHlsPlayer, destroyHlsPlayer, hasNativeHlsSupport, isHlsSupported, readCTFile, readCTManifest, useAudioElement, useAudioSync, useInteractiveMode, usePlayback, usePlayback as usePlaybackEngine, useRemoteStreamingPlayback, useStreamingPlayback, useVideoElement, useVideoSync, validateCTFile, writeCTFile };
+/**
+ * WebcamOverlay Component v3
+ *
+ * Clean webcam video overlay with:
+ * - Draggable circular bubble
+ * - Maximize on hover click
+ * - Smooth animations
+ *
+ * @packageDocumentation
+ */
+type OverlayPosition = "top-right" | "top-left" | "bottom-right" | "bottom-left" | "custom";
+type OverlaySize = "small" | "medium" | "large" | "custom";
+interface CustomPosition {
+    x: number;
+    y: number;
+}
+interface CustomSize {
+    width: number;
+    height: number;
+}
+interface WebcamOverlayProps {
+    src: string | null;
+    currentTime: number;
+    isPlaying: boolean;
+    playbackRate?: number;
+    position?: OverlayPosition;
+    customPosition?: CustomPosition;
+    size?: OverlaySize;
+    customSize?: CustomSize;
+    visible?: boolean;
+    draggable?: boolean;
+    resizable?: boolean;
+    showControls?: boolean;
+    borderRadius?: number | "circle";
+    opacity?: number;
+    onPositionChange?: (position: CustomPosition) => void;
+    onSizeChange?: (size: CustomSize) => void;
+    onVisibilityToggle?: () => void;
+    onVideoRef?: (video: HTMLVideoElement | null) => void;
+    muted?: boolean;
+    volume?: number;
+    syncTolerance?: number;
+    /** Whether webcam is in maximized (full overlay) mode - from playback events */
+    maximized?: boolean;
+    /** Callback when user clicks minimize button */
+    onMinimize?: () => void;
+    /** Callback when user clicks maximize button */
+    onMaximize?: () => void;
+}
+declare function WebcamOverlay({ src, currentTime: _currentTime, isPlaying: _isPlaying, playbackRate: _playbackRate, position, customPosition, size, customSize, visible, draggable, resizable: _resizable, showControls: _showControls, borderRadius, opacity, onPositionChange, onSizeChange: _onSizeChange, onVisibilityToggle: _onVisibilityToggle, onVideoRef, muted: _muted, volume: _volume, syncTolerance: _syncTolerance, maximized, onMinimize, onMaximize, }: WebcamOverlayProps): JSX.Element | null;
+
+export { AudioOverlay, type AudioOverlayProps, type AudioQuality, type AudioSyncControls, type AudioSyncState, type BackendAdapter, BranchPanel, type BranchPanelProps, BranchSavedToast, type BranchSavedToastProps, type BranchSnapshot, BranchTransition, type BranchTransitionProps, type BufferHealth, type CTEvent, type CTManifest, type CTMarker, type CTReadOptions, type CTRecording, CoursePlayer, type CoursePlayerProps, type CoursePlayerRef, type CursorPosition, type CustomPosition$1 as CustomPosition, DocumentPanel, type DocumentPanelProps, FileExplorer, type FileExplorerProps, type FileSystemSnapshot, type HLSPlayerInstance, HLS_EVENTS, IDEPanel, type IDEPanelProps, type InteractionPoint, type InternalEvent, type InternalRecording, type LearnerBranch, MCQOverlay, type MCQOverlayProps, type MCQResult, type MCQSubmission, type OverlayPosition$1 as OverlayPosition, type PanelMode, type PlaybackControls$1 as PlaybackControls, type PlaybackEngineConfig, type PlaybackHookState, type PlaybackState, PlayerControls, type PlayerControlsProps$1 as PlayerControlsProps, type PlayerProps, type PlayerRef, type RecordingMarker, type RemoteBufferHealth, type RemoteStreamingMetrics, type RemoteStreamingPlaybackControls, type RemoteStreamingPlaybackState, SaveBranchButton, type SaveBranchButtonProps, type SpeedSelectorProps, type StreamingAudioConfig, type StreamingConfig, StreamingCoursePlayer, type StreamingCoursePlayerProps, type StreamingCoursePlayerRef, type StreamingEventsConfig, type StreamingManifest, type StreamingMetrics, type StreamingPlaybackControls, type StreamingPlaybackState, type StreamingRecordingInfo, Terminal, type TerminalLineData, type TerminalProps, Timeline, type TimelineProps$1 as TimelineProps, ToolSidebar, type ToolSidebarProps, type ToolType, UnsavedBranchPrompt, type UnsavedBranchPromptProps, type UseAudioSyncOptions, type UseBranchesOptions, type UseBranchesResult, type UseBranchingOptions, type UseBranchingResult, type UseInteractionPointsOptions, type UseInteractionPointsResult, type UsePlaybackEngineResult, type UsePlaybackOptions, type UseRemoteStreamingPlaybackOptions, type UseVideoSyncOptions, type ValidationResult$1 as ValidationResult, type VideoSyncControls, type VideoSyncState, type VolumeControlProps, WebcamOverlay, type WebcamOverlayProps, WhiteboardPanel, type WhiteboardPanelProps, type WriteCTOptions, canPlayHls, createEmptyRecording, createHlsPlayer, deleteBranch as deleteBranchFromStorage, destroyHlsPlayer, formatBranchTime, hasNativeHlsSupport, isHlsSupported, loadBranches, readCTFile, readCTManifest, saveBranch as saveBranchToStorage, updateBranchLabel, useAudioElement, useAudioSync, useBranches, useBranching, useInteractionPoints, useInteractiveMode, usePlayback, usePlayback as usePlaybackEngine, useRemoteStreamingPlayback, useStreamingPlayback, useVideoElement, useVideoSync, validateCTFile, writeCTFile };