sandboxedjs 0.1.25 → 0.1.27

package/README.md

@@ -577,8 +577,8 @@ its kill signal.
 
 ## Running in a browser
 
-This package targets Node today, and that is what is tested. If your goal is a browser IDE, here
-is exactly where things stand.
+The same `createContainer()` API runs under Node and in modern browsers. Browser execution is
+tested under Vite 8; the remaining browser-specific limits are listed below.
 
 **Done — the package no longer hard-depends on Node at import time.** Compression and hashing
 resolve their implementation at call time (`node:zlib`/`node:crypto` on Node,
@@ -597,7 +597,34 @@ await box.exec("ls -la /");      // shell + coreutils
 await box.exec("node app/index.js");
 ```
 
-**Not done — three things stand between this and a browser IDE.**
+**Verified in a browser.** Booted under Vite 8, a container starts in the page and the shell,
+coreutils, virtual filesystem and Node runtime all work:
+
+```
+$ uname -a               Linux sandbox 5.10.0 (sandboxedjs@sandbox) … x86_64 GNU/Linux
+$ ls -la /               the full FHS tree
+$ node -p process.version  v22.12.0
+$ cat /etc/os-release    SandboxedJS 1.0 (sandbox)
+```
+
+**Vite 8 works through Rolldown's official WASI binding.** Because that binding uses shared
+WebAssembly memory and workers, the page must be cross-origin isolated. For example:
+
+```ts
+// vite.config.ts
+export default {
+  server: { headers: {
+    "Cross-Origin-Opener-Policy": "same-origin",
+    "Cross-Origin-Embedder-Policy": "require-corp",
+  } },
+};
+```
+
+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
+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.**
 
 - *A service worker.* A preview iframe needs a real URL, and giving it one means a worker on your
   own origin that intercepts requests and routes them into the container. `request()` works
@@ -607,11 +634,14 @@ await box.exec("node app/index.js");
 - *Worker isolation.* The runtime executes in whichever realm you boot it from, which in a browser
   is the main thread — so a long build blocks the UI, and container code can reach page globals.
   `comlink` is a dependency in anticipation of this and is not used yet.
-- *esbuild.* The runtime cannot execute any build of esbuild itself: one dlopens a compiled addon,
+- *esbuild-dependent tools.* The runtime cannot execute any build of esbuild itself: one dlopens a compiled addon,
   the other drives a Go program through facilities the sandbox does not have. On Node it borrows
-  the host's `esbuild-wasm`, which is why Vite's dev server works there. In a browser there is
-  nothing to borrow, so anything routed through esbuild fails until esbuild-wasm runs *inside*
-  the sandbox.
+  the host's `esbuild-wasm`. Vite 8's Rolldown path works in a browser, but tools which call
+  esbuild directly still fail until esbuild-wasm runs *inside* the sandbox.
+
+Vite prints two warnings about `util` being externalized. They come from `readable-stream`, which
+declares `"util": false` for browsers and falls back on its own; nothing in this package imports
+it.
 
 Everything else is already browser-shaped. Nothing in the runtime imports a `node:` builtin except
 through an explicitly Node-only path that returns `null` elsewhere, compression and hashing pick
@@ -623,7 +653,6 @@ built on `fetch`, `acorn`, `resolve.exports`, `@noble/hashes` and `pako`.
 - `copyIn()` / `copyOut()` — they read and write the host filesystem, which does not exist.
 - `expose()` — it opens a real `node:http` listener. Use `request()` to reach an in-container
   server instead of a host port.
-- `python3` — see below.
 - The `sandboxedjs` CLI, obviously.
 
 Those use dynamic imports, so they only fail if you call them.
@@ -736,9 +765,11 @@ 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 does not work** for this reason: it builds on Rolldown, whose only
-  sandbox-viable binding needs WASI and `worker_threads`. Vite 7 runs, dev server included, as do
-  Express, Koa, Fastify-style apps and plain `http` servers.
+  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.
+- **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