@illuma-ai/code-sandbox 1.3.0 → 1.4.0

package/README.md

@@ -0,0 +1,715 @@
+# @illuma-ai/code-sandbox
+
+A browser-native code sandbox with file tree, Monaco editor, terminal, and live preview — powered by [Nodepod](https://www.npmjs.com/package/@illuma-ai/nodepod).
+
+Run Express + React applications entirely in the browser. No server-side containers required.
+
+## Features
+
+- Full IDE workbench: file tree, code editor, terminal, live preview
+- Runs Node.js in the browser via Nodepod (SharedArrayBuffer + Service Worker)
+- Monaco editor with syntax highlighting, diff viewer, and file tabs
+- Structured error reporting with file path, line number, and source context
+- Hot reload for CSS/HTML/static asset changes (no server restart)
+- Imperative API for programmatic control (designed for AI agent integration)
+- Built-in project templates (Express + React full-stack apps)
+- Customizable via CSS custom properties
+- Dark theme by default, Ranger/shadcn theme variable bridge
+
+## Installation
+
+```bash
+npm install @illuma-ai/code-sandbox
+```
+
+### Peer Dependencies
+
+These must be installed by the consuming application:
+
+```bash
+npm install react react-dom @monaco-editor/react monaco-editor @xterm/xterm @xterm/addon-fit lucide-react
+```
+
+| Peer Dependency        | Version                |
+| ---------------------- | ---------------------- |
+| `react`                | `^18.0.0 \|\| ^19.0.0` |
+| `react-dom`            | `^18.0.0 \|\| ^19.0.0` |
+| `@monaco-editor/react` | `^4.6.0`               |
+| `monaco-editor`        | `>=0.40.0`             |
+| `@xterm/xterm`         | `^5.5.0 \|\| ^6.0.0`   |
+| `@xterm/addon-fit`     | `^0.11.0`              |
+| `lucide-react`         | `>=0.300.0`            |
+
+## Prerequisites
+
+### COOP/COEP Headers
+
+Nodepod requires `SharedArrayBuffer`, which is only available in cross-origin isolated contexts. Your dev server must send these headers:
+
+```
+Cross-Origin-Opener-Policy: same-origin
+Cross-Origin-Embedder-Policy: credentialless
+```
+
+**Vite example:**
+
+```ts
+// vite.config.ts
+export default defineConfig({
+  server: {
+    headers: {
+      "Cross-Origin-Opener-Policy": "same-origin",
+      "Cross-Origin-Embedder-Policy": "credentialless",
+    },
+  },
+});
+```
+
+### Service Worker
+
+Copy the Nodepod service worker file to your `public/` directory so it's served at `/__sw__.js`:
+
+```bash
+cp node_modules/@illuma-ai/nodepod/dist/sw.js public/__sw__.js
+```
+
+## Quick Start
+
+```tsx
+import { useRef } from "react";
+import { CodeSandbox } from "@illuma-ai/code-sandbox";
+import type { CodeSandboxHandle } from "@illuma-ai/code-sandbox";
+import "@illuma-ai/code-sandbox/styles.css";
+
+function App() {
+  const ref = useRef<CodeSandboxHandle>(null);
+
+  return (
+    <CodeSandbox
+      ref={ref}
+      template="fullstack-starter"
+      height="100vh"
+      onServerReady={(port, url) => console.log(`Ready on port ${port}`)}
+      onSandboxError={(err) => console.error(err.category, err.message)}
+    />
+  );
+}
+```
+
+### With Custom Files
+
+```tsx
+const files = {
+  "package.json": JSON.stringify(
+    {
+      name: "my-app",
+      dependencies: { express: "^4.18.0" },
+    },
+    null,
+    2,
+  ),
+  "server.js": `
+    const express = require("express");
+    const app = express();
+    app.get("/", (req, res) => res.send("<h1>Hello World</h1>"));
+    app.listen(3000, () => console.log("Running on port 3000"));
+  `,
+};
+
+<CodeSandbox
+  ref={ref}
+  files={files}
+  entryCommand="node server.js"
+  port={3000}
+  height="100vh"
+/>;
+```
+
+### AI Agent Integration
+
+The sandbox is designed as a "dumb renderer" — the host application pushes files in and reads state out. The user does not edit code in the sandbox; an AI agent writes code, and the host pushes it via the imperative API.
+
+```tsx
+const ref = useRef<CodeSandboxHandle>(null);
+
+// Agent generates new files → push them into the sandbox
+await ref.current.updateFiles(agentGeneratedFiles);
+
+// Agent modifies a single file
+await ref.current.updateFile("server.js", newServerCode);
+
+// Read errors for the agent to self-correct
+const errors = ref.current.getErrors();
+// errors[0] → { category: "process-stderr", message: "...", filePath: "server.js", line: 42, sourceContext: "..." }
+```
+
+---
+
+## API Reference
+
+### `<CodeSandbox>` Component
+
+The main component. Renders the full workbench (file tree, editor, terminal, preview). Uses `React.forwardRef` to expose the imperative handle.
+
+```tsx
+<CodeSandbox
+  ref={sandboxRef}
+  files={fileMap} // OR template="fullstack-starter"
+  entryCommand="node server.js"
+  port={3000}
+  env={{ NODE_ENV: "development" }}
+  height="100vh"
+  className="my-sandbox"
+  onFileChange={(path, content) => {}}
+  onServerReady={(port, url) => {}}
+  onProgress={(progress) => {}}
+  onError={(message) => {}}
+  onSandboxError={(error) => {}}
+  onFilesUpdated={(changes) => {}}
+/>
+```
+
+#### Props (`CodeSandboxProps`)
+
+| Prop           | Type                     | Default                                            | Description                                                                                   |
+| -------------- | ------------------------ | -------------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| `files`        | `FileMap`                | —                                                  | Initial file set. Pass a flat `Record<string, string>` mapping file paths to contents.        |
+| `template`     | `string`                 | —                                                  | Use a built-in template instead of `files`. One of: `"express-react"`, `"fullstack-starter"`. |
+| `entryCommand` | `string`                 | Inferred from `package.json` or `"node server.js"` | Shell command to start the dev server.                                                        |
+| `port`         | `number`                 | `3000`                                             | Port the server listens on.                                                                   |
+| `env`          | `Record<string, string>` | —                                                  | Environment variables passed to Node.js processes.                                            |
+| `height`       | `string`                 | `"100vh"`                                          | CSS height of the sandbox root element.                                                       |
+| `className`    | `string`                 | —                                                  | CSS class name for the root element.                                                          |
+
+#### Callback Props
+
+| Callback         | Signature                                             | Description                                                                                    |
+| ---------------- | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| `onFileChange`   | `(path: string, content: string) => void`             | Fires when a file is modified in the editor.                                                   |
+| `onServerReady`  | `(port: number, url: string) => void`                 | Fires when the dev server is ready (initial boot or after restart).                            |
+| `onProgress`     | `(progress: BootProgress) => void`                    | Fires on boot progress changes.                                                                |
+| `onError`        | `(message: string) => void`                           | Fires on errors (legacy string format).                                                        |
+| `onSandboxError` | `(error: SandboxError) => void`                       | Fires when a structured error is detected. **Primary error channel for AI agent integration.** |
+| `onFilesUpdated` | `(changes: Record<string, FileChangeStatus>) => void` | Fires after `updateFiles()` completes (files written + server restarted).                      |
+
+---
+
+### `CodeSandboxHandle` (Imperative API)
+
+Access via a React ref. This is the primary API for host applications to control the sandbox programmatically.
+
+```tsx
+const ref = useRef<CodeSandboxHandle>(null);
+<CodeSandbox ref={ref} ... />
+```
+
+#### Methods
+
+##### `updateFiles(files, options?)`
+
+Replace the entire file set. Diffs against current files, writes only changed files to the virtual FS, and restarts the server if anything changed.
+
+The previous file set becomes `originalFiles` for diff tracking.
+
+```ts
+await ref.current.updateFiles(newFileMap);
+await ref.current.updateFiles(newFileMap, { restartServer: false });
+```
+
+| Param                   | Type      | Description                                                   |
+| ----------------------- | --------- | ------------------------------------------------------------- |
+| `files`                 | `FileMap` | Complete new file set.                                        |
+| `options.restartServer` | `boolean` | Whether to restart the server after writing. Default: `true`. |
+
+**Hot reload vs cold restart:** If ALL changed files are hot-reloadable (CSS, HTML, images, fonts), the sandbox refreshes the preview iframe without restarting the Node.js server. If ANY changed file is JS/TS/JSON, the server process is killed and re-run.
+
+##### `updateFile(path, content)`
+
+Update a single file. Writes to the virtual FS and updates state. Does **not** restart the server — call `restart()` manually if needed, or use `updateFiles()` for bulk updates with auto-restart.
+
+```ts
+await ref.current.updateFile("public/styles.css", newCss);
+```
+
+##### `restart()`
+
+Force restart the server process. Kills the current process and re-runs the entry command.
+
+```ts
+await ref.current.restart();
+```
+
+##### `getFiles()`
+
+Returns the current `FileMap` (all files including edits).
+
+```ts
+const files: FileMap = ref.current.getFiles();
+```
+
+##### `getChangedFiles()`
+
+Returns a `FileMap` containing only files that have been modified relative to `originalFiles`.
+
+```ts
+const changed: FileMap = ref.current.getChangedFiles();
+```
+
+##### `getFileChanges()`
+
+Returns the per-file change status map. Missing keys should be treated as `"unchanged"`.
+
+```ts
+const changes: Record<string, FileChangeStatus> = ref.current.getFileChanges();
+// { "server.js": "modified", "public/new-page.html": "new" }
+```
+
+##### `getErrors()`
+
+Returns all structured errors collected during this session. The array grows monotonically — new errors are appended.
+
+```ts
+const errors: SandboxError[] = ref.current.getErrors();
+```
+
+##### `getState()`
+
+Returns the current `RuntimeState` snapshot.
+
+```ts
+const state: RuntimeState = ref.current.getState();
+// state.status, state.previewUrl, state.terminalOutput, etc.
+```
+
+---
+
+### `SandboxError`
+
+Structured error type designed for AI agent consumption. Includes enough context for the agent to construct a targeted fix prompt.
+
+```ts
+interface SandboxError {
+  id: string; // Unique ID for deduplication
+  category: SandboxErrorCategory; // Error type
+  message: string; // Human-readable error message
+  stack?: string; // Full stack trace
+  filePath?: string; // File path (relative to workdir)
+  line?: number; // Line number (1-indexed)
+  column?: number; // Column number (1-indexed)
+  timestamp: string; // ISO 8601 timestamp
+  sourceContext?: string; // ~10 surrounding source lines
+}
+```
+
+#### Error Categories (`SandboxErrorCategory`)
+
+| Category                      | Description                                                    |
+| ----------------------------- | -------------------------------------------------------------- |
+| `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                      |
+| `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 at module load time                       |
+| `network`                     | Failed HTTP requests from the preview (fetch/XHR)              |
+| `boot`                        | Error during Nodepod boot, file writing, or dependency install |
+
+#### Source Context Format
+
+When available, `sourceContext` contains lines formatted as `"lineNum: content"`:
+
+```
+38: const express = require("express");
+39: const app = express();
+40: const PORT = 3000;
+41:
+42: app.get("/api/data", (req, res) => {
+43:   res.json(undefinedVariable);    // ← error here
+44: });
+45: app.listen(PORT);
+```
+
+---
+
+### `RuntimeState`
+
+The full reactive state exposed by the runtime.
+
+```ts
+interface RuntimeState {
+  status: BootStage;
+  progress: BootProgress;
+  previewUrl: string | null;
+  terminalOutput: string[];
+  files: FileMap;
+  originalFiles: FileMap;
+  fileChanges: Record<string, FileChangeStatus>;
+  previewReloadKey: number;
+  error: string | null;
+  errors: SandboxError[];
+}
+```
+
+| Field              | Type                               | Description                                                                 |
+| ------------------ | ---------------------------------- | --------------------------------------------------------------------------- |
+| `status`           | `BootStage`                        | Current lifecycle stage.                                                    |
+| `progress`         | `BootProgress`                     | Current boot progress (stage, message, percent).                            |
+| `previewUrl`       | `string \| null`                   | URL for the preview iframe. `null` until server is ready.                   |
+| `terminalOutput`   | `string[]`                         | All terminal output lines (stdout + stderr).                                |
+| `files`            | `FileMap`                          | Current files in the virtual FS (including edits).                          |
+| `originalFiles`    | `FileMap`                          | Baseline files before the latest `updateFiles()`. Used for diffs.           |
+| `fileChanges`      | `Record<string, FileChangeStatus>` | Per-file change status. Missing keys = `"unchanged"`.                       |
+| `previewReloadKey` | `number`                           | Incremented on hot reload — triggers iframe refresh without server restart. |
+| `error`            | `string \| null`                   | Error message if status is `"error"`.                                       |
+| `errors`           | `SandboxError[]`                   | All structured errors (grows monotonically).                                |
+
+### `BootStage`
+
+```ts
+type BootStage =
+  | "initializing" // Nodepod.boot() in progress
+  | "writing-files" // Writing project files to virtual FS
+  | "installing" // npm install running
+  | "starting" // Entry command executing
+  | "ready" // Server is listening, preview iframe can load
+  | "error"; // Something failed
+```
+
+### `BootProgress`
+
+```ts
+interface BootProgress {
+  stage: BootStage;
+  message: string;
+  percent: number; // 0-100, approximate
+}
+```
+
+### `FileChangeStatus`
+
+```ts
+type FileChangeStatus = "new" | "modified" | "deleted" | "unchanged";
+```
+
+---
+
+## Hot Reload
+
+When `updateFiles()` is called, the sandbox inspects which files changed:
+
+- **Hot-reloadable extensions:** `.css`, `.html`, `.htm`, `.svg`, `.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`, `.ico`, `.woff`, `.woff2`, `.ttf`, `.eot`
+- If **all** changed files have hot-reloadable extensions → the preview iframe is soft-reloaded (`location.reload()`) without restarting the Node.js server process.
+- If **any** changed file is JS/TS/JSON/etc. → the server process is killed and re-run (cold restart).
+
+This makes CSS-only iterations instant.
+
+---
+
+## Built-in Templates
+
+Use `template="name"` to bootstrap with a pre-built project.
+
+### `express-react`
+
+A lightweight Express + React app using JSONPlaceholder as a data source. React is loaded from CDN (no build step). Demonstrates posts/users CRUD views.
+
+- **Entry command:** `node server.js`
+- **Port:** 3000
+- **Files:** 9 (server.js, public/index.html, styles, 5 React components)
+
+### `fullstack-starter`
+
+A comprehensive full-stack template with authentication, CRUD, charts, and theming.
+
+- **Entry command:** `node server.js`
+- **Port:** 3000
+- **Files:** 35 (Express + sql.js + React + React Router + Auth + CRUD + Chart.js + Ranger theme variables)
+- **Features:** Login/register, todo CRUD with SQLite (sql.js), doughnut chart, light/dark theme, responsive layout
+
+### Template API
+
+```ts
+import { getTemplate, listTemplates } from "@illuma-ai/code-sandbox";
+
+const names = listTemplates();
+// ["express-react", "fullstack-starter"]
+
+const tpl = getTemplate("fullstack-starter");
+// { files: FileMap, entryCommand: string, port: number }
+```
+
+---
+
+## Theming
+
+### Sandbox Chrome (CSS Custom Properties)
+
+The sandbox UI is themed via `--sb-*` CSS custom properties. Override them in your CSS to match your application:
+
+```css
+:root {
+  --sb-bg: #1e1e1e;
+  --sb-bg-alt: #252526;
+  --sb-bg-hover: #2a2d2e;
+  --sb-bg-active: #37373d;
+  --sb-sidebar: #252526;
+  --sb-editor: #1e1e1e;
+  --sb-terminal: #0d1117;
+  --sb-terminal-header: #161b22;
+  --sb-preview: #ffffff;
+  --sb-border: #3c3c3c;
+  --sb-text: #cccccc;
+  --sb-text-muted: #858585;
+  --sb-text-active: #ffffff;
+  --sb-accent: #007acc;
+  --sb-accent-hover: #1a8ad4;
+  --sb-success: #3fb950;
+  --sb-warning: #d29922;
+  --sb-error: #f85149;
+  --sb-info: #58a6ff;
+  --sb-scrollbar-thumb: rgba(255, 255, 255, 0.12);
+  --sb-scrollbar-thumb-hover: rgba(255, 255, 255, 0.25);
+  --sb-scrollbar-track: transparent;
+  --sb-scrollbar-width: 6px;
+}
+```
+
+### Ranger Theme Bridge
+
+The sandbox CSS also defines Ranger/shadcn design tokens (`--text-primary`, `--surface-primary`, `--border-light`, `--chart-1` through `--chart-5`, etc.) in both light and dark variants. These are available inside the preview iframe content for seamless visual integration with Ranger's UI.
+
+Add the `.dark` class to an ancestor element to activate dark mode tokens.
+
+---
+
+## Advanced Usage
+
+### Individual Components
+
+All sub-components are exported individually for custom layouts:
+
+```tsx
+import {
+  FileTree,
+  buildFileTree,
+  CodeEditor,
+  Terminal,
+  Preview,
+  BootOverlay,
+  ViewSlider,
+} from "@illuma-ai/code-sandbox";
+```
+
+#### `<FileTree>`
+
+Renders a collapsible file tree with per-extension SVG icons (19 distinct types: JS, TS, JSX, TSX, JSON, HTML, CSS, SCSS, MD, PY, RB, GO, RS, YML, ENV, SH, SQL, SVG, Lock) and change status indicators.
+
+```tsx
+import { FileTree, buildFileTree } from "@illuma-ai/code-sandbox";
+
+const tree = buildFileTree(fileMap);
+<FileTree
+  files={tree}
+  selectedFile="server.js"
+  onSelectFile={(path) => setSelected(path)}
+  fileChanges={{ "server.js": "modified" }}
+/>;
+```
+
+#### `<CodeEditor>`
+
+Monaco-based code editor with file tabs, diff mode toggle, and change status indicators on tabs.
+
+```tsx
+<CodeEditor
+  files={fileMap}
+  originalFiles={baselineFiles}
+  fileChanges={changes}
+  activeFile="server.js"
+  openFiles={["server.js", "public/index.html"]}
+  onSelectFile={(path) => {}}
+  onCloseFile={(path) => {}}
+  onFileChange={(path, content) => {}}
+  readOnly={false}
+/>
+```
+
+#### `<Terminal>`
+
+Clean monochrome terminal output display with minimize/expand toggle and line count badge.
+
+```tsx
+<Terminal
+  output={terminalLines}
+  minimized={false}
+  onToggleMinimize={() => setMinimized(!minimized)}
+/>
+```
+
+#### `<Preview>`
+
+Live preview iframe with JavaScript error capture (injects `window.onerror`, `unhandledrejection`, and `console.error` listeners). URL bar displays friendly `localhost:3000/` instead of internal paths.
+
+```tsx
+<Preview
+  url={previewUrl}
+  onRefresh={() => runtime.restart()}
+  onBrowserError={(error) => handleError(error)}
+  reloadKey={state.previewReloadKey}
+/>
+```
+
+#### `<BootOverlay>`
+
+Loading overlay with staged progress animation.
+
+```tsx
+<BootOverlay
+  progress={{
+    stage: "installing",
+    message: "Installing express...",
+    percent: 55,
+  }}
+/>
+```
+
+#### `<ViewSlider>`
+
+Pill-shaped toggle between Code and Preview views with Framer Motion animation.
+
+```tsx
+import type { WorkbenchView } from "@illuma-ai/code-sandbox";
+
+<ViewSlider
+  activeView={view}
+  onViewChange={(v: WorkbenchView) => setView(v)}
+/>;
+```
+
+### `NodepodRuntime` Service
+
+The framework-agnostic runtime service (no React dependency). Use directly for custom integrations.
+
+```ts
+import { NodepodRuntime } from "@illuma-ai/code-sandbox";
+
+const runtime = new NodepodRuntime({
+  files: myFiles,
+  entryCommand: "node server.js",
+  port: 3000,
+  workdir: "/app",
+  env: { NODE_ENV: "production" },
+});
+
+runtime.setProgressCallback((progress) => console.log(progress));
+runtime.setOutputCallback((line) => console.log(line));
+runtime.setServerReadyCallback((port, url) => console.log("Ready:", url));
+runtime.setErrorCallback((error) => console.error(error));
+
+await runtime.boot();
+
+// File operations
+await runtime.writeFile("server.js", newContent);
+const content = await runtime.readFile("server.js");
+
+// State
+const files = runtime.getCurrentFiles();
+const changed = runtime.getChangedFiles();
+const errors = runtime.getErrors();
+const status = runtime.getStatus();
+const previewUrl = runtime.getPreviewUrl();
+
+// Lifecycle
+await runtime.restart();
+runtime.teardown();
+```
+
+### `useRuntime` Hook
+
+React hook wrapping `NodepodRuntime`. Powers the `CodeSandbox` component internally. Use for fully custom React UIs.
+
+```ts
+import { useRuntime } from "@illuma-ai/code-sandbox";
+
+const {
+  state, // RuntimeState
+  selectedFile, // string | null
+  openFiles, // string[]
+  handleFileChange, // (path, content) => void
+  handleSelectFile, // (path) => void
+  handleCloseFile, // (path) => void
+  handleBrowserError, // (error: SandboxError) => void
+  restart, // () => Promise<void>
+  updateFiles, // (files, options?) => Promise<void>
+  updateFile, // (path, content) => Promise<void>
+  getFiles, // () => FileMap
+  getChangedFiles, // () => FileMap
+  getFileChanges, // () => Record<string, FileChangeStatus>
+  getErrors, // () => SandboxError[]
+  getState, // () => RuntimeState
+} = useRuntime(props);
+```
+
+---
+
+## Nodepod Constraints
+
+The sandbox runs on [Nodepod](https://www.npmjs.com/package/@illuma-ai/nodepod), a browser-native Node.js runtime. Key constraints:
+
+- **No build tools:** Vite, Webpack, Next.js, etc. will not work. Use CDN-loaded libraries instead.
+- **`express.static()` does not work.** Serve files manually via `fs.readFileSync()` + `res.send()`.
+- **`res.sendFile()` does not work.** Same — use `fs.readFileSync()` + `res.send()`.
+- **Module wrapper hides browser globals:** `document`, `window`, `location` are `undefined` in server-side code (as expected in Node.js).
+- **Preview URL rewriting:** Nodepod returns `/__virtual__/{port}` URLs but the Service Worker expects `/__preview__/{port}/`. The sandbox handles this transparently.
+
+---
+
+## All Exports
+
+```ts
+// Main component
+export { CodeSandbox } from "@illuma-ai/code-sandbox";
+
+// Individual components
+export { FileTree, buildFileTree } from "@illuma-ai/code-sandbox";
+export { CodeEditor } from "@illuma-ai/code-sandbox";
+export { Terminal } from "@illuma-ai/code-sandbox";
+export { Preview } from "@illuma-ai/code-sandbox";
+export { BootOverlay } from "@illuma-ai/code-sandbox";
+export { ViewSlider } from "@illuma-ai/code-sandbox";
+
+// Services & hooks
+export { NodepodRuntime } from "@illuma-ai/code-sandbox";
+export { useRuntime } from "@illuma-ai/code-sandbox";
+
+// Templates
+export { getTemplate, listTemplates } from "@illuma-ai/code-sandbox";
+
+// Types
+export type {
+  FileMap,
+  FileNode,
+  FileChangeStatus,
+  SandboxError,
+  SandboxErrorCategory,
+  BootStage,
+  BootProgress,
+  RuntimeConfig,
+  RuntimeState,
+  CodeSandboxProps,
+  CodeSandboxHandle,
+  FileTreeProps,
+  CodeEditorProps,
+  TerminalProps,
+  PreviewProps,
+  BootOverlayProps,
+  WorkbenchView,
+} from "@illuma-ai/code-sandbox";
+```
+
+---
+
+## License
+
+Proprietary - Illuma AI. See [LICENSE](./LICENSE) for details.