@johnhenry/andbox 0.0.7 → 0.0.8

package/README.md

@@ -19,9 +19,12 @@ Zero dependencies. Uses only Web Workers and standard browser APIs.
 - [Install](#install)
 - [Quick Start](#quick-start)
 - [Sandbox Modes](#sandbox-modes)
+- [Node](#node)
+- [`mode: 'wasm'`](#mode-wasm)
 - [API](#api)
 - [Execution model](#execution-model)
 - [Security model](#security-model)
+- [Threat model by mode](#threat-model-by-mode)
 - [Family](#family)
 - [License](#license)
 
@@ -85,10 +88,11 @@ await sandbox.dispose();
 
 ## Sandbox Modes
 
-andbox supports five execution modes (any other `mode` throws an error listing these):
+andbox supports six execution modes (any other `mode` throws an error listing these):
 
 - **`worker`** (default) -- Runs in a dedicated Worker with an RPC bridge, import maps, virtual modules, and hard-kill timeout semantics. See [Security model](#security-model) for what this does and doesn't protect against.
 - **`node-worker`** -- The `worker` mode on `node:worker_threads`. Selected automatically under Node when there is no global `Worker`; see [Node](#node).
+- **`wasm`** -- Optional. Runs the code in QuickJS-ng compiled to WebAssembly *inside* the Worker (or worker thread), with `host.call` as the only authority and real memory, stack, fuel and deadline limits. The only mode that withholds the Worker's own globals (`fetch`, `WebSocket`, `importScripts`, ...). See [`mode: 'wasm'`](#mode-wasm).
 - **`inline`** -- Same-thread execution via AsyncFunction. Lighter weight, no Worker overhead, no isolation at all -- code runs with full access to the calling context. Only for code you already trust.
 - **`data-uri`** -- Dynamic `import()` via Blob URL (a `data:` URL under Node). Module-level separation without a Worker. Supports globals injection.
 - **`service-worker`** -- Not code execution at all: registers a Service Worker that serves an in-memory `path → content` map with real HTTP-shaped fetch/navigation semantics. For hosting a small virtual multi-file site (HTML/CSS/JS, arbitrary paths), not for running JS in isolation. See [andbox#14](https://github.com/johnhenry/andbox/issues/14) and [Security model](#security-model) -- this mode does **not** provide isolation by merely existing.
@@ -162,6 +166,82 @@ const sandbox = await createSandbox({
 - `mode: 'service-worker'` needs a browser and rejects under Node.
 - **A worker thread is not a security boundary** -- not by default and not with `nodeWorker.permissions`. By default sandboxed code can reach `process` (including `process.env`, `process.binding`, `process.getBuiltinModule('fs')`) and can `import('node:child_process')`. For untrusted code on a server add OS-level isolation (a separate process or container with its own filesystem, network and resource limits).
 
+## `mode: 'wasm'`
+
+`mode: 'wasm'` (added in 0.0.8, [andbox#21](https://github.com/johnhenry/andbox/issues/21)) is the "different execution strategy" the [Security model](#security-model) says `worker` mode is missing. The code you `evaluate()` is not run by the Worker's JavaScript engine at all: it runs in [QuickJS-ng](https://github.com/quickjs-ng/quickjs) compiled to WebAssembly, in the same Worker (browser) or `worker_thread` (Node) andbox already uses. A fresh QuickJS runtime and context is created for every `evaluate()`.
+
+The engine has no `fetch`, `WebSocket`, `XMLHttpRequest`, `importScripts`, `indexedDB`, `postMessage`, `self`, `Worker`, timers or `process`: they are not hidden, they simply do not exist in that engine. Its only way out is the single native function behind `host.call(name, ...args)`, which goes through the same `capabilityCall` message, `gateCapabilities()` and `policy` as worker mode. `sandboxImport()` and `import()` resolve **only** virtual modules (`defineModule()`); no URL is ever fetched.
+
+```js
+import { createSandbox } from '@johnhenry/andbox';
+
+const sandbox = await createSandbox({
+  mode: 'wasm',
+  capabilities: { readFile: async (path) => { /* host side */ } },
+  fuel: 50_000,              // interrupt polls, deterministic (default: unlimited)
+  memoryBytes: 32 * 1024 * 1024, // JS heap cap (default 64 MiB)
+  stackBytes: 128 * 1024,    // guest stack cap (default 128 KiB)
+  deadlineMs: 2_000,         // cooperative wall-clock deadline (default: the call's timeoutMs)
+});
+
+await sandbox.evaluate('return await host.call("readFile", "/etc/hostname")');
+```
+
+### Installing the engine (optional, pinned)
+
+The engine is an **optional** peer dependency, pinned to exact versions, so the default install stays dependency-free:
+
+```sh
+npm install --save-exact quickjs-emscripten-core@0.32.0 @jitl/quickjs-ng-wasmfile-release-sync@0.32.0
+```
+
+Without them `createSandbox({ mode: 'wasm' })` rejects with `ERR_ANDBOX_ENGINE_MISSING` and the install command above. Every other mode is unaffected.
+
+**Node:** nothing else to do. andbox finds the installed packages and the `.wasm` file itself.
+
+**Browser, no CDN:** the Worker needs two files from your own origin: the engine as one ES module, and the `.wasm` file. Build them once:
+
+```sh
+npx esbuild node_modules/@johnhenry/andbox/src/wasm-engine.mjs \
+  --bundle --format=esm --platform=browser --minify --outfile=public/andbox-quickjs.mjs
+cp node_modules/@jitl/quickjs-ng-wasmfile-release-sync/dist/emscripten-module.wasm public/andbox-quickjs.wasm
+```
+
+and point andbox at them (relative URLs resolve against `baseURL`, which defaults to the page URL):
+
+```js
+const sandbox = await createSandbox({
+  mode: 'wasm',
+  engineURL: '/andbox-quickjs.mjs',
+  wasmURL: '/andbox-quickjs.wasm',
+});
+```
+
+Or give them through the sandbox import map, so a page that already has one needs no new option: `importMap: { imports: { '@johnhenry/andbox/wasm-engine': '/andbox-quickjs.mjs', '@johnhenry/andbox/wasm': '/andbox-quickjs.wasm' } }`. Serve the `.wasm` as `application/wasm`. Size: about 54 KB for the engine module (15 KB gzipped) plus 528 KB for the `.wasm` (248 KB gzipped); the main `andbox` entry grows by about 10 KB minified (4 KB gzipped) for the extra worker source. `examples/08-wasm-browser/` is a complete working build + server + headless-Chrome check.
+
+### Limits
+
+| Option (sandbox or per `evaluate()` call) | What it does | Reported as |
+|---|---|---|
+| `fuel` | Budget of interrupt-handler polls (QuickJS polls about once per 10,000 VM operations). Counted, not timed, so the same code stops at the same count on every run. `sandbox.stats().fuelUsed` shows the last call's count. Guest code cannot catch it. | `FuelExhaustedError`, `code: 'ERR_ANDBOX_FUEL_EXHAUSTED'` |
+| `memoryBytes` | Cap on the guest JS heap (checked while the code runs, on a time budget of roughly 10% overhead) plus QuickJS's own limit, which rejects any single allocation above it. The engine's whole linear memory also gets a hard maximum of about `2 * memoryBytes + 32 MiB`, which is what actually bounds `ArrayBuffer` and similar allocations. | `MemoryLimitError`, `code: 'ERR_ANDBOX_MEMORY_LIMIT'` |
+| `stackBytes` | QuickJS call-stack cap. Overflow is an ordinary, catchable guest `RangeError`. | `RangeError` |
+| `deadlineMs` | Wall-clock deadline for the whole call, including time spent awaiting host calls. Checked in the interrupt handler and by a timer. The Worker survives; no respawn. Defaults to the call's `timeoutMs`. | `TimeoutError`, `code: 'ERR_ANDBOX_DEADLINE'` |
+| `timeoutMs` | Unchanged, but in this mode it is the **backstop**: the host `terminate()`s the Worker `max(timeoutMs, deadlineMs) + 1000 ms` after the call starts, which covers anything that stops the engine from polling. `AbortSignal` still terminates and restarts the Worker. | `TimeoutError` / `AbortError` |
+
+`stats()` additionally returns `fuelUsed`, `peakMemoryBytes` (sampled) and `totalFuelUsed`. The error classes are plain `Error`s with the `name` and `code` shown; `WASM_ERROR_CODES` exports the codes. An exception that escapes the engine itself (for example the host stack overflowing when `stackBytes` is set far above the default) is caught and reported as `EngineError` / `ERR_ANDBOX_ENGINE`; the engine is reloaded for the next call.
+
+### Differences from worker mode
+
+- `host.call` arguments and results, and the value you `return`, are JSON-serialised (worker mode uses structured clone). `undefined`, functions (`'[Function]'`) and `BigInt` (as a string) are handled as in worker mode; `Map`, `Set`, `Date` and typed arrays are not preserved.
+- Each `evaluate()` starts from a fresh global scope. Nothing set on `globalThis` survives; use `defineModule()` or the host for shared state.
+- `sandboxImport()` is limited to virtual modules (relative imports, bare names and import-map names that point at a virtual module name all work). An import map entry that points at a URL does not make that URL loadable.
+- Capability arguments are JSON, so a capability that expects non-JSON values will not get them.
+- Concurrent `evaluate()` calls on one sandbox share the Worker's single thread: a busy loop in one delays the others (their deadlines are wall-clock). Use one sandbox per tenant if that matters.
+- `nodeWorker.permissions` is rejected with this mode for now (the Worker has to read the engine from disk). The other `nodeWorker` options work.
+- A guest can catch the engine's out-of-memory error and keep running inside the cap; it cannot exceed the cap.
+- `Date`, `Math.random` and `performance` exist in the guest (QuickJS provides them from the host clock); see the threat model.
+
 ## API
 
 ### `createSandbox(options?)`
@@ -172,7 +252,7 @@ Creates a new sandboxed runtime. Returns a promise (Worker mode) or object (inli
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `mode` | `'worker' \| 'inline' \| 'data-uri'` | `'worker'` | Execution mode |
+| `mode` | `'worker' \| 'node-worker' \| 'wasm' \| 'inline' \| 'data-uri'` | `'worker'` | Execution mode |
 | `importMap` | `{ imports?, scopes? }` | `{}` | Import map for package resolution (Worker mode) |
 | `capabilities` | `Record<string, Function>` | `{}` | Host functions callable via `host.call()` (Worker mode) |
 | `defaultTimeoutMs` | `number` | `30000` | Default timeout for `evaluate()` |
@@ -180,6 +260,8 @@ Creates a new sandboxed runtime. Returns a promise (Worker mode) or object (inli
 | `policy` | `GatePolicy` | -- | Rate limiting policy |
 | `onConsole` | `(level, ...args) => void` | -- | Console output handler |
 | `globals` | `Record<string, any>` | `{}` | Global variables (inline/data-uri modes) |
+| `engineURL`, `wasmURL` | `string` | -- | `mode: 'wasm'`: same-origin URLs of the bundled engine module and the `.wasm` (optional under Node) |
+| `fuel`, `memoryBytes`, `stackBytes`, `deadlineMs` | `number` | see [Limits](#limits) | `mode: 'wasm'` limits (also accepted per `evaluate()` call) |
 
 **Returns (Worker mode):** `Promise<{ evaluate, defineModule, dispose, stats, isDisposed }>`
 
@@ -351,7 +433,7 @@ andbox is **not** a boundary against code that is actively trying to escape it.
 
 **What is still yours:**
 
-- **Worker-global APIs are directly reachable, regardless of `capabilities`.** Sandboxed code executes in a real Worker global scope, so `fetch`, `WebSocket`, `Worker` (nested workers), `importScripts`, `indexedDB`, and `self.postMessage` are all callable directly -- omitting a `fetch` capability does not block network access. This is fundamental to how `Function`-based evaluation works and isn't fixable without a different execution strategy (e.g. a cross-origin iframe with a strict CSP, or a Realms/Compartments-based approach). See [andbox#10](https://github.com/johnhenry/andbox/issues/10).
+- **Worker-global APIs are directly reachable, regardless of `capabilities`.** Sandboxed code executes in a real Worker global scope, so `fetch`, `WebSocket`, `Worker` (nested workers), `importScripts`, `indexedDB`, and `self.postMessage` are all callable directly -- omitting a `fetch` capability does not block network access. This is fundamental to how `Function`-based evaluation works and isn't fixable without a different execution strategy: [`mode: 'wasm'`](#mode-wasm) is that strategy (QuickJS in WebAssembly, no ambient authority), and a cross-origin iframe with a strict CSP is another. See [andbox#10](https://github.com/johnhenry/andbox/issues/10).
 - **`sandboxImport()` will load and execute an arbitrary remote URL.** Any `http(s)://` specifier is passed straight to `import()` with no allowlist, independent of any network policy configured for capabilities. See [andbox#7](https://github.com/johnhenry/andbox/issues/7).
 - **A timeout stops message delivery, not in-flight host-side effects.** If a capability call with a real side effect (a write, an API call) is in flight when the timeout fires, that side effect still completes on the host even though the Worker is killed. Capabilities with real side effects should be designed to be idempotent and/or cancellable via `AbortSignal`. See [andbox#8](https://github.com/johnhenry/andbox/issues/8).
 - **`mode: 'service-worker'` does not provide isolation by merely existing.** It's a hosting mechanism -- a real Service Worker, same-origin by default, serving your `files` map with real fetch/navigation interception. Content served through it can see and touch its own origin exactly like any other same-origin page can; nothing about registering a Service Worker sandboxes what runs inside the pages it serves. If you're hosting content you don't fully trust, point this mode at a genuinely separate origin from day one -- the same recommendation the `fetch`/`WebSocket`/`Worker` item above makes for `worker` mode (a cross-origin iframe with a strict CSP), not something bolted on after the fact. See [andbox#14](https://github.com/johnhenry/andbox/issues/14).
@@ -359,6 +441,33 @@ andbox is **not** a boundary against code that is actively trying to escape it.
 
 If you need to run untrusted/adversarial code safely, andbox alone is not sufficient -- pair it with OS-level isolation (a separate process/container with its own network and filesystem restrictions) or use a purpose-built sandboxing runtime. Capability gating and rate limits here are for organizing and throttling code you already trust, not for containing code you don't.
 
+## Threat model by mode
+
+What each mode is built to stop, and what it is not. "Hostile" means code actively trying to escape or abuse the host.
+
+| | `worker` / `node-worker` | `wasm` |
+|---|---|---|
+| **Runs in** | The Worker's own JS engine (`new Function`) | QuickJS-ng compiled to WebAssembly, inside the Worker / worker thread |
+| **Reaching `fetch`, `WebSocket`, `importScripts`, `indexedDB`, `postMessage`** | Possible. They are Worker globals the code can call. | Not possible. The engine has no such globals, and `constructor`/`eval`/`Function` chains only reach the guest realm. |
+| **Forging protocol messages to the host** | Possible in principle (`self.postMessage`); ids are random, which only slows a guess. | Not possible. The guest has no `postMessage` or `self`. |
+| **`sandboxImport` of arbitrary URLs / Node builtins** | Loaded and executed (browser) or blocked only with `nodeWorker.permissions` (Node). | Refused: only virtual modules resolve; no URL is fetched. |
+| **Prototype-chain names via `host.call`** | Closed by the capability gate (`Object.create(null)`). | Same gate, plus the guest never sees host objects. |
+| **Infinite loops** | `terminate()` after `timeoutMs`, then a new Worker. | Deterministic `fuel` and a wall-clock `deadlineMs` stop it without a respawn; `terminate()` remains the backstop. |
+| **Memory exhaustion** | Browser: nothing but the tab limit. Node: opt-in `nodeWorker.maxMemoryMb`. | Guest heap cap plus a hard cap on the engine's linear memory. |
+| **Deep recursion** | Engine stack limit of the host JS engine. | `stackBytes`; overflow is a catchable `RangeError`. |
+| **Capability abuse** | `gateCapabilities()` rate and size limits (cooperative callers). | Same. |
+
+**What `wasm` mode does not defend against**
+
+- **Bugs in QuickJS-ng or in the WebAssembly engine.** A memory-safety bug in QuickJS is confined to the module's linear memory, but a bug in the browser's WebAssembly implementation is a browser sandbox escape. Keep browsers and Node updated; pinning the engine version here is a reproducibility choice, not a security update channel.
+- **What your capabilities do.** `host.call` is the whole attack surface. A capability that reads any path, fetches any URL, or evals what it is given is an escape hatch by design. Validate arguments host-side, and keep side-effecting capabilities idempotent: a deadline or restart does not undo a host call already in flight ([andbox#8](https://github.com/johnhenry/andbox/issues/8)).
+- **Timing and side channels.** QuickJS exposes `Date.now()` and `performance.now()` from the host clock, so a guest can measure time and mount timing attacks on anything the host does in response. andbox does not coarsen those clocks. (QuickJS has no threads, so there is no shared-memory clock on top of them.)
+- **Denial of service beyond the limits.** Fuel, memory and deadline bound one `evaluate()`; they do not bound how many you start, how big a capability result is, or CPU time spent *inside* the host while serving a call. Concurrent calls share one thread.
+- **The host trusting the result.** Return values are plain JSON from untrusted code; treat them as untrusted input.
+- **`nodeWorker.permissions`** is not available in this mode, and a worker thread still shares the process. For hostile code on a server, add OS-level isolation as the [Security model](#security-model) says.
+
+**What `worker` and `node-worker` do not defend against** is the "What is still yours" list in the [Security model](#security-model): they are for code you trust to be well-behaved, not for containing code that is trying to get out. `inline` and `data-uri` provide no isolation at all.
+
 ## Family
 
 andbox isn't just a standalone sandbox runtime -- it's the sandboxing engine

package/package.json

@@ -1,15 +1,19 @@
 {
   "name": "@johnhenry/andbox",
-  "version": "0.0.7",
+  "version": "0.0.8",
   "type": "module",
-  "description": "Sandboxed JavaScript runtime with Worker isolation, RPC, import maps, and timeouts",
+  "description": "Sandboxed JavaScript runtime with Worker isolation, RPC, import maps, timeouts, and an optional QuickJS-in-WebAssembly mode",
   "main": "./src/index.mjs",
   "types": "./src/index.d.ts",
   "exports": {
     ".": {
       "types": "./src/index.d.ts",
       "import": "./src/index.mjs"
-    }
+    },
+    "./wasm-engine": {
+      "import": "./src/wasm-engine.mjs"
+    },
+    "./package.json": "./package.json"
   },
   "files": [
     "src",
@@ -23,7 +27,10 @@
     "example:03": "node examples/03-network-allowlist-blocks-unapproved-hosts.mjs",
     "example:04": "node examples/04-runaway-code-gets-timed-out.mjs",
     "example:05": "node examples/05-virtual-module-registry-resolves-a-multi-file-tree.mjs",
-    "examples": "npm run example:01 && npm run example:02 && npm run example:03 && npm run example:04 && npm run example:05"
+    "examples": "npm run example:01 && npm run example:02 && npm run example:03 && npm run example:04 && npm run example:05 && npm run example:07",
+    "example:07": "node examples/07-wasm-mode-contains-hostile-code.mjs",
+    "example:08:build": "node examples/08-wasm-browser/build.mjs",
+    "example:08:headless": "node examples/08-wasm-browser/build.mjs && node examples/08-wasm-browser/run-headless.mjs"
   },
   "keywords": [
     "sandbox",
@@ -31,7 +38,9 @@
     "isolation",
     "rpc",
     "browser",
-    "javascript"
+    "javascript",
+    "wasm",
+    "quickjs"
   ],
   "license": "MIT",
   "repository": {
@@ -43,8 +52,22 @@
     "node": ">=26.0.0"
   },
   "devDependencies": {
+    "@jitl/quickjs-ng-wasmfile-release-sync": "0.32.0",
     "esbuild": "^0.28.2",
+    "quickjs-emscripten-core": "0.32.0",
     "vite": "^8.3.3",
     "webpack": "^5.111.1"
+  },
+  "peerDependencies": {
+    "@jitl/quickjs-ng-wasmfile-release-sync": "0.32.0",
+    "quickjs-emscripten-core": "0.32.0"
+  },
+  "peerDependenciesMeta": {
+    "@jitl/quickjs-ng-wasmfile-release-sync": {
+      "optional": true
+    },
+    "quickjs-emscripten-core": {
+      "optional": true
+    }
   }
 }

package/src/index.d.ts

@@ -300,6 +300,14 @@ export interface EvaluateOptions {
   signal?: AbortSignal;
   /** Console output handler for this evaluation (overrides sandbox-level handler). */
   onConsole?: (level: string, ...args: string[]) => void;
+  /** `mode: 'wasm'` only: fuel for this call (overrides the sandbox option). */
+  fuel?: number;
+  /** `mode: 'wasm'` only: JS heap cap in bytes for this call. */
+  memoryBytes?: number;
+  /** `mode: 'wasm'` only: guest stack cap in bytes for this call. */
+  stackBytes?: number;
+  /** `mode: 'wasm'` only: cooperative wall-clock deadline for this call (default: `timeoutMs`). */
+  deadlineMs?: number;
 }
 
 /** Options for createSandbox(). */
@@ -321,8 +329,44 @@ export interface SandboxOptions {
    * `node:worker_threads` automatically when run under Node with no global
    * `Worker`. `'node-worker'` forces the Node implementation.
    */
-  mode?: 'worker' | 'node-worker';
-  // Any other value throws: supported modes are 'worker', 'node-worker', 'inline', 'data-uri', 'service-worker'.
+  mode?: 'worker' | 'node-worker' | 'wasm';
+  // Any other value throws: supported modes are 'worker', 'node-worker', 'wasm', 'inline', 'data-uri', 'service-worker'.
+  /**
+   * `mode: 'wasm'` only. URL of an ES module built from
+   * `@johnhenry/andbox/wasm-engine` (the QuickJS engine entry), served from
+   * your own origin. Optional under Node (the installed optional packages
+   * are used); required in a browser. May also be given as the import map
+   * entry `@johnhenry/andbox/wasm-engine`.
+   */
+  engineURL?: string;
+  /**
+   * `mode: 'wasm'` only. URL of the QuickJS `.wasm` file (from
+   * `@jitl/quickjs-ng-wasmfile-release-sync`), served from your own origin.
+   * May also be given as the import map entry `@johnhenry/andbox/wasm`.
+   */
+  wasmURL?: string;
+  /**
+   * `mode: 'wasm'` only. Fuel budget: the number of interrupt-handler polls
+   * (one roughly every 10,000 VM operations) the code may use before it is
+   * stopped with a `FuelExhaustedError`. Deterministic for the same code.
+   * Default 0 (unlimited; the deadline still applies).
+   */
+  fuel?: number;
+  /**
+   * `mode: 'wasm'` only. Cap in bytes on the guest's JS heap, plus a hard cap
+   * of about `2 * memoryBytes + 32 MiB` on the engine's total linear memory.
+   * Default 64 MiB. 0 disables the soft cap and uses the 2 GiB engine maximum.
+   */
+  memoryBytes?: number;
+  /** `mode: 'wasm'` only. Guest call-stack cap in bytes. Default 128 KiB (raising it far enough overflows the host stack; that is caught and reported as an EngineError). */
+  stackBytes?: number;
+  /**
+   * `mode: 'wasm'` only. Cooperative wall-clock deadline in ms for each
+   * `evaluate()`; exceeding it rejects with `TimeoutError` and the Worker
+   * survives. Default: the call's `timeoutMs`. `timeoutMs` then acts as the
+   * hard-kill backstop (`terminate()`) a little later.
+   */
+  deadlineMs?: number;
   /**
    * Supply the Worker implementation: given the worker script source, return
    * a Web-Worker-shaped object. Overrides automatic selection. See
@@ -394,8 +438,29 @@ export interface SandboxStats {
   pendingEvaluations: number;
   virtualModules: string[];
   gate: GateStatsResult;
+  /** `mode: 'wasm'` only: interrupt polls used by the most recent evaluate(). */
+  fuelUsed?: number;
+  /** `mode: 'wasm'` only: peak sampled JS heap bytes seen so far. */
+  peakMemoryBytes?: number;
+  /** `mode: 'wasm'` only: interrupt polls used across all evaluate() calls. */
+  totalFuelUsed?: number;
 }
 
+/**
+ * `mode: 'wasm'` failure codes, set as `error.code` (and `error.name` is the
+ * key): fuel ran out, the heap cap was hit, the deadline passed, or the
+ * engine could not be loaded / faulted.
+ */
+export declare const WASM_ERROR_CODES: Readonly<{
+  FuelExhaustedError: 'ERR_ANDBOX_FUEL_EXHAUSTED';
+  MemoryLimitError: 'ERR_ANDBOX_MEMORY_LIMIT';
+  TimeoutError: 'ERR_ANDBOX_DEADLINE';
+  EngineError: 'ERR_ANDBOX_ENGINE';
+}>;
+
+/** The Worker script for `mode: 'wasm'`, as a string. */
+export declare function makeWasmWorkerSource(): string;
+
 /** A sandboxed JavaScript runtime instance. */
 export interface Sandbox {
   /**

package/src/index.mjs

@@ -13,6 +13,7 @@ export { createNetworkFetch } from './network-policy.mjs';
 export { makeDeferred, makeAbortError, makeTimeoutError } from './deferred.mjs';
 export { DEFAULT_TIMEOUT_MS, DEFAULT_LIMITS, DEFAULT_CAPABILITY_LIMITS } from './constants.mjs';
 export { makeWorkerSource } from './worker-source.mjs';
+export { makeWasmWorkerSource, WASM_ERROR_CODES } from './wasm-worker-source.mjs';
 export { makeServiceWorkerSource } from './service-worker-source.mjs';
 export { resolveServiceWorkerResponse } from './service-worker-response.mjs';
 export { createNodeWorkerFactory } from './node-worker.mjs';

package/src/node-wasm.mjs

@@ -0,0 +1,26 @@
+/**
+ * Node-only helper for `mode: 'wasm'`: locate the engine entry and the `.wasm`
+ * file from the installed optional peer dependencies. Loaded with a
+ * non-literal dynamic `import()` (see sandbox.mjs) so browser bundles never
+ * follow it.
+ */
+
+const INSTALL_HINT =
+  "mode: 'wasm' needs the optional engine packages. Install them with:\n" +
+  '  npm install --save-exact quickjs-emscripten-core@0.32.0 @jitl/quickjs-ng-wasmfile-release-sync@0.32.0';
+
+/**
+ * @returns {{ engineURL: string, wasmURL: string }} `file:` URLs.
+ * @throws {Error} with an install hint when the packages are missing.
+ */
+export function resolveNodeWasmEngine() {
+  try {
+    import.meta.resolve('quickjs-emscripten-core');
+    const wasmURL = import.meta.resolve('@jitl/quickjs-ng-wasmfile-release-sync/wasm');
+    return { engineURL: new URL('./wasm-engine.mjs', import.meta.url).href, wasmURL };
+  } catch (e) {
+    const err = new Error(`${INSTALL_HINT}\n(${e?.message ?? e})`);
+    err.code = 'ERR_ANDBOX_ENGINE_MISSING';
+    throw err;
+  }
+}

package/src/sandbox.mjs

@@ -11,6 +11,8 @@
  */
 
 import { makeWorkerSource } from './worker-source.mjs';
+import { makeWasmWorkerSource } from './wasm-worker-source.mjs';
+import { resolveWithImportMap } from './import-map-resolver.mjs';
 import { gateCapabilities } from './capability-gate.mjs';
 import { makeDeferred, makeTimeoutError, makeAbortError } from './deferred.mjs';
 import { DEFAULT_TIMEOUT_MS } from './constants.mjs';
@@ -305,7 +307,7 @@ async function createServiceWorkerSandbox(options = {}) {
  * @property {(level: string, ...args: string[]) => void} [onConsole] - Console output handler
  */
 
-const SUPPORTED_MODES = ['worker', 'node-worker', 'inline', 'data-uri', 'service-worker'];
+const SUPPORTED_MODES = ['worker', 'node-worker', 'wasm', 'inline', 'data-uri', 'service-worker'];
 
 /**
  * Create a new sandboxed runtime.
@@ -324,10 +326,73 @@ export function createSandbox(options = {}) {
   if (mode === 'inline') return createInlineSandbox(options);
   if (mode === 'data-uri') return createDataUriSandbox(options);
   if (mode === 'service-worker') return createServiceWorkerSandbox(options);
-  return createWorkerSandbox(options, mode === 'node-worker');
+  return createWorkerSandbox(options, mode === 'node-worker', mode === 'wasm');
 }
 
-async function createWorkerSandbox(options = {}, forceNode = false) {
+/** Default limits for `mode: 'wasm'` (0 = unlimited / not enforced). */
+const WASM_DEFAULTS = Object.freeze({
+  fuel: 0,
+  memoryBytes: 64 * 1024 * 1024,
+  stackBytes: 128 * 1024,
+});
+
+/**
+ * Extra grace (ms) the host's hard-kill backstop waits beyond the in-worker
+ * deadline, so a cooperative TimeoutError wins over terminate() + respawn.
+ */
+const WASM_BACKSTOP_GRACE_MS = 1000;
+
+function checkLimit(name, value) {
+  if (value === undefined) return;
+  if (!(typeof value === 'number' && Number.isFinite(value) && value >= 0)) {
+    throw new Error(`${name} must be a non-negative number (0 disables it); got ${String(value)}`);
+  }
+}
+
+/**
+ * Work out where the Worker should load the engine and `.wasm` from, and
+ * validate the limit options. Under Node the installed optional packages are
+ * used when no URLs are given; in a browser the URLs (or import map entries
+ * `@johnhenry/andbox/wasm-engine` / `@johnhenry/andbox/wasm`) are required.
+ */
+async function resolveWasmConfig(options, baseURL, usingNode) {
+  const { engineURL, wasmURL, fuel, memoryBytes, stackBytes, deadlineMs, importMap } = options;
+  checkLimit('fuel', fuel);
+  checkLimit('memoryBytes', memoryBytes);
+  checkLimit('stackBytes', stackBytes);
+  checkLimit('deadlineMs', deadlineMs);
+
+  const abs = (u) => (u == null ? null : new URL(u, baseURL).href);
+  let engine = abs(engineURL ?? resolveWithImportMap('@johnhenry/andbox/wasm-engine', importMap));
+  let wasm = abs(wasmURL ?? resolveWithImportMap('@johnhenry/andbox/wasm', importMap));
+
+  if (!engine && (usingNode || isNodeRuntime())) {
+    // Non-literal specifier: browser bundlers must not follow this Node-only file.
+    const spec = './node-' + 'wasm.mjs';
+    const { resolveNodeWasmEngine } = await import(/* @vite-ignore */ /* webpackIgnore: true */ spec);
+    const found = resolveNodeWasmEngine();
+    engine = found.engineURL;
+    wasm = wasm ?? found.wasmURL;
+  }
+  if (!engine || !wasm) {
+    throw new Error(
+      "createSandbox({ mode: 'wasm' }) needs `engineURL` (an ES module built from " +
+      "@johnhenry/andbox/src/wasm-engine.mjs) and `wasmURL` (the QuickJS .wasm file), both served " +
+      'from your own origin. See the README section on mode: wasm for the two-command setup.'
+    );
+  }
+  return {
+    engine: { engineURL: engine, wasmURL: wasm },
+    limits: {
+      fuel: fuel ?? WASM_DEFAULTS.fuel,
+      memoryBytes: memoryBytes ?? WASM_DEFAULTS.memoryBytes,
+      stackBytes: stackBytes ?? WASM_DEFAULTS.stackBytes,
+      deadlineMs, // undefined -> the per-evaluate timeout
+    },
+  };
+}
+
+async function createWorkerSandbox(options = {}, forceNode = false, isWasm = false) {
   const {
     importMap = { imports: {}, scopes: {} },
     capabilities = {},
@@ -356,6 +421,20 @@ async function createWorkerSandbox(options = {}, forceNode = false) {
     );
   }
 
+  // mode: 'wasm' -- resolve the engine location and limits up front so a
+  // missing optional dependency fails here, with an install hint.
+  let wasmConfig = null;
+  if (isWasm) {
+    if (nodeWorker?.permissions) {
+      throw new Error(
+        "nodeWorker.permissions is not supported with mode: 'wasm' yet: the Worker has to read the " +
+        'engine and .wasm file from disk, which the permission model blocks. The WASM engine is the ' +
+        'isolation layer in this mode; see the README threat model.'
+      );
+    }
+    wasmConfig = await resolveWasmConfig(options, baseURL, usingNode);
+  }
+
   // Gate capabilities with rate limits
   const { gated: gatedCaps, stats: gateStats } = gateCapabilities(capabilities, policy);
 
@@ -382,10 +461,13 @@ async function createWorkerSandbox(options = {}, forceNode = false) {
   // Pending evaluations
   const pending = new Map(); // id -> { resolve, reject, timer }
 
+  // mode: 'wasm' bookkeeping (stats() adds these)
+  const wasmStats = { fuelUsed: 0, peakMemoryBytes: 0, totalFuelUsed: 0 };
+
   // ── Worker lifecycle ──
 
   function createWorker() {
-    const source = makeWorkerSource();
+    const source = isWasm ? makeWasmWorkerSource() : makeWorkerSource();
     if (workerFactory) {
       worker = workerFactory(source);
       attachWorkerHandlers();
@@ -411,11 +493,17 @@ async function createWorkerSandbox(options = {}, forceNode = false) {
           if (entry) {
             pending.delete(msg.id);
             if (entry.timer) clearTimeout(entry.timer);
+            if (msg.stats) {
+              wasmStats.fuelUsed = msg.stats.fuelUsed;
+              wasmStats.totalFuelUsed += msg.stats.fuelUsed;
+              wasmStats.peakMemoryBytes = Math.max(wasmStats.peakMemoryBytes, msg.stats.peakMemoryBytes);
+            }
             if (msg.success) {
               entry.resolve(msg.value);
             } else {
               const err = new Error(msg.error?.message || 'Evaluation failed');
               err.name = msg.error?.name || 'Error';
+              if (msg.error?.code) err.code = msg.error.code;
               entry.reject(err);
             }
           }
@@ -437,6 +525,9 @@ async function createWorkerSandbox(options = {}, forceNode = false) {
     };
 
     worker.onerror = (e) => {
+      // A Worker that fails while starting up (script error, engine load
+      // failure) must reject createSandbox()/restart instead of hanging it.
+      if (rejectConfigure) rejectConfigure(new Error(`Worker error: ${e.message}`));
       // Reject all pending on Worker error
       for (const [id, entry] of pending) {
         pending.delete(id);
@@ -446,12 +537,20 @@ async function createWorkerSandbox(options = {}, forceNode = false) {
     };
   }
 
+  let rejectConfigure = null;
   async function configureWorker() {
-    const { promise, resolve } = makeDeferred();
+    const { promise, resolve, reject } = makeDeferred();
+    rejectConfigure = reject;
     const handler = ({ data }) => {
       if (data.type === 'configured') {
         worker.removeEventListener('message', handler);
-        resolve();
+        if (data.error) {
+          const err = new Error(`Failed to load the WASM engine: ${data.error.message}`);
+          err.code = 'ERR_ANDBOX_ENGINE';
+          reject(err);
+        } else {
+          resolve();
+        }
       }
     };
     worker.addEventListener('message', handler);
@@ -460,8 +559,14 @@ async function createWorkerSandbox(options = {}, forceNode = false) {
       importMap,
       baseURL,
       virtualModules: Object.fromEntries(virtualModules),
+      ...(wasmConfig ? { wasm: { ...wasmConfig.engine, memoryBytes: wasmConfig.limits.memoryBytes } } : {}),
     });
-    await promise;
+    try {
+      await promise;
+    } finally {
+      rejectConfigure = null;
+      worker?.removeEventListener('message', handler);
+    }
   }
 
   async function handleCapabilityCall(rpcId, name, args) {
@@ -522,6 +627,9 @@ async function createWorkerSandbox(options = {}, forceNode = false) {
    */
   async function evaluate(code, opts = {}) {
     if (disposed) throw new Error('Sandbox is disposed');
+    if (wasmConfig) {
+      for (const k of ['fuel', 'memoryBytes', 'stackBytes', 'deadlineMs']) checkLimit(k, opts[k]);
+    }
     if (!worker || worker.dead) await restartWorker();
     beginOp();
 
@@ -538,14 +646,31 @@ async function createWorkerSandbox(options = {}, forceNode = false) {
       activeConsoleHandler = opts.onConsole;
     }
 
+    // mode: 'wasm' -- limits travel with the call. The in-worker deadline
+    // (default: this call's timeoutMs) ends a busy loop gracefully; the
+    // host-side timer below becomes a hard-kill backstop a little later.
+    let wasmLimits = null;
+    let backstopMs = timeoutMs;
+    if (wasmConfig) {
+      const base = wasmConfig.limits;
+      const deadline = opts.deadlineMs ?? base.deadlineMs ?? (timeoutMs > 0 ? timeoutMs : 0);
+      wasmLimits = {
+        fuel: opts.fuel ?? base.fuel,
+        memoryBytes: opts.memoryBytes ?? base.memoryBytes,
+        stackBytes: opts.stackBytes ?? base.stackBytes,
+        deadlineMs: deadline,
+      };
+      if (timeoutMs > 0) backstopMs = Math.max(timeoutMs, deadline) + WASM_BACKSTOP_GRACE_MS;
+    }
+
     let timer = null;
-    if (timeoutMs > 0) {
+    if (backstopMs > 0) {
       timer = setTimeout(() => {
         pending.delete(id);
         reject(makeTimeoutError(timeoutMs));
         // Hard kill and restart — only reliable way to stop infinite loops
         restartWorker().catch(() => {});
-      }, timeoutMs);
+      }, backstopMs);
     }
 
     // AbortSignal support
@@ -567,7 +692,7 @@ async function createWorkerSandbox(options = {}, forceNode = false) {
     }
 
     pending.set(id, { resolve, reject, timer });
-    worker.postMessage({ type: 'evaluate', id, code });
+    worker.postMessage({ type: 'evaluate', id, code, ...(wasmLimits ? { limits: wasmLimits } : {}) });
 
     // Restore console handler when evaluation completes
     return promise.finally(() => {
@@ -628,6 +753,7 @@ async function createWorkerSandbox(options = {}, forceNode = false) {
       pendingEvaluations: pending.size,
       virtualModules: [...virtualModules.keys()],
       gate: gateStats(),
+      ...(wasmConfig ? { fuelUsed: wasmStats.fuelUsed, peakMemoryBytes: wasmStats.peakMemoryBytes, totalFuelUsed: wasmStats.totalFuelUsed } : {}),
     };
   }
 
@@ -636,6 +762,10 @@ async function createWorkerSandbox(options = {}, forceNode = false) {
   try {
     createWorker();
     await configureWorker();
+  } catch (e) {
+    // e.g. the WASM engine failed to load: do not leave the thread running.
+    terminateWorker();
+    throw e;
   } finally {
     endOp();
   }

package/src/wasm-engine.mjs

@@ -0,0 +1,20 @@
+/**
+ * Engine entry for `mode: 'wasm'` (andbox#21).
+ *
+ * This is the module the Worker `import()`s to get QuickJS-ng. It re-exports
+ * exactly what the Worker needs from the two OPTIONAL peer dependencies
+ * (`quickjs-emscripten-core` and `@jitl/quickjs-ng-wasmfile-release-sync`,
+ * both pinned to an exact version).
+ *
+ * Under Node, andbox imports this file directly. In a browser, bundle it into
+ * one same-origin ES module and serve it next to the `.wasm` file -- see the
+ * README's "mode: 'wasm'" section -- then pass `engineURL` and `wasmURL`:
+ *
+ *   npx esbuild node_modules/@johnhenry/andbox/src/wasm-engine.mjs \
+ *     --bundle --format=esm --minify --outfile=public/andbox-quickjs.mjs
+ *
+ * Nothing here is imported by the main entry (`src/index.mjs`), so the
+ * default entry stays dependency-free.
+ */
+export { newQuickJSWASMModuleFromVariant, newVariant } from 'quickjs-emscripten-core';
+export { default as variant } from '@jitl/quickjs-ng-wasmfile-release-sync';

package/src/wasm-worker-source.mjs

@@ -0,0 +1,494 @@
+/**
+ * Worker source for `mode: 'wasm'` (andbox#21).
+ *
+ * The worker script is the function below, stringified. The user's code never
+ * runs in this Worker's JavaScript realm: it runs inside QuickJS-ng compiled
+ * to WebAssembly (one runtime + context per `evaluate()`), whose only way out
+ * is the single native function behind `host.call`. The Worker's own globals
+ * (`fetch`, `WebSocket`, `importScripts`, `indexedDB`, `postMessage`, ...) are
+ * simply not present in that engine.
+ *
+ * Protocol (same message types as the plain worker script, plus a few
+ * fields): the host sends `configure` (with `wasm: { engineURL, wasmURL }`),
+ * `defineModule`, `evaluate` (with `limits`), `capabilityResult`, `dispose`;
+ * the Worker sends `configured` (with `error` if the engine failed to load),
+ * `moduleDefined`, `result` (with `stats` and, for failures, `error.code`),
+ * `capabilityCall`, `console`.
+ *
+ * The function must stay self-contained (no free variables): it is inlined as
+ * text via `Function.prototype.toString`, exactly like `installNodeVfs`.
+ */
+
+/** Error codes carried on `result.error.code` and on the rejected Error. */
+export const WASM_ERROR_CODES = Object.freeze({
+  FuelExhaustedError: 'ERR_ANDBOX_FUEL_EXHAUSTED',
+  MemoryLimitError: 'ERR_ANDBOX_MEMORY_LIMIT',
+  TimeoutError: 'ERR_ANDBOX_DEADLINE',
+  EngineError: 'ERR_ANDBOX_ENGINE',
+});
+
+function wasmWorkerMain() {
+  'use strict';
+
+  const CODES = {
+    FuelExhaustedError: 'ERR_ANDBOX_FUEL_EXHAUSTED',
+    MemoryLimitError: 'ERR_ANDBOX_MEMORY_LIMIT',
+    TimeoutError: 'ERR_ANDBOX_DEADLINE',
+    EngineError: 'ERR_ANDBOX_ENGINE',
+  };
+  const RESOLVE_FAILED = 'andbox:resolve-failed:';
+  const PAGE = 65536;
+  const INITIAL_PAGES = 256; // 16 MiB, what the engine build asks for
+  const MAX_PAGES = 32768; // 2 GiB, the wasm32 / engine-build ceiling
+  const HARD_CAP_BASE_BYTES = 32 * 1024 * 1024;
+
+  let importMap = { imports: {}, scopes: {} };
+  const virtualModules = new Map();
+  let config = null; // { engineURL, wasmURL }
+  let enginePromise = null;
+  const pendingRpc = new Map();
+  const live = new Set(); // abort functions for in-flight evaluations
+  let rpcSeq = 0;
+
+  // ── Engine ──
+
+  async function loadEngine() {
+    const eng = await import(config.engineURL);
+    // Hard cap on the engine's linear memory. QuickJS's own memory limit only
+    // counts allocation *blocks* in this build (no malloc_usable_size), so it
+    // cannot bound total bytes; the wasm memory maximum can, and a failed
+    // grow surfaces in the guest as an out-of-memory error.
+    const maxPages = config.memoryBytes > 0
+      ? Math.min(MAX_PAGES, Math.max(INITIAL_PAGES, Math.ceil((2 * config.memoryBytes + HARD_CAP_BASE_BYTES) / PAGE)))
+      : MAX_PAGES;
+    const variant = eng.newVariant(eng.variant, {
+      ...(config.wasmURL ? { wasmLocation: config.wasmURL } : {}),
+      wasmMemory: new WebAssembly.Memory({ initial: INITIAL_PAGES, maximum: maxPages }),
+    });
+    return eng.newQuickJSWASMModuleFromVariant(variant);
+  }
+
+  function getEngine() {
+    if (!enginePromise) {
+      enginePromise = loadEngine().catch((e) => {
+        enginePromise = null;
+        throw e;
+      });
+    }
+    return enginePromise;
+  }
+
+  // ── Guest bootstrap (runs inside QuickJS, not in this Worker) ──
+  // Receives the two native bridge functions as arguments, so they are never
+  // reachable as globals. Everything else is plain JS.
+  function guestBoot(nativeCall, nativeLog) {
+    const stringify = JSON.stringify;
+    const parse = JSON.parse;
+    const str = String;
+    const fmt = (a) => {
+      try {
+        if (typeof a !== 'object') return str(a);
+        const s = stringify(a);
+        return s === undefined ? str(a) : s;
+      } catch {
+        return str(a);
+      }
+    };
+    const log = (level) => (...args) => {
+      nativeLog(level, stringify(args.map(fmt)));
+    };
+    const consoleObj = {
+      log: log('log'), warn: log('warn'), error: log('error'),
+      info: log('info'), debug: log('debug'),
+    };
+    globalThis.console = consoleObj;
+    const host = Object.freeze({
+      call: async (name, ...args) => {
+        const r = await nativeCall(str(name), stringify(args));
+        return r === '' ? undefined : parse(r);
+      },
+    });
+    const sandboxImport = (specifier) => import(str(specifier));
+    const ser = (v) => {
+      if (v === undefined) return '{"t":"u"}';
+      if (typeof v === 'function') return '{"t":"v","v":"[Function]"}';
+      try {
+        const s = stringify(v);
+        if (s !== undefined) return '{"t":"v","v":' + s + '}';
+      } catch {}
+      try { return stringify({ t: 'v', v: str(v) }); } catch { return '{"t":"v","v":"[object]"}'; }
+    };
+    return { host, sandboxImport, ser, console: consoleObj };
+  }
+
+  // ── Virtual modules for the in-guest module loader ──
+
+  function lookupModule(name) {
+    const bare = name.replace(/\.m?js$/, '');
+    for (const cand of [name, name + '.js', name + '.mjs', name + '/index.js', bare]) {
+      if (virtualModules.has(cand)) return cand;
+    }
+    return null;
+  }
+
+  function mapSpecifier(specifier) {
+    const m = importMap.imports || {};
+    if (m[specifier] !== undefined) return m[specifier];
+    let best = null;
+    for (const key of Object.keys(m)) {
+      if (key.endsWith('/') && specifier.startsWith(key) && (best === null || key.length > best.length)) best = key;
+    }
+    return best === null ? null : m[best] + specifier.slice(best.length);
+  }
+
+  function normalizeModule(base, requested) {
+    let name = null;
+    if (requested.startsWith('./') || requested.startsWith('../')) {
+      const parts = (lookupModule(base) ?? base).split('/');
+      parts.pop();
+      for (const seg of requested.split('/')) {
+        if (seg === '..') parts.pop();
+        else if (seg !== '.' && seg !== '') parts.push(seg);
+      }
+      name = lookupModule(parts.join('/'));
+    } else {
+      name = lookupModule(requested);
+      if (name === null) {
+        const mapped = mapSpecifier(requested);
+        if (mapped !== null) name = lookupModule(mapped);
+      }
+    }
+    if (name === null) {
+      throw new Error(
+        'Cannot resolve module: ' + requested +
+        ". In mode: 'wasm' only virtual modules (defineModule) can be imported; URLs are never fetched."
+      );
+    }
+    return name;
+  }
+
+  // ── Evaluation ──
+
+  function errorFrom(name, message) {
+    return { name, message, code: CODES[name] };
+  }
+
+  async function runEval(msg) {
+    const limits = msg.limits || {};
+    let QJS;
+    try {
+      QJS = await getEngine();
+    } catch (e) {
+      return { success: false, error: errorFrom('EngineError', 'Failed to load the WASM engine: ' + (e?.message ?? e)) };
+    }
+
+    return new Promise((resolveEval) => {
+      const t0 = Date.now();
+      const deadlineAt = limits.deadlineMs > 0 ? t0 + limits.deadlineMs : 0;
+      let polls = 0;
+      let peak = 0;
+      let fuelHit = false;
+      let deadlineHit = false;
+      let done = false;
+      let timer = null;
+      let rt = null;
+      let ctx = null;
+      const owned = []; // handles to dispose, in creation order
+      const own = (h) => { owned.push(h); return h; };
+      const rpcIds = new Set();
+      const deferreds = new Set();
+
+      let memHit = false;
+      let nextSampleAt = 0;
+      // JS heap bytes in use right now, or -1 if the usage report itself could
+      // not be allocated (the heap is at its limit).
+      function sample() {
+        if (!rt || !ctx || !ctx.alive) return 0;
+        try {
+          const h = rt.computeMemoryUsage();
+          try {
+            const used = ctx.getProp(h, 'memory_used_size').consume((x) => ctx.getNumber(x));
+            if (used > peak) peak = used;
+            return used;
+          } finally {
+            h.dispose();
+          }
+        } catch {
+          return -1;
+        }
+      }
+
+      function teardown() {
+        for (const id of rpcIds) pendingRpc.delete(id);
+        rpcIds.clear();
+        for (const d of deferreds) { try { if (d.alive) d.dispose(); } catch {} }
+        deferreds.clear();
+        for (let i = owned.length - 1; i >= 0; i--) { try { if (owned[i].alive) owned[i].dispose(); } catch {} }
+        owned.length = 0;
+        try { if (ctx?.alive) ctx.dispose(); } catch { enginePromise = null; }
+        try { if (rt?.alive) rt.dispose(); } catch { enginePromise = null; }
+        ctx = null;
+        rt = null;
+      }
+
+      function finish(result) {
+        if (done) return;
+        done = true;
+        if (timer) clearTimeout(timer);
+        live.delete(abort);
+        try { sample(); } catch {}
+        result.stats = { fuelUsed: polls, peakMemoryBytes: peak };
+        teardown();
+        resolveEval(result);
+      }
+
+      function abort(message) {
+        finish({ success: false, error: { name: 'Error', message } });
+      }
+      live.add(abort);
+
+      function failure(errHandle) {
+        try {
+          return mapFailure(errHandle);
+        } finally {
+          try { if (errHandle?.alive) errHandle.dispose(); } catch {}
+        }
+      }
+
+      function mapFailure(errHandle) {
+        // Map whatever the guest threw (or the engine reported) to a result.
+        if (fuelHit) return { success: false, error: errorFrom('FuelExhaustedError', 'Fuel exhausted after ' + polls + ' interrupt polls (limit ' + limits.fuel + ')') };
+        if (memHit) return { success: false, error: errorFrom('MemoryLimitError', 'Memory limit exceeded (' + limits.memoryBytes + ' bytes of JS heap)') };
+        if (deadlineHit) return { success: false, error: errorFrom('TimeoutError', 'Sandbox execution timed out after ' + limits.deadlineMs + 'ms') };
+        let dumped;
+        try { dumped = ctx.dump(errHandle); } catch { dumped = null; }
+        let name = 'Error';
+        let message = '';
+        let stack;
+        if (dumped && typeof dumped === 'object') {
+          name = dumped.name || 'Error';
+          message = dumped.message !== undefined ? String(dumped.message) : JSON.stringify(dumped);
+          stack = dumped.stack;
+        } else {
+          message = String(dumped);
+        }
+        if (name === 'InternalError' && /out of memory/i.test(message)) {
+          return { success: false, error: errorFrom('MemoryLimitError', 'Memory limit exceeded (' + limits.memoryBytes + ' bytes)') };
+        }
+        return { success: false, error: { name, message, stack } };
+      }
+
+      try {
+        rt = QJS.newRuntime();
+        if (limits.memoryBytes > 0) rt.setMemoryLimit(limits.memoryBytes);
+        if (limits.stackBytes > 0) rt.setMaxStackSize(limits.stackBytes);
+        rt.setInterruptHandler(() => {
+          polls++;
+          if (fuelHit || deadlineHit || memHit) return true;
+          if (limits.fuel > 0 && polls > limits.fuel) { fuelHit = true; return true; }
+          if (deadlineAt && Date.now() > deadlineAt) { deadlineHit = true; return true; }
+          // Walking the heap costs ~1-2 ms per MB of live objects, so sample on a
+          // time budget (about 10% of run time) rather than every poll.
+          const now = performance.now();
+          if (now >= nextSampleAt) {
+            const used = sample();
+            nextSampleAt = performance.now() + Math.max(1, (performance.now() - now) * 9);
+            if (used < 0 || (limits.memoryBytes > 0 && used > limits.memoryBytes)) { memHit = true; return true; }
+          }
+          return false;
+        });
+        rt.setModuleLoader(
+          (name) => {
+            if (virtualModules.has(name)) return virtualModules.get(name);
+            // QuickJS ignores a failing normalizer and calls the loader with
+            // an empty name, so a failed resolution travels as a marker name.
+            if (name.startsWith(RESOLVE_FAILED)) return { error: new Error(name.slice(RESOLVE_FAILED.length)) };
+            return { error: new Error('Cannot load module: ' + name) };
+          },
+          (base, requested) => {
+            try {
+              return normalizeModule(base, requested);
+            } catch (e) {
+              return RESOLVE_FAILED + (e?.message ?? e);
+            }
+          }
+        );
+        ctx = rt.newContext();
+
+        const nativeLog = own(ctx.newFunction('log', (levelH, argsH) => {
+          if (done) return;
+          let args;
+          try { args = JSON.parse(ctx.getString(argsH)); } catch { args = []; }
+          self.postMessage({ type: 'console', evalId: msg.id, level: ctx.getString(levelH), args });
+        }));
+
+        const nativeCall = own(ctx.newFunction('call', (nameH, argsH) => {
+          const name = ctx.getString(nameH);
+          const args = JSON.parse(ctx.getString(argsH));
+          const deferred = ctx.newPromise();
+          deferreds.add(deferred);
+          const id = 'w' + (++rpcSeq);
+          rpcIds.add(id);
+          pendingRpc.set(id, {
+            resolve(value) {
+              if (done || !deferred.alive) return;
+              let text = '';
+              try { text = value === undefined ? '' : JSON.stringify(value) ?? ''; } catch (e) {
+                deferred.reject(ctx.newError('Capability result is not JSON-serializable'));
+                pump();
+                return;
+              }
+              const v = ctx.newString(text);
+              deferred.resolve(v);
+              v.dispose();
+              pump();
+            },
+            reject(error) {
+              if (done || !deferred.alive) return;
+              const e = ctx.newError(String(error?.message ?? error));
+              deferred.reject(e);
+              e.dispose();
+              pump();
+            },
+          });
+          self.postMessage({ type: 'capabilityCall', id, name, args });
+          return deferred.handle;
+        }));
+
+        const boot = ctx.evalCode('(' + guestBoot.toString() + ')', 'andbox-boot.js');
+        if (boot.error) { finish(failure(boot.error)); return; }
+        own(boot.value);
+        const bridge = ctx.callFunction(boot.value, ctx.undefined, nativeCall, nativeLog);
+        if (bridge.error) { finish(failure(bridge.error)); return; }
+        own(bridge.value);
+        const hostH = own(ctx.getProp(bridge.value, 'host'));
+        const importH = own(ctx.getProp(bridge.value, 'sandboxImport'));
+        const consoleH = own(ctx.getProp(bridge.value, 'console'));
+        const serH = own(ctx.getProp(bridge.value, 'ser'));
+
+        // Same wrapper as worker mode, including the newline that keeps a
+        // trailing // comment from swallowing the closing brace (andbox#23).
+        const fn = ctx.evalCode(
+          '(async (sandboxImport, host, console) => {\n' + msg.code + '\n})',
+          'eval.js'
+        );
+        if (fn.error) { finish(failure(fn.error)); return; }
+        own(fn.value);
+
+        // Cooperative wall-clock deadline for time spent awaiting host calls
+        // (the interrupt handler covers time spent executing guest code).
+        if (deadlineAt) {
+          timer = setTimeout(() => {
+            deadlineHit = true;
+            finish(failure(null));
+          }, Math.max(0, deadlineAt - Date.now()));
+        }
+
+        const call = ctx.callFunction(fn.value, ctx.undefined, importH, hostH, consoleH);
+        if (call.error) { finish(failure(call.error)); return; }
+        const promiseH = own(call.value);
+
+        function pump() {
+          if (done) return;
+          try {
+            let guard = 0;
+            while (!fuelHit && !deadlineHit && !memHit && rt.hasPendingJob() && guard++ < 1e6) {
+              const jr = rt.executePendingJobs();
+              if (jr.error) jr.error.dispose();
+            }
+            if (fuelHit || deadlineHit || memHit) { finish(failure(null)); return; }
+            const st = ctx.getPromiseState(promiseH);
+            if (st.type === 'pending') return;
+            if (st.type === 'rejected') {
+              finish(failure(st.error));
+              return;
+            }
+            const sr = ctx.callFunction(serH, ctx.undefined, st.value);
+            if (st.value?.alive) st.value.dispose();
+            if (sr.error) { finish(failure(sr.error)); return; }
+            const parsed = JSON.parse(ctx.getString(sr.value));
+            sr.value.dispose();
+            finish({ success: true, value: parsed.t === 'u' ? undefined : parsed.v });
+          } catch (e) {
+            // An exception escaping the engine (e.g. host stack overflow, wasm
+            // abort) leaves it in an unknown state: drop it and reload.
+            enginePromise = null;
+            done || (done = true, clearTimeout(timer), live.delete(abort), resolveEval({
+              success: false,
+              error: errorFrom('EngineError', 'WASM engine fault: ' + (e?.message ?? e)),
+              stats: { fuelUsed: polls, peakMemoryBytes: peak },
+            }));
+          }
+        }
+        pump();
+      } catch (e) {
+        enginePromise = null;
+        if (!done) {
+          done = true;
+          if (timer) clearTimeout(timer);
+          live.delete(abort);
+          resolveEval({
+            success: false,
+            error: errorFrom('EngineError', 'WASM engine fault: ' + (e?.message ?? e)),
+            stats: { fuelUsed: polls, peakMemoryBytes: peak },
+          });
+        }
+      }
+    });
+  }
+
+  // ── Message handler ──
+
+  self.onmessage = async ({ data: msg }) => {
+    switch (msg.type) {
+      case 'configure': {
+        if (msg.importMap) importMap = msg.importMap;
+        if (msg.virtualModules) {
+          for (const [name, src] of Object.entries(msg.virtualModules)) virtualModules.set(name, src);
+        }
+        config = msg.wasm;
+        try {
+          await getEngine();
+          self.postMessage({ type: 'configured' });
+        } catch (e) {
+          self.postMessage({ type: 'configured', error: { message: String(e?.message ?? e) } });
+        }
+        break;
+      }
+      case 'defineModule': {
+        virtualModules.set(msg.name, msg.source);
+        self.postMessage({ type: 'moduleDefined', name: msg.name });
+        break;
+      }
+      case 'evaluate': {
+        const res = await runEval(msg);
+        self.postMessage({ type: 'result', id: msg.id, ...res });
+        break;
+      }
+      case 'capabilityResult': {
+        const p = pendingRpc.get(msg.id);
+        if (p) {
+          pendingRpc.delete(msg.id);
+          if (msg.success) p.resolve(msg.value);
+          else p.reject(new Error(msg.error || 'Capability call failed'));
+        }
+        break;
+      }
+      case 'dispose': {
+        for (const abort of [...live]) abort('Sandbox disposed');
+        pendingRpc.clear();
+        self.close();
+        break;
+      }
+    }
+  };
+}
+
+/**
+ * Generate the Worker source for `mode: 'wasm'` as a string.
+ *
+ * @returns {string} The Worker script source code.
+ */
+export function makeWasmWorkerSource() {
+  return `'use strict';\n(${wasmWorkerMain.toString()})();\n`;
+}