sandboxedjs 0.1.29 → 0.1.31

package/dist/index.d.cts

@@ -6,7 +6,7 @@ interface ChildHandle {
     pid: number;
     state: "starting" | "running" | "exited";
     exitCode: number | undefined;
-    on(event: "stdout" | "stderr" | "exit", listener: (...args: any[]) => void): unknown;
+    on(event: "stdout" | "stderr" | "exit" | "rawmode", listener: (...args: any[]) => void): unknown;
     exec(): void;
     sendStdin(data: string): void;
     /**
@@ -25,6 +25,14 @@ interface ChildSpawnConfig {
     cwd?: string;
     env?: Record<string, string>;
     parentPid?: number;
+    /**
+     * The child was given the parent's streams (`stdio: "inherit"`).
+     *
+     * Its input is then the parent's terminal rather than a pipe that will end,
+     * which is the difference between a program that waits for what the user
+     * types and one that reads to end-of-input and stops.
+     */
+    inheritStdio?: boolean;
 }
 type SpawnChild = (config: ChildSpawnConfig) => ChildHandle;
 /**
@@ -40,6 +48,7 @@ type SyncSpawn = (request: {
     cwd: string;
     env?: Record<string, string>;
     input?: string;
+    inheritStdio?: boolean;
 }) => {
     status: number | null;
     stdout: string;
@@ -50,7 +59,7 @@ type SyncSpawn = (request: {
         message: string;
     };
 };
-declare function createChildProcessModule(spawnChild: SpawnChild, defaultCwd: () => string, syncSpawn?: SyncSpawn): Record<string, unknown>;
+declare function createChildProcessModule(spawnChild: SpawnChild, defaultCwd: () => string, syncSpawn?: SyncSpawn, defaultEnv?: () => Record<string, string>): Record<string, unknown>;
 
 /**
  * Clean-room contracts between SandboxedJS and its JavaScript runtime.
@@ -433,7 +442,10 @@ declare class Pipe implements InputStream, OutputStream {
      * whole line on every keystroke — so the terminal must stop echoing, or
      * every character appears twice.
      */
-    rawMode: boolean;
+    private raw;
+    onRawMode?: (enabled: boolean) => void;
+    get rawMode(): boolean;
+    set rawMode(enabled: boolean);
     columns: number | undefined;
     rows: number | undefined;
     get closed(): boolean;
@@ -1382,6 +1394,8 @@ declare class Shell {
     constructor(init: ShellInit);
     /** Parse and run a script fragment. Returns the last exit status. */
     execute(source: string, io: ShellIO): Promise<number>;
+    /** Signal the current terminal pipeline without terminating the interactive shell. */
+    interruptForeground(signal: string, stdin: InputStream): void;
     get isExiting(): boolean;
     /** True when `source` is not yet a complete command (for REPL continuation). */
     static isIncomplete(source: string): boolean;
@@ -1665,12 +1679,15 @@ interface ContainerOptions {
     /**
      * 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.
+     * `"auto"` (the default) tries the worker runtime and reports any fallback.
+     * `"worker"` requires a working guest worker and shared-memory channel: boot
+     * rejects with the cause if either is unavailable, rather than letting
+     * synchronous child-process calls fail later. `"realm"` opts out explicitly.
+     * Processes requiring host-native modules can still run in the host realm.
      */
-    isolation?: "worker" | "realm";
+    isolation?: "auto" | "worker" | "realm";
+    /** Receives the reason for an automatic fallback; defaults to console.warn. */
+    onRuntimeFallback?: (error: Error) => void;
     /**
      * Where to load the guest worker bundle from.
      *
@@ -2457,6 +2474,7 @@ declare class VirtualHttpServer extends EventEmitter {
     readonly owner: string;
     listening: boolean;
     private portValue;
+    private referenced;
     constructor(router: VirtualHttpRouter, owner: string, listener?: (req: VirtualIncomingMessage, res: VirtualServerResponse) => void);
     listen(...args: any[]): this;
     close(callback?: (error?: Error) => void): this;
@@ -2467,17 +2485,20 @@ declare class VirtualHttpServer extends EventEmitter {
     } | null;
     ref(): this;
     unref(): this;
+    hasRef(): boolean;
     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;
+    onClose: ((port: number) => void) | undefined;
     register(port: number, server: VirtualHttpServer, owner: string): void;
     unregister(port: number, server: VirtualHttpServer): void;
     /** Whether anything in this container is listening on `port`. */
     activePortsIncludes(port: number): boolean;
     activePorts(owner?: string): number[];
+    referencedPorts(owner: string): number[];
     closeOwner(owner: string): void;
     closeAll(): void;
     request(port: number, init?: VirtualRequestInit): Promise<RuntimeHttpResponse>;
@@ -2734,6 +2755,7 @@ declare class LocalRuntimePod implements RuntimePod {
         spawn(config: ChildSpawnConfig): ChildHandle;
     };
     private disposed;
+    private readonly running;
     protected readonly workdir: string;
     protected readonly env: Record<string, string>;
     protected readonly aliases: Record<string, string>;
@@ -2777,6 +2799,62 @@ declare class LocalRuntimePod implements RuntimePod {
     private assertActive;
 }
 
+/**
+ * A pod that evaluates each guest program on its own thread.
+ *
+ * Everything shared stays here: the volume, the HTTP router, the package
+ * installer and the process table. Only the program's own evaluation moves,
+ * and it reaches back for the rest through a {@link SyncChannelServer}.
+ *
+ * That arrangement is forced rather than chosen. A synchronous call has to
+ * block the caller while the work it is waiting on still makes progress, so
+ * the blocking side cannot be the side that owns the resources — otherwise a
+ * child process needing the filesystem would have to call into a thread that
+ * is frozen waiting for that child. The guest blocks; the host never does.
+ *
+ * It inherits from {@link LocalRuntimePod} because every other part of the
+ * contract is identical, and overriding one method is a smaller and more
+ * honest claim than reimplementing nine. Both are held to the same contract
+ * suite (`test/pod-contract.ts`).
+ */
+
+interface WorkerRuntimeOptions extends LocalRuntimeOptions {
+    /** Where the guest bundle lives; defaults to the copy shipped beside this one. */
+    workerUrl?: string | URL;
+}
+declare class WorkerRuntimePod extends LocalRuntimePod {
+    private readonly workerUrl;
+    /** Live workers, so teardown can stop them all. */
+    private readonly live;
+    protected constructor(options: WorkerRuntimeOptions);
+    /** Boot without silently dropping synchronous child-process support. */
+    static boot(options?: WorkerRuntimeOptions): Promise<WorkerRuntimePod>;
+    /** Compatibility mode, with an observable explanation for every fallback. */
+    static tryBoot(options?: WorkerRuntimeOptions, onFallback?: (error: Error) => void): Promise<WorkerRuntimePod | null>;
+    spawn(command: string, args?: string[], options?: Record<string, unknown>): Promise<RuntimeProcess>;
+    private spawnInWorker;
+    /** Start an asynchronous child on the host's behalf and relay its events. */
+    private startChild;
+    /** Run a child to completion and collect it, for the guest's `spawnSync`. */
+    private runChildToCompletion;
+    private readonly proxies;
+    private readonly waiting;
+    private nextRequestId;
+    /**
+     * Register a stand-in for a server that is actually running in the Worker.
+     *
+     * The router only knows how to reach servers on this thread, so each bound
+     * port gets a local server whose whole job is to forward and wait.
+     */
+    private proxyPort;
+    private forward;
+    private settleProxied;
+    private closeProxies;
+    teardown(): void;
+    /** Does anything under `cwd` need a module only the host can supply? */
+    private needsHostModules;
+}
+
 interface RegistryManifest {
     name: string;
     version: string;
@@ -2837,8 +2915,8 @@ declare function extractNpmTarball(volume: RuntimeVolume, compressed: Uint8Array
  * 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.
+ * So this never assumes it worked. Strict boot surfaces the failure; automatic mode reports
+ * the cause before choosing the in-realm pod.
  */
 interface RuntimeWorker {
     postMessage(message: unknown): void;
@@ -2859,14 +2937,59 @@ declare function startRuntimeWorker(options?: {
     timeoutMs?: number;
 }): Promise<RuntimeWorker>;
 
+declare function syncChannelSupported(): boolean;
+
 /**
- * Can this environment support a blocking client at all?
+ * Wiring a container's HTTP servers up to real URLs in the page.
  *
- * `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.
+ * The service worker does the routing; this is the half that lives in the page
+ * and actually knows about the container.
+ *
+ * **Read the origin note before using this.** A preview served this way runs on
+ * *your* origin, so scripts inside it can reach `window.parent`, your cookies
+ * and your `localStorage` — the sandbox contains the program's *filesystem and
+ * process table*, not the page it serves. For code you did not write, either
+ * host the preview on a separate origin, or use {@link renderInto}, which puts
+ * the response in an iframe with no origin at all.
  */
-declare function syncChannelSupported(): boolean;
+
+interface PreviewOptions {
+    /** Where the worker script lives; defaults to the copy shipped beside the bundle. */
+    scriptUrl?: string | URL;
+    /** Registration scope. Must be able to see the paths a preview will request. */
+    scope?: string;
+}
+interface Preview {
+    /** The URL an iframe should be pointed at to see `port`. */
+    urlFor(port: number): string;
+    /** Stop answering requests and unregister the worker. */
+    dispose(): Promise<void>;
+}
+/**
+ * Register the preview worker and start answering its requests from `box`.
+ *
+ * Resolves to null where service workers are unavailable — a non-secure origin,
+ * a browser with them disabled, or any non-browser host. Callers should treat
+ * that as "no preview URLs here" and fall back to `box.request`.
+ */
+declare function createPreview(box: Container, options?: PreviewOptions): Promise<Preview | null>;
+/**
+ * Show one response from the container inside an element, without letting it
+ * touch the page.
+ *
+ * The iframe is sandboxed with `allow-scripts` and deliberately *without*
+ * `allow-same-origin`, which puts the document in an opaque origin: its scripts
+ * run, and they can reach neither this page's DOM nor its cookies and storage.
+ * That combination is what makes it safe to render output you do not trust.
+ *
+ * The trade-off is that only this one response exists — a page that asks for
+ * `/main.js` gets nothing, because there is no origin to serve it from. For a
+ * whole site, use {@link createPreview}, and read its note about origins first.
+ */
+declare function renderInto(box: Container, element: HTMLElement, options?: {
+    port: number;
+    path?: string;
+}): Promise<HTMLIFrameElement>;
 
 /**
  * sandboxedjs — a Linux-like container that runs entirely inside Node.js.
@@ -2886,4 +3009,4 @@ declare function syncChannelSupported(): boolean;
  * ```
  */
 
-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 };
+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, type Preview, type PreviewOptions, 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 WorkerRuntimeOptions, WorkerRuntimePod, type WriteOptions, allCommands, applyChmod, braceExpand, buildRootfs, builtinNames, captureStdio, configureCPython, configurePython, createChildProcessModule, createContainer, createContext, createCoreModules, createPreview, 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, renderInto, resetPidCounter, shellQuote, startRuntimeWorker, strerror, syncChannelSupported, transformEsm, unameInfo };

package/dist/index.d.ts

@@ -6,7 +6,7 @@ interface ChildHandle {
     pid: number;
     state: "starting" | "running" | "exited";
     exitCode: number | undefined;
-    on(event: "stdout" | "stderr" | "exit", listener: (...args: any[]) => void): unknown;
+    on(event: "stdout" | "stderr" | "exit" | "rawmode", listener: (...args: any[]) => void): unknown;
     exec(): void;
     sendStdin(data: string): void;
     /**
@@ -25,6 +25,14 @@ interface ChildSpawnConfig {
     cwd?: string;
     env?: Record<string, string>;
     parentPid?: number;
+    /**
+     * The child was given the parent's streams (`stdio: "inherit"`).
+     *
+     * Its input is then the parent's terminal rather than a pipe that will end,
+     * which is the difference between a program that waits for what the user
+     * types and one that reads to end-of-input and stops.
+     */
+    inheritStdio?: boolean;
 }
 type SpawnChild = (config: ChildSpawnConfig) => ChildHandle;
 /**
@@ -40,6 +48,7 @@ type SyncSpawn = (request: {
     cwd: string;
     env?: Record<string, string>;
     input?: string;
+    inheritStdio?: boolean;
 }) => {
     status: number | null;
     stdout: string;
@@ -50,7 +59,7 @@ type SyncSpawn = (request: {
         message: string;
     };
 };
-declare function createChildProcessModule(spawnChild: SpawnChild, defaultCwd: () => string, syncSpawn?: SyncSpawn): Record<string, unknown>;
+declare function createChildProcessModule(spawnChild: SpawnChild, defaultCwd: () => string, syncSpawn?: SyncSpawn, defaultEnv?: () => Record<string, string>): Record<string, unknown>;
 
 /**
  * Clean-room contracts between SandboxedJS and its JavaScript runtime.
@@ -433,7 +442,10 @@ declare class Pipe implements InputStream, OutputStream {
      * whole line on every keystroke — so the terminal must stop echoing, or
      * every character appears twice.
      */
-    rawMode: boolean;
+    private raw;
+    onRawMode?: (enabled: boolean) => void;
+    get rawMode(): boolean;
+    set rawMode(enabled: boolean);
     columns: number | undefined;
     rows: number | undefined;
     get closed(): boolean;
@@ -1382,6 +1394,8 @@ declare class Shell {
     constructor(init: ShellInit);
     /** Parse and run a script fragment. Returns the last exit status. */
     execute(source: string, io: ShellIO): Promise<number>;
+    /** Signal the current terminal pipeline without terminating the interactive shell. */
+    interruptForeground(signal: string, stdin: InputStream): void;
     get isExiting(): boolean;
     /** True when `source` is not yet a complete command (for REPL continuation). */
     static isIncomplete(source: string): boolean;
@@ -1665,12 +1679,15 @@ interface ContainerOptions {
     /**
      * 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.
+     * `"auto"` (the default) tries the worker runtime and reports any fallback.
+     * `"worker"` requires a working guest worker and shared-memory channel: boot
+     * rejects with the cause if either is unavailable, rather than letting
+     * synchronous child-process calls fail later. `"realm"` opts out explicitly.
+     * Processes requiring host-native modules can still run in the host realm.
      */
-    isolation?: "worker" | "realm";
+    isolation?: "auto" | "worker" | "realm";
+    /** Receives the reason for an automatic fallback; defaults to console.warn. */
+    onRuntimeFallback?: (error: Error) => void;
     /**
      * Where to load the guest worker bundle from.
      *
@@ -2457,6 +2474,7 @@ declare class VirtualHttpServer extends EventEmitter {
     readonly owner: string;
     listening: boolean;
     private portValue;
+    private referenced;
     constructor(router: VirtualHttpRouter, owner: string, listener?: (req: VirtualIncomingMessage, res: VirtualServerResponse) => void);
     listen(...args: any[]): this;
     close(callback?: (error?: Error) => void): this;
@@ -2467,17 +2485,20 @@ declare class VirtualHttpServer extends EventEmitter {
     } | null;
     ref(): this;
     unref(): this;
+    hasRef(): boolean;
     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;
+    onClose: ((port: number) => void) | undefined;
     register(port: number, server: VirtualHttpServer, owner: string): void;
     unregister(port: number, server: VirtualHttpServer): void;
     /** Whether anything in this container is listening on `port`. */
     activePortsIncludes(port: number): boolean;
     activePorts(owner?: string): number[];
+    referencedPorts(owner: string): number[];
     closeOwner(owner: string): void;
     closeAll(): void;
     request(port: number, init?: VirtualRequestInit): Promise<RuntimeHttpResponse>;
@@ -2734,6 +2755,7 @@ declare class LocalRuntimePod implements RuntimePod {
         spawn(config: ChildSpawnConfig): ChildHandle;
     };
     private disposed;
+    private readonly running;
     protected readonly workdir: string;
     protected readonly env: Record<string, string>;
     protected readonly aliases: Record<string, string>;
@@ -2777,6 +2799,62 @@ declare class LocalRuntimePod implements RuntimePod {
     private assertActive;
 }
 
+/**
+ * A pod that evaluates each guest program on its own thread.
+ *
+ * Everything shared stays here: the volume, the HTTP router, the package
+ * installer and the process table. Only the program's own evaluation moves,
+ * and it reaches back for the rest through a {@link SyncChannelServer}.
+ *
+ * That arrangement is forced rather than chosen. A synchronous call has to
+ * block the caller while the work it is waiting on still makes progress, so
+ * the blocking side cannot be the side that owns the resources — otherwise a
+ * child process needing the filesystem would have to call into a thread that
+ * is frozen waiting for that child. The guest blocks; the host never does.
+ *
+ * It inherits from {@link LocalRuntimePod} because every other part of the
+ * contract is identical, and overriding one method is a smaller and more
+ * honest claim than reimplementing nine. Both are held to the same contract
+ * suite (`test/pod-contract.ts`).
+ */
+
+interface WorkerRuntimeOptions extends LocalRuntimeOptions {
+    /** Where the guest bundle lives; defaults to the copy shipped beside this one. */
+    workerUrl?: string | URL;
+}
+declare class WorkerRuntimePod extends LocalRuntimePod {
+    private readonly workerUrl;
+    /** Live workers, so teardown can stop them all. */
+    private readonly live;
+    protected constructor(options: WorkerRuntimeOptions);
+    /** Boot without silently dropping synchronous child-process support. */
+    static boot(options?: WorkerRuntimeOptions): Promise<WorkerRuntimePod>;
+    /** Compatibility mode, with an observable explanation for every fallback. */
+    static tryBoot(options?: WorkerRuntimeOptions, onFallback?: (error: Error) => void): Promise<WorkerRuntimePod | null>;
+    spawn(command: string, args?: string[], options?: Record<string, unknown>): Promise<RuntimeProcess>;
+    private spawnInWorker;
+    /** Start an asynchronous child on the host's behalf and relay its events. */
+    private startChild;
+    /** Run a child to completion and collect it, for the guest's `spawnSync`. */
+    private runChildToCompletion;
+    private readonly proxies;
+    private readonly waiting;
+    private nextRequestId;
+    /**
+     * Register a stand-in for a server that is actually running in the Worker.
+     *
+     * The router only knows how to reach servers on this thread, so each bound
+     * port gets a local server whose whole job is to forward and wait.
+     */
+    private proxyPort;
+    private forward;
+    private settleProxied;
+    private closeProxies;
+    teardown(): void;
+    /** Does anything under `cwd` need a module only the host can supply? */
+    private needsHostModules;
+}
+
 interface RegistryManifest {
     name: string;
     version: string;
@@ -2837,8 +2915,8 @@ declare function extractNpmTarball(volume: RuntimeVolume, compressed: Uint8Array
  * 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.
+ * So this never assumes it worked. Strict boot surfaces the failure; automatic mode reports
+ * the cause before choosing the in-realm pod.
  */
 interface RuntimeWorker {
     postMessage(message: unknown): void;
@@ -2859,14 +2937,59 @@ declare function startRuntimeWorker(options?: {
     timeoutMs?: number;
 }): Promise<RuntimeWorker>;
 
+declare function syncChannelSupported(): boolean;
+
 /**
- * Can this environment support a blocking client at all?
+ * Wiring a container's HTTP servers up to real URLs in the page.
  *
- * `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.
+ * The service worker does the routing; this is the half that lives in the page
+ * and actually knows about the container.
+ *
+ * **Read the origin note before using this.** A preview served this way runs on
+ * *your* origin, so scripts inside it can reach `window.parent`, your cookies
+ * and your `localStorage` — the sandbox contains the program's *filesystem and
+ * process table*, not the page it serves. For code you did not write, either
+ * host the preview on a separate origin, or use {@link renderInto}, which puts
+ * the response in an iframe with no origin at all.
  */
-declare function syncChannelSupported(): boolean;
+
+interface PreviewOptions {
+    /** Where the worker script lives; defaults to the copy shipped beside the bundle. */
+    scriptUrl?: string | URL;
+    /** Registration scope. Must be able to see the paths a preview will request. */
+    scope?: string;
+}
+interface Preview {
+    /** The URL an iframe should be pointed at to see `port`. */
+    urlFor(port: number): string;
+    /** Stop answering requests and unregister the worker. */
+    dispose(): Promise<void>;
+}
+/**
+ * Register the preview worker and start answering its requests from `box`.
+ *
+ * Resolves to null where service workers are unavailable — a non-secure origin,
+ * a browser with them disabled, or any non-browser host. Callers should treat
+ * that as "no preview URLs here" and fall back to `box.request`.
+ */
+declare function createPreview(box: Container, options?: PreviewOptions): Promise<Preview | null>;
+/**
+ * Show one response from the container inside an element, without letting it
+ * touch the page.
+ *
+ * The iframe is sandboxed with `allow-scripts` and deliberately *without*
+ * `allow-same-origin`, which puts the document in an opaque origin: its scripts
+ * run, and they can reach neither this page's DOM nor its cookies and storage.
+ * That combination is what makes it safe to render output you do not trust.
+ *
+ * The trade-off is that only this one response exists — a page that asks for
+ * `/main.js` gets nothing, because there is no origin to serve it from. For a
+ * whole site, use {@link createPreview}, and read its note about origins first.
+ */
+declare function renderInto(box: Container, element: HTMLElement, options?: {
+    port: number;
+    path?: string;
+}): Promise<HTMLIFrameElement>;
 
 /**
  * sandboxedjs — a Linux-like container that runs entirely inside Node.js.
@@ -2886,4 +3009,4 @@ declare function syncChannelSupported(): boolean;
  * ```
  */
 
-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 };
+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, type Preview, type PreviewOptions, 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 WorkerRuntimeOptions, WorkerRuntimePod, type WriteOptions, allCommands, applyChmod, braceExpand, buildRootfs, builtinNames, captureStdio, configureCPython, configurePython, createChildProcessModule, createContainer, createContext, createCoreModules, createPreview, 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, renderInto, resetPidCounter, shellQuote, startRuntimeWorker, strerror, syncChannelSupported, transformEsm, unameInfo };