sandboxedjs 0.1.28 → 0.1.30

package/LICENSE

@@ -18,10 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
-
----
-
-This package depends on @scelar/nodepod, which is licensed MIT with the
-Commons Clause. Nodepod is not redistributed here; it is installed as a normal
-npm dependency.
+SOFTWARE.

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,83 @@ 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.
 
+## Reaching a container's servers from the page
+
+A server inside the container is not on the network, so there is no `http://localhost:5173`
+your page can navigate to. There are three ways to reach one, and the right choice depends on
+whether you need a whole site or a single response — and on whether you trust the code.
+
+**1. One response, into a variable.** `request()` speaks to a server directly and hands back the
+bytes. Nothing is executed, so there is nothing to be careful about.
+
+```ts
+const res = await box.request(5173, { path: "/api/items" });
+element.textContent = res.body;          // text
+const items = res.json<Item[]>();        // parsed
+const bytes = res.bytes;                 // exact bytes, for images and source maps
+```
+
+**2. One response, rendered — safely.** `renderInto` puts the response in an iframe with
+`sandbox="allow-scripts"` and deliberately *without* `allow-same-origin`. The document lands in an
+opaque origin: its scripts run, and they can reach neither your DOM nor your cookies and storage.
+
+```ts
+import { renderInto } from "sandboxedjs";
+await renderInto(box, document.querySelector("#preview")!, { port: 5173 });
+```
+
+This is the option to reach for when the code came from somewhere you do not control. Its limit is
+that only that one response exists — a page asking for `/main.js` gets nothing, because there is no
+origin to serve it from. Good for generated HTML, a chart, a rendered document.
+
+**3. A whole site, with real URLs.** `createPreview` registers a service worker that gives the
+container's ports working URLs, so an iframe can load a dev server with all its subresources.
+
+```ts
+import { createPreview } from "sandboxedjs";
+const preview = await createPreview(box);          // null where service workers are unavailable
+iframe.src = preview!.urlFor(5173);
+```
+
+Requests are routed by *which client is asking* rather than by path, so a dev server's absolute
+URLs — `/src/main.js`, `/@vite/client` — resolve without rewriting anything.
+
+> **This one runs guest code on your origin.** A service worker can only serve URLs under the
+> origin that registered it, so scripts in the preview can reach `window.parent`, your cookies and
+> your `localStorage`. The sandbox contains a program's *filesystem and process table*, not the
+> page it serves. Use it for code you trust; for anything else, serve the preview from a separate
+> origin (a subdomain pointed at the same app) or stay with option 2.
+
+Service workers need a secure context, and some embedded browsers disable them entirely — hence
+the `null` return rather than a throw. Responses are served with both
+`Cross-Origin-Resource-Policy` and `Cross-Origin-Embedder-Policy`, so a preview still frames
+correctly inside the cross-origin isolated page that Rolldown requires.
+
+## 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 +852,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