sandboxedjs 0.2.11 → 0.2.12

package/docs/developer-tool-packs.md

@@ -0,0 +1,134 @@
+# Optional developer tools and binary backends
+
+This is an extension mechanism and two limited developer-tool adapters, not
+universal Linux compatibility. The core has no new third-party dependencies,
+paid endpoint, account requirement, or automatic downloads.
+
+## Working developer tools
+
+Install engines in the **host application**, then pass them to the adapters:
+
+```sh
+npm install sandboxedjs isomorphic-git @electric-sql/pglite
+```
+
+```js
+import git from 'isomorphic-git';
+import { PGlite } from '@electric-sql/pglite';
+import { createContainer, createGitCommand, createSqlCommand } from 'sandboxedjs';
+
+const box = await createContainer({ cwd: '/app' });
+const db = new PGlite();
+box.kernel.installCommand(createGitCommand(git));
+box.kernel.installCommand(createSqlCommand(db));
+
+await box.exec('git init');
+await box.fs.writeFile('/app/hello.txt', 'hello');
+await box.exec('git add hello.txt');
+await box.exec('git commit -m first', {
+  env: { GIT_AUTHOR_NAME: 'Your Name', GIT_AUTHOR_EMAIL: 'you@example.com' },
+});
+console.log(await box.exec('git log'));
+console.log(await box.exec('sql -c "SELECT 42 AS answer"'));
+
+// The application owns the database lifetime and persistence configuration.
+await db.close();
+box.dispose();
+```
+
+Git supports `init`, `add PATH...`, `commit -m MESSAGE`, `status`, and `log`.
+These are local operations backed by isomorphic-git and the credential-aware
+container filesystem. Clone, fetch, push, branches, checkout and full Git CLI
+compatibility are not implemented. No CORS proxy is configured implicitly.
+
+`sql -c SQL` and `sql -f FILE` print result rows as JSON. This is an embedded
+SQL adapter, not `psql`, a PostgreSQL server, or a TCP endpoint for `pg` clients.
+Database storage belongs to PGlite, separately from the container filesystem.
+Use its persistence options in the host; container snapshots do not capture it.
+The supplied database API does not provide hard query cancellation; a timeout
+is not a transaction rollback. Do not share the same database across tenants.
+
+Both adapters are trusted host integrations. This pass validated real Git
+commits with isomorphic-git 1.42.2 and real SQL with PGlite 0.5.8 on Node,
+not a browser UI. Their upstream engines
+support browsers; host asset loading must still be configured and verified.
+
+## Precompiled command packs
+
+Packs live outside the core. A host can load their manifests and artifact bytes
+from its own storage and call:
+
+```js
+import { installWasmCommands } from 'sandboxedjs';
+installWasmCommands(box.kernel, [
+  { name: 'my-tool', bytes: wasmBytes, sha256: trustedManifest.sha256 },
+]);
+await box.exec('my-tool --help');
+```
+
+Supply a wasm32-wasi command compatible with this runtime's WASI preview1 host.
+Hashes detect changed artifact bytes; trust in the manifest comes from the host.
+Names, collisions, hashes and Wasm validity are checked before commands are
+installed. No network fetch, registry, package archive or license acceptance is
+hidden in this API. WASI imports and behaviors still need compatibility checks;
+valid Wasm alone does not prove that a command can execute here.
+
+## ELF execution and fallback
+
+The kernel now recognizes executable ELF files instead of treating them as
+shell scripts. It consults `box.kernel.binaries` in this order:
+
+1. `compatibility`: exact binary hashes mapped to tested ports.
+2. `translation`: a supplied compiler producing compatible WASI commands.
+3. `emulation`: a supplied emulator backend.
+
+`createWasmCompatibilityBackend(id, entries)` registers mappings of
+`{ elfSha256, wasm: { name, bytes, sha256 } }`. Matching content rather than a
+command name prevents silently substituting a port for a different version.
+
+`createTranslationBackend(translator, maxCacheBytes?)` wraps a compiler with a
+32 MiB default in-memory LRU output cache. The compiler supplies `id`,
+`supports(info)` and `translate(request, signal)`. Give it a versioned identity.
+Return null only when the input is unsupported. Thrown errors are surfaced.
+This wrapper **does not contain an ELF compiler**. Its checks use a fixture
+translator, not a claim that native instructions were translated in the test.
+Ordinary elfconv/Emscripten output cannot be assumed to match our WASI ABI.
+
+An emulator implements `BinaryBackend`, with `tier: 'emulation'` and
+`prepare(request, signal)`. Register it with `box.kernel.binaries.register()`;
+the returned function unregisters it. `list()` reports installed providers.
+An original experimental x86-64 translator and interpreter are now available
+through `createOriginalX64Backends()`. They support a small freestanding subset;
+see [Original engines](original-x64.md). No Linux image is shipped.
+
+Preparation returns either `{ supported: false, reason }` or
+`{ supported: true, program: { run(ctx) } }`. Preparation must not execute guest
+code or modify guest files. Backends receive an AbortSignal and must honor it.
+After `run()` starts, its exit code is final: retrying on another backend could
+duplicate writes or other effects. A native program with no supported backend
+exits 126 with a diagnostic. Hard interruption requires a backend worker; the
+existing in-realm WASI runner cannot interrupt a tight compute loop.
+
+## Package priorities
+
+| Priority | Tools | Approach and current status |
+| --- | --- | --- |
+| 1 | Git | Optional isomorphic-git adapter; local subset implemented |
+| 1 | PostgreSQL SQL | Optional PGlite adapter implemented; embedded SQL only |
+| 2 | jq, ripgrep, SQLite CLI, diff/patch | Candidate separate WASI packs; not bundled or validated here |
+| 3 | C/C++ compiler and build tools | Separate large toolchain pack; compilation and subprocess support need work |
+| Later | Redis-compatible services | Evaluate a separate engine and exact protocol/command coverage |
+| Separate project | Docker Engine | Requires Linux kernel facilities; not a small WASI shim |
+
+Broad binary translation and emulation coverage remain substantive follow-up work.
+Do not advertise arbitrary ELF, Docker, complete PostgreSQL service compatibility,
+or WebContainer performance parity based on this extension layer.
+
+## Cost and licensing
+
+SandboxedJs remains MIT. Upstream PGlite and isomorphic-git publish permissive
+licenses, but retain the notices and check the specific versions you distribute.
+A compatibility layer does not remove a tool's license obligations or make
+enterprise software free. Host-supplied packs let users choose their own tools
+and licenses. Hosting, compilation and network services have real resource costs;
+this API does not require a paid provider or promise free third-party hosting.

