sandlot 0.1.1 → 0.1.3

package/README.md

@@ -1,616 +1,243 @@
 # Sandlot
 
-A browser-based TypeScript sandbox for AI agent-driven code generation.
-
-Sandlot provides a complete in-browser development environment with a virtual filesystem, TypeScript type checking, esbuild bundling, and npm package management—all without a server.
-
-## Features
-
-- **Virtual Filesystem** - In-memory or IndexedDB-backed file storage
-- **TypeScript Type Checking** - Full type checking
-- **esbuild Bundling** - Fast bundling with automatic npm import handling via esbuild-wasm
-- **Package Management** - Install npm packages via esm.sh CDN
-- **Bash Shell** - Familiar command interface (`tsc`, `build`, `install`, etc.) via just-bash
-- **React Integration** - Share your React instance with dynamic components
+Browser-based TypeScript sandbox with esbuild bundling and type checking. Designed for AI agent workflows where code needs to be written, validated, and executed in real-time, all in the browser.
 
 ## Installation
 
 ```bash
 npm install sandlot
-# or
-bun add sandlot
 ```
 
 ## Quick Start
 
 ```typescript
-import { createSandbox, loadModule } from "sandlot";
+import { createBuilder, registerSharedModules } from "sandlot";
+import * as React from "react";
 
-// Create a sandbox
-const sandbox = await createSandbox({
-  fsOptions: {
-    initialFiles: {
-      "/tsconfig.json": JSON.stringify({
-        compilerOptions: { target: "ES2020", module: "ESNext", strict: true },
-      }),
-    },
-  },
-});
+// Share React with dynamic code to avoid duplicate instances
+registerSharedModules({ react: React });
 
-// Write code
-await sandbox.fs.writeFile(
-  "/src/index.ts",
-  `export function greet(name: string) {
-    return \`Hello, \${name}!\`;
-  }`,
-);
-
-// Capture build result via callback
-let bundle: BundleResult | null = null;
-const unsubscribe = sandbox.onBuild((result) => {
-  bundle = result;
+// Create a reusable builder
+const runAgent = createBuilder({
+  sandboxOptions: { sharedModules: ["react"] },
+  build: async (sandbox, prompt) => {
+    // Your agent logic here - execute commands via sandbox.bash.exec()
+    await sandbox.bash.exec(
+      'echo "export const App = () => <div>Hello</div>" > /src/index.tsx',
+    );
+    await sandbox.bash.exec("build /src/index.tsx");
+  },
 });
 
-// Build
-const result = await sandbox.bash.exec("build /src/index.ts");
-unsubscribe();
+// Run with a prompt
+const result = await runAgent("Create a counter component");
 
-if (result.exitCode === 0 && bundle) {
-  const mod = await loadModule<{ greet: (name: string) => string }>(bundle);
-  console.log(mod.greet("World")); // "Hello, World!"
+if (result.module?.App) {
+  // Use the generated component
+  const App = result.module.App as React.ComponentType;
 }
-
-sandbox.close();
 ```
 
-## Sandbox API
+## Builder API
 
-The Sandbox API provides direct access to the filesystem and bash shell.
+The `createBuilder()` function is the primary API for agent workflows. It handles sandbox lifecycle, build capture, validation, and cancellation.
 
-### Creating a Sandbox
+### `createBuilder(options)`
 
-```typescript
-import { createSandbox, createInMemorySandbox } from "sandlot";
-
-// Persistent sandbox (IndexedDB-backed)
-const sandbox = await createSandbox({
-  fsOptions: {
-    dbName: "my-project",
-    initialFiles: {
-      "/src/index.ts": "export const x = 1;",
-    },
-  },
-});
-
-// In-memory sandbox (no persistence)
-const memSandbox = await createInMemorySandbox({
-  initialFiles: {
-    "/src/index.ts": "export const x = 1;",
-  },
-});
-```
-
-### Using Bash Commands
+Returns a reusable builder function that can be called with different prompts.
 
 ```typescript
-// Write files using bash
-await sandbox.bash.exec('echo "export const x = 1;" > /src/index.ts');
+const runAgent = createBuilder<T>({
+  // Sandbox configuration (pick one)
+  sandbox?: Sandbox,           // Reuse an existing sandbox (state persists between calls)
+  sandboxOptions?: SandboxOptions, // Create fresh sandbox per call (isolated runs)
 
-// Type check (entry point required)
-const tscResult = await sandbox.bash.exec("tsc /src/index.ts");
-console.log(tscResult.stdout);
-
-// Build (entry point required) - capture result via onBuild callback
-let bundleResult: BundleResult | null = null;
-const unsubscribe = sandbox.onBuild((result) => {
-  bundleResult = result;
+  // Your agent logic
+  build: (sandbox: Sandbox, prompt: string) => Promise<T>,
 });
-
-const buildCmd = await sandbox.bash.exec("build /src/index.ts");
-if (buildCmd.exitCode === 0 && bundleResult) {
-  console.log(bundleResult.code); // Compiled JavaScript
-}
-unsubscribe();
-
-// Install packages
-await sandbox.bash.exec("install react lodash@4.17.21");
-
-// List installed packages
-const listResult = await sandbox.bash.exec("list");
-console.log(listResult.stdout);
-
-// Run code (entry point required)
-await sandbox.bash.exec("run /src/script.ts");
 ```
 
-### Build Command Options
-
-```bash
-build <entry> [options]
+#### Options
 
-Arguments:
-  entry                   Entry point file (required, e.g., /src/index.ts)
-
-Options:
-  --skip-typecheck, -s    Skip type checking
-  --minify, -m            Enable minification
-  --format, -f <format>   Output format: esm (default), iife, cjs
-```
+| Option           | Type                              | Description                                             |
+| ---------------- | --------------------------------- | ------------------------------------------------------- |
+| `sandbox`        | `Sandbox`                         | Existing sandbox to reuse. Files persist between calls. |
+| `sandboxOptions` | `SandboxOptions`                  | Options for creating fresh sandboxes per call.          |
+| `build`          | `(sandbox, prompt) => Promise<T>` | Your agent logic. Receives the sandbox and prompt.      |
 
-### Sandbox Events
+### Calling the Builder
 
 ```typescript
-// Subscribe to build events to capture build results
-let bundleResult: BundleResult | null = null;
-const unsubscribe = sandbox.onBuild((result) => {
-  bundleResult = result;
-  console.log("Build completed:", result.code.length, "bytes");
-});
-
-// Build with entry point (required)
-const buildCmd = await sandbox.bash.exec("build /src/index.ts");
-if (buildCmd.exitCode !== 0) {
-  console.error("Build failed:", buildCmd.stderr);
-} else if (bundleResult) {
-  console.log(bundleResult.code);
-}
-unsubscribe();
-
-// Check for unsaved changes
-if (sandbox.isDirty()) {
-  await sandbox.save(); // Persist to IndexedDB
-}
-
-// Clean up
-sandbox.close();
+const result = await runAgent(prompt, options?);
 ```
 
-> **Note:** The `onBuild` callback is invoked synchronously during successful builds.
-> Use it to capture the `BundleResult` for loading modules.
-
-### Sandbox Manager
-
-For managing multiple sandboxes with shared resources:
-
-```typescript
-import { createSandboxManager } from "sandlot";
-
-const manager = await createSandboxManager({
-  sharedModules: ["react", "react-dom/client"],
-});
-
-// Create multiple sandboxes - they share TypeScript libs and bundler
-const sandbox1 = await manager.createSandbox({ id: "agent-1" });
-const sandbox2 = await manager.createSandbox({ id: "agent-2" });
+#### Call Options
 
-// Run operations in parallel
-await Promise.all([sandbox1.bash.exec("build"), sandbox2.bash.exec("build")]);
+| Option     | Type            | Description                                                     |
+| ---------- | --------------- | --------------------------------------------------------------- |
+| `validate` | `(module) => M` | Validate exports during build. Errors are visible to the agent. |
+| `timeout`  | `number`        | Max time in ms. Throws `AbortError` if exceeded.                |
+| `signal`   | `AbortSignal`   | For external cancellation.                                      |
 
-// Save all with unsaved changes
-await manager.saveAll();
-
-// Get dirty sandbox IDs
-const unsaved = manager.getDirtySandboxes();
-
-// Clean up
-manager.destroyAll();
-```
-
-### Sandbox Options
+#### Result
 
 ```typescript
-interface SandboxOptions {
-  // Filesystem configuration
-  fsOptions?: {
-    dbName?: string; // IndexedDB database name
-    initialFiles?: Record<string, string>;
-    maxSizeBytes?: number; // Filesystem size limit
-  };
-
-  // Build configuration
-  tsconfigPath?: string; // Default: "/tsconfig.json"
-
-  // Module sharing (see React Integration)
-  sharedModules?: string[];
-
-  // Build callback - use to capture successful build results
-  onBuild?: (result: BundleResult) => void | Promise<void>;
-
-  // Custom bash commands
-  customCommands?: Command[];
+interface BuildResult<T, M> {
+  result: T | undefined; // Return value from your build function
+  error: Error | null; // Error if build function threw
+  bundle: BundleResult | null; // The compiled JavaScript bundle
+  module: M | null; // Loaded module exports (validated if validate provided)
+  sandbox: Sandbox; // The sandbox used (for inspection or reuse)
 }
 ```
 
----
-
-## React Integration
+### Validation
 
-Sandlot solves the "multiple React instances" problem by letting dynamic components use your host application's React.
-
-### Setup
+Validation runs as part of the `build` command. If it throws, the build fails and the agent sees the error, allowing it to fix the code and retry.
 
 ```typescript
-import * as React from "react";
-import * as ReactDOM from "react-dom/client";
-import { registerSharedModules, createSandbox } from "sandlot";
-import { DynamicMount } from "sandlot/react";
-
-// Register your React instances (do this once at app startup)
-registerSharedModules({
-  react: React,
-  "react-dom/client": ReactDOM,
+const result = await runAgent("Create a counter", {
+  validate: (mod) => {
+    if (typeof mod.App !== "function") {
+      throw new Error("Must export an App component");
+    }
+    return { App: mod.App as React.ComponentType };
+  },
 });
+// result.module is typed as { App: React.ComponentType } | null
 ```
 
-### Generating React Components
+With Zod:
 
 ```typescript
-import { createSandbox, loadModule, BundleResult } from "sandlot";
+import { z } from "zod";
 
-const sandbox = await createSandbox({
-  fsOptions: {
-    initialFiles: {
-      "/tsconfig.json": JSON.stringify({
-        compilerOptions: {
-          target: "ES2020",
-          module: "ESNext",
-          jsx: "react-jsx",
-          strict: true,
-        },
-      }),
-    },
-  },
-  sharedModules: ["react", "react-dom/client"],
+const Schema = z.object({
+  App: z.custom<React.ComponentType>((v) => typeof v === "function"),
+  initialCount: z.number().optional(),
 });
 
-// Install React types for TypeScript compilation
-// (sharedModules provides runtime React, but types are still needed)
-await sandbox.bash.exec("install react react-dom");
-
-await sandbox.fs.writeFile(
-  "/src/index.tsx",
-  `
-  import React, { useState } from "react";
-  import { createRoot } from "react-dom/client";
-
-  function Counter() {
-    const [count, setCount] = useState(0);
-    return (
-      <button onClick={() => setCount(c => c + 1)}>
-        Count: {count}
-      </button>
-    );
-  }
-
-  export function render(container: HTMLElement) {
-    const root = createRoot(container);
-    root.render(<Counter />);
-    return () => root.unmount();
-  }
-  `,
-);
-
-// Capture build result
-let bundle: BundleResult | null = null;
-const unsubscribe = sandbox.onBuild((result) => {
-  bundle = result;
+const result = await runAgent("Create a counter", {
+  validate: (mod) => Schema.parse(mod),
 });
-
-const buildResult = await sandbox.bash.exec("build /src/index.tsx");
-unsubscribe();
-
-if (buildResult.exitCode === 0 && bundle) {
-  // Load the module and call render
-  const mod = await loadModule<{ render: (el: HTMLElement) => () => void }>(
-    bundle,
-  );
-  // mod.render is ready to use
-}
-
-sandbox.close();
-```
-
-### Rendering Dynamic Components
-
-Use `DynamicMount` to render the generated component:
-
-```tsx
-import { DynamicMount } from "sandlot/react";
-
-function App() {
-  const [module, setModule] = useState(null);
-
-  const generate = async () => {
-    // ... build with sandbox, capture bundle via onBuild ...
-    setModule(bundle);
-  };
-
-  return (
-    <div>
-      <button onClick={generate}>Generate</button>
-      <DynamicMount
-        module={module}
-        props={{ name: "World" }}
-        fallback={<div>Click to generate...</div>}
-        onMount={() => console.log("Mounted")}
-        onError={(err) => console.error(err)}
-      />
-    </div>
-  );
-}
-```
-
-### Using the Hook
-
-For more control, use `useDynamicComponent`:
-
-```tsx
-import { useDynamicComponent } from "sandlot/react";
-
-function App() {
-  const { containerRef, isMounted, error, unmount } = useDynamicComponent(
-    module,
-    { name: "World" },
-  );
-
-  return (
-    <div>
-      <div ref={containerRef} />
-      {isMounted && <button onClick={unmount}>Remove</button>}
-      {error && <div>Error: {error.message}</div>}
-    </div>
-  );
-}
-```
-
-### Render Function Pattern
-
-Dynamic components must export a `render` function:
-
-```typescript
-export function render(container: HTMLElement, props?: MyProps) {
-  const root = createRoot(container);
-  root.render(<MyComponent {...props} />);
-  return () => root.unmount(); // Cleanup function
-}
 ```
 
----
-
-## Package Management
-
-Sandlot installs packages via esm.sh CDN and fetches TypeScript type definitions.
-
-### Installing Packages
+### Cancellation
 
 ```typescript
-// Via bash
-await sandbox.bash.exec("install lodash date-fns@3.0.0");
-
-// Via direct API
-import { installPackage } from "sandlot";
-await installPackage(fs, "lodash@4.17.21");
-```
-
-### How It Works
+const controller = new AbortController();
 
-1. Resolves package version from esm.sh CDN
-2. Fetches TypeScript type definitions
-3. Stores types in `/node_modules/<package>/`
-4. Updates `/package.json` with installed version
-5. At bundle time, imports are rewritten to esm.sh URLs
-
-### Package Commands
-
-```bash
-install <package>[@version] [...]   # Install packages
-uninstall <package> [...]           # Remove packages
-list                                # Show installed packages
-```
-
----
-
-## Loading Modules
-
-After building, use loaders to access the compiled code:
-
-```typescript
-import { loadModule, loadExport, loadDefault } from "sandlot";
-
-// Load all exports
-const mod = await loadModule<{ add: Function; multiply: Function }>(
-  result.bundle,
-);
-
-// Load a specific export
-const add = await loadExport<(a: number, b: number) => number>(
-  result.bundle,
-  "add",
-);
-
-// Load default export
-const Calculator = await loadDefault<typeof Calculator>(result.bundle);
+const promise = runAgent("Create a dashboard", {
+  signal: controller.signal,
+  timeout: 60_000, // 1 minute
+});
 
-// Check what's exported
-const names = await getExportNames(result.bundle); // ["add", "multiply", "default"]
-const hasAdd = await hasExport(result.bundle, "add"); // true
+// Cancel on user action
+cancelButton.onclick = () => controller.abort();
 ```
 
----
-
-## Advanced Usage
+## Sandbox API
 
-### Direct Bundler Access
+For lower-level control, use `createSandbox()` directly.
 
 ```typescript
-import { bundle, initBundler } from "sandlot";
-
-// Pre-warm the bundler (optional)
-await initBundler();
-
-const result = await bundle({
-  fs: myFilesystem,
-  entryPoint: "/src/index.ts",
-  format: "esm", // "esm" | "iife" | "cjs"
-  minify: false,
-  sourcemap: false,
-  sharedModules: ["react"],
-  npmImports: "cdn", // "cdn" | "external" | "bundle"
-});
-
-console.log(result.code);
-console.log(result.warnings);
-console.log(result.includedFiles);
-```
-
-### Direct Type Checking
+import { createSandbox } from "sandlot";
 
-```typescript
-import {
-  typecheck,
-  formatDiagnostics,
-  formatDiagnosticsForAgent,
-} from "sandlot";
-
-const result = await typecheck({
-  fs: myFilesystem,
-  entryPoint: "/src/index.ts",
-  tsconfigPath: "/tsconfig.json",
-  libFiles: myLibFiles, // Map of lib name to content
+const sandbox = await createSandbox({
+  initialFiles: {
+    "/src/index.ts": "export const x = 1;",
+    "/tsconfig.json": JSON.stringify({ compilerOptions: { strict: true } }),
+  },
+  sharedModules: ["react", "react-dom/client"],
+  onBuild: (result) => console.log("Build succeeded:", result),
 });
 
-if (result.hasErrors) {
-  // Human-readable format
-  console.log(formatDiagnostics(result.diagnostics));
+// Execute shell commands
+await sandbox.bash.exec("tsc /src/index.ts"); // Type check
+await sandbox.bash.exec("build /src/index.ts"); // Bundle
+await sandbox.bash.exec("install lodash"); // Install package
+await sandbox.bash.exec("list"); // List packages
 
-  // Agent-friendly format
-  console.log(formatDiagnosticsForAgent(result.diagnostics));
+// Access the last successful build
+if (sandbox.lastBuild) {
+  const { bundle, module } = sandbox.lastBuild;
 }
-```
 
-### Custom Filesystem
+// Serialize state for persistence
+const state = sandbox.getState();
+localStorage.setItem("project", JSON.stringify(state));
+```
 
-```typescript
-import { createIndexedDbFs, IndexedDbFs } from "sandlot";
+### Sandbox Options
 
-// Persistent filesystem
-const fs = await createIndexedDbFs({
-  dbName: "my-project",
-  initialFiles: { "/README.md": "# Hello" },
-  maxSizeBytes: 50 * 1024 * 1024, // 50MB limit
-});
+| Option          | Type                     | Description                                         |
+| --------------- | ------------------------ | --------------------------------------------------- |
+| `initialFiles`  | `Record<string, string>` | Files to populate the filesystem with.              |
+| `sharedModules` | `string[]`               | Modules to resolve from host (e.g., `['react']`).   |
+| `tsconfigPath`  | `string`                 | Path to tsconfig.json (default: `/tsconfig.json`).  |
+| `onBuild`       | `(result) => void`       | Callback when a build succeeds.                     |
+| `bashOptions`   | `SandboxBashOptions`     | Options for the just-bash shell (cwd, env, limits). |
 
-// In-memory filesystem
-const memFs = IndexedDbFs.createInMemory({
-  initialFiles: { "/README.md": "# Hello" },
-});
+## Shell Commands
 
-// File operations
-await fs.writeFile("/src/index.ts", "export const x = 1;");
-const content = await fs.readFile("/src/index.ts");
-const exists = await fs.exists("/src/index.ts");
-await fs.mkdir("/src/utils", { recursive: true });
-await fs.rm("/src/old.ts");
+The sandbox provides these built-in commands:
 
-// Persistence
-if (fs.isDirty()) {
-  await fs.save();
-}
+| Command                   | Description                         |
+| ------------------------- | ----------------------------------- |
+| `tsc [entry]`             | Type check (uses tsconfig.json)     |
+| `build [entry] [options]` | Bundle (runs typecheck first)       |
+| `install <pkg>`           | Install npm package (fetches types) |
+| `uninstall <pkg>`         | Remove package                      |
+| `list`                    | List installed packages             |
+| `run <entry>`             | Execute a script                    |
 
-fs.close();
-```
+Build options: `--format <esm\|iife\|cjs>`, `--minify`, `--skip-typecheck`
 
-### Shared Resources
+## Shared Modules
 
-Share TypeScript libs and bundler across multiple sandboxes:
+To avoid duplicate library instances (important for React context/hooks), register shared modules before creating sandboxes:
 
 ```typescript
-import { createSharedResources, getDefaultResources } from "sandlot";
-
-// Create custom resources
-const resources = await createSharedResources({
-  libs: ["ES2022", "DOM", "DOM.Iterable"],
-});
+import { registerSharedModules } from "sandlot";
+import * as React from "react";
+import * as ReactDOM from "react-dom/client";
 
-// Use with sandbox
-const sandbox = await createSandbox({
-  resources,
+registerSharedModules({
+  react: React,
+  "react-dom/client": ReactDOM,
 });
-
-// Or use the default singleton
-const defaultResources = await getDefaultResources();
 ```
 
----
+Then include them in `sharedModules` when creating a sandbox.
 
-## TypeScript Configuration
+## Cross-Origin Isolation
 
-Sandlot respects your `tsconfig.json`:
+For optimal esbuild-wasm performance, enable cross-origin isolation by adding these headers to your dev server:
 
-```json
-{
-  "compilerOptions": {
-    "target": "ES2020",
-    "module": "ESNext",
-    "moduleResolution": "bundler",
-    "jsx": "react-jsx",
-    "strict": true,
-    "esModuleInterop": true,
-    "skipLibCheck": true,
-    "lib": ["ES2020", "DOM", "DOM.Iterable"]
-  }
-}
 ```
-
-Supported options:
-
-- `target`: ES5 through ESNext
-- `module`: CommonJS, ES2015, ES2020, ESNext, Node16, NodeNext
-- `moduleResolution`: Classic, Node, Node16, NodeNext, Bundler
-- `jsx`: preserve, react, react-jsx, react-jsxdev, react-native
-- `strict`, `noImplicitAny`, `strictNullChecks`
-- `esModuleInterop`, `allowJs`, `resolveJsonModule`
-- `lib`: Array of lib names
-
----
-
-## API Reference
-
-### Exports from `sandlot`
-
-```typescript
-// Sandbox API
-export { createSandbox, createInMemorySandbox } from "sandlot";
-export { SandboxManager, createSandboxManager } from "sandlot";
-
-// Module Loading
-export { loadModule, loadExport, loadDefault } from "sandlot";
-export { getExportNames, hasExport } from "sandlot";
-
-// Shared Modules
-export { registerSharedModules, clearSharedModules } from "sandlot";
-
-// Types
-export type { Sandbox, SandboxOptions } from "sandlot";
-export type { BundleResult, TypecheckResult } from "sandlot";
+Cross-Origin-Embedder-Policy: require-corp
+Cross-Origin-Opener-Policy: same-origin
 ```
 
-### Exports from `sandlot/react`
+In Vite:
 
 ```typescript
-export { DynamicMount, useDynamicComponent } from "sandlot/react";
-export { generateRenderFunction, REACT_RENDER_TEMPLATE } from "sandlot/react";
-export type { DynamicRenderModule, DynamicMountProps } from "sandlot/react";
+export default defineConfig({
+  plugins: [
+    {
+      name: "isolation",
+      configureServer: (server) => {
+        server.middlewares.use((_, res, next) => {
+          res.setHeader("Cross-Origin-Embedder-Policy", "require-corp");
+          res.setHeader("Cross-Origin-Opener-Policy", "same-origin");
+          next();
+        });
+      },
+    },
+  ],
+});
 ```
 
----
-
-## Requirements
-
-- Modern browser with ES2020 support
-- IndexedDB (for persistent filesystems)
-- WebAssembly (for esbuild)
-
 ## License
 
 MIT