sandboxedjs 0.1.22 → 0.1.24

package/dist/index.d.cts

@@ -1,4 +1,120 @@
-import { MemoryVolume, Nodepod } from '@scelar/nodepod';
+import EventEmitter from 'events';
+import streamModule from 'stream-browserify';
+
+/** The handle a pod's process manager returns. */
+interface ChildHandle {
+    pid: number;
+    state: "starting" | "running" | "exited";
+    exitCode: number | undefined;
+    on(event: "stdout" | "stderr" | "exit", listener: (...args: any[]) => void): unknown;
+    exec(): void;
+    sendStdin(data: string): void;
+    kill(signal?: string): void;
+}
+interface ChildSpawnConfig {
+    command: string;
+    args?: string[];
+    cwd?: string;
+    env?: Record<string, string>;
+    parentPid?: number;
+}
+type SpawnChild = (config: ChildSpawnConfig) => ChildHandle;
+declare function createChildProcessModule(spawnChild: SpawnChild, defaultCwd: () => string): Record<string, unknown>;
+
+/**
+ * Clean-room contracts between SandboxedJS and its JavaScript runtime.
+ *
+ * These deliberately describe only behavior SandboxedJS consumes. Runtime
+ * implementations may use Web Workers in browsers or worker_threads on Node.
+ */
+
+interface VolumeStats {
+    totalBytes: number;
+    fileCount: number;
+    /** New runtime spelling. */
+    directoryCount?: number;
+    /** Compatibility spelling used by existing volume implementations. */
+    dirCount?: number;
+}
+interface VolumeStat {
+    mode: number;
+    size: number;
+    uid: number;
+    gid: number;
+    ino: number;
+    nlink: number;
+    atimeMs: number;
+    mtimeMs: number;
+    ctimeMs: number;
+    birthtimeMs: number;
+    isFile(): boolean;
+    isDirectory(): boolean;
+    isSymbolicLink(): boolean;
+}
+interface RuntimeVolume {
+    readFileSync(path: string): Uint8Array;
+    writeFileSync(path: string, data: string | Uint8Array): void;
+    appendFileSync(path: string, data: string | Uint8Array): void;
+    readdirSync(path: string): string[];
+    lstatSync(path: string): VolumeStat;
+    readlinkSync(path: string): string;
+    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;
+    getStats(): VolumeStats;
+}
+interface RuntimeProcessResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}
+interface RuntimeProcess {
+    readonly completion: Promise<RuntimeProcessResult>;
+    on(event: "output" | "error" | "exit", listener: (...args: any[]) => void): this;
+    write(data: string): void;
+    kill(signal?: string): void;
+}
+interface RuntimeHttpResponse {
+    statusCode?: number;
+    statusMessage?: string;
+    headers?: Record<string, string>;
+    body?: string | Uint8Array | ArrayBuffer;
+}
+interface RuntimePackageInstaller {
+    install(name: string, version?: string, options?: Record<string, unknown>): Promise<unknown>;
+    installFromManifest(path: string, options?: Record<string, unknown>): Promise<unknown>;
+    /** Create a view that installs into another project root. */
+    forCwd?(cwd: string): RuntimePackageInstaller;
+}
+/** The process-manager protocol a container's kernel bridge substitutes for. */
+interface RuntimeProcessManager {
+    spawn(config: ChildSpawnConfig): ChildHandle;
+}
+interface RuntimePod {
+    readonly volume: RuntimeVolume;
+    readonly packages: RuntimePackageInstaller;
+    readonly instanceId: string;
+    readonly processManager: RuntimeProcessManager;
+    readonly proxy: {
+        activePorts(instanceId?: string): number[];
+    };
+    spawn(command: string, args?: string[], options?: Record<string, unknown>): Promise<RuntimeProcess>;
+    request(port: number, init?: Record<string, unknown>): Promise<RuntimeHttpResponse>;
+    snapshot(options?: Record<string, unknown>): unknown;
+    restore(snapshot: unknown, options?: Record<string, unknown>): Promise<void>;
+    teardown(): void;
+}
 
 type FileKind = "file" | "directory" | "symlink" | "chardev" | "blockdev" | "fifo" | "socket";
 /** Render as `drwxr-xr-x`, honouring setuid/setgid/sticky. */
@@ -138,11 +254,11 @@ interface ResolveOptions {
     followFinal?: boolean;
 }
 declare class Vfs {
-    readonly volume: MemoryVolume;
+    readonly volume: RuntimeVolume;
     private readonly providers;
     private nextVirtualIno;
     private readonly virtualInos;
-    constructor(volume: MemoryVolume);
+    constructor(volume: RuntimeVolume);
     addProvider(provider: VirtualProvider): void;
     removeProvider(root: string): void;
     /** The mount points currently served synthetically. */
@@ -665,7 +781,7 @@ declare class NetworkStack {
     private readonly ifaces;
     private readonly listeners;
     readonly options: Required<Pick<NetworkOptions, "allowOutbound">> & NetworkOptions;
-    constructor(pod: Nodepod, vfs: Vfs, options?: NetworkOptions);
+    constructor(pod: RuntimePod, vfs: Vfs, options?: NetworkOptions);
     interfaces(): NetInterface[];
     interface(name: string): NetInterface | undefined;
     setInterfaceUp(name: string, up: boolean): boolean;
@@ -705,7 +821,7 @@ declare class NetworkStack {
  */
 
 interface KernelOptions {
-    pod: Nodepod;
+    pod: RuntimePod;
     hostname?: string;
     /** Login user for interactive sessions. Defaults to `root`. */
     user?: string;
@@ -760,7 +876,7 @@ declare class Kernel {
     readonly procs: ProcessTable;
     readonly commands: CommandRegistry;
     readonly users: UserDatabase;
-    readonly pod: Nodepod;
+    readonly pod: RuntimePod;
     readonly bootTime: number;
     readonly memoryBytes: number;
     readonly cpus: number;
@@ -1489,33 +1605,21 @@ interface ContainerOptions {
     /** Invoked when an in-container HTTP server starts listening. */
     onServerReady?: (port: number, url: string) => void;
     /**
-     * Supply the Nodepod instance instead of letting the container boot one.
+     * Run on a JavaScript runtime you booted yourself.
      *
-     * The default path imports `@scelar/nodepod/headless`, which installs a
-     * `worker_threads` host and is the right choice on Node. In a browser you
-     * boot Nodepod's browser build yourself (it needs a service worker) and hand
-     * the instance over:
+     * The container boots a {@link LocalRuntimePod} when this is omitted, which
+     * is what almost every caller wants. Pass one to share a single runtime
+     * across containers, to seed it differently, or to substitute an
+     * implementation of your own — anything satisfying {@link RuntimePod} works.
      *
      * ```ts
-     * import { Nodepod } from "@scelar/nodepod";
-     * const pod = await Nodepod.boot({ ... });
-     * const box = await createContainer({ pod });
+     * const pod = await LocalRuntimePod.boot({ workdir: "/app" });
+     * const box = await createContainer({ pod, cwd: "/app" });
      * ```
      */
-    pod?: Nodepod;
+    pod?: RuntimePod;
     /** Python runtime settings; a browser host uses this to locate the wasm. */
     python?: PythonOptions;
-    /**
-     * Forwarded to Nodepod when this package boots it in a browser. `swUrl`
-     * points at the service worker if you serve it somewhere other than
-     * `/__sw__.js`; `serviceWorker: false` skips registration entirely, which
-     * also disables preview iframes.
-     */
-    browser?: {
-        swUrl?: string;
-        serviceWorker?: boolean;
-        watermark?: boolean;
-    };
 }
 interface ExecOptions {
     cwd?: string;
@@ -1561,7 +1665,7 @@ interface HttpResponse {
 }
 declare class Container {
     readonly kernel: Kernel;
-    readonly pod: Nodepod;
+    readonly pod: RuntimePod;
     readonly fs: ContainerFs;
     readonly net: NetworkStack;
     private readonly defaults;
@@ -1739,13 +1843,13 @@ declare function exitCodeForSignal(sig: string): number;
 /**
  * The identity the container reports for itself.
  *
- * The release string deliberately matches what Nodepod's `os.release()` returns
- * inside a spawned Node process, so `uname -r` and
- * `node -p "os.release()"` agree.
+ * The runtime's `os.release()` is built from these same constants, so `uname -r`
+ * and `node -p "os.release()"` agree inside the container — a program that
+ * checks the platform gets one answer whichever way it asks.
  */
 declare const KERNEL_NAME = "Linux";
 declare const KERNEL_RELEASE = "5.10.0";
-declare const OS_RELEASE = "PRETTY_NAME=\"SandboxedJS 1.0 (nodepod)\"\nNAME=\"SandboxedJS\"\nVERSION_ID=\"1.0\"\nVERSION=\"1.0 (nodepod)\"\nVERSION_CODENAME=nodepod\nID=sandboxedjs\nID_LIKE=debian\nHOME_URL=\"https://github.com/R1ck404/Nodepod\"\nSUPPORT_URL=\"https://www.npmjs.com/package/sandboxedjs\"\n";
+declare const OS_RELEASE = "PRETTY_NAME=\"SandboxedJS 1.0 (sandbox)\"\nNAME=\"SandboxedJS\"\nVERSION_ID=\"1.0\"\nVERSION=\"1.0 (sandbox)\"\nVERSION_CODENAME=sandbox\nID=sandboxedjs\nID_LIKE=debian\nHOME_URL=\"https://www.npmjs.com/package/sandboxedjs\"\nSUPPORT_URL=\"https://www.npmjs.com/package/sandboxedjs\"\n";
 interface UnameInfo {
     sysname: string;
     nodename: string;
@@ -2016,12 +2120,486 @@ declare function buildRootfs(vfs: Vfs, opts?: RootfsOptions): void;
 declare const NODE_VERSION = "v22.12.0";
 
 /**
- * Package managers: `npm`/`npx`/`yarn`/`pnpm` on top of Nodepod's installer,
- * and an `apt`-shaped front end for the things a container image would ship.
+ * Package managers: `npm`/`npx`/`yarn`/`pnpm` on top of the runtime's package
+ * installer, and an `apt`-shaped front end for the things a container image
+ * would ship.
  */
 
 declare const NPM_VERSION = "10.9.0";
 
+type NodeKind = "file" | "directory" | "symlink";
+interface MemoryVolumeSnapshotEntry {
+    path: string;
+    ino: number;
+    kind: NodeKind;
+    mode: number;
+    uid: number;
+    gid: number;
+    nlink: number;
+    data: number[];
+    target: string;
+    atimeMs: number;
+    mtimeMs: number;
+    ctimeMs: number;
+    birthtimeMs: number;
+}
+/** Browser-safe, synchronous in-memory filesystem used by the new runtime. */
+declare class MemoryVolume implements RuntimeVolume {
+    private readonly entries;
+    private nextIno;
+    constructor();
+    readFileSync(path: string): Uint8Array;
+    writeFileSync(path: string, data: string | Uint8Array): void;
+    appendFileSync(path: string, data: string | Uint8Array): void;
+    readdirSync(path: string): string[];
+    lstatSync(path: string): VolumeStat;
+    readlinkSync(path: string): string;
+    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;
+    getStats(): VolumeStats;
+    snapshot(): MemoryVolumeSnapshotEntry[];
+    restore(snapshot: MemoryVolumeSnapshotEntry[]): void;
+    /** Serializable representation used by RuntimePod snapshots. */
+    export(): Array<{
+        path: string;
+        kind: NodeKind;
+        mode: number;
+        uid: number;
+        gid: number;
+        data?: number[];
+        target?: string;
+    }>;
+    private setMode;
+    private setOwner;
+    private key;
+    private required;
+    private requireParent;
+    private inode;
+    private touchChanged;
+}
+
+/**
+ * How a specifier was requested. Node resolves the same package differently
+ * for the two, and a dual package depends on that: `is-promise` exports a
+ * callable function under "require" and a namespace under "import", so
+ * `require("is-promise")` served the ESM build is not merely suboptimal, it is
+ * a `TypeError` at the first call site.
+ */
+type RequestKind = "import" | "require";
+interface CommonJsModule {
+    id: string;
+    filename: string;
+    exports: any;
+    loaded: boolean;
+    parent: CommonJsModule | null;
+    children: CommonJsModule[];
+    /**
+     * Set for an ES module whose body contains a top-level `await`: the promise
+     * for its completion. A synchronous `require` of such a module cannot
+     * succeed, and this is what lets the engine say so precisely.
+     */
+    pending?: Promise<void>;
+}
+interface CommonJsEngineOptions {
+    volume: RuntimeVolume;
+    cwd?: string;
+    builtins?: Record<string, unknown>;
+    globals?: Record<string, unknown>;
+    /**
+     * Package-name substitutions, applied to bare specifiers before resolution.
+     *
+     * Several cornerstone build tools ship a compiled addon on the platforms
+     * they support and a WebAssembly build for everywhere else — `rollup` and
+     * `@rollup/wasm-node`, `esbuild` and `esbuild-wasm`. This runtime is always
+     * the "everywhere else" case, but the packages select their binding by
+     * reading `process.platform`, which reports a platform whose addon exists
+     * and cannot be loaded. Redirecting the name is how the WebAssembly build
+     * gets chosen instead.
+     *
+     * A substitution that is not installed falls back to the original name, so
+     * an alias is a preference rather than a requirement.
+     */
+    aliases?: Record<string, string>;
+    /**
+     * Modules supplied by the runtime instead of resolved from the filesystem.
+     *
+     * The case this exists for is a toolchain component that cannot execute
+     * inside the sandbox at all. `esbuild` is the example: every build of it
+     * either dlopens a compiled addon or drives a Go/WebAssembly process through
+     * facilities the runtime does not have, so the copy installed in
+     * `node_modules` is unusable no matter which one is chosen. Handing over a
+     * working implementation is what lets the tools built on it run.
+     *
+     * These take precedence over an installed package of the same name but not
+     * over a Node built-in, so an override can never shadow `fs`.
+     */
+    overrides?: Record<string, unknown>;
+}
+/**
+ * CommonJS loader for a runtime worker. The worker is the security boundary;
+ * this class intentionally has no dependency on Node's module implementation.
+ */
+declare class CommonJsEngine {
+    readonly volume: RuntimeVolume;
+    readonly cache: Map<string, CommonJsModule>;
+    readonly builtins: Record<string, unknown>;
+    readonly globals: Record<string, unknown>;
+    readonly aliases: Record<string, string>;
+    readonly overrides: Record<string, unknown>;
+    cwd: string;
+    main: CommonJsModule | null;
+    /** `package.json` per directory; resolution reads them constantly. */
+    private readonly manifests;
+    constructor(volume: RuntimeVolume, options?: Omit<CommonJsEngineOptions, "volume">);
+    /**
+     * Evaluate an entry point.
+     *
+     * Returns the module's exports, or a promise for them when the entry is an
+     * ES module with a top-level `await` — the caller has to await that before
+     * treating the program as finished.
+     */
+    run(entry: string): unknown | Promise<unknown>;
+    require(specifier: string, importer?: string): unknown;
+    resolve(specifier: string, importer: string, kind?: RequestKind): string;
+    private load;
+    private evaluate;
+    /** The `require` a module sees, complete with `resolve`, `cache` and `main`. */
+    private makeRequire;
+    /**
+     * Load `specifier` and present it as an ES module namespace.
+     *
+     * A static `import` is synchronous here, exactly as the CommonJS `require`
+     * it compiles down to. That is the one place this engine knowingly differs
+     * from Node's real ESM semantics, and it is the trade that lets both module
+     * systems share a single cache and resolver.
+     */
+    private importNamespace;
+    /** `import(...)`: the same load, but able to await a top-level `await`. */
+    private dynamicImport;
+    /** `import.meta` for a module. */
+    private importMeta;
+    /**
+     * The substituted specifier for `specifier`, or null when none applies.
+     *
+     * An alias names a package, so a subpath rides along: aliasing `rollup` also
+     * redirects `rollup/dist/native.js` into the substitute.
+     */
+    private aliasFor;
+    /**
+     * Resolve a bare specifier (`pkg`, `@scope/pkg`, `pkg/sub`) by walking
+     * `node_modules` up from the importer, exactly as Node does.
+     */
+    private resolvePackage;
+    /**
+     * Resolve `subpath` ("" for the package root) inside an installed package.
+     *
+     * An `exports` map, when present, is authoritative: Node refuses paths it
+     * does not name, and packages rely on that to keep their internals private.
+     * Only a package without one falls back to `main`/`module` and to treating
+     * the subpath as a plain file path.
+     */
+    private resolveInPackage;
+    /**
+     * Resolve a `#private` specifier through the importing package's `imports`
+     * map, which is scoped to the nearest enclosing package rather than to
+     * `node_modules`.
+     */
+    private resolveImports;
+    /** Resolve a path to a file, trying Node's extension and index fallbacks. */
+    private resolvePath;
+    private resolveIndex;
+    /** The nearest ancestor directory holding a `package.json`. */
+    private packageRoot;
+    private readManifest;
+    private builtin;
+    private exists;
+    private isFile;
+    private isDirectory;
+    private readText;
+    private moduleNotFound;
+}
+
+interface VirtualRequestInit {
+    method?: string;
+    path?: string;
+    headers?: Record<string, string>;
+    body?: string | Uint8Array | ArrayBuffer | null;
+}
+declare class VirtualIncomingMessage extends streamModule.Readable {
+    readonly method: string;
+    readonly url: string;
+    readonly headers: Record<string, string>;
+    readonly rawHeaders: string[];
+    readonly httpVersion = "1.1";
+    readonly httpVersionMajor = 1;
+    readonly httpVersionMinor = 1;
+    readonly complete = true;
+    readonly socket: Record<string, unknown>;
+    readonly connection: Record<string, unknown>;
+    constructor(init: VirtualRequestInit);
+    _read(): void;
+    setTimeout(_milliseconds: number, callback?: () => void): this;
+}
+declare class VirtualServerResponse extends streamModule.Writable {
+    statusCode: number;
+    statusMessage: string;
+    headersSent: boolean;
+    sendDate: boolean;
+    readonly req: VirtualIncomingMessage;
+    readonly socket: Record<string, unknown>;
+    readonly connection: Record<string, unknown>;
+    private readonly headers;
+    private readonly chunks;
+    private resolve;
+    readonly completed: Promise<RuntimeHttpResponse>;
+    constructor(request: VirtualIncomingMessage);
+    _write(chunk: any, encoding: BufferEncoding, callback: (error?: Error | null) => void): void;
+    _final(callback: (error?: Error | null) => void): void;
+    setHeader(name: string, value: string | number | readonly string[]): this;
+    appendHeader(name: string, value: string | readonly string[]): this;
+    getHeader(name: string): string | string[] | undefined;
+    getHeaders(): Record<string, string | string[]>;
+    getHeaderNames(): string[];
+    hasHeader(name: string): boolean;
+    removeHeader(name: string): void;
+    writeHead(statusCode: number, statusMessage?: string | Record<string, unknown>, headers?: Record<string, unknown>): this;
+    flushHeaders(): void;
+    writeContinue(): void;
+    writeProcessing(): void;
+    addTrailers(_headers: Record<string, string>): void;
+    setTimeout(_milliseconds: number, callback?: () => void): this;
+}
+declare class VirtualHttpServer extends EventEmitter {
+    private readonly router;
+    readonly owner: string;
+    listening: boolean;
+    private portValue;
+    constructor(router: VirtualHttpRouter, owner: string, listener?: (req: VirtualIncomingMessage, res: VirtualServerResponse) => void);
+    listen(...args: any[]): this;
+    close(callback?: (error?: Error) => void): this;
+    address(): {
+        address: string;
+        family: string;
+        port: number;
+    } | null;
+    ref(): this;
+    unref(): this;
+    setTimeout(_milliseconds: number, callback?: () => void): this;
+}
+declare class VirtualHttpRouter {
+    private readonly servers;
+    /** Notified when a server begins listening, for `onServerReady`. */
+    onListen: ((port: number) => void) | undefined;
+    register(port: number, server: VirtualHttpServer, owner: string): void;
+    unregister(port: number, server: VirtualHttpServer): void;
+    activePorts(owner?: string): number[];
+    closeOwner(owner: string): void;
+    closeAll(): void;
+    request(port: number, init?: VirtualRequestInit): Promise<RuntimeHttpResponse>;
+}
+
+interface CoreModulesOptions {
+    volume: RuntimeVolume;
+    cwd?: string;
+    env?: Record<string, string>;
+    argv?: string[];
+    stdout?: (chunk: string) => void;
+    stderr?: (chunk: string) => void;
+    onExit?: (code: number) => void;
+    http?: {
+        router: VirtualHttpRouter;
+        owner: string;
+    };
+    /** Backs `child_process`; without it the module reports as unavailable. */
+    spawnChild?: SpawnChild;
+    /** File holding the process's standard input, exposed as descriptor 0. */
+    stdinPath?: string;
+}
+/** Build the core-module table injected into each isolated JS worker. */
+declare function createCoreModules(options: CoreModulesOptions): {
+    builtins: Record<string, unknown>;
+    globals: Record<string, unknown>;
+    process: Record<string, any>;
+    /**
+     * How many timers this process still has outstanding.
+     *
+     * Node keeps a process alive while its event loop has work, and exits when
+     * it does not. Tracking the timers a program schedules is what lets this
+     * runtime make the same decision — without it a server that binds its port
+     * one turn after its entry module settles looks indistinguishable from a
+     * script that has simply finished.
+     */
+    pendingHandles(): number;
+};
+
+interface EsmTransformResult {
+    /** The rewritten source. */
+    code: string;
+    /**
+     * True when the file is an ES module, and so must be evaluated in a wrapper
+     * that does not inject `require`, `module`, `__filename` or `__dirname`.
+     *
+     * False for a CommonJS file that was rewritten only because it contains a
+     * dynamic `import(...)`, which is legal there and still has to be routed
+     * through the engine rather than to the host realm.
+     */
+    esm: boolean;
+    /** True when the module body contains a top-level `await`. */
+    topLevelAwait: boolean;
+}
+declare function looksLikeEsm(source: string): boolean;
+/**
+ * Rewrite `source` from ESM to the engine's CommonJS wrapper shape, or return
+ * `null` when it is not an ES module and should be evaluated as-is.
+ *
+ * `null` is also returned when the source does not parse as a module: that is
+ * not this function's error to raise. Letting it through means the engine
+ * evaluates the original text and the runtime reports the real syntax error at
+ * the real position.
+ */
+declare function transformEsm(source: string, filename?: string): EsmTransformResult | null;
+
+interface LocalRuntimeOptions {
+    workdir?: string;
+    env?: Record<string, string>;
+    files?: Record<string, string | Uint8Array>;
+    registry?: string;
+    fetch?: typeof globalThis.fetch;
+    /** Invoked when a program inside the runtime starts listening on a port. */
+    onServerReady?: (port: number, url: string) => void;
+    /** Extra package substitutions, merged over {@link WASM_ALIASES}. */
+    aliases?: Record<string, string>;
+    /** Modules supplied by the host rather than resolved from the volume. */
+    modules?: Record<string, unknown>;
+    /**
+     * Supply `esbuild` from the host when it can be loaded. On by default: no
+     * build of esbuild runs inside the sandbox, so without this every toolchain
+     * that depends on it — Vite included — starts and then fails on the first
+     * transform.
+     */
+    hostEsbuild?: boolean;
+}
+/**
+ * Default substitutions for packages that would otherwise load a compiled
+ * addon.
+ *
+ * Each of these ships a WebAssembly build under a second package name for
+ * exactly this situation — a host with no prebuilt binary for its platform.
+ * The substitute is only used when it is actually installed, so a project that
+ * has neither is unaffected and one that has both gets the runnable one.
+ */
+declare const WASM_ALIASES: Record<string, string>;
+/**
+ * First complete clean-room RuntimePod composition. Execution currently uses
+ * the caller's JS realm; BrowserRuntimePod will place the same engine in a
+ * dedicated Worker before this becomes the default untrusted-code path.
+ */
+declare class LocalRuntimePod implements RuntimePod {
+    readonly volume: MemoryVolume;
+    readonly packages: RuntimePackageInstaller;
+    readonly instanceId: string;
+    private readonly router;
+    readonly proxy: {
+        activePorts: (_instanceId?: string) => number[];
+    };
+    /**
+     * Mutable on purpose: a container replaces `spawn` so that children resolve
+     * against the kernel's PATH. Left alone, it runs `node` and reports anything
+     * else as not found, which is the correct answer for a bare pod.
+     */
+    readonly processManager: {
+        spawn(config: ChildSpawnConfig): ChildHandle;
+    };
+    private disposed;
+    private readonly workdir;
+    private readonly env;
+    private readonly aliases;
+    private readonly modules;
+    private constructor();
+    static boot(options?: LocalRuntimeOptions): Promise<LocalRuntimePod>;
+    spawn(command: string, args?: string[], options?: Record<string, unknown>): Promise<RuntimeProcess>;
+    /**
+     * Wait until the process has either started serving or genuinely run out of
+     * work.
+     *
+     * Two different kinds of pending work have to be waited on. Callbacks queued
+     * as microtasks or `nextTick` — which is most of what streams and promise
+     * chains are built from — need only for the current turn to end, so a few
+     * turns of the macrotask queue are yielded first. Without that, a script
+     * whose last act is `process.stdin.on("data", …)` exits before its own
+     * handler runs and produces no output at all. Timers are the part that can
+     * outlive any number of turns, so those are then polled until none remain.
+     *
+     * A plain script that has genuinely finished falls straight through both,
+     * costing a handful of empty turns.
+     */
+    private settle;
+    request(_port: number, _init?: Record<string, unknown>): Promise<RuntimeHttpResponse>;
+    snapshot(): MemoryVolumeSnapshotEntry[];
+    restore(snapshot: unknown): Promise<void>;
+    teardown(): void;
+    private seed;
+    private assertActive;
+}
+
+interface RegistryManifest {
+    name: string;
+    version: string;
+    dist: {
+        tarball: string;
+        integrity?: string;
+        shasum?: string;
+    };
+    dependencies?: Record<string, string>;
+    optionalDependencies?: Record<string, string>;
+    bin?: string | Record<string, string>;
+}
+interface CleanInstallerOptions {
+    cwd?: string;
+    registry?: string;
+    fetch?: typeof globalThis.fetch;
+}
+interface InstallOptions extends Record<string, unknown> {
+    onProgress?: (message: string) => void;
+    persist?: boolean;
+    persistDev?: boolean;
+    withDevDeps?: boolean;
+}
+/** npm-registry installer independent of npm CLI and Node host APIs. */
+declare class CleanPackageInstaller implements RuntimePackageInstaller {
+    readonly volume: RuntimeVolume;
+    readonly options: CleanInstallerOptions;
+    private readonly registry;
+    private readonly fetcher;
+    private readonly metadata;
+    private readonly tarballs;
+    constructor(volume: RuntimeVolume, options?: CleanInstallerOptions);
+    forCwd(cwd: string): CleanPackageInstaller;
+    install(name: string, version?: string, options?: InstallOptions): Promise<RegistryManifest>;
+    installFromManifest(path: string, options?: InstallOptions): Promise<void>;
+    private installAt;
+    private getMetadata;
+    private getTarball;
+    private createBinLinks;
+    private persist;
+    private removeIfPresent;
+    private readJson;
+    private tryReadJson;
+}
+declare function extractNpmTarball(volume: RuntimeVolume, compressed: Uint8Array, destination: string): void;
+
 /**
  * sandboxedjs — a Linux-like container that runs entirely inside Node.js.
  *
@@ -2040,4 +2618,4 @@ declare const NPM_VERSION = "10.9.0";
  * ```
  */
 
-export { ArithError, BufferSink, type CPythonOptions, CallbackSink, type Command, CommandRegistry, Container, ContainerFs, type ContainerOptions, type ContextInit, type Cred, type DirEntry, ERRNO, type Env, type ErrnoCode, type ExecContext, type ExecOptions, type ExecResult, type FileData, FileInput, FileOutput, type GroupEntry, type HttpResponse, IncompleteInputError, type InputStream, type Job, KERNEL_NAME, KERNEL_RELEASE, Kernel, type KernelOptions, type ListeningPort, 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, SIGNALS, SIGNAL_NAMES, Session, type SessionInit, type SessionResult, type SessionRunOptions, Shell, ShellExit, type ShellIO, type ShellInit, Lexer as ShellLexer, type ShellOptions, ShellSyntaxError, type SpawnHandle, Stats, type Stdio, SysError, TeeOutput, Terminal, type TerminalOptions, UserDatabase, Variables, Vfs, type VirtualNode, type VirtualProvider, type WriteOptions, allCommands, applyChmod, braceExpand, buildRootfs, builtinNames, captureStdio, configureCPython, configurePython, createContainer, createContext, createContainer as default, defineCommand, evalArith, exitCodeForSignal, expandPrompt, expandWord, expandWords, fnmatch, formatMode, getBuiltin, glob, globToRegex, hasMagic, installUserland, isBuiltinName, isCPythonAvailable, isPythonAvailable, isSysError, makeCred, normalizeSignal, octalMode, parse as parseShell, parseUmask, path as posixPath, resetPidCounter, shellQuote, strerror, 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, strerror, transformEsm, unameInfo };