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

@@ -3,14 +3,36 @@
  *
  * Manages the Nodepod runtime instance and exposes reactive state
  * for all UI components (progress, files, terminal output, preview URL).
+ *
+ * Supports two file sources:
+ * 1. Direct files (via `files` prop or `template` prop)
+ * 2. GitHub repo (via `github` prop) — with branch polling for hot-reload
+ *
+ * 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, FileMap, RuntimeState, SandboxError } from "../types";
 /**
  * Hook that manages the full Nodepod runtime lifecycle.
  *
  * @param props - CodeSandbox component props
  * @returns Reactive runtime state + control functions
+ *
+ * @example
+ * ```tsx
+ * // Direct files
+ * const { state } = useRuntime({ files: myFiles, entryCommand: 'node server.js' });
+ *
+ * // GitHub repo with auto-polling
+ * const { state } = useRuntime({
+ *   github: { owner: 'illuma-ai', repo: 'fullstack-starter', branch: 'main' },
+ *   gitToken: 'ghp_xxx',
+ *   onSandboxError: (err) => agent.fix(err),
+ * });
+ * ```
  */
 export declare function useRuntime(props: CodeSandboxProps): {
     state: RuntimeState;
@@ -19,6 +41,7 @@ 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>;
     getChangedFiles: () => FileMap;
     runtime: import("react").MutableRefObject<NodepodRuntime | null>;