@statewalker/webrun-streams-ws 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022-2026 statewalker
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,24 @@
+# @statewalker/webrun-streams-ws
+
+WebSocket-backed `Connect` / `Serve` adapter in the `webrun-streams-*` family. Each `WebSocket` is one byte channel; `emulateMux` provides the multi-stream layer on top.
+
+```ts
+import { connect, serve } from "@statewalker/webrun-streams-ws";
+import { WebSocket as NodeWebSocket, WebSocketServer } from "ws";
+
+const wss = new WebSocketServer({ port: 8080 });
+const stop = await serve(
+  { onConnection: (cb) => { wss.on("connection", cb); return () => wss.off("connection", cb); } },
+  async function* (input) { for await (const c of input) yield c; },
+);
+
+const { call } = await connect({ url: "ws://localhost:8080", WebSocketCtor: NodeWebSocket });
+```
+
+## Conformance
+
+Passes every level of `@statewalker/webrun-streams-conformance` against an in-process `WebSocketServer`.
+
+## License
+
+MIT

package/dist/byte-channel.d.ts

@@ -0,0 +1,12 @@
+import { type ByteChannel } from "@statewalker/webrun-streams";
+import { type WebSocketLike } from "./websocket-like.js";
+/**
+ * Wrap an open `WebSocket` (or any `WebSocketLike` — Node `ws` works) into a
+ * `ByteChannel` consumable by `emulateMux`. The socket MUST already be in the
+ * `OPEN` state; the adapter does not perform handshakes.
+ *
+ * Inbound binary frames are normalised to `Uint8Array`. Text frames are also
+ * accepted (rare on this transport) and surfaced as their UTF-8 bytes.
+ */
+export declare function byteChannelFromWebSocket(ws: WebSocketLike): ByteChannel;
+//# sourceMappingURL=byte-channel.d.ts.map

package/dist/byte-channel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"byte-channel.d.ts","sourceRoot":"","sources":["../src/byte-channel.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,WAAW,EAAyB,MAAM,6BAA6B,CAAC;AACtF,OAAO,EAAE,KAAK,aAAa,EAAkB,MAAM,qBAAqB,CAAC;AAEzE;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CAAC,EAAE,EAAE,aAAa,GAAG,WAAW,CA8GvE"}

package/dist/connect.d.ts

@@ -0,0 +1,20 @@
+import { type Connect } from "@statewalker/webrun-streams";
+import { type WebSocketLike } from "./websocket-like.js";
+export interface ConnectWsParams {
+    /** WebSocket URL (`ws://` or `wss://`). */
+    url: string;
+    /** Optional subprotocol(s) passed to the WebSocket constructor. */
+    protocols?: string | string[];
+    /**
+     * WebSocket constructor. Defaults to the global `WebSocket` when present
+     * (browser); pass Node's `ws` package's `WebSocket` in Node.
+     */
+    WebSocketCtor?: new (url: string, protocols?: string | string[]) => WebSocketLike;
+}
+/**
+ * Open a WebSocket to `params.url`, wrap it as a `ByteChannel`, and run it
+ * through `emulateMux`. Returns `{ call, close }` where `call` is the
+ * caller-side `Duplex`.
+ */
+export declare const connect: Connect<ConnectWsParams>;
+//# sourceMappingURL=connect.d.ts.map

package/dist/connect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connect.d.ts","sourceRoot":"","sources":["../src/connect.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,OAAO,EAAc,MAAM,6BAA6B,CAAC;AAEvE,OAAO,EAAE,KAAK,aAAa,EAAkB,MAAM,qBAAqB,CAAC;AAEzE,MAAM,WAAW,eAAe;IAC9B,2CAA2C;IAC3C,GAAG,EAAE,MAAM,CAAC;IACZ,mEAAmE;IACnE,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC9B;;;OAGG;IACH,aAAa,CAAC,EAAE,KACd,GAAG,EAAE,MAAM,EACX,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,KAC1B,aAAa,CAAC;CACpB;AAED;;;;GAIG;AACH,eAAO,MAAM,OAAO,EAAE,OAAO,CAAC,eAAe,CAiB5C,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { byteChannelFromWebSocket } from "./byte-channel.js";
+export { type ConnectWsParams, connect } from "./connect.js";
+export { type ServeWsParams, serve } from "./serve.js";
+export { type WebSocketLike, WS_READY_STATE } from "./websocket-like.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAC;AAC7D,OAAO,EAAE,KAAK,eAAe,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC7D,OAAO,EAAE,KAAK,aAAa,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACvD,OAAO,EAAE,KAAK,aAAa,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/index.js

@@ -0,0 +1,181 @@
+import { emulateMux, normalizeToUint8Array } from "@statewalker/webrun-streams";
+//#region src/websocket-like.ts
+const WS_READY_STATE = {
+	CONNECTING: 0,
+	OPEN: 1,
+	CLOSING: 2,
+	CLOSED: 3
+};
+//#endregion
+//#region src/byte-channel.ts
+/**
+* Wrap an open `WebSocket` (or any `WebSocketLike` — Node `ws` works) into a
+* `ByteChannel` consumable by `emulateMux`. The socket MUST already be in the
+* `OPEN` state; the adapter does not perform handshakes.
+*
+* Inbound binary frames are normalised to `Uint8Array`. Text frames are also
+* accepted (rare on this transport) and surfaced as their UTF-8 bytes.
+*/
+function byteChannelFromWebSocket(ws) {
+	if (ws.readyState !== WS_READY_STATE.OPEN) throw new Error(`byteChannelFromWebSocket: WebSocket is in readyState ${ws.readyState}, expected OPEN (1)`);
+	let closedResolve;
+	const closed = new Promise((r) => {
+		closedResolve = r;
+	});
+	let isClosed = false;
+	const queue = [];
+	let pending = null;
+	const onMessage = (event) => {
+		if (isClosed) return;
+		const data = event.data;
+		let normalised;
+		if (data instanceof Uint8Array) normalised = data;
+		else if (data instanceof ArrayBuffer) normalised = new Uint8Array(data);
+		else if (ArrayBuffer.isView(data)) {
+			const view = data;
+			normalised = new Uint8Array(view.buffer, view.byteOffset, view.byteLength);
+		} else if (typeof Blob !== "undefined" && data instanceof Blob) {
+			data.arrayBuffer().then((buf) => deliver(new Uint8Array(buf)));
+			return;
+		} else if (typeof data === "string") {
+			const n = normalizeToUint8Array(data);
+			if (n instanceof Uint8Array) normalised = n;
+			else {
+				n.then(deliver);
+				return;
+			}
+		} else return;
+		deliver(normalised);
+	};
+	const deliver = (bytes) => {
+		if (isClosed) return;
+		if (pending) {
+			const r = pending;
+			pending = null;
+			r({
+				value: bytes,
+				done: false
+			});
+		} else queue.push(bytes);
+	};
+	const onClose = () => {
+		if (isClosed) return;
+		isClosed = true;
+		ws.removeEventListener("message", onMessage);
+		ws.removeEventListener("close", onClose);
+		if (pending) {
+			const r = pending;
+			pending = null;
+			r({
+				value: void 0,
+				done: true
+			});
+		}
+		closedResolve();
+	};
+	ws.addEventListener("message", onMessage);
+	ws.addEventListener("close", onClose);
+	return {
+		send(bytes) {
+			if (isClosed) return;
+			if (ws.readyState !== WS_READY_STATE.OPEN) return;
+			ws.send(bytes);
+		},
+		recv: { [Symbol.asyncIterator]() {
+			return { next() {
+				if (queue.length > 0) return Promise.resolve({
+					value: queue.shift(),
+					done: false
+				});
+				if (isClosed) return Promise.resolve({
+					value: void 0,
+					done: true
+				});
+				return new Promise((resolve) => {
+					pending = resolve;
+				});
+			} };
+		} },
+		closed,
+		close() {
+			if (isClosed) return;
+			try {
+				ws.close();
+			} catch {}
+			onClose();
+		}
+	};
+}
+//#endregion
+//#region src/connect.ts
+/**
+* Open a WebSocket to `params.url`, wrap it as a `ByteChannel`, and run it
+* through `emulateMux`. Returns `{ call, close }` where `call` is the
+* caller-side `Duplex`.
+*/
+const connect = async (params) => {
+	const Ctor = params.WebSocketCtor ?? globalThis.WebSocket;
+	if (!Ctor) throw new Error("webrun-streams-ws connect: no WebSocket constructor available. Pass `params.WebSocketCtor` (e.g. the `ws` package's WebSocket in Node).");
+	const ws = new Ctor(params.url, params.protocols);
+	await waitForOpen(ws);
+	const channel = byteChannelFromWebSocket(ws);
+	const mux = emulateMux(channel, { side: "initiator" });
+	return {
+		call: mux.call,
+		async close() {
+			await mux.close();
+		}
+	};
+};
+function waitForOpen(ws) {
+	if (ws.readyState === WS_READY_STATE.OPEN) return Promise.resolve();
+	return new Promise((resolve, reject) => {
+		const cleanup = () => {
+			ws.removeEventListener("open", onOpen);
+			ws.removeEventListener("error", onError);
+			ws.removeEventListener("close", onCloseEarly);
+		};
+		const onOpen = () => {
+			cleanup();
+			resolve();
+		};
+		const onError = () => {
+			cleanup();
+			reject(/* @__PURE__ */ new Error("WebSocket error before open"));
+		};
+		const onCloseEarly = () => {
+			cleanup();
+			reject(/* @__PURE__ */ new Error("WebSocket closed before it opened"));
+		};
+		ws.addEventListener("open", onOpen);
+		ws.addEventListener("error", onError);
+		ws.addEventListener("close", onCloseEarly);
+	});
+}
+//#endregion
+//#region src/serve.ts
+/**
+* Register a `Duplex` handler against an inbound-WebSocket source. The
+* `onConnection` callback is invoked once per accepted connection; the
+* adapter wraps each in `emulateMux` and binds the handler.
+*
+* Returns an idempotent teardown that unregisters the connection listener.
+* Open `emulateMux` instances continue running until their underlying
+* WebSocket closes.
+*/
+async function serve(params, handler) {
+	const off = params.onConnection((ws) => {
+		const channel = byteChannelFromWebSocket(ws);
+		const mux = emulateMux(channel, { side: "responder" });
+		mux.serve(handler);
+		channel.closed.then(() => mux.close());
+	});
+	let torn = false;
+	return async () => {
+		if (torn) return;
+		torn = true;
+		off();
+	};
+}
+//#endregion
+export { WS_READY_STATE, byteChannelFromWebSocket, connect, serve };

package/dist/serve.d.ts

@@ -0,0 +1,21 @@
+import { type Duplex } from "@statewalker/webrun-streams";
+import type { WebSocketLike } from "./websocket-like.js";
+export interface ServeWsParams {
+    /**
+     * Source of inbound WebSocket connections. Either a `wss` instance with a
+     * `connection` event, or a manual handler the caller wires to its own
+     * server.
+     */
+    onConnection: (cb: (ws: WebSocketLike) => void) => () => void;
+}
+/**
+ * Register a `Duplex` handler against an inbound-WebSocket source. The
+ * `onConnection` callback is invoked once per accepted connection; the
+ * adapter wraps each in `emulateMux` and binds the handler.
+ *
+ * Returns an idempotent teardown that unregisters the connection listener.
+ * Open `emulateMux` instances continue running until their underlying
+ * WebSocket closes.
+ */
+export declare function serve(params: ServeWsParams, handler: Duplex): Promise<() => Promise<void>>;
+//# sourceMappingURL=serve.d.ts.map

package/dist/serve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serve.d.ts","sourceRoot":"","sources":["../src/serve.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,MAAM,EAAc,MAAM,6BAA6B,CAAC;AAEtE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,YAAY,EAAE,CAAC,EAAE,EAAE,CAAC,EAAE,EAAE,aAAa,KAAK,IAAI,KAAK,MAAM,IAAI,CAAC;CAC/D;AAED;;;;;;;;GAQG;AACH,wBAAsB,KAAK,CAAC,MAAM,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,CAahG"}

package/dist/websocket-like.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Structural subset of the WHATWG `WebSocket` interface that also matches the
+ * Node.js `ws` package. Anything that implements this surface works with the
+ * helpers in this package.
+ */
+export interface WebSocketLike {
+    readonly readyState: number;
+    send(data: string | ArrayBuffer | Blob | Uint8Array): void;
+    close(): void;
+    addEventListener(type: "message", listener: (event: MessageEvent) => void): void;
+    addEventListener(type: "open", listener: () => void): void;
+    addEventListener(type: "close", listener: () => void): void;
+    addEventListener(type: "error", listener: () => void): void;
+    removeEventListener(type: "message", listener: (event: MessageEvent) => void): void;
+    removeEventListener(type: "open", listener: () => void): void;
+    removeEventListener(type: "close", listener: () => void): void;
+    removeEventListener(type: "error", listener: () => void): void;
+}
+export declare const WS_READY_STATE: {
+    readonly CONNECTING: 0;
+    readonly OPEN: 1;
+    readonly CLOSING: 2;
+    readonly CLOSED: 3;
+};
+//# sourceMappingURL=websocket-like.d.ts.map

package/dist/websocket-like.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"websocket-like.d.ts","sourceRoot":"","sources":["../src/websocket-like.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,GAAG,UAAU,GAAG,IAAI,CAAC;IAC3D,KAAK,IAAI,IAAI,CAAC;IACd,gBAAgB,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,GAAG,IAAI,CAAC;IACjF,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IAC3D,gBAAgB,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IAC5D,gBAAgB,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IAC5D,mBAAmB,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,GAAG,IAAI,CAAC;IACpF,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IAC9D,mBAAmB,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IAC/D,mBAAmB,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;CAChE;AAED,eAAO,MAAM,cAAc;aACzB,UAAU,EAAE,CAAC;aACb,IAAI,EAAE,CAAC;aACP,OAAO,EAAE,CAAC;aACV,MAAM,EAAE,CAAC;CACD,CAAC"}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@statewalker/webrun-streams-ws",
+  "version": "0.1.1",
+  "private": false,
+  "type": "module",
+  "description": "WebSocket-backed Connect/Serve adapter in the webrun-streams-* family",
+  "homepage": "https://github.com/statewalker/webrun-wire",
+  "author": {
+    "name": "Mikhail Kotelnikov",
+    "email": "mikhail.kotelnikov@gmail.com"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git@github.com:statewalker/webrun-wire.git"
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "@statewalker/webrun-streams": "0.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^26.2.0",
+    "@types/ws": "^8.5.13",
+    "rimraf": "^6.1.3",
+    "rolldown": "^1.2.4",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10",
+    "ws": "^8.18.0",
+    "@statewalker/webrun-streams-conformance": "0.1.1"
+  },
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rimraf dist && rolldown -c && tsc --emitDeclarationOnly --declaration",
+    "test": "vitest run",
+    "lint": "biome check src tests"
+  }
+}

package/src/byte-channel.ts

@@ -0,0 +1,122 @@
+import { type ByteChannel, normalizeToUint8Array } from "@statewalker/webrun-streams";
+import { type WebSocketLike, WS_READY_STATE } from "./websocket-like.js";
+
+/**
+ * Wrap an open `WebSocket` (or any `WebSocketLike` — Node `ws` works) into a
+ * `ByteChannel` consumable by `emulateMux`. The socket MUST already be in the
+ * `OPEN` state; the adapter does not perform handshakes.
+ *
+ * Inbound binary frames are normalised to `Uint8Array`. Text frames are also
+ * accepted (rare on this transport) and surfaced as their UTF-8 bytes.
+ */
+export function byteChannelFromWebSocket(ws: WebSocketLike): ByteChannel {
+  if (ws.readyState !== WS_READY_STATE.OPEN) {
+    throw new Error(
+      `byteChannelFromWebSocket: WebSocket is in readyState ${ws.readyState}, expected OPEN (1)`,
+    );
+  }
+
+  let closedResolve!: () => void;
+  const closed = new Promise<void>((r) => {
+    closedResolve = r;
+  });
+  let isClosed = false;
+
+  // Inbound: queue of received chunks + pending next() resolver
+  const queue: Uint8Array[] = [];
+  let pending: ((value: IteratorResult<Uint8Array>) => void) | null = null;
+
+  const onMessage = (event: MessageEvent): void => {
+    if (isClosed) return;
+    const data = event.data as unknown;
+    let normalised: Uint8Array;
+    if (data instanceof Uint8Array) {
+      normalised = data;
+    } else if (data instanceof ArrayBuffer) {
+      normalised = new Uint8Array(data);
+    } else if (ArrayBuffer.isView(data)) {
+      const view = data as ArrayBufferView;
+      normalised = new Uint8Array(view.buffer, view.byteOffset, view.byteLength);
+    } else if (typeof Blob !== "undefined" && data instanceof Blob) {
+      void data.arrayBuffer().then((buf) => deliver(new Uint8Array(buf)));
+      return;
+    } else if (typeof data === "string") {
+      const n = normalizeToUint8Array(data);
+      if (n instanceof Uint8Array) normalised = n;
+      else {
+        void n.then(deliver);
+        return;
+      }
+    } else {
+      return;
+    }
+    deliver(normalised);
+  };
+
+  const deliver = (bytes: Uint8Array): void => {
+    if (isClosed) return;
+    if (pending) {
+      const r = pending;
+      pending = null;
+      r({ value: bytes, done: false });
+    } else {
+      queue.push(bytes);
+    }
+  };
+
+  const onClose = (): void => {
+    if (isClosed) return;
+    isClosed = true;
+    ws.removeEventListener("message", onMessage);
+    ws.removeEventListener("close", onClose);
+    if (pending) {
+      const r = pending;
+      pending = null;
+      r({ value: undefined, done: true } as IteratorResult<Uint8Array>);
+    }
+    closedResolve();
+  };
+
+  ws.addEventListener("message", onMessage);
+  ws.addEventListener("close", onClose);
+
+  const recv: AsyncIterable<Uint8Array> = {
+    [Symbol.asyncIterator]() {
+      return {
+        next(): Promise<IteratorResult<Uint8Array>> {
+          if (queue.length > 0) {
+            return Promise.resolve({ value: queue.shift() as Uint8Array, done: false });
+          }
+          if (isClosed) {
+            return Promise.resolve({
+              value: undefined,
+              done: true,
+            } as IteratorResult<Uint8Array>);
+          }
+          return new Promise<IteratorResult<Uint8Array>>((resolve) => {
+            pending = resolve;
+          });
+        },
+      };
+    },
+  };
+
+  return {
+    send(bytes) {
+      if (isClosed) return;
+      if (ws.readyState !== WS_READY_STATE.OPEN) return;
+      ws.send(bytes);
+    },
+    recv,
+    closed,
+    close() {
+      if (isClosed) return;
+      try {
+        ws.close();
+      } catch {
+        /* ignore */
+      }
+      onClose();
+    },
+  };
+}

package/src/connect.ts

@@ -0,0 +1,68 @@
+import { type Connect, emulateMux } from "@statewalker/webrun-streams";
+import { byteChannelFromWebSocket } from "./byte-channel.js";
+import { type WebSocketLike, WS_READY_STATE } from "./websocket-like.js";
+
+export interface ConnectWsParams {
+  /** WebSocket URL (`ws://` or `wss://`). */
+  url: string;
+  /** Optional subprotocol(s) passed to the WebSocket constructor. */
+  protocols?: string | string[];
+  /**
+   * WebSocket constructor. Defaults to the global `WebSocket` when present
+   * (browser); pass Node's `ws` package's `WebSocket` in Node.
+   */
+  WebSocketCtor?: new (
+    url: string,
+    protocols?: string | string[],
+  ) => WebSocketLike;
+}
+
+/**
+ * Open a WebSocket to `params.url`, wrap it as a `ByteChannel`, and run it
+ * through `emulateMux`. Returns `{ call, close }` where `call` is the
+ * caller-side `Duplex`.
+ */
+export const connect: Connect<ConnectWsParams> = async (params) => {
+  const Ctor = params.WebSocketCtor ?? (globalThis as { WebSocket?: typeof WebSocket }).WebSocket;
+  if (!Ctor) {
+    throw new Error(
+      "webrun-streams-ws connect: no WebSocket constructor available. Pass `params.WebSocketCtor` (e.g. the `ws` package's WebSocket in Node).",
+    );
+  }
+  const ws = new Ctor(params.url, params.protocols) as WebSocketLike;
+  await waitForOpen(ws);
+  const channel = byteChannelFromWebSocket(ws);
+  const mux = emulateMux(channel, { side: "initiator" });
+  return {
+    call: mux.call,
+    async close() {
+      await mux.close();
+    },
+  };
+};
+
+function waitForOpen(ws: WebSocketLike): Promise<void> {
+  if (ws.readyState === WS_READY_STATE.OPEN) return Promise.resolve();
+  return new Promise<void>((resolve, reject) => {
+    const cleanup = (): void => {
+      ws.removeEventListener("open", onOpen);
+      ws.removeEventListener("error", onError);
+      ws.removeEventListener("close", onCloseEarly);
+    };
+    const onOpen = (): void => {
+      cleanup();
+      resolve();
+    };
+    const onError = (): void => {
+      cleanup();
+      reject(new Error("WebSocket error before open"));
+    };
+    const onCloseEarly = (): void => {
+      cleanup();
+      reject(new Error("WebSocket closed before it opened"));
+    };
+    ws.addEventListener("open", onOpen);
+    ws.addEventListener("error", onError);
+    ws.addEventListener("close", onCloseEarly);
+  });
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export { byteChannelFromWebSocket } from "./byte-channel.js";
+export { type ConnectWsParams, connect } from "./connect.js";
+export { type ServeWsParams, serve } from "./serve.js";
+export { type WebSocketLike, WS_READY_STATE } from "./websocket-like.js";

package/src/serve.ts

@@ -0,0 +1,36 @@
+import { type Duplex, emulateMux } from "@statewalker/webrun-streams";
+import { byteChannelFromWebSocket } from "./byte-channel.js";
+import type { WebSocketLike } from "./websocket-like.js";
+
+export interface ServeWsParams {
+  /**
+   * Source of inbound WebSocket connections. Either a `wss` instance with a
+   * `connection` event, or a manual handler the caller wires to its own
+   * server.
+   */
+  onConnection: (cb: (ws: WebSocketLike) => void) => () => void;
+}
+
+/**
+ * Register a `Duplex` handler against an inbound-WebSocket source. The
+ * `onConnection` callback is invoked once per accepted connection; the
+ * adapter wraps each in `emulateMux` and binds the handler.
+ *
+ * Returns an idempotent teardown that unregisters the connection listener.
+ * Open `emulateMux` instances continue running until their underlying
+ * WebSocket closes.
+ */
+export async function serve(params: ServeWsParams, handler: Duplex): Promise<() => Promise<void>> {
+  const off = params.onConnection((ws) => {
+    const channel = byteChannelFromWebSocket(ws);
+    const mux = emulateMux(channel, { side: "responder" });
+    mux.serve(handler);
+    void channel.closed.then(() => mux.close());
+  });
+  let torn = false;
+  return async () => {
+    if (torn) return;
+    torn = true;
+    off();
+  };
+}

package/src/websocket-like.ts

@@ -0,0 +1,25 @@
+/**
+ * Structural subset of the WHATWG `WebSocket` interface that also matches the
+ * Node.js `ws` package. Anything that implements this surface works with the
+ * helpers in this package.
+ */
+export interface WebSocketLike {
+  readonly readyState: number;
+  send(data: string | ArrayBuffer | Blob | Uint8Array): void;
+  close(): void;
+  addEventListener(type: "message", listener: (event: MessageEvent) => void): void;
+  addEventListener(type: "open", listener: () => void): void;
+  addEventListener(type: "close", listener: () => void): void;
+  addEventListener(type: "error", listener: () => void): void;
+  removeEventListener(type: "message", listener: (event: MessageEvent) => void): void;
+  removeEventListener(type: "open", listener: () => void): void;
+  removeEventListener(type: "close", listener: () => void): void;
+  removeEventListener(type: "error", listener: () => void): void;
+}
+
+export const WS_READY_STATE = {
+  CONNECTING: 0,
+  OPEN: 1,
+  CLOSING: 2,
+  CLOSED: 3,
+} as const;