@illuma-ai/code-sandbox 1.0.0 → 1.1.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

@@ -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,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[];
 }
 export interface GitHubRepo {
     owner: string;
@@ -97,8 +175,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;
     /** CSS class name for the root element */
     className?: string;
     /** Height of the sandbox (default: '100vh') */
@@ -108,6 +196,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 +205,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 +224,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.1.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}

package/src/components/FileTree.tsx

@@ -7,7 +7,28 @@
  */
 
 import React, { useState } from "react";
-import type { FileMap, FileNode, FileTreeProps } from "../types";
+import type {
+  FileMap,
+  FileNode,
+  FileTreeProps,
+  FileChangeStatus,
+} from "../types";
+
+/** 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",
+};
+
+/** Short label for each file change status (one character) */
+const STATUS_LETTERS: Record<FileChangeStatus, string> = {
+  new: "N",
+  modified: "M",
+  deleted: "D",
+  unchanged: "",
+};
 
 /**
  * Build a tree structure from a flat FileMap.
@@ -201,8 +222,14 @@ function FileIcon({ name }: { name: string }) {
 
 /**
  * FileTree component — renders a collapsible tree of files and folders.
+ * Shows change status indicators (N/M/D) next to modified files.
  */
-export function FileTree({ files, selectedFile, onSelectFile }: FileTreeProps) {
+export function FileTree({
+  files,
+  selectedFile,
+  onSelectFile,
+  fileChanges,
+}: FileTreeProps) {
   return (
     <div className="h-full overflow-auto bg-sb-sidebar text-sm select-none">
       <div className="px-3 py-2 text-[11px] font-semibold text-sb-text-muted uppercase tracking-wider border-b border-sb-border">
@@ -216,6 +243,7 @@ export function FileTree({ files, selectedFile, onSelectFile }: FileTreeProps) {
             depth={0}
             selectedFile={selectedFile}
             onSelectFile={onSelectFile}
+            fileChanges={fileChanges}
           />
         ))}
       </div>
@@ -229,18 +257,36 @@ function TreeNode({
   depth,
   selectedFile,
   onSelectFile,
+  fileChanges,
 }: {
   node: FileNode;
   depth: number;
   selectedFile: string | null;
   onSelectFile: (path: string) => void;
+  fileChanges?: Record<string, FileChangeStatus>;
 }) {
   const [expanded, setExpanded] = useState(depth < 2);
 
   const isSelected = node.path === selectedFile;
   const paddingLeft = 8 + depth * 16;
+  const changeStatus: FileChangeStatus =
+    fileChanges?.[node.path] ?? "unchanged";
 
   if (node.type === "directory") {
+    // Check if any child has changes (to show a subtle indicator on folders)
+    const hasChangedChild =
+      fileChanges &&
+      node.children?.some((c) => {
+        if (fileChanges[c.path]) return true;
+        // For directories, check recursively by prefix
+        if (c.type === "directory") {
+          return Object.keys(fileChanges).some(
+            (p) => p.startsWith(c.path + "/") && fileChanges[p] !== "unchanged",
+          );
+        }
+        return false;
+      });
+
     return (
       <div>
         <button
@@ -252,7 +298,13 @@ function TreeNode({
         >
           <ChevronIcon expanded={expanded} />
           <FolderIcon open={expanded} />
-          <span className="truncate ml-0.5">{node.name}</span>
+          <span className="truncate ml-0.5 flex-1">{node.name}</span>
+          {hasChangedChild && (
+            <span
+              className="w-1.5 h-1.5 rounded-full shrink-0 mr-2"
+              style={{ backgroundColor: "#fb923c" }}
+            />
+          )}
         </button>
         {expanded && node.children && (
           <div>
@@ -263,6 +315,7 @@ function TreeNode({
                 depth={depth + 1}
                 selectedFile={selectedFile}
                 onSelectFile={onSelectFile}
+                fileChanges={fileChanges}
               />
             ))}
           </div>
@@ -280,7 +333,16 @@ function TreeNode({
       onClick={() => onSelectFile(node.path)}
     >
       <FileIcon name={node.name} />
-      <span className="truncate ml-0.5">{node.name}</span>
+      <span className="truncate ml-0.5 flex-1">{node.name}</span>
+      {changeStatus !== "unchanged" && (
+        <span
+          className="text-[9px] font-bold shrink-0 mr-2"
+          style={{ color: STATUS_COLORS[changeStatus] }}
+          title={changeStatus}
+        >
+          {STATUS_LETTERS[changeStatus]}
+        </span>
+      )}
     </button>
   );
 }