sandboxedjs 0.1.14 → 0.1.16

package/README.md

@@ -579,33 +579,87 @@ resolve their implementation at call time (`node:zlib`/`node:crypto` on Node,
 `CompressionStream`/`crypto.subtle` plus a JS MD5 in a browser), so nothing pulls a `node:`
 builtin in when the module loads and a bundler will not fail on it.
 
-**You supply the pod.** The default boot path uses `@scelar/nodepod/headless`, which installs a
-`worker_threads` host. In a browser you boot Nodepod's browser build yourself — it needs a
-service worker, per Nodepod's own setup docs — and hand the instance over:
+**One call, either side.** `createContainer()` picks its own host: the headless
+`worker_threads` engine on Node, Nodepod's browser build in a browser. You do not import Nodepod,
+and you do not pass a pod:
 
 ```ts
-import { Nodepod } from "@scelar/nodepod";
 import { createContainer } from "sandboxedjs";
 
-const pod = await Nodepod.boot({ /* your service-worker setup */ });
-const box = await createContainer({ pod });
+const box = await createContainer({ files: { "/app/index.js": "console.log(1)" } });
 
 await box.exec("ls -la /");      // shell + coreutils
-await box.exec("node app.js");   // Node, through Nodepod's browser engine
+await box.exec("node app/index.js");
 ```
 
-**What will not work in a browser:**
+**Serve the service worker.** In a browser, a container's preview iframe reaches an HTTP server
+running inside the page through a service worker, and a browser will not register one from
+`node_modules` — it has to come from your own origin at `/__sw__.js`. One line:
+
+```ts
+// vite.config.ts
+import sandboxedjs from "sandboxedjs/vite";
+export default defineConfig({ plugins: [sandboxedjs()] });
+```
+
+For anything else, `sandboxedjs/server` exports `serveSW()` (Fetch-style hosts) and
+`serveSWNode()` (Express, Fastify, `node:http`). Skip it with
+`createContainer({ browser: { serviceWorker: false } })`, which also disables preview iframes.
+
+You can still boot the pod yourself and pass it as `pod` when you need control over Nodepod's
+own options.
+
+**Verified in a browser.** Booted under Vite, the following run:
+
+```
+$ uname -a              Linux sandbox 5.10.0 (sandboxedjs@nodepod) … x86_64 GNU/Linux
+$ ls -la /app           the mounted files
+$ grep beta …           beta
+$ node /app/hello.js    node runtime says hi
+```
+
+Shell, coreutils, the virtual filesystem and the Node runtime all work. Boot costs about ten
+seconds, nearly all of it Nodepod starting.
+
+**What does not work in a browser:**
 
 - `copyIn()` / `copyOut()` — they read and write the host filesystem, which does not exist.
-- `expose()` — it opens a real `node:http` listener. In a browser you use Nodepod's service
-  worker and preview iframe to reach an in-container server instead of a host port.
+- `expose()` — it opens a real `node:http` listener. Use the service worker and a preview iframe
+  to reach an in-container server instead of a host port.
+- `python3` — see below.
 - The `sandboxedjs` CLI, obviously.
 
-Those three use dynamic imports, so they only fail if you call them.
+Those use dynamic imports, so they only fail if you call them.
+
+### Python in a browser
+
+MicroPython does not currently start in a browser. Two separate things are involved.
+
+The first is ours and is fixed: Emscripten resolves `micropython.wasm` against the loader's own
+directory, which is right in Node and wrong once a bundler has rewritten the loader into a hashed
+chunk — the guess lands on a path the dev server answers with `index.html`, and instantiation
+dies on `expected magic word 00 61 73 6d, found 3c 21 64 6f` (the first bytes of `<!doctype`).
+Pass the real URL and that goes away:
+
+```ts
+import wasm from "@micropython/micropython-webassembly-pyscript/micropython.wasm?url";
+
+await createContainer({ pod, python: { wasmUrl: wasm } });
+```
+
+`?url` is Vite's spelling; every bundler has its own. `configurePython({ wasmUrl })` does the
+same thing outside a container.
+
+The second is upstream and is not fixed. With the correct binary loaded, instantiation fails on
+
+```
+LinkError: Import #45 "env" "__syscall_poll_nonblocking": function import requires a callable
+```
 
-**Not yet verified.** I have not run this in a browser end to end. The Node-side blockers are
-removed and the seam is there, but treat browser support as "should work, unproven" rather than
-a tested claim.
+The symbol appears nowhere in the shipped `micropython.mjs`, so the published glue and `.wasm`
+disagree about their import table. Node is unaffected — the Python tests pass there — and nothing
+in this package can supply a symbol the loader never declares. Treat `python3` as Node-only until
+the upstream package ships a matching pair.
 
 ## Uploading files
 

package/dist/index.cjs

@@ -2,7 +2,7 @@
 
 Object.defineProperty(exports, '__esModule', { value: true });
 
-var headless = require('@scelar/nodepod/headless');
+var nodepod = require('@scelar/nodepod');
 var acorn = require('acorn');
 
 var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
@@ -8553,6 +8553,15 @@ async function nodeBuiltin(name) {
     specifier
   );
 }
+async function nodeOnlyModule(specifier) {
+  const parts = specifier.split("/");
+  const runtimeSpecifier = parts.join("/");
+  return await import(
+    /* @vite-ignore */
+    /* webpackIgnore: true */
+    runtimeSpecifier
+  );
+}
 var zlibPromise = null;
 function nodeZlib() {
   zlibPromise ??= nodeBuiltin("zlib");
@@ -8755,7 +8764,7 @@ function installEsbuildRuntime() {
 async function install() {
   const workerPath = await buildPatchedWorker();
   if (!workerPath) return;
-  const { createNodeHost, setRuntimeHost } = await import('@scelar/nodepod/headless');
+  const { createNodeHost, setRuntimeHost } = await nodeOnlyModule("@scelar/nodepod/headless");
   setRuntimeHost(createNodeHost({ workerPath }));
 }
 async function buildPatchedWorker() {
@@ -22144,6 +22153,10 @@ init_path();
 var PYTHON_VERSION = "3.4.0";
 var MICROPYTHON_BANNER = "MicroPython v1.28.0 on 2026-04-06; SandboxedJS with Emscripten";
 var loaderPromise = null;
+var wasmUrl;
+function configurePython(options = {}) {
+  if (options.wasmUrl !== void 0) wasmUrl = options.wasmUrl;
+}
 async function getLoader() {
   if (!loaderPromise) {
     loaderPromise = import('@micropython/micropython-webassembly-pyscript/micropython.mjs').then(
@@ -22166,6 +22179,7 @@ async function createInterpreter(ctx, opts) {
     stdout: opts.stdout,
     stderr: opts.stderr,
     ...opts.stdin ? { stdin: opts.stdin } : {},
+    ...wasmUrl ? { url: wasmUrl } : {},
     linebuffer: false,
     heapsize: opts.heapsize ?? 64 * 1024 * 1024
   });
@@ -22890,7 +22904,7 @@ function splitPackageSpec(spec) {
   return { name: spec.slice(0, at), version: spec.slice(at + 1) };
 }
 async function installPackages(ctx, specs, opts) {
-  const installer = opts.cwd === "/" ? ctx.kernel.pod.packages : new headless.DependencyInstaller(ctx.vfs.volume, { cwd: opts.cwd });
+  const installer = opts.cwd === "/" ? ctx.kernel.pod.packages : new nodepod.DependencyInstaller(ctx.vfs.volume, { cwd: opts.cwd });
   const onProgress = (message) => {
     if (!opts.quiet) ctx.stderr.write(message.endsWith("\n") ? message : message + "\n");
   };
@@ -23182,6 +23196,12 @@ function packageBinaries(ctx, root, packageName) {
   }
   return [];
 }
+var CLI_MOVED_TO = {
+  tailwindcss: "@tailwindcss/cli",
+  postcss: "postcss-cli",
+  autoprefixer: "postcss-cli",
+  sass: "sass-embedded"
+};
 function findLocalBin(ctx, name) {
   let dir3 = ctx.cwd;
   for (let i = 0; i < 64; i++) {
@@ -23288,6 +23308,14 @@ unless the container was created with network: { allowOutbound: true }.`,
       const chosen = binaries.includes(command) ? command : binaries[0];
       if (chosen === void 0) {
         ctx.warn(`could not determine executable to run: ${packageName} provides no binary`);
+        const replacement = CLI_MOVED_TO[packageName];
+        if (replacement !== void 0) {
+          ctx.warn(`'${packageName}' ships no CLI; its command lives in '${replacement}'.`);
+          ctx.warn(`Try: npx ${replacement} ${rest.join(" ")}`.trimEnd());
+        } else {
+          ctx.warn(`'${packageName}' is installed but declares no "bin" entry.`);
+          ctx.warn("Check which package provides the command, or use `npx -p <pkg> <command>`.");
+        }
         return 127;
       }
       command = chosen;
@@ -23864,14 +23892,9 @@ var Container = class _Container {
   }
   // ── boot ──────────────────────────────────────────────────────────────────
   static async create(opts = {}) {
-    if (!opts.pod) await installEsbuildRuntime();
-    const pod = opts.pod ?? await headless.Nodepod.boot({
-      headless: true,
-      serviceWorker: false,
-      env: opts.env ?? {},
-      workdir: opts.cwd ?? "/",
-      ...opts.onServerReady ? { onServerReady: opts.onServerReady } : {}
-    });
+    if (opts.python) configurePython(opts.python);
+    if (!opts.pod && isNodeRuntime()) await installEsbuildRuntime();
+    const pod = opts.pod ?? (isNodeRuntime() ? await bootHeadlessPod(opts) : await bootBrowserPod(opts));
     const kernel = new Kernel({
       pod,
       hostname: opts.hostname ?? "sandbox",
@@ -24293,6 +24316,30 @@ function normalizeHeaders(headers) {
 async function createContainer(opts = {}) {
   return Container.create(opts);
 }
+function isNodeRuntime() {
+  return typeof process !== "undefined" && process.versions != null && process.versions.node != null;
+}
+async function bootBrowserPod(opts) {
+  const { Nodepod } = await import('@scelar/nodepod');
+  return Nodepod.boot({
+    env: opts.env ?? {},
+    workdir: opts.cwd ?? "/",
+    ...opts.browser ?? {},
+    ...opts.onServerReady ? { onServerReady: opts.onServerReady } : {}
+  });
+}
+async function bootHeadlessPod(opts) {
+  const { Nodepod } = await nodeOnlyModule(
+    "@scelar/nodepod/headless"
+  );
+  return Nodepod.boot({
+    headless: true,
+    serviceWorker: false,
+    env: opts.env ?? {},
+    workdir: opts.cwd ?? "/",
+    ...opts.onServerReady ? { onServerReady: opts.onServerReady } : {}
+  });
+}
 
 // src/container/terminal.ts
 init_path();
@@ -24771,6 +24818,7 @@ exports.braceExpand = braceExpand;
 exports.buildRootfs = buildRootfs;
 exports.builtinNames = builtinNames;
 exports.captureStdio = captureStdio;
+exports.configurePython = configurePython;
 exports.createContainer = createContainer;
 exports.createContext = createContext;
 exports.default = src_default;