@illuma-ai/code-sandbox 1.0.0 → 1.2.0

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>
   );
 }

package/src/components/Preview.tsx

@@ -1,22 +1,204 @@
 /**
  * Preview — Full-width iframe that renders the Nodepod virtual server.
  *
- * Loads the URL from Nodepod's Service Worker proxy (/__virtual__/PORT/).
+ * Loads the URL from Nodepod's Service Worker proxy (/__preview__/PORT/).
  * The toolbar handles the URL bar and refresh — this is just the iframe.
+ *
+ * Error capture: After the iframe loads, we inject a small script that
+ * hooks `window.onerror`, `window.onunhandledrejection`, and
+ * `console.error` inside the iframe. These are relayed to the parent
+ * via `postMessage`, where we parse them into SandboxError objects
+ * and forward to the `onBrowserError` callback.
+ *
+ * The iframe and parent are same-origin (both served through the
+ * Nodepod Service Worker), so direct contentWindow access works.
+ */
+
+import React, { useRef, useEffect, useCallback } from "react";
+import type {
+  PreviewProps,
+  SandboxError,
+  SandboxErrorCategory,
+} from "../types";
+
+/** Message type sent from the error-capture script inside the iframe */
+interface IframeErrorMessage {
+  type: "sandbox-error";
+  category: SandboxErrorCategory;
+  message: string;
+  stack?: string;
+  filename?: string;
+  lineno?: number;
+  colno?: number;
+}
+
+/**
+ * Build the error-capture script injected into the iframe.
+ *
+ * This script runs inside the preview iframe's global scope and
+ * intercepts three error vectors:
+ * 1. window.onerror — uncaught exceptions
+ * 2. window.onunhandledrejection — unhandled Promise rejections
+ * 3. console.error — explicit error logging
+ *
+ * Each error is posted to the parent via postMessage with a
+ * structured payload so the parent can construct a SandboxError.
  */
+function buildErrorCaptureScript(): string {
+  return `
+(function() {
+  // Guard against double-injection
+  if (window.__sandboxErrorCapture) return;
+  window.__sandboxErrorCapture = true;
+
+  var post = function(category, message, stack, filename, lineno, colno) {
+    try {
+      window.parent.postMessage({
+        type: 'sandbox-error',
+        category: category,
+        message: String(message || 'Unknown error'),
+        stack: stack || undefined,
+        filename: filename || undefined,
+        lineno: lineno || undefined,
+        colno: colno || undefined
+      }, '*');
+    } catch(e) { /* swallow — parent may not be listening */ }
+  };
+
+  // 1. Uncaught exceptions
+  window.onerror = function(msg, source, lineno, colno, error) {
+    post(
+      'browser-error',
+      msg,
+      error && error.stack ? error.stack : undefined,
+      source,
+      lineno,
+      colno
+    );
+  };
+
+  // 2. Unhandled promise rejections
+  window.onunhandledrejection = function(event) {
+    var reason = event.reason;
+    var msg = reason instanceof Error ? reason.message : String(reason);
+    var stack = reason instanceof Error ? reason.stack : undefined;
+    post('browser-unhandled-rejection', msg, stack);
+  };
+
+  // 3. console.error intercept
+  var origError = console.error;
+  console.error = function() {
+    // Forward to original so DevTools still shows it
+    origError.apply(console, arguments);
+    var parts = [];
+    for (var i = 0; i < arguments.length; i++) {
+      var arg = arguments[i];
+      if (arg instanceof Error) {
+        parts.push(arg.message);
+        // Use the stack from the first Error argument
+        if (parts.length === 1) {
+          post('browser-console-error', arg.message, arg.stack);
+          return;
+        }
+      } else {
+        parts.push(String(arg));
+      }
+    }
+    post('browser-console-error', parts.join(' '));
+  };
+})();
+`;
+}
 
-import React, { useRef, useEffect } from "react";
-import type { PreviewProps } from "../types";
+/** Counter for unique error IDs within this component instance */
+let browserErrorCounter = 0;
 
 /**
  * Preview component — renders the dev server output in a full-width iframe.
  *
- * The URL points to /__virtual__/PORT/ which is intercepted by the
+ * The URL points to /__preview__/PORT/ which is intercepted by the
  * Nodepod Service Worker and proxied to the Express server running
  * in the Web Worker.
+ *
+ * After the iframe loads, an error-capture script is injected so that
+ * runtime errors inside the preview are surfaced to the AI agent.
  */
-export function Preview({ url, className = "" }: PreviewProps) {
+export function Preview({ url, className = "", onBrowserError }: PreviewProps) {
   const iframeRef = useRef<HTMLIFrameElement>(null);
+  const onBrowserErrorRef = useRef(onBrowserError);
+  onBrowserErrorRef.current = onBrowserError;
+
+  /**
+   * Inject the error-capture script into the iframe's contentWindow.
+   *
+   * Called on iframe `load` event. We use direct contentWindow access
+   * (same-origin) rather than srcdoc to avoid breaking the SW proxy.
+   */
+  const injectErrorCapture = useCallback(() => {
+    const iframe = iframeRef.current;
+    if (!iframe) return;
+
+    try {
+      const iframeDoc =
+        iframe.contentDocument || iframe.contentWindow?.document;
+      if (!iframeDoc) return;
+
+      const script = iframeDoc.createElement("script");
+      script.textContent = buildErrorCaptureScript();
+      // Append to <head> (or <body> if <head> doesn't exist)
+      const target =
+        iframeDoc.head || iframeDoc.body || iframeDoc.documentElement;
+      if (target) {
+        target.appendChild(script);
+      }
+    } catch (err) {
+      // Cross-origin restriction — shouldn't happen with SW proxy but
+      // degrade gracefully if it does.
+      console.warn(
+        "[CodeSandbox:Preview] Could not inject error capture:",
+        err,
+      );
+    }
+  }, []);
+
+  // Listen for postMessage from the iframe
+  useEffect(() => {
+    const handler = (event: MessageEvent) => {
+      if (!event.data || event.data.type !== "sandbox-error") return;
+
+      const data = event.data as IframeErrorMessage;
+      const cb = onBrowserErrorRef.current;
+      if (!cb) return;
+
+      // Parse filename to extract relative file path.
+      // The iframe's script src URLs look like:
+      //   https://host/__preview__/3000/js/app.js
+      // We want just "public/js/app.js" or "js/app.js".
+      let filePath: string | undefined;
+      if (data.filename) {
+        const match = data.filename.match(
+          /\/__(?:preview|virtual)__\/\d+(\/.*)/,
+        );
+        filePath = match ? match[1].replace(/^\//, "") : undefined;
+      }
+
+      const error: SandboxError = {
+        id: `browser_${++browserErrorCounter}_${Date.now()}`,
+        category: data.category,
+        message: data.message,
+        stack: data.stack,
+        filePath,
+        line: data.lineno ?? undefined,
+        column: data.colno ?? undefined,
+        timestamp: new Date().toISOString(),
+      };
+
+      cb(error);
+    };
+
+    window.addEventListener("message", handler);
+    return () => window.removeEventListener("message", handler);
+  }, []);
 
   // Reload iframe when URL changes
   useEffect(() => {
@@ -34,6 +216,7 @@ export function Preview({ url, className = "" }: PreviewProps) {
           className="w-full h-full border-none"
           title="Preview"
           sandbox="allow-scripts allow-forms allow-same-origin allow-popups allow-modals"
+          onLoad={injectErrorCapture}
         />
       ) : (
         <div className="flex items-center justify-center h-full bg-sb-bg">

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 } from "../types";
+import type {
+  CodeSandboxProps,
+  CodeSandboxHandle,
+  FileChangeStatus,
+} from "../types";
 
 /** Transition for view crossfade */
 const VIEW_TRANSITION = {
@@ -50,99 +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,
-    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}
-            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} />
-        </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
@@ -241,6 +290,8 @@ function RefreshIcon() {
 interface CodeViewProps {
   fileTree: ReturnType<typeof buildFileTree>;
   files: Record<string, string>;
+  originalFiles: Record<string, string>;
+  fileChanges: Record<string, FileChangeStatus>;
   selectedFile: string | null;
   openFiles: string[];
   terminalOutput: string[];
@@ -257,6 +308,8 @@ interface CodeViewProps {
 function CodeView({
   fileTree,
   files,
+  originalFiles,
+  fileChanges,
   selectedFile,
   openFiles,
   terminalOutput,
@@ -273,6 +326,7 @@ function CodeView({
             files={fileTree}
             selectedFile={selectedFile}
             onSelectFile={onSelectFile}
+            fileChanges={fileChanges}
           />
         </Allotment.Pane>
 
@@ -282,6 +336,8 @@ function CodeView({
             <Allotment.Pane preferredSize="70%">
               <CodeEditor
                 files={files}
+                originalFiles={originalFiles}
+                fileChanges={fileChanges}
                 activeFile={selectedFile}
                 openFiles={openFiles}
                 onSelectFile={onSelectFile}