@illuma-ai/code-sandbox 1.1.0 → 1.2.0

package/dist/types.d.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.
  */
 /** A flat map of file paths to their string contents */
 export type FileMap = Record<string, string>;
@@ -102,11 +102,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;
     /**
@@ -154,13 +152,101 @@ export interface GitPRResult {
     url: string;
     branch: string;
 }
+/**
+ * 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;
+}
+/**
+ * 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) */
@@ -169,9 +255,9 @@ export interface CodeSandboxProps {
     port?: number;
     /** Environment variables */
     env?: Record<string, string>;
-    /** 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;
@@ -187,6 +273,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;
     /** CSS class name for the root element */
     className?: string;
     /** Height of the sandbox (default: '100vh') */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@illuma-ai/code-sandbox",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",
   "author": "Illuma AI (https://github.com/illuma-ai)",

package/src/components/Workbench.tsx

@@ -20,6 +20,8 @@ import React, {
   useEffect,
   useCallback,
   useRef,
+  useImperativeHandle,
+  forwardRef,
 } from "react";
 import { Allotment } from "allotment";
 import { motion, AnimatePresence } from "framer-motion";
@@ -32,7 +34,11 @@ import { Preview } from "./Preview";
 import { BootOverlay } from "./BootOverlay";
 import { ViewSlider, type WorkbenchView } from "./ViewSlider";
 import { useRuntime } from "../hooks/useRuntime";
-import type { CodeSandboxProps, FileChangeStatus } from "../types";
+import type {
+  CodeSandboxProps,
+  CodeSandboxHandle,
+  FileChangeStatus,
+} from "../types";
 
 /** Transition for view crossfade */
 const VIEW_TRANSITION = {
@@ -50,102 +56,142 @@ const VIEW_TRANSITION = {
  * A compact toolbar row contains the view toggle and (in preview mode)
  * a URL bar with refresh button.
  */
-export function CodeSandbox(props: CodeSandboxProps) {
-  const { className = "", height = "100vh", port = 3000 } = props;
+export const CodeSandbox = forwardRef<CodeSandboxHandle, CodeSandboxProps>(
+  function CodeSandbox(props, ref) {
+    const { className = "", height = "100vh", port = 3000 } = props;
 
-  const {
-    state,
-    selectedFile,
-    openFiles,
-    handleFileChange,
-    handleSelectFile,
-    handleCloseFile,
-    handleBrowserError,
-    restart,
-  } = useRuntime(props);
+    const runtime = useRuntime(props);
+    const {
+      state,
+      selectedFile,
+      openFiles,
+      handleFileChange,
+      handleSelectFile,
+      handleCloseFile,
+      handleBrowserError,
+      restart,
+      updateFiles,
+      updateFile,
+      getFiles,
+      getChangedFiles,
+      getFileChanges,
+      getErrors,
+      getState,
+    } = runtime;
 
-  const fileTree = useMemo(() => buildFileTree(state.files), [state.files]);
-  const isBooting = state.status !== "ready" && state.status !== "error";
+    // Expose imperative handle to parent via ref
+    useImperativeHandle(
+      ref,
+      () => ({
+        updateFiles,
+        updateFile,
+        restart,
+        getFiles,
+        getChangedFiles,
+        getFileChanges,
+        getErrors,
+        getState,
+      }),
+      [
+        updateFiles,
+        updateFile,
+        restart,
+        getFiles,
+        getChangedFiles,
+        getFileChanges,
+        getErrors,
+        getState,
+      ],
+    );
 
-  // Active view: code or preview
-  const [activeView, setActiveView] = useState<WorkbenchView>("code");
+    const fileTree = useMemo(() => buildFileTree(state.files), [state.files]);
+    const isBooting = state.status !== "ready" && state.status !== "error";
 
-  // Auto-switch to preview when server becomes ready
-  const hasPreview = !!state.previewUrl;
-  useEffect(() => {
-    if (hasPreview) {
-      setActiveView("preview");
-    }
-  }, [hasPreview]);
+    // Active view: code or preview
+    const [activeView, setActiveView] = useState<WorkbenchView>("code");
 
-  // Switch to code view when a file is selected from the tree
-  const onFileSelect = useCallback(
-    (path: string) => {
-      handleSelectFile(path);
-      setActiveView("code");
-    },
-    [handleSelectFile],
-  );
+    // Auto-switch to preview when server becomes ready
+    const hasPreview = !!state.previewUrl;
+    useEffect(() => {
+      if (hasPreview) {
+        setActiveView("preview");
+      }
+    }, [hasPreview]);
 
-  return (
-    <div
-      className={`sb-root relative w-full bg-sb-bg text-sb-text overflow-hidden flex flex-col ${className}`}
-      style={{ height }}
-    >
-      {/* Boot overlay */}
-      {isBooting && <BootOverlay progress={state.progress} />}
+    // Switch to code view when a file is selected from the tree
+    const onFileSelect = useCallback(
+      (path: string) => {
+        handleSelectFile(path);
+        setActiveView("code");
+      },
+      [handleSelectFile],
+    );
 
-      {/* Toolbar — compact row with view toggle + URL bar */}
-      <Toolbar
-        activeView={activeView}
-        onViewChange={setActiveView}
-        previewUrl={state.previewUrl}
-        port={port}
-        onRefresh={restart}
-      />
+    return (
+      <div
+        className={`sb-root relative w-full bg-sb-bg text-sb-text overflow-hidden flex flex-col ${className}`}
+        style={{ height }}
+      >
+        {/* Boot overlay */}
+        {isBooting && <BootOverlay progress={state.progress} />}
 
-      {/* Views — full width, toggled */}
-      <div className="flex-1 relative overflow-hidden min-h-0">
-        {/* Code view */}
-        <motion.div
-          className="absolute inset-0"
-          initial={false}
-          animate={{
-            opacity: activeView === "code" ? 1 : 0,
-            pointerEvents: activeView === "code" ? "auto" : "none",
-          }}
-          transition={{ duration: 0.15 }}
-        >
-          <CodeView
-            fileTree={fileTree}
-            files={state.files}
-            originalFiles={state.originalFiles}
-            fileChanges={state.fileChanges}
-            selectedFile={selectedFile}
-            openFiles={openFiles}
-            terminalOutput={state.terminalOutput}
-            onSelectFile={onFileSelect}
-            onCloseFile={handleCloseFile}
-            onFileChange={handleFileChange}
-          />
-        </motion.div>
+        {/* Toolbar — compact row with view toggle + URL bar */}
+        <Toolbar
+          activeView={activeView}
+          onViewChange={setActiveView}
+          previewUrl={state.previewUrl}
+          port={port}
+          onRefresh={restart}
+        />
 
-        {/* Preview view */}
-        <motion.div
-          className="absolute inset-0"
-          initial={false}
-          animate={{
-            opacity: activeView === "preview" ? 1 : 0,
-            pointerEvents: activeView === "preview" ? "auto" : "none",
-          }}
-          transition={{ duration: 0.15 }}
-        >
-          <Preview url={state.previewUrl} onBrowserError={handleBrowserError} />
-        </motion.div>
+        {/* Views — full width, toggled */}
+        <div className="flex-1 relative overflow-hidden min-h-0">
+          {/* Code view */}
+          <motion.div
+            className="absolute inset-0"
+            initial={false}
+            animate={{
+              opacity: activeView === "code" ? 1 : 0,
+              pointerEvents: activeView === "code" ? "auto" : "none",
+            }}
+            transition={{ duration: 0.15 }}
+          >
+            <CodeView
+              fileTree={fileTree}
+              files={state.files}
+              originalFiles={state.originalFiles}
+              fileChanges={state.fileChanges}
+              selectedFile={selectedFile}
+              openFiles={openFiles}
+              terminalOutput={state.terminalOutput}
+              onSelectFile={onFileSelect}
+              onCloseFile={handleCloseFile}
+              onFileChange={handleFileChange}
+            />
+          </motion.div>
+
+          {/* Preview view */}
+          <motion.div
+            className="absolute inset-0"
+            initial={false}
+            animate={{
+              opacity: activeView === "preview" ? 1 : 0,
+              pointerEvents: activeView === "preview" ? "auto" : "none",
+            }}
+            transition={{ duration: 0.15 }}
+          >
+            <Preview
+              url={state.previewUrl}
+              onBrowserError={handleBrowserError}
+            />
+          </motion.div>
+        </div>
       </div>
-    </div>
-  );
-}
+    );
+  },
+);
+
+CodeSandbox.displayName = "CodeSandbox";
 
 // ---------------------------------------------------------------------------
 // Toolbar