npm - sandboxedjs - Versions diffs - 0.1.45 → 0.1.46 - Mend

sandboxedjs 0.1.45 → 0.1.46

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (16) hide show

package/README.md +23 -3
package/dist/agent.d.cts +1 -1
package/dist/agent.d.ts +1 -1
package/dist/{container-CZn9USBQ.d.cts → container-DyRF-bY0.d.cts} +52 -1
package/dist/{container-CZn9USBQ.d.ts → container-DyRF-bY0.d.ts} +52 -1
package/dist/index.cjs +242 -2
package/dist/index.cjs.map +1 -1
package/dist/index.d.cts +104 -4
package/dist/index.d.ts +104 -4
package/dist/index.js +242 -2
package/dist/index.js.map +1 -1
package/dist/service-worker.js +340 -8
package/dist/service-worker.js.map +1 -1
package/dist/worker-entry.js +133 -1
package/dist/worker-entry.js.map +1 -1
package/package.json +4 -2

package/README.md CHANGED Viewed

@@ -669,9 +669,10 @@ These are runtime lifecycle rules, not Vite-specific command replacements.
 **Not done — these things still stand between this and a complete browser IDE.**
-- *Preview isolation and WebSockets.* `createPreview()` registers the bundled service worker
-  and routes HTTP requests into the container. It is an origin-local preview for trusted code;
-  WebSocket forwarding/HMR is not implemented. Reload the iframe after changes.
+- *Preview isolation.* `createPreview()` registers the bundled service worker and routes HTTP
+  and WebSocket traffic into the container. It is an origin-local preview for trusted code:
+  scripts in the frame share your origin. Serve it from a separate origin for anything you
+  did not write.
 - *Complete worker isolation.* Worker-capable programs run off the main thread, but host-backed
   compiler modules can require the local runtime. Container code is not a security boundary
   from the host page; do not treat it as one.
@@ -846,6 +847,25 @@ URLs — `/src/main.js`, `/@vite/client` — resolve without rewriting anything.
 > page it serves. Use it for code you trust; for anything else, serve the preview from a separate
 > origin (a subdomain pointed at the same app) or stay with option 2.
+**WebSockets, and why the HTML is modified.** A service worker can answer `fetch`; it cannot
+answer a WebSocket handshake, because no browser ever shipped that. So a previewed page is handed
+a `WebSocket` that tunnels through the host page into the container, injected as one `<script>` at
+the top of `<head>`. URLs that do not name the container keep the native implementation.
+```ts
+const preview = await createPreview(box, { websocket: false });  // serve HTML byte for byte
+```
+This is what makes HMR work. Without it Vite loses more than hot reload: it loses the only channel
+it has for telling a page that its dependency hashes are stale, which it needs after re-optimizing
+dependencies — and the frame is then stranded on `504 Outdated Optimize Dep` with every module
+failing and nothing to explain it. If you turn injection off, pass `onStale` to reload the frame
+yourself.
+The container side is a real socket, not a Vite shim: `http` servers emit `upgrade` with a duplex
+socket, so `ws` and `socket.io` work unmodified. To speak to one from your own code rather than
+from a previewed page, use `box.connect(port, init, peer)`.
 Service workers need a secure context, and some embedded browsers disable them entirely — hence
 the `null` return rather than a throw. Responses are served with both
 `Cross-Origin-Resource-Policy` and `Cross-Origin-Embedder-Policy`, so a preview still frames

package/dist/agent.d.cts CHANGED Viewed

@@ -1,4 +1,4 @@
-import { C as Container } from './container-CZn9USBQ.cjs';
+import { C as Container } from './container-DyRF-bY0.cjs';
 /**
  * Structural copies of the LangChain Deep Agents backend contract.

package/dist/agent.d.ts CHANGED Viewed

@@ -1,4 +1,4 @@
-import { C as Container } from './container-CZn9USBQ.js';
+import { C as Container } from './container-DyRF-bY0.js';
 /**
  * Structural copies of the LangChain Deep Agents backend contract.

package/dist/{container-CZn9USBQ.d.cts → container-DyRF-bY0.d.cts} RENAMED Viewed

@@ -146,6 +146,16 @@ interface RuntimePackageInstaller {
     /** Create a view that installs into another project root. */
     forCwd?(cwd: string): RuntimePackageInstaller;
 }
+/** Where bytes written by an upgraded server inside the container come out. */
+interface RuntimeSocketPeer {
+    data(bytes: Uint8Array): void;
+    close(): void;
+}
+/** The caller's end of a connection opened with {@link RuntimePod.connect}. */
+interface RuntimeConnection {
+    send(bytes: Uint8Array): void;
+    close(): void;
+}
 /** The process-manager protocol a container's kernel bridge substitutes for. */
 interface RuntimeProcessManager {
     spawn(config: ChildSpawnConfig): ChildHandle;
@@ -160,6 +170,14 @@ interface RuntimePod {
     };
     spawn(command: string, args?: string[], options?: Record<string, unknown>): Promise<RuntimeProcess>;
     request(port: number, init?: Record<string, unknown>): Promise<RuntimeHttpResponse>;
+    /**
+     * Open a connection that upgrades out of HTTP, or null if nothing takes one.
+     *
+     * Optional because a pod that only ever answers requests is still a usable
+     * pod — a caller treats the absence as "no WebSocket here" rather than as a
+     * broken implementation.
+     */
+    connect?(port: number, init: Record<string, unknown>, peer: RuntimeSocketPeer): RuntimeConnection | null;
     snapshot(options?: Record<string, unknown>): unknown;
     restore(snapshot: unknown, options?: Record<string, unknown>): Promise<void>;
     teardown(): void;
@@ -1705,6 +1723,20 @@ interface HttpResponse {
     bytes: Uint8Array;
     json<T = unknown>(): T;
 }
+/** Where bytes written by an upgraded server inside the container come out. */
+interface SocketPeer {
+    /** The server sent these. */
+    data(bytes: Uint8Array): void;
+    /** The server hung up. */
+    close(): void;
+}
+/** The caller's end of a connection opened with {@link Container.connect}. */
+interface SocketConnection {
+    /** Send bytes to the server. */
+    send(bytes: Uint8Array): void;
+    /** Hang up. */
+    close(): void;
+}
 declare class Container {
     readonly kernel: Kernel;
     readonly pod: RuntimePod;
@@ -1758,6 +1790,25 @@ declare class Container {
         headers?: Record<string, string>;
         body?: string | Uint8Array;
     }): Promise<HttpResponse>;
+    /**
+     * Open a connection to a server inside the container that upgrades out of
+     * HTTP — in practice, a WebSocket.
+     *
+     * The counterpart to {@link request}, and the thing a dev server needs that
+     * a request cannot provide. Bytes go in with `send`, come back through
+     * `peer.data`, and neither side interprets them: the container runs whatever
+     * WebSocket library the program chose, and the caller is responsible for
+     * speaking the protocol it answers with.
+     *
+     * Null means there is nothing to talk to — no server on the port, or one
+     * that never registered an `upgrade` handler. Both are worth reporting
+     * rather than waiting out, because neither resolves on its own.
+     */
+    connect(port: number, init: {
+        method?: string;
+        path?: string;
+        headers?: Record<string, string>;
+    } | undefined, peer: SocketPeer): SocketConnection | null;
     /**
      * Deliver a request whose body is bytes, without letting them become text.
      *
@@ -1808,4 +1859,4 @@ declare class Container {
 /** Boot a container. The one function most callers need. */
 declare function createContainer(opts?: ContainerOptions): Promise<Container>;
-export { type ProcessKind as $, type KernelOptions as A, BufferSink as B, Container as C, type DirEntry as D, type ExecContext as E, type FileData as F, type GroupEntry as G, type HttpResponse as H, type InputStream as I, type Job as J, Kernel as K, type ListeningPort as L, type MountEntry as M, type Node as N, type OutputStream as O, type NetInterface as P, type NetworkOptions as Q, type RuntimeVolume as R, Shell as S, NetworkStack as T, NullInput as U, Vfs as V, NullOutput as W, PYTHON_VERSION as X, type PasswdEntry as Y, Pipe as Z, Process as _, type ShellIO as a, type ProcessOptions as a0, type ProcessState as a1, ProcessTable as a2, type PythonOptions as a3, ROOT_CRED as a4, type ResolvedExecutable as a5, type RunOptions as a6, type RunResult as a7, type RuntimeProcessManager as a8, type RuntimeProcessResult as a9, isCPythonAvailable as aA, isPythonAvailable as aB, makeCred as aC, octalMode as aD, parseUmask as aE, resetPidCounter as aF, shellQuote as aG, type SessionInit as aa, type SessionResult as ab, type SessionRunOptions as ac, ShellExit as ad, type ShellInit as ae, type ShellOptions as af, type SpawnHandle as ag, Stats as ah, type Stdio as ai, TeeOutput as aj, UserDatabase as ak, Variables as al, type VirtualNode as am, type VirtualProvider as an, type WriteOptions as ao, applyChmod as ap, braceExpand as aq, captureStdio as ar, configureCPython as as, configurePython as at, createChildProcessModule as au, createContext as av, defineCommand as aw, expandWord as ax, expandWords as ay, formatMode as az, Session as b, type Cred as c, type Command as d, type VolumeStat as e, type VolumeStats as f, type RuntimeHttpResponse as g, type SpawnChild as h, type SyncSpawn as i, type RuntimePod as j, type RuntimePackageInstaller as k, type ChildSpawnConfig as l, type ChildHandle as m, type RuntimeProcess as n, createContainer as o, type CPythonOptions as p, CallbackSink as q, CommandRegistry as r, ContainerFs as s, type ContainerOptions as t, type ContextInit as u, type Env as v, type ExecOptions as w, type ExecResult as x, FileInput as y, FileOutput as z };
+export { Pipe as $, FileInput as A, BufferSink as B, Container as C, type DirEntry as D, type ExecContext as E, type FileData as F, FileOutput as G, type GroupEntry as H, type HttpResponse as I, type InputStream as J, Kernel as K, type Job as L, type KernelOptions as M, type Node as N, type OutputStream as O, type ListeningPort as P, type MountEntry as Q, type RuntimeVolume as R, Shell as S, type NetInterface as T, type NetworkOptions as U, Vfs as V, NetworkStack as W, NullInput as X, NullOutput as Y, PYTHON_VERSION as Z, type PasswdEntry as _, type ShellIO as a, Process as a0, type ProcessKind as a1, type ProcessOptions as a2, type ProcessState as a3, ProcessTable as a4, type PythonOptions as a5, ROOT_CRED as a6, type ResolvedExecutable as a7, type RunOptions as a8, type RunResult as a9, expandWords as aA, formatMode as aB, isCPythonAvailable as aC, isPythonAvailable as aD, makeCred as aE, octalMode as aF, parseUmask as aG, resetPidCounter as aH, shellQuote as aI, type RuntimeProcessManager as aa, type RuntimeProcessResult as ab, type SessionInit as ac, type SessionResult as ad, type SessionRunOptions as ae, ShellExit as af, type ShellInit as ag, type ShellOptions as ah, type SpawnHandle as ai, Stats as aj, type Stdio as ak, TeeOutput as al, UserDatabase as am, Variables as an, type VirtualNode as ao, type VirtualProvider as ap, type WriteOptions as aq, applyChmod as ar, braceExpand as as, captureStdio as at, configureCPython as au, configurePython as av, createChildProcessModule as aw, createContext as ax, defineCommand as ay, expandWord as az, Session as b, type Cred as c, type Command as d, type VolumeStat as e, type VolumeStats as f, type RuntimeHttpResponse as g, type SpawnChild as h, type SyncSpawn as i, type RuntimePod as j, type RuntimePackageInstaller as k, type ChildSpawnConfig as l, type ChildHandle as m, type RuntimeProcess as n, type RuntimeSocketPeer as o, type RuntimeConnection as p, createContainer as q, type CPythonOptions as r, CallbackSink as s, CommandRegistry as t, ContainerFs as u, type ContainerOptions as v, type ContextInit as w, type Env as x, type ExecOptions as y, type ExecResult as z };

package/dist/{container-CZn9USBQ.d.ts → container-DyRF-bY0.d.ts} RENAMED Viewed

@@ -146,6 +146,16 @@ interface RuntimePackageInstaller {
     /** Create a view that installs into another project root. */
     forCwd?(cwd: string): RuntimePackageInstaller;
 }
+/** Where bytes written by an upgraded server inside the container come out. */
+interface RuntimeSocketPeer {
+    data(bytes: Uint8Array): void;
+    close(): void;
+}
+/** The caller's end of a connection opened with {@link RuntimePod.connect}. */
+interface RuntimeConnection {
+    send(bytes: Uint8Array): void;
+    close(): void;
+}
 /** The process-manager protocol a container's kernel bridge substitutes for. */
 interface RuntimeProcessManager {
     spawn(config: ChildSpawnConfig): ChildHandle;
@@ -160,6 +170,14 @@ interface RuntimePod {
     };
     spawn(command: string, args?: string[], options?: Record<string, unknown>): Promise<RuntimeProcess>;
     request(port: number, init?: Record<string, unknown>): Promise<RuntimeHttpResponse>;
+    /**
+     * Open a connection that upgrades out of HTTP, or null if nothing takes one.
+     *
+     * Optional because a pod that only ever answers requests is still a usable
+     * pod — a caller treats the absence as "no WebSocket here" rather than as a
+     * broken implementation.
+     */
+    connect?(port: number, init: Record<string, unknown>, peer: RuntimeSocketPeer): RuntimeConnection | null;
     snapshot(options?: Record<string, unknown>): unknown;
     restore(snapshot: unknown, options?: Record<string, unknown>): Promise<void>;
     teardown(): void;
@@ -1705,6 +1723,20 @@ interface HttpResponse {
     bytes: Uint8Array;
     json<T = unknown>(): T;
 }
+/** Where bytes written by an upgraded server inside the container come out. */
+interface SocketPeer {
+    /** The server sent these. */
+    data(bytes: Uint8Array): void;
+    /** The server hung up. */
+    close(): void;
+}
+/** The caller's end of a connection opened with {@link Container.connect}. */
+interface SocketConnection {
+    /** Send bytes to the server. */
+    send(bytes: Uint8Array): void;
+    /** Hang up. */
+    close(): void;
+}
 declare class Container {
     readonly kernel: Kernel;
     readonly pod: RuntimePod;
@@ -1758,6 +1790,25 @@ declare class Container {
         headers?: Record<string, string>;
         body?: string | Uint8Array;
     }): Promise<HttpResponse>;
+    /**
+     * Open a connection to a server inside the container that upgrades out of
+     * HTTP — in practice, a WebSocket.
+     *
+     * The counterpart to {@link request}, and the thing a dev server needs that
+     * a request cannot provide. Bytes go in with `send`, come back through
+     * `peer.data`, and neither side interprets them: the container runs whatever
+     * WebSocket library the program chose, and the caller is responsible for
+     * speaking the protocol it answers with.
+     *
+     * Null means there is nothing to talk to — no server on the port, or one
+     * that never registered an `upgrade` handler. Both are worth reporting
+     * rather than waiting out, because neither resolves on its own.
+     */
+    connect(port: number, init: {
+        method?: string;
+        path?: string;
+        headers?: Record<string, string>;
+    } | undefined, peer: SocketPeer): SocketConnection | null;
     /**
      * Deliver a request whose body is bytes, without letting them become text.
      *
@@ -1808,4 +1859,4 @@ declare class Container {
 /** Boot a container. The one function most callers need. */
 declare function createContainer(opts?: ContainerOptions): Promise<Container>;
-export { type ProcessKind as $, type KernelOptions as A, BufferSink as B, Container as C, type DirEntry as D, type ExecContext as E, type FileData as F, type GroupEntry as G, type HttpResponse as H, type InputStream as I, type Job as J, Kernel as K, type ListeningPort as L, type MountEntry as M, type Node as N, type OutputStream as O, type NetInterface as P, type NetworkOptions as Q, type RuntimeVolume as R, Shell as S, NetworkStack as T, NullInput as U, Vfs as V, NullOutput as W, PYTHON_VERSION as X, type PasswdEntry as Y, Pipe as Z, Process as _, type ShellIO as a, type ProcessOptions as a0, type ProcessState as a1, ProcessTable as a2, type PythonOptions as a3, ROOT_CRED as a4, type ResolvedExecutable as a5, type RunOptions as a6, type RunResult as a7, type RuntimeProcessManager as a8, type RuntimeProcessResult as a9, isCPythonAvailable as aA, isPythonAvailable as aB, makeCred as aC, octalMode as aD, parseUmask as aE, resetPidCounter as aF, shellQuote as aG, type SessionInit as aa, type SessionResult as ab, type SessionRunOptions as ac, ShellExit as ad, type ShellInit as ae, type ShellOptions as af, type SpawnHandle as ag, Stats as ah, type Stdio as ai, TeeOutput as aj, UserDatabase as ak, Variables as al, type VirtualNode as am, type VirtualProvider as an, type WriteOptions as ao, applyChmod as ap, braceExpand as aq, captureStdio as ar, configureCPython as as, configurePython as at, createChildProcessModule as au, createContext as av, defineCommand as aw, expandWord as ax, expandWords as ay, formatMode as az, Session as b, type Cred as c, type Command as d, type VolumeStat as e, type VolumeStats as f, type RuntimeHttpResponse as g, type SpawnChild as h, type SyncSpawn as i, type RuntimePod as j, type RuntimePackageInstaller as k, type ChildSpawnConfig as l, type ChildHandle as m, type RuntimeProcess as n, createContainer as o, type CPythonOptions as p, CallbackSink as q, CommandRegistry as r, ContainerFs as s, type ContainerOptions as t, type ContextInit as u, type Env as v, type ExecOptions as w, type ExecResult as x, FileInput as y, FileOutput as z };
+export { Pipe as $, FileInput as A, BufferSink as B, Container as C, type DirEntry as D, type ExecContext as E, type FileData as F, FileOutput as G, type GroupEntry as H, type HttpResponse as I, type InputStream as J, Kernel as K, type Job as L, type KernelOptions as M, type Node as N, type OutputStream as O, type ListeningPort as P, type MountEntry as Q, type RuntimeVolume as R, Shell as S, type NetInterface as T, type NetworkOptions as U, Vfs as V, NetworkStack as W, NullInput as X, NullOutput as Y, PYTHON_VERSION as Z, type PasswdEntry as _, type ShellIO as a, Process as a0, type ProcessKind as a1, type ProcessOptions as a2, type ProcessState as a3, ProcessTable as a4, type PythonOptions as a5, ROOT_CRED as a6, type ResolvedExecutable as a7, type RunOptions as a8, type RunResult as a9, expandWords as aA, formatMode as aB, isCPythonAvailable as aC, isPythonAvailable as aD, makeCred as aE, octalMode as aF, parseUmask as aG, resetPidCounter as aH, shellQuote as aI, type RuntimeProcessManager as aa, type RuntimeProcessResult as ab, type SessionInit as ac, type SessionResult as ad, type SessionRunOptions as ae, ShellExit as af, type ShellInit as ag, type ShellOptions as ah, type SpawnHandle as ai, Stats as aj, type Stdio as ak, TeeOutput as al, UserDatabase as am, Variables as an, type VirtualNode as ao, type VirtualProvider as ap, type WriteOptions as aq, applyChmod as ar, braceExpand as as, captureStdio as at, configureCPython as au, configurePython as av, createChildProcessModule as aw, createContext as ax, defineCommand as ay, expandWord as az, Session as b, type Cred as c, type Command as d, type VolumeStat as e, type VolumeStats as f, type RuntimeHttpResponse as g, type SpawnChild as h, type SyncSpawn as i, type RuntimePod as j, type RuntimePackageInstaller as k, type ChildSpawnConfig as l, type ChildHandle as m, type RuntimeProcess as n, type RuntimeSocketPeer as o, type RuntimeConnection as p, createContainer as q, type CPythonOptions as r, CallbackSink as s, CommandRegistry as t, ContainerFs as u, type ContainerOptions as v, type ContextInit as w, type Env as x, type ExecOptions as y, type ExecResult as z };

package/dist/index.cjs CHANGED Viewed

@@ -23489,8 +23489,17 @@ var VirtualIncomingMessage = class extends streamModule4__default.default.Readab
   httpVersionMajor = 1;
   httpVersionMinor = 1;
   complete = true;
+  /*
+   * Mutable, and `connection` a getter over it, because an upgraded request
+   * carries a real socket rather than the stub. `emit("upgrade", req, socket)`
+   * hands the same object to both places, and a library that reaches it as
+   * `req.socket` — rather than through the argument — has to find the one it
+   * can actually write to.
+   */
   socket = socketStub();
-  connection = this.socket;
+  get connection() {
+    return this.socket;
+  }
   constructor(init) {
     super();
     this.method = (init.method ?? "GET").toUpperCase();
@@ -23596,6 +23605,80 @@ var VirtualServerResponse = class extends streamModule4__default.default.Writabl
     return this;
   }
 };
+var VirtualSocket = class extends streamModule4__default.default.Duplex {
+  remoteAddress = "127.0.0.1";
+  remotePort = 0;
+  localAddress = "127.0.0.1";
+  localPort = 0;
+  encrypted = false;
+  bufferSize = 0;
+  peer;
+  /** Set once the peer is told, so `end()` then `destroy()` reports once. */
+  hungUp = false;
+  constructor(peer) {
+    super({ allowHalfOpen: false });
+    this.peer = peer;
+  }
+  _read() {
+  }
+  _write(chunk, encoding, callback) {
+    const bytes2 = Buffer2.isBuffer(chunk) ? chunk : Buffer2.from(chunk, encoding);
+    try {
+      this.peer?.data(new Uint8Array(bytes2));
+      callback();
+    } catch (error) {
+      callback(error);
+    }
+  }
+  _final(callback) {
+    this.hangUp();
+    callback();
+  }
+  _destroy(error, callback) {
+    this.hangUp();
+    callback(error);
+  }
+  hangUp() {
+    if (this.hungUp) return;
+    this.hungUp = true;
+    try {
+      this.peer?.close();
+    } catch {
+    }
+    this.peer = null;
+  }
+  /** Bytes arriving from the far end. */
+  deliver(bytes2) {
+    if (this.destroyed || this.hungUp) return;
+    this.push(Buffer2.from(bytes2));
+  }
+  /** The far end went away; let the server's stream end cleanly. */
+  peerClosed() {
+    if (this.destroyed) return;
+    this.push(null);
+  }
+  /* The parts of `net.Socket` a WebSocket library reaches for. None of them
+   * mean anything without a kernel, but every one of them is called. */
+  setNoDelay() {
+    return this;
+  }
+  setKeepAlive() {
+    return this;
+  }
+  setTimeout(_milliseconds, callback) {
+    if (callback) this.once("timeout", callback);
+    return this;
+  }
+  destroySoon() {
+    this.end();
+  }
+  ref() {
+    return this;
+  }
+  unref() {
+    return this;
+  }
+};
 var VirtualHttpServer = class extends EventEmitter4__default.default {
   constructor(router, owner, listener) {
     super();
@@ -23695,6 +23778,33 @@ var VirtualHttpRouter = class {
       return { statusCode: 500, statusMessage: "Internal Server Error", headers: {}, body: error instanceof Error ? error.message : String(error) };
     }
   }
+  /**
+   * Open a connection that leaves HTTP behind — a WebSocket, in practice.
+   *
+   * The counterpart to {@link request}, and the thing whose absence made a dev
+   * server look broken. Every Node WebSocket library is built the same way: it
+   * hands `http.Server` an `upgrade` listener and waits. Nothing here ever
+   * emitted one, so `ws` sat holding a server that could not receive a single
+   * connection, and Vite lost the channel it uses to tell a page to reload —
+   * which is the only way it can recover after re-optimizing dependencies.
+   *
+   * Null means there is nothing to connect to: no server on the port, or a
+   * server that never asked for upgrades. Both are refusals the caller should
+   * report rather than wait out.
+   */
+  connect(port, init, peer) {
+    const item = this.servers.get(port);
+    if (!item) return null;
+    if (item.server.listenerCount("upgrade") === 0) return null;
+    const request = new VirtualIncomingMessage(init);
+    const socket = new VirtualSocket(peer);
+    request.socket = socket;
+    item.server.emit("upgrade", request, socket, Buffer2.alloc(0));
+    return {
+      send: (bytes2) => socket.deliver(bytes2),
+      close: () => socket.peerClosed()
+    };
+  }
 };
 var VirtualClientResponse = class extends streamModule4__default.default.Readable {
   constructor(statusCode, statusMessage, headers, body) {
@@ -27211,6 +27321,9 @@ var LocalRuntimePod = class _LocalRuntimePod {
   async request(_port, _init = {}) {
     return this.router.request(_port, _init);
   }
+  connect(port, init, peer) {
+    return this.router.connect(port, init, peer);
+  }
   snapshot() {
     this.assertActive();
     return this.volume.snapshot();
@@ -27646,6 +27759,15 @@ var WorkerRuntimePod = class _WorkerRuntimePod extends LocalRuntimePod {
         case "http-response":
           this.settleProxied(Number(message.id), message.response);
           return;
+        case "ws-data":
+          this.upgraded.get(Number(message.id))?.write(new Uint8Array(message.data));
+          return;
+        case "ws-close": {
+          const socket = this.upgraded.get(Number(message.id));
+          this.upgraded.delete(Number(message.id));
+          socket?.end();
+          return;
+        }
         case "child-start":
           this.startChild(worker, children, message, ownedChildren);
           return;
@@ -27734,6 +27856,8 @@ var WorkerRuntimePod = class _WorkerRuntimePod extends LocalRuntimePod {
   // ── HTTP servers living on another thread ─────────────────────────────────
   proxies = /* @__PURE__ */ new Map();
   waiting = /* @__PURE__ */ new Map();
+  /** Upgraded connections, by the id the Worker knows them as. */
+  upgraded = /* @__PURE__ */ new Map();
   nextRequestId = 1;
   /**
    * Register a stand-in for a server that is actually running in the Worker.
@@ -27746,6 +27870,9 @@ var WorkerRuntimePod = class _WorkerRuntimePod extends LocalRuntimePod {
     const server = new VirtualHttpServer(this.router, owner, (request, response) => {
       void this.forward(worker, port, request, response);
     });
+    server.on("upgrade", (request, socket) => {
+      this.upgrade(worker, port, request, socket);
+    });
     try {
       server.listen(port);
       this.proxies.set(port, server);
@@ -27776,6 +27903,33 @@ var WorkerRuntimePod = class _WorkerRuntimePod extends LocalRuntimePod {
     response.writeHead(Number(result.statusCode ?? 200), String(result.statusMessage ?? ""), result.headers ?? {});
     response.end(result.body ?? new Uint8Array());
   }
+  /**
+   * Tunnel one upgraded connection to the server that actually holds the port.
+   *
+   * Unlike {@link forward} there is no reply to wait for: both ends write
+   * whenever they have something, until one of them stops. The id is what ties
+   * the two directions together across the Worker boundary.
+   */
+  upgrade(worker, port, request, socket) {
+    const id = this.nextRequestId++;
+    this.upgraded.set(id, socket);
+    socket.on("data", (chunk) => {
+      const bytes2 = new Uint8Array(chunk);
+      worker.postMessage({ type: "ws-data", id, data: bytes2 });
+    });
+    const drop = () => {
+      if (!this.upgraded.delete(id)) return;
+      worker.postMessage({ type: "ws-close", id });
+    };
+    socket.on("close", drop);
+    socket.on("error", drop);
+    worker.postMessage({
+      type: "ws-open",
+      id,
+      port,
+      init: { method: request.method, path: request.url, headers: request.headers }
+    });
+  }
   settleProxied(id, response) {
     const resolve2 = this.waiting.get(id);
     if (!resolve2) return;
@@ -27788,6 +27942,10 @@ var WorkerRuntimePod = class _WorkerRuntimePod extends LocalRuntimePod {
       server.close();
       this.proxies.delete(port);
     }
+    for (const [id, socket] of [...this.upgraded]) {
+      this.upgraded.delete(id);
+      socket.destroy();
+    }
   }
   teardown() {
     for (const { worker, server } of [...this.live]) {
@@ -28161,6 +28319,29 @@ var Container = class _Container {
       }
     };
   }
+  /**
+   * Open a connection to a server inside the container that upgrades out of
+   * HTTP — in practice, a WebSocket.
+   *
+   * The counterpart to {@link request}, and the thing a dev server needs that
+   * a request cannot provide. Bytes go in with `send`, come back through
+   * `peer.data`, and neither side interprets them: the container runs whatever
+   * WebSocket library the program chose, and the caller is responsible for
+   * speaking the protocol it answers with.
+   *
+   * Null means there is nothing to talk to — no server on the port, or one
+   * that never registered an `upgrade` handler. Both are worth reporting
+   * rather than waiting out, because neither resolves on its own.
+   */
+  connect(port, init = {}, peer) {
+    this.assertActive();
+    if (!this.pod.connect) return null;
+    return this.pod.connect(
+      port,
+      { method: init.method ?? "GET", path: init.path ?? "/", headers: init.headers ?? {} },
+      peer
+    );
+  }
   /**
    * Deliver a request whose body is bytes, without letting them become text.
    *
@@ -28732,6 +28913,12 @@ init_arith();
 init_expand();
 init_builtins();
+// src/preview/ws-client.ts
+var WS_OPEN = "sandboxedjs:ws-open";
+var WS_DATA = "sandboxedjs:ws-data";
+var WS_CLOSE = "sandboxedjs:ws-close";
+var WS_ERROR = "sandboxedjs:ws-error";
 // src/preview/register.ts
 function serveContainerOn(port, box) {
   port.onmessage = async (event) => {
@@ -28817,7 +29004,7 @@ async function createPreview(box, options = {}) {
     channel = new MessageChannel();
     serveContainerOn(channel.port1, box);
     const target = registration.active ?? worker;
-    target.postMessage({ type: "sandboxedjs:connect" }, [channel.port2]);
+    target.postMessage({ type: "sandboxedjs:connect", injectSockets: options.websocket !== false }, [channel.port2]);
   };
   const onWorkerMessage = (event) => {
     const type = event.data?.type;
@@ -28826,6 +29013,56 @@ async function createPreview(box, options = {}) {
   };
   navigator.serviceWorker.addEventListener("message", onWorkerMessage);
   connect();
+  const sockets = /* @__PURE__ */ new Map();
+  const onFrameMessage = (event) => {
+    if (event.origin !== location.origin || !event.source) return;
+    const data = event.data;
+    if (!data || typeof data !== "object") return;
+    if (data.type !== WS_OPEN && data.type !== WS_DATA && data.type !== WS_CLOSE) return;
+    const source = event.source;
+    const id = Number(data.id);
+    const reply = (message, transfer = []) => source.postMessage(message, location.origin, transfer);
+    if (data.type === WS_OPEN) {
+      let table2 = sockets.get(source);
+      if (!table2) sockets.set(source, table2 = /* @__PURE__ */ new Map());
+      let opened = null;
+      try {
+        opened = box.connect(
+          Number(data.port),
+          { method: "GET", path: data.path ?? "/", headers: data.headers ?? {} },
+          {
+            data: (bytes2) => {
+              const carrier = bytes2.slice().buffer;
+              reply({ type: WS_DATA, id, data: carrier }, [carrier]);
+            },
+            close: () => {
+              table2.delete(id);
+              reply({ type: WS_CLOSE, id });
+            }
+          }
+        );
+      } catch (error) {
+        opened = null;
+        reply({ type: WS_ERROR, id, message: error instanceof Error ? error.message : String(error) });
+        return;
+      }
+      if (!opened) {
+        reply({ type: WS_ERROR, id, message: `Nothing is accepting WebSocket connections on port ${data.port}.` });
+        return;
+      }
+      table2.set(id, opened);
+      return;
+    }
+    const table = sockets.get(source);
+    const socket = table?.get(id);
+    if (!socket) return;
+    if (data.type === WS_DATA) socket.send(new Uint8Array(data.data));
+    else {
+      socket.close();
+      table.delete(id);
+    }
+  };
+  if (typeof window !== "undefined") window.addEventListener("message", onFrameMessage);
   const base2 = registration.scope.replace(/\/$/, "");
   const urlFor = (port) => `${base2}/__sbx__/${port}/`;
   return {
@@ -28839,6 +29076,9 @@ async function createPreview(box, options = {}) {
     },
     dispose: async () => {
       navigator.serviceWorker.removeEventListener("message", onWorkerMessage);
+      if (typeof window !== "undefined") window.removeEventListener("message", onFrameMessage);
+      for (const table of sockets.values()) for (const socket of table.values()) socket.close();
+      sockets.clear();
       channel?.port1.close();
       channel = null;
       await registration.unregister();