@illuma-ai/code-sandbox 1.0.0 → 1.2.0

package/dist/services/runtime.d.ts

@@ -7,13 +7,15 @@
  * It is framework-agnostic (no React) — consumed by the useRuntime hook.
  */
 import { Nodepod } from "@illuma-ai/nodepod";
-import type { BootProgress, BootStage, FileMap, RuntimeConfig } from "../types";
+import type { BootProgress, BootStage, FileMap, RuntimeConfig, SandboxError } from "../types";
 /** Callback type for progress updates */
 type ProgressCallback = (progress: BootProgress) => void;
 /** Callback type for terminal output lines */
 type OutputCallback = (line: string) => void;
 /** Callback type for server ready */
 type ServerReadyCallback = (port: number, url: string) => void;
+/** Callback type for structured errors */
+type ErrorCallback = (error: SandboxError) => void;
 /**
  * Manages the Nodepod runtime lifecycle.
  *
@@ -35,9 +37,12 @@ export declare class NodepodRuntime {
     private status;
     private error;
     private previewUrl;
+    private errors;
+    private errorIdCounter;
     private onProgress;
     private onOutput;
     private onServerReady;
+    private onSandboxError;
     constructor(config: RuntimeConfig);
     /** Register a progress callback */
     setProgressCallback(cb: ProgressCallback): void;
