sandboxedjs 0.1.28 → 0.1.29

package/dist/index.d.cts

@@ -27,7 +27,30 @@ interface ChildSpawnConfig {
     parentPid?: number;
 }
 type SpawnChild = (config: ChildSpawnConfig) => ChildHandle;
-declare function createChildProcessModule(spawnChild: SpawnChild, defaultCwd: () => string): Record<string, unknown>;
+/**
+ * Run a child to completion without returning to the event loop.
+ *
+ * Supplied only by a pod that can actually block — one whose guest runs on its
+ * own thread. Where it is absent the synchronous entry points keep reporting
+ * that they are unavailable, which is the honest answer for an in-realm pod.
+ */
+type SyncSpawn = (request: {
+    command: string;
+    args: string[];
+    cwd: string;
+    env?: Record<string, string>;
+    input?: string;
+}) => {
+    status: number | null;
+    stdout: string;
+    stderr: string;
+    signal: string | null;
+    error?: {
+        code?: string;
+        message: string;
+    };
+};
+declare function createChildProcessModule(spawnChild: SpawnChild, defaultCwd: () => string, syncSpawn?: SyncSpawn): Record<string, unknown>;
 
 /**
  * Clean-room contracts between SandboxedJS and its JavaScript runtime.
@@ -1639,6 +1662,24 @@ interface ContainerOptions {
      * ```
      */
     pod?: RuntimePod;
+    /**
+     * Where guest programs run.
+     *
+     * `"worker"` (the default) gives each program its own thread, which is what
+     * makes synchronous child processes work and keeps guest code out of the
+     * host's realm; it falls back automatically where the host cannot support it.
+     * `"realm"` forces the in-realm runtime.
+     */
+    isolation?: "worker" | "realm";
+    /**
+     * Where to load the guest worker bundle from.
+     *
+     * Defaults to the copy shipped beside the main bundle, which is what a
+     * published package wants. Worth setting when a bundler has moved or
+     * rewritten it — or when running from source, where the built file is the
+     * only one a Worker can load.
+     */
+    workerUrl?: string | URL;
     /** Python runtime settings; a browser host uses this to locate the wasm. */
     python?: PythonOptions;
 }
@@ -2457,6 +2498,14 @@ interface CoreModulesOptions {
     };
     /** Backs `child_process`; without it the module reports as unavailable. */
     spawnChild?: SpawnChild;
+    /**
+     * Backs the `*Sync` half of `child_process`.
+     *
+     * Only a pod whose guest runs on its own thread can supply this — blocking
+     * requires somewhere else for the child's work to happen. Without it the
+     * synchronous entry points keep reporting that they are unavailable.
+     */
+    syncSpawn?: SyncSpawn;
     /** File holding the process's standard input, exposed as descriptor 0. */
     stdinPath?: string;
     /** Keep `process.stdin` open and fed by {@link writeStdin} rather than ending it. */
@@ -2496,6 +2545,13 @@ declare function createCoreModules(options: CoreModulesOptions): {
     pendingHandles(): number;
     /** Active timers which called `unref()` and therefore only merit startup grace. */
     pendingUnrefed(): number;
+    /**
+     * Cancel every timer this process still holds.
+     *
+     * Called when a process is killed: the process is finished, but its
+     * scheduled work would otherwise keep running on the host's event loop.
+     */
+    cancelTimers(): void;
     /**
      * Client requests sent but not yet read to completion.
      *
@@ -2533,6 +2589,99 @@ declare function looksLikeEsm(source: string): boolean;
  */
 declare function transformEsm(source: string, filename?: string): EsmTransformResult | null;
 
+/**
+ * A volume that keeps a second, foreign filesystem in step with itself.
+ *
+ * Rolldown's browser WebAssembly binding owns a `memfs` volume of its own —
+ * its Rust resolver reads through WASI, not through anything JavaScript can
+ * hand it. So the sandbox project has to exist in two places at once, and the
+ * copy has to stay current: a dev server reads `index.html` when the request
+ * arrives, not when the process started.
+ *
+ * Mirroring on write rather than copying up-front is what makes that true. The
+ * previous approach took one deep snapshot per spawn, which was both expensive
+ * — every `npm run dev` re-copied `node_modules` — and already stale by the
+ * time it mattered, so an edit during a session was served from the old tree.
+ *
+ * The mirror is deliberately one-way and best-effort. It is a cache for a
+ * consumer that only reads; a write that fails to reach it must never fail the
+ * write that the container itself made.
+ */
+
+/** The slice of a `memfs`-style filesystem the mirror writes through. */
+interface MirrorFs {
+    mkdirSync(path: string, options?: {
+        recursive?: boolean;
+    }): void;
+    writeFileSync(path: string, data: Uint8Array): void;
+    symlinkSync(target: string, path: string): void;
+    rmSync?(path: string, options?: {
+        recursive?: boolean;
+        force?: boolean;
+    }): void;
+    unlinkSync?(path: string): void;
+    rmdirSync?(path: string): void;
+}
+/**
+ * A `RuntimeVolume` that forwards every mutation to an optional mirror.
+ *
+ * Wrapping rather than modifying `MemoryVolume` keeps the mirroring concern out
+ * of the filesystem, and keeps this transparent to the kernel, whose `Vfs`
+ * takes any `RuntimeVolume`.
+ */
+declare class MirroringVolume implements RuntimeVolume {
+    private readonly inner;
+    private mirror;
+    private root;
+    constructor(inner?: MemoryVolume);
+    /**
+     * Start mirroring the tree under `root`, seeding it with what is there now.
+     *
+     * Called once the Rolldown binding is known to be in play; before that a
+     * container pays nothing for this.
+     */
+    attach(mirror: MirrorFs, root: string): void;
+    detach(): void;
+    /** Copy the whole subtree across. The only bulk operation that remains. */
+    private seed;
+    /** Is this path inside the mirrored subtree? */
+    private mirrored;
+    /**
+     * Run a mirror update, swallowing failure.
+     *
+     * The mirror is a read-only cache for another engine. If it rejects
+     * something — an unsupported operation, a path it has not seen — the
+     * container's own write has still happened and must still succeed.
+     */
+    private safely;
+    /** Push a path's current state across, whatever it is now. */
+    private sync;
+    readFileSync(path: string): Uint8Array;
+    readdirSync(path: string): string[];
+    lstatSync(path: string): VolumeStat;
+    readlinkSync(path: string): string;
+    getStats(): VolumeStats;
+    writeFileSync(path: string, data: string | Uint8Array): void;
+    appendFileSync(path: string, data: string | Uint8Array): void;
+    mkdirSync(path: string, options?: {
+        mode?: number;
+    }): void;
+    rmdirSync(path: string): void;
+    unlinkSync(path: string): void;
+    renameSync(from: string, to: string): void;
+    symlinkSync(target: string, path: string): void;
+    linkSync(existing: string, path: string): void;
+    truncateSync(path: string, length?: number): void;
+    chmodSync(path: string, mode: number): void;
+    lchmodSync(path: string, mode: number): void;
+    chownSync(path: string, uid: number, gid: number): void;
+    lchownSync(path: string, uid: number, gid: number): void;
+    utimesSync(path: string, atime: Date, mtime: Date): void;
+    snapshot(): MemoryVolumeSnapshotEntry[];
+    /** A restore replaces everything, so the mirror is rebuilt rather than patched. */
+    restore(entries: MemoryVolumeSnapshotEntry[]): void;
+}
+
 interface LocalRuntimeOptions {
     workdir?: string;
     env?: Record<string, string>;
@@ -2569,10 +2718,10 @@ declare const WASM_ALIASES: Record<string, string>;
  * dedicated Worker before this becomes the default untrusted-code path.
  */
 declare class LocalRuntimePod implements RuntimePod {
-    readonly volume: MemoryVolume;
+    readonly volume: MirroringVolume;
     readonly packages: RuntimePackageInstaller;
     readonly instanceId: string;
-    private readonly router;
+    protected readonly router: VirtualHttpRouter;
     readonly proxy: {
         activePorts: (_instanceId?: string) => number[];
     };
@@ -2585,15 +2734,15 @@ declare class LocalRuntimePod implements RuntimePod {
         spawn(config: ChildSpawnConfig): ChildHandle;
     };
     private disposed;
-    private readonly workdir;
-    private readonly env;
-    private readonly aliases;
+    protected readonly workdir: string;
+    protected readonly env: Record<string, string>;
+    protected readonly aliases: Record<string, string>;
     private readonly modules;
     private readonly esbuild;
     private rolldownBinding;
     /** Backs outbound `http`/`https` client requests from inside the sandbox. */
     private readonly fetch;
-    private constructor();
+    protected constructor(options: LocalRuntimeOptions);
     static boot(options?: LocalRuntimeOptions): Promise<LocalRuntimePod>;
     spawn(command: string, args?: string[], options?: Record<string, unknown>): Promise<RuntimeProcess>;
     /**
@@ -2678,6 +2827,47 @@ declare class CleanPackageInstaller implements RuntimePackageInstaller {
 }
 declare function extractNpmTarball(volume: RuntimeVolume, compressed: Uint8Array, destination: string): void;
 
+/**
+ * Starting the guest Worker, in whichever environment the host happens to be.
+ *
+ * The awkward part of shipping a Worker from a library is not creating it, but
+ * naming it. `new URL("./worker-entry.js", import.meta.url)` is the form every
+ * bundler recognises, and it resolves correctly from `dist/` — but a bundler
+ * that *pre-bundles* this package rewrites `import.meta.url` to point into its
+ * own dependency cache, where no such file exists. That is the same trap
+ * Rolldown's WASI binding falls into, and it surfaces just as obliquely.
+ *
+ * So this never assumes it worked. The caller treats a failure to start as
+ * "this host cannot run the Worker pod" and uses the in-realm pod instead.
+ */
+interface RuntimeWorker {
+    postMessage(message: unknown): void;
+    onMessage(listener: (message: unknown) => void): void;
+    onError(listener: (error: unknown) => void): void;
+    terminate(): unknown;
+}
+/**
+ * Start the guest Worker and wait for it to say it is alive.
+ *
+ * Rejects rather than hanging when the script cannot be loaded: a Worker whose
+ * script 404s reports an `error` event and would otherwise leave the caller
+ * waiting for a ready message that can never arrive.
+ */
+declare function startRuntimeWorker(options?: {
+    url?: string | URL;
+    workerData?: Record<string, unknown>;
+    timeoutMs?: number;
+}): Promise<RuntimeWorker>;
+
+/**
+ * Can this environment support a blocking client at all?
+ *
+ * `SharedArrayBuffer` needs cross-origin isolation in a browser, and
+ * `Atomics.wait` is forbidden on a browser's main thread — which is why the
+ * client is always the Worker.
+ */
+declare function syncChannelSupported(): boolean;
+
 /**
  * sandboxedjs — a Linux-like container that runs entirely inside Node.js.
  *
@@ -2696,4 +2886,4 @@ declare function extractNpmTarball(volume: RuntimeVolume, compressed: Uint8Array
  * ```
  */
 
-export { ArithError, BufferSink, type CPythonOptions, CallbackSink, type ChildHandle, type ChildSpawnConfig, type CleanInstallerOptions, CleanPackageInstaller, type Command, CommandRegistry, CommonJsEngine, type CommonJsEngineOptions, type CommonJsModule, Container, ContainerFs, type ContainerOptions, type ContextInit, type CoreModulesOptions, type Cred, type DirEntry, ERRNO, type Env, type ErrnoCode, type EsmTransformResult, type ExecContext, type ExecOptions, type ExecResult, type FileData, FileInput, FileOutput, type GroupEntry, type HttpResponse, IncompleteInputError, type InputStream, type InstallOptions, type Job, KERNEL_NAME, KERNEL_RELEASE, Kernel, type KernelOptions, type ListeningPort, type LocalRuntimeOptions, LocalRuntimePod, MemoryVolume, type MountEntry, NODE_VERSION, NPM_VERSION, type NetInterface, type NetworkOptions, NetworkStack, NullInput, NullOutput, OS_RELEASE, type OutputStream, PYTHON_VERSION, type PasswdEntry, Pipe, Process, type ProcessKind, type ProcessOptions, type ProcessState, ProcessTable, type PythonOptions, ROOT_CRED, type ResolvedExecutable, type RootfsOptions, type RunOptions, type RunResult, type RuntimePackageInstaller, type RuntimePod, type RuntimeProcess, type RuntimeProcessManager, type RuntimeProcessResult, type RuntimeVolume, SIGNALS, SIGNAL_NAMES, Session, type SessionInit, type SessionResult, type SessionRunOptions, Shell, ShellExit, type ShellIO, type ShellInit, Lexer as ShellLexer, type ShellOptions, ShellSyntaxError, type SpawnChild, type SpawnHandle, Stats, type Stdio, SysError, TeeOutput, Terminal, type TerminalOptions, UserDatabase, Variables, Vfs, VirtualHttpRouter, VirtualHttpServer, VirtualIncomingMessage, type VirtualNode, type VirtualProvider, VirtualServerResponse, WASM_ALIASES, type WriteOptions, allCommands, applyChmod, braceExpand, buildRootfs, builtinNames, captureStdio, configureCPython, configurePython, createChildProcessModule, createContainer, createContext, createCoreModules, createContainer as default, defineCommand, evalArith, exitCodeForSignal, expandPrompt, expandWord, expandWords, extractNpmTarball, fnmatch, formatMode, getBuiltin, glob, globToRegex, hasMagic, installUserland, isBuiltinName, isCPythonAvailable, isPythonAvailable, isSysError, looksLikeEsm, makeCred, normalizeSignal, octalMode, parse as parseShell, parseUmask, path as posixPath, resetPidCounter, shellQuote, strerror, transformEsm, unameInfo };
+export { ArithError, BufferSink, type CPythonOptions, CallbackSink, type ChildHandle, type ChildSpawnConfig, type CleanInstallerOptions, CleanPackageInstaller, type Command, CommandRegistry, CommonJsEngine, type CommonJsEngineOptions, type CommonJsModule, Container, ContainerFs, type ContainerOptions, type ContextInit, type CoreModulesOptions, type Cred, type DirEntry, ERRNO, type Env, type ErrnoCode, type EsmTransformResult, type ExecContext, type ExecOptions, type ExecResult, type FileData, FileInput, FileOutput, type GroupEntry, type HttpResponse, IncompleteInputError, type InputStream, type InstallOptions, type Job, KERNEL_NAME, KERNEL_RELEASE, Kernel, type KernelOptions, type ListeningPort, type LocalRuntimeOptions, LocalRuntimePod, MemoryVolume, type MountEntry, NODE_VERSION, NPM_VERSION, type NetInterface, type NetworkOptions, NetworkStack, NullInput, NullOutput, OS_RELEASE, type OutputStream, PYTHON_VERSION, type PasswdEntry, Pipe, Process, type ProcessKind, type ProcessOptions, type ProcessState, ProcessTable, type PythonOptions, ROOT_CRED, type ResolvedExecutable, type RootfsOptions, type RunOptions, type RunResult, type RuntimePackageInstaller, type RuntimePod, type RuntimeProcess, type RuntimeProcessManager, type RuntimeProcessResult, type RuntimeVolume, SIGNALS, SIGNAL_NAMES, Session, type SessionInit, type SessionResult, type SessionRunOptions, Shell, ShellExit, type ShellIO, type ShellInit, Lexer as ShellLexer, type ShellOptions, ShellSyntaxError, type SpawnChild, type SpawnHandle, Stats, type Stdio, SysError, TeeOutput, Terminal, type TerminalOptions, UserDatabase, Variables, Vfs, VirtualHttpRouter, VirtualHttpServer, VirtualIncomingMessage, type VirtualNode, type VirtualProvider, VirtualServerResponse, WASM_ALIASES, type WriteOptions, allCommands, applyChmod, braceExpand, buildRootfs, builtinNames, captureStdio, configureCPython, configurePython, createChildProcessModule, createContainer, createContext, createCoreModules, createContainer as default, defineCommand, evalArith, exitCodeForSignal, expandPrompt, expandWord, expandWords, extractNpmTarball, fnmatch, formatMode, getBuiltin, glob, globToRegex, hasMagic, installUserland, isBuiltinName, isCPythonAvailable, isPythonAvailable, isSysError, looksLikeEsm, makeCred, normalizeSignal, octalMode, parse as parseShell, parseUmask, path as posixPath, resetPidCounter, shellQuote, startRuntimeWorker, strerror, syncChannelSupported, transformEsm, unameInfo };

package/dist/index.d.ts

@@ -27,7 +27,30 @@ interface ChildSpawnConfig {
     parentPid?: number;
 }
 type SpawnChild = (config: ChildSpawnConfig) => ChildHandle;
-declare function createChildProcessModule(spawnChild: SpawnChild, defaultCwd: () => string): Record<string, unknown>;
+/**
+ * Run a child to completion without returning to the event loop.
+ *
+ * Supplied only by a pod that can actually block — one whose guest runs on its
+ * own thread. Where it is absent the synchronous entry points keep reporting
+ * that they are unavailable, which is the honest answer for an in-realm pod.
+ */
+type SyncSpawn = (request: {
+    command: string;
+    args: string[];
+    cwd: string;
+    env?: Record<string, string>;
+    input?: string;
+}) => {
+    status: number | null;
+    stdout: string;
+    stderr: string;
+    signal: string | null;
+    error?: {
+        code?: string;
+        message: string;
+    };
+};
+declare function createChildProcessModule(spawnChild: SpawnChild, defaultCwd: () => string, syncSpawn?: SyncSpawn): Record<string, unknown>;
 
 /**
  * Clean-room contracts between SandboxedJS and its JavaScript runtime.
@@ -1639,6 +1662,24 @@ interface ContainerOptions {
      * ```
      */
     pod?: RuntimePod;
+    /**
+     * Where guest programs run.
+     *
+     * `"worker"` (the default) gives each program its own thread, which is what
+     * makes synchronous child processes work and keeps guest code out of the
+     * host's realm; it falls back automatically where the host cannot support it.
+     * `"realm"` forces the in-realm runtime.
+     */
+    isolation?: "worker" | "realm";
+    /**
+     * Where to load the guest worker bundle from.
+     *
+     * Defaults to the copy shipped beside the main bundle, which is what a
+     * published package wants. Worth setting when a bundler has moved or
+     * rewritten it — or when running from source, where the built file is the
+     * only one a Worker can load.
+     */
+    workerUrl?: string | URL;
     /** Python runtime settings; a browser host uses this to locate the wasm. */
     python?: PythonOptions;
 }
@@ -2457,6 +2498,14 @@ interface CoreModulesOptions {
     };
     /** Backs `child_process`; without it the module reports as unavailable. */
     spawnChild?: SpawnChild;
+    /**
+     * Backs the `*Sync` half of `child_process`.
+     *
+     * Only a pod whose guest runs on its own thread can supply this — blocking
+     * requires somewhere else for the child's work to happen. Without it the
+     * synchronous entry points keep reporting that they are unavailable.
+     */
+    syncSpawn?: SyncSpawn;
     /** File holding the process's standard input, exposed as descriptor 0. */
     stdinPath?: string;
     /** Keep `process.stdin` open and fed by {@link writeStdin} rather than ending it. */
@@ -2496,6 +2545,13 @@ declare function createCoreModules(options: CoreModulesOptions): {
     pendingHandles(): number;
     /** Active timers which called `unref()` and therefore only merit startup grace. */
     pendingUnrefed(): number;
+    /**
+     * Cancel every timer this process still holds.
+     *
+     * Called when a process is killed: the process is finished, but its
+     * scheduled work would otherwise keep running on the host's event loop.
+     */
+    cancelTimers(): void;
     /**
      * Client requests sent but not yet read to completion.
      *
@@ -2533,6 +2589,99 @@ declare function looksLikeEsm(source: string): boolean;
  */
 declare function transformEsm(source: string, filename?: string): EsmTransformResult | null;
 
+/**
+ * A volume that keeps a second, foreign filesystem in step with itself.
+ *
+ * Rolldown's browser WebAssembly binding owns a `memfs` volume of its own —
+ * its Rust resolver reads through WASI, not through anything JavaScript can
+ * hand it. So the sandbox project has to exist in two places at once, and the
+ * copy has to stay current: a dev server reads `index.html` when the request
+ * arrives, not when the process started.
+ *
+ * Mirroring on write rather than copying up-front is what makes that true. The
+ * previous approach took one deep snapshot per spawn, which was both expensive
+ * — every `npm run dev` re-copied `node_modules` — and already stale by the
+ * time it mattered, so an edit during a session was served from the old tree.
+ *
+ * The mirror is deliberately one-way and best-effort. It is a cache for a
+ * consumer that only reads; a write that fails to reach it must never fail the
+ * write that the container itself made.
+ */
+
+/** The slice of a `memfs`-style filesystem the mirror writes through. */
+interface MirrorFs {
+    mkdirSync(path: string, options?: {
+        recursive?: boolean;
+    }): void;
+    writeFileSync(path: string, data: Uint8Array): void;
+    symlinkSync(target: string, path: string): void;
+    rmSync?(path: string, options?: {
+        recursive?: boolean;
+        force?: boolean;
+    }): void;
+    unlinkSync?(path: string): void;
+    rmdirSync?(path: string): void;
+}
+/**
+ * A `RuntimeVolume` that forwards every mutation to an optional mirror.
+ *
+ * Wrapping rather than modifying `MemoryVolume` keeps the mirroring concern out
+ * of the filesystem, and keeps this transparent to the kernel, whose `Vfs`
+ * takes any `RuntimeVolume`.
+ */
+declare class MirroringVolume implements RuntimeVolume {
+    private readonly inner;
+    private mirror;
+    private root;
+    constructor(inner?: MemoryVolume);
+    /**
+     * Start mirroring the tree under `root`, seeding it with what is there now.
+     *
+     * Called once the Rolldown binding is known to be in play; before that a
+     * container pays nothing for this.
+     */
+    attach(mirror: MirrorFs, root: string): void;
+    detach(): void;
+    /** Copy the whole subtree across. The only bulk operation that remains. */
+    private seed;
+    /** Is this path inside the mirrored subtree? */
+    private mirrored;
+    /**
+     * Run a mirror update, swallowing failure.
+     *
+     * The mirror is a read-only cache for another engine. If it rejects
+     * something — an unsupported operation, a path it has not seen — the
+     * container's own write has still happened and must still succeed.
+     */
+    private safely;
+    /** Push a path's current state across, whatever it is now. */
+    private sync;
+    readFileSync(path: string): Uint8Array;
+    readdirSync(path: string): string[];
+    lstatSync(path: string): VolumeStat;
+    readlinkSync(path: string): string;
+    getStats(): VolumeStats;
+    writeFileSync(path: string, data: string | Uint8Array): void;
+    appendFileSync(path: string, data: string | Uint8Array): void;
+    mkdirSync(path: string, options?: {
+        mode?: number;
+    }): void;
+    rmdirSync(path: string): void;
+    unlinkSync(path: string): void;
+    renameSync(from: string, to: string): void;
+    symlinkSync(target: string, path: string): void;
+    linkSync(existing: string, path: string): void;
+    truncateSync(path: string, length?: number): void;
+    chmodSync(path: string, mode: number): void;
+    lchmodSync(path: string, mode: number): void;
+    chownSync(path: string, uid: number, gid: number): void;
+    lchownSync(path: string, uid: number, gid: number): void;
+    utimesSync(path: string, atime: Date, mtime: Date): void;
+    snapshot(): MemoryVolumeSnapshotEntry[];
+    /** A restore replaces everything, so the mirror is rebuilt rather than patched. */
+    restore(entries: MemoryVolumeSnapshotEntry[]): void;
+}
+
 interface LocalRuntimeOptions {
     workdir?: string;
     env?: Record<string, string>;
@@ -2569,10 +2718,10 @@ declare const WASM_ALIASES: Record<string, string>;
  * dedicated Worker before this becomes the default untrusted-code path.
  */
 declare class LocalRuntimePod implements RuntimePod {
-    readonly volume: MemoryVolume;
+    readonly volume: MirroringVolume;
     readonly packages: RuntimePackageInstaller;
     readonly instanceId: string;
-    private readonly router;
+    protected readonly router: VirtualHttpRouter;
     readonly proxy: {
         activePorts: (_instanceId?: string) => number[];
     };
@@ -2585,15 +2734,15 @@ declare class LocalRuntimePod implements RuntimePod {
         spawn(config: ChildSpawnConfig): ChildHandle;
     };
     private disposed;
-    private readonly workdir;
-    private readonly env;
-    private readonly aliases;
+    protected readonly workdir: string;
+    protected readonly env: Record<string, string>;
+    protected readonly aliases: Record<string, string>;
     private readonly modules;
     private readonly esbuild;
     private rolldownBinding;
     /** Backs outbound `http`/`https` client requests from inside the sandbox. */
     private readonly fetch;
-    private constructor();
+    protected constructor(options: LocalRuntimeOptions);
     static boot(options?: LocalRuntimeOptions): Promise<LocalRuntimePod>;
     spawn(command: string, args?: string[], options?: Record<string, unknown>): Promise<RuntimeProcess>;
     /**
@@ -2678,6 +2827,47 @@ declare class CleanPackageInstaller implements RuntimePackageInstaller {
 }
 declare function extractNpmTarball(volume: RuntimeVolume, compressed: Uint8Array, destination: string): void;
 
+/**
+ * Starting the guest Worker, in whichever environment the host happens to be.
+ *
+ * The awkward part of shipping a Worker from a library is not creating it, but
+ * naming it. `new URL("./worker-entry.js", import.meta.url)` is the form every
+ * bundler recognises, and it resolves correctly from `dist/` — but a bundler
+ * that *pre-bundles* this package rewrites `import.meta.url` to point into its
+ * own dependency cache, where no such file exists. That is the same trap
+ * Rolldown's WASI binding falls into, and it surfaces just as obliquely.
+ *
+ * So this never assumes it worked. The caller treats a failure to start as
+ * "this host cannot run the Worker pod" and uses the in-realm pod instead.
+ */
+interface RuntimeWorker {
+    postMessage(message: unknown): void;
+    onMessage(listener: (message: unknown) => void): void;
+    onError(listener: (error: unknown) => void): void;
+    terminate(): unknown;
+}
+/**
+ * Start the guest Worker and wait for it to say it is alive.
+ *
+ * Rejects rather than hanging when the script cannot be loaded: a Worker whose
+ * script 404s reports an `error` event and would otherwise leave the caller
+ * waiting for a ready message that can never arrive.
+ */
+declare function startRuntimeWorker(options?: {
+    url?: string | URL;
+    workerData?: Record<string, unknown>;
+    timeoutMs?: number;
+}): Promise<RuntimeWorker>;
+
+/**
+ * Can this environment support a blocking client at all?
+ *
+ * `SharedArrayBuffer` needs cross-origin isolation in a browser, and
+ * `Atomics.wait` is forbidden on a browser's main thread — which is why the
+ * client is always the Worker.
+ */
+declare function syncChannelSupported(): boolean;
+
 /**
  * sandboxedjs — a Linux-like container that runs entirely inside Node.js.
  *
@@ -2696,4 +2886,4 @@ declare function extractNpmTarball(volume: RuntimeVolume, compressed: Uint8Array
  * ```
  */
 
-export { ArithError, BufferSink, type CPythonOptions, CallbackSink, type ChildHandle, type ChildSpawnConfig, type CleanInstallerOptions, CleanPackageInstaller, type Command, CommandRegistry, CommonJsEngine, type CommonJsEngineOptions, type CommonJsModule, Container, ContainerFs, type ContainerOptions, type ContextInit, type CoreModulesOptions, type Cred, type DirEntry, ERRNO, type Env, type ErrnoCode, type EsmTransformResult, type ExecContext, type ExecOptions, type ExecResult, type FileData, FileInput, FileOutput, type GroupEntry, type HttpResponse, IncompleteInputError, type InputStream, type InstallOptions, type Job, KERNEL_NAME, KERNEL_RELEASE, Kernel, type KernelOptions, type ListeningPort, type LocalRuntimeOptions, LocalRuntimePod, MemoryVolume, type MountEntry, NODE_VERSION, NPM_VERSION, type NetInterface, type NetworkOptions, NetworkStack, NullInput, NullOutput, OS_RELEASE, type OutputStream, PYTHON_VERSION, type PasswdEntry, Pipe, Process, type ProcessKind, type ProcessOptions, type ProcessState, ProcessTable, type PythonOptions, ROOT_CRED, type ResolvedExecutable, type RootfsOptions, type RunOptions, type RunResult, type RuntimePackageInstaller, type RuntimePod, type RuntimeProcess, type RuntimeProcessManager, type RuntimeProcessResult, type RuntimeVolume, SIGNALS, SIGNAL_NAMES, Session, type SessionInit, type SessionResult, type SessionRunOptions, Shell, ShellExit, type ShellIO, type ShellInit, Lexer as ShellLexer, type ShellOptions, ShellSyntaxError, type SpawnChild, type SpawnHandle, Stats, type Stdio, SysError, TeeOutput, Terminal, type TerminalOptions, UserDatabase, Variables, Vfs, VirtualHttpRouter, VirtualHttpServer, VirtualIncomingMessage, type VirtualNode, type VirtualProvider, VirtualServerResponse, WASM_ALIASES, type WriteOptions, allCommands, applyChmod, braceExpand, buildRootfs, builtinNames, captureStdio, configureCPython, configurePython, createChildProcessModule, createContainer, createContext, createCoreModules, createContainer as default, defineCommand, evalArith, exitCodeForSignal, expandPrompt, expandWord, expandWords, extractNpmTarball, fnmatch, formatMode, getBuiltin, glob, globToRegex, hasMagic, installUserland, isBuiltinName, isCPythonAvailable, isPythonAvailable, isSysError, looksLikeEsm, makeCred, normalizeSignal, octalMode, parse as parseShell, parseUmask, path as posixPath, resetPidCounter, shellQuote, strerror, transformEsm, unameInfo };
+export { ArithError, BufferSink, type CPythonOptions, CallbackSink, type ChildHandle, type ChildSpawnConfig, type CleanInstallerOptions, CleanPackageInstaller, type Command, CommandRegistry, CommonJsEngine, type CommonJsEngineOptions, type CommonJsModule, Container, ContainerFs, type ContainerOptions, type ContextInit, type CoreModulesOptions, type Cred, type DirEntry, ERRNO, type Env, type ErrnoCode, type EsmTransformResult, type ExecContext, type ExecOptions, type ExecResult, type FileData, FileInput, FileOutput, type GroupEntry, type HttpResponse, IncompleteInputError, type InputStream, type InstallOptions, type Job, KERNEL_NAME, KERNEL_RELEASE, Kernel, type KernelOptions, type ListeningPort, type LocalRuntimeOptions, LocalRuntimePod, MemoryVolume, type MountEntry, NODE_VERSION, NPM_VERSION, type NetInterface, type NetworkOptions, NetworkStack, NullInput, NullOutput, OS_RELEASE, type OutputStream, PYTHON_VERSION, type PasswdEntry, Pipe, Process, type ProcessKind, type ProcessOptions, type ProcessState, ProcessTable, type PythonOptions, ROOT_CRED, type ResolvedExecutable, type RootfsOptions, type RunOptions, type RunResult, type RuntimePackageInstaller, type RuntimePod, type RuntimeProcess, type RuntimeProcessManager, type RuntimeProcessResult, type RuntimeVolume, SIGNALS, SIGNAL_NAMES, Session, type SessionInit, type SessionResult, type SessionRunOptions, Shell, ShellExit, type ShellIO, type ShellInit, Lexer as ShellLexer, type ShellOptions, ShellSyntaxError, type SpawnChild, type SpawnHandle, Stats, type Stdio, SysError, TeeOutput, Terminal, type TerminalOptions, UserDatabase, Variables, Vfs, VirtualHttpRouter, VirtualHttpServer, VirtualIncomingMessage, type VirtualNode, type VirtualProvider, VirtualServerResponse, WASM_ALIASES, type WriteOptions, allCommands, applyChmod, braceExpand, buildRootfs, builtinNames, captureStdio, configureCPython, configurePython, createChildProcessModule, createContainer, createContext, createCoreModules, createContainer as default, defineCommand, evalArith, exitCodeForSignal, expandPrompt, expandWord, expandWords, extractNpmTarball, fnmatch, formatMode, getBuiltin, glob, globToRegex, hasMagic, installUserland, isBuiltinName, isCPythonAvailable, isPythonAvailable, isSysError, looksLikeEsm, makeCred, normalizeSignal, octalMode, parse as parseShell, parseUmask, path as posixPath, resetPidCounter, shellQuote, startRuntimeWorker, strerror, syncChannelSupported, transformEsm, unameInfo };