sandboxedjs 0.2.10 → 0.2.12

package/docs/browser-runtime-architecture.md

@@ -0,0 +1,142 @@
+# Browser runtime architecture
+
+The current implementation is a JavaScript/POSIX compatibility runtime with
+CPython compiled to WebAssembly. It is not a Linux kernel or an x86 emulator.
+Keep this distinction in the public API and product claims.
+
+## Existing execution paths
+
+- JavaScript: the module engine and worker pods implement a subset of Node APIs.
+- Python: CPython runs in a process worker and calls the shared virtual kernel.
+- WASI: compiled wasm32-wasi programs use the existing WASI host.
+- Browser preview: a service worker routes HTTP into the virtual network.
+- Native Linux ELF executables and native Node addons: unsupported by these paths.
+
+Browser execution needs suitable worker URLs and, for blocking worker calls,
+SharedArrayBuffer and cross-origin isolation. Static hosting is still needed to
+serve application and runtime assets. It is not a computation backend.
+Python build-on-miss is different: its local builder requires Node/toolchains,
+and its remote builder uses another machine. Prebuilt compatible wheels avoid
+that backend. Not every PyPI package has such a wheel.
+
+## Changes in this pass
+
+The npm installer now overlaps up to six sibling package downloads while keeping
+filesystem mutations ordered. Installers created through `forCwd` share their
+metadata, archive and platform-detail caches within that installer family.
+Transient metadata/archive failures are evicted so retries can recover.
+An extracted package no longer hides an incomplete dependency tree, and optional
+dependencies override duplicate required entries.
+
+Python startup now cleans resources after worker creation or message-send
+failures, and honors cancellation that arrives before or during worker creation.
+
+Caches remain in memory; there is no persistent offline package store, lockfile
+implementation, global hoisting, or measured real-project performance claim.
+Browser bundling and the static import guard are checks of build compatibility,
+not substitutes for interactive browser acceptance testing.
+
+## Native Linux direction (not implemented)
+
+Use a separately loaded browser machine emulator with its own Linux kernel and
+disk image if running unchanged Linux packages is required. Keep it optional:
+ordinary JavaScript/Python projects should not download an entire Linux image.
+Expose the same high-level exec, filesystem transfer and preview operations, but
+report the selected backend and its limitations explicitly. The emulator owns
+its filesystem; transfer files explicitly instead of pretending it shares the
+JavaScript runtime's synchronous in-memory volume.
+
+This requires choosing the CPU architecture, emulator, kernel/root filesystem,
+network bridge and image distribution terms. Native addon compatibility then
+comes from running actual Node inside the guest Linux system. It brings larger
+assets and different startup/performance tradeoffs, and does not promise every
+Linux package will work. No such backend is included in this change.
+
+MIT licensing of this project can avoid a runtime subscription. It does not
+promise free CDN hosting, registry availability or third-party services forever.
+Audit the separate distribution terms of any kernel, disk image and packages
+before redistributing them.
+
+## Extension implementation
+
+The subsequent implementation adds ELF dispatch, external WASI command packs,
+three ordered backend tiers, a translator output cache, and optional local Git
+and embedded SQL adapters. See [Developer tool packs](developer-tool-packs.md)
+for the working APIs and explicit limits. Translation and emulator engines
+remain external and are not included.
+
+## Verified behaviour, and the gaps that remain
+
+A verification harness in the browser test project (`npm run verify`, driving
+real Chrome over the published package) exercises the container boot, Node,
+CPython, an npm install from the registry, both x86-64 ELF tiers, WASI command
+packs, Git, PostgreSQL, an in-container HTTP server, and the frontend
+automation subset. All of it passes in a real browser.
+
+One gap is closed and one remains.
+
+## Outbound HTTP for Python
+
+A browser cannot open a raw TCP socket, so nothing inside the container can
+speak TLS to a real server: outbound traffic has to leave at the HTTP layer,
+through the page's `fetch`. The container therefore serves a loopback HTTP
+endpoint, advertised to the guest as `SBX_HTTP_EGRESS`, which takes an
+*absolute* URL in the request line the way a proxy does and performs the
+transfer on the guest's behalf. `https://` targets are named in that request
+line rather than tunnelled with CONNECT, precisely so the guest never begins a
+TLS handshake it cannot finish; the real request leaves the page over HTTPS.
+
+The startup hook points `urllib.request` and `http.client` at it, so the
+standard library reaches the network without changes to a program. The same
+outbound policy every other exit applies is applied here, and because a refusal
+comes back as a real HTTP response it carries the reason -- a guest is told that
+outbound access is disabled and where to enable it, rather than being handed an
+errno it renders as "connection refused".
+
+Libraries that manage their own TLS rather than going through `http.client` --
+`urllib3`, and so `requests` -- still cannot egress. Their sockets would need to
+carry a TLS handshake this transport cannot terminate. A page's `fetch` is also
+subject to CORS, so a cross-origin target must send the headers that let the
+page read the response; that is a browser rule, not a container policy.
+
+## Blocking syscalls stop every thread
+
+Threads in this runtime are real and run in parallel: a worker thread happily
+burns CPU while the main thread sits in `time.sleep`, which releases the GIL.
+What they cannot do is make a syscall while another thread is inside one.
+
+The cause is in the interpreter image, not in this package. It is built with
+`-sPROXY_TO_PTHREAD` over a JavaScript-backed filesystem, so every syscall made
+on a thread is forwarded to the single thread that owns that filesystem -- the
+generated glue is full of `if (ENVIRONMENT_IS_PTHREAD) return
+proxyToMainThread(...)`. That thread answers a host call by blocking in
+`Atomics.wait`. While it is blocked it cannot service anybody else's proxied
+syscall, so one thread parked in a blocking read freezes every other thread's
+I/O until it returns.
+
+`asyncio.to_thread` is the case that meets this head-on: the loop parks in a
+blocking `select`, and waking it requires the worker thread to make a syscall
+that the parked thread would have to service. Neither completes.
+`to_thread` now raises immediately, naming the limitation, instead of hanging
+until the process is killed. That is a mitigation, not a fix.
+
+Three earlier explanations of this were wrong and are recorded here so the next
+person does not re-derive them: it is not a single control slot in the transport
+(threads do run concurrently), it is not the file-scope statics in `sbx_call`
+(they are downstream of the proxying), and it is not a missing per-thread
+channel on its own (a channel per thread does nothing while the syscalls are
+still funnelled to one thread).
+
+Fixing it is a change to how the runtime image is built, and there are two
+routes, neither small:
+
+- Stack switching. Suspend the wasm stack on a blocking call and return to the
+  event loop, instead of holding the thread in `Atomics.wait`. This is what the
+  Pyodide backend did through `run_sync`, and it is why that backend did not
+  have this problem. It needs JSPI and a transport rewritten around suspension.
+- Unproxied per-thread syscalls. Give each thread its own channel and host
+  server and stop routing syscalls through one thread. This fights the
+  JavaScript filesystem the image is built on, since that filesystem lives on
+  one thread by construction.
+
+Both are runtime-image work measured in days, not a patch plus a rebuild.

package/docs/compatibility-implementation-plan.md

@@ -0,0 +1,98 @@
+# Compatibility implementation plan
+
+## Decisions and evidence
+
+Keep the owned JavaScript runtime and CPython WebAssembly distribution. No
+Nodepod, Pyodide, v86, or replacement VM is required for the first milestones.
+The timeout, missing Node APIs and Python syscall deadlock are separate issues.
+
+The extension acceptance suite serves local wheels using node:http. In the
+restricted development environment listen(127.0.0.1) fails with EPERM. Its
+setup promise previously had no error handler, so setup waited for the hook
+timeout. The test now rejects immediately and teardown handles failed startup.
+With loopback listening permitted, all 12 extension acceptance tests passed in
+34.19 seconds of test execution (37.26 seconds total). This includes C, Cython,
+Rust/PyO3, Meson and Pydantic's compiled core. This establishes the Node-hosted
+fixture path, not browser acceptance or arbitrary PyPI compatibility.
+
+The Python build uses PROXY_TO_PTHREAD. backend.ts sets SBX_SERIAL_HOST_CALLS
+and refuses asyncio.to_thread because proxied blocking syscalls serialize the
+filesystem-owning thread. Removing the refusal alone is not a fix.
+
+## Alternatives
+
+| Approach | Useful for | Main constraint | Decision |
+| --- | --- | --- | --- |
+| Owned JavaScript builtins | Node utility and lifecycle APIs | Must reproduce observable semantics | First choice |
+| Compile source to Wasm | C/C++/Rust extensions and tools | ABI, dependencies and host calls must match | Preferred native-code route |
+| JSPI suspension | Freeing the worker event loop during a blocking host call | Runtime support, suspension boundaries, dynamic modules and pthread interaction | Prototype before adopting |
+| Asyncify | Suspension where JSPI is unavailable | Instrumentation cost and dynamic-module compatibility | Compare as fallback |
+| Per-thread syscall channels | Concurrent Python I/O | Must also remove synchronous proxy bottleneck and preserve fd semantics | Prototype alongside suspension |
+| WasmFS integration | Moving filesystem work away from JS-only ownership | Existing virtual FS needs a backend; not a flag-only change | Assess with thread prototype |
+| Host-native executables | Compatible tools on Node servers | Host OS/architecture, process permissions, unavailable in browsers | Optional explicit host capability |
+| Owned instruction interpreter | Selected binaries without source | ISA, loader, syscalls, linking, signals and threads | Defer until a concrete binary needs it |
+| Binary-to-Wasm translation | Repeated execution of supported binaries | Same ABI needs plus translation correctness and cache invalidation | Later, reuse existing backend interface |
+
+## Ordered implementation milestones
+
+### 1. Make extension acceptance trustworthy
+
+Run the complete local wheel suite with working loopback networking. Separate
+setup, download, install, link, import and execution failures. Fix each observed
+failure with a focused regression. Preserve failures; do not raise timeouts to
+make deadlocks disappear. Repeat in the browser using static fixture hosting.
+
+Exit: ordinary imports execute compiled C/C++/Rust fixtures; missing/incompatible
+artifacts produce actionable failures, and shutdown releases all resources.
+
+### 2. Replace Node stubs in dependency order
+
+Inventory actual package imports. Start with diagnostics_channel and utility
+APIs, followed by worker_threads backed by guest workers, then virtual network
+APIs. Separate virtual TCP from external browser networking. cluster/domain,
+http2, tls, inspector, v8 and vm each need an explicit supported surface rather
+than a catch-all function that pretends to implement them. A JS vm substitute
+must not claim a security boundary it does not provide.
+
+Exit per module: native-Node differential tests, error/cancellation tests,
+cross-guest isolation, and a real package that consumes that API in Node and
+browser hosts. Mark unsupported operations explicitly.
+
+### 3. Prove concurrent Python I/O before rebuilding production
+
+Build a minimal C/pthread fixture against the same Emscripten toolchain. One
+thread blocks on a host read while another writes; add cancellation and a
+timer on the owning JS worker. Compare an asynchronous proxy/suspension path
+with unproxied per-thread host calls. Channels alone cannot repair serialized
+proxy dispatch. Feature-detect JSPI; test fallback behavior explicitly.
+
+Measure idle CPU, wakeup latency, memory, download size and throughput for each
+variant. Select only after the fixture passes. Then rebuild CPython and all
+affected extension fixtures, preserving one shared descriptor authority.
+
+Exit: asyncio.to_thread, run_in_executor, concurrent socket read/write,
+cancellation, subprocess interaction and dynamic extensions work together.
+Remove the current guard only after these pass in supported browsers and Node.
+
+### 4. Expand portable binaries
+
+Use source builds targeting the existing Wasm ABI first. Track toolchain and
+ABI fingerprints in artifacts. If an essential source-unavailable binary
+remains, define one ISA and a static executable subset for an owned interpreter;
+reject unsupported instructions and syscalls deterministically. Bound memory,
+execution and cancellation. Do not start with dynamic Linux package parity.
+
+Exit: selected real binaries have reproducible correctness tests and measured
+startup, memory and throughput. Translation caching follows correctness.
+
+## Sources for the suspension prototypes
+
+- Emscripten pthread proxying and blocking rules:
+  https://emscripten.org/docs/porting/pthreads.html
+- Emscripten Asyncify and JSPI integration:
+  https://emscripten.org/docs/porting/asyncify.html
+- V8 JSPI boundary model:
+  https://v8.dev/blog/jspi-newapi
+
+These sources describe mechanisms; they do not establish that this CPython
+image or its extensions already support them. The prototypes are required.

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.