@ct-player/embed 1.1.3 → 1.1.5

package/dist/index.d.ts

@@ -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' | 'file_select' | 'file_change' | 'file_creation_start' | 'file_creation_input' | 'file_creation_cancel' | 'cursor_move' | 'cursor_click' | 'cursor_enter' | 'cursor_leave' | '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' | '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';
 /**
  * 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<'file_select'> | CTEventBase<'file_change'> | CTEventBase<'file_creation_start'> | CTEventBase<'file_creation_input'> | CTEventBase<'file_creation_cancel'> | CTEventBase<'cursor_move'> | CTEventBase<'cursor_click'> | CTEventBase<'cursor_enter'> | CTEventBase<'cursor_leave'> | 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<'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'>;
 /**
  * Mapping of event types to their data structures
  */
@@ -56,13 +56,22 @@ interface CTEventDataMap {
     file_delete: FileDeleteEventData;
     file_rename: FileRenameEventData;
     file_switch: FileSwitchEventData;
+    folder_create: FolderCreateEventData;
+    folder_delete: FolderDeleteEventData;
     file_creation_start: FileCreationStartEventData;
     file_creation_input: FileCreationInputEventData;
     file_creation_cancel: FileCreationCancelEventData;
+    file_rename_start: FileRenameStartEventData;
+    file_rename_input: FileRenameInputEventData;
+    file_rename_cancel: FileRenameCancelEventData;
+    folder_toggle: FolderToggleEventData;
     cursor_move: CursorMoveEventData;
     cursor_click: CursorClickEventData;
     cursor_enter: CursorEnterEventData;
     cursor_leave: CursorLeaveEventData;
+    file_hover: FileHoverEventData;
+    text_select: TextSelectEventData;
+    editor_cursor: EditorCursorEventData;
     tool_switch: ToolSwitchEventData;
     marker: MarkerEventData;
     tool: ToolEventData;
@@ -440,6 +449,18 @@ interface FileRenameEventData {
 interface FileSwitchEventData {
     path: string;
 }
+/**
+ * Create an empty folder
+ */
+interface FolderCreateEventData {
+    path: string;
+}
+/**
+ * Delete a folder and all its contents
+ */
+interface FolderDeleteEventData {
+    path: string;
+}
 /**
  * File/folder creation UI started - shows the inline input
  */
@@ -463,6 +484,38 @@ interface FileCreationCancelEventData {
     /** Reason for cancellation (optional) */
     reason?: 'escape' | 'blur' | 'other';
 }
+/**
+ * File/folder rename UI started - shows the inline input
+ */
+interface FileRenameStartEventData {
+    /** Path of the file/folder being renamed */
+    path: string;
+    /** Current name of the item */
+    currentName: string;
+}
+/**
+ * File/folder rename input changed - for typing animation
+ */
+interface FileRenameInputEventData {
+    /** Current value of the input field */
+    value: string;
+}
+/**
+ * File/folder rename cancelled - hides the inline input
+ */
+interface FileRenameCancelEventData {
+    /** Reason for cancellation (optional) */
+    reason?: 'escape' | 'blur' | 'other';
+}
+/**
+ * Folder expanded or collapsed
+ */
+interface FolderToggleEventData {
+    /** Path of the folder */
+    path: string;
+    /** Whether the folder is now expanded */
+    expanded: boolean;
+}
 /**
  * Cursor position update
  */
@@ -491,6 +544,37 @@ interface CursorEnterEventData {
 interface CursorLeaveEventData {
     area: string;
 }
+/**
+ * File/folder hover in file explorer — highlights the hovered item during playback
+ */
+interface FileHoverEventData {
+    /** Path of the hovered file/folder, or null when hover ends */
+    path: string | null;
+}
+/**
+ * Text selection in IDE editor or terminal
+ */
+interface TextSelectEventData {
+    /** Where the selection occurred */
+    source: 'editor' | 'terminal';
+    /** Selected text (empty string means selection cleared) */
+    text: string;
+    /** Start position (for editor selections) */
+    startLine?: number;
+    startColumn?: number;
+    /** End position (for editor selections) */
+    endLine?: number;
+    endColumn?: number;
+}
+/**
+ * Editor typing cursor (caret) position
+ */
+interface EditorCursorEventData {
+    /** Line number (1-based) */
+    line: number;
+    /** Column number (1-based) */
+    column: number;
+}
 /**
  * Switch active tool
  */
@@ -567,6 +651,8 @@ interface PlaybackState$1 {
     currentFile: string | null;
     /** Virtual file system (path → content) */
     fileSystem: Record<string, string>;
+    /** Explicitly created empty folders (folders with no files) */
+    folders: Set<string>;
     /** Currently loaded document */
     documentData: DocumentData | null;
     /** Current document page number */
@@ -583,9 +669,20 @@ interface PlaybackState$1 {
         x: number;
         y: number;
         visible: boolean;
+        clicking?: boolean;
     };
     /** File creation UI state - for showing inline input during playback */
     fileCreation: FileCreationState | null;
+    /** File renaming UI state - for showing inline input during playback */
+    fileRenaming: FileRenamingState | null;
+    /** Expanded folders in the file explorer during playback */
+    expandedFolders: Set<string>;
+    /** Currently hovered file/folder path in file explorer (null = no hover) */
+    hoveredFile: string | null;
+    /** Current text selection state */
+    textSelection: TextSelectionState | null;
+    /** Editor typing cursor (caret) position */
+    editorCursor: EditorCursorState | null;
 }
 /**
  * State for file/folder creation UI display during playback
@@ -598,6 +695,41 @@ interface FileCreationState {
     /** Current input value (filename being typed) */
     inputValue: string;
 }
+/**
+ * State for file/folder rename UI display during playback
+ */
+interface FileRenamingState {
+    /** Path of the file/folder being renamed */
+    path: string;
+    /** Current name of the item */
+    currentName: string;
+    /** Current input value (new name being typed) */
+    inputValue: string;
+}
+/**
+ * Text selection state for playback overlay
+ */
+interface TextSelectionState {
+    /** Where the selection is */
+    source: 'editor' | 'terminal';
+    /** Selected text */
+    text: string;
+    /** Start position (editor) */
+    startLine?: number;
+    startColumn?: number;
+    /** End position (editor) */
+    endLine?: number;
+    endColumn?: number;
+}
+/**
+ * Editor cursor (typing caret) state for playback
+ */
+interface EditorCursorState {
+    /** Line number (1-based) */
+    line: number;
+    /** Column number (1-based) */
+    column: number;
+}
 
 /**
  * CT Format Chunked Events Types
@@ -1224,12 +1356,20 @@ interface ValidationResult$1 {
  * Validate a complete CT recording
  */
 declare function validateCTFile(recording: CTRecording): ValidationResult$1;
+interface FileTreeNode {
+    name: string;
+    type: 'file' | 'directory';
+    path: string;
+    language?: string;
+    children?: FileTreeNode[];
+}
 
 /**
  * CT-Courses UI Types
  *
  * Shared type definitions for all UI components.
  */
+
 /**
  * Component operation mode
  */
@@ -1290,6 +1430,10 @@ interface IDEPanelProps extends BasePanelProps {
     terminalLines?: TerminalLineData[];
     /** Current terminal input */
     terminalInput?: string;
+    /** Pre-built file tree — when provided, IDEPanel skips internal tree building from VFS */
+    tree?: FileTreeNode;
+    /** Flat file map (path → content) for reading file contents in playback mode */
+    files?: Record<string, string>;
     /** Called when code changes */
     onCodeChange?: (code: string, language: string) => void;
     /** Called when cursor moves */
@@ -1306,6 +1450,10 @@ interface IDEPanelProps extends BasePanelProps {
     onFileDelete?: (path: string) => void;
     /** Called when a file is renamed */
     onFileRename?: (oldPath: string, newPath: string) => void;
+    /** Called when a folder is created */
+    onFolderCreate?: (path: string) => void;
+    /** Called when a folder is deleted */
+    onFolderDelete?: (path: string) => void;
     /**
      * File creation state during playback - shows inline input for typing animation.
      * When set, displays the file creation UI with the inputValue.
@@ -1321,6 +1469,28 @@ interface IDEPanelProps extends BasePanelProps {
     onFileCreationInput?: (value: string) => void;
     /** Called when file creation is cancelled */
     onFileCreationCancel?: (reason?: string) => void;
+    /**
+     * File renaming state during playback - shows inline input for typing animation.
+     * When set, displays the file rename UI with the inputValue.
+     */
+    fileRenamingState?: {
+        path: string;
+        currentName: string;
+        inputValue: string;
+    } | null;
+    /** Called when file rename starts (user clicks Rename button) */
+    onFileRenameStart?: (path: string, currentName: string) => void;
+    /** Called when file rename input changes (user types in the rename input) */
+    onFileRenameInput?: (value: string) => void;
+    /** Called when file rename is cancelled */
+    onFileRenameCancel?: (reason?: string) => void;
+    /**
+     * Expanded folders state during playback - controls which folders are expanded.
+     * When set, uses this instead of local state for folder expansion.
+     */
+    expandedFoldersState?: Set<string> | null;
+    /** Called when a folder is expanded or collapsed */
+    onFolderToggle?: (path: string, expanded: boolean) => void;
     /** Called when terminal input changes */
     onTerminalInputChange?: (input: string) => void;
     /** Called when a command is executed */
@@ -1349,6 +1519,38 @@ interface IDEPanelProps extends BasePanelProps {
     onExecute?: (path: string, language: string) => Promise<TerminalLineData[] | undefined>;
     /** Execute terminal command handler (uses TerminalService for full command support) */
     onTerminalExecute?: (command: string) => Promise<TerminalLineData[]>;
+    /** Currently hovered file path in file explorer (playback display) */
+    hoveredFile?: string | null;
+    /** File hover callback (recording) */
+    onFileHover?: (path: string | null) => void;
+    /** Text selection state (playback display) */
+    textSelection?: {
+        source: 'editor' | 'terminal';
+        text: string;
+        startLine?: number;
+        startColumn?: number;
+        endLine?: number;
+        endColumn?: number;
+    } | null;
+    /** Text selection callback (recording) */
+    onTextSelect?: (selection: {
+        source: 'editor' | 'terminal';
+        text: string;
+        startLine?: number;
+        startColumn?: number;
+        endLine?: number;
+        endColumn?: number;
+    }) => void;
+    /** Editor cursor (typing caret) position (playback display) */
+    editorCursor?: {
+        line: number;
+        column: number;
+    } | null;
+    /** Editor cursor change callback (recording) */
+    onEditorCursorChange?: (position: {
+        line: number;
+        column: number;
+    }) => void;
 }
 /**
  * Excalidraw scene structure (simplified)
@@ -1481,36 +1683,67 @@ interface TerminalRef {
     scrollToBottom: () => void;
 }
 /**
- * File Explorer props
+ * File Explorer props — fully props-driven, VS Code-like component.
+ *
+ * Key design decisions:
+ *   - No internal VFS subscription. The tree is passed as a pre-built prop.
+ *   - `expandedFolders` is always controlled from the parent.
+ *   - `mode` + `isPlaying` replace the old ambiguous `readOnly` flag.
+ *   - Interaction is allowed when:
+ *       mode === 'recording' || mode === 'interactive' ||
+ *       (mode === 'playback' && !isPlaying)
  */
 interface FileExplorerProps {
-    /** Currently selected file path */
-    selectedFile?: string | null;
-    /** Called when file is selected */
-    onFileSelect: (path: string) => void;
-    /** Called when file is created */
+    /** Pre-built tree from buildFileTree() */
+    tree: FileTreeNode;
+    /** Currently active / selected file path */
+    selectedFile: string | null;
+    /** Which folders are expanded — controlled from parent */
+    expandedFolders: Set<string>;
+    /** Playback file creation state — shows inline typing input */
+    fileCreation?: {
+        type: 'file' | 'folder';
+        parentPath: string;
+        inputValue: string;
+    } | null;
+    /** Playback file rename state — shows inline rename input */
+    fileRenaming?: {
+        path: string;
+        currentName: string;
+        inputValue: string;
+    } | null;
+    /** Current operation mode */
+    mode: 'recording' | 'playback' | 'interactive';
+    /** True when playback is actively running (blocks user interaction) */
+    isPlaying?: boolean;
+    /** Called when a file is clicked */
+    onFileSelect?: (path: string) => void;
+    /** Called when a new file is created */
     onFileCreate?: (path: string, content: string) => void;
-    /** Called when folder is created */
+    /** Called when a new folder is created */
     onFolderCreate?: (path: string) => void;
-    /** Called when file is deleted */
+    /** Called when a file/folder is deleted */
     onFileDelete?: (path: string) => void;
-    /** Called when file is renamed */
+    /** Called when a file/folder is renamed */
     onFileRename?: (oldPath: string, newPath: string) => void;
-    /** Called when user starts creating a file/folder (clicks New File/Folder button) */
+    /** Called when a folder is toggled (expand/collapse) */
+    onFolderToggle?: (path: string, expanded: boolean) => void;
+    /** Called when user clicks New File/Folder button */
     onFileCreationStart?: (type: 'file' | 'folder', parentPath: string) => void;
-    /** Called when user types in the file creation input */
+    /** Called when user types in file creation input */
     onFileCreationInput?: (value: string) => void;
-    /** Called when user cancels file creation (Escape or blur) */
+    /** Called when user cancels file creation */
     onFileCreationCancel?: (reason?: string) => void;
-    /**
-     * Playback file creation state - for showing the file creation input during playback.
-     * When set, displays a read-only input showing the filename being typed.
-     */
-    playbackFileCreation?: {
-        type: 'file' | 'folder';
-        parentPath: string;
-        inputValue: string;
-    } | null;
+    /** Called when user starts renaming */
+    onFileRenameStart?: (path: string, currentName: string) => void;
+    /** Called when user types in rename input */
+    onFileRenameInput?: (value: string) => void;
+    /** Called when user cancels rename */
+    onFileRenameCancel?: (reason?: string) => void;
+    /** Currently hovered file/folder path during playback */
+    hoveredFile?: string | null;
+    /** Called when user hovers over a file/folder (recording) */
+    onFileHover?: (path: string | null) => void;
     /** Additional CSS classes */
     className?: string;
 }
@@ -1542,22 +1775,20 @@ interface VirtualFileSystem {
     getFileTree: () => FileSystemEntry;
     subscribe: (callback: () => void) => () => void;
     writeFile: (path: string, content: string) => void;
-    /** Optional: Delete a file by path */
-    deleteFile?: (path: string) => void;
-    /** Optional: Read file content by path */
+    deleteFile?: (path: string) => boolean;
+    deleteDirectory?: (path: string) => boolean;
+    exists?: (path: string) => boolean;
+    directoryExists?: (path: string) => boolean;
     readFile?: (path: string) => string;
-    /** Optional: Get all files as a record */
     getFiles?: () => Record<string, string>;
-    /** Optional: Notify subscribers of changes (call after batch VFS operations) */
     notifyChanged?: () => void;
+    mkdir?: (path: string) => void;
 }
-declare function FileExplorer({ fileSystem, selectedFile, onFileSelect, onFileCreate, onFolderCreate, onFileDelete, onFileRename, onFileCreationStart, onFileCreationInput, onFileCreationCancel, playbackFileCreation, className }: FileExplorerProps & {
-    fileSystem: VirtualFileSystem;
+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 & {
+    fileSystem?: VirtualFileSystem;
 }): react_jsx_runtime.JSX.Element;
 
-declare function IDEPanel({ fileSystem, code: externalCode, language: externalLanguage, currentFile: externalCurrentFile, onCodeChange, onFileChange, onFileCreate, onFileDelete, onFileRename, onFileSelect, onTerminalCommand, onTerminalClear, onTerminalAddLines, fileCreationState, onFileCreationStart, onFileCreationInput, onFileCreationCancel, terminalLines: externalTerminalLines, terminalInput: externalTerminalInput, onTerminalInputChange, onExecute, onTerminalExecute, mode, isPlaying, defaultShowExplorer, defaultShowTerminal, showRunButton, interactiveLabel, initialFiles, initialActiveFile }: 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>>;