@kyneta/websocket-transport 1.3.0 → 1.4.0

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,"file":"server.js","names":["#fragmentThreshold","#reassembler","#socket","#channel","#started","#handleMessage","#handleKeepalive","#handleChannelMessage","#fragmentThreshold","#connections"],"sources":["../src/connection.ts","../src/server-transport.ts","../src/service-client.ts"],"sourcesContent":["// 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 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","// 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` (protocol-level)\n * 3. Server upgrades channel and sends present (handled by Synchronizer)\n *\n * The server does NOT call `establishChannel()` — it waits for the\n * client's establish to avoid a race condition where the binary\n * establish 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 after receiving \"ready\".\n        // Our channel gets established when the Synchronizer receives\n        // and processes that establish message.\n        //\n        // This prevents a race condition where our binary establish\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","// 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  type WebsocketClientOptions,\n  WebsocketClientTransport,\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}\n"],"mappings":"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"}

package/dist/types-CJAcr1Df.d.ts

@@ -0,0 +1,199 @@
+import { PeerId, StateTransition, TransitionListener } from "@kyneta/transport";
+
+//#region src/types.d.ts
+/**
+ * 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 | ArrayBuffer): 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.
+ */
+type SocketReadyState = "connecting" | "open" | "closing" | "closed";
+/**
+ * Framework-agnostic Websocket interface.
+ *
+ * This allows the adapter to work with any Websocket library:
+ * - Browser `WebSocket` via `wrapStandardWebsocket()`
+ * - Node.js `ws` library via `wrapNodeWebsocket()`
+ * - Bun `ServerWebSocket` via `wrapBunWebsocket()`
+ *
+ * The interface is intentionally minimal — only the operations the
+ * adapter needs are exposed.
+ */
+interface Socket {
+  /** Send binary or text data through the Websocket. */
+  send(data: Uint8Array | string): void;
+  /** Close the Websocket connection. */
+  close(code?: number, reason?: string): void;
+  /** Register a handler for incoming messages (binary or text). */
+  onMessage(handler: (data: Uint8Array | string) => void): void;
+  /** Register a handler for connection close. */
+  onClose(handler: (code: number, reason: string) => void): void;
+  /** Register a handler for errors. */
+  onError(handler: (error: Error) => void): void;
+  /** The current ready state of the Websocket. */
+  readonly readyState: SocketReadyState;
+}
+/**
+ * Options for handling a new Websocket connection on the server.
+ */
+interface WebsocketConnectionOptions {
+  /** The Websocket instance, wrapped in the Socket interface. */
+  socket: Socket;
+  /** Optional peer ID extracted from the upgrade request. */
+  peerId?: PeerId;
+  /** Optional authentication token from the upgrade request. */
+  authToken?: string;
+}
+/**
+ * Handle for an active Websocket connection.
+ */
+interface WebsocketConnectionHandle {
+  /** The peer ID for this connection. */
+  readonly peerId: PeerId;
+  /** The channel ID for this connection. */
+  readonly channelId: number;
+  /** Close the connection. */
+  close(code?: number, reason?: string): void;
+}
+/**
+ * Result of handling a Websocket connection on the server.
+ */
+interface WebsocketConnectionResult {
+  /** The connection handle for managing this peer. */
+  connection: WebsocketConnectionHandle;
+  /** Call this to start processing messages. */
+  start(): void;
+}
+/**
+ * Discriminated union describing why a Websocket connection was lost.
+ */
+type DisconnectReason = {
+  type: "intentional";
+} | {
+  type: "error";
+  error: Error;
+} | {
+  type: "closed";
+  code: number;
+  reason: string;
+} | {
+  type: "max-retries-exceeded";
+  attempts: number;
+} | {
+  type: "not-started";
+};
+/**
+ * All possible states of the Websocket client.
+ *
+ * State machine transitions:
+ * ```
+ * disconnected → connecting → connected → ready
+ *                    ↓            ↓         ↓
+ *               reconnecting ← ─ ┴ ─ ─ ─ ─ ┘
+ *                    ↓
+ *               connecting (retry)
+ *                    ↓
+ *               disconnected (max retries)
+ * ```
+ */
+type WebsocketClientState = {
+  status: "disconnected";
+  reason?: DisconnectReason;
+} | {
+  status: "connecting";
+  attempt: number;
+} | {
+  status: "connected";
+} | {
+  status: "ready";
+} | {
+  status: "reconnecting";
+  attempt: number;
+  nextAttemptMs: number;
+};
+/**
+ * A state transition event for websocket client states.
+ * Specialized from the generic `StateTransition<S>`.
+ */
+type WebsocketClientStateTransition = StateTransition<WebsocketClientState>;
+/**
+ * Listener for websocket client state transitions.
+ * Specialized from the generic `TransitionListener<S>`.
+ */
+type TransitionListener$1 = TransitionListener<WebsocketClientState>;
+/**
+ * Wrap a standard `WebSocket` (browser or Node.js `ws` via `ws` package
+ * in `WebSocket`-compatible mode) into the `Socket` interface.
+ *
+ * Handles `ArrayBuffer`, `Blob`, and string messages.
+ */
+declare function wrapStandardWebsocket(ws: WebSocket): Socket;
+/**
+ * The minimal interface we need from the Node.js `ws` library's `WebSocket`.
+ *
+ * Using a structural type rather than importing `ws` — consumers provide
+ * the actual `ws` instance, we just need these methods.
+ */
+interface NodeWebsocketLike {
+  send(data: Uint8Array | string): void;
+  close(code?: number, reason?: string): void;
+  on(event: "message", handler: (data: Buffer | ArrayBuffer | string, isBinary: boolean) => void): void;
+  on(event: "close", handler: (code: number, reason: Buffer) => void): void;
+  on(event: "error", handler: (error: Error) => void): void;
+  readyState: number;
+}
+/**
+ * Wrap a Node.js `ws` library WebSocket into the `Socket` interface.
+ *
+ * Handles `Buffer` → `Uint8Array` conversion for binary messages.
+ */
+declare function wrapNodeWebsocket(ws: NodeWebsocketLike): Socket;
+//#endregion
+export { wrapStandardWebsocket as _, SocketReadyState as a, WebSocketConstructor as c, WebsocketClientState as d, WebsocketClientStateTransition as f, wrapNodeWebsocket as g, WebsocketConnectionResult as h, Socket as i, WebSocketLike as l, WebsocketConnectionOptions as m, NodeWebsocketLike as n, TransitionListener$1 as o, WebsocketConnectionHandle as p, READY_STATE as r, WebSocketCloseEvent as s, DisconnectReason as t, WebSocketMessageEvent as u };
+//# sourceMappingURL=types-CJAcr1Df.d.ts.map

