sandboxedjs 0.2.11 → 0.2.13

package/docs/agent/tasks/01-authoritative-metadata.md

@@ -0,0 +1,34 @@
+# Task 01: authoritative wheel metadata
+
+## Problem
+
+The current builder synthesizes `METADATA` from recipe fields. That duplicates
+the package's dependency declarations and can create a wheel that installs but
+resolves the wrong environment.
+
+## Deliverable
+
+Generate distribution metadata using the package's build metadata path under
+the controlled build environment. Preserve upstream `Name`, `Version`,
+`Requires-Dist`, extras, Python requirements, entry points, licenses, and other
+install-relevant files. SandboxedJS should add only its wheel tag, generator,
+and `Build-ABI` assertion.
+
+Recipe constraints may explicitly override a target-inapplicable dependency,
+but every override must be visible, justified, and tested.
+
+## Required tests
+
+- A fixture declares a conditional and an extra dependency upstream; neither
+  is copied into the recipe.
+- The resulting wheel and generated `index.json` contain the authoritative
+  requirements.
+- The resolver respects at least one marker/extras case.
+- A disagreement between recipe identity and upstream identity fails loudly.
+- Existing extension runtime tests remain green.
+
+## Exit gate
+
+No generic setuptools fixture needs handwritten `requires` metadata, and the
+index is provably derived from the wheel produced from upstream metadata.
+

package/docs/agent/tasks/02-native-dependencies.md

@@ -0,0 +1,35 @@
+# Task 02: native target dependencies and sysroot
+
+## Problem
+
+Extensions that name libraries or include their headers cannot currently
+declare, build, locate, or link those target dependencies generically.
+
+## Design requirement
+
+Represent native target dependencies separately from Python runtime
+dependencies and host build requirements. Each dependency must identify a
+pinned source, hash, build recipe, output markers, license/provenance, and ABI
+profile. The dynamic profile uses `out/sysroot-dynamic`; incompatible profiles
+must never share object archives.
+
+Add sysroot include and library search paths through generated cross-build
+configuration, not ad hoc recipe flags.
+
+## Reduced acceptance fixture
+
+Before attempting a large external library, create a tiny static target library
+with a header and one function. Build/install it through the dependency system,
+then build a setuptools extension that declares the library normally and calls
+it. The wheel must install and execute the function in the owned runtime.
+
+After the reduced fixture passes, add one small real native library already
+compatible with the project architecture. Do not begin with BLAS or NumPy.
+
+## Exit gate
+
+- Dependency closure is deterministic and cycle/error aware.
+- Rebuilds are skipped only when validated output markers match inputs/profile.
+- Missing dependency and wrong-profile reuse have focused negative tests.
+- Reduced and real-library extensions import and run in owned CPython.
+

package/docs/agent/tasks/03-reproducible-inputs.md

@@ -0,0 +1,27 @@
+# Task 03: reproducible inputs, patches, and provenance
+
+## Deliverable
+
+Unify source archives, build-tool wheels, native dependencies, and package
+patches under verified acquisition. No release artifact may depend on an
+unpinned `pip install setuptools wheel ...` result.
+
+Define a visible patch layout. A patch records package/version, upstream source
+hash, reason, target fact being substituted, and a test. Patch application must
+fail on drift rather than fuzzily succeeding against another source version.
+
+Record enough provenance in build output or adjacent index metadata to answer:
+
+- which source hash produced this wheel;
+- which build tools and target libraries were used;
+- which ABI ID and recipe revision were used;
+- which patches were applied.
+
+## Exit gate
+
+- Offline rebuild succeeds from a populated verified cache.
+- A changed hash, unpinned build tool, or drifting patch fails before compile.
+- Two identical clean builds produce equivalent wheel contents, allowing only
+  explicitly documented archive timestamp normalization until deterministic
+  ZIP output is implemented.
+

package/docs/agent/tasks/04-build-frontends.md

@@ -0,0 +1,27 @@
+# Task 04: build frontend interface
+
+## Purpose
+
+Turn the current kinds into a stable backend interface rather than accumulating
+branches in `build_extension.py`.
+
+## Required interface
+
+Each backend receives verified source, host tools, target configuration,
+declared native dependencies, staging directory, and ABI contract. It returns a
+wheel tree or wheel plus build evidence. It cannot mutate the ABI.
+
+Retain proven setuptools/Cython and PyO3 behavior. Add another frontend only
+when a selected cohort package requires it; likely candidates include PEP 517
+wheel hooks, Meson, or scikit-build/CMake. Do not implement all frontends
+speculatively.
+
+Keep package quirks in patches/recipes and backend mechanics in adapters.
+
+## Exit gate
+
+- Backend selection is explicit and schema-validated.
+- The generic orchestrator has no package-name checks.
+- Existing fixtures pass through the interface.
+- One pyproject-only package runs through a real isolated PEP 517 path.
+

package/docs/agent/tasks/05-registry-integration.md

@@ -0,0 +1,27 @@
+# Task 05: registry and installer integration
+
+## Deliverable
+
+Produce an immutable wheel repository that the existing SandboxedJS `pip`
+resolver can consume. Define schema versioning, atomic publication layout,
+digest verification, ABI partitioning, and dependency metadata.
+
+The browser runtime remains an installer, not a compiler. A missing native
+wheel should return a structured, actionable classification that a host may use
+later to request a build. It must not perform an implicit remote mutation.
+
+## Required tests
+
+- Correct ABI wheel wins over incompatible and host-native candidates.
+- Wrong ABI and wrong digest are refused before installation.
+- A failed graph leaves no partial site-packages state.
+- A newly built test wheel can be indexed, served, installed, imported, and
+  exercised through the ordinary container command.
+- Index publication cannot expose a wheel before its metadata and content are
+  complete.
+
+## Exit gate
+
+A clean consumer needs only a runtime plus index URL/object; no local source
+tree or compiler is required for supported packages.
+

package/docs/agent/tasks/06-package-cohorts.md

@@ -0,0 +1,42 @@
+# Task 06: representative package cohorts
+
+## Purpose
+
+Measure generality without allowing one package to define the architecture.
+
+## Selection method
+
+Choose small packages first, pin exact versions and hashes, and record why each
+adds a new capability. Select at least one from each applicable cohort:
+
+1. pure wheel control case;
+2. setuptools C extension without external target libraries;
+3. generated C/Cython extension;
+4. Rust/PyO3 extension;
+5. extension using a separately built native target library;
+6. package requiring a visible cross-compilation patch;
+7. pyproject/PEP 517 backend not already covered;
+8. scientific-stack stress case, eventually including NumPy.
+
+Do not count existing probes as real-package cohort evidence, but retain them as
+reduced regression tests.
+
+## Compatibility report
+
+For every attempted package, record exactly one status:
+
+- `supported-generic`;
+- `supported-recipe`;
+- `blocked-platform-capability`;
+- `blocked-toolchain`;
+- `not-yet-attempted`.
+
+Record build command, source hash, wheel hash, ABI ID, test behavior, peak size
+or memory when material, and the earliest unsupported assumption on failure.
+
+## Exit gate
+
+At least five independent real packages across four native/build shapes pass
+runtime behavior tests, and failures produce reusable classifications instead
+of package-specific branches.
+

package/docs/agent/tasks/07-build-on-miss-boundary.md

@@ -0,0 +1,31 @@
+# Task 07: external build-on-miss boundary
+
+## Purpose
+
+Specify the seam that can later connect the installer to a trusted build
+service without deploying that service or placing a toolchain in the browser.
+
+## Deliverable
+
+Define versioned request/status/result schemas. A request includes normalized
+requirement, source/index evidence, target ABI ID, policy/recipe revision, and
+an idempotency key. A result includes immutable wheel/index locations, hashes,
+provenance, logs summary, compatibility classification, and terminal state.
+
+States should cover queued, resolving, building host tools, building target
+dependencies, building wheel, testing, published, unsupported, failed, and
+cancelled. Repeated identical requests must converge on one cached artifact.
+
+Security requirements include source allowlists/policy, resource limits,
+network isolation, no untrusted artifact publication before runtime tests,
+digest verification, and auditability.
+
+## Exit gate
+
+- Schemas and a local fake implementation are tested.
+- Installer/host integration can report a buildable miss without automatically
+  triggering external work.
+- Cached success, unsupported result, transient failure, cancellation, and ABI
+  rollover are covered.
+- No cloud service is deployed without explicit user authorization.
+

package/docs/browser-runtime-architecture.md

@@ -0,0 +1,132 @@
+# 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.
+
+## Python thread offloads
+
+The bundled pthread interpreter supports standard `asyncio.to_thread`,
+`run_in_executor`, and AnyIO's thread pool, including synchronous FastAPI routes.
+These execute on real Python worker threads, preserving context propagation,
+exceptions, and cancellation of the awaiting task.
+
+Native socket calls release the GIL and send requests directly from each pthread
+to the process supervisor over a private BroadcastChannel. Every outstanding
+request owns a shared response buffer, so a waiting interpreter cannot prevent
+another thread from completing network I/O. The supervisor still applies the
+same descriptor ownership and outbound network policy.
+
+Emscripten filesystem operations still proxy through the interpreter thread.
+While other Python threads exist, the asyncio selector limits each wait to
+10 ms and briefly yields, allowing those queued operations to run. This prevents
+the old deadlock between a sleeping selector and a worker trying to wake it.
+It adds polling overhead while the thread pool is alive.
+
+Deploy the matching `python-worker.js` and the complete `python/` runtime directory
+together. The worker detects the native bridge before enabling this behavior.
+Older custom interpreter images retain the previous explicit `to_thread` error
+and inline AnyIO fallback rather than silently entering a known deadlock.
+
+Regression coverage includes context variables, exceptions, cancellation, file
+I/O, simultaneous thread HTTP calls into an asyncio server, executor shutdown,
+and FastAPI synchronous endpoints. The browser fixture also offloads a file read
+and an outbound HTTPX request from a FastAPI streaming endpoint. This does not
+certify arbitrary native extensions or indefinite blocking filesystem operations;
+thread churn and long-running cleanup soak remain release gates. Browser egress
+restrictions still apply independently of threading.

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.