@kyneta/websocket-transport 1.2.0 → 1.3.1

package/dist/{client.d.ts → client-transport-DUAFjVbh.d.ts}

@@ -1,58 +1,6 @@
-import { Program, TransitionListener } from '@kyneta/machine';
-import { ReconnectOptions, PeerId, Transport, GeneratedChannel, TransportFactory } from '@kyneta/transport';
-import { W as WebsocketClientState, b as WebsocketClientStateTransition, D as DisconnectReason } from './types-DdNb8cAz.js';
-export { S as Socket, a as SocketReadyState, T as TransitionListener, w as wrapStandardWebsocket } from './types-DdNb8cAz.js';
-
-type WsClientMsg = {
-    type: "start";
-} | {
-    type: "socket-opened";
-} | {
-    type: "server-ready";
-} | {
-    type: "socket-closed";
-    code: number;
-    reason: string;
-} | {
-    type: "socket-error";
-    error: Error;
-} | {
-    type: "reconnect-timer-fired";
-} | {
-    type: "stop";
-};
-type WsClientEffect = {
-    type: "create-websocket";
-    attempt: number;
-} | {
-    type: "close-websocket";
-} | {
-    type: "add-channel-and-establish";
-} | {
-    type: "remove-channel";
-} | {
-    type: "start-reconnect-timer";
-    delayMs: number;
-} | {
-    type: "cancel-reconnect-timer";
-} | {
-    type: "start-keepalive";
-} | {
-    type: "stop-keepalive";
-};
-interface WsClientProgramOptions {
-    reconnect?: Partial<ReconnectOptions>;
-    /** Inject jitter source for deterministic testing. Default: () => Math.random() * 1000 */
-    jitterFn?: () => number;
-}
-/**
- * Create the websocket client connection lifecycle program — a pure Mealy machine.
- *
- * The returned `Program<WsClientMsg, WebsocketClientState, WsClientEffect>`
- * encodes every state transition and effect as inspectable data. The imperative
- * shell interprets `WsClientEffect` as actual I/O.
- */
-declare function createWsClientProgram(options?: WsClientProgramOptions): Program<WsClientMsg, WebsocketClientState, WsClientEffect>;
+import { TransitionListener } from '@kyneta/machine';
+import { PeerId, Transport, GeneratedChannel, TransportFactory } from '@kyneta/transport';
+import { f as WebsocketClientStateTransition, D as DisconnectReason, c as WebSocketConstructor, W as WebsocketClientState } from './types-D0lbeevu.js';
 
 /**
  * Default fragment threshold in bytes.
@@ -65,8 +13,22 @@ declare const DEFAULT_FRAGMENT_THRESHOLD: number;
 interface WebsocketClientOptions {
     /** Websocket URL to connect to. Can be a string or a function of peerId. */
     url: string | ((peerId: PeerId) => string);
-    /** Optional custom WebSocket implementation (for Node.js or testing). */
-    WebSocket?: typeof globalThis.WebSocket;
+    /**
+     * WebSocket constructor — caller must provide explicitly.
+     *
+     * In browsers, pass the global `WebSocket`. In Node.js, pass `ws`'s
+     * `WebSocket`. In Bun, pass `globalThis.WebSocket`. The transport
+     * never probes `globalThis` on its own.
+     */
+    WebSocket: WebSocketConstructor;
+    /**
+     * Headers to send during Websocket upgrade.
+     * Used for authentication in service-to-service communication.
+     *
+     * Note: Headers are a Bun/Node-specific extension. The browser WebSocket
+     * API does not support custom headers per the WHATWG spec.
+     */
+    headers?: Record<string, string>;
     /** Reconnection options. */
     reconnect?: {
         enabled?: boolean;
@@ -100,20 +62,6 @@ interface WebsocketClientLifecycleEvents {
     /** Called when the server sends the "ready" signal. */
     onReady?: () => void;
 }
-/**
- * Options for service-to-service Websocket connections.
- * Extends WebsocketClientOptions with header support for authentication.
- *
- * Note: Headers are a Bun/Node-specific extension. The browser WebSocket API
- * does not support custom headers per the WHATWG spec.
- */
-interface ServiceWebsocketClientOptions extends WebsocketClientOptions {
-    /**
-     * Headers to send during Websocket upgrade.
-     * Used for authentication in service-to-service communication.
-     */
-    headers?: Record<string, string>;
-}
 /**
  * Websocket client network transport for @kyneta/exchange.
  *
@@ -125,12 +73,12 @@ interface ServiceWebsocketClientOptions extends WebsocketClientOptions {
  * This class is the imperative shell that interprets data effects as I/O.
  *
  * Prefer the factory functions for construction:
- * - `createWebsocketClient()` — browser-to-server
- * - `createServiceWebsocketClient()` — service-to-service (with headers)
+ * - `createWebsocketClient()` — browser-to-server (from `./browser`)
+ * - `createServiceWebsocketClient()` — service-to-service with headers (from `./server`)
  */
 declare class WebsocketClientTransport extends Transport<void> {
     #private;
-    constructor(options: ServiceWebsocketClientOptions);
+    constructor(options: WebsocketClientOptions);
     /**
      * Get the current connection state.
      */
@@ -168,40 +116,17 @@ declare class WebsocketClientTransport extends Transport<void> {
  *
  * @example
  * ```typescript
- * import { createWebsocketClient } from "@kyneta/websocket-transport/client"
+ * import { createWebsocketClient } from "@kyneta/websocket-transport/browser"
  *
  * const exchange = new Exchange({
  *   transports: [createWebsocketClient({
  *     url: "ws://localhost:3000/ws",
+ *     WebSocket,
  *     reconnect: { enabled: true },
  *   })],
  * })
  * ```
  */
 declare function createWebsocketClient(options: WebsocketClientOptions): TransportFactory;
-/**
- * Create a Websocket client transport for service-to-service connections.
- *
- * This factory is for backend environments (Bun, Node.js) where you need
- * to pass authentication headers during the Websocket upgrade.
- *
- * Note: Headers are a Bun/Node-specific extension. The browser WebSocket API
- * does not support custom headers. For browser clients, use
- * `createWebsocketClient()` and authenticate via URL query parameters.
- *
- * @example
- * ```typescript
- * import { createServiceWebsocketClient } from "@kyneta/websocket-transport/client"
- *
- * const exchange = new Exchange({
- *   transports: [createServiceWebsocketClient({
- *     url: "ws://primary-server:3000/ws",
- *     headers: { Authorization: "Bearer token" },
- *     reconnect: { enabled: true },
- *   })],
- * })
- * ```
- */
-declare function createServiceWebsocketClient(options: ServiceWebsocketClientOptions): TransportFactory;
 
-export { DEFAULT_FRAGMENT_THRESHOLD, DisconnectReason, type ServiceWebsocketClientOptions, type WebsocketClientLifecycleEvents, type WebsocketClientOptions, WebsocketClientState, WebsocketClientStateTransition, WebsocketClientTransport, type WsClientEffect, type WsClientMsg, type WsClientProgramOptions, createServiceWebsocketClient, createWebsocketClient, createWsClientProgram };
+export { DEFAULT_FRAGMENT_THRESHOLD as D, type WebsocketClientLifecycleEvents as W, type WebsocketClientOptions as a, WebsocketClientTransport as b, createWebsocketClient as c };

package/dist/server.d.ts

@@ -1,6 +1,8 @@
-import { PeerId, Channel, ChannelMsg, Transport, GeneratedChannel } from '@kyneta/transport';
-import { S as Socket, c as WebsocketConnectionOptions, d as WebsocketConnectionResult } from './types-DdNb8cAz.js';
-export { D as DisconnectReason, N as NodeWebsocketLike, a as SocketReadyState, e as WebsocketConnectionHandle, f as wrapNodeWebsocket, w as wrapStandardWebsocket } from './types-DdNb8cAz.js';
+import { PeerId, Channel, ChannelMsg, Transport, GeneratedChannel, TransportFactory } from '@kyneta/transport';
+import { S as Socket, g as WebsocketConnectionOptions, h as WebsocketConnectionResult } from './types-D0lbeevu.js';
+export { D as DisconnectReason, N as NodeWebsocketLike, R as READY_STATE, a as SocketReadyState, b as WebSocketCloseEvent, c as WebSocketConstructor, d as WebSocketLike, e as WebSocketMessageEvent, i as WebsocketConnectionHandle, w as wrapNodeWebsocket, j as wrapStandardWebsocket } from './types-D0lbeevu.js';
+import { a as WebsocketClientOptions } from './client-transport-DUAFjVbh.js';
+import '@kyneta/machine';
 
 /**
  * Default fragment threshold in bytes.
@@ -158,4 +160,39 @@ declare class WebsocketServerTransport extends Transport<PeerId> {
     get connectionCount(): number;
 }
 
-export { DEFAULT_FRAGMENT_THRESHOLD, Socket, WebsocketConnection, type WebsocketConnectionConfig, WebsocketConnectionOptions, WebsocketConnectionResult, WebsocketServerTransport, type WebsocketServerTransportOptions };
+/**
+ * Options for service-to-service Websocket connections.
+ *
+ * Identical to `WebsocketClientOptions` — the `headers` field is always
+ * available on the base options. This alias exists for API clarity:
+ * importing `ServiceWebsocketClientOptions` from `./server` signals
+ * intent and pairs with `createServiceWebsocketClient`.
+ */
+type ServiceWebsocketClientOptions = WebsocketClientOptions;
+/**
+ * Create a Websocket client transport for service-to-service connections.
+ *
+ * This factory is for backend environments (Bun, Node.js) where you need
+ * to pass authentication headers during the Websocket upgrade.
+ *
+ * Note: Headers are a Bun/Node-specific extension. The browser WebSocket API
+ * does not support custom headers. For browser clients, use
+ * `createWebsocketClient()` and authenticate via URL query parameters.
+ *
+ * @example
+ * ```typescript
+ * import { createServiceWebsocketClient } from "@kyneta/websocket-transport/server"
+ *
+ * const exchange = new Exchange({
+ *   transports: [createServiceWebsocketClient({
+ *     url: "ws://primary-server:3000/ws",
+ *     WebSocket,
+ *     headers: { Authorization: "Bearer token" },
+ *     reconnect: { enabled: true },
+ *   })],
+ * })
+ * ```
+ */
+declare function createServiceWebsocketClient(options: ServiceWebsocketClientOptions): TransportFactory;
+
+export { DEFAULT_FRAGMENT_THRESHOLD, type ServiceWebsocketClientOptions, Socket, WebsocketConnection, type WebsocketConnectionConfig, WebsocketConnectionOptions, WebsocketConnectionResult, WebsocketServerTransport, type WebsocketServerTransportOptions, createServiceWebsocketClient };

package/dist/server.js

@@ -1,7 +1,9 @@
 import {
+  READY_STATE,
+  WebsocketClientTransport,
   wrapNodeWebsocket,
   wrapStandardWebsocket
-} from "./chunk-PSG3LLT5.js";
+} from "./chunk-YZQF5RLV.js";
 
 // src/server-transport.ts
 import { Transport } from "@kyneta/transport";
@@ -294,10 +296,17 @@ var WebsocketServerTransport = class extends Transport {
     return this.#connections.size;
   }
 };
+
+// src/service-client.ts
+function createServiceWebsocketClient(options) {
+  return () => new WebsocketClientTransport(options);
+}
 export {
   DEFAULT_FRAGMENT_THRESHOLD,
+  READY_STATE,
   WebsocketConnection,
   WebsocketServerTransport,
+  createServiceWebsocketClient,
   wrapNodeWebsocket,
   wrapStandardWebsocket
 };

package/dist/server.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/server-transport.ts","../src/connection.ts"],"sourcesContent":["// server-adapter — Websocket server adapter for @kyneta/exchange.\n//\n// Manages Websocket connections from clients, encoding/decoding via the\n// kyneta wire format. Framework-agnostic — works with any Websocket\n// library through the Socket interface.\n//\n// Usage with Bun:\n//   import { WebsocketServerTransport } from \"@kyneta/websocket-network-adapter/server\"\n//   import { createBunWebsocketHandlers } from \"@kyneta/websocket-network-adapter/bun\"\n//\n//   const serverAdapter = new WebsocketServerTransport()\n//   Bun.serve({\n//     websocket: createBunWebsocketHandlers(serverAdapter),\n//     fetch(req, server) { server.upgrade(req); return new Response(\"\", { status: 101 }) },\n//   })\n//\n// Usage with Node.js `ws`:\n//   import { WebsocketServerTransport, wrapNodeWebsocket } from \"@kyneta/websocket-network-adapter/server\"\n//   import { WebSocketServer } from \"ws\"\n//\n//   const serverAdapter = new WebsocketServerTransport()\n//   const wss = new WebSocketServer({ server })\n//   wss.on(\"connection\", (ws) => {\n//     const { start } = serverAdapter.handleConnection({ socket: wrapNodeWebsocket(ws) })\n//     start()\n//   })\n//\n// Ported from @loro-extended/adapter-websocket's WsServerNetworkAdapter with\n// kyneta naming conventions and the kyneta 5-message protocol.\n\nimport type { ChannelMsg, GeneratedChannel, PeerId } from \"@kyneta/transport\"\nimport { Transport } from \"@kyneta/transport\"\nimport {\n  DEFAULT_FRAGMENT_THRESHOLD,\n  WebsocketConnection,\n} from \"./connection.js\"\nimport type {\n  WebsocketConnectionOptions,\n  WebsocketConnectionResult,\n} from \"./types.js\"\n\n// ---------------------------------------------------------------------------\n// Options\n// ---------------------------------------------------------------------------\n\n/**\n * Options for the Websocket server adapter.\n */\nexport interface WebsocketServerTransportOptions {\n  /**\n   * Fragment threshold in bytes. Messages larger than this are fragmented.\n   * Set to 0 to disable fragmentation (not recommended for cloud deployments).\n   * Default: 100KB (safe for AWS API Gateway's 128KB limit)\n   */\n  fragmentThreshold?: number\n}\n\n// ---------------------------------------------------------------------------\n// Peer ID generation\n// ---------------------------------------------------------------------------\n\n/**\n * Generate a random peer ID for connections that don't provide one.\n */\nfunction generatePeerId(): PeerId {\n  const chars = \"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789\"\n  let result = \"ws-\"\n  for (let i = 0; i < 12; i++) {\n    result += chars.charAt(Math.floor(Math.random() * chars.length))\n  }\n  return result\n}\n\n// ---------------------------------------------------------------------------\n// WebsocketServerTransport\n// ---------------------------------------------------------------------------\n\n/**\n * Websocket server network adapter.\n *\n * Framework-agnostic — works with any Websocket library through the\n * `Socket` interface. Use `handleConnection()` to integrate with your\n * framework's Websocket upgrade handler.\n *\n * Each client connection is tracked as a `WebsocketConnection` keyed\n * by peer ID. The adapter creates a channel per connection and routes\n * outbound messages through the connection's send method.\n *\n * The connection handshake follows a two-phase protocol:\n * 1. Server sends text `\"ready\"` signal (transport-level)\n * 2. Client sends `establish-request` (protocol-level)\n * 3. Server responds with `establish-response` (handled by Synchronizer)\n *\n * The server does NOT call `establishChannel()` — it waits for the\n * client's establish-request to avoid a race condition where the binary\n * establish-request could arrive before the client has processed \"ready\".\n */\nexport class WebsocketServerTransport extends Transport<PeerId> {\n  #connections = new Map<PeerId, WebsocketConnection>()\n  readonly #fragmentThreshold: number\n\n  constructor(options?: WebsocketServerTransportOptions) {\n    super({ transportType: \"websocket-server\" })\n    this.#fragmentThreshold =\n      options?.fragmentThreshold ?? DEFAULT_FRAGMENT_THRESHOLD\n  }\n\n  // ==========================================================================\n  // Adapter abstract method implementations\n  // ==========================================================================\n\n  protected generate(peerId: PeerId): GeneratedChannel {\n    return {\n      transportType: this.transportType,\n      send: (msg: ChannelMsg) => {\n        const connection = this.#connections.get(peerId)\n        if (connection) {\n          connection.send(msg)\n        }\n      },\n      stop: () => {\n        this.unregisterConnection(peerId)\n      },\n    }\n  }\n\n  async onStart(): Promise<void> {\n    // Server adapter starts passively — connections arrive via handleConnection()\n  }\n\n  async onStop(): Promise<void> {\n    // Disconnect all active connections\n    for (const connection of this.#connections.values()) {\n      connection.close(1001, \"Server shutting down\")\n    }\n    this.#connections.clear()\n  }\n\n  // ==========================================================================\n  // Connection management\n  // ==========================================================================\n\n  /**\n   * Handle a new Websocket connection.\n   *\n   * Call this from your framework's Websocket upgrade handler.\n   * Returns a connection handle and a `start()` function that begins\n   * message processing and sends the \"ready\" signal.\n   *\n   * @param options - Connection options including the Socket and optional peer ID\n   * @returns A connection handle and start function\n   *\n   * @example Bun\n   * ```typescript\n   * const { start } = serverAdapter.handleConnection({\n   *   socket: wrapBunWebsocket(ws),\n   * })\n   * start()\n   * ```\n   *\n   * @example Node.js ws\n   * ```typescript\n   * wss.on(\"connection\", (ws) => {\n   *   const { start } = serverAdapter.handleConnection({\n   *     socket: wrapNodeWebsocket(ws),\n   *   })\n   *   start()\n   * })\n   * ```\n   */\n  handleConnection(\n    options: WebsocketConnectionOptions,\n  ): WebsocketConnectionResult {\n    const { socket, peerId: providedPeerId } = options\n\n    // Generate peer ID if not provided\n    const peerId = providedPeerId ?? generatePeerId()\n\n    // Check for existing connection with same peer ID\n    const existingConnection = this.#connections.get(peerId)\n    if (existingConnection) {\n      existingConnection.close(1000, \"Replaced by new connection\")\n      this.unregisterConnection(peerId)\n    }\n\n    // Create channel for this peer\n    const channel = this.addChannel(peerId)\n\n    // Create connection object with fragmentation config\n    const connection = new WebsocketConnection(\n      peerId,\n      channel.channelId,\n      socket,\n      {\n        fragmentThreshold: this.#fragmentThreshold,\n      },\n    )\n    connection._setChannel(channel)\n\n    // Store connection\n    this.#connections.set(peerId, connection)\n\n    // Set up close handler\n    socket.onClose((_code, _reason) => {\n      this.unregisterConnection(peerId)\n    })\n\n    socket.onError(_error => {\n      this.unregisterConnection(peerId)\n    })\n\n    return {\n      connection,\n      start: () => {\n        connection.start()\n\n        // Send ready signal to client so it knows the server is ready\n        // This is a transport-level signal, separate from protocol-level establishment\n        connection.sendReady()\n\n        // NOTE: We do NOT call establishChannel() here.\n        // The client will send establish-request after receiving \"ready\".\n        // Our channel gets established when the Synchronizer receives\n        // and processes that establish-request.\n        //\n        // This prevents a race condition where our binary establish-request\n        // could arrive before the client has processed \"ready\" and created\n        // its channel.\n      },\n    }\n  }\n\n  /**\n   * Get an active connection by peer ID.\n   */\n  getConnection(peerId: PeerId): WebsocketConnection | undefined {\n    return this.#connections.get(peerId)\n  }\n\n  /**\n   * Get all active connections.\n   */\n  getAllConnections(): WebsocketConnection[] {\n    return Array.from(this.#connections.values())\n  }\n\n  /**\n   * Check if a peer is connected.\n   */\n  isConnected(peerId: PeerId): boolean {\n    return this.#connections.has(peerId)\n  }\n\n  /**\n   * Unregister a connection, removing its channel and cleaning up state.\n   */\n  unregisterConnection(peerId: PeerId): void {\n    const connection = this.#connections.get(peerId)\n    if (connection) {\n      this.removeChannel(connection.channelId)\n      this.#connections.delete(peerId)\n    }\n  }\n\n  /**\n   * Broadcast a message to all connected peers.\n   */\n  broadcast(msg: ChannelMsg): void {\n    for (const connection of this.#connections.values()) {\n      connection.send(msg)\n    }\n  }\n\n  /**\n   * Get the number of connected peers.\n   */\n  get connectionCount(): number {\n    return this.#connections.size\n  }\n}\n","// connection — WebsocketConnection for server-side peer connections.\n//\n// Wraps a Socket + CBOR codec + FragmentReassembler to provide\n// send/receive for ChannelMsg over a single Websocket connection.\n//\n// Used by WebsocketServerTransport to manage individual client connections.\n// The client adapter handles its own encoding/decoding inline since it\n// manages a single socket with reconnection logic.\n//\n// Ported from @loro-extended/adapter-websocket's WsConnection with\n// kyneta naming conventions and the kyneta wire format.\n\nimport type { Channel, ChannelMsg, PeerId } from \"@kyneta/transport\"\nimport {\n  decodeBinaryMessages,\n  encodeBinaryAndSend,\n  FragmentReassembler,\n} from \"@kyneta/wire\"\nimport type { Socket } from \"./types.js\"\n\n/**\n * Default fragment threshold in bytes.\n * Messages larger than this are fragmented for cloud infrastructure compatibility.\n * AWS API Gateway has a 128KB limit, so 100KB provides a safe margin.\n */\nexport const DEFAULT_FRAGMENT_THRESHOLD = 100 * 1024\n\n/**\n * Configuration for creating a WebsocketConnection.\n */\nexport interface WebsocketConnectionConfig {\n  /**\n   * Fragment threshold in bytes. Messages larger than this are fragmented.\n   * Set to 0 to disable fragmentation (not recommended for cloud deployments).\n   * Default: 100KB (safe for AWS API Gateway's 128KB limit)\n   */\n  fragmentThreshold?: number\n}\n\n/**\n * Represents a single Websocket connection to a peer (server-side).\n *\n * Manages encoding, framing, fragmentation, and reassembly for one\n * connected client. Created by `WebsocketServerTransport.handleConnection()`.\n *\n * The connection uses the CBOR codec for binary transport — this is\n * the natural choice for Websocket's binary frame support.\n */\nexport class WebsocketConnection {\n  readonly peerId: PeerId\n  readonly channelId: number\n\n  #socket: Socket\n  #channel: Channel | null = null\n  #started = false\n\n  // Fragmentation support\n  readonly #fragmentThreshold: number\n  readonly #reassembler: FragmentReassembler\n\n  constructor(\n    peerId: PeerId,\n    channelId: number,\n    socket: Socket,\n    config?: WebsocketConnectionConfig,\n  ) {\n    this.peerId = peerId\n    this.channelId = channelId\n    this.#socket = socket\n    this.#fragmentThreshold =\n      config?.fragmentThreshold ?? DEFAULT_FRAGMENT_THRESHOLD\n    this.#reassembler = new FragmentReassembler({\n      timeoutMs: 10_000,\n      onTimeout: (frameId: string) => {\n        console.warn(\n          `[WebsocketConnection] Fragment batch timed out: ${frameId}`,\n        )\n      },\n    })\n  }\n\n  // ==========================================================================\n  // INTERNAL API — for adapter use\n  // ==========================================================================\n\n  /**\n   * Set the channel reference.\n   * Called by the adapter when the channel is created.\n   * @internal\n   */\n  _setChannel(channel: Channel): void {\n    this.#channel = channel\n  }\n\n  // ==========================================================================\n  // PUBLIC API\n  // ==========================================================================\n\n  /**\n   * Start processing messages on this connection.\n   *\n   * Sets up the message handler on the socket. Must be called after\n   * the connection is fully set up (channel assigned, stored in adapter).\n   */\n  start(): void {\n    if (this.#started) {\n      return\n    }\n    this.#started = true\n\n    this.#socket.onMessage(data => {\n      this.#handleMessage(data)\n    })\n  }\n\n  /**\n   * Send a ChannelMsg through the Websocket.\n   *\n   * Encodes via CBOR codec → frame → fragment if needed → socket.send().\n   */\n  send(msg: ChannelMsg): void {\n    if (this.#socket.readyState !== \"open\") {\n      return\n    }\n\n    encodeBinaryAndSend(msg, this.#fragmentThreshold, data =>\n      this.#socket.send(data),\n    )\n  }\n\n  /**\n   * Send a \"ready\" signal to the client.\n   *\n   * This is a transport-level text message that tells the client the\n   * server is ready to receive protocol messages. The client creates\n   * its channel and sends establish-request after receiving this.\n   */\n  sendReady(): void {\n    if (this.#socket.readyState !== \"open\") {\n      return\n    }\n    this.#socket.send(\"ready\")\n  }\n\n  /**\n   * Close the connection and clean up resources.\n   */\n  close(code?: number, reason?: string): void {\n    this.#reassembler.dispose()\n    this.#socket.close(code, reason)\n  }\n\n  // ==========================================================================\n  // INTERNAL — message handling\n  // ==========================================================================\n\n  /**\n   * Handle an incoming message from the Websocket.\n   */\n  #handleMessage(data: Uint8Array | string): void {\n    // Handle keepalive ping/pong (text frames)\n    if (typeof data === \"string\") {\n      this.#handleKeepalive(data)\n      return\n    }\n\n    // Handle binary protocol messages through shared decode pipeline\n    try {\n      const messages = decodeBinaryMessages(data, this.#reassembler)\n      if (messages) {\n        for (const msg of messages) {\n          this.#handleChannelMessage(msg)\n        }\n      }\n    } catch (error) {\n      console.error(\"Failed to decode wire message:\", error)\n    }\n  }\n\n  /**\n   * Handle a decoded channel message.\n   *\n   * Delivers messages synchronously. The Synchronizer's receive queue\n   * handles recursion prevention by queuing messages and processing\n   * them iteratively.\n   */\n  #handleChannelMessage(msg: ChannelMsg): void {\n    if (!this.#channel) {\n      console.error(\"Cannot handle message: channel not set\")\n      return\n    }\n\n    // Deliver synchronously — the Synchronizer's receive queue prevents recursion\n    this.#channel.onReceive(msg)\n  }\n\n  /**\n   * Handle keepalive ping/pong messages.\n   */\n  #handleKeepalive(text: string): void {\n    if (text === \"ping\") {\n      this.#socket.send(\"pong\")\n    }\n    // Ignore \"pong\" and \"ready\" responses\n  }\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../src/server-transport.ts","../src/connection.ts","../src/service-client.ts"],"sourcesContent":["// server-adapter — Websocket server adapter for @kyneta/exchange.\n//\n// Manages Websocket connections from clients, encoding/decoding via the\n// kyneta wire format. Framework-agnostic — works with any Websocket\n// library through the Socket interface.\n//\n// Usage with Bun:\n//   import { WebsocketServerTransport } from \"@kyneta/websocket-transport/server\"\n//   import { createBunWebsocketHandlers } from \"@kyneta/websocket-transport/bun\"\n//\n//   const serverAdapter = new WebsocketServerTransport()\n//   Bun.serve({\n//     websocket: createBunWebsocketHandlers(serverAdapter),\n//     fetch(req, server) { server.upgrade(req); return new Response(\"\", { status: 101 }) },\n//   })\n//\n// Usage with Node.js `ws`:\n//   import { WebsocketServerTransport, wrapNodeWebsocket } from \"@kyneta/websocket-transport/server\"\n//   import { WebSocketServer } from \"ws\"\n//\n//   const serverAdapter = new WebsocketServerTransport()\n//   const wss = new WebSocketServer({ server })\n//   wss.on(\"connection\", (ws) => {\n//     const { start } = serverAdapter.handleConnection({ socket: wrapNodeWebsocket(ws) })\n//     start()\n//   })\n//\n// Ported from @loro-extended/adapter-websocket's WsServerNetworkAdapter with\n// kyneta naming conventions and the kyneta 5-message protocol.\n\nimport type { ChannelMsg, GeneratedChannel, PeerId } from \"@kyneta/transport\"\nimport { Transport } from \"@kyneta/transport\"\nimport {\n  DEFAULT_FRAGMENT_THRESHOLD,\n  WebsocketConnection,\n} from \"./connection.js\"\nimport type {\n  WebsocketConnectionOptions,\n  WebsocketConnectionResult,\n} from \"./types.js\"\n\n// ---------------------------------------------------------------------------\n// Options\n// ---------------------------------------------------------------------------\n\n/**\n * Options for the Websocket server adapter.\n */\nexport interface WebsocketServerTransportOptions {\n  /**\n   * Fragment threshold in bytes. Messages larger than this are fragmented.\n   * Set to 0 to disable fragmentation (not recommended for cloud deployments).\n   * Default: 100KB (safe for AWS API Gateway's 128KB limit)\n   */\n  fragmentThreshold?: number\n}\n\n// ---------------------------------------------------------------------------\n// Peer ID generation\n// ---------------------------------------------------------------------------\n\n/**\n * Generate a random peer ID for connections that don't provide one.\n */\nfunction generatePeerId(): PeerId {\n  const chars = \"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789\"\n  let result = \"ws-\"\n  for (let i = 0; i < 12; i++) {\n    result += chars.charAt(Math.floor(Math.random() * chars.length))\n  }\n  return result\n}\n\n// ---------------------------------------------------------------------------\n// WebsocketServerTransport\n// ---------------------------------------------------------------------------\n\n/**\n * Websocket server network adapter.\n *\n * Framework-agnostic — works with any Websocket library through the\n * `Socket` interface. Use `handleConnection()` to integrate with your\n * framework's Websocket upgrade handler.\n *\n * Each client connection is tracked as a `WebsocketConnection` keyed\n * by peer ID. The adapter creates a channel per connection and routes\n * outbound messages through the connection's send method.\n *\n * The connection handshake follows a two-phase protocol:\n * 1. Server sends text `\"ready\"` signal (transport-level)\n * 2. Client sends `establish-request` (protocol-level)\n * 3. Server responds with `establish-response` (handled by Synchronizer)\n *\n * The server does NOT call `establishChannel()` — it waits for the\n * client's establish-request to avoid a race condition where the binary\n * establish-request could arrive before the client has processed \"ready\".\n */\nexport class WebsocketServerTransport extends Transport<PeerId> {\n  #connections = new Map<PeerId, WebsocketConnection>()\n  readonly #fragmentThreshold: number\n\n  constructor(options?: WebsocketServerTransportOptions) {\n    super({ transportType: \"websocket-server\" })\n    this.#fragmentThreshold =\n      options?.fragmentThreshold ?? DEFAULT_FRAGMENT_THRESHOLD\n  }\n\n  // ==========================================================================\n  // Adapter abstract method implementations\n  // ==========================================================================\n\n  protected generate(peerId: PeerId): GeneratedChannel {\n    return {\n      transportType: this.transportType,\n      send: (msg: ChannelMsg) => {\n        const connection = this.#connections.get(peerId)\n        if (connection) {\n          connection.send(msg)\n        }\n      },\n      stop: () => {\n        this.unregisterConnection(peerId)\n      },\n    }\n  }\n\n  async onStart(): Promise<void> {\n    // Server adapter starts passively — connections arrive via handleConnection()\n  }\n\n  async onStop(): Promise<void> {\n    // Disconnect all active connections\n    for (const connection of this.#connections.values()) {\n      connection.close(1001, \"Server shutting down\")\n    }\n    this.#connections.clear()\n  }\n\n  // ==========================================================================\n  // Connection management\n  // ==========================================================================\n\n  /**\n   * Handle a new Websocket connection.\n   *\n   * Call this from your framework's Websocket upgrade handler.\n   * Returns a connection handle and a `start()` function that begins\n   * message processing and sends the \"ready\" signal.\n   *\n   * @param options - Connection options including the Socket and optional peer ID\n   * @returns A connection handle and start function\n   *\n   * @example Bun\n   * ```typescript\n   * const { start } = serverAdapter.handleConnection({\n   *   socket: wrapBunWebsocket(ws),\n   * })\n   * start()\n   * ```\n   *\n   * @example Node.js ws\n   * ```typescript\n   * wss.on(\"connection\", (ws) => {\n   *   const { start } = serverAdapter.handleConnection({\n   *     socket: wrapNodeWebsocket(ws),\n   *   })\n   *   start()\n   * })\n   * ```\n   */\n  handleConnection(\n    options: WebsocketConnectionOptions,\n  ): WebsocketConnectionResult {\n    const { socket, peerId: providedPeerId } = options\n\n    // Generate peer ID if not provided\n    const peerId = providedPeerId ?? generatePeerId()\n\n    // Check for existing connection with same peer ID\n    const existingConnection = this.#connections.get(peerId)\n    if (existingConnection) {\n      existingConnection.close(1000, \"Replaced by new connection\")\n      this.unregisterConnection(peerId)\n    }\n\n    // Create channel for this peer\n    const channel = this.addChannel(peerId)\n\n    // Create connection object with fragmentation config\n    const connection = new WebsocketConnection(\n      peerId,\n      channel.channelId,\n      socket,\n      {\n        fragmentThreshold: this.#fragmentThreshold,\n      },\n    )\n    connection._setChannel(channel)\n\n    // Store connection\n    this.#connections.set(peerId, connection)\n\n    // Set up close handler\n    socket.onClose((_code, _reason) => {\n      this.unregisterConnection(peerId)\n    })\n\n    socket.onError(_error => {\n      this.unregisterConnection(peerId)\n    })\n\n    return {\n      connection,\n      start: () => {\n        connection.start()\n\n        // Send ready signal to client so it knows the server is ready\n        // This is a transport-level signal, separate from protocol-level establishment\n        connection.sendReady()\n\n        // NOTE: We do NOT call establishChannel() here.\n        // The client will send establish-request after receiving \"ready\".\n        // Our channel gets established when the Synchronizer receives\n        // and processes that establish-request.\n        //\n        // This prevents a race condition where our binary establish-request\n        // could arrive before the client has processed \"ready\" and created\n        // its channel.\n      },\n    }\n  }\n\n  /**\n   * Get an active connection by peer ID.\n   */\n  getConnection(peerId: PeerId): WebsocketConnection | undefined {\n    return this.#connections.get(peerId)\n  }\n\n  /**\n   * Get all active connections.\n   */\n  getAllConnections(): WebsocketConnection[] {\n    return Array.from(this.#connections.values())\n  }\n\n  /**\n   * Check if a peer is connected.\n   */\n  isConnected(peerId: PeerId): boolean {\n    return this.#connections.has(peerId)\n  }\n\n  /**\n   * Unregister a connection, removing its channel and cleaning up state.\n   */\n  unregisterConnection(peerId: PeerId): void {\n    const connection = this.#connections.get(peerId)\n    if (connection) {\n      this.removeChannel(connection.channelId)\n      this.#connections.delete(peerId)\n    }\n  }\n\n  /**\n   * Broadcast a message to all connected peers.\n   */\n  broadcast(msg: ChannelMsg): void {\n    for (const connection of this.#connections.values()) {\n      connection.send(msg)\n    }\n  }\n\n  /**\n   * Get the number of connected peers.\n   */\n  get connectionCount(): number {\n    return this.#connections.size\n  }\n}\n","// connection — WebsocketConnection for server-side peer connections.\n//\n// Wraps a Socket + CBOR codec + FragmentReassembler to provide\n// send/receive for ChannelMsg over a single Websocket connection.\n//\n// Used by WebsocketServerTransport to manage individual client connections.\n// The client adapter handles its own encoding/decoding inline since it\n// manages a single socket with reconnection logic.\n//\n// Ported from @loro-extended/adapter-websocket's WsConnection with\n// kyneta naming conventions and the kyneta wire format.\n\nimport type { Channel, ChannelMsg, PeerId } from \"@kyneta/transport\"\nimport {\n  decodeBinaryMessages,\n  encodeBinaryAndSend,\n  FragmentReassembler,\n} from \"@kyneta/wire\"\nimport type { Socket } from \"./types.js\"\n\n/**\n * Default fragment threshold in bytes.\n * Messages larger than this are fragmented for cloud infrastructure compatibility.\n * AWS API Gateway has a 128KB limit, so 100KB provides a safe margin.\n */\nexport const DEFAULT_FRAGMENT_THRESHOLD = 100 * 1024\n\n/**\n * Configuration for creating a WebsocketConnection.\n */\nexport interface WebsocketConnectionConfig {\n  /**\n   * Fragment threshold in bytes. Messages larger than this are fragmented.\n   * Set to 0 to disable fragmentation (not recommended for cloud deployments).\n   * Default: 100KB (safe for AWS API Gateway's 128KB limit)\n   */\n  fragmentThreshold?: number\n}\n\n/**\n * Represents a single Websocket connection to a peer (server-side).\n *\n * Manages encoding, framing, fragmentation, and reassembly for one\n * connected client. Created by `WebsocketServerTransport.handleConnection()`.\n *\n * The connection uses the CBOR codec for binary transport — this is\n * the natural choice for Websocket's binary frame support.\n */\nexport class WebsocketConnection {\n  readonly peerId: PeerId\n  readonly channelId: number\n\n  #socket: Socket\n  #channel: Channel | null = null\n  #started = false\n\n  // Fragmentation support\n  readonly #fragmentThreshold: number\n  readonly #reassembler: FragmentReassembler\n\n  constructor(\n    peerId: PeerId,\n    channelId: number,\n    socket: Socket,\n    config?: WebsocketConnectionConfig,\n  ) {\n    this.peerId = peerId\n    this.channelId = channelId\n    this.#socket = socket\n    this.#fragmentThreshold =\n      config?.fragmentThreshold ?? DEFAULT_FRAGMENT_THRESHOLD\n    this.#reassembler = new FragmentReassembler({\n      timeoutMs: 10_000,\n      onTimeout: (frameId: string) => {\n        console.warn(\n          `[WebsocketConnection] Fragment batch timed out: ${frameId}`,\n        )\n      },\n    })\n  }\n\n  // ==========================================================================\n  // INTERNAL API — for adapter use\n  // ==========================================================================\n\n  /**\n   * Set the channel reference.\n   * Called by the adapter when the channel is created.\n   * @internal\n   */\n  _setChannel(channel: Channel): void {\n    this.#channel = channel\n  }\n\n  // ==========================================================================\n  // PUBLIC API\n  // ==========================================================================\n\n  /**\n   * Start processing messages on this connection.\n   *\n   * Sets up the message handler on the socket. Must be called after\n   * the connection is fully set up (channel assigned, stored in adapter).\n   */\n  start(): void {\n    if (this.#started) {\n      return\n    }\n    this.#started = true\n\n    this.#socket.onMessage(data => {\n      this.#handleMessage(data)\n    })\n  }\n\n  /**\n   * Send a ChannelMsg through the Websocket.\n   *\n   * Encodes via CBOR codec → frame → fragment if needed → socket.send().\n   */\n  send(msg: ChannelMsg): void {\n    if (this.#socket.readyState !== \"open\") {\n      return\n    }\n\n    encodeBinaryAndSend(msg, this.#fragmentThreshold, data =>\n      this.#socket.send(data),\n    )\n  }\n\n  /**\n   * Send a \"ready\" signal to the client.\n   *\n   * This is a transport-level text message that tells the client the\n   * server is ready to receive protocol messages. The client creates\n   * its channel and sends establish-request after receiving this.\n   */\n  sendReady(): void {\n    if (this.#socket.readyState !== \"open\") {\n      return\n    }\n    this.#socket.send(\"ready\")\n  }\n\n  /**\n   * Close the connection and clean up resources.\n   */\n  close(code?: number, reason?: string): void {\n    this.#reassembler.dispose()\n    this.#socket.close(code, reason)\n  }\n\n  // ==========================================================================\n  // INTERNAL — message handling\n  // ==========================================================================\n\n  /**\n   * Handle an incoming message from the Websocket.\n   */\n  #handleMessage(data: Uint8Array | string): void {\n    // Handle keepalive ping/pong (text frames)\n    if (typeof data === \"string\") {\n      this.#handleKeepalive(data)\n      return\n    }\n\n    // Handle binary protocol messages through shared decode pipeline\n    try {\n      const messages = decodeBinaryMessages(data, this.#reassembler)\n      if (messages) {\n        for (const msg of messages) {\n          this.#handleChannelMessage(msg)\n        }\n      }\n    } catch (error) {\n      console.error(\"Failed to decode wire message:\", error)\n    }\n  }\n\n  /**\n   * Handle a decoded channel message.\n   *\n   * Delivers messages synchronously. The Synchronizer's receive queue\n   * handles recursion prevention by queuing messages and processing\n   * them iteratively.\n   */\n  #handleChannelMessage(msg: ChannelMsg): void {\n    if (!this.#channel) {\n      console.error(\"Cannot handle message: channel not set\")\n      return\n    }\n\n    // Deliver synchronously — the Synchronizer's receive queue prevents recursion\n    this.#channel.onReceive(msg)\n  }\n\n  /**\n   * Handle keepalive ping/pong messages.\n   */\n  #handleKeepalive(text: string): void {\n    if (text === \"ping\") {\n      this.#socket.send(\"pong\")\n    }\n    // Ignore \"pong\" and \"ready\" responses\n  }\n}\n","// service-client — service-to-service WebSocket client factory.\n//\n// Extracted from client-transport.ts so that the service client factory\n// lives in the `./server` entry point (where it belongs) rather than\n// the `./browser` entry point. Backend code imports from `./server`;\n// browser code imports from `./browser`.\n\nimport type { TransportFactory } from \"@kyneta/transport\"\nimport {\n  WebsocketClientTransport,\n  type WebsocketClientOptions,\n} from \"./client-transport.js\"\n\n/**\n * Options for service-to-service Websocket connections.\n *\n * Identical to `WebsocketClientOptions` — the `headers` field is always\n * available on the base options. This alias exists for API clarity:\n * importing `ServiceWebsocketClientOptions` from `./server` signals\n * intent and pairs with `createServiceWebsocketClient`.\n */\nexport type ServiceWebsocketClientOptions = WebsocketClientOptions\n\n/**\n * Create a Websocket client transport for service-to-service connections.\n *\n * This factory is for backend environments (Bun, Node.js) where you need\n * to pass authentication headers during the Websocket upgrade.\n *\n * Note: Headers are a Bun/Node-specific extension. The browser WebSocket API\n * does not support custom headers. For browser clients, use\n * `createWebsocketClient()` and authenticate via URL query parameters.\n *\n * @example\n * ```typescript\n * import { createServiceWebsocketClient } from \"@kyneta/websocket-transport/server\"\n *\n * const exchange = new Exchange({\n *   transports: [createServiceWebsocketClient({\n *     url: \"ws://primary-server:3000/ws\",\n *     WebSocket,\n *     headers: { Authorization: \"Bearer token\" },\n *     reconnect: { enabled: true },\n *   })],\n * })\n * ```\n */\nexport function createServiceWebsocketClient(\n  options: ServiceWebsocketClientOptions,\n): TransportFactory {\n  return () => new WebsocketClientTransport(options)\n}"],"mappings":"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","names":[]}

package/dist/{types-DdNb8cAz.d.ts → types-D0lbeevu.d.ts}

@@ -1,5 +1,53 @@
-import { StateTransition, TransitionListener as TransitionListener$1, PeerId } from '@kyneta/transport';
+import { TransitionListener as TransitionListener$1, StateTransition, PeerId } from '@kyneta/transport';
 
+/**
+ * WebSocket readyState constants per the WHATWG WebSocket spec.
+ * Replaces references to `WebSocket.CONNECTING`, `WebSocket.OPEN`, etc.
+ * so that shared code never depends on the browser global.
+ */
+declare const READY_STATE: {
+    readonly CONNECTING: 0;
+    readonly OPEN: 1;
+    readonly CLOSING: 2;
+    readonly CLOSED: 3;
+};
+/** Minimal message event — only the fields the transport accesses. */
+interface WebSocketMessageEvent {
+    readonly data: string | ArrayBuffer;
+}
+/** Minimal close event — only the fields the transport accesses. */
+interface WebSocketCloseEvent {
+    readonly code: number;
+    readonly reason: string;
+}
+/**
+ * Structural type for a constructed WebSocket instance.
+ *
+ * Covers the browser's `WebSocket`, the `ws` library's `WebSocket`,
+ * and Bun's client `WebSocket` — all satisfy this interface without casting.
+ *
+ * The client transport uses `addEventListener`/`removeEventListener` for
+ * one-shot connection handlers with explicit cleanup during the connect
+ * phase. This is why `WebSocketLike` exists alongside the server-side
+ * `Socket` interface (which uses single-callback registration).
+ */
+interface WebSocketLike {
+    readonly readyState: number;
+    binaryType: string;
+    send(data: string | ArrayBufferLike | Uint8Array): void;
+    close(code?: number, reason?: string): void;
+    addEventListener(type: string, listener: (event: any) => void): void;
+    removeEventListener(type: string, listener: (event: any) => void): void;
+}
+/**
+ * Structural type for a WebSocket constructor.
+ *
+ * Type safety for constructor arguments is intentionally at the options
+ * layer (`WebsocketClientOptions.headers`), not here. The `...rest: any[]`
+ * absorbs both the browser's `protocols` arg and backend's `{ headers }`
+ * arg without requiring the transport to know which runtime it's in.
+ */
+type WebSocketConstructor = new (url: string, ...rest: any[]) => WebSocketLike;
 /**
  * Websocket ready states — mirrors the standard WebSocket readyState
  * values as human-readable strings.
@@ -146,4 +194,4 @@ interface NodeWebsocketLike {
  */
 declare function wrapNodeWebsocket(ws: NodeWebsocketLike): Socket;
 
-export { type DisconnectReason as D, type NodeWebsocketLike as N, type Socket as S, type TransitionListener as T, type WebsocketClientState as W, type SocketReadyState as a, type WebsocketClientStateTransition as b, type WebsocketConnectionOptions as c, type WebsocketConnectionResult as d, type WebsocketConnectionHandle as e, wrapNodeWebsocket as f, wrapStandardWebsocket as w };
+export { type DisconnectReason as D, type NodeWebsocketLike as N, READY_STATE as R, type Socket as S, type TransitionListener as T, type WebsocketClientState as W, type SocketReadyState as a, type WebSocketCloseEvent as b, type WebSocketConstructor as c, type WebSocketLike as d, type WebSocketMessageEvent as e, type WebsocketClientStateTransition as f, type WebsocketConnectionOptions as g, type WebsocketConnectionResult as h, type WebsocketConnectionHandle as i, wrapStandardWebsocket as j, wrapNodeWebsocket as w };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kyneta/websocket-transport",
-  "version": "1.2.0",
-  "description": "Websocket network adapter for @kyneta/exchange — client, server, and Bun integration",
+  "version": "1.3.1",
+  "description": "Websocket network adapter for @kyneta/exchange — browser, server, and Bun integration",
   "author": "Duane Johnson",
   "license": "MIT",
   "repository": {
@@ -18,9 +18,9 @@
     "src"
   ],
   "exports": {
-    "./client": {
-      "types": "./dist/client.d.ts",
-      "import": "./dist/client.js"
+    "./browser": {
+      "types": "./dist/browser.d.ts",
+      "import": "./dist/browser.js"
     },
     "./server": {
       "types": "./dist/server.d.ts",
@@ -33,9 +33,9 @@
     "./src/*": "./src/*"
   },
   "peerDependencies": {
-    "@kyneta/transport": "^1.0.0",
-    "@kyneta/machine": "^1.0.0",
-    "@kyneta/wire": "^1.2.0"
+    "@kyneta/transport": "^1.3.1",
+    "@kyneta/machine": "^1.3.1",
+    "@kyneta/wire": "^1.3.1"
   },
   "devDependencies": {
     "@types/node": "^22",
@@ -43,11 +43,11 @@
     "tsup": "^8.5.0",
     "typescript": "^5.9.2",
     "vitest": "^4.0.17",
-    "@kyneta/exchange": "^1.2.0",
-    "@kyneta/transport": "^1.0.0",
-    "@kyneta/machine": "^1.0.0",
-    "@kyneta/schema": "^1.2.0",
-    "@kyneta/wire": "^1.2.0"
+    "@kyneta/exchange": "^1.3.1",
+    "@kyneta/machine": "^1.3.1",
+    "@kyneta/wire": "^1.3.1",
+    "@kyneta/transport": "^1.3.1",
+    "@kyneta/schema": "^1.3.1"
   },
   "scripts": {
     "build": "tsup",

package/src/__tests__/client-transport.test.ts

@@ -0,0 +1,168 @@
+// client-transport.test — unit tests for the websocket client transport's
+// constructor injection and header-passing behavior.
+//
+// These tests verify two properties:
+//   1. The transport uses the caller-provided WebSocket constructor.
+//   2. When `headers` are provided, they're passed as `{ headers }` in the
+//      second argument. When absent, the constructor is called with just the URL.
+
+import { describe, expect, it, vi } from "vitest"
+import type { TransportContext } from "@kyneta/transport"
+import type { PeerIdentityDetails } from "@kyneta/transport"
+import { WebsocketClientTransport } from "../client-transport.js"
+import type { WebSocketConstructor, WebSocketLike } from "../types.js"
+
+// ---------------------------------------------------------------------------
+// Mock WebSocket
+// ---------------------------------------------------------------------------
+
+interface MockCall {
+  url: string
+  rest: any[]
+}
+
+/**
+ * Create a mock WebSocket class that records constructor invocations
+ * and implements WebSocketLike with no-op methods.
+ */
+function createMockWebSocketClass() {
+  const calls: MockCall[] = []
+
+  const MockWebSocket = vi.fn(function (
+    this: WebSocketLike,
+    url: string,
+    ...rest: any[]
+  ) {
+    calls.push({ url, rest })
+    ;(this as any).readyState = 0
+    ;(this as any).binaryType = "blob"
+    ;(this as any).send = vi.fn()
+    ;(this as any).close = vi.fn()
+    ;(this as any).addEventListener = vi.fn()
+    ;(this as any).removeEventListener = vi.fn()
+  }) as unknown as WebSocketConstructor
+
+  return { MockWebSocket, calls }
+}
+
+// ---------------------------------------------------------------------------
+// Transport lifecycle helpers
+// ---------------------------------------------------------------------------
+
+const testIdentity: PeerIdentityDetails = {
+  peerId: "test-peer-123",
+  name: "Test Peer",
+  type: "user",
+}
+
+function createTransportContext(
+  overrides: Partial<TransportContext> = {},
+): TransportContext {
+  return {
+    identity: testIdentity,
+    onChannelReceive: vi.fn(),
+    onChannelAdded: vi.fn(),
+    onChannelRemoved: vi.fn(),
+    onChannelEstablish: vi.fn(),
+    ...overrides,
+  }
+}
+
+/**
+ * Initialize and start a WebsocketClientTransport through the full
+ * Transport lifecycle so the program's "create-websocket" effect fires.
+ */
+async function startTransport(transport: WebsocketClientTransport) {
+  const ctx = createTransportContext()
+  transport._initialize(ctx)
+  await transport._start()
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("WebsocketClientTransport — constructor injection", () => {
+  it("calls the provided WebSocket constructor with the URL", async () => {
+    const { MockWebSocket, calls } = createMockWebSocketClass()
+
+    const transport = new WebsocketClientTransport({
+      url: "ws://localhost:9999/ws",
+      WebSocket: MockWebSocket,
+      reconnect: { enabled: false },
+    })
+
+    await startTransport(transport)
+
+    expect(calls).toHaveLength(1)
+    expect(calls[0]!.url).toBe("ws://localhost:9999/ws")
+  })
+
+  it("resolves URL function with peerId before passing to constructor", async () => {
+    const { MockWebSocket, calls } = createMockWebSocketClass()
+
+    const transport = new WebsocketClientTransport({
+      url: (peerId) => `ws://localhost:9999/ws/${peerId}`,
+      WebSocket: MockWebSocket,
+      reconnect: { enabled: false },
+    })
+
+    await startTransport(transport)
+
+    expect(calls).toHaveLength(1)
+    expect(calls[0]!.url).toBe(`ws://localhost:9999/ws/${testIdentity.peerId}`)
+  })
+})
+
+describe("WebsocketClientTransport — header passing", () => {
+  it("passes { headers } as second arg when headers are non-empty", async () => {
+    const headers = {
+      Authorization: "Bearer test-token",
+      "X-Custom": "value",
+    }
+    const { MockWebSocket, calls } = createMockWebSocketClass()
+
+    const transport = new WebsocketClientTransport({
+      url: "ws://localhost:9999/ws",
+      WebSocket: MockWebSocket,
+      headers,
+      reconnect: { enabled: false },
+    })
+
+    await startTransport(transport)
+
+    expect(calls).toHaveLength(1)
+    expect(calls[0]!.rest).toEqual([{ headers }])
+  })
+
+  it("omits second arg when headers are not provided", async () => {
+    const { MockWebSocket, calls } = createMockWebSocketClass()
+
+    const transport = new WebsocketClientTransport({
+      url: "ws://localhost:9999/ws",
+      WebSocket: MockWebSocket,
+      reconnect: { enabled: false },
+    })
+
+    await startTransport(transport)
+
+    expect(calls).toHaveLength(1)
+    expect(calls[0]!.rest).toEqual([])
+  })
+
+  it("omits second arg when headers is an empty object", async () => {
+    const { MockWebSocket, calls } = createMockWebSocketClass()
+
+    const transport = new WebsocketClientTransport({
+      url: "ws://localhost:9999/ws",
+      WebSocket: MockWebSocket,
+      headers: {},
+      reconnect: { enabled: false },
+    })
+
+    await startTransport(transport)
+
+    expect(calls).toHaveLength(1)
+    expect(calls[0]!.rest).toEqual([])
+  })
+})