@liquidmetal-ai/precip 1.0.0

package/src/sandbox/README.md

@@ -0,0 +1,1321 @@
+# Precip Sandbox
+
+A secure JavaScript sandbox system using QuickJS WASM that enables async/await execution with bridged runtime APIs.
+
+## Overview
+
+The Precip sandbox provides isolated JavaScript execution environments using QuickJS WebAssembly. It enables running untrusted code safely while providing controlled access to runtime APIs through a bridge system. The key innovation is enabling `async/await` in QuickJS (which is synchronous) using a deferred promise pattern with Promise.race optimization.
+
+**Key Features:**
+
+- Isolated execution in QuickJS WASM
+- Full async/await support via host promise bridging
+- Bridge system for runtime APIs (fetch, console, storage, search, etc.)
+- Proper resource cleanup and handle management
+- Timeout and memory limit enforcement
+- Console output capture
+- 5.81x faster than polling for simple async operations
+
+## Architecture
+
+```
+sandbox/
+├── sandbox.ts              # Singleton sandbox with queued execution
+├── index.ts                # Sandbox exports
+├── test-helper.ts          # Test compatibility helper
+├── quickjs-wasm.d.ts       # TypeScript definitions
+└── bridges/                # API bridge implementations
+    ├── types.ts            # Shared bridge types
+    ├── utils.ts            # Bridge utility functions
+    ├── index.ts            # Bridge installation and cleanup
+    ├── console.ts          # Console API bridge
+    ├── fetch.ts            # Fetch API bridge
+    ├── response.ts         # Response constructor bridge
+    ├── readable-stream.ts  # ReadableStream bridge
+    ├── text-encoder.ts     # TextEncoder bridge
+    ├── text-decoder.ts     # TextDecoder bridge
+    ├── storage.ts          # KV storage bridge
+    ├── search.ts           # Vector search bridge
+    ├── bucket.ts           # Bucket object bridge
+    ├── actor.ts            # Actor/Durable Object bridge
+    └── shared/             # Shared bridge utilities
+        ├── index.ts
+        ├── headers.ts           # Headers object factory
+        ├── response-object.ts   # Unified Response factory
+        ├── body-methods.ts      # Body consumption methods
+        ├── cleanup.ts           # Stream cleanup utilities
+        └── json-helpers.ts      # JSON parsing utilities
+```
+
+## Core Concepts
+
+### QuickJS Context
+
+QuickJS is a lightweight JavaScript engine compiled to WebAssembly. The `QuickJSContext` represents an isolated JavaScript execution environment with its own global object, heap, and runtime state.
+
+**Handles**: All QuickJS values (objects, strings, functions) are represented as `QuickJSHandle` objects. Handles must be manually disposed to prevent memory leaks.
+
+### Async/Await in QuickJS
+
+QuickJS is synchronous by design, so it doesn't support native async/await. The sandbox enables async functionality through a **deferred promise pattern**:
+
+1. When sandbox code calls an async host function, the function returns a QuickJS Promise immediately (created via `context.newPromise()`)
+2. The host function kicks off the actual async work and stores the promise in a tracker
+3. When the async work completes, the deferred promise is resolved/rejected using the result
+4. The main execution waits for the top-level promise using a race loop that:
+   - Checks if the main promise is settled
+   - Races all pending host promises
+   - Wakes immediately when any promise settles (no polling)
+   - Re-races until the main promise settles
+
+```typescript
+// Host function returns deferred promise immediately
+const deferred = context.newPromise();
+
+// Kick off async work
+const hostPromise = fetch(url)
+  .then(result => {
+    const handle = convertToHandle(context, result);
+    deferred.resolve(handle);
+    handle.dispose();
+  })
+  .catch(err => {
+    const errHandle = context.newString(err.message);
+    deferred.reject(errHandle);
+    errHandle.dispose();
+  });
+
+// Track for cleanup and race optimization
+tracker.pendingPromises.add(hostPromise);
+tracker.notifyNewPromise();
+
+return deferred.handle;
+```
+
+### Bridge System
+
+Bridges expose runtime APIs to the sandbox code by creating QuickJS objects and methods that call into host functions. Each bridge is responsible for:
+
+1. Creating QuickJS objects/functions
+2. Converting between host and sandbox values
+3. Tracking host resources (streams, responses, readers)
+4. Managing handle lifetimes
+5. Registering cleanup handlers
+
+### Handle Management
+
+Handles represent QuickJS values and must be disposed when no longer needed. The pattern is:
+
+```typescript
+// Create handle
+const handle = context.newString('hello');
+
+// Use handle
+context.setProp(objHandle, 'message', handle);
+
+// Dispose handle
+handle.dispose();
+```
+
+**Critical Rules:**
+
+- Every `new*` call must be matched with a `dispose()` call
+- `callFunction` returns a handle that must be disposed
+- `evalCode` returns a value/error handle that must be disposed
+- Use `context.dump()` to convert handles to JS values (doesn't dispose the handle)
+
+### Promise Tracking
+
+The `PromiseTracker` manages all async operations in the sandbox:
+
+```typescript
+interface PromiseTracker {
+  pendingPromises: Set<Promise<void>>; // Host promises being tracked
+  notifyNewPromise: () => void; // Signal to wake race loop
+  newPromiseSignal: Promise<void>; // Signal promise for racing
+  deferredPromises: Set<any>; // QuickJS deferred promises
+}
+```
+
+The tracker is used for:
+
+- Race loop optimization (wake when any promise settles)
+- Cleanup (wait for all promises to settle before disposal)
+- Proper handle disposal timing
+
+## Main Components
+
+### sandbox.ts
+
+Singleton QuickJS sandbox with queued execution. Ensures only one sandbox (64MB memory limit) exists per worker by using a singleton pattern and execution queue.
+
+#### `Sandbox` Class
+
+```typescript
+class Sandbox {
+  static async getInstance(options?: SandboxOptions): Promise<Sandbox>;
+  async execute(
+    code: string,
+    globals: SandboxGlobals,
+    options?: SandboxOptions
+  ): Promise<SandboxResult>;
+  async dispose(): Promise<void>;
+  static reset(): void;
+}
+```
+
+**Usage:**
+
+```typescript
+// Get or create singleton (same for services and actors)
+const sandbox = await Sandbox.getInstance();
+
+// Execute code (queues if another execution is running)
+const result = await sandbox.execute(
+  'const x = await fetch(url); return x;',
+  {},
+  {
+    timeoutMs: 30000,
+    memoryLimitBytes: 64 * 1024 * 1024,
+    logger: console
+  }
+);
+
+// Dispose when shutting down (e.g., actor eviction)
+await sandbox.dispose();
+```
+
+**Key Features:**
+
+- **Singleton pattern**: One sandbox per worker, created on first `getInstance()`
+- **Execution queue**: Concurrent `execute()` calls wait their turn
+- **Memory limit**: Enforces 64MB limit (or custom via options)
+- **Reusable context**: Created once, reused across executions (recreated after cleanup)
+- **Proper cleanup**: Full cleanup after each execution including context recreation
+- **Queue management**: Pending executions are rejected on `dispose()`
+
+**Why Singleton?**
+
+In Raindrop Actors, multiple requests can arrive concurrently. Without a singleton, each request would create its own sandbox (64MB each), exceeding worker memory limits (128MB) and causing crashes. The singleton ensures maximum one sandbox per worker.
+
+**Execution Flow:**
+
+1. **First `getInstance()`**: Creates QuickJS runtime and context, sets memory limit
+2. **`execute(code, globals, options)`**:
+   - Adds execution to queue
+   - If queue is idle, starts processing immediately
+   - If another execution is running, waits in queue
+   - When turn comes:
+     - Set interrupt handler for timeout
+     - Create promise tracker and cleanup handlers
+     - Install bridges (standard + custom)
+     - Inject globals with promise tracking
+     - Wrap code in async IIFE
+     - Run race loop to wait for promise
+     - Return result
+     - Full cleanup
+     - Recreate context for next execution
+3. **`dispose()`**:
+   - Rejects all queued executions
+   - Disposes context and runtime
+   - Clears singleton (next `getInstance()` creates new instance)
+
+### Bridge System
+
+The bridge system enables sandbox code to interact with host APIs. Bridges are registered functions or objects that expose host capabilities to the sandbox.
+
+**Key Types:**
+
+```typescript
+interface BridgeContext {
+  context: QuickJSContext;
+  runtime: any;
+  tracker: PromiseTracker;
+  logger?: Logger;
+  cleanupHandlers: Array<() => void | Promise<void>>;
+}
+
+type BridgeInstaller = (ctx: BridgeContext) => void;
+```
+
+**Bridge Installation:**
+
+Bridges are installed in two phases:
+
+1. **Standard bridges**: Always installed (fetch, console, TextEncoder, TextDecoder, ReadableStream, Response)
+2. **Custom bridges**: Optional, provided via options
+
+**Execution Flow:**
+
+1. **Initialization**
+   - Load QuickJS WASM module (singleton, cached across executions)
+   - Create runtime and context
+   - Set memory limit and interrupt handler for timeout
+   - Create promise tracker and cleanup handlers array
+
+2. **Bridge Installation**
+   - Install standard bridges (fetch, console, TextEncoder, TextDecoder)
+   - Install custom bridges (if provided)
+
+3. **Global Injection**
+   - For each global value:
+     - Primitive → convert to handle, set on global
+     - Function → create QuickJS function that tracks async returns
+     - Object → create object, inject properties and methods
+
+4. **Code Execution**
+   - Wrap code in async IIFE: `(async () => { ${code} })()`
+   - Evaluate code (returns promise handle immediately)
+   - Run race loop to wait for promise settlement
+
+5. **Race Loop**
+
+   ```typescript
+   while (true) {
+     // Check timeout
+     // Execute pending QuickJS jobs
+     // Check main promise state
+     // If settled → resolve/reject with result
+     // Race: pending promises | new promise signal | timeout
+     // Wait for first to complete
+     // Loop
+   }
+   ```
+
+6. **Cleanup** (in finally block)
+   - Run bridge cleanup handlers (abort streams, release readers)
+   - Flush microtasks
+   - Wait for all pending promises to settle (3s timeout)
+   - Settle remaining deferred promises
+   - Drain job queue (max 1000 iterations, 1s timeout)
+   - Dispose deferred promise handles
+   - Final job drain (100 iterations, 500ms timeout)
+   - Check for lingering GC objects
+   - Dispose context
+   - Dispose runtime (only if safe)
+
+**Cleanup Complexity:**
+
+The cleanup sequence is critical to prevent memory leaks and crashes:
+
+1. **Bridge cleanup first**: Aborts streams, releases readers. This prevents new promises from being created.
+2. **Flush microtasks**: Lets abort handlers propagate and settle deferred promises.
+3. **Wait for promises**: All pending host promises must settle before disposal.
+4. **Settle deferred promises**: Reject pending deferred promises with cleanup error.
+5. **Drain job queue**: Execute QuickJS jobs repeatedly until queue is empty.
+6. **Dispose handles**: All QuickJS handles must be disposed.
+7. **Check GC objects**: Skip runtime disposal if lingering promise objects detected (QuickJS limitation).
+8. **Dispose context and runtime**: Final cleanup.
+
+### Bridge System
+
+#### types.ts
+
+Defines shared types for bridges:
+
+```typescript
+interface BridgeContext {
+  context: QuickJSContext;
+  runtime: any;
+  tracker: PromiseTracker;
+  logger?: Logger;
+  cleanupHandlers: Array<() => void | Promise<void>>;
+}
+
+interface PromiseTracker {
+  pendingPromises: Set<Promise<void>>;
+  notifyNewPromise: () => void;
+  newPromiseSignal: Promise<void>;
+  deferredPromises: Set<any>;
+}
+```
+
+#### utils.ts
+
+Core bridge utility functions:
+
+- `convertToHandle(context, value)`: Convert JS values to QuickJS handles
+- `createAsyncBridge(ctx, name, hostFn)`: Create an async bridge function
+- `createSyncBridge(ctx, name, hostFn)`: Create a sync bridge function
+- `defineClass(ctx, classCode, className)`: Define a QuickJS class from code
+- `setProperties(context, handle, props)`: Set multiple properties on an object
+- `addMethod(context, objHandle, methodName, methodHandle)`: Add a method to an object
+- `executeTrackedAsync(ctx, deferred, hostPromise)`: Execute async work with tracking
+
+#### index.ts
+
+Bridge installation and cleanup orchestration:
+
+- `installAllBridges(ctx)`: Install all standard bridges
+- `createPromiseTracker()`: Create a new promise tracker
+- `runCleanupHandlers(handlers, logger)`: Execute all cleanup handlers
+
+### Bridge Implementations
+
+#### console.ts
+
+Bridges the `console` API with output capture.
+
+**Features:**
+
+- `console.log`, `console.error`, `console.warn` methods
+- Argument formatting (objects, strings, primitives)
+- Output capture (accessible via `getConsoleOutput(context)`)
+- Cleanup via `clearConsoleOutput(context)`
+
+**Pattern:**
+
+```typescript
+export function installConsole(ctx: BridgeContext): void {
+  const consoleHandle = context.newObject();
+  const output: string[] = [];
+
+  const logMethod = context.newFunction('log', (...args: QuickJSHandle[]) => {
+    const jsArgs = args.map(arg => context.dump(arg));
+    const outputLine = formatArgs(jsArgs);
+    output.push(`[LOG] ${outputLine}`);
+    return context.undefined;
+  });
+
+  context.setProp(consoleHandle, 'log', logMethod);
+  logHandle.dispose();
+  context.setProp(context.global, 'console', consoleHandle);
+  consoleHandle.dispose();
+}
+```
+
+#### fetch.ts
+
+Bridges the `fetch` API.
+
+**Features:**
+
+- Full fetch API support (GET, POST, etc.)
+- Request/Response streaming
+- AbortController support
+- Stream cleanup on abort/timeout
+- Headers support
+
+**Resource Tracking:**
+
+- Tracks fetch abort controllers for cleanup
+- Registers cleanup handler to abort in-flight requests
+
+**Key Implementation:**
+
+```typescript
+export function installFetch(ctx: BridgeContext): void {
+  const { context, tracker, cleanupHandlers } = ctx;
+  const pendingAbortControllers = new Set<AbortController>();
+
+  const fetchHandle = context.newFunction(
+    'fetch',
+    (urlHandle: QuickJSHandle, initHandle?: QuickJSHandle) => {
+      const url = context.dump(urlHandle);
+      const init = initHandle ? context.dump(initHandle) : undefined;
+
+      const deferred = context.newPromise();
+      tracker.deferredPromises.add(deferred);
+
+      // Create AbortController for this request
+      const abortController = new AbortController();
+      pendingAbortControllers.add(abortController);
+
+      const hostPromise = fetch(url, { ...init, signal: abortController.signal })
+        .then(response => {
+          const responseHandle = createResponseObject(ctx, response, objCtx);
+          deferred.resolve(responseHandle);
+          responseHandle.dispose();
+        })
+        .catch(err => {
+          const errHandle = context.newString(err.message);
+          deferred.reject(errHandle);
+          errHandle.dispose();
+        })
+        .finally(() => {
+          pendingAbortControllers.delete(abortController);
+          tracker.pendingPromises.delete(hostPromise);
+        });
+
+      tracker.pendingPromises.add(hostPromise);
+      tracker.notifyNewPromise();
+
+      return deferred.handle;
+    }
+  );
+
+  // Register cleanup handler
+  cleanupHandlers.push(() => {
+    for (const controller of pendingAbortControllers) {
+      controller.abort('Sandbox cleanup');
+    }
+    pendingAbortControllers.clear();
+  });
+}
+```
+
+#### response.ts
+
+Bridges the `Response` constructor.
+
+**Features:**
+
+- `new Response(body, init)` support
+- Stream body bridging
+- Headers support
+- Body consumption methods (text, json, arrayBuffer)
+
+**Implementation:**
+Uses `createResponseObject` from shared utilities for unified Response creation.
+
+#### readable-stream.ts
+
+Bridges the `ReadableStream` API.
+
+**Features:**
+
+- `getReader()` method
+- `read()` method (async)
+- `releaseLock()` method
+- `locked` property (getter)
+- Coalescing reader for performance (buffers small chunks)
+
+**Coalescing Reader:**
+Reduces boundary crossing overhead by buffering small chunks before passing to QuickJS. Minimum chunk size: 16KB.
+
+**Key Implementation:**
+
+```typescript
+export function createStreamObject(
+  ctx: BridgeContext,
+  hostStream: ReadableStream,
+  streamId: number,
+  hostReaders: Map<number, ReadableStreamDefaultReader>,
+  readerIdCounter: { value: number }
+): QuickJSHandle {
+  const { context } = ctx;
+  const streamHandle = context.newObject();
+
+  const getReaderMethod = context.newFunction('getReader', () => {
+    const hostReader = hostStream.getReader();
+    const readerId = ++readerIdCounter.value;
+    hostReaders.set(readerId, hostReader);
+    return createReaderObject(ctx, hostReader, readerId);
+  });
+
+  context.setProp(streamHandle, 'getReader', getReaderMethod);
+  getReaderMethod.dispose();
+
+  return streamHandle;
+}
+```
+
+#### text-encoder.ts & text-decoder.ts
+
+Bridges `TextEncoder` and `TextDecoder` classes.
+
+**Features:**
+
+- Standard Web API compatibility
+- UTF-8 encoding/decoding
+- TextDecoder label support
+- Stream mode for TextDecoder
+
+#### storage.ts
+
+Bridges KV storage API.
+
+**Features:**
+
+- `await storage.get(path)` - Read values
+- `await storage.write(path, content)` - Write values
+- `await storage.list(prefix, limit)` - List keys
+- `await storage.remove(path)` - Delete keys
+- Response body with metadata (key, size, uploaded)
+- Proper error handling
+
+**Mount Info:**
+
+```typescript
+interface StorageMountInfo {
+  kv: KVNamespace;
+  bucket: R2Bucket;
+}
+```
+
+**Usage:**
+
+```typescript
+const bridgeCtx: BridgeContext = { ... };
+bridgeInstallers.push((ctx) => installStorage(ctx, { kv, bucket }));
+```
+
+#### search.ts
+
+Bridges vector search API.
+
+**Features:**
+
+- `await search(path, query)` - Search documents
+- `await search.chunk(path, query)` - Chunked search
+- Async iteration for results (for await...of)
+- Pagination support
+- Response metadata (text, source, score, chunk)
+
+**Mount Info:**
+
+```typescript
+interface SearchMountInfo {
+  search: VectorSearch;
+}
+```
+
+#### bucket.ts
+
+Bridges R2 bucket API.
+
+**Features:**
+
+- `await bucket.get(path)` - Get object
+- `await bucket.put(path, content)` - Put object
+- `await bucket.list(prefix, limit)` - List objects
+- `await bucket.delete(path)` - Delete object
+- Response streaming
+- Object metadata
+
+#### actor.ts
+
+Bridges Durable Object actor API.
+
+**Features:**
+
+- `await actor(path, instanceName)` - Get actor stub
+- Host stub caching
+- Error handling
+
+### Shared Utilities
+
+The `shared/` directory contains reusable components used across multiple bridges.
+
+#### headers.ts
+
+Creates Headers objects with full Web API support.
+
+**Features:**
+
+- `get()`, `has()`, `set()` methods
+- `entries()`, `keys()`, `values()` iterators
+- `forEach(callback)` method
+- Direct property access (e.g., `headers['content-type']`)
+
+**Usage:**
+
+```typescript
+const headersHandle = createHeadersObject(ctx, {
+  'content-type': 'application/json',
+  'x-custom': 'value'
+});
+```
+
+**Handle Management:**
+
+- Disposes all temporary handles created during iteration
+- Returns Headers handle that caller must dispose
+
+#### response-object.ts
+
+Unified Response object factory.
+
+**Features:**
+
+- Works with real Response objects (fetch, Response constructor)
+- Works with bare ReadableStream (bucket.get)
+- Sets all standard Response properties (status, ok, headers, etc.)
+- Bridges body stream
+- Attaches body consumption methods (text, json, arrayBuffer)
+- Exposes `bodyUsed` as getter
+- Supports extra metadata (bucket: key, size, uploaded)
+
+**Usage:**
+
+```typescript
+// From real Response
+const responseHandle = createResponseObject(ctx, { response: hostResponse }, objCtx);
+
+// From bare stream (bucket)
+const responseHandle = createResponseObject(ctx, { body: stream, metadata }, objCtx);
+```
+
+#### body-methods.ts
+
+Body consumption methods for Response objects.
+
+**Features:**
+
+- `createBodyMethod(ctx, methodName, responseId, registry)` - Creates text/json/arrayBuffer method
+- `attachBodyMethods(ctx, responseHandle, responseId, registry)` - Attaches all three
+- Checks `bodyUsed` before consumption
+- Uses cached JSON.parse for efficiency
+- Proper promise tracking
+
+**Pattern:**
+
+```typescript
+export function createBodyMethod(
+  ctx: BridgeContext,
+  methodName: 'json' | 'text' | 'arrayBuffer',
+  responseId: number,
+  responseRegistry: Map<number, Response>
+): QuickJSHandle {
+  return context.newFunction(methodName, () => {
+    const response = responseRegistry.get(responseId);
+    if (!response || response.bodyUsed) {
+      // Return rejected promise
+    }
+
+    const deferred = context.newPromise();
+    const hostPromise = response[methodName]().then(result => {
+      // Convert and resolve
+    });
+    tracker.pendingPromises.add(hostPromise);
+    return deferred.handle;
+  });
+}
+```
+
+#### cleanup.ts
+
+Stream cleanup utilities.
+
+**Features:**
+
+- `createStreamCleanupHandler(registry, bridgeName, logger)` - Creates cleanup function
+- Proper cleanup order: readers → streams → wait → clear maps
+- Timeout for cleanup operations (2s)
+- Error handling and logging
+
+**Critical Pattern:**
+
+```typescript
+export function createStreamCleanupHandler(
+  registry: StreamRegistry,
+  bridgeName: string,
+  logger?: Logger
+): () => Promise<void> {
+  return async () => {
+    // STEP 1: Release readers FIRST
+    for (const [id, reader] of registry.hostReaders) {
+      reader.releaseLock();
+    }
+    registry.hostReaders.clear();
+
+    // STEP 2: Cancel streams
+    const pendingOperations: Promise<unknown>[] = [];
+    for (const [id, stream] of registry.hostStreams) {
+      pendingOperations.push(stream.cancel('Sandbox cleanup'));
+    }
+    registry.hostStreams.clear();
+
+    // STEP 3: Wait for cancellation (with timeout)
+    await Promise.race([
+      Promise.allSettled(pendingOperations),
+      new Promise(resolve => setTimeout(resolve, 2000))
+    ]);
+
+    // STEP 4: Clear response references
+    registry.hostResponses?.clear();
+  };
+}
+```
+
+**Why this order?**
+
+- Readers must be released before streams can be cancelled
+- Cancellation settles pending read promises
+- Timeout prevents cleanup from blocking disposal indefinitely
+
+#### json-helpers.ts
+
+JSON parsing utilities with caching.
+
+**Features:**
+
+- `getJsonParse(context)` - Get or create cached JSON.parse handle
+- `parseJsonInContext(context, jsonString)` - Parse JSON string
+- Caches JSON.parse on context global to avoid evalCode overhead
+- Caller must dispose returned handle
+
+**Performance:**
+Caching JSON.parse avoids expensive `evalCode()` calls on every parse operation.
+
+**Usage:**
+
+```typescript
+const jsonHandle = parseJsonInContext(context, jsonString);
+// Use handle
+jsonHandle.dispose();
+```
+
+## Creating a New Bridge
+
+### Step 1: Define the Bridge Function
+
+```typescript
+// packages/precip/src/sandbox/bridges/my-api.ts
+import type { QuickJSHandle } from 'quickjs-emscripten-core';
+import type { BridgeContext } from './types.js';
+import { createAsyncBridge, convertToHandle } from './utils.js';
+
+export function installMyApi(ctx: BridgeContext): void {
+  const { context, tracker, cleanupHandlers, logger } = ctx;
+
+  // Create the main API object
+  const apiHandle = context.newObject();
+
+  // Add a method
+  const myMethod = context.newFunction('myMethod', (...args: QuickJSHandle[]) => {
+    const jsArgs = args.map(arg => context.dump(arg));
+
+    // Create deferred promise
+    const deferred = context.newPromise();
+    tracker.deferredPromises.add(deferred);
+
+    // Kick off async work
+    const hostPromise = doAsyncWork(jsArgs)
+      .then(result => {
+        const handle = convertToHandle(context, result);
+        deferred.resolve(handle);
+        handle.dispose();
+        runtime.executePendingJobs();
+      })
+      .catch(err => {
+        const errHandle = context.newString(err.message);
+        deferred.reject(errHandle);
+        errHandle.dispose();
+        runtime.executePendingJobs();
+      })
+      .finally(() => {
+        tracker.pendingPromises.delete(hostPromise);
+      });
+
+    tracker.pendingPromises.add(hostPromise);
+    tracker.notifyNewPromise();
+
+    return deferred.handle;
+  });
+
+  context.setProp(apiHandle, 'myMethod', myMethod);
+  myMethod.dispose();
+
+  // Register on global
+  context.setProp(context.global, 'myApi', apiHandle);
+  apiHandle.dispose();
+
+  logger?.info?.('[MyApi] Bridge installed');
+}
+```
+
+### Step 2: Register the Bridge
+
+```typescript
+// In packages/precip/src/sandbox/bridges/index.ts
+export { installMyApi } from './my-api.js';
+```
+
+### Step 3: Use the Bridge
+
+```typescript
+// When executing sandbox code
+const sandbox = await Sandbox.getInstance();
+await sandbox.execute(code, globals, {
+  bridgeInstallers: [installMyApi]
+});
+```
+
+## Common Patterns
+
+### Sync Bridge Function
+
+```typescript
+const syncMethod = context.newFunction('syncMethod', (argHandle: QuickJSHandle) => {
+  const arg = context.dump(argHandle);
+  const result = doSyncWork(arg);
+  return convertToHandle(context, result);
+});
+
+context.setProp(objHandle, 'syncMethod', syncMethod);
+syncMethod.dispose();
+```
+
+### Async Bridge Function
+
+```typescript
+const asyncMethod = context.newFunction('asyncMethod', (argHandle: QuickJSHandle) => {
+  const arg = context.dump(argHandle);
+  const deferred = context.newPromise();
+  tracker.deferredPromises.add(deferred);
+
+  const hostPromise = doAsyncWork(arg)
+    .then(result => {
+      const handle = convertToHandle(context, result);
+      deferred.resolve(handle);
+      handle.dispose();
+      runtime.executePendingJobs();
+    })
+    .catch(err => {
+      const errHandle = context.newString(err.message);
+      deferred.reject(errHandle);
+      errHandle.dispose();
+      runtime.executePendingJobs();
+    })
+    .finally(() => {
+      tracker.pendingPromises.delete(hostPromise);
+    });
+
+  tracker.pendingPromises.add(hostPromise);
+  tracker.notifyNewPromise();
+
+  return deferred.handle;
+});
+
+context.setProp(objHandle, 'asyncMethod', asyncMethod);
+asyncMethod.dispose();
+```
+
+### Class Definition
+
+```typescript
+const classCode = `
+  class MyClass {
+    constructor(value) {
+      this.value = value;
+    }
+
+    method() {
+      return this.value * 2;
+    }
+  }
+`;
+
+const { value: classHandle, error } = context.evalCode(classCode);
+if (error) {
+  error.dispose();
+  throw new Error('Failed to define class');
+}
+
+context.setProp(context.global, 'MyClass', classHandle);
+classHandle.dispose();
+```
+
+### Property Getter
+
+```typescript
+// Create getter function
+const getProp = context.newFunction('__getProp', () => {
+  return hostProp ? context.true : context.false;
+});
+
+context.setProp(objHandle, '__getProp', getProp);
+getProp.dispose();
+
+// Define as getter
+const defineCode = `
+  (function(obj) {
+    var fn = obj.__getProp;
+    Object.defineProperty(obj, 'myProp', {
+      get: function() { return fn(); },
+      enumerable: true,
+      configurable: true
+    });
+    delete obj.__getProp;
+    return obj;
+  })
+`;
+
+const { value: defineFn, error } = context.evalCode(defineCode);
+if (!error) {
+  const result = context.callFunction(defineFn, context.undefined, objHandle);
+  defineFn.dispose();
+  if (!('error' in result)) {
+    result.value.dispose();
+  }
+}
+```
+
+## Resource Management
+
+### Handle Disposal
+
+**Golden Rule:** Every handle created must be disposed.
+
+```typescript
+// Create handle
+const handle = context.newString('value');
+
+// Use it
+context.setProp(obj, 'key', handle);
+
+// Dispose it
+handle.dispose();
+```
+
+**Handle Lifecycle:**
+
+1. **Create**: `context.newString()`, `context.newObject()`, etc.
+2. **Use**: Pass to other functions or set as properties
+3. **Dispose**: `handle.dispose()`
+
+**Common Pitfalls:**
+
+```typescript
+// ❌ Forgot to dispose
+const handle = context.newString('value');
+context.setProp(obj, 'key', handle);
+// handle.dispose() missing!
+
+// ❌ Disposed too early
+const handle = context.newString('value');
+handle.dispose();
+context.setProp(obj, 'key', handle); // Error: handle already disposed
+
+// ✅ Correct
+const handle = context.newString('value');
+context.setProp(obj, 'key', handle);
+handle.dispose();
+```
+
+### Stream Cleanup
+
+Streams must be cleaned up in a specific order:
+
+1. Release readers (streams can't be cancelled while locked)
+2. Cancel streams (settles pending promises)
+3. Wait for cancellation (with timeout)
+4. Clear all maps
+
+```typescript
+export function cleanupStreams(registry: StreamRegistry): () => Promise<void> {
+  return async () => {
+    // Release readers
+    for (const reader of registry.hostReaders.values()) {
+      reader.releaseLock();
+    }
+    registry.hostReaders.clear();
+
+    // Cancel streams
+    const pending = [];
+    for (const stream of registry.hostStreams.values()) {
+      pending.push(stream.cancel('Sandbox cleanup'));
+    }
+    registry.hostStreams.clear();
+
+    // Wait (with timeout)
+    await Promise.race([
+      Promise.allSettled(pending),
+      new Promise(resolve => setTimeout(resolve, 2000))
+    ]);
+  };
+}
+```
+
+### Registry Pattern
+
+Host objects are tracked in registries for cleanup:
+
+```typescript
+interface ObjectContext {
+  registry: {
+    hostResponses: Map<number, Response>;
+    hostStreams: Map<number, ReadableStream>;
+    hostReaders: Map<number, ReadableStreamDefaultReader>;
+  };
+  responseIdCounter: { value: number };
+  streamIdCounter: { value: number };
+  readerIdCounter: { value: number };
+}
+
+// When creating a response
+const responseId = ++responseIdCounter.value;
+registry.hostResponses.set(responseId, response);
+
+// During cleanup
+registry.hostResponses.clear();
+registry.hostStreams.clear();
+registry.hostReaders.clear();
+```
+
+## Performance Optimizations
+
+### 1. Cached Function Handles
+
+Expensive operations like `evalCode()` are cached:
+
+```typescript
+// JSON parsing
+const JSON_PARSE_CACHE_KEY = '__cachedJsonParse';
+
+function getJsonParse(context: QuickJSContext): QuickJSHandle {
+  const cachedHandle = context.getProp(context.global, JSON_PARSE_CACHE_KEY);
+  if (context.typeof(cachedHandle) === 'function') {
+    return cachedHandle;
+  }
+  cachedHandle.dispose();
+
+  const jsonParse = context.getProp(context.global, 'JSON').parse;
+  context.setProp(context.global, JSON_PARSE_CACHE_KEY, jsonParse);
+  return jsonParse;
+}
+```
+
+### 2. Coalescing Reader
+
+Small stream chunks are buffered before crossing the boundary:
+
+```typescript
+class CoalescingReader {
+  private buffer: Uint8Array[] = [];
+  private bufferSize = 0;
+  private minChunkSize = 16 * 1024;
+
+  async read(): Promise<ReadableStreamReadResult<Uint8Array>> {
+    // Buffer until minChunkSize or stream ends
+    while (!this.done && this.bufferSize < this.minChunkSize) {
+      const result = await this.hostReader.read();
+      if (result.done) {
+        this.done = true;
+        break;
+      }
+      this.buffer.push(result.value);
+      this.bufferSize += result.value.length;
+    }
+
+    // Coalesce and return
+    // ...
+  }
+}
+```
+
+### 3. Promise.race Optimization
+
+Instead of polling, race all pending promises:
+
+```typescript
+const raceLoop = async () => {
+  while (true) {
+    // Check promise state
+    const state = context.getPromiseState(promiseHandle);
+    if (state.type !== 'pending') {
+      // Return result
+    }
+
+    // Create fresh signal BEFORE racing
+    tracker.newPromiseSignal = new Promise<void>(resolve => {
+      tracker.notifyNewPromise = resolve;
+    });
+
+    // Race: pending promises | signal | timeout
+    await Promise.race([
+      ...Array.from(tracker.pendingPromises),
+      tracker.newPromiseSignal,
+      new Promise(r => setTimeout(r, 100))
+    ]);
+
+    // Loop
+  }
+};
+```
+
+This wakes immediately when any promise settles, achieving 5.81x speedup over polling.
+
+## Error Handling
+
+### Context Errors
+
+QuickJS can throw errors during operations. Always handle them:
+
+```typescript
+try {
+  const result = context.callFunction(fn, context.undefined, argHandle);
+  if (result.error) {
+    const error = context.dump(result.error);
+    result.error.dispose();
+    throw new Error(`Call failed: ${error}`);
+  }
+  // Use result.value
+  result.value.dispose();
+} catch (e) {
+  // Handle error
+}
+```
+
+### Disposal Errors
+
+Disposal can fail if the handle is already disposed or invalid:
+
+```typescript
+try {
+  handle.dispose();
+} catch (e) {
+  logger?.warn?.(`Failed to dispose handle: ${e}`);
+}
+```
+
+### Promise Rejection
+
+Host promises can reject. Always handle rejections:
+
+```typescript
+const hostPromise = fetch(url)
+  .then(result => {
+    // Handle success
+  })
+  .catch(err => {
+    try {
+      const errHandle = context.newString(err.message);
+      deferred.reject(errHandle);
+      errHandle.dispose();
+      runtime.executePendingJobs();
+    } catch (e) {
+      // Context may be disposed
+    }
+  })
+  .finally(() => {
+    tracker.pendingPromises.delete(hostPromise);
+  });
+```
+
+## Testing
+
+Bridges should be tested for:
+
+1. **Functionality**: Correct behavior of bridged APIs
+2. **Error handling**: Proper error propagation
+3. **Resource cleanup**: No handle leaks or memory leaks
+4. **Async patterns**: Correct promise tracking and settlement
+5. **Edge cases**: Empty values, large payloads, timeouts
+
+### Example Test
+
+```typescript
+import { describe, it, expect, beforeEach } from 'vitest';
+import { Sandbox } from './index.js';
+
+describe('Console Bridge', () => {
+  let sandbox: Sandbox;
+
+  beforeEach(async () => {
+    sandbox = await Sandbox.getInstance();
+  });
+
+  it('should capture console output', async () => {
+    const result = await sandbox.execute(
+      `
+      console.log("hello");
+      console.error("oops");
+      console.warn("careful");
+      return "done"
+    `,
+      {}
+    );
+
+    expect(result.success).toBe(true);
+    expect(result.result).toBe('done');
+    expect(result.consoleOutput).toContain('hello');
+    expect(result.consoleOutput).toContain('[ERROR] oops');
+    expect(result.consoleOutput).toContain('[WARN] careful');
+  });
+});
+```
+
+## Debugging
+
+### Logging
+
+Use the logger parameter to trace execution:
+
+```typescript
+const sandbox = await Sandbox.getInstance();
+await sandbox.execute(code, globals, {
+  logger: console
+});
+```
+
+### Handle Leak Detection
+
+QuickJS doesn't track handles for you. Watch for:
+
+- Increasing memory usage
+- QuickJS assertion errors on disposal
+- Lingering GC objects in memory usage dump
+
+### Promise Leak Detection
+
+Check promise tracker size:
+
+```typescript
+logger?.info(`Pending promises: ${tracker.pendingPromises.size}`);
+logger?.info(`Deferred promises: ${tracker.deferredPromises.size}`);
+```
+
+### Cleanup Verification
+
+Verify cleanup handlers run:
+
+```typescript
+logger?.info(`Running ${cleanupHandlers.length} cleanup handlers`);
+await runCleanupHandlers(cleanupHandlers, logger);
+```
+
+## Known Limitations
+
+### QuickJS GC Objects
+
+When sandbox code holds references to unresolved promises (e.g., timeout during fetch), QuickJS may have lingering GC objects. Disposing the runtime in this state causes assertion errors.
+
+**Workaround:** Skip runtime disposal if lingering objects detected:
+
+```typescript
+const memUsage = runtime.dumpMemoryUsage();
+if (memUsage.includes(' resolve') || memUsage.includes(' promise')) {
+  logger?.warn?.('Detected lingering promise objects - skipping runtime disposal');
+  // Memory will leak, but process won't crash
+} else {
+  runtime.dispose();
+}
+```
+
+### Context Disposal
+
+Context must be disposed before runtime. If context disposal fails, runtime should not be disposed.
+
+### Promise Settlement
+
+Not all promises can be settled during cleanup (e.g., network timeout). After a timeout, remaining promises are abandoned.
+
+### Web API Gaps (Accepted)
+
+The following Web API features are intentionally not implemented. They are known gaps accepted as current limitations:
+
+- **`Response.clone()`** — Not supported. Body can only be consumed once; sandbox code cannot both stream and read text from the same response.
+- **`Request` constructor** — Not available. The `fetch` bridge accepts `(url, init)` directly. Sandbox code cannot create `Request` objects for more complex fetch patterns.
+- **`AbortController` / `AbortSignal`** — Not exposed to sandbox code. The fetch bridge creates its own `AbortController` internally for cleanup, but sandbox code cannot create or use `AbortController` to cancel its own requests. This may be implemented in the future.
+- **`ReadableStream.tee()`, `pipeTo()`, `pipeThrough()`** — Only `getReader()` is supported on ReadableStream. Advanced stream combinators are not bridged.
+
+## Best Practices
+
+1. **Always dispose handles**: Use try/finally to ensure cleanup
+2. **Track host objects**: Use registries for streams, responses, readers
+3. **Register cleanup handlers**: Abort streams, release readers
+4. **Check handle validity**: Use `handle.alive` before disposal
+5. **Log operations**: Use logger for debugging
+6. **Handle errors gracefully**: Context may be disposed during async operations
+7. **Use shared utilities**: Don't reinvent headers, response objects, etc.
+8. **Test cleanup**: Verify no handle leaks
+9. **Time-limit cleanup**: Prevent indefinite blocking
+10. **Follow patterns**: Use existing bridges as templates
+
+## See Also
+
+- [QuickJS Documentation](https://bellard.org/quickjs/)
+- [quickjs-emscripten](https://github.com/justjake/quickjs-emscripten)
+- [Bridges README](./bridges/README.md) - Detailed bridge development guide