@volter/browser-runtime

The engine-neutral browser kernel. It owns filesystem and HTTP contracts, the process registry, OPFS persistence, POSIX metadata, virtual WebSockets, sandboxed previews, private byte storage, sharing clients, and strict program manifests.

It intentionally has no execution-engine or UI dependency. Compose it through an adapter such as @volter/browser-node, then register additional program runners with runtime.registerProgram(name, runner).

For commands supported by an enforcing backend, pass { filesystemPolicy: { writableRoots: ["/workspace", "/tmp"] } } to start() or spawn(). An empty list allows reads but refuses every filesystem mutation. The process host refuses unsupported backends with ENOTSUP. A custom runner can declare { filesystemPolicy: true } as the third registerProgram argument only if it enforces the supplied policy and propagates it to every descendant. The flag is a trusted adapter contract, not an automatic sandbox around arbitrary JavaScript. With an attached lifecycle, background: true saves the command and its policy before execution. workspace.resume() restores that policy; supplied options can narrow its grants but cannot remove or widen them. Lifecycle schema 2 migrates existing workspace identities, processes and attachments. Older readers reject the new schema. Storage failures reject the launch and flush().

The public embedding contract includes:

• start() for cancellable process handles and spawn() for completion-only commands;
• typed process, port, workspace, metrics, and disposal events;
• direct Fetch-shaped requests to virtual ports plus browser preview URLs;
• process/filesystem/storage/cache/memory metrics; and
• one idempotent dispose() boundary for processes, ports, tunnels, durable workspaces, and host resources.

The runtime starts prepared images only: an image's build half (every COPY, stage and RUN) is prepared on a machine, and the tab applies the image by its digest and starts its command.

BrowserSandboxBridge is the agent-facing preview contract. Once its sandbox is ready, consumers can call snapshot(), query(), screenshot(), navigate(), reloadPreview(), and waitForNetworkIdle(). It retains a bounded stream of typed console, exception, rejection, and navigation observations. setPreviewScript() installs optional instrumentation before the application starts and reapplies it after navigation; the script is never ambient authority in the host page. waitForReady(timeoutMs = 15000) waits for both the authenticated bridge and generated preview. Its timeout applies to that call; subsequent calls can observe a late connection. The optional onReady callback fires once when both connect, even after an earlier timeout. The ready and initialPreviewReady promises retain their first result. Screenshot capture returns a PNG when the browser permits safe rasterization and a sanitized SVG otherwise.

Portable projects use runtime.exportProject({ format: "json" | "zip", root }) and runtime.importProject(data, { root }). JSON exports are strict versioned envelopes. ZIP exports are ordinary rooted archives that unpack with standard tools and carry versioned metadata in ZIP extra fields. Both preserve binary content, POSIX mode, and millisecond modification time; both verify SHA-256 integrity before import mutates the destination. Imports reject traversal, duplicate paths, unsupported ZIP features, expansion beyond documented bounds, and corrupt file or archive checksums.

The package ships JavaScript, declarations, and worker entry modules under dist/; source worker URLs remain relative to those emitted modules so normal consumer bundlers can discover them. See the repository README for a complete example.