package/docs/frontend-automation.md

@@ -0,0 +1,49 @@
+# Frontend browser automation
+
+`createFrontendPlaywright(options?)` provides a Playwright-shaped API that runs
+entirely in the page hosting SandboxedJs. It drives a same-origin `<iframe>`
+using the browser the user already has. It does **not** bundle, download or
+launch Chromium, and it is not Playwright.
+
+```js
+import { createFrontendPlaywright } from 'sandboxedjs';
+
+const pw = createFrontendPlaywright({ mount: document.querySelector('#tests') });
+const browser = await pw.chromium.launch();
+const page = await browser.newPage();
+
+await page.goto('/preview/index.html');
+await page.getByRole('textbox', { name: 'Email' }).fill('a@example.com');
+await page.getByRole('button', { name: 'Submit' }).click();
+await pw.expect(page.getByText('Thanks')).toBeVisible();
+
+await pw.dispose();
+```
+
+## Supported
+
+`page`: `goto`, `setContent`, `title`, `content`, `evaluate`,
+`setDefaultTimeout`, `close`; locators via `locator`, `getByTestId`,
+`getByText`, and `getByRole` for `button`, `textbox`, `link`, `checkbox`
+(plus any explicit `role=` attribute).
+
+`locator`: `first`, `nth`, `locator`, `count`, `isVisible`, `textContent`,
+`innerText`, `inputValue`, `getAttribute`, `click`, `fill`, `waitFor`.
+Locators are strict: more than one match throws unless you narrow with
+`first()`/`nth()`. Actions wait for the element to be visible and enabled.
+
+`expect(locator)`: `toBeVisible`, `toHaveText`.
+
+## Not supported
+
+`screenshot`, `route`/network interception, cross-origin navigation, browser
+launch options, and `firefox`/`webkit` all throw
+`FrontendAutomationUnsupported`. Clicks and typing are dispatched DOM events,
+not OS-level trusted input; `capabilities.trustedEvents` is `false`. `goto`
+returns `null` rather than a Response. `evaluate` uses `eval` inside the frame
+and fails where the page's CSP forbids it.
+
+Pass `resolveUrl` to map a container's virtual server URL to the same-origin
+preview URL served by the SandboxedJs service worker. Inspect
+`pw.capabilities` before relying on any behavior; treat this as a labeled
+subset for smoke-testing your own preview output, not a Chromium replacement.