@@ -45,6 +50,8 @@ export declare class NodepodRuntime {
     setOutputCallback(cb: OutputCallback): void;
     /** Register a server ready callback */
     setServerReadyCallback(cb: ServerReadyCallback): void;
+    /** Register a structured error callback */
+    setErrorCallback(cb: ErrorCallback): void;
     /** Get the current preview URL (null if server not ready) */
     getPreviewUrl(): string | null;
     /** Get current status */
@@ -59,6 +66,17 @@ export declare class NodepodRuntime {
     getChangedFiles(): FileMap;
     /** Get the error message if status is 'error' */
     getError(): string | null;
+    /** Get all structured errors collected during this session */
+    getErrors(): SandboxError[];
+    /**
+     * Report an external error (e.g., from the preview iframe).
+     *
+     * This is the public entry point for errors that originate outside
+     * the runtime — browser console errors, unhandled rejections, etc.
+     * The runtime enriches them with source context from the virtual FS
+     * and emits them via the onSandboxError callback.
+     */
+    reportError(error: SandboxError): Promise<void>;
     /**
      * Boot the runtime: initialize Nodepod → write files → install → start server.
      *
@@ -115,5 +133,44 @@ export declare class NodepodRuntime {
     private emitProgress;
     /** Append a line to terminal output */
     private appendOutput;
+    /** Generate a unique error ID */
+    private nextErrorId;
+    /**
+     * Create and record a structured error from a process or boot event.
+     *
+     * Parses the error message to extract file path and line number when
+     * possible, then enriches with surrounding source context.
+     */
+    private emitError;
+    /**
+     * Filter out common non-error stderr output.
+     *
+     * Many Node.js tools write informational messages to stderr
+     * (deprecation warnings, experimental feature notices, etc.).
+     * We don't want to flood the agent with these.
+     */
+    private isStderrNoise;
+    /**
+     * Parse file path and line/column from common error message formats.
+     *
+     * Handles:
+     * - Node.js stack frames: "at func (/app/file.js:12:5)"
+     * - Direct references: "/app/file.js:12:5"
+     * - SyntaxError: "/app/file.js: Unexpected token (12:5)"
+     */
+    private parseErrorLocation;
+    /**
+     * Get surrounding source code lines from the virtual filesystem.
+     *
+     * Returns ~10 lines centered on the target line, formatted as
+     * "lineNum: content" for each line. This gives the AI agent enough
+     * context to construct a surgical fix.
+     */
+    private getSourceContext;
+    /**
+     * Format source code lines centered on a target line.
+     * Output: "lineNum: content\n" for each line in the window.
+     */
+    private formatSourceContext;
 }
 export {};

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>;
@@ -13,6 +13,62 @@ export interface FileNode {
     type: "file" | "directory";
     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";
+/**
+ * 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;
+}
 /** Boot stages shown during the loading animation */
 export type BootStage = "initializing" | "writing-files" | "installing" | "starting" | "ready" | "error";
 export interface BootProgress {
@@ -44,8 +100,28 @@ 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[];
 }
 export interface GitHubRepo {
     owner: string;
@@ -76,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) */
@@ -91,14 +255,30 @@ 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;
-    /** 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;
     /** CSS class name for the root element */
     className?: string;
     /** Height of the sandbox (default: '100vh') */
@@ -108,6 +288,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;
@@ -115,6 +297,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;
@@ -130,6 +316,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 {
     progress: BootProgress;

package/package.json

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

package/src/components/CodeEditor.tsx

@@ -1,27 +1,37 @@
 /**
- * CodeEditor — Monaco editor with file tabs.
+ * CodeEditor — Monaco editor with file tabs, diff mode, and change indicators.
  *
- * Uses @monaco-editor/react for the editor and renders a tab bar
- * of open files. Supports dark theme that matches the sandbox.
+ * Uses @monaco-editor/react for both the regular editor and diff editor.
+ * Renders a tab bar of open files with change status indicators:
+ * - Green dot: new file
+ * - Orange dot: modified file
+ * - Red dot: deleted file (shown as read-only)
+ *
+ * When diff mode is active, displays Monaco's side-by-side DiffEditor
+ * comparing the original file content (left) with the current content (right).
+ *
+ * @see @monaco-editor/react DiffEditor: https://github.com/suren-atoyan/monaco-react
  */
 
-import React, { useCallback, useMemo } from "react";
-import type { CodeEditorProps } from "../types";
+import React, { useCallback, useMemo, useState } from "react";
+import type { CodeEditorProps, FileChangeStatus } from "../types";
 
 // Lazy import Monaco to keep the bundle splittable
 let MonacoEditor: React.ComponentType<any> | null = null;
+let MonacoDiffEditor: React.ComponentType<any> | null = null;
 let monacoLoadPromise: Promise<void> | null = null;
 
 /**
- * Load Monaco editor dynamically.
- * Returns the Editor component from @monaco-editor/react.
+ * Load Monaco editor (regular + diff) dynamically.
+ * Returns both Editor and DiffEditor from @monaco-editor/react.
  */
 function loadMonaco(): Promise<void> {
-  if (MonacoEditor) return Promise.resolve();
+  if (MonacoEditor && MonacoDiffEditor) return Promise.resolve();
   if (monacoLoadPromise) return monacoLoadPromise;
 
   monacoLoadPromise = import("@monaco-editor/react").then((mod) => {
     MonacoEditor = mod.default || mod.Editor;
+    MonacoDiffEditor = mod.DiffEditor;
   });
 
   return monacoLoadPromise;
@@ -59,11 +69,34 @@ function getLanguage(path: string): string {
   return langMap[ext] || "plaintext";
 }
 
+/** Color for each file change status indicator dot */
+const STATUS_COLORS: Record<FileChangeStatus, string> = {
+  new: "#4ade80", // green-400
+  modified: "#fb923c", // orange-400
+  deleted: "#f87171", // red-400
+  unchanged: "transparent",
+};
+
+/** Tooltip for each file change status */
+const STATUS_LABELS: Record<FileChangeStatus, string> = {
+  new: "New file",
+  modified: "Modified",
+  deleted: "Deleted",
+  unchanged: "",
+};
+
 /**
- * CodeEditor component — Monaco editor with file tabs.
+ * CodeEditor component — Monaco editor with file tabs, diff view, and
+ * change status indicators.
+ *
+ * When `originalFiles` has content for the active file (meaning a prior
+ * version exists), a "Diff" toggle button appears in the tab bar. Clicking
+ * it switches to Monaco's DiffEditor showing the old (left) vs new (right).
  */
 export function CodeEditor({
   files,
+  originalFiles,
+  fileChanges,
   activeFile,
   openFiles,
   onSelectFile,
@@ -72,6 +105,7 @@ export function CodeEditor({
   readOnly = false,
 }: CodeEditorProps) {
   const [loaded, setLoaded] = React.useState(!!MonacoEditor);
+  const [diffMode, setDiffMode] = useState(false);
 
   // Load Monaco on mount
   React.useEffect(() => {
@@ -81,8 +115,29 @@ export function CodeEditor({
   }, []);
 
   const activeContent = activeFile ? files[activeFile] || "" : "";
+  const activeOriginalContent = activeFile
+    ? (originalFiles[activeFile] ?? "")
+    : "";
   const language = activeFile ? getLanguage(activeFile) : "plaintext";
 
+  /**
+   * Whether the active file has a diff available.
+   * A diff is available when:
+   * - The file is marked as "modified" (content differs from original), OR
+   * - The file is marked as "new" (no original — diff shows empty left side)
+   */
+  const hasDiff = activeFile
+    ? fileChanges[activeFile] === "modified" ||
+      fileChanges[activeFile] === "new"
+    : false;
+
+  // Auto-disable diff mode when switching to a file with no diff
+  React.useEffect(() => {
+    if (!hasDiff && diffMode) {
+      setDiffMode(false);
+    }
+  }, [hasDiff, diffMode, activeFile]);
+
   const handleEditorChange = useCallback(
     (value: string | undefined) => {
       if (activeFile && value !== undefined) {
@@ -92,6 +147,23 @@ export function CodeEditor({
     [activeFile, onFileChange],
   );
 
+  /**
+   * Handler for Monaco DiffEditor's modified content changes.
+   * The DiffEditor fires `onMount` with the editor instance — we
+   * listen to the modified editor's onDidChangeModelContent event.
+   */
+  const handleDiffEditorMount = useCallback(
+    (editor: any) => {
+      if (!editor || !activeFile) return;
+      const modifiedEditor = editor.getModifiedEditor();
+      modifiedEditor.onDidChangeModelContent(() => {
+        const value = modifiedEditor.getValue();
+        onFileChange(activeFile, value);
+      });
+    },
+    [activeFile, onFileChange],
+  );
+
   return (
     <div className="flex flex-col h-full bg-sb-editor">
       {/* Tab bar */}
@@ -99,6 +171,8 @@ export function CodeEditor({
         {openFiles.map((path) => {
           const fileName = path.split("/").pop() || path;
           const isActive = path === activeFile;
+          const changeStatus: FileChangeStatus =
+            fileChanges[path] || "unchanged";
 
           return (
             <div
@@ -111,6 +185,14 @@ export function CodeEditor({
                 }`}
               onClick={() => onSelectFile(path)}
             >
+              {/* Change status indicator dot */}
+              {changeStatus !== "unchanged" && (
+                <span
+                  className="w-2 h-2 rounded-full shrink-0"
+                  style={{ backgroundColor: STATUS_COLORS[changeStatus] }}
+                  title={STATUS_LABELS[changeStatus]}
+                />
+              )}
               <span className="truncate max-w-[120px]">{fileName}</span>
               <button
                 className="opacity-0 group-hover:opacity-100 hover:text-sb-text-active ml-1 text-[10px]"
@@ -125,9 +207,27 @@ export function CodeEditor({
             </div>
           );
         })}
+
+        {/* Spacer */}
+        <div className="flex-1" />
+
+        {/* Diff toggle button — only shown when a diff is available */}
+        {hasDiff && (
+          <button
+            className={`shrink-0 px-2 py-1 mr-1 text-[10px] font-medium rounded transition-colors ${
+              diffMode
+                ? "bg-sb-accent text-white"
+                : "text-sb-text-muted hover:text-sb-text-active hover:bg-sb-bg-hover"
+            }`}
+            onClick={() => setDiffMode((prev) => !prev)}
+            title={diffMode ? "Switch to editor" : "Show diff view"}
+          >
+            {diffMode ? "Editor" : "Diff"}
+          </button>
+        )}
       </div>
 
-      {/* Editor */}
+      {/* Editor / DiffEditor / placeholder */}
       <div className="flex-1 overflow-hidden">
         {!activeFile && (
           <div className="flex items-center justify-center h-full text-sb-text-muted text-sm">
@@ -135,7 +235,37 @@ export function CodeEditor({
           </div>
         )}
 
-        {activeFile && loaded && MonacoEditor && (
+        {/* Diff mode: Monaco DiffEditor (side-by-side) */}
+        {activeFile && loaded && diffMode && MonacoDiffEditor && (
+          <MonacoDiffEditor
+            height="100%"
+            language={language}
+            original={activeOriginalContent}
+            modified={activeContent}
+            theme="vs-dark"
+            onMount={handleDiffEditorMount}
+            options={{
+              readOnly,
+              minimap: { enabled: false },
+              fontSize: 13,
+              wordWrap: "on",
+              scrollBeyondLastLine: false,
+              padding: { top: 8 },
+              renderWhitespace: "selection",
+              automaticLayout: true,
+              tabSize: 2,
+              // DiffEditor-specific options
+              renderSideBySide: true,
+              enableSplitViewResizing: true,
+              renderIndicators: true,
+              renderMarginRevertIcon: false,
+              originalEditable: false,
+            }}
+          />
+        )}
+
+        {/* Regular mode: Monaco Editor */}
+        {activeFile && loaded && !diffMode && MonacoEditor && (
           <MonacoEditor
             height="100%"
             language={language}