package/dist/types-CJAcr1Df.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types-CJAcr1Df.d.ts","names":[],"sources":["../src/types.ts"],"mappings":";;;;;AAyBA;;;cAAa,WAAA;EAAA;;;;;;UAYI,qBAAA;EAAA,SACN,IAAA,WAAe,WAAA;AAAA;;UAIT,mBAAA;EAAA,SACN,IAAA;EAAA,SACA,MAAA;AAAA;;;AAkBX;;;;;;;;;UAAiB,aAAA;EAAA,SACN,UAAA;EACT,UAAA;EACA,IAAA,CAAK,IAAA,WAAe,WAAA;EACpB,KAAA,CAAM,IAAA,WAAe,MAAA;EACrB,gBAAA,CAAiB,IAAA,UAAc,QAAA,GAAW,KAAA;EAC1C,mBAAA,CAAoB,IAAA,UAAc,QAAA,GAAW,KAAA;AAAA;;;;;;AAW/C;;;KAAY,oBAAA,QACV,GAAA,aACG,IAAA,YACA,aAAA;;;;;KAUO,gBAAA;AAAZ;;;;;AAiBA;;;;;;AAjBA,UAiBiB,MAAA;EAiBsB;EAfrC,IAAA,CAAK,IAAA,EAAM,UAAA;EAAX;EAGA,KAAA,CAAM,IAAA,WAAe,MAAA;EAHhB;EAML,SAAA,CAAU,OAAA,GAAU,IAAA,EAAM,UAAA;EAHpB;EAMN,OAAA,CAAQ,OAAA,GAAU,IAAA,UAAc,MAAA;EAHhC;EAMA,OAAA,CAAQ,OAAA,GAAU,KAAA,EAAO,KAAA;EANL;EAAA,SASX,UAAA,EAAY,gBAAA;AAAA;;;;UAUN,0BAAA;EAbU;EAezB,MAAA,EAAQ,MAAA;EAfA;EAkBR,MAAA,GAAS,MAAA;EAfY;EAkBrB,SAAA;AAAA;AARF;;;AAAA,UAciB,yBAAA;EAZf;EAAA,SAcS,MAAA,EAAQ,MAAA;EAXjB;EAAA,SAcS,SAAA;EAXT;EAcA,KAAA,CAAM,IAAA,WAAe,MAAA;AAAA;AARvB;;;AAAA,UAciB,yBAAA;EAZN;EAcT,UAAA,EAAY,yBAAA;EAXH;EAcT,KAAA;AAAA;;;;KAUU,gBAAA;EACN,IAAA;AAAA;EACA,IAAA;EAAe,KAAA,EAAO,KAAA;AAAA;EACtB,IAAA;EAAgB,IAAA;EAAc,MAAA;AAAA;EAC9B,IAAA;EAA8B,QAAA;AAAA;EAC9B,IAAA;AAAA;;;;;;;;;;;AAoBN;;;;KAAY,oBAAA;EACN,MAAA;EAAwB,MAAA,GAAS,gBAAA;AAAA;EACjC,MAAA;EAAsB,OAAA;AAAA;EACtB,MAAA;AAAA;EACA,MAAA;AAAA;EACA,MAAA;EAAwB,OAAA;EAAiB,aAAA;AAAA;;;AAa/C;;KAPY,8BAAA,GACV,eAAA,CAAgB,oBAAA;;;AAkBlB;;KAZY,oBAAA,GAAqB,kBAAA,CAA0B,oBAAA;;;;;;;iBAY3C,qBAAA,CAAsB,EAAA,EAAI,SAAA,GAAY,MAAA;;;;;;;UAkErC,iBAAA;EACf,IAAA,CAAK,IAAA,EAAM,UAAA;EACX,KAAA,CAAM,IAAA,WAAe,MAAA;EACrB,EAAA,CACE,KAAA,aACA,OAAA,GAAU,IAAA,EAAM,MAAA,GAAS,WAAA,WAAsB,QAAA;EAEjD,EAAA,CAAG,KAAA,WAAgB,OAAA,GAAU,IAAA,UAAc,MAAA,EAAQ,MAAA;EACnD,EAAA,CAAG,KAAA,WAAgB,OAAA,GAAU,KAAA,EAAO,KAAA;EACpC,UAAA;AAAA;;;;;;iBAQc,iBAAA,CAAkB,EAAA,EAAI,iBAAA,GAAoB,MAAA"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kyneta/websocket-transport",
-  "version": "1.3.0",
-  "description": "Websocket network adapter for @kyneta/exchange — client, server, and Bun integration",
+  "version": "1.4.0",
+  "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,24 +33,24 @@
     "./src/*": "./src/*"
   },
   "peerDependencies": {
-    "@kyneta/transport": "^1.3.0",
-    "@kyneta/machine": "^1.3.0",
-    "@kyneta/wire": "^1.3.0"
+    "@kyneta/machine": "^1.4.0",
+    "@kyneta/transport": "^1.4.0",
+    "@kyneta/wire": "^1.4.0"
   },
   "devDependencies": {
     "@types/node": "^22",
     "bun-types": "latest",
-    "tsup": "^8.5.0",
+    "tsdown": "^0.21.9",
     "typescript": "^5.9.2",
     "vitest": "^4.0.17",
-    "@kyneta/exchange": "^1.3.0",
-    "@kyneta/transport": "^1.3.0",
-    "@kyneta/schema": "^1.3.0",
-    "@kyneta/wire": "^1.3.0",
-    "@kyneta/machine": "^1.3.0"
+    "@kyneta/exchange": "^1.4.0",
+    "@kyneta/schema": "^1.4.0",
+    "@kyneta/transport": "^1.4.0",
+    "@kyneta/wire": "^1.4.0",
+    "@kyneta/machine": "^1.4.0"
   },
   "scripts": {
-    "build": "tsup",
+    "build": "tsdown",
     "test": "verify logic",
     "verify": "verify"
   }

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