package/docs/fullstack-deployment.md

@@ -0,0 +1,163 @@
+# Full-stack projects across browser and Node hosts
+
+The guest project can keep its frontend, FastAPI backend, and `http://127.0.0.1:8000`
+API URLs. Hosting prerequisites belong to the outer application that embeds SandboxedJS.
+They cannot all be removed by a JavaScript library.
+
+| Where SandboxedJS executes | Frontend → guest backend | Backend → external API | Lifetime |
+| --- | --- | --- | --- |
+| Browser, served by a static CDN | `createPreview(box)` rewrites loopback fetch/XHR/EventSource requests into virtual ports | Direct when browser policies permit; otherwise a deployed egress function or an explicitly configured relay | Owner tab stays open |
+| Long-running Node process | `box.request()` or an application HTTP adapter; `box.expose()` for local access | Node performs outbound requests | Process stays alive |
+| Node serverless function | Use `box.request()` within the invocation; return its result through the platform's HTTP response | Node performs outbound requests | Invocation only; do not rely on a background server surviving the response |
+
+A Vercel-hosted browser app is still a **browser** runtime. Serving its assets from Vercel
+does not give code in the visitor's browser Node networking permissions. A purely static
+host cannot itself relay an API that rejects cross-origin browser calls. Use a function on
+that host, or provide `network.proxy` pointing to a relay you operate.
+
+## Browser host setup
+
+1. Serve over HTTPS (localhost is suitable for development).
+2. Send these HTTP response headers on the outer document:
+
+   ```http
+   Cross-Origin-Opener-Policy: same-origin
+   Cross-Origin-Embedder-Policy: require-corp
+   ```
+
+3. Serve the matching worker and Python runtime assets from the installed package. When
+   copying them into `public`, copy them on **every production build**, not just on `dev`:
+
+   ```json
+   {
+     "scripts": {
+       "predev": "npm run stage:runtime",
+       "prebuild": "npm run stage:runtime",
+       "build": "tsc && vite build"
+     }
+   }
+   ```
+
+   The staging script must copy `dist/service-worker.js` from the same installed
+   `sandboxedjs` as the host bundle. Copy the guest worker, Python worker, and Python
+   distribution if your host explicitly serves those from `public` too. Do not keep an
+   independently maintained old service worker. Alternatively, let your bundler emit the
+   default worker asset used by `createPreview()`.
+
+4. Register the emitted worker and use its URL for the iframe:
+
+   ```ts
+   const preview = await createPreview(box, { scriptUrl: '/service-worker.js' });
+   if (!preview) throw new Error('Preview worker could not be registered');
+   iframe.src = preview.urlFor(3000);
+   ```
+
+   Without a copied/custom worker, omit `scriptUrl`. Preserve the same-origin worker asset
+   as a file; do not inline it as a data URL. A strict guest CSP that rejects the injected
+   scripts, compressed HTML, or `{ websocket: false }` prevents the current loopback shim
+   from being installed. Use normal uncompressed preview HTML with injection enabled.
+
+5. Enable outbound access for package installation and API calls:
+   `network: { allowOutbound: true }`. Start both guest servers, check their exit/output
+   and `waitForPort()` results, and keep the owning container alive.
+
+## External APIs: create the relay in the right directory
+
+Run from the **host application root**, not the guest's `/workspace` shell:
+
+```sh
+# Cloudflare Pages
+npx sandboxedjs-egress init --target cloudflare --allow ollama.com,api.openai.com
+# Vercel
+npx sandboxedjs-egress init --target vercel --allow ollama.com,api.openai.com
+# Netlify
+npx sandboxedjs-egress init --target netlify --allow ollama.com,api.openai.com
+```
+
+Use one command for the platform you deploy to. An explicit project directory may appear
+before or after the flags. Older CLI builds incorrectly treated a flag value as the
+project directory; if you see a folder called `ollama.com,api.openai.com` or `cloudflare`,
+upgrade the CLI and generate the function at the root instead.
+
+Expected paths:
+
+| Platform | File relative to host project root | Probe URL |
+| --- | --- | --- |
+| Pages | `functions/__sandboxedjs__/egress.ts` | `/__sandboxedjs__/egress` |
+| Vercel | `api/__sandboxedjs__/egress.ts` | `/api/__sandboxedjs__/egress` |
+| Netlify | `netlify/functions/sandboxedjs-egress.ts` | `/.netlify/functions/sandboxedjs-egress` |
+
+A GET to the deployed probe must return JSON containing
+`{"sandboxedjs":"egress","protocol":1}`, not the site's HTML. Containers discover these
+paths automatically. Development uses `npx sandboxedjs-egress --allow ollama.com` or
+`npx sandboxedjs-serve dist`; Vite alone does not execute Pages Functions.
+
+Deploy the function along with the static build. Cloudflare dashboard drag-and-drop does
+not compile a `functions` directory: use Git integration or Wrangler from the project root.
+See [Cloudflare's deployment documentation](https://developers.cloudflare.com/pages/get-started/direct-upload/).
+
+Keep the relay's allowlist narrow and apply your application's authentication and rate limits
+at the host route. Guest `.env` files and browser-delivered keys are visible to the visitor;
+operator-owned credentials belong in server-side secrets. Do not commit actual keys.
+
+## FastAPI and a static frontend
+
+Inside one container, use the project's normal commands:
+
+```sh
+cd /workspace/backend
+pip install -r requirements.txt
+fastapi run main.py --host 0.0.0.0 --port 8000 &
+cd /workspace/frontend
+npx serve . -l 3000
+```
+
+Preview port 3000 with `preview.urlFor(3000)`. Its fetch to
+`http://127.0.0.1:8000/agent/run/stream` must appear in browser developer tools as a
+same-origin `/…/__sbx__/8000/agent/run/stream` request. No CORS relay is needed for this
+internal hop. An external Ollama request made by FastAPI uses the separate egress path.
+
+The bridge currently buffers response bodies. A finite SSE response arrives after the
+backend finishes, preserving its event text, but tokens do not appear progressively.
+An indefinitely open stream will time out. `createPreview(box, { timeoutMs: 600_000 })`
+changes the preview timeout; it cannot change a hosting platform's function limits.
+
+## Node and serverless usage
+
+The stable transport API is `box.request(port, { method, path, headers, body })`. Start the
+backend and wait for its virtual port before invoking it. Return `response.bytes`, status,
+and headers using your framework's response adapter. Clean up the container when its
+owning request/session ends. `box.expose()` opens a local socket and is useful for local
+Node development; it does not create a public route in Vercel.
+
+Serverless workers may be frozen or discarded between invocations. Store files/session
+state externally if needed and reconstruct the container, or use a persistent host for
+interactive sessions. Package support, available workers/WASM, memory, payload sizes and
+[function duration limits](https://vercel.com/docs/functions/limitations) still apply.
+This project does not promise that an arbitrary browser workload runs unchanged inside an
+edge runtime.
+
+## Diagnose the actual failed hop
+
+- **Frontend still requests `127.0.0.1:8000` in developer tools:** check the deployed worker
+  for `installPreviewFetch`, rebuild staged assets, then reload the host and reopen the
+  preview. Also check CSP/injection restrictions. Changing FastAPI CORS does not fix an
+  address that points at the visitor's machine.
+- **Same-origin `__sbx__/8000` returns 502:** check backend process output and
+  `await box.request(8000, { path: '/docs' })`.
+- **Backend receives the request but its AI call fails:** verify the egress probe, allowed
+  hostname, upstream credentials and upstream response. Test authenticated and ordinary
+  user sessions independently; application permissions may differ.
+- **504 after a long wait:** inspect backend completion and buffering/host time limits.
+- **Works locally but not after build:** inspect actual deployed headers, worker bytes,
+  copied runtime versions and function deployment. A successful asset build alone does
+  not deploy a function.
+
+## Regression evidence
+
+`test/preview-worker-build.test.ts` evaluates the distributed service worker, executes its
+injected script, and verifies the loopback POST route and navigation paths.
+`test/egress-cli.test.ts` checks generated paths and flag order for all three platforms.
+`test/fixtures/fullstack-browser` builds a real static browser fixture with a Python
+FastAPI backend, a separate frontend, and a finite SSE POST. It needs no AI credentials;
+see its README for running it.

package/docs/handoff.md

@@ -0,0 +1,275 @@
+# Handoff — SandboxedJS
+
+## Repo state
+
+`npx tsc --noEmit` passes, `npm run build` passes, and **316 tests pass**
+including the network acceptance suite:
+
+```bash
+SANDBOXEDJS_CLEAN_NETWORK_TESTS=1 npx vitest run
+```
+
+(The network tests hit the real npm registry and take ~2 min: Express,
+`npx serve`, `npm install` + `npx`, `npm create vite`, a Vite 7 dev server, and
+an interactive clack prompt driven through `Terminal`.)
+
+## Context
+
+`@scelar/nodepod` was removed entirely (licence: Commons Clause). The Node.js
+runtime is this package's own, under `src/runtime/`. It must stay
+browser-capable: **nothing in `src/runtime/` may import a `node:` builtin**
+except through `nodeOnlyModule`/`nodeBuiltin` (`src/util/binary.ts`) on a path
+that returns `null` off Node. Several npm shims had to be replaced because they
+are not browser-safe — see `util-module.ts`, `assert-module.ts`,
+`zlib-module.ts`, `url-module.ts`, `readline-module.ts`, `readable-from.ts`.
+
+## Verified in a real browser
+
+Chrome, against the Vite host app at
+`/Users/shazi/Practice/sandboxedjs tes/browser-server` (`npm run dev`). That
+project has a `check.html` / `src/browser-check.ts` page that boots a container
+and drives `Terminal` through the whole set; open `/check.html` and it prints a
+pass/fail line per check:
+
+- `readline.question` answered, with the typed text echoed as it is typed
+- `https.get` from inside the sandbox reaching the npm registry
+- clipboard round-trip through `pbcopy`/`pbpaste`
+- `npm create vite@latest` accepting a project name and advancing
+- `ctrl+c` cancelling a prompt and returning to the shell
+- `npx serve --debug` starting with no errors and serving a file
+
+## How isolation is put together
+
+`WorkerRuntimePod` (`src/runtime/worker-runtime-pod.ts`) extends
+`LocalRuntimePod` and overrides `spawn` alone; everything else in the contract
+is identical. Both are held to `test/pod-contract.ts`, which is the thing to
+extend when either changes.
+
+The topology is forced, not chosen. A synchronous call must block its caller
+while the work it waits on still progresses, so the blocking side cannot own
+the shared state — otherwise a child needing the filesystem would call into a
+frozen thread. Hence: guest in the Worker, volume and kernel on the host.
+
+- `sync-channel.ts` — `SharedArrayBuffer` + `Atomics.wait`, chunked both ways.
+  Only the client blocks; the server answers from its ordinary event loop.
+- `remote-volume.ts` — `RuntimeVolume` over that channel. Because the interface
+  was already the seam, `core-modules`, `Vfs` and the kernel are untouched.
+- `sync-syscalls.ts` — the filesystem and `spawnSync` share one channel.
+- `worker-entry.ts` — the guest half, built as its own bundle.
+
+Two packaging traps, both already paid for:
+
+1. The guest bundle must be **fully self-contained** (`noExternal` in
+   `tsup.config.ts`). The main bundle leaves `buffer` and friends external and
+   lets the host's bundler map them onto polyfills; the Worker is fetched as
+   its own module graph and gets no such help, so an external `buffer` resolves
+   to raw CommonJS with no named exports and the Worker dies before it runs.
+2. `new URL("./worker-entry.js", import.meta.url)` **does** survive Vite's
+   dependency pre-bundling — verified in Chrome, it fetches from
+   `node_modules/sandboxedjs/dist/`. Do not "fix" this with a blob URL: a blob
+   worker has no module-resolution context and could no longer `import()` the
+   host's esbuild or Rolldown binding.
+
+## Verifying the preview service worker
+
+The in-app browser pane refuses service worker registration outright — even a
+one-line worker fails — so the preview cannot be checked there and will always
+report itself unavailable. Real Chrome works. The quickest check is
+`/swcheck.html` in the harness, which stands up a tiny server and asserts that
+an absolute-path subresource is routed; `/preview.html` runs the full
+`create-vite` flow and takes about half a minute. Headless Chrome over CDP works
+too, which is how this was verified.
+
+Three things bit during that verification and are easy to re-introduce:
+`navigator.serviceWorker.ready` never resolves for a worker whose scope excludes
+the registering page; the claim path arrives under the worker's scope directory,
+so its pattern must not be anchored to the start; and a framed response needs
+`Cross-Origin-Embedder-Policy` as well as `Cross-Origin-Resource-Policy` or an
+isolated parent refuses it.
+
+## A trap worth remembering: inherited stdin is a terminal
+
+`stdio: "inherit"` hands a child the parent's standard input, and a terminal
+never ends. Give it a pipe and anything that reads to end-of-file first will
+wait forever — and `node` does that in `captureStdin` (`src/runtime/node.ts`)
+before it runs a script. The symptom is remote from the cause: a shell script
+that launches node prints nothing at all and hangs, with no error anywhere.
+
+`KernelChildProcess` (`node-child-process-bridge.ts`) therefore marks an
+inheriting child's stdin `isTTY`/`interactive`. `test/sync-child-process.test.ts`
+pins the reduced case — `spawnSync('sh', ['-c', 'node -e …'], {stdio:"inherit"})`
+— which is much cheaper to run than the create-vite flow it was found in.
+
+## The interactive-input chain, for future work
+
+1. `Terminal.key()` — `src/container/terminal.ts`. While a command runs it
+   writes each keystroke to `this.currentStdin` (a `Pipe`). **Raw mode changes
+   what it does**: no local echo, no CR→LF translation, and `ctrl+c`/`ctrl+d`
+   are passed through as keystrokes rather than becoming a signal and EOF.
+2. `node` command — `src/runtime/node.ts`, `execute()`. Forwards `ctx.stdin`
+   into `proc.write(...)`, propagates EOF via `proc.endInput()`, and mirrors the
+   program's `rawmode` event back onto `ctx.stdin.rawMode`.
+3. `LocalProcess.write` — `src/runtime/local-runtime-pod.ts`. Buffers input
+   until the task starts, then hands it to `core.writeStdin`.
+4. `createCoreModules` — `src/runtime/core-modules.ts`. With
+   `interactiveStdin: true`, `process.stdin` is a `PassThrough` that stays open;
+   `tty: true` sets `isTTY` on all three streams; `setRawMode` calls back into
+   `options.onRawMode`.
+5. `readline-module.ts`. `emitKeypressEvents(stream)` turns incoming data into
+   `keypress` events. `createInterface` defaults `terminal` from `output.isTTY`,
+   as Node does; a terminal `Interface` owns raw mode, keeps `line`/`cursor`
+   current, and echoes. **Prompt libraries read `rl.line` for the answer**, so
+   anything that stops it tracking shows up as an empty answer and a re-prompt,
+   not as an error.
+
+`settle()` in `local-runtime-pod.ts` decides when a process is finished. It
+counts pending timers, `core.readingStdin()` and `core.pendingRequests()` — an
+in-flight HTTP request is event-loop work and schedules no timer of its own.
+Check this first if a process exits before something asynchronous completes.
+
+## Known gaps
+
+- **Vite 8 / Rolldown works in a browser, not under a Node host.** (The old note
+  saying it cannot run at all was wrong.) In a browser it needs two things from
+  the host app, both now in the README: COOP/COEP headers, and
+  `optimizeDeps.exclude: ["@rolldown/binding-wasm32-wasi"]` so the bundler does
+  not pre-bundle away the `import.meta.url` its WASI worker is created from.
+  With those, `npm create vite` installs and the dev server serves transformed
+  modules — verified in Chrome. Under Node the binding's other build makes a
+  `node:wasi` instance preopening the real filesystem root, which cannot be
+  redirected at the sandbox volume, so Rolldown never finds the project and Vite
+  answers with its fallback page. Fixing that means running the *browser* build
+  on Node, which needs a `fetch` that handles `file:` URLs and a global `Worker`
+  over `worker_threads`. Vite 7 works on both and is what the Node test pins.
+
+- **`spawnSync`/`execSync`/`execFileSync` work under the Worker pod**, which is
+  the default. See *Isolation* in the README for the fallback rules. Under the
+  in-realm pod they still throw, naming the command — guest, child and event
+  loop share a thread there, so blocking the caller stops the child.
+- **esbuild in a browser.** `host-esbuild.ts` borrows the host's `esbuild-wasm`
+  on Node and returns `null` in a browser, so browser Vite transforms fail.
+- **No service worker**, so preview iframes have no URL. `box.request()` works
+  everywhere.
+- **`curl` to a non-CORS host cannot work in a browser.** Platform limit, not a
+  bug; the error message says so. The npm registry does send CORS headers, which
+  is why installing packages works.
+- **`child_process.execSync` and friends** cannot exist: they would have to
+  block the JS thread. They throw `ERR_FEATURE_UNAVAILABLE_ON_PLATFORM`.
+- Vite prints two `util` externalization warnings from `readable-stream`, which
+  declares `"util": false` for browsers and falls back on its own. Harmless.
+
+## Python: blocking syscalls, and what they are built on
+
+`src/runtime/python-syscalls.ts` is the layer that makes Pyodide behave like a
+Linux Python rather than a sandboxed evaluator. The constraint it removes is
+that **WebAssembly cannot wait for a JavaScript promise**: Pyodide's `setStdin`
+callback is synchronous, so anything only the host can answer asynchronously
+had to be answered immediately or not at all. Answering "not at all" is what
+made `input()` raise `EOFError`, and it is the same wall behind `socket`,
+`subprocess` and `time.sleep`.
+
+The primitive is WebAssembly stack switching (JSPI), reached through Pyodide's
+`run_sync`. It suspends the whole interpreter stack until a host promise
+settles, so an ordinary `def` — nested arbitrarily deep — can block while the
+event loop keeps running. Verified available unflagged in Node 25 and Chrome
+137+. **Adding a blocking syscall is now a method on the host facade**, not
+another special case; that is the point of the file.
+
+Three are wired:
+
+- **stdin.** `sys.stdin` is rebuilt as a real `TextIOWrapper`, not a patched
+  `input()` — otherwise `csv.reader(sys.stdin)` stays broken. EOF still raises
+  `EOFError` as CPython does.
+- **processes.** Only `subprocess.Popen` is replaced; `run`, `call`,
+  `check_call` and `check_output` are written in terms of it upstream, so the
+  family comes with it. The child is a *live* process on the host's event loop
+  (`kernel.spawn` + pipes), not a finished result: the parent suspends only
+  when it reads, waits or communicates, so `for line in p.stdout` follows a
+  child that is still running and `poll()` can say "running". `os.system` and
+  `os.popen` go to the same place — `os.system` previously returned 0 having
+  run *nothing*, which reads as success and is worse than an error.
+- **HTTP.** `urllib` handlers call `performRequest` (`src/net/commands.ts`),
+  the same path as `curl`. Deliberately not `fetch`: that is what makes Python
+  obey the container's `allowOutbound` policy instead of routing around it.
+
+### Third-party HTTP stacks, and a network-policy escape
+
+A library that brings its own transport does not go through `urllib`, and in
+Pyodide several reach JavaScript's `fetch` directly. **`requests` used to reach
+the internet from a container with `allowOutbound` off, while `curl` in the
+same container was correctly refused** — a real hole in the sandbox, found by
+testing the policy rather than the feature. `test/python-syscalls.test.ts`
+guards it.
+
+Such libraries cannot all be patched at boot, because pip installs them later.
+So adapters are registered by module name and applied when that module is first
+imported, through a hook on `builtins.__import__`. **Supporting another stack
+is a small function registered there, not a change to the machinery.** The
+`requests` adapter replaces `HTTPAdapter.send` — the one seam every call
+crosses, below sessions/redirects/cookies/retries and above the urllib3
+transport that would otherwise reach the network itself.
+
+### Hosts without stack switching
+
+Everything blocking rests on JSPI, and Pyodide 0.28 ships JSPI-only — there is
+no Asyncify build to fall back to. Where it is missing, the degradation is
+deliberate rather than incidental:
+
+- piped and redirected stdin still work, from the pre-drained buffer;
+- anything that must genuinely wait (interactive input, a child process) says
+  so plainly instead of faking end-of-file;
+- `requests` falls back to the library's own transport rather than breaking —
+  **but the network policy is not the part that degrades.** A host the
+  container forbids is still refused. Capability degrades; the sandbox does not.
+
+The only way to get blocking without JSPI is a Worker plus
+`SharedArrayBuffer`/`Atomics.wait` — the machinery `sync-channel.ts` already
+has for the Node runtime. It is a real project: Pyodide would move off the main
+thread and its Emscripten filesystem would have to reach the volume over the
+channel, and in a browser it additionally requires cross-origin isolation
+(COOP/COEP), which is a deployment requirement and not only code.
+
+Five traps, each already paid for and each cheap to reintroduce:
+
+1. **Pyodide maps JS `null` to a truthy `JsNull` proxy; only `undefined`
+   becomes `None`.** `buffered()` returns `undefined` to mean "you must
+   suspend", and a `?? EMPTY` on that path silently turned it back into
+   end-of-file — the exact bug the bridge exists to remove.
+2. **One interpreter is shared per container**, so its streams belong to
+   whichever program is running. A Python child binds over its parent while the
+   parent is suspended, so every host call that can suspend goes through
+   `resuming()`, which puts the parent's binding back.
+3. **`kernel.spawn` does not close a child's output pipes when it exits** —
+   `Container.spawn` does that itself — and a reader waiting on a pipe that
+   never ends waits forever. This deadlocked the whole suite once.
+4. **`Popen` must not run at construction.** `subprocess.run` hands `input=` to
+   `communicate()`, never to `Popen`.
+5. **Pyodide builds urllib without `ssl`, so `urllib.request.HTTPSHandler` does
+   not exist** to subclass. One handler subclassing `HTTPHandler` serves both
+   schemes, which also keeps `build_opener` treating it as a replacement.
+
+`asyncio.run` and `run_until_complete` are patched onto `run_sync` for the same
+reason: programs execute under `eval_code_async`, so Pyodide's loop is always
+already running and `asyncio.run` refuses to start a second one.
+
+Known remaining gaps:
+
+- **Python cannot accept connections.** `loop.create_server` is unimplemented
+  on Pyodide's WebLoop, so uvicorn and aiohttp install, import and start but
+  never bind — outbound requests work, inbound do not. Closing this means
+  widening the `RuntimePod` contract with a serve hook so Python can register
+  with `VirtualHttpRouter` (`src/runtime/virtual-http.ts`), the same router
+  that already routes `curl localhost:3000` to a Node server in the container,
+  plus an asyncio transport that frames HTTP between the router's structured
+  requests and the protocol's raw bytes. `router` is currently `protected` on
+  `LocalRuntimePod`; `WorkerRuntimePod` inherits it, so one implementation
+  covers both. For now the failure at least explains itself.
+
+- A library with its own transport and no registered adapter can still reach
+  the network directly and escape the policy. `requests` and `urllib` are
+  covered; the hook makes the next one cheap, but it is opt-in by design.
+- Package resolution: `loadPackagesFromImports` only sees Pyodide's lockfile
+  and `micropip` only installs pure-Python wheels, so `opencv-python` and
+  everything else needing a C extension built for wasm32-emscripten remains out
+  of reach. The fix is a resolution chain (lockfile → PyPI pure-Python → a wasm
+  binary-wheel index → clear failure), not a special case per library.

package/docs/original-x64.md

@@ -0,0 +1,39 @@
+# Original experimental x86-64 engines
+
+`createOriginalX64Backends()` returns two optional backends written in this
+repository: an instruction-to-WebAssembly translator and a JavaScript instruction
+interpreter. Neither embeds a third-party compiler or CPU emulator. Register the
+returned backends with `box.kernel.binaries.register(backend)`.
+
+The translator emits real Wasm integer operations, using mutable register globals
+and an instruction cache. It translates lazily during execution, rather than
+producing a distributable standalone Wasm file. The interpreter executes the same
+decoded instructions directly. They currently support the same instruction subset;
+register only the `emulation` backend to exercise the interpreter directly.
+
+Supported inputs are freestanding, static, little-endian x86-64 ET_EXEC ELF files.
+Loadable segments must fit a 16 MiB memory window and use addresses below 4 GiB.
+Dynamic linking is rejected. Supported instructions: 32/64-bit immediate and
+register MOV, register ADD/SUB/XOR/CMP, selected immediate ADD/SUB/CMP, RIP-relative
+LEA, NOP, short JMP/JZ/JNZ, relative JMP, and SYSCALL. Only the zero flag is modeled.
+There is no stack/argv ABI, arbitrary memory operand, SSE, libc, file-open syscall,
+networking, threads, or Docker support. Unsupported instructions fail explicitly.
+
+Linux calls: read stdin, write stdout/stderr, exit/exit_group, getpid. Unsupported
+calls return ENOSYS. Segment read/write permissions are checked for I/O buffers;
+self-modifying code is rejected. Each run owns its registers and memory. The
+one-million-instruction default budget and periodic event-loop yields bound loops
+and permit cancellation between batches. This is not a hardened security boundary
+or a claim of native performance. Translation currently has substantial per-
+instruction overhead; performance optimization is future work.
+
+Tests use `test/fixtures/native/hello.s`, assembled by Clang for Linux. The checked
+in ELF is built with the adjacent `package-elf.py` script. Both engines run the
+same binary, including a conditional loop and Linux console output; an infinite
+loop fixture verifies the instruction limit. Clang is only used to produce test
+inputs; it is not part of either engine at runtime.
+
+The local browser project registers both backends and exposes `native-hello`.
+Opening `/?native=emulation` selects the interpreter. Node and Python commands
+continue through their existing runtimes. This is an initial working CPU subset,
+not arbitrary Linux package compatibility.