sandboxedjs 0.1.27 → 0.1.29

package/README.md

@@ -617,11 +617,21 @@ export default {
     "Cross-Origin-Opener-Policy": "same-origin",
     "Cross-Origin-Embedder-Policy": "require-corp",
   } },
+  // Required as well — see below.
+  optimizeDeps: { exclude: ["@rolldown/binding-wasm32-wasi"] },
 };
 ```
 
 Production hosting must return the same two headers. Without them SandboxedJS reports a direct
-configuration error when Vite/Rolldown starts. The compiler is loaded only when an installed
+configuration error when Vite/Rolldown starts.
+
+`optimizeDeps.exclude` matters just as much, and fails less obviously. The binding starts its
+WASI worker with `new Worker(new URL("@rolldown/binding-wasm32-wasi/wasi-worker-browser.mjs",
+import.meta.url))`. A bundler that pre-bundles the package rewrites that URL to a path inside its
+own dependency cache, where the worker file does not exist — so the dev server answers with
+`index.html` and the browser rejects it for its MIME type, several layers away from anything that
+mentions Rolldown. Excluding the binding leaves it served from `node_modules`, where that URL
+resolves. The compiler is loaded only when an installed
 project actually contains Rolldown, so ordinary container boot does not pay its WASM startup cost.
 
 **Not done — these things still stand between this and a complete browser IDE.**
@@ -758,6 +768,31 @@ Two caveats worth knowing:
   itself reports status correctly and can be relied on in `&&` chains.
 - **No hardware acceleration and no native codecs** beyond what the WebAssembly build ships.
 
+## Isolation
+
+By default each guest program runs on its own thread, in a Worker. The volume, the kernel, the
+coreutils and the process table stay on the thread that created the container, and the program
+reaches them through a `SharedArrayBuffer` channel it can wait on synchronously.
+
+Two things follow from that. Guest code no longer shares your page's realm, so it cannot reach
+your application's globals. And `child_process.execSync`, `spawnSync` and `execFileSync` work —
+they cannot be expressed any other way, because a synchronous call has to block its caller while
+the child it is waiting for still makes progress, which is impossible when both are the same
+thread.
+
+It is chosen automatically and falls back on its own, so nothing that runs today stops running:
+
+| Condition | What happens |
+|---|---|
+| `SharedArrayBuffer` unavailable, or the page is not cross-origin isolated | Falls back to the in-realm runtime |
+| The guest bundle cannot be loaded (a bundler moved or rewrote it) | Falls back to the in-realm runtime |
+| `modules` supplied by the host | Falls back — live JavaScript objects cannot cross a thread |
+| The project has `rolldown` installed | *That process* runs in-realm; the rest still get a thread |
+
+In a browser this needs the same COOP/COEP headers Rolldown does, which is the usual reason to
+find yourself in the fallback. `createContainer({ isolation: "realm" })` opts out entirely, and
+`workerUrl` points at the guest bundle when a bundler has moved it.
+
 ## Known limits
 
 Honest list of what does not work:
@@ -765,15 +800,25 @@ Honest list of what does not work:
 - **Compiled native addons.** A `.node` file cannot be loaded, so a package that ships one has to
   have a JavaScript or WebAssembly build to fall back on. `rollup` and `esbuild` do, and the
   runtime redirects those two names to `@rollup/wasm-node` and `esbuild-wasm` automatically when
-  they are installed. Vite 8 is supported through Rolldown's official WASI build (with the browser
-  isolation headers above). Express, Koa, Fastify-style apps and plain `http` servers also run.
+  they are installed. Vite 8 is supported through Rolldown's official WASI build **in a browser
+  host** (with the two configuration steps above). Express, Koa, Fastify-style apps and plain
+  `http` servers also run.
+- **Vite 8 / Rolldown does not work when the host is Node.** The binding has two builds. The
+  browser one owns a `memfs` volume, which SandboxedJS mirrors the project into; the Node one
+  builds a `node:wasi` instance that preopens the *real* filesystem root, and there is no way to
+  hand it a different one. Rolldown therefore looks for `/app/my-app/index.html` on your actual
+  disk, does not find it, and the dev server answers every request with its fallback page. Vite 7
+  works on both hosts and is what the Node acceptance test pins.
 - **Concurrent browser Rolldown projects need distinct absolute working directories.** The
   official binding owns one WASI memfs per page; SandboxedJS mirrors each project into it before
   startup. Two live projects using the same path such as `/workspace` can overwrite that mirror.
-- **`child_process` is asynchronous only.** `spawn`, `exec` and `execFile` run through the kernel,
-  so a child sees the same filesystem and coreutils as the shell. `execSync`, `spawnSync` and
-  `execFileSync` throw `ERR_FEATURE_UNAVAILABLE_ON_PLATFORM`: blocking the JavaScript thread on
-  another process is not expressible here.
+- **`child_process` is synchronous only under the Worker pod.** `spawn`, `exec` and `execFile`
+  always work and run through the kernel, so a child sees the same filesystem and coreutils as the
+  shell. `execSync`, `spawnSync` and `execFileSync` need the guest program to be on its own thread
+  — see *Isolation* above. Where it is, they work; where it is not, they throw
+  `ERR_FEATURE_UNAVAILABLE_ON_PLATFORM` naming the command they were asked to run, and the way
+  through is to answer **No** to a prompt like `npm create vite`'s "Install with npm and start
+  now?" and run `npm install && npm run dev` from the shell instead.
 - **No `net`, `tls`, `worker_threads` or `vm`.** `http` and `https` are served by a virtual stack
   that `request()` talks to directly, so servers work; raw sockets do not.
 - **Python is CPython via Pyodide.** The standard library is the real one. A C