@@ -0,0 +1,167 @@
+// 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 type { PeerIdentityDetails, TransportContext } from "@kyneta/transport"
+import { describe, expect, it, vi } from "vitest"
+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([])
+  })
+})

package/src/{client.ts → browser.ts}

@@ -1,7 +1,10 @@
-// client — barrel export for @kyneta/websocket-network-adapter/client.
+// browser — barrel export for @kyneta/websocket-transport/browser.
 //
-// This is the client-side entry point. It exports everything needed
-// to create a Websocket client adapter for browser or service connections.
+// This is the browser-side entry point. It exports everything needed
+// to create a Websocket client transport for browser-to-server connections.
+//
+// Service-to-service connections (with headers) are in `./server`.
+// The `wrapStandardWebsocket` wrapper is a server-side concern — use `./server`.
 
 // ---------------------------------------------------------------------------
 // Client program (pure Mealy machine)
@@ -15,19 +18,14 @@ export {
 } from "./client-program.js"
 
 // ---------------------------------------------------------------------------
-// Client transport + factory functions
+// Client transport + factory function
 // ---------------------------------------------------------------------------
 
 export {
-  createServiceWebsocketClient,
   createWebsocketClient,
   DEFAULT_FRAGMENT_THRESHOLD,
-  type DisconnectReason,
-  type ServiceWebsocketClientOptions,
   type WebsocketClientLifecycleEvents,
   type WebsocketClientOptions,
-  type WebsocketClientState,
-  type WebsocketClientStateTransition,
   WebsocketClientTransport,
 } from "./client-transport.js"
 
@@ -36,9 +34,16 @@ export {
 // ---------------------------------------------------------------------------
 
 export type {
+  DisconnectReason,
   Socket,
   SocketReadyState,
   TransitionListener,
+  WebSocketCloseEvent,
+  WebSocketConstructor,
+  WebSocketLike,
+  WebSocketMessageEvent,
+  WebsocketClientState,
+  WebsocketClientStateTransition,
 } from "./types.js"
 
-export { wrapStandardWebsocket } from "./types.js"
+export { READY_STATE } from "./types.js"

package/src/bun-websocket.ts

@@ -1,4 +1,4 @@
-// bun-websocket — Bun-specific Websocket wrapper for @kyneta/websocket-network-adapter.
+// bun-websocket — Bun-specific Websocket wrapper for @kyneta/websocket-transport.
 //
 // Provides a wrapper to adapt Bun's ServerWebSocket to the Socket interface
 // expected by WebsocketServerTransport.
@@ -50,8 +50,8 @@ export type BunWebsocketData = {
  *
  * @example
  * ```typescript
- * import { WebsocketServerTransport } from "@kyneta/websocket-network-adapter/server"
- * import { wrapBunWebsocket, type BunWebsocketData } from "@kyneta/websocket-network-adapter/bun"
+ * import { WebsocketServerTransport } from "@kyneta/websocket-transport/server"
+ * import { wrapBunWebsocket, type BunWebsocketData } from "@kyneta/websocket-transport/bun"
  *
  * const serverAdapter = new WebsocketServerTransport()
  *
@@ -123,8 +123,8 @@ export function wrapBunWebsocket(
  *
  * @example
  * ```typescript
- * import { WebsocketServerTransport } from "@kyneta/websocket-network-adapter/server"
- * import { createBunWebsocketHandlers, type BunWebsocketData } from "@kyneta/websocket-network-adapter/bun"
+ * import { WebsocketServerTransport } from "@kyneta/websocket-transport/server"
+ * import { createBunWebsocketHandlers, type BunWebsocketData } from "@kyneta/websocket-transport/bun"
  *
  * const serverAdapter = new WebsocketServerTransport()
  *

package/src/bun.ts

@@ -1,4 +1,4 @@
-// bun — barrel export for @kyneta/websocket-network-adapter/bun.
+// bun — barrel export for @kyneta/websocket-transport/bun.
 //
 // This is the Bun-specific entry point. It exports everything needed
 // to integrate WebsocketServerTransport with Bun's WebSocket API.