sandboxedjs 0.2.18 → 0.2.20

package/README.md

@@ -2,12 +2,11 @@
 
 <img src="https://cdn.jsdelivr.net/npm/sandboxedjs@latest/assets/logo.png" alt="SandboxedJS" width="140" />
 
-# SandboxedJS
+# SandboxedJS: The Zero-Infra Sandbox for AI Agents & Code Playgrounds
 
-**A Linux-like operating system of its own — written in JavaScript, running inside a browser tab or a Node process.**
+**A secure, Linux-like environment written in JavaScript, running entirely inside a browser tab or a Node process.**
 
-Not a Linux kernel, not a VM, not Docker, not WebContainers. Its own filesystem, shell, process
-table, package installer and network stack, all in memory, booting in about 100 ms.
+The ideal alternative to WebContainers and NodePod for those who need a full POSIX shell, Node.js, and Python runtimes without the infrastructure overhead. Boots in ~100 ms, all in memory.
 
 [![npm](https://img.shields.io/npm/v/sandboxedjs?color=cb0000&label=npm)](https://www.npmjs.com/package/sandboxedjs)
 [![license](https://img.shields.io/badge/license-MIT-black)](./LICENSE)
@@ -42,14 +41,28 @@ touches your disk.
 <a href="https://sandboxedjs.pages.dev">
 <img src="https://cdn.jsdelivr.net/npm/sandboxedjs@latest/assets/demo.png" alt="SandboxedJS running a full-stack project in a browser" width="720" />
 </a>
-<p>The image you see above is that I am running a full stack project in a static site deployed on cloudlfare pages, this site is a CLI to interact with this sandbox, just like I have ran a full-stack project, you can too. Try it out! <a href="https://sandboxedjs.pages.dev">Try the live demo →</a></p>
+<p>Above: a full-stack project running inside a static site deployed on Cloudflare Pages. The site is a CLI for interacting with the sandbox — and just as it runs a full-stack project, so can yours. <a href="https://sandboxedjs.pages.dev">Try the live demo →</a></p>
 </div>
 
-## Why
+## Why SandboxedJS?
 
-Run untrusted or AI-generated code. Give an agent a real shell. Build a browser IDE that actually
-installs packages and starts servers. Teach Unix without handing out VMs. A real container is too
-heavy, too slow, or simply unavailable — in a browser tab, in a serverless function, in CI.
+Looking for a **WebContainer alternative** that works in both Node.js and the browser without the infrastructure overhead?
+
+SandboxedJS is designed for cases where a real container is too heavy, too slow, or unavailable — like in a browser tab, a serverless function, or a CI pipeline.
+
+### Best For:
+- **AI Agents**: Give your LLM a real POSIX shell to manage files, run scripts, and install packages safely.
+- **Code Sandboxes**: Build a browser-based IDE or interactive tutorial that boots in 100ms with zero server-side setup.
+- **Secure JS Sandboxing**: Run untrusted JavaScript and Python code in an isolated environment without native module risks.
+
+### SandboxedJS vs. The World
+
+| Feature | SandboxedJS | WebContainers / NodePod | Traditional VMs/Docker |
+| :--- | :--- | :--- | :--- |
+| **Infrastructure** | Zero (Pure JS/WASM) | Medium (Browser/Host) | High (Server/Hypervisor) |
+| **Boot Time** | ~100ms | Seconds | Minutes |
+| **Environment** | Node + Browser | Browser-only / Server | Server-only |
+| **Setup** | `npm install` | Cloud Provisioning | Complex Orchestration |
 
 ## Install
 
@@ -61,6 +74,12 @@ Node 18.17+. Pure JavaScript and WebAssembly — no build step, no native module
 
 ## What's inside
 
+Browser automation uses the separately distributed **Vireo** Rust/WebAssembly
+document engine. Node and Python Playwright discover the built-in Chromium
+compatibility command; its first launch securely installs Vireo from the
+SandboxedJs application registry. See [the Vireo architecture and current
+compatibility](docs/vireo.md).
+
 |                 |                                                                                                                    |
 | --------------- | ------------------------------------------------------------------------------------------------------------------ |
 | **Filesystem**  | A full FHS tree in memory (`/etc`, `/usr`, `/var`, `/home`), permissions, ownership, symlinks, hard links, `umask` |
@@ -121,7 +140,7 @@ terminal.start();
 
 ## Running a full-stack project in a browser
 
-This is the case most people arrive for: a Vite frontend and a Python backend, in one container, in
+This can be the case most people arrive for: a Vite frontend and a Python backend, in one container, in
 a tab — the frontend calling `http://localhost:8000`, the backend calling a real API.
 
 The frontend-to-backend hop and the backend-to-internet hop have different requirements.

package/bin/sandboxedjs-pack.mjs

@@ -105,6 +105,9 @@ async function build() {
       throw new Error(`app.json declares the command ${binary.name} at ${binary.path}, which is not in ${directory}`);
     }
   }
+  if (app.browserEngine?.wasm && !files.includes(app.browserEngine.wasm)) {
+    throw new Error(`app.json declares a browser engine at ${app.browserEngine.wasm}, which is not in ${directory}`);
+  }
 
   const digests = {};
   const contents = new Map();
@@ -218,6 +221,7 @@ async function inspect() {
 function collect(root, prefix = "") {
   const out = [];
   for (const entry of readdirSync(join(root, prefix), { withFileTypes: true })) {
+    if ([".git", "target"].includes(entry.name)) continue;
     const path = prefix ? `${prefix}/${entry.name}` : entry.name;
     if (entry.isDirectory()) {
       out.push(...collect(root, path));