@illuma-ai/code-sandbox 1.0.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.
  */
 
 // ---------------------------------------------------------------------------
@@ -20,6 +20,78 @@ export interface FileNode {
   children?: FileNode[];
 }
 
+/**
+ * Change status for a file relative to the baseline (original) snapshot.
+ *
+ * - `new`: File exists in current but not in original
+ * - `modified`: File exists in both but content differs
+ * - `deleted`: File exists in original but not in current
+ * - `unchanged`: File content is identical
+ */
+export type FileChangeStatus = "new" | "modified" | "deleted" | "unchanged";
+
+// ---------------------------------------------------------------------------
+// Errors (structured error types for AI agent consumption)
+// ---------------------------------------------------------------------------
+
+/**
+ * Categories of errors that can occur in the sandbox.
+ *
+ * - `process-stderr`: Output written to stderr by the Node.js process
+ * - `process-exit`: Process exited with a non-zero code
+ * - `runtime-exception`: Uncaught exception in the Node.js runtime (Nodepod)
+ * - `browser-error`: JavaScript error in the preview iframe (window.onerror)
+ * - `browser-unhandled-rejection`: Unhandled promise rejection in the iframe
+ * - `browser-console-error`: console.error() calls in the iframe
+ * - `compilation`: Syntax/import errors detected at module load time
+ * - `network`: Failed HTTP requests from the preview (fetch/XHR errors)
+ * - `boot`: Error during Nodepod boot, file writing, or dependency install
+ */
+export type SandboxErrorCategory =
+  | "process-stderr"
+  | "process-exit"
+  | "runtime-exception"
+  | "browser-error"
+  | "browser-unhandled-rejection"
+  | "browser-console-error"
+  | "compilation"
+  | "network"
+  | "boot";
+
+/**
+ * A structured error emitted by the sandbox.
+ *
+ * Designed for AI agent consumption — includes enough context for the
+ * agent to construct a targeted fix prompt (file path, line number,
+ * surrounding code, stack trace).
+ *
+ * @see Ranger's auto-fix: client/src/components/Artifacts/Artifacts.tsx
+ */
+export interface SandboxError {
+  /** Unique ID for deduplication */
+  id: string;
+  /** Error category — determines how the agent should interpret it */
+  category: SandboxErrorCategory;
+  /** Human-readable error message (the "what") */
+  message: string;
+  /** Full stack trace if available */
+  stack?: string;
+  /** File path where the error occurred (relative to workdir) */
+  filePath?: string;
+  /** Line number in the file (1-indexed) */
+  line?: number;
+  /** Column number in the file (1-indexed) */
+  column?: number;
+  /** ISO 8601 timestamp */
+  timestamp: string;
+  /**
+   * Surrounding source code lines for context.
+   * Format: "lineNum: content" per line (e.g., "42: const x = foo();")
+   * Typically ~10 lines centered on the error line.
+   */
+  sourceContext?: string;
+}
+
 // ---------------------------------------------------------------------------
 // Runtime (Nodepod lifecycle)
 // ---------------------------------------------------------------------------
@@ -64,12 +136,32 @@ export interface RuntimeState {
   terminalOutput: string[];
   /** Current files in the virtual FS (may differ from original after edits) */
   files: FileMap;
+  /**
+   * Baseline file snapshot — the files as they were before the latest
+   * 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;
+  /**
+   * Per-file change status relative to originalFiles.
+   *
+   * Only includes files that have a non-"unchanged" status.
+   * Missing keys should be treated as "unchanged".
+   */
+  fileChanges: Record<string, FileChangeStatus>;
   /** Error message if status is 'error' */
   error: string | null;
+  /**
+   * All structured errors collected during this session.
+   * New errors are appended — the array grows monotonically.
+   * Use `errors[errors.length - 1]` to get the latest.
+   */
+  errors: SandboxError[];
 }
 
 // ---------------------------------------------------------------------------
-// Git (GitHub API integration)
+// Git (GitHub API integration — utility, NOT used internally by sandbox)
 // ---------------------------------------------------------------------------
 
 export interface GitHubRepo {
@@ -105,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) */
@@ -126,14 +319,30 @@ 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;
-  /** Fires on errors */
+  /** Fires on errors (legacy — simple string message) */
   onError?: (error: string) => void;
+  /**
+   * Fires when a structured error is detected.
+   *
+   * This is the primary error channel for AI agent integration.
+   * Errors include file path, line number, source context, and category
+   * so the agent can construct a targeted fix prompt.
+   *
+   * 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 */
@@ -146,6 +355,8 @@ export interface FileTreeProps {
   files: FileNode[];
   selectedFile: string | null;
   onSelectFile: (path: string) => void;
+  /** Per-file change status for visual indicators (colored dots) */
+  fileChanges?: Record<string, FileChangeStatus>;
   onCreateFile?: (path: string) => void;
   onCreateFolder?: (path: string) => void;
   onDeleteFile?: (path: string) => void;
@@ -154,6 +365,10 @@ export interface FileTreeProps {
 
 export interface CodeEditorProps {
   files: FileMap;
+  /** Baseline files for diff comparison (empty = no diff available) */
+  originalFiles: FileMap;
+  /** Per-file change status for tab indicators */
+  fileChanges: Record<string, FileChangeStatus>;
   activeFile: string | null;
   openFiles: string[];
   onSelectFile: (path: string) => void;
@@ -171,6 +386,8 @@ export interface PreviewProps {
   url: string | null;
   className?: string;
   onRefresh?: () => void;
+  /** Called when a JavaScript error occurs inside the preview iframe */
+  onBrowserError?: (error: SandboxError) => void;
 }
 
 export interface BootOverlayProps {