@illuma-ai/code-sandbox 1.0.0 → 1.2.0

package/src/hooks/useRuntime.ts

@@ -3,6 +3,15 @@
  *
  * Manages the Nodepod runtime instance and exposes reactive state
  * for all UI components (progress, files, terminal output, preview URL).
+ *
+ * The sandbox is a pure renderer — it receives files via props (initial
+ * load) and via the imperative handle (updateFiles/updateFile for live
+ * updates). It does NOT interact with any storage backend directly.
+ *
+ * Error exposure: wires the runtime's structured error system and the
+ * preview iframe's browser error capture into a unified `errors[]` array
+ * in state, and forwards each error to the `onSandboxError` callback
+ * so the AI agent can auto-fix.
  */
 
 import { useCallback, useEffect, useRef, useState } from "react";
@@ -11,15 +20,67 @@ import { getTemplate } from "../templates";
 import type {
   BootProgress,
   CodeSandboxProps,
+  FileChangeStatus,
   FileMap,
   RuntimeState,
+  SandboxError,
 } from "../types";
 
+/** Debug log prefix for easy filtering in DevTools */
+const DBG = "[CodeSandbox:useRuntime]";
+
+/**
+ * Compute per-file change statuses between an original and current file set.
+ *
+ * Returns only files with a non-"unchanged" status (new, modified, deleted).
+ * Files that are identical are omitted — treat missing keys as "unchanged".
+ */
+function computeFileChanges(
+  original: FileMap,
+  current: FileMap,
+): Record<string, FileChangeStatus> {
+  const changes: Record<string, FileChangeStatus> = {};
+
+  // Check current files against original
+  for (const path of Object.keys(current)) {
+    if (!(path in original)) {
+      changes[path] = "new";
+    } else if (original[path] !== current[path]) {
+      changes[path] = "modified";
+    }
+    // unchanged — omit
+  }
+
+  // Check for deleted files (in original but not in current)
+  for (const path of Object.keys(original)) {
+    if (!(path in current)) {
+      changes[path] = "deleted";
+    }
+  }
+
+  return changes;
+}
+
 /**
  * Hook that manages the full Nodepod runtime lifecycle.
  *
+ * The sandbox is a pure renderer — files come in via props or the
+ * imperative handle. No GitHub, no polling, no storage backends.
+ *
  * @param props - CodeSandbox component props
- * @returns Reactive runtime state + control functions
+ * @returns Reactive runtime state + control functions + imperative methods
+ *
+ * @example
+ * ```tsx
+ * // Direct files (fetched from any source by the host app)
+ * const runtime = useRuntime({ files: myFiles, entryCommand: 'node server.js' });
+ *
+ * // Later, push updated files from the host:
+ * await runtime.updateFiles(newFiles);
+ *
+ * // Or update a single file:
+ * await runtime.updateFile('server.js', newContent);
+ * ```
  */
 export function useRuntime(props: CodeSandboxProps) {
   const {
@@ -32,10 +93,19 @@ export function useRuntime(props: CodeSandboxProps) {
     onServerReady,
     onProgress,
     onError,
+    onSandboxError,
+    onFilesUpdated,
   } = props;
 
   const runtimeRef = useRef<NodepodRuntime | null>(null);
   const bootedRef = useRef(false);
+  /** Ref for the latest onSandboxError callback (avoids stale closures) */
+  const onSandboxErrorRef = useRef(onSandboxError);
+  onSandboxErrorRef.current = onSandboxError;
+
+  /** Ref for latest onFilesUpdated callback */
+  const onFilesUpdatedRef = useRef(onFilesUpdated);
+  onFilesUpdatedRef.current = onFilesUpdated;
 
   const [state, setState] = useState<RuntimeState>({
     status: "initializing",
@@ -43,18 +113,78 @@ export function useRuntime(props: CodeSandboxProps) {
     previewUrl: null,
     terminalOutput: [],
     files: {},
+    originalFiles: {},
+    fileChanges: {},
     error: null,
+    errors: [],
   });
 
   const [selectedFile, setSelectedFile] = useState<string | null>(null);
   const [openFiles, setOpenFiles] = useState<string[]>([]);
 
-  // Resolve files + entry command from props or template
+  // -------------------------------------------------------------------------
+  // Error handling — unified pipeline
+  // -------------------------------------------------------------------------
+
+  /**
+   * Handle a structured error from any source (runtime or browser).
+   *
+   * Appends to the errors array in state and forwards to onSandboxError.
+   * The runtime calls reportError for process errors; the Preview
+   * component calls handleBrowserError for iframe errors.
+   */
+  const handleSandboxError = useCallback((error: SandboxError) => {
+    setState((prev) => ({
+      ...prev,
+      errors: [...prev.errors, error],
+    }));
+    onSandboxErrorRef.current?.(error);
+  }, []);
+
+  /**
+   * Handle a browser error from the preview iframe.
+   *
+   * Called by the Preview component's onBrowserError callback.
+   * We enrich the error with source context from the runtime
+   * (if the file exists in our virtual FS) then record it.
+   */
+  const handleBrowserError = useCallback(
+    async (error: SandboxError) => {
+      const runtime = runtimeRef.current;
+      if (runtime) {
+        // reportError enriches with source context and records internally
+        await runtime.reportError(error);
+      }
+      // Also update React state
+      handleSandboxError(error);
+    },
+    [handleSandboxError],
+  );
+
+  // -------------------------------------------------------------------------
+  // Config resolution
+  // -------------------------------------------------------------------------
+
+  /**
+   * Resolve files + entry command from props or template.
+   */
   const resolvedConfig = useCallback(() => {
-    if (propFiles) {
+    if (propFiles && Object.keys(propFiles).length > 0) {
+      // Infer entry command from package.json if not provided
+      let entryCommand = propEntryCommand || "node server.js";
+      if (!propEntryCommand && propFiles["package.json"]) {
+        try {
+          const pkg = JSON.parse(propFiles["package.json"]);
+          if (pkg.scripts?.start) {
+            entryCommand = pkg.scripts.start;
+          }
+        } catch {
+          /* use default */
+        }
+      }
       return {
         files: propFiles,
-        entryCommand: propEntryCommand || "node server.js",
+        entryCommand,
         port: propPort || 3000,
       };
     }
@@ -70,131 +200,309 @@ export function useRuntime(props: CodeSandboxProps) {
       }
     }
 
-    // Default: empty project
-    return {
-      files: {},
-      entryCommand: propEntryCommand || "node server.js",
-      port: propPort || 3000,
-    };
+    // No files provided — return null (sandbox waits for updateFiles)
+    return null;
   }, [propFiles, template, propEntryCommand, propPort]);
 
-  // Boot the runtime on mount
-  useEffect(() => {
-    if (bootedRef.current) {
-      return;
-    }
-    bootedRef.current = true;
-
-    const config = resolvedConfig();
-    if (Object.keys(config.files).length === 0) {
-      return;
-    }
-
-    const runtime = new NodepodRuntime({
-      files: config.files,
-      entryCommand: config.entryCommand,
-      port: config.port,
-      env,
-    });
-
-    runtimeRef.current = runtime;
+  // -------------------------------------------------------------------------
+  // Boot helpers
+  // -------------------------------------------------------------------------
 
-    // Set initial files state + open the first file
-    setState((prev) => ({
-      ...prev,
-      files: config.files,
-    }));
+  /**
+   * Boot the runtime with a resolved file set.
+   */
+  const bootWithFiles = useCallback(
+    (files: FileMap, entryCommand: string, port: number) => {
+      const runtime = new NodepodRuntime({
+        files,
+        entryCommand,
+        port,
+        env,
+      });
 
-    const fileNames = Object.keys(config.files);
-    // Auto-select entry file or first file
-    const entryFile =
-      fileNames.find((f) => f === "server.js") ||
-      fileNames.find((f) => f === "index.js") ||
-      fileNames.find((f) => f.endsWith(".js")) ||
-      fileNames[0];
-
-    if (entryFile) {
-      setSelectedFile(entryFile);
-      setOpenFiles([entryFile]);
-    }
+      runtimeRef.current = runtime;
 
-    // Wire callbacks
-    runtime.setProgressCallback((progress: BootProgress) => {
+      // Set initial files state + open the first file
       setState((prev) => ({
         ...prev,
-        status: progress.stage,
-        progress,
-        previewUrl: runtime.getPreviewUrl(),
-        error: progress.stage === "error" ? progress.message : prev.error,
+        files,
       }));
-      onProgress?.(progress);
-      if (progress.stage === "error") {
-        onError?.(progress.message);
+
+      const fileNames = Object.keys(files);
+      const entryFile =
+        fileNames.find((f) => f === "server.js") ||
+        fileNames.find((f) => f === "index.js") ||
+        fileNames.find((f) => f.endsWith(".js")) ||
+        fileNames[0];
+
+      if (entryFile) {
+        setSelectedFile(entryFile);
+        setOpenFiles([entryFile]);
       }
-    });
 
-    runtime.setOutputCallback((line: string) => {
+      // Wire progress callback
+      runtime.setProgressCallback((progress: BootProgress) => {
+        setState((prev) => ({
+          ...prev,
+          status: progress.stage,
+          progress,
+          previewUrl: runtime.getPreviewUrl(),
+          error: progress.stage === "error" ? progress.message : prev.error,
+        }));
+        onProgress?.(progress);
+        if (progress.stage === "error") {
+          onError?.(progress.message);
+        }
+      });
+
+      // Wire terminal output callback
+      runtime.setOutputCallback((line: string) => {
+        setState((prev) => ({
+          ...prev,
+          terminalOutput: [...prev.terminalOutput, line],
+        }));
+      });
+
+      // Wire server ready callback
+      runtime.setServerReadyCallback((readyPort: number, url: string) => {
+        setState((prev) => ({
+          ...prev,
+          previewUrl: url,
+          status: "ready",
+        }));
+        onServerReady?.(readyPort, url);
+      });
+
+      // Wire structured error callback
+      runtime.setErrorCallback(handleSandboxError);
+
+      // Boot
+      runtime.boot().catch((err) => {
+        const msg = err instanceof Error ? err.message : String(err);
+        onError?.(msg);
+      });
+
+      return runtime;
+    },
+    [env, onProgress, onError, onServerReady, handleSandboxError],
+  );
+
+  // -------------------------------------------------------------------------
+  // Imperative file update methods
+  // -------------------------------------------------------------------------
+
+  /**
+   * Push a complete new file set into the sandbox.
+   *
+   * Diffs against current files, writes only changed files to Nodepod FS,
+   * and restarts the server if anything changed (unless restartServer=false).
+   *
+   * The previous file set becomes `originalFiles` for diff tracking.
+   *
+   * Called by the imperative handle's updateFiles() method.
+   * Also usable as the initial boot path when files arrive asynchronously
+   * (e.g., host fetches from GitHub/DB/S3, then calls updateFiles).
+   */
+  const updateFiles = useCallback(
+    async (newFiles: FileMap, options?: { restartServer?: boolean }) => {
+      const shouldRestart = options?.restartServer !== false;
+      const runtime = runtimeRef.current;
+
+      // If runtime hasn't booted yet, boot with these files
+      if (!runtime) {
+        if (bootedRef.current) {
+          console.warn(
+            DBG,
+            "updateFiles called but runtime is gone (already torn down)",
+          );
+          return;
+        }
+        bootedRef.current = true;
+
+        // Infer entry command from package.json
+        let entryCommand = propEntryCommand || "node server.js";
+        if (!propEntryCommand && newFiles["package.json"]) {
+          try {
+            const pkg = JSON.parse(newFiles["package.json"]);
+            if (pkg.scripts?.start) {
+              entryCommand = pkg.scripts.start;
+            }
+          } catch {
+            /* use default */
+          }
+        }
+        const port = propPort || 3000;
+
+        bootWithFiles(newFiles, entryCommand, port);
+        return;
+      }
+
+      // Runtime exists — diff and write changed files
+      const currentFiles = runtime.getCurrentFiles();
+      let changed = false;
+
+      for (const [path, content] of Object.entries(newFiles)) {
+        if (currentFiles[path] !== content) {
+          try {
+            await runtime.writeFile(path, content);
+            changed = true;
+            console.log(DBG, `updated file: ${path}`);
+          } catch (err) {
+            console.warn(DBG, `failed to write ${path}:`, err);
+          }
+        }
+      }
+
+      // Compute change status — "original" is what we had before this update
+      const fileChanges = computeFileChanges(currentFiles, newFiles);
+
+      // Update React state with new file set + diff info
       setState((prev) => ({
         ...prev,
-        terminalOutput: [...prev.terminalOutput, line],
+        originalFiles: currentFiles,
+        files: newFiles,
+        fileChanges,
       }));
-    });
 
-    runtime.setServerReadyCallback((port: number, url: string) => {
-      setState((prev) => ({
+      // Restart server if any files changed
+      if (changed && shouldRestart) {
+        console.log(
+          DBG,
+          `files changed — restarting server (${Object.keys(fileChanges).length} files differ)`,
+        );
+        try {
+          await runtime.restart();
+        } catch (err) {
+          console.error(DBG, "restart failed:", err);
+        }
+      }
+
+      // Notify host that files have been processed
+      onFilesUpdatedRef.current?.(fileChanges);
+    },
+    [propEntryCommand, propPort, bootWithFiles],
+  );
+
+  /**
+   * Push a single file update into the sandbox.
+   *
+   * Writes to Nodepod FS and updates React state. Does NOT restart
+   * the server — use restart() if needed, or updateFiles() for bulk
+   * updates with auto-restart.
+   *
+   * This is the same path as editor edits, but callable imperatively
+   * (e.g., when the agent modifies a single file).
+   */
+  const updateFile = useCallback(async (path: string, content: string) => {
+    const runtime = runtimeRef.current;
+    if (!runtime) {
+      console.warn(
+        DBG,
+        "updateFile called but runtime not ready. Use updateFiles() for initial load.",
+      );
+      return;
+    }
+
+    try {
+      await runtime.writeFile(path, content);
+    } catch (err) {
+      console.error(`Failed to write file ${path}:`, err);
+    }
+
+    setState((prev) => {
+      const newFiles = { ...prev.files, [path]: content };
+      const newChanges = { ...prev.fileChanges };
+      if (!(path in prev.originalFiles)) {
+        newChanges[path] = "new";
+      } else if (prev.originalFiles[path] !== content) {
+        newChanges[path] = "modified";
+      } else {
+        // Reverted back to original — remove from changes
+        delete newChanges[path];
+      }
+      return {
         ...prev,
-        previewUrl: url,
-        status: "ready",
-      }));
-      onServerReady?.(port, url);
+        files: newFiles,
+        fileChanges: newChanges,
+      };
     });
+  }, []);
 
-    // Boot
-    runtime.boot().catch((err) => {
-      const msg = err instanceof Error ? err.message : String(err);
-      onError?.(msg);
-    });
+  // -------------------------------------------------------------------------
+  // Boot on mount
+  // -------------------------------------------------------------------------
+
+  useEffect(() => {
+    if (bootedRef.current) return;
+
+    const config = resolvedConfig();
+
+    if (config) {
+      // Direct files or template — boot immediately
+      bootedRef.current = true;
+      if (Object.keys(config.files).length === 0) return;
+      bootWithFiles(config.files, config.entryCommand, config.port);
+    }
+    // If no config (no files, no template), sandbox waits for
+    // updateFiles() to be called via the imperative handle.
 
     // Cleanup on unmount
     return () => {
-      runtime.teardown();
+      runtimeRef.current?.teardown();
       runtimeRef.current = null;
     };
   }, []); // eslint-disable-line react-hooks/exhaustive-deps
 
-  // File change handler
+  // -------------------------------------------------------------------------
+  // File editing (from the CodeEditor UI)
+  // -------------------------------------------------------------------------
+
   const handleFileChange = useCallback(
     async (path: string, content: string) => {
       const runtime = runtimeRef.current;
-      if (!runtime) {
-        return;
-      }
+      if (!runtime) return;
 
-      // Write to Nodepod FS
       try {
         await runtime.writeFile(path, content);
       } catch (err) {
         console.error(`Failed to write file ${path}:`, err);
       }
 
-      // Update state
-      setState((prev) => ({
-        ...prev,
-        files: { ...prev.files, [path]: content },
-      }));
+      setState((prev) => {
+        const newFiles = { ...prev.files, [path]: content };
+        // Recompute change status for this file against originalFiles.
+        // Only update this file's status — don't recompute everything.
+        const newChanges = { ...prev.fileChanges };
+        if (!(path in prev.originalFiles)) {
+          newChanges[path] = "new";
+        } else if (prev.originalFiles[path] !== content) {
+          newChanges[path] = "modified";
+        } else {
+          // Reverted back to original — remove from changes
+          delete newChanges[path];
+        }
+
+        return {
+          ...prev,
+          files: newFiles,
+          fileChanges: newChanges,
+        };
+      });
 
       onFileChange?.(path, content);
     },
     [onFileChange],
   );
 
-  // Select a file
+  // -------------------------------------------------------------------------
+  // File selection
+  // -------------------------------------------------------------------------
+
   const handleSelectFile = useCallback((path: string) => {
     setSelectedFile(path);
     setOpenFiles((prev) => (prev.includes(path) ? prev : [...prev, path]));
   }, []);
 
-  // Close a file tab
   const handleCloseFile = useCallback(
     (path: string) => {
       setOpenFiles((prev) => {
@@ -208,20 +516,41 @@ export function useRuntime(props: CodeSandboxProps) {
     [selectedFile],
   );
 
-  // Restart the server
+  // -------------------------------------------------------------------------
+  // Server control
+  // -------------------------------------------------------------------------
+
   const restart = useCallback(async () => {
     const runtime = runtimeRef.current;
-    if (!runtime) {
-      return;
-    }
+    if (!runtime) return;
     await runtime.restart();
   }, []);
 
-  // Get changed files for git operations
+  // -------------------------------------------------------------------------
+  // State readers (for imperative handle)
+  // -------------------------------------------------------------------------
+
+  const getFiles = useCallback((): FileMap => {
+    return runtimeRef.current?.getCurrentFiles() ?? {};
+  }, []);
+
   const getChangedFiles = useCallback((): FileMap => {
     return runtimeRef.current?.getChangedFiles() ?? {};
   }, []);
 
+  const getFileChanges = useCallback((): Record<string, FileChangeStatus> => {
+    // Read from React state since it's the source of truth for changes
+    return state.fileChanges;
+  }, [state.fileChanges]);
+
+  const getErrors = useCallback((): SandboxError[] => {
+    return state.errors;
+  }, [state.errors]);
+
+  const getState = useCallback((): RuntimeState => {
+    return state;
+  }, [state]);
+
   return {
     state,
     selectedFile,
@@ -229,8 +558,16 @@ export function useRuntime(props: CodeSandboxProps) {
     handleFileChange,
     handleSelectFile,
     handleCloseFile,
+    handleBrowserError,
     restart,
+    // Imperative methods (exposed via handle)
+    updateFiles,
+    updateFile,
+    getFiles,
     getChangedFiles,
+    getFileChanges,
+    getErrors,
+    getState,
     runtime: runtimeRef,
   };
 }

package/src/index.ts

@@ -31,6 +31,9 @@ export { getTemplate, listTemplates } from "./templates";
 export type {
   FileMap,
   FileNode,
+  FileChangeStatus,
+  SandboxError,
+  SandboxErrorCategory,
   BootStage,
   BootProgress,
   RuntimeConfig,
@@ -40,6 +43,7 @@ export type {
   GitPRRequest,
   GitPRResult,
   CodeSandboxProps,
+  CodeSandboxHandle,
   FileTreeProps,
   CodeEditorProps,
   TerminalProps,