@kyneta/websocket-transport 1.1.0 → 1.2.0

package/src/client.ts

@@ -4,7 +4,18 @@
 // to create a Websocket client adapter for browser or service connections.
 
 // ---------------------------------------------------------------------------
-// Client adapter + factory functions
+// Client program (pure Mealy machine)
+// ---------------------------------------------------------------------------
+
+export {
+  createWsClientProgram,
+  type WsClientEffect,
+  type WsClientMsg,
+  type WsClientProgramOptions,
+} from "./client-program.js"
+
+// ---------------------------------------------------------------------------
+// Client transport + factory functions
 // ---------------------------------------------------------------------------
 
 export {
@@ -20,12 +31,6 @@ export {
   WebsocketClientTransport,
 } from "./client-transport.js"
 
-// ---------------------------------------------------------------------------
-// State machine
-// ---------------------------------------------------------------------------
-
-export { WebsocketClientStateMachine } from "./client-state-machine.js"
-
 // ---------------------------------------------------------------------------
 // Shared types
 // ---------------------------------------------------------------------------

package/src/connection.ts

@@ -10,14 +10,11 @@
 // Ported from @loro-extended/adapter-websocket's WsConnection with
 // kyneta naming conventions and the kyneta wire format.
 
-import type { Channel, ChannelMsg, PeerId } from "@kyneta/exchange"
+import type { Channel, ChannelMsg, PeerId } from "@kyneta/transport"
 import {
-  cborCodec,
-  decodeBinaryFrame,
-  encodeComplete,
+  decodeBinaryMessages,
+  encodeBinaryAndSend,
   FragmentReassembler,
-  fragmentPayload,
-  wrapCompleteMessage,
 } from "@kyneta/wire"
 import type { Socket } from "./types.js"
 
@@ -126,18 +123,9 @@ export class WebsocketConnection {
       return
     }
 
-    const frame = encodeComplete(cborCodec, msg)
-
-    // 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))
-    }
+    encodeBinaryAndSend(msg, this.#fragmentThreshold, data =>
+      this.#socket.send(data),
+    )
   }
 
   /**
@@ -176,23 +164,17 @@ export class WebsocketConnection {
       return
     }
 
-    // Handle binary protocol messages through reassembler
-    const result = this.#reassembler.receiveRaw(data)
-
-    if (result.status === "complete") {
-      try {
-        const frame = decodeBinaryFrame(result.data)
-        const messages = cborCodec.decode(frame.content.payload)
+    // Handle binary protocol messages through shared decode pipeline
+    try {
+      const messages = decodeBinaryMessages(data, this.#reassembler)
+      if (messages) {
         for (const msg of messages) {
           this.#handleChannelMessage(msg)
         }
-      } catch (error) {
-        console.error("Failed to decode wire message:", error)
       }
-    } else if (result.status === "error") {
-      console.error("Fragment reassembly error:", result.error)
+    } catch (error) {
+      console.error("Failed to decode wire message:", error)
     }
-    // "pending" status means we're waiting for more fragments — nothing to do
   }
 
   /**

package/src/server-transport.ts

@@ -28,15 +28,13 @@
 // Ported from @loro-extended/adapter-websocket's WsServerNetworkAdapter with
 // kyneta naming conventions and the kyneta 5-message protocol.
 
-import type { ChannelMsg, GeneratedChannel, PeerId } from "@kyneta/exchange"
-import { Transport } from "@kyneta/exchange"
+import type { ChannelMsg, GeneratedChannel, PeerId } from "@kyneta/transport"
+import { Transport } from "@kyneta/transport"
 import {
   DEFAULT_FRAGMENT_THRESHOLD,
   WebsocketConnection,
-  type WebsocketConnectionConfig,
 } from "./connection.js"
 import type {
-  Socket,
   WebsocketConnectionOptions,
   WebsocketConnectionResult,
 } from "./types.js"

package/src/types.ts

@@ -12,7 +12,7 @@ import type {
   TransitionListener as GenericTransitionListener,
   PeerId,
   StateTransition,
-} from "@kyneta/exchange"
+} from "@kyneta/transport"
 
 // ---------------------------------------------------------------------------
 // Socket ready states
@@ -167,7 +167,9 @@ export type TransitionListener = GenericTransitionListener<WebsocketClientState>
 export function wrapStandardWebsocket(ws: WebSocket): Socket {
   return {
     send(data: Uint8Array | string): void {
-      ws.send(data)
+      ws.send(
+        typeof data === "string" ? data : (data as Uint8Array<ArrayBuffer>),
+      )
     },
 
     close(code?: number, reason?: string): void {

package/dist/chunk-5FHT54WT.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/types.ts"],"sourcesContent":["// types — framework-agnostic Websocket abstractions for @kyneta/websocket-network-adapter.\n//\n// The `Socket` interface decouples the adapter from any specific Websocket\n// library (browser WebSocket, Node `ws`, Bun ServerWebSocket). Platform-\n// specific wrappers (`wrapStandardWebsocket`, `wrapNodeWebsocket`,\n// `wrapBunWebsocket`) adapt concrete implementations to this interface.\n//\n// Ported from @loro-extended/adapter-websocket's WsSocket with kyneta\n// naming conventions applied.\n\nimport type {\n  TransitionListener as GenericTransitionListener,\n  PeerId,\n  StateTransition,\n} from \"@kyneta/exchange\"\n\n// ---------------------------------------------------------------------------\n// Socket ready states\n// ---------------------------------------------------------------------------\n\n/**\n * Websocket ready states — mirrors the standard WebSocket readyState\n * values as human-readable strings.\n */\nexport type SocketReadyState = \"connecting\" | \"open\" | \"closing\" | \"closed\"\n\n// ---------------------------------------------------------------------------\n// Socket interface\n// ---------------------------------------------------------------------------\n\n/**\n * Framework-agnostic Websocket interface.\n *\n * This allows the adapter to work with any Websocket library:\n * - Browser `WebSocket` via `wrapStandardWebsocket()`\n * - Node.js `ws` library via `wrapNodeWebsocket()`\n * - Bun `ServerWebSocket` via `wrapBunWebsocket()`\n *\n * The interface is intentionally minimal — only the operations the\n * adapter needs are exposed.\n */\nexport interface Socket {\n  /** Send binary or text data through the Websocket. */\n  send(data: Uint8Array | string): void\n\n  /** Close the Websocket connection. */\n  close(code?: number, reason?: string): void\n\n  /** Register a handler for incoming messages (binary or text). */\n  onMessage(handler: (data: Uint8Array | string) => void): void\n\n  /** Register a handler for connection close. */\n  onClose(handler: (code: number, reason: string) => void): void\n\n  /** Register a handler for errors. */\n  onError(handler: (error: Error) => void): void\n\n  /** The current ready state of the Websocket. */\n  readonly readyState: SocketReadyState\n}\n\n// ---------------------------------------------------------------------------\n// Connection types — used by server adapter\n// ---------------------------------------------------------------------------\n\n/**\n * Options for handling a new Websocket connection on the server.\n */\nexport interface WebsocketConnectionOptions {\n  /** The Websocket instance, wrapped in the Socket interface. */\n  socket: Socket\n\n  /** Optional peer ID extracted from the upgrade request. */\n  peerId?: PeerId\n\n  /** Optional authentication token from the upgrade request. */\n  authToken?: string\n}\n\n/**\n * Handle for an active Websocket connection.\n */\nexport interface WebsocketConnectionHandle {\n  /** The peer ID for this connection. */\n  readonly peerId: PeerId\n\n  /** The channel ID for this connection. */\n  readonly channelId: number\n\n  /** Close the connection. */\n  close(code?: number, reason?: string): void\n}\n\n/**\n * Result of handling a Websocket connection on the server.\n */\nexport interface WebsocketConnectionResult {\n  /** The connection handle for managing this peer. */\n  connection: WebsocketConnectionHandle\n\n  /** Call this to start processing messages. */\n  start(): void\n}\n\n// ---------------------------------------------------------------------------\n// Disconnect reason\n// ---------------------------------------------------------------------------\n\n/**\n * Discriminated union describing why a Websocket connection was lost.\n */\nexport type DisconnectReason =\n  | { type: \"intentional\" }\n  | { type: \"error\"; error: Error }\n  | { type: \"closed\"; code: number; reason: string }\n  | { type: \"max-retries-exceeded\"; attempts: number }\n  | { type: \"not-started\" }\n\n// ---------------------------------------------------------------------------\n// Connection state (for client adapter observability)\n// ---------------------------------------------------------------------------\n\n/**\n * All possible states of the Websocket client.\n *\n * State machine transitions:\n * ```\n * disconnected → connecting → connected → ready\n *                    ↓            ↓         ↓\n *               reconnecting ← ─ ┴ ─ ─ ─ ─ ┘\n *                    ↓\n *               connecting (retry)\n *                    ↓\n *               disconnected (max retries)\n * ```\n */\nexport type WebsocketClientState =\n  | { status: \"disconnected\"; reason?: DisconnectReason }\n  | { status: \"connecting\"; attempt: number }\n  | { status: \"connected\" }\n  | { status: \"ready\" }\n  | { status: \"reconnecting\"; attempt: number; nextAttemptMs: number }\n\n/**\n * A state transition event for websocket client states.\n * Specialized from the generic `StateTransition<S>`.\n */\nexport type WebsocketClientStateTransition =\n  StateTransition<WebsocketClientState>\n\n/**\n * Listener for websocket client state transitions.\n * Specialized from the generic `TransitionListener<S>`.\n */\nexport type TransitionListener = GenericTransitionListener<WebsocketClientState>\n\n// ---------------------------------------------------------------------------\n// Socket wrapper — standard WebSocket API (browser + Node ws)\n// ---------------------------------------------------------------------------\n\n/**\n * Wrap a standard `WebSocket` (browser or Node.js `ws` via `ws` package\n * in `WebSocket`-compatible mode) into the `Socket` interface.\n *\n * Handles `ArrayBuffer`, `Blob`, and string messages.\n */\nexport function wrapStandardWebsocket(ws: WebSocket): Socket {\n  return {\n    send(data: Uint8Array | string): void {\n      ws.send(data)\n    },\n\n    close(code?: number, reason?: string): void {\n      ws.close(code, reason)\n    },\n\n    onMessage(handler: (data: Uint8Array | string) => void): void {\n      ws.addEventListener(\"message\", event => {\n        if (event.data instanceof ArrayBuffer) {\n          handler(new Uint8Array(event.data))\n        } else if (typeof Blob !== \"undefined\" && event.data instanceof Blob) {\n          // Handle Blob data (browser)\n          event.data.arrayBuffer().then(buffer => {\n            handler(new Uint8Array(buffer))\n          })\n        } else {\n          handler(event.data as string)\n        }\n      })\n    },\n\n    onClose(handler: (code: number, reason: string) => void): void {\n      ws.addEventListener(\"close\", event => {\n        handler(event.code, event.reason)\n      })\n    },\n\n    onError(handler: (error: Error) => void): void {\n      ws.addEventListener(\"error\", _event => {\n        handler(new Error(\"WebSocket error\"))\n      })\n    },\n\n    get readyState(): SocketReadyState {\n      switch (ws.readyState) {\n        case WebSocket.CONNECTING:\n          return \"connecting\"\n        case WebSocket.OPEN:\n          return \"open\"\n        case WebSocket.CLOSING:\n          return \"closing\"\n        case WebSocket.CLOSED:\n          return \"closed\"\n        default:\n          return \"closed\"\n      }\n    },\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Socket wrapper — Node.js `ws` library (raw API, not WebSocket-compat)\n// ---------------------------------------------------------------------------\n\n/**\n * The minimal interface we need from the Node.js `ws` library's `WebSocket`.\n *\n * Using a structural type rather than importing `ws` — consumers provide\n * the actual `ws` instance, we just need these methods.\n */\nexport interface NodeWebsocketLike {\n  send(data: Uint8Array | string): void\n  close(code?: number, reason?: string): void\n  on(\n    event: \"message\",\n    handler: (data: Buffer | ArrayBuffer | string, isBinary: boolean) => void,\n  ): void\n  on(event: \"close\", handler: (code: number, reason: Buffer) => void): void\n  on(event: \"error\", handler: (error: Error) => void): void\n  readyState: number\n}\n\n/**\n * Wrap a Node.js `ws` library WebSocket into the `Socket` interface.\n *\n * Handles `Buffer` → `Uint8Array` conversion for binary messages.\n */\nexport function wrapNodeWebsocket(ws: NodeWebsocketLike): Socket {\n  const CONNECTING = 0\n  const OPEN = 1\n  const CLOSING = 2\n\n  return {\n    send(data: Uint8Array | string): void {\n      ws.send(data)\n    },\n\n    close(code?: number, reason?: string): void {\n      ws.close(code, reason)\n    },\n\n    onMessage(handler: (data: Uint8Array | string) => void): void {\n      ws.on(\n        \"message\",\n        (data: Buffer | ArrayBuffer | string, isBinary: boolean) => {\n          if (isBinary) {\n            if (data instanceof ArrayBuffer) {\n              handler(new Uint8Array(data))\n            } else if (typeof Buffer !== \"undefined\" && Buffer.isBuffer(data)) {\n              handler(new Uint8Array(data))\n            } else {\n              handler(new Uint8Array(data as unknown as ArrayBuffer))\n            }\n          } else {\n            if (typeof Buffer !== \"undefined\" && Buffer.isBuffer(data)) {\n              handler(data.toString(\"utf-8\"))\n            } else {\n              handler(data as string)\n            }\n          }\n        },\n      )\n    },\n\n    onClose(handler: (code: number, reason: string) => void): void {\n      ws.on(\"close\", (code: number, reason: Buffer) => {\n        handler(code, reason.toString())\n      })\n    },\n\n    onError(handler: (error: Error) => void): void {\n      ws.on(\"error\", handler)\n    },\n\n    get readyState(): SocketReadyState {\n      switch (ws.readyState) {\n        case CONNECTING:\n          return \"connecting\"\n        case OPEN:\n          return \"open\"\n        case CLOSING:\n          return \"closing\"\n        default:\n          return \"closed\"\n      }\n    },\n  }\n}\n"],"mappings":";AAsKO,SAAS,sBAAsB,IAAuB;AAC3D,SAAO;AAAA,IACL,KAAK,MAAiC;AACpC,SAAG,KAAK,IAAI;AAAA,IACd;AAAA,IAEA,MAAM,MAAe,QAAuB;AAC1C,SAAG,MAAM,MAAM,MAAM;AAAA,IACvB;AAAA,IAEA,UAAU,SAAoD;AAC5D,SAAG,iBAAiB,WAAW,WAAS;AACtC,YAAI,MAAM,gBAAgB,aAAa;AACrC,kBAAQ,IAAI,WAAW,MAAM,IAAI,CAAC;AAAA,QACpC,WAAW,OAAO,SAAS,eAAe,MAAM,gBAAgB,MAAM;AAEpE,gBAAM,KAAK,YAAY,EAAE,KAAK,YAAU;AACtC,oBAAQ,IAAI,WAAW,MAAM,CAAC;AAAA,UAChC,CAAC;AAAA,QACH,OAAO;AACL,kBAAQ,MAAM,IAAc;AAAA,QAC9B;AAAA,MACF,CAAC;AAAA,IACH;AAAA,IAEA,QAAQ,SAAuD;AAC7D,SAAG,iBAAiB,SAAS,WAAS;AACpC,gBAAQ,MAAM,MAAM,MAAM,MAAM;AAAA,MAClC,CAAC;AAAA,IACH;AAAA,IAEA,QAAQ,SAAuC;AAC7C,SAAG,iBAAiB,SAAS,YAAU;AACrC,gBAAQ,IAAI,MAAM,iBAAiB,CAAC;AAAA,MACtC,CAAC;AAAA,IACH;AAAA,IAEA,IAAI,aAA+B;AACjC,cAAQ,GAAG,YAAY;AAAA,QACrB,KAAK,UAAU;AACb,iBAAO;AAAA,QACT,KAAK,UAAU;AACb,iBAAO;AAAA,QACT,KAAK,UAAU;AACb,iBAAO;AAAA,QACT,KAAK,UAAU;AACb,iBAAO;AAAA,QACT;AACE,iBAAO;AAAA,MACX;AAAA,IACF;AAAA,EACF;AACF;AA6BO,SAAS,kBAAkB,IAA+B;AAC/D,QAAM,aAAa;AACnB,QAAM,OAAO;AACb,QAAM,UAAU;AAEhB,SAAO;AAAA,IACL,KAAK,MAAiC;AACpC,SAAG,KAAK,IAAI;AAAA,IACd;AAAA,IAEA,MAAM,MAAe,QAAuB;AAC1C,SAAG,MAAM,MAAM,MAAM;AAAA,IACvB;AAAA,IAEA,UAAU,SAAoD;AAC5D,SAAG;AAAA,QACD;AAAA,QACA,CAAC,MAAqC,aAAsB;AAC1D,cAAI,UAAU;AACZ,gBAAI,gBAAgB,aAAa;AAC/B,sBAAQ,IAAI,WAAW,IAAI,CAAC;AAAA,YAC9B,WAAW,OAAO,WAAW,eAAe,OAAO,SAAS,IAAI,GAAG;AACjE,sBAAQ,IAAI,WAAW,IAAI,CAAC;AAAA,YAC9B,OAAO;AACL,sBAAQ,IAAI,WAAW,IAA8B,CAAC;AAAA,YACxD;AAAA,UACF,OAAO;AACL,gBAAI,OAAO,WAAW,eAAe,OAAO,SAAS,IAAI,GAAG;AAC1D,sBAAQ,KAAK,SAAS,OAAO,CAAC;AAAA,YAChC,OAAO;AACL,sBAAQ,IAAc;AAAA,YACxB;AAAA,UACF;AAAA,QACF;AAAA,MACF;AAAA,IACF;AAAA,IAEA,QAAQ,SAAuD;AAC7D,SAAG,GAAG,SAAS,CAAC,MAAc,WAAmB;AAC/C,gBAAQ,MAAM,OAAO,SAAS,CAAC;AAAA,MACjC,CAAC;AAAA,IACH;AAAA,IAEA,QAAQ,SAAuC;AAC7C,SAAG,GAAG,SAAS,OAAO;AAAA,IACxB;AAAA,IAEA,IAAI,aAA+B;AACjC,cAAQ,GAAG,YAAY;AAAA,QACrB,KAAK;AACH,iBAAO;AAAA,QACT,KAAK;AACH,iBAAO;AAAA,QACT,KAAK;AACH,iBAAO;AAAA,QACT;AACE,iBAAO;AAAA,MACX;AAAA,IACF;AAAA,EACF;AACF;","names":[]}

package/src/__tests__/client-state-machine.test.ts

@@ -1,472 +0,0 @@
-// WebsocketClientStateMachine tests.
-//
-// Verifies the state machine's validated transitions, async microtask
-// delivery, waitForState/waitForStatus, and error handling.
-
-import { describe, expect, it, vi } from "vitest"
-import { WebsocketClientStateMachine } from "../client-state-machine.js"
-import type {
-  WebsocketClientState,
-  WebsocketClientStateTransition,
-} from "../types.js"
-
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-/** Drain the microtask queue so transition listeners fire. */
-async function flush(): Promise<void> {
-  await new Promise<void>(r => queueMicrotask(r))
-}
-
-// ---------------------------------------------------------------------------
-// Initial state
-// ---------------------------------------------------------------------------
-
-describe("WebsocketClientStateMachine — initial state", () => {
-  it("starts in disconnected state", () => {
-    const sm = new WebsocketClientStateMachine()
-    expect(sm.getState()).toEqual({ status: "disconnected" })
-    expect(sm.getStatus()).toBe("disconnected")
-  })
-
-  it("isReady() returns false initially", () => {
-    const sm = new WebsocketClientStateMachine()
-    expect(sm.isReady()).toBe(false)
-  })
-
-  it("isConnectedOrReady() returns false initially", () => {
-    const sm = new WebsocketClientStateMachine()
-    expect(sm.isConnectedOrReady()).toBe(false)
-  })
-})
-
-// ---------------------------------------------------------------------------
-// Valid transitions
-// ---------------------------------------------------------------------------
-
-describe("WebsocketClientStateMachine — valid transitions", () => {
-  it("disconnected → connecting", () => {
-    const sm = new WebsocketClientStateMachine()
-    sm.transition({ status: "connecting", attempt: 1 })
-    expect(sm.getStatus()).toBe("connecting")
-  })
-
-  it("connecting → connected", () => {
-    const sm = new WebsocketClientStateMachine()
-    sm.transition({ status: "connecting", attempt: 1 })
-    sm.transition({ status: "connected" })
-    expect(sm.getStatus()).toBe("connected")
-  })
-
-  it("connected → ready", () => {
-    const sm = new WebsocketClientStateMachine()
-    sm.transition({ status: "connecting", attempt: 1 })
-    sm.transition({ status: "connected" })
-    sm.transition({ status: "ready" })
-    expect(sm.getStatus()).toBe("ready")
-    expect(sm.isReady()).toBe(true)
-    expect(sm.isConnectedOrReady()).toBe(true)
-  })
-
-  it("connecting → disconnected", () => {
-    const sm = new WebsocketClientStateMachine()
-    sm.transition({ status: "connecting", attempt: 1 })
-    sm.transition({
-      status: "disconnected",
-      reason: { type: "error", error: new Error("fail") },
-    })
-    expect(sm.getStatus()).toBe("disconnected")
-  })
-
-  it("connecting → reconnecting", () => {
-    const sm = new WebsocketClientStateMachine()
-    sm.transition({ status: "connecting", attempt: 1 })
-    sm.transition({ status: "reconnecting", attempt: 1, nextAttemptMs: 1000 })
-    expect(sm.getStatus()).toBe("reconnecting")
-  })
-
-  it("connected → disconnected", () => {
-    const sm = new WebsocketClientStateMachine()
-    sm.transition({ status: "connecting", attempt: 1 })
-    sm.transition({ status: "connected" })
-    sm.transition({ status: "disconnected", reason: { type: "intentional" } })
-    expect(sm.getStatus()).toBe("disconnected")
-  })
-
-  it("connected → reconnecting", () => {
-    const sm = new WebsocketClientStateMachine()
-    sm.transition({ status: "connecting", attempt: 1 })
-    sm.transition({ status: "connected" })
-    sm.transition({ status: "reconnecting", attempt: 1, nextAttemptMs: 2000 })
-    expect(sm.getStatus()).toBe("reconnecting")
-  })
-
-  it("ready → disconnected", () => {
-    const sm = new WebsocketClientStateMachine()
-    sm.transition({ status: "connecting", attempt: 1 })
-    sm.transition({ status: "connected" })
-    sm.transition({ status: "ready" })
-    sm.transition({
-      status: "disconnected",
-      reason: { type: "closed", code: 1000, reason: "done" },
-    })
-    expect(sm.getStatus()).toBe("disconnected")
-  })
-
-  it("ready → reconnecting", () => {
-    const sm = new WebsocketClientStateMachine()
-    sm.transition({ status: "connecting", attempt: 1 })
-    sm.transition({ status: "connected" })
-    sm.transition({ status: "ready" })
-    sm.transition({ status: "reconnecting", attempt: 1, nextAttemptMs: 500 })
-    expect(sm.getStatus()).toBe("reconnecting")
-  })
-
-  it("reconnecting → connecting", () => {
-    const sm = new WebsocketClientStateMachine()
-    sm.transition({ status: "connecting", attempt: 1 })
-    sm.transition({ status: "reconnecting", attempt: 1, nextAttemptMs: 1000 })
-    sm.transition({ status: "connecting", attempt: 2 })
-    expect(sm.getStatus()).toBe("connecting")
-    expect((sm.getState() as { attempt: number }).attempt).toBe(2)
-  })
-
-  it("reconnecting → disconnected", () => {
-    const sm = new WebsocketClientStateMachine()
-    sm.transition({ status: "connecting", attempt: 1 })
-    sm.transition({ status: "reconnecting", attempt: 1, nextAttemptMs: 1000 })
-    sm.transition({
-      status: "disconnected",
-      reason: { type: "max-retries-exceeded", attempts: 10 },
-    })
-    expect(sm.getStatus()).toBe("disconnected")
-  })
-
-  it("full lifecycle: disconnect → connect → connected → ready → disconnect", () => {
-    const sm = new WebsocketClientStateMachine()
-    sm.transition({ status: "connecting", attempt: 1 })
-    sm.transition({ status: "connected" })
-    sm.transition({ status: "ready" })
-    sm.transition({ status: "disconnected", reason: { type: "intentional" } })
-    expect(sm.getStatus()).toBe("disconnected")
-  })
-})
-
-// ---------------------------------------------------------------------------
-// Invalid transitions
-// ---------------------------------------------------------------------------
-
-describe("WebsocketClientStateMachine — invalid transitions", () => {
-  it("rejects disconnected → connected (must go through connecting)", () => {
-    const sm = new WebsocketClientStateMachine()
-    expect(() => sm.transition({ status: "connected" })).toThrow(
-      "Invalid state transition: disconnected -> connected",
-    )
-  })
-
-  it("rejects disconnected → ready", () => {
-    const sm = new WebsocketClientStateMachine()
-    expect(() => sm.transition({ status: "ready" })).toThrow(
-      "Invalid state transition",
-    )
-  })
-
-  it("rejects disconnected → reconnecting", () => {
-    const sm = new WebsocketClientStateMachine()
-    expect(() =>
-      sm.transition({
-        status: "reconnecting",
-        attempt: 1,
-        nextAttemptMs: 1000,
-      }),
-    ).toThrow("Invalid state transition")
-  })
-
-  it("rejects connecting → ready (must go through connected)", () => {
-    const sm = new WebsocketClientStateMachine()
-    sm.transition({ status: "connecting", attempt: 1 })
-    expect(() => sm.transition({ status: "ready" })).toThrow(
-      "Invalid state transition: connecting -> ready",
-    )
-  })
-
-  it("rejects ready → connecting (must go through reconnecting)", () => {
-    const sm = new WebsocketClientStateMachine()
-    sm.transition({ status: "connecting", attempt: 1 })
-    sm.transition({ status: "connected" })
-    sm.transition({ status: "ready" })
-    expect(() => sm.transition({ status: "connecting", attempt: 2 })).toThrow(
-      "Invalid state transition: ready -> connecting",
-    )
-  })
-
-  it("allows forced invalid transitions with force: true", () => {
-    const sm = new WebsocketClientStateMachine()
-    sm.transition({ status: "ready" }, { force: true })
-    expect(sm.getStatus()).toBe("ready")
-  })
-})
-
-// ---------------------------------------------------------------------------
-// Async delivery via microtask
-// ---------------------------------------------------------------------------
-
-describe("WebsocketClientStateMachine — async delivery", () => {
-  it("delivers transitions asynchronously via microtask", async () => {
-    const sm = new WebsocketClientStateMachine()
-    const transitions: WebsocketClientStateTransition[] = []
-
-    sm.subscribeToTransitions(t => transitions.push(t))
-
-    sm.transition({ status: "connecting", attempt: 1 })
-
-    // Synchronously — listener has NOT been called yet
-    expect(transitions).toHaveLength(0)
-
-    // After microtask — listener is called
-    await flush()
-    expect(transitions).toHaveLength(1)
-    expect(transitions[0]!.from.status).toBe("disconnected")
-    expect(transitions[0]!.to.status).toBe("connecting")
-  })
-
-  it("batches multiple transitions in the same synchronous call stack", async () => {
-    const sm = new WebsocketClientStateMachine()
-    const transitions: WebsocketClientStateTransition[] = []
-
-    sm.subscribeToTransitions(t => transitions.push(t))
-
-    // Multiple transitions in one synchronous block
-    sm.transition({ status: "connecting", attempt: 1 })
-    sm.transition({ status: "connected" })
-    sm.transition({ status: "ready" })
-
-    // Nothing delivered yet
-    expect(transitions).toHaveLength(0)
-
-    // All three delivered in one batch
-    await flush()
-    expect(transitions).toHaveLength(3)
-    expect(transitions[0]!.to.status).toBe("connecting")
-    expect(transitions[1]!.to.status).toBe("connected")
-    expect(transitions[2]!.to.status).toBe("ready")
-  })
-
-  it("transitions have timestamps", async () => {
-    const sm = new WebsocketClientStateMachine()
-    const transitions: WebsocketClientStateTransition[] = []
-
-    sm.subscribeToTransitions(t => transitions.push(t))
-    sm.transition({ status: "connecting", attempt: 1 })
-
-    await flush()
-    expect(transitions[0]!.timestamp).toBeGreaterThan(0)
-    expect(typeof transitions[0]!.timestamp).toBe("number")
-  })
-
-  it("unsubscribe stops delivery", async () => {
-    const sm = new WebsocketClientStateMachine()
-    const transitions: WebsocketClientStateTransition[] = []
-
-    const unsub = sm.subscribeToTransitions(t => transitions.push(t))
-
-    sm.transition({ status: "connecting", attempt: 1 })
-    await flush()
-    expect(transitions).toHaveLength(1)
-
-    unsub()
-
-    sm.transition({ status: "connected" })
-    await flush()
-
-    // No more deliveries after unsubscribe
-    expect(transitions).toHaveLength(1)
-  })
-
-  it("multiple listeners all receive transitions", async () => {
-    const sm = new WebsocketClientStateMachine()
-    const a: WebsocketClientStateTransition[] = []
-    const b: WebsocketClientStateTransition[] = []
-
-    sm.subscribeToTransitions(t => a.push(t))
-    sm.subscribeToTransitions(t => b.push(t))
-
-    sm.transition({ status: "connecting", attempt: 1 })
-    await flush()
-
-    expect(a).toHaveLength(1)
-    expect(b).toHaveLength(1)
-  })
-
-  it("listener errors do not break other listeners", async () => {
-    const sm = new WebsocketClientStateMachine()
-    const received: string[] = []
-
-    // First listener throws
-    sm.subscribeToTransitions(() => {
-      throw new Error("boom")
-    })
-
-    // Second listener should still receive
-    sm.subscribeToTransitions(t => {
-      received.push(t.to.status)
-    })
-
-    // Suppress console.error for this test
-    const consoleError = vi.spyOn(console, "error").mockImplementation(() => {})
-
-    sm.transition({ status: "connecting", attempt: 1 })
-    await flush()
-
-    expect(received).toEqual(["connecting"])
-    consoleError.mockRestore()
-  })
-})
-
-// ---------------------------------------------------------------------------
-// waitForState / waitForStatus
-// ---------------------------------------------------------------------------
-
-describe("WebsocketClientStateMachine — waitForState", () => {
-  it("resolves immediately if already in desired state", async () => {
-    const sm = new WebsocketClientStateMachine()
-    const state = await sm.waitForState(s => s.status === "disconnected")
-    expect(state.status).toBe("disconnected")
-  })
-
-  it("resolves when the desired state is reached", async () => {
-    const sm = new WebsocketClientStateMachine()
-
-    const promise = sm.waitForState(s => s.status === "connected")
-
-    // Transition to connecting, then connected
-    sm.transition({ status: "connecting", attempt: 1 })
-    sm.transition({ status: "connected" })
-
-    const state = await promise
-    expect(state.status).toBe("connected")
-  })
-
-  it("rejects on timeout", async () => {
-    const sm = new WebsocketClientStateMachine()
-
-    await expect(
-      sm.waitForState(s => s.status === "ready", { timeoutMs: 50 }),
-    ).rejects.toThrow("Timeout waiting for state after 50ms")
-  })
-
-  it("cleans up listener after resolution", async () => {
-    const sm = new WebsocketClientStateMachine()
-
-    // We can't directly inspect listener count, but we can verify
-    // that the promise resolves correctly and doesn't leak
-    const promise = sm.waitForState(s => s.status === "connecting")
-    sm.transition({ status: "connecting", attempt: 1 })
-
-    const state = await promise
-    expect(state.status).toBe("connecting")
-  })
-})
-
-describe("WebsocketClientStateMachine — waitForStatus", () => {
-  it("resolves immediately if already in desired status", async () => {
-    const sm = new WebsocketClientStateMachine()
-    const state = await sm.waitForStatus("disconnected")
-    expect(state.status).toBe("disconnected")
-  })
-
-  it("resolves when the desired status is reached", async () => {
-    const sm = new WebsocketClientStateMachine()
-
-    const promise = sm.waitForStatus("ready")
-
-    sm.transition({ status: "connecting", attempt: 1 })
-    sm.transition({ status: "connected" })
-    sm.transition({ status: "ready" })
-
-    const state = await promise
-    expect(state.status).toBe("ready")
-  })
-
-  it("rejects on timeout", async () => {
-    const sm = new WebsocketClientStateMachine()
-
-    await expect(sm.waitForStatus("ready", { timeoutMs: 50 })).rejects.toThrow(
-      "Timeout",
-    )
-  })
-})
-
-// ---------------------------------------------------------------------------
-// reset
-// ---------------------------------------------------------------------------
-
-describe("WebsocketClientStateMachine — reset", () => {
-  it("resets to initial disconnected state", () => {
-    const sm = new WebsocketClientStateMachine()
-    sm.transition({ status: "connecting", attempt: 1 })
-    sm.transition({ status: "connected" })
-    sm.transition({ status: "ready" })
-    expect(sm.getStatus()).toBe("ready")
-
-    sm.reset()
-    expect(sm.getStatus()).toBe("disconnected")
-  })
-
-  it("clears pending transitions", async () => {
-    const sm = new WebsocketClientStateMachine()
-    const transitions: WebsocketClientStateTransition[] = []
-
-    sm.subscribeToTransitions(t => transitions.push(t))
-
-    sm.transition({ status: "connecting", attempt: 1 })
-    sm.reset() // Should clear the pending transition
-
-    await flush()
-
-    // The transition that happened before reset should still be delivered
-    // because it was already queued before reset() was called.
-    // But the state should be disconnected.
-    expect(sm.getStatus()).toBe("disconnected")
-  })
-})
-
-// ---------------------------------------------------------------------------
-// isConnectedOrReady
-// ---------------------------------------------------------------------------
-
-describe("WebsocketClientStateMachine — isConnectedOrReady", () => {
-  it("returns false for disconnected", () => {
-    const sm = new WebsocketClientStateMachine()
-    expect(sm.isConnectedOrReady()).toBe(false)
-  })
-
-  it("returns false for connecting", () => {
-    const sm = new WebsocketClientStateMachine()
-    sm.transition({ status: "connecting", attempt: 1 })
-    expect(sm.isConnectedOrReady()).toBe(false)
-  })
-
-  it("returns true for connected", () => {
-    const sm = new WebsocketClientStateMachine()
-    sm.transition({ status: "connecting", attempt: 1 })
-    sm.transition({ status: "connected" })
-    expect(sm.isConnectedOrReady()).toBe(true)
-  })
-
-  it("returns true for ready", () => {
-    const sm = new WebsocketClientStateMachine()
-    sm.transition({ status: "connecting", attempt: 1 })
-    sm.transition({ status: "connected" })
-    sm.transition({ status: "ready" })
-    expect(sm.isConnectedOrReady()).toBe(true)
-  })
-
-  it("returns false for reconnecting", () => {
-    const sm = new WebsocketClientStateMachine()
-    sm.transition({ status: "connecting", attempt: 1 })
-    sm.transition({ status: "reconnecting", attempt: 1, nextAttemptMs: 1000 })
-    expect(sm.isConnectedOrReady()).toBe(false)
-  })
-})