sandboxedjs 0.1.29 → 0.1.30

package/dist/index.d.cts

@@ -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.
@@ -2777,6 +2786,68 @@ 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 a Worker-backed pod, or return null when this host cannot support one.
+     *
+     * Declining is a first-class outcome. `SharedArrayBuffer` needs cross-origin
+     * isolation, a bundler may have made the guest script unreachable, and a host
+     * that supplied its own module objects has handed over things no thread
+     * boundary can carry. In every case the caller falls back to the in-realm pod
+     * and keeps working.
+     */
+    static tryBoot(options?: WorkerRuntimeOptions): 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;
@@ -2868,6 +2939,58 @@ declare function startRuntimeWorker(options?: {
  */
 declare function syncChannelSupported(): boolean;
 
+/**
+ * Wiring a container's HTTP servers up to real URLs in the page.
+ *
+ * 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.
+ */
+
+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

@@ -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.
@@ -2777,6 +2786,68 @@ 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 a Worker-backed pod, or return null when this host cannot support one.
+     *
+     * Declining is a first-class outcome. `SharedArrayBuffer` needs cross-origin
+     * isolation, a bundler may have made the guest script unreachable, and a host
+     * that supplied its own module objects has handed over things no thread
+     * boundary can carry. In every case the caller falls back to the in-realm pod
+     * and keeps working.
+     */
+    static tryBoot(options?: WorkerRuntimeOptions): 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;
@@ -2868,6 +2939,58 @@ declare function startRuntimeWorker(options?: {
  */
 declare function syncChannelSupported(): boolean;
 
+/**
+ * Wiring a container's HTTP servers up to real URLs in the page.
+ *
+ * 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.
+ */
+
+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.js

@@ -19695,6 +19695,10 @@ var KernelChildProcess = class {
   started = false;
   cancelled = false;
   constructor(kernel, cred, config, pid) {
+    if (config.inheritStdio) {
+      this.stdin.isTTY = true;
+      this.stdin.interactive = true;
+    }
     this.kernel = kernel;
     this.cred = cred;
     this.pid = pid;
@@ -22099,7 +22103,8 @@ var ChildProcess = class extends EventEmitter4 {
     queueMicrotask(() => this.emit("close", code, null));
   }
 };
-function createChildProcessModule(spawnChild, defaultCwd, syncSpawn) {
+function createChildProcessModule(spawnChild, defaultCwd, syncSpawn, defaultEnv = () => ({})) {
+  const environmentFor = (options) => options.env ? { ...options.env } : defaultEnv();
   const throughShell = (command, options) => {
     const shell = typeof options.shell === "string" ? options.shell : "/bin/sh";
     return { file: shell, args: ["-c", command] };
@@ -22110,7 +22115,7 @@ function createChildProcessModule(spawnChild, defaultCwd, syncSpawn) {
       command: resolved.file,
       args: resolved.args,
       cwd: options.cwd ?? defaultCwd(),
-      ...options.env ? { env: options.env } : {}
+      env: environmentFor(options)
     });
     return new ChildProcess(handle, resolved.file, resolved.args);
   };
@@ -22156,11 +22161,11 @@ ${err.join("")}`),
     exec,
     execFile,
     fork: (modulePath, args = [], options = {}) => spawn("node", [modulePath, ...args], options),
-    ...buildSyncFamily(syncSpawn, throughShell, defaultCwd),
+    ...buildSyncFamily(syncSpawn, throughShell, defaultCwd, environmentFor),
     ChildProcess
   };
 }
-function buildSyncFamily(syncSpawn, throughShell, defaultCwd) {
+function buildSyncFamily(syncSpawn, throughShell, defaultCwd, environmentFor) {
   if (!syncSpawn) {
     return {
       execSync: unavailable("execSync"),
@@ -22171,12 +22176,14 @@ function buildSyncFamily(syncSpawn, throughShell, defaultCwd) {
   const run = (file3, args, options) => {
     const resolved = options.shell ? throughShell([file3, ...args].join(" "), options) : { file: file3, args };
     const input = options.input === void 0 ? void 0 : typeof options.input === "string" ? options.input : new TextDecoder().decode(options.input);
+    const inherit = options.stdio === "inherit" || Array.isArray(options.stdio) && options.stdio[0] === "inherit";
     return syncSpawn({
       command: resolved.file,
       args: resolved.args,
       cwd: options.cwd ?? defaultCwd(),
-      ...options.env ? { env: options.env } : {},
-      ...input === void 0 ? {} : { input }
+      env: environmentFor(options),
+      ...input === void 0 ? {} : { input },
+      ...inherit ? { inheritStdio: true } : {}
     });
   };
   const asOutput = (text2, options) => options.encoding === "buffer" || options.encoding === void 0 ? Buffer2.from(text2) : text2;
@@ -22856,7 +22863,7 @@ function createCoreModules(options) {
   };
   const http = options.http ? createHttpModule(options.http.router, options.http.owner, httpOptions, "http:") : createUnsupportedModule("http");
   const https = options.http ? createHttpModule(options.http.router, options.http.owner, httpOptions, "https:") : createUnsupportedModule("https");
-  const childProcess = options.spawnChild ? createChildProcessModule(options.spawnChild, () => cwd, options.syncSpawn) : createUnsupportedModule("child_process");
+  const childProcess = options.spawnChild ? createChildProcessModule(options.spawnChild, () => cwd, options.syncSpawn, () => ({ ...processObject.env })) : createUnsupportedModule("child_process");
   const readline = createReadlineModule(() => processObject.stdin, () => processObject.stdout);
   const dns = createDnsModule();
   const builtins = {
@@ -24101,8 +24108,10 @@ var MirroringVolume = class {
    * container pays nothing for this.
    */
   attach(mirror, root) {
+    const cleanRoot = clean(root);
+    if (this.mirror === mirror && this.root === cleanRoot) return;
     this.mirror = mirror;
-    this.root = clean(root);
+    this.root = cleanRoot;
     this.seed();
   }
   detach() {
@@ -25237,9 +25246,10 @@ var WorkerRuntimePod = class _WorkerRuntimePod extends LocalRuntimePod {
       ...this.workerUrl ? { url: this.workerUrl } : {},
       timeoutMs: 15e3
     });
+    const streams = { target: null };
     const server = new SyncChannelServer(buffers, serveSyncSyscalls({
       volume: this.volume,
-      spawnChild: (request) => this.runChildToCompletion(request)
+      spawnChild: (request) => this.runChildToCompletion(request, streams.target)
     }));
     const entry = { worker, server };
     this.live.add(entry);
@@ -25249,6 +25259,7 @@ var WorkerRuntimePod = class _WorkerRuntimePod extends LocalRuntimePod {
       this.closeProxies(owner);
       void worker.terminate();
     });
+    streams.target = process2;
     const children = /* @__PURE__ */ new Map();
     worker.onMessage((raw) => {
       const message = raw;
@@ -25315,7 +25326,7 @@ var WorkerRuntimePod = class _WorkerRuntimePod extends LocalRuntimePod {
     handle.exec();
   }
   /** Run a child to completion and collect it, for the guest's `spawnSync`. */
-  runChildToCompletion(request) {
+  runChildToCompletion(request, streamTo) {
     return new Promise((resolve2) => {
       let handle;
       try {
@@ -25323,7 +25334,8 @@ var WorkerRuntimePod = class _WorkerRuntimePod extends LocalRuntimePod {
           command: request.command,
           args: request.args,
           cwd: request.cwd,
-          ...request.env ? { env: request.env } : {}
+          ...request.env ? { env: request.env } : {},
+          ...request.inheritStdio ? { inheritStdio: true } : {}
         });
       } catch (error) {
         const failure = error;
@@ -25332,18 +25344,21 @@ var WorkerRuntimePod = class _WorkerRuntimePod extends LocalRuntimePod {
       }
       let stdout = "";
       let stderr = "";
+      const live = request.inheritStdio ? streamTo : null;
       handle.on("stdout", (text2) => {
         stdout += text2;
+        live?.output(text2);
       });
       handle.on("stderr", (text2) => {
         stderr += text2;
+        live?.error(text2);
       });
       handle.on("exit", (code) => resolve2({ status: code, stdout, stderr, signal: null }));
       handle.exec();
       if (request.input !== void 0) {
         handle.sendStdin?.(request.input);
       }
-      handle.endStdin?.();
+      if (!request.inheritStdio) handle.endStdin?.();
     });
   }
   // ── HTTP servers living on another thread ─────────────────────────────────
@@ -26344,8 +26359,99 @@ init_variables();
 init_arith();
 init_expand();
 init_builtins();
+
+// src/preview/register.ts
+function serveContainerOn(port, box) {
+  port.onmessage = async (event) => {
+    const request = event.data;
+    try {
+      const response = await box.request(request.port, {
+        method: request.method,
+        path: request.path,
+        headers: request.headers,
+        ...request.body ? { body: new Uint8Array(request.body) } : {}
+      });
+      const bytes2 = response.bytes.slice();
+      port.postMessage(
+        {
+          id: request.id,
+          response: {
+            status: response.status,
+            statusText: response.statusText,
+            headers: response.headers,
+            body: bytes2.buffer
+          }
+        },
+        [bytes2.buffer]
+      );
+    } catch (error) {
+      const message = new TextEncoder().encode(error instanceof Error ? error.message : String(error));
+      port.postMessage({
+        id: request.id,
+        response: { status: 502, statusText: "Bad Gateway", headers: {}, body: message.buffer }
+      });
+    }
+  };
+  port.start?.();
+}
+async function createPreview(box, options = {}) {
+  if (typeof navigator === "undefined" || !("serviceWorker" in navigator)) return null;
+  const scriptUrl = options.scriptUrl ?? new URL("./service-worker.js", import.meta.url);
+  let registration;
+  try {
+    registration = await navigator.serviceWorker.register(scriptUrl, {
+      type: "module",
+      ...options.scope ? { scope: options.scope } : {}
+    });
+  } catch {
+    return null;
+  }
+  const worker = registration.active ?? registration.waiting ?? registration.installing;
+  if (!worker) return null;
+  if (worker.state !== "activated") {
+    const activated = await new Promise((resolve2) => {
+      const check = () => {
+        if (worker.state === "activated") {
+          worker.removeEventListener("statechange", check);
+          resolve2(true);
+        } else if (worker.state === "redundant") {
+          worker.removeEventListener("statechange", check);
+          resolve2(false);
+        }
+      };
+      worker.addEventListener("statechange", check);
+      setTimeout(() => resolve2(worker.state === "activated"), 1e4);
+      check();
+    });
+    if (!activated) return null;
+  }
+  const channel = new MessageChannel();
+  serveContainerOn(channel.port1, box);
+  worker.postMessage({ type: "sandboxedjs:connect" }, [channel.port2]);
+  const base2 = registration.scope.replace(/\/$/, "");
+  return {
+    urlFor: (port) => `${base2}/__sbx__/${port}/`,
+    dispose: async () => {
+      channel.port1.close();
+      await registration.unregister();
+    }
+  };
+}
+async function renderInto(box, element, options = { port: 80 }) {
+  const response = await box.request(options.port, { path: options.path ?? "/" });
+  const frame = document.createElement("iframe");
+  frame.setAttribute("sandbox", "allow-scripts");
+  frame.style.width = "100%";
+  frame.style.height = "100%";
+  frame.style.border = "0";
+  frame.srcdoc = response.body;
+  element.replaceChildren(frame);
+  return frame;
+}
+
+// src/index.ts
 var src_default = createContainer;
 
-export { ArithError, BufferSink, CallbackSink, CleanPackageInstaller, CommandRegistry, CommonJsEngine, Container, ContainerFs, ERRNO, FileInput, FileOutput, IncompleteInputError, KERNEL_NAME, KERNEL_RELEASE, Kernel, LocalRuntimePod, MemoryVolume, NODE_VERSION, NPM_VERSION, NetworkStack, NullInput, NullOutput, OS_RELEASE, PYTHON_VERSION, Pipe, Process, ProcessTable, ROOT_CRED, SIGNALS, SIGNAL_NAMES, Session, Shell, ShellExit, Lexer as ShellLexer, ShellSyntaxError, Stats, SysError, TeeOutput, Terminal, UserDatabase, Variables, Vfs, VirtualHttpRouter, VirtualHttpServer, VirtualIncomingMessage, VirtualServerResponse, WASM_ALIASES, allCommands, applyChmod, braceExpand, buildRootfs, builtinNames, captureStdio, configureCPython, configurePython, createChildProcessModule, createContainer, createContext, createCoreModules, src_default 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_exports as posixPath, resetPidCounter, shellQuote, startRuntimeWorker, strerror, syncChannelSupported, transformEsm, unameInfo };
+export { ArithError, BufferSink, CallbackSink, CleanPackageInstaller, CommandRegistry, CommonJsEngine, Container, ContainerFs, ERRNO, FileInput, FileOutput, IncompleteInputError, KERNEL_NAME, KERNEL_RELEASE, Kernel, LocalRuntimePod, MemoryVolume, NODE_VERSION, NPM_VERSION, NetworkStack, NullInput, NullOutput, OS_RELEASE, PYTHON_VERSION, Pipe, Process, ProcessTable, ROOT_CRED, SIGNALS, SIGNAL_NAMES, Session, Shell, ShellExit, Lexer as ShellLexer, ShellSyntaxError, Stats, SysError, TeeOutput, Terminal, UserDatabase, Variables, Vfs, VirtualHttpRouter, VirtualHttpServer, VirtualIncomingMessage, VirtualServerResponse, WASM_ALIASES, WorkerRuntimePod, allCommands, applyChmod, braceExpand, buildRootfs, builtinNames, captureStdio, configureCPython, configurePython, createChildProcessModule, createContainer, createContext, createCoreModules, createPreview, src_default 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_exports as posixPath, renderInto, resetPidCounter, shellQuote, startRuntimeWorker, strerror, syncChannelSupported, transformEsm, unameInfo };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map