@kyneta/websocket-transport 1.1.0 → 1.3.0

package/src/client-transport.ts

@@ -1,44 +1,38 @@
-// client-adapter — Websocket client adapter for @kyneta/exchange.
+// client-transport — Websocket client transport for @kyneta/exchange.
 //
-// Connects to a Websocket server and handles bidirectional communication
-// using the kyneta wire format (CBOR codec + framing + fragmentation).
+// Thin imperative shell around the pure client program (client-program.ts).
+// The program produces data effects; this module interprets them as I/O.
 //
-// Features:
-// - State machine with validated transitions (disconnected → connecting → connected → ready)
-// - Exponential backoff reconnection with jitter
-// - Keepalive ping/pong (text frames, default 30s)
-// - Transport-level fragmentation for large payloads
-// - Observable connection state via subscribeToTransitions()
+// FC/IS design:
+// - client-program.ts: pure Mealy machine (functional core)
+// - client-transport.ts: effect executor (imperative shell)
 //
-// The connection handshake:
-// 1. Client creates Websocket, waits for open
-// 2. Server sends text "ready" signal
-// 3. Client creates channel + calls establishChannel()
-// 4. Synchronizer exchanges establish-request / establish-response
-//
-// Ported from @loro-extended/adapter-websocket's WsClientNetworkAdapter
-// with kyneta naming conventions and the kyneta 5-message protocol.
+// Uses the kyneta wire format (CBOR codec + framing + fragmentation)
+// for binary messages. Text frames carry the "ready" handshake and
+// keepalive ping/pong.
 
+import type { ObservableHandle, TransitionListener } from "@kyneta/machine"
+import { createObservableProgram } from "@kyneta/machine"
 import type {
   Channel,
   ChannelMsg,
   GeneratedChannel,
   PeerId,
   TransportFactory,
-} from "@kyneta/exchange"
-import { Transport } from "@kyneta/exchange"
+} from "@kyneta/transport"
+import { Transport } from "@kyneta/transport"
 import {
-  cborCodec,
-  decodeBinaryFrame,
-  encodeComplete,
+  decodeBinaryMessages,
+  encodeBinaryAndSend,
   FragmentReassembler,
-  fragmentPayload,
-  wrapCompleteMessage,
 } from "@kyneta/wire"
-import { WebsocketClientStateMachine } from "./client-state-machine.js"
+import {
+  createWsClientProgram,
+  type WsClientEffect,
+  type WsClientMsg,
+} from "./client-program.js"
 import type {
   DisconnectReason,
-  TransitionListener,
   WebsocketClientState,
   WebsocketClientStateTransition,
 } from "./types.js"
@@ -61,7 +55,7 @@ export type {
 export const DEFAULT_FRAGMENT_THRESHOLD = 100 * 1024
 
 /**
- * Options for the Websocket client adapter (browser connections).
+ * Options for the Websocket client transport (browser connections).
  */
 export interface WebsocketClientOptions {
   /** Websocket URL to connect to. Can be a string or a function of peerId. */
@@ -72,7 +66,7 @@ export interface WebsocketClientOptions {
 
   /** Reconnection options. */
   reconnect?: {
-    enabled: boolean
+    enabled?: boolean
     maxAttempts?: number
     baseDelay?: number
     maxDelay?: number
@@ -127,43 +121,37 @@ export interface ServiceWebsocketClientOptions extends WebsocketClientOptions {
   headers?: Record<string, string>
 }
 
-/**
- * Default reconnection options.
- */
-const DEFAULT_RECONNECT = {
-  enabled: true,
-  maxAttempts: 10,
-  baseDelay: 1000,
-  maxDelay: 30000,
-}
-
 // ---------------------------------------------------------------------------
 // WebsocketClientTransport
 // ---------------------------------------------------------------------------
 
 /**
- * Websocket client network adapter for @kyneta/exchange.
+ * Websocket client network transport for @kyneta/exchange.
  *
  * Connects to a Websocket server, sends and receives ChannelMsg via
  * the kyneta wire format (CBOR codec + framing + fragmentation).
  *
+ * Internally, the connection lifecycle is a `Program<Msg, Model, Fx>` —
+ * a pure Mealy machine whose transitions are deterministically testable.
+ * 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)
  */
 export class WebsocketClientTransport extends Transport<void> {
   #peerId?: PeerId
+  #options: ServiceWebsocketClientOptions
+  #WebSocketImpl: typeof globalThis.WebSocket
+
+  // Observable program handle — created in constructor, drives all state
+  #handle: ObservableHandle<WsClientMsg, WebsocketClientState>
+
+  // Executor-local I/O state — not in the program model
   #socket?: WebSocket
   #serverChannel?: Channel
   #keepaliveTimer?: ReturnType<typeof setInterval>
   #reconnectTimer?: ReturnType<typeof setTimeout>
-  #options: ServiceWebsocketClientOptions
-  #WebSocketImpl: typeof globalThis.WebSocket
-  #shouldReconnect = true
-  #wasConnectedBefore = false
-
-  // State machine
-  readonly #stateMachine = new WebsocketClientStateMachine()
 
   // Fragmentation
   readonly #fragmentThreshold: number
@@ -179,174 +167,115 @@ export class WebsocketClientTransport extends Transport<void> {
       timeoutMs: 10_000,
     })
 
+    const program = createWsClientProgram({
+      reconnect: options.reconnect,
+    })
+
+    this.#handle = createObservableProgram(program, (effect, dispatch) => {
+      this.#executeEffect(effect, dispatch)
+    })
+
     // Set up lifecycle event forwarding
     this.#setupLifecycleEvents()
   }
 
   // ==========================================================================
-  // Lifecycle event forwarding
+  // Effect executor — interprets data effects as I/O
   // ==========================================================================
 
-  #setupLifecycleEvents(): void {
-    this.#stateMachine.subscribeToTransitions(transition => {
-      // Forward to onStateChange callback
-      this.#options.lifecycle?.onStateChange?.(transition)
-
-      const { from, to } = transition
-
-      // onDisconnect: transitioning TO disconnected
-      if (to.status === "disconnected" && to.reason) {
-        this.#options.lifecycle?.onDisconnect?.(to.reason)
-      }
-
-      // onReconnecting: transitioning TO reconnecting
-      if (to.status === "reconnecting") {
-        this.#options.lifecycle?.onReconnecting?.(to.attempt, to.nextAttemptMs)
+  #executeEffect(
+    effect: WsClientEffect,
+    dispatch: (msg: WsClientMsg) => void,
+  ): void {
+    switch (effect.type) {
+      case "create-websocket": {
+        this.#doCreateWebsocket(dispatch)
+        break
       }
 
-      // onReconnected: from reconnecting/connecting TO connected/ready (after prior connection)
-      if (
-        this.#wasConnectedBefore &&
-        (from.status === "reconnecting" || from.status === "connecting") &&
-        (to.status === "connected" || to.status === "ready")
-      ) {
-        this.#options.lifecycle?.onReconnected?.()
-      }
-
-      // onReady: transitioning TO ready
-      if (to.status === "ready") {
-        this.#options.lifecycle?.onReady?.()
+      case "close-websocket": {
+        if (this.#socket) {
+          this.#socket.close(1000, "Client disconnecting")
+          this.#socket = undefined
+        }
+        break
       }
-    })
-  }
 
-  // ==========================================================================
-  // State observation API
-  // ==========================================================================
-
-  /**
-   * Get the current state of the connection.
-   */
-  getState(): WebsocketClientState {
-    return this.#stateMachine.getState()
-  }
-
-  /**
-   * Subscribe to state transitions.
-   * @returns Unsubscribe function
-   */
-  subscribeToTransitions(listener: TransitionListener): () => void {
-    return this.#stateMachine.subscribeToTransitions(listener)
-  }
-
-  /**
-   * Wait for a specific state.
-   */
-  waitForState(
-    predicate: (state: WebsocketClientState) => boolean,
-    options?: { timeoutMs?: number },
-  ): Promise<WebsocketClientState> {
-    return this.#stateMachine.waitForState(predicate, options)
-  }
-
-  /**
-   * Wait for a specific status.
-   */
-  waitForStatus(
-    status: WebsocketClientState["status"],
-    options?: { timeoutMs?: number },
-  ): Promise<WebsocketClientState> {
-    return this.#stateMachine.waitForStatus(status, options)
-  }
+      case "add-channel-and-establish": {
+        // Clean up previous channel if it exists (e.g. after reconnect)
+        if (this.#serverChannel) {
+          this.removeChannel(this.#serverChannel.channelId)
+          this.#serverChannel = undefined
+        }
 
-  /**
-   * Check if the client is ready (server ready signal received).
-   */
-  get isReady(): boolean {
-    return this.#stateMachine.isReady()
-  }
+        this.#serverChannel = this.addChannel()
 
-  // ==========================================================================
-  // Adapter abstract method implementations
-  // ==========================================================================
+        // Establish immediately — the server already signaled ready
+        this.establishChannel(this.#serverChannel.channelId)
+        break
+      }
 
-  protected generate(): GeneratedChannel {
-    return {
-      transportType: this.transportType,
-      send: (msg: ChannelMsg) => {
-        if (!this.#socket || this.#socket.readyState !== WebSocket.OPEN) {
-          return
+      case "remove-channel": {
+        if (this.#serverChannel) {
+          this.removeChannel(this.#serverChannel.channelId)
+          this.#serverChannel = undefined
         }
+        break
+      }
 
-        const frame = encodeComplete(cborCodec, msg)
+      case "start-reconnect-timer": {
+        this.#reconnectTimer = setTimeout(() => {
+          this.#reconnectTimer = undefined
+          dispatch({ type: "reconnect-timer-fired" })
+        }, effect.delayMs)
+        break
+      }
 
-        // Fragment large payloads for cloud infrastructure compatibility
-        if (
-          this.#fragmentThreshold > 0 &&
-          frame.length > this.#fragmentThreshold
-        ) {
-          const fragments = fragmentPayload(frame, this.#fragmentThreshold)
-          for (const fragment of fragments) {
-            this.#socket.send(fragment)
-          }
-        } else {
-          // Wrap with MESSAGE_COMPLETE prefix for transport layer consistency
-          this.#socket.send(wrapCompleteMessage(frame))
+      case "cancel-reconnect-timer": {
+        if (this.#reconnectTimer !== undefined) {
+          clearTimeout(this.#reconnectTimer)
+          this.#reconnectTimer = undefined
         }
-      },
-      stop: () => {
-        // Don't call disconnect() here — channel.stop() is called when
-        // the channel is removed, which can happen during handleClose().
-        // The actual disconnect is handled by onStop() or handleClose().
-      },
-    }
-  }
+        break
+      }
 
-  async onStart(): Promise<void> {
-    if (!this.identity) {
-      throw new Error(
-        "Adapter not properly initialized — identity not available",
-      )
-    }
-    this.#peerId = this.identity.peerId
-    this.#shouldReconnect = true
-    this.#wasConnectedBefore = false
-    await this.#connect()
-  }
+      case "start-keepalive": {
+        this.#startKeepalive()
+        break
+      }
 
-  async onStop(): Promise<void> {
-    this.#shouldReconnect = false
-    this.#reassembler.dispose()
-    this.#disconnect({ type: "intentional" })
+      case "stop-keepalive": {
+        this.#stopKeepalive()
+        break
+      }
+    }
   }
 
   // ==========================================================================
-  // Connection management
+  // WebSocket creation — the core I/O operation
   // ==========================================================================
 
   /**
-   * Connect to the Websocket server.
+   * Create a WebSocket and wire up event handlers to dispatch messages.
+   *
+   * The message handler is set up IMMEDIATELY after creation (before
+   * the open event) to handle the race condition where the server sends
+   * "ready" before the client's open promise resolves.
    */
-  async #connect(): Promise<void> {
-    const currentState = this.#stateMachine.getState()
-    if (currentState.status === "connecting") {
+  #doCreateWebsocket(dispatch: (msg: WsClientMsg) => void): void {
+    const peerId = this.#peerId
+    if (!peerId) {
+      dispatch({
+        type: "socket-error",
+        error: new Error("Cannot connect: peerId not set"),
+      })
       return
     }
 
-    if (!this.#peerId) {
-      throw new Error("Cannot connect: peerId not set")
-    }
-
-    // Determine attempt number
-    const attempt =
-      currentState.status === "reconnecting" ? currentState.attempt : 1
-
-    this.#stateMachine.transition({ status: "connecting", attempt })
-
     // Resolve URL
     const url =
       typeof this.#options.url === "function"
-        ? this.#options.url(this.#peerId)
+        ? this.#options.url(peerId)
         : this.#options.url
 
     try {
@@ -355,7 +284,6 @@ export class WebsocketClientTransport extends Transport<void> {
         this.#options.headers &&
         Object.keys(this.#options.headers).length > 0
       ) {
-        // Bun extends the standard WebSocket API with a non-standard constructor
         type BunWebSocketConstructor = new (
           url: string,
           options: { headers: Record<string, string> },
@@ -370,171 +298,112 @@ export class WebsocketClientTransport extends Transport<void> {
       }
       this.#socket.binaryType = "arraybuffer"
 
-      // IMPORTANT: Set up message handler IMMEDIATELY after creating the socket.
-      // This must happen BEFORE waiting for the open event to avoid a race
-      // condition where the server sends "ready" before the handler is attached.
-      this.#socket.addEventListener("message", event => {
-        this.#handleMessage(event)
-      })
-
-      await new Promise<void>((resolve, reject) => {
-        if (!this.#socket) {
-          reject(new Error("Socket not created"))
-          return
-        }
-
-        const onOpen = () => {
-          cleanup()
-          resolve()
-        }
-
-        const onError = (event: Event) => {
-          cleanup()
-          reject(new Error(`WebSocket connection failed: ${event}`))
-        }
+      const socket = this.#socket
 
-        const onClose = () => {
-          cleanup()
-          reject(new Error("WebSocket closed during connection"))
-        }
-
-        const cleanup = () => {
-          this.#socket?.removeEventListener("open", onOpen)
-          this.#socket?.removeEventListener("error", onError)
-          this.#socket?.removeEventListener("close", onClose)
-        }
-
-        this.#socket.addEventListener("open", onOpen)
-        this.#socket.addEventListener("error", onError)
-        this.#socket.addEventListener("close", onClose)
+      // Set up message handler IMMEDIATELY to handle the "ready" race condition.
+      // The server may send "ready" before the open event fires.
+      socket.addEventListener("message", (event: MessageEvent) => {
+        this.#handleMessage(event, dispatch)
       })
 
-      // Socket is now open — transition to connected
-      this.#stateMachine.transition({ status: "connected" })
+      // Track whether we've dispatched a terminal event for this connection attempt
+      let settled = false
+
+      const onOpen = () => {
+        cleanup()
+        settled = true
+        dispatch({ type: "socket-opened" })
+
+        // After open, set up permanent close handler for post-connection closes
+        socket.addEventListener("close", (event: CloseEvent) => {
+          dispatch({
+            type: "socket-closed",
+            code: event.code,
+            reason: event.reason,
+          })
+        })
+      }
 
-      // Set up close handler for disconnections after connection is established
-      this.#socket.addEventListener("close", event => {
-        this.#handleClose(event.code, event.reason)
-      })
+      const onError = () => {
+        if (settled) return
+        cleanup()
+        settled = true
+        dispatch({
+          type: "socket-error",
+          error: new Error("WebSocket connection failed"),
+        })
+      }
 
-      // Start keepalive
-      this.#startKeepalive()
+      const onClose = () => {
+        if (settled) return
+        cleanup()
+        settled = true
+        dispatch({
+          type: "socket-error",
+          error: new Error("WebSocket closed during connection"),
+        })
+      }
+
+      const cleanup = () => {
+        socket.removeEventListener("open", onOpen)
+        socket.removeEventListener("error", onError)
+        socket.removeEventListener("close", onClose)
+      }
 
-      // Note: Channel creation is deferred until we receive the "ready" signal
-      // from the server. This ensures the server is fully set up before we
-      // start sending messages.
+      socket.addEventListener("open", onOpen)
+      socket.addEventListener("error", onError)
+      socket.addEventListener("close", onClose)
     } catch (error) {
-      // Transition to reconnecting or disconnected
-      this.#scheduleReconnect({
-        type: "error",
+      dispatch({
+        type: "socket-error",
         error: error instanceof Error ? error : new Error(String(error)),
       })
     }
   }
 
-  /**
-   * Disconnect from the Websocket server.
-   */
-  #disconnect(reason: DisconnectReason): void {
-    this.#stopKeepalive()
-    this.#clearReconnectTimer()
-
-    if (this.#socket) {
-      this.#socket.close(1000, "Client disconnecting")
-      this.#socket = undefined
-    }
-
-    if (this.#serverChannel) {
-      this.removeChannel(this.#serverChannel.channelId)
-      this.#serverChannel = undefined
-    }
-
-    // Only transition if not already disconnected
-    const currentState = this.#stateMachine.getState()
-    if (currentState.status !== "disconnected") {
-      this.#stateMachine.transition({ status: "disconnected", reason })
-    }
-  }
-
   // ==========================================================================
-  // Message handling
+  // Message handling — I/O parsing logic
   // ==========================================================================
 
   /**
    * Handle incoming Websocket messages.
+   *
+   * Text frames carry the "ready" handshake and keepalive pong.
+   * Binary frames carry CBOR-encoded ChannelMsg.
    */
-  #handleMessage(event: MessageEvent): void {
+  #handleMessage(
+    event: MessageEvent,
+    dispatch: (msg: WsClientMsg) => void,
+  ): void {
     const data = event.data
 
     // Handle text messages (keepalive and ready signal)
     if (typeof data === "string") {
       if (data === "ready") {
-        this.#handleServerReady()
+        dispatch({ type: "server-ready" })
       }
-      // Ignore pong responses
+      // Ignore pong responses and other text
       return
     }
 
-    // Handle binary messages through reassembler
+    // Handle binary messages through shared decode pipeline
     if (data instanceof ArrayBuffer) {
-      const result = this.#reassembler.receiveRaw(new Uint8Array(data))
-
-      if (result.status === "complete") {
-        try {
-          const frame = decodeBinaryFrame(result.data)
-          const messages = cborCodec.decode(frame.content.payload)
+      try {
+        const messages = decodeBinaryMessages(
+          new Uint8Array(data),
+          this.#reassembler,
+        )
+        if (messages) {
           for (const msg of messages) {
             this.#handleChannelMessage(msg)
           }
-        } catch (error) {
-          console.error("Failed to decode message:", error)
         }
-      } else if (result.status === "error") {
-        console.error("Fragment reassembly error:", result.error)
+      } catch (error) {
+        console.error("Failed to decode message:", error)
       }
-      // "pending" status means we're waiting for more fragments — nothing to do
     }
   }
 
-  /**
-   * Handle the "ready" signal from the server.
-   *
-   * Creates the channel and starts the establishment handshake.
-   * The "ready" signal is a transport-level indicator that the server's
-   * Websocket handler is ready. After receiving it, we create our channel
-   * and send a real establish-request.
-   */
-  #handleServerReady(): void {
-    const currentState = this.#stateMachine.getState()
-    if (currentState.status === "ready") {
-      // Already received ready signal, ignore duplicate
-      return
-    }
-
-    // Handle race condition: if we receive "ready" while still in "connecting" state,
-    // the server sent the ready signal before our open promise resolved.
-    // Transition through "connected" first to maintain valid state machine transitions.
-    if (currentState.status === "connecting") {
-      this.#stateMachine.transition({ status: "connected" })
-    }
-
-    // Transition to ready state
-    this.#stateMachine.transition({ status: "ready" })
-    this.#wasConnectedBefore = true
-
-    // Create channel if not exists
-    if (this.#serverChannel) {
-      this.removeChannel(this.#serverChannel.channelId)
-      this.#serverChannel = undefined
-    }
-
-    this.#serverChannel = this.addChannel()
-
-    // Send real establish-request over the wire
-    // The server will respond with establish-response containing its actual identity
-    this.establishChannel(this.#serverChannel.channelId)
-  }
-
   /**
    * Handle a decoded channel message.
    */
@@ -547,21 +416,6 @@ export class WebsocketClientTransport extends Transport<void> {
     this.#serverChannel.onReceive(msg)
   }
 
-  /**
-   * Handle Websocket close.
-   */
-  #handleClose(code: number, reason: string): void {
-    this.#stopKeepalive()
-
-    if (this.#serverChannel) {
-      this.removeChannel(this.#serverChannel.channelId)
-      this.#serverChannel = undefined
-    }
-
-    // Schedule reconnect or transition to disconnected
-    this.#scheduleReconnect({ type: "closed", code, reason })
-  }
-
   // ==========================================================================
   // Keepalive
   // ==========================================================================
@@ -586,70 +440,131 @@ export class WebsocketClientTransport extends Transport<void> {
   }
 
   // ==========================================================================
-  // Reconnection
+  // Lifecycle event forwarding
+  // ==========================================================================
+
+  #setupLifecycleEvents(): void {
+    // wasConnectedBefore is observer-local state, not in the program model
+    let wasConnectedBefore = false
+
+    this.#handle.subscribeToTransitions(transition => {
+      // Forward to onStateChange callback
+      this.#options.lifecycle?.onStateChange?.(transition)
+
+      const { from, to } = transition
+
+      // onDisconnect: transitioning TO disconnected
+      if (to.status === "disconnected" && to.reason) {
+        this.#options.lifecycle?.onDisconnect?.(to.reason)
+      }
+
+      // onReconnecting: transitioning TO reconnecting
+      if (to.status === "reconnecting") {
+        this.#options.lifecycle?.onReconnecting?.(to.attempt, to.nextAttemptMs)
+      }
+
+      // onReconnected: from reconnecting/connecting TO connected/ready (after prior connection)
+      if (
+        wasConnectedBefore &&
+        (from.status === "reconnecting" || from.status === "connecting") &&
+        (to.status === "connected" || to.status === "ready")
+      ) {
+        this.#options.lifecycle?.onReconnected?.()
+      }
+
+      // onReady: transitioning TO ready
+      if (to.status === "ready") {
+        this.#options.lifecycle?.onReady?.()
+        wasConnectedBefore = true
+      }
+    })
+  }
+
+  // ==========================================================================
+  // State observation — delegated to the observable handle
   // ==========================================================================
 
   /**
-   * Schedule a reconnection attempt or transition to disconnected.
+   * Get the current connection state.
    */
-  #scheduleReconnect(reason: DisconnectReason): void {
-    const currentState = this.#stateMachine.getState()
-
-    // If already disconnected, don't transition again
-    if (currentState.status === "disconnected") {
-      return
-    }
+  getState(): WebsocketClientState {
+    return this.#handle.getState()
+  }
 
-    const reconnectOpts = {
-      ...DEFAULT_RECONNECT,
-      ...this.#options.reconnect,
-    }
+  /**
+   * Subscribe to state transitions.
+   */
+  subscribeToTransitions(
+    listener: TransitionListener<WebsocketClientState>,
+  ): () => void {
+    return this.#handle.subscribeToTransitions(listener)
+  }
 
-    if (!this.#shouldReconnect || !reconnectOpts.enabled) {
-      this.#stateMachine.transition({ status: "disconnected", reason })
-      return
-    }
+  /**
+   * Wait for a specific state.
+   */
+  waitForState(
+    predicate: (state: WebsocketClientState) => boolean,
+    options?: { timeoutMs?: number },
+  ): Promise<WebsocketClientState> {
+    return this.#handle.waitForState(predicate, options)
+  }
 
-    // Get current attempt count from state
-    const currentAttempt =
-      currentState.status === "reconnecting"
-        ? currentState.attempt
-        : currentState.status === "connecting"
-          ? (currentState as { attempt: number }).attempt
-          : 0
-
-    if (currentAttempt >= reconnectOpts.maxAttempts) {
-      this.#stateMachine.transition({
-        status: "disconnected",
-        reason: { type: "max-retries-exceeded", attempts: currentAttempt },
-      })
-      return
-    }
+  /**
+   * Wait for a specific status.
+   */
+  waitForStatus(
+    status: WebsocketClientState["status"],
+    options?: { timeoutMs?: number },
+  ): Promise<WebsocketClientState> {
+    return this.#handle.waitForStatus(status, options)
+  }
 
-    const nextAttempt = currentAttempt + 1
+  /**
+   * Whether the client is ready (server ready signal received).
+   */
+  get isReady(): boolean {
+    return this.#handle.getState().status === "ready"
+  }
 
-    // Exponential backoff with jitter
-    const delay = Math.min(
-      reconnectOpts.baseDelay * 2 ** (nextAttempt - 1) + Math.random() * 1000,
-      reconnectOpts.maxDelay,
-    )
+  // ==========================================================================
+  // Transport abstract method implementations
+  // ==========================================================================
 
-    this.#stateMachine.transition({
-      status: "reconnecting",
-      attempt: nextAttempt,
-      nextAttemptMs: delay,
-    })
+  protected generate(): GeneratedChannel {
+    return {
+      transportType: this.transportType,
+      send: (msg: ChannelMsg) => {
+        const socket = this.#socket
+        if (!socket || socket.readyState !== WebSocket.OPEN) {
+          return
+        }
 
-    this.#reconnectTimer = setTimeout(() => {
-      this.#connect()
-    }, delay)
+        encodeBinaryAndSend(msg, this.#fragmentThreshold, data =>
+          socket.send(new Uint8Array(data).buffer),
+        )
+      },
+      stop: () => {
+        // Don't call disconnect here — channel.stop() is called when
+        // the channel is removed, which can happen during effect execution.
+        // The actual disconnect is handled by onStop() or the program.
+      },
+    }
   }
 
-  #clearReconnectTimer(): void {
-    if (this.#reconnectTimer) {
-      clearTimeout(this.#reconnectTimer)
-      this.#reconnectTimer = undefined
+  async onStart(): Promise<void> {
+    if (!this.identity) {
+      throw new Error(
+        "Transport not properly initialized — identity not available",
+      )
     }
+    this.#peerId = this.identity.peerId
+    this.#handle.dispatch({ type: "start" })
+  }
+
+  async onStop(): Promise<void> {
+    this.#reassembler.dispose()
+    this.#handle.dispatch({ type: "stop" })
   }
 }
 
@@ -658,14 +573,15 @@ export class WebsocketClientTransport extends Transport<void> {
 // ---------------------------------------------------------------------------
 
 /**
- * Create a Websocket client adapter factory for browser-to-server connections.
+ * Create a Websocket client transport factory for browser-to-server
+ * connections.
  *
- * Returns an `TransportFactory` — a closure that creates a fresh adapter
+ * Returns an `TransportFactory` — a closure that creates a fresh transport
  * instance when called. Pass directly to `Exchange({ transports: [...] })`.
  *
  * @example
  * ```typescript
- * import { createWebsocketClient } from "@kyneta/websocket-network-adapter/client"
+ * import { createWebsocketClient } from "@kyneta/websocket-transport/client"
  *
  * const exchange = new Exchange({
  *   transports: [createWebsocketClient({
@@ -682,7 +598,7 @@ export function createWebsocketClient(
 }
 
 /**
- * Create a Websocket client adapter for service-to-service connections.
+ * 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.
@@ -693,7 +609,7 @@ export function createWebsocketClient(
  *
  * @example
  * ```typescript
- * import { createServiceWebsocketClient } from "@kyneta/websocket-network-adapter/client"
+ * import { createServiceWebsocketClient } from "@kyneta/websocket-transport/client"
  *
  * const exchange = new Exchange({
  *   transports: [createServiceWebsocketClient({