@illuma-ai/code-sandbox 1.1.0 → 1.2.0

package/src/types.ts

@@ -2,7 +2,7 @@
  * @illuma-ai/code-sandbox — Type definitions
  *
  * Core types for the browser-native code sandbox.
- * Covers file maps, runtime states, git operations, and component props.
+ * Covers file maps, runtime states, imperative handle, and component props.
  */
 
 // ---------------------------------------------------------------------------
@@ -138,11 +138,9 @@ export interface RuntimeState {
   files: FileMap;
   /**
    * Baseline file snapshot — the files as they were before the latest
-   * update (initial load, or the version before the last GitHub poll).
-   *
-   * Used by the diff viewer to show what changed. Empty on first load
-   * (everything is "new"), populated after the first file update
-   * (GitHub poll, updateFiles, etc.).
+   * update (via updateFiles). Used by the diff viewer to show what changed.
+   * Empty on first load (everything is "new"), populated after the first
+   * file update.
    */
   originalFiles: FileMap;
   /**
@@ -163,7 +161,7 @@ export interface RuntimeState {
 }
 
 // ---------------------------------------------------------------------------
-// Git (GitHub API integration)
+// Git (GitHub API integration — utility, NOT used internally by sandbox)
 // ---------------------------------------------------------------------------
 
 export interface GitHubRepo {
@@ -199,17 +197,118 @@ export interface GitPRResult {
   branch: string;
 }
 
+// ---------------------------------------------------------------------------
+// Imperative Handle
+// ---------------------------------------------------------------------------
+
+/**
+ * Imperative handle exposed by CodeSandbox via React.forwardRef.
+ *
+ * This is the primary API for host applications (like Ranger) to
+ * control the sandbox programmatically. The sandbox is a "dumb renderer"
+ * — the host pushes files in and reads state out.
+ *
+ * @example
+ * ```tsx
+ * const ref = useRef<CodeSandboxHandle>(null);
+ *
+ * // Push files from any source (GitHub, DB, S3, agent output)
+ * ref.current?.updateFiles(fileMap);
+ *
+ * // Push a single file (e.g., agent modified one file)
+ * ref.current?.updateFile('server.js', newContent);
+ *
+ * // Read current state
+ * const files = ref.current?.getFiles();
+ * const changes = ref.current?.getChangedFiles();
+ * const errors = ref.current?.getErrors();
+ * ```
+ */
+export interface CodeSandboxHandle {
+  /**
+   * Replace the entire file set. Diffs against current files, writes only
+   * changed files to Nodepod FS, and restarts the server if anything changed.
+   *
+   * The previous file set becomes `originalFiles` for diff tracking.
+   *
+   * @param files - Complete new file set
+   * @param options - Optional: restartServer (default true)
+   */
+  updateFiles: (
+    files: FileMap,
+    options?: { restartServer?: boolean },
+  ) => Promise<void>;
+
+  /**
+   * Update a single file. Writes to Nodepod FS and updates state.
+   * Does NOT restart the server — call `restart()` manually if needed,
+   * or use `updateFiles()` for bulk updates with auto-restart.
+   *
+   * @param path - File path (e.g., "server.js", "public/index.html")
+   * @param content - New file content
+   */
+  updateFile: (path: string, content: string) => Promise<void>;
+
+  /**
+   * Force restart the server process. Kills the current process
+   * and re-runs the entry command.
+   */
+  restart: () => Promise<void>;
+
+  /**
+   * Get the current file map (all files including edits).
+   */
+  getFiles: () => FileMap;
+
+  /**
+   * Get only files that have been modified relative to originalFiles.
+   * Returns a FileMap containing only the changed files.
+   */
+  getChangedFiles: () => FileMap;
+
+  /**
+   * Get the per-file change status map (new/modified/deleted).
+   * Missing keys should be treated as "unchanged".
+   */
+  getFileChanges: () => Record<string, FileChangeStatus>;
+
+  /**
+   * Get all structured errors collected during this session.
+   */
+  getErrors: () => SandboxError[];
+
+  /**
+   * Get the current runtime state snapshot.
+   */
+  getState: () => RuntimeState;
+}
+
 // ---------------------------------------------------------------------------
 // Component Props
 // ---------------------------------------------------------------------------
 
+/**
+ * Props for the CodeSandbox component.
+ *
+ * The sandbox is a pure renderer — it receives files via props and
+ * exposes an imperative handle for programmatic updates. It does NOT
+ * interact with any storage backend (GitHub, S3, DB) directly.
+ *
+ * File sources (for initial load, pick ONE):
+ * - `files` — pass a FileMap directly
+ * - `template` — use a built-in template name (e.g., "fullstack-starter")
+ *
+ * For live updates after mount, use the imperative handle:
+ * ```tsx
+ * const ref = useRef<CodeSandboxHandle>(null);
+ * <CodeSandbox ref={ref} files={initialFiles} />
+ * // Later:
+ * ref.current.updateFiles(newFiles);
+ * ```
+ */
 export interface CodeSandboxProps {
-  /** Pass files directly */
+  /** Pass files directly (from any source — GitHub, DB, S3, agent, etc.) */
   files?: FileMap;
-  /** OR load from GitHub */
-  github?: GitHubRepo;
-  /** GitHub personal access token (for private repos and write-back) */
-  gitToken?: string;
   /** OR use a built-in template name */
   template?: string;
   /** Command to start the dev server (default inferred from package.json or template) */
@@ -220,9 +319,9 @@ export interface CodeSandboxProps {
   env?: Record<string, string>;
 
   // Callbacks
-  /** Fires when a file is modified in the editor */
+  /** Fires when a file is modified in the editor by the user */
   onFileChange?: (path: string, content: string) => void;
-  /** Fires when the dev server is ready */
+  /** Fires when the dev server is ready (initial boot or after restart) */
   onServerReady?: (port: number, url: string) => void;
   /** Fires on boot progress changes */
   onProgress?: (progress: BootProgress) => void;
@@ -238,6 +337,12 @@ export interface CodeSandboxProps {
    * Max 2 auto-fix attempts per error is recommended (see Ranger pattern).
    */
   onSandboxError?: (error: SandboxError) => void;
+  /**
+   * Fires after updateFiles() completes (files written + server restarted).
+   * Useful for the host to know when the sandbox has finished processing
+   * a file push.
+   */
+  onFilesUpdated?: (fileChanges: Record<string, FileChangeStatus>) => void;
 
   // Layout
   /** CSS class name for the root element */