@illuma-ai/code-sandbox 1.0.0 → 1.1.0

package/src/types.ts

@@ -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,8 +136,30 @@ 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 (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.).
+   */
+  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[];
 }
 
 // ---------------------------------------------------------------------------
@@ -132,8 +226,18 @@ export interface CodeSandboxProps {
   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;
 
   // Layout
   /** CSS class name for the root element */
@@ -146,6 +250,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 +260,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 +281,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 {