@illuma-ai/code-sandbox 1.0.0 → 1.2.0

package/dist/components/CodeEditor.d.ts

@@ -1,11 +1,24 @@
 /**
- * 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 type { CodeEditorProps } from "../types";
 /**
- * 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 declare function CodeEditor({ files, activeFile, openFiles, onSelectFile, onCloseFile, onFileChange, readOnly, }: CodeEditorProps): import("react/jsx-runtime").JSX.Element;
+export declare function CodeEditor({ files, originalFiles, fileChanges, activeFile, openFiles, onSelectFile, onCloseFile, onFileChange, readOnly, }: CodeEditorProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/FileTree.d.ts

@@ -15,5 +15,6 @@ import type { FileMap, FileNode, FileTreeProps } from "../types";
 export declare function buildFileTree(files: FileMap): FileNode[];
 /**
  * FileTree component — renders a collapsible tree of files and folders.
+ * Shows change status indicators (N/M/D) next to modified files.
  */
-export declare function FileTree({ files, selectedFile, onSelectFile }: FileTreeProps): import("react/jsx-runtime").JSX.Element;
+export declare function FileTree({ files, selectedFile, onSelectFile, fileChanges, }: FileTreeProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/Preview.d.ts

@@ -1,15 +1,27 @@
 /**
  * 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 type { PreviewProps } from "../types";
 /**
  * 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 declare function Preview({ url, className }: PreviewProps): import("react/jsx-runtime").JSX.Element;
+export declare function Preview({ url, className, onBrowserError }: PreviewProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/Workbench.d.ts

@@ -13,8 +13,9 @@
  *
  * @see bolt.diy: app/components/workbench/Workbench.client.tsx (reference)
  */
+import React from "react";
 import "allotment/dist/style.css";
-import type { CodeSandboxProps } from "../types";
+import type { CodeSandboxProps, CodeSandboxHandle } from "../types";
 /**
  * CodeSandbox — The main entrypoint component.
  *
@@ -25,4 +26,4 @@ import type { CodeSandboxProps } from "../types";
  * A compact toolbar row contains the view toggle and (in preview mode)
  * a URL bar with refresh button.
  */
-export declare function CodeSandbox(props: CodeSandboxProps): import("react/jsx-runtime").JSX.Element;
+export declare const CodeSandbox: React.ForwardRefExoticComponent<CodeSandboxProps & React.RefAttributes<CodeSandboxHandle>>;

package/dist/hooks/useRuntime.d.ts

@@ -3,14 +3,38 @@
  *
  * Manages the Nodepod runtime instance and exposes reactive state
  * for all UI components (progress, files, terminal output, preview URL).
+ *
+ * The sandbox is a pure renderer — it receives files via props (initial
+ * load) and via the imperative handle (updateFiles/updateFile for live
+ * updates). It does NOT interact with any storage backend directly.
+ *
+ * Error exposure: wires the runtime's structured error system and the
+ * preview iframe's browser error capture into a unified `errors[]` array
+ * in state, and forwards each error to the `onSandboxError` callback
+ * so the AI agent can auto-fix.
  */
 import { NodepodRuntime } from "../services/runtime";
-import type { CodeSandboxProps, FileMap, RuntimeState } from "../types";
+import type { CodeSandboxProps, FileChangeStatus, FileMap, RuntimeState, SandboxError } from "../types";
 /**
  * Hook that manages the full Nodepod runtime lifecycle.
  *
+ * The sandbox is a pure renderer — files come in via props or the
+ * imperative handle. No GitHub, no polling, no storage backends.
+ *
  * @param props - CodeSandbox component props
- * @returns Reactive runtime state + control functions
+ * @returns Reactive runtime state + control functions + imperative methods
+ *
+ * @example
+ * ```tsx
+ * // Direct files (fetched from any source by the host app)
+ * const runtime = useRuntime({ files: myFiles, entryCommand: 'node server.js' });
+ *
+ * // Later, push updated files from the host:
+ * await runtime.updateFiles(newFiles);
+ *
+ * // Or update a single file:
+ * await runtime.updateFile('server.js', newContent);
+ * ```
  */
 export declare function useRuntime(props: CodeSandboxProps): {
     state: RuntimeState;
@@ -19,7 +43,16 @@ export declare function useRuntime(props: CodeSandboxProps): {
     handleFileChange: (path: string, content: string) => Promise<void>;
     handleSelectFile: (path: string) => void;
     handleCloseFile: (path: string) => void;
+    handleBrowserError: (error: SandboxError) => Promise<void>;
     restart: () => Promise<void>;
+    updateFiles: (newFiles: FileMap, options?: {
+        restartServer?: boolean;
+    }) => Promise<void>;
+    updateFile: (path: string, content: string) => Promise<void>;
+    getFiles: () => FileMap;
     getChangedFiles: () => FileMap;
+    getFileChanges: () => Record<string, FileChangeStatus>;
+    getErrors: () => SandboxError[];
+    getState: () => RuntimeState;
     runtime: import("react").MutableRefObject<NodepodRuntime | null>;
 };