@flighthq/socket 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './socket';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export * from './socket';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC"}

package/dist/socket.d.ts

@@ -0,0 +1,13 @@
+import type { Socket, SocketBackend, SocketOptions, SocketReadyState, SocketSignals } from '@flighthq/types';
+export declare function attachSocket(socket: Socket): void;
+export declare function closeSocket(socket: Socket, code?: number, reason?: string): void;
+export declare function createSocket(options: Readonly<SocketOptions>): Socket;
+export declare function createWebSocketBackend(): SocketBackend;
+export declare function detachSocket(socket: Socket): void;
+export declare function disposeSocket(socket: Socket): void;
+export declare function enableSocketSignals(socket: Socket): SocketSignals;
+export declare function getSocketBackend(): SocketBackend;
+export declare function getSocketReadyState(socket: Readonly<Socket>): SocketReadyState;
+export declare function sendSocketMessage(socket: Readonly<Socket>, data: string | ArrayBuffer): boolean;
+export declare function setSocketBackend(backend: SocketBackend | null): void;
+//# sourceMappingURL=socket.d.ts.map

package/dist/socket.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"socket.d.ts","sourceRoot":"","sources":["../src/socket.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,MAAM,EACN,aAAa,EAKb,aAAa,EACb,gBAAgB,EAEhB,aAAa,EACd,MAAM,iBAAiB,CAAC;AAIzB,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAEjD;AAKD,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAKhF;AAOD,wBAAgB,YAAY,CAAC,OAAO,EAAE,QAAQ,CAAC,aAAa,CAAC,GAAG,MAAM,CAUrE;AAMD,wBAAgB,sBAAsB,IAAI,aAAa,CA0BtD;AAID,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAEjD;AAKD,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAIlD;AAKD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,CAWjE;AAGD,wBAAgB,gBAAgB,IAAI,aAAa,CAGhD;AAGD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,gBAAgB,CAE9E;AAID,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,OAAO,CAI/F;AAGD,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI,GAAG,IAAI,CAEpE"}

package/dist/socket.js

@@ -0,0 +1,155 @@
+import { createSignal, emitSignal } from '@flighthq/signals';
+// Resumes delivery of backend events to the socket's signals (idempotent). Pair with detachSocket.
+// createSocket leaves a new socket attached, so this is only needed to resume after detachSocket.
+export function attachSocket(socket) {
+    socket.runtime.delivering = true;
+}
+// Begins a clean close of the live connection. Transitions readyState connecting/open → 'closing';
+// the backend's close event later transitions it to 'closed'. A no-op when already closing or closed.
+// This is the connection command, distinct from disposeSocket (which releases the entity to GC).
+export function closeSocket(socket, code, reason) {
+    const runtime = socket.runtime;
+    if (runtime.readyState === 'closing' || runtime.readyState === 'closed')
+        return;
+    runtime.readyState = 'closing';
+    runtime.connection?.closeSocketConnection(code, reason);
+}
+// Allocates a Socket entity plus its runtime and opens the connection through the active backend,
+// wiring the backend's open/message/close/error into the socket's (still inert) signal group. The
+// socket starts in 'connecting' and is left attached (delivering). Enable signals with
+// enableSocketSignals to observe events. A backend that does not support the transport yields a null
+// connection and the socket stays in 'connecting' until closed.
+export function createSocket(options) {
+    const runtime = {
+        connection: null,
+        signals: null,
+        readyState: 'connecting',
+        delivering: true,
+    };
+    const socket = { url: options.url, runtime };
+    runtime.connection = getSocketBackend().openSocket(options, makeSocketEventSink(runtime));
+    return socket;
+}
+// Builds the default web backend over the DOM WebSocket. Created lazily by getSocketBackend — no
+// WebSocket is constructed at import time, so importing the package has no side effect. Returns a
+// null connection when WebSocket is unavailable (non-browser host) rather than throwing; raw TCP/UDP
+// is likewise unsupported here and only reachable through a native backend.
+export function createWebSocketBackend() {
+    return {
+        openSocket(options, events) {
+            if (typeof WebSocket === 'undefined')
+                return null;
+            const ws = options.protocols !== undefined
+                ? new WebSocket(options.url, options.protocols)
+                : new WebSocket(options.url);
+            ws.binaryType = options.binaryType ?? 'arraybuffer';
+            ws.onopen = () => events.handleSocketOpen();
+            ws.onmessage = (event) => events.handleSocketMessage(toSocketMessage(event.data));
+            ws.onclose = (event) => events.handleSocketClose({ code: event.code, reason: event.reason, wasClean: event.wasClean });
+            ws.onerror = () => events.handleSocketError();
+            return {
+                sendSocketFrame(data) {
+                    if (ws.readyState !== WebSocket.OPEN)
+                        return false;
+                    ws.send(data);
+                    return true;
+                },
+                closeSocketConnection(code, reason) {
+                    ws.close(code, reason);
+                },
+            };
+        },
+    };
+}
+// Stops delivery of backend events to the socket's signals. The live connection is untouched — use
+// closeSocket to close it. Safe to call repeatedly; resume with attachSocket.
+export function detachSocket(socket) {
+    socket.runtime.delivering = false;
+}
+// Releases the socket to garbage collection: closes the live connection if still open, stops event
+// delivery, and drops the signal group. Distinct from closeSocket — dispose is entity teardown, close
+// is the connection command. After dispose the socket is inert and should not be reused.
+export function disposeSocket(socket) {
+    closeSocket(socket);
+    detachSocket(socket);
+    socket.runtime.signals = null;
+}
+// Opts the socket into its typed event signals, allocating the group on first call and returning it
+// (idempotent — a later call returns the same group). A bare socket that never calls this keeps
+// runtime.signals null and pays no signal allocation or dispatch cost.
+export function enableSocketSignals(socket) {
+    const runtime = socket.runtime;
+    if (runtime.signals === null) {
+        runtime.signals = {
+            onSocketOpen: createSignal(),
+            onSocketMessage: createSignal(),
+            onSocketClose: createSignal(),
+            onSocketError: createSignal(),
+        };
+    }
+    return runtime.signals;
+}
+// The active socket backend, or a lazily-created web default. There is always a backend.
+export function getSocketBackend() {
+    if (_backend === null)
+        _backend = createWebSocketBackend();
+    return _backend;
+}
+// The socket's current connection phase, tracked on the runtime from backend events and closeSocket.
+export function getSocketReadyState(socket) {
+    return socket.runtime.readyState;
+}
+// Sends a text or binary frame over the live connection. Returns false — a sentinel, not a throw —
+// when the socket is not open or has no connection.
+export function sendSocketMessage(socket, data) {
+    const runtime = socket.runtime;
+    if (runtime.readyState !== 'open' || runtime.connection === null)
+        return false;
+    return runtime.connection.sendSocketFrame(data);
+}
+// Installs a native host socket backend (adding TCP/UDP); pass null to fall back to the web default.
+export function setSocketBackend(backend) {
+    _backend = backend;
+}
+let _backend = null;
+// Builds the backend→entity sink bound to one socket's runtime: it updates readyState and emits the
+// opt-in signals. Every handler is a no-op once the runtime stops delivering (detach/dispose), so a
+// late backend event after teardown fires nothing.
+function makeSocketEventSink(runtime) {
+    return {
+        handleSocketOpen() {
+            if (!runtime.delivering)
+                return;
+            runtime.readyState = 'open';
+            if (runtime.signals !== null)
+                emitSignal(runtime.signals.onSocketOpen);
+        },
+        handleSocketMessage(message) {
+            if (!runtime.delivering)
+                return;
+            if (runtime.signals !== null)
+                emitSignal(runtime.signals.onSocketMessage, message);
+        },
+        handleSocketClose(info) {
+            if (!runtime.delivering)
+                return;
+            runtime.readyState = 'closed';
+            if (runtime.signals !== null)
+                emitSignal(runtime.signals.onSocketClose, info);
+        },
+        handleSocketError() {
+            if (!runtime.delivering)
+                return;
+            if (runtime.signals !== null)
+                emitSignal(runtime.signals.onSocketError);
+        },
+    };
+}
+// Maps a raw WebSocket message payload onto a SocketMessage. A string is a text frame; anything else
+// (with binaryType 'arraybuffer', an ArrayBuffer) is a binary frame.
+function toSocketMessage(data) {
+    if (typeof data === 'string')
+        return { data, binary: false };
+    return { data: data, binary: true };
+}
+//# sourceMappingURL=socket.js.map

package/dist/socket.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"socket.js","sourceRoot":"","sources":["../src/socket.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@flighthq/socket",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src/**/*.test.ts",
+    "!dist/**/*.test.js",
+    "!dist/**/*.test.d.ts",
+    "!dist/**/*.test.js.map",
+    "!dist/**/*.test.d.ts.map"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "tsc -b --clean",
+    "test": "vitest run --config vitest.config.ts",
+    "test:watch": "vitest --watch --config vitest.config.ts",
+    "prepack": "npm run clean && npm run clean:dist && npm run build",
+    "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
+  },
+  "dependencies": {
+    "@flighthq/signals": "0.1.0",
+    "@flighthq/types": "0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0"
+  },
+  "description": "Bidirectional persistent-connection transport (Socket/WebSocket) over a swappable web/native backend (WebSocket by default)",
+  "sideEffects": false
+}

package/src/socket.test.ts

@@ -0,0 +1,443 @@
+import { connectSignal } from '@flighthq/signals';
+import type { SocketBackend, SocketCloseInfo, SocketConnection, SocketEventSink, SocketMessage } from '@flighthq/types';
+
+import {
+  attachSocket,
+  closeSocket,
+  createSocket,
+  createWebSocketBackend,
+  detachSocket,
+  disposeSocket,
+  enableSocketSignals,
+  getSocketBackend,
+  getSocketReadyState,
+  sendSocketMessage,
+  setSocketBackend,
+} from './socket';
+
+interface FakeSocket {
+  backend: SocketBackend;
+  sink: SocketEventSink;
+  sent: (string | ArrayBuffer)[];
+  closes: { code?: number; reason?: string }[];
+  openReturnsNull: boolean;
+  sendReturns: boolean;
+  lastOptions: { url: string; protocols?: readonly string[]; binaryType?: string } | null;
+}
+
+// A mock SocketBackend that records the sink handed to openSocket (so a test can drive
+// open/message/close/error) and captures every send/close. openSocket can be made to return a null
+// connection to exercise the unsupported-transport path.
+function fakeBackend(): FakeSocket {
+  const state: FakeSocket = {
+    sent: [],
+    closes: [],
+    openReturnsNull: false,
+    sendReturns: true,
+    lastOptions: null,
+    sink: null as unknown as SocketEventSink,
+    backend: null as unknown as SocketBackend,
+  };
+  state.backend = {
+    openSocket(options, events): SocketConnection | null {
+      state.sink = events;
+      state.lastOptions = { url: options.url, protocols: options.protocols, binaryType: options.binaryType };
+      if (state.openReturnsNull) return null;
+      return {
+        sendSocketFrame(data): boolean {
+          state.sent.push(data);
+          return state.sendReturns;
+        },
+        closeSocketConnection(code, reason): void {
+          state.closes.push({ code, reason });
+        },
+      };
+    },
+  };
+  return state;
+}
+
+afterEach(() => setSocketBackend(null));
+
+describe('attachSocket', () => {
+  it('resumes delivery after a detach', () => {
+    const fake = fakeBackend();
+    setSocketBackend(fake.backend);
+    const socket = createSocket({ url: 'ws://x' });
+    const signals = enableSocketSignals(socket);
+    let opens = 0;
+    connectSignal(signals.onSocketOpen, () => opens++);
+    detachSocket(socket);
+    attachSocket(socket);
+    fake.sink.handleSocketOpen();
+    expect(opens).toBe(1);
+  });
+});
+
+describe('closeSocket', () => {
+  it('transitions to closing and forwards code/reason to the connection', () => {
+    const fake = fakeBackend();
+    setSocketBackend(fake.backend);
+    const socket = createSocket({ url: 'ws://x' });
+    fake.sink.handleSocketOpen();
+    closeSocket(socket, 1000, 'bye');
+    expect(getSocketReadyState(socket)).toBe('closing');
+    expect(fake.closes).toEqual([{ code: 1000, reason: 'bye' }]);
+  });
+
+  it('reaches closed once the backend close event arrives', () => {
+    const fake = fakeBackend();
+    setSocketBackend(fake.backend);
+    const socket = createSocket({ url: 'ws://x' });
+    fake.sink.handleSocketOpen();
+    closeSocket(socket);
+    fake.sink.handleSocketClose({ code: 1000, reason: '', wasClean: true });
+    expect(getSocketReadyState(socket)).toBe('closed');
+  });
+
+  it('is a no-op when already closed', () => {
+    const fake = fakeBackend();
+    setSocketBackend(fake.backend);
+    const socket = createSocket({ url: 'ws://x' });
+    fake.sink.handleSocketOpen();
+    closeSocket(socket);
+    fake.sink.handleSocketClose({ code: 1000, reason: '', wasClean: true });
+    closeSocket(socket);
+    expect(fake.closes).toHaveLength(1);
+  });
+});
+
+describe('createSocket', () => {
+  it('opens through the backend in the connecting state and records the url', () => {
+    const fake = fakeBackend();
+    setSocketBackend(fake.backend);
+    const socket = createSocket({ url: 'ws://host/path' });
+    expect(socket.url).toBe('ws://host/path');
+    expect(getSocketReadyState(socket)).toBe('connecting');
+    expect(fake.lastOptions?.url).toBe('ws://host/path');
+  });
+
+  it('passes protocols and binaryType through to the backend', () => {
+    const fake = fakeBackend();
+    setSocketBackend(fake.backend);
+    createSocket({ url: 'ws://x', protocols: ['a', 'b'], binaryType: 'arraybuffer' });
+    expect(fake.lastOptions?.protocols).toEqual(['a', 'b']);
+    expect(fake.lastOptions?.binaryType).toBe('arraybuffer');
+  });
+
+  it('tolerates a null connection from an unsupported transport', () => {
+    const fake = fakeBackend();
+    fake.openReturnsNull = true;
+    setSocketBackend(fake.backend);
+    const socket = createSocket({ url: 'tcp://x' });
+    expect(getSocketReadyState(socket)).toBe('connecting');
+    expect(sendSocketMessage(socket, 'x')).toBe(false);
+  });
+
+  it('emits a text message with binary false and a binary message with binary true', () => {
+    const fake = fakeBackend();
+    setSocketBackend(fake.backend);
+    const socket = createSocket({ url: 'ws://x' });
+    const signals = enableSocketSignals(socket);
+    const received: SocketMessage[] = [];
+    connectSignal(signals.onSocketMessage, (m) => received.push(m));
+    fake.sink.handleSocketOpen();
+    fake.sink.handleSocketMessage({ data: 'hi', binary: false });
+    const buffer = new Uint8Array([1, 2]).buffer;
+    fake.sink.handleSocketMessage({ data: buffer, binary: true });
+    expect(received).toEqual([
+      { data: 'hi', binary: false },
+      { data: buffer, binary: true },
+    ]);
+  });
+
+  it('emits close info with code, reason, and wasClean', () => {
+    const fake = fakeBackend();
+    setSocketBackend(fake.backend);
+    const socket = createSocket({ url: 'ws://x' });
+    const signals = enableSocketSignals(socket);
+    const infos: SocketCloseInfo[] = [];
+    connectSignal(signals.onSocketClose, (i) => infos.push(i));
+    fake.sink.handleSocketClose({ code: 1006, reason: 'gone', wasClean: false });
+    expect(infos).toEqual([{ code: 1006, reason: 'gone', wasClean: false }]);
+  });
+
+  it('emits onSocketError', () => {
+    const fake = fakeBackend();
+    setSocketBackend(fake.backend);
+    const socket = createSocket({ url: 'ws://x' });
+    const signals = enableSocketSignals(socket);
+    let errors = 0;
+    connectSignal(signals.onSocketError, () => errors++);
+    fake.sink.handleSocketError();
+    expect(errors).toBe(1);
+  });
+});
+
+describe('createWebSocketBackend', () => {
+  it('constructs a WebSocket with url and protocols and sets binaryType', () => {
+    const restore = installFakeWebSocket();
+    try {
+      createWebSocketBackend().openSocket(
+        { url: 'ws://host', protocols: ['chat'], binaryType: 'arraybuffer' },
+        noopSink(),
+      );
+      const ws = FakeWebSocket.last!;
+      expect(ws.url).toBe('ws://host');
+      expect(ws.protocols).toEqual(['chat']);
+      expect(ws.binaryType).toBe('arraybuffer');
+    } finally {
+      restore();
+    }
+  });
+
+  it('translates an incoming string message to binary false', () => {
+    const restore = installFakeWebSocket();
+    try {
+      const received: SocketMessage[] = [];
+      createWebSocketBackend().openSocket({ url: 'ws://x' }, sinkCollecting(received));
+      FakeWebSocket.last!.onmessage!({ data: 'hello' } as MessageEvent);
+      expect(received).toEqual([{ data: 'hello', binary: false }]);
+    } finally {
+      restore();
+    }
+  });
+
+  it('translates an incoming ArrayBuffer message to binary true', () => {
+    const restore = installFakeWebSocket();
+    try {
+      const received: SocketMessage[] = [];
+      createWebSocketBackend().openSocket({ url: 'ws://x' }, sinkCollecting(received));
+      const buffer = new Uint8Array([9]).buffer;
+      FakeWebSocket.last!.onmessage!({ data: buffer } as MessageEvent);
+      expect(received[0]).toEqual({ data: buffer, binary: true });
+    } finally {
+      restore();
+    }
+  });
+
+  it('maps close events and open into the sink', () => {
+    const restore = installFakeWebSocket();
+    try {
+      let opened = false;
+      const closes: SocketCloseInfo[] = [];
+      const sink: SocketEventSink = {
+        ...noopSink(),
+        handleSocketOpen: () => (opened = true),
+        handleSocketClose: (i) => closes.push(i),
+      };
+      createWebSocketBackend().openSocket({ url: 'ws://x' }, sink);
+      const ws = FakeWebSocket.last!;
+      ws.onopen!(new Event('open'));
+      ws.onclose!({ code: 1000, reason: 'done', wasClean: true } as CloseEvent);
+      expect(opened).toBe(true);
+      expect(closes).toEqual([{ code: 1000, reason: 'done', wasClean: true }]);
+    } finally {
+      restore();
+    }
+  });
+
+  it('sends only when the WebSocket is OPEN and closes with code/reason', () => {
+    const restore = installFakeWebSocket();
+    try {
+      const connection = createWebSocketBackend().openSocket({ url: 'ws://x' }, noopSink())!;
+      const ws = FakeWebSocket.last!;
+      ws.readyState = FakeWebSocket.CONNECTING;
+      expect(connection.sendSocketFrame('x')).toBe(false);
+      ws.readyState = FakeWebSocket.OPEN;
+      expect(connection.sendSocketFrame('y')).toBe(true);
+      expect(ws.sent).toEqual(['y']);
+      connection.closeSocketConnection(1001, 'later');
+      expect(ws.closed).toEqual({ code: 1001, reason: 'later' });
+    } finally {
+      restore();
+    }
+  });
+
+  it('returns a null connection when WebSocket is unavailable', () => {
+    const original = (globalThis as { WebSocket?: unknown }).WebSocket;
+    (globalThis as { WebSocket?: unknown }).WebSocket = undefined;
+    try {
+      expect(createWebSocketBackend().openSocket({ url: 'ws://x' }, noopSink())).toBeNull();
+    } finally {
+      (globalThis as { WebSocket?: unknown }).WebSocket = original;
+    }
+  });
+});
+
+describe('detachSocket', () => {
+  it('stops backend events from reaching the signals', () => {
+    const fake = fakeBackend();
+    setSocketBackend(fake.backend);
+    const socket = createSocket({ url: 'ws://x' });
+    const signals = enableSocketSignals(socket);
+    let opens = 0;
+    connectSignal(signals.onSocketOpen, () => opens++);
+    detachSocket(socket);
+    fake.sink.handleSocketOpen();
+    expect(opens).toBe(0);
+  });
+});
+
+describe('disposeSocket', () => {
+  it('closes an open connection and detaches so later events fire no signal', () => {
+    const fake = fakeBackend();
+    setSocketBackend(fake.backend);
+    const socket = createSocket({ url: 'ws://x' });
+    const signals = enableSocketSignals(socket);
+    let messages = 0;
+    connectSignal(signals.onSocketMessage, () => messages++);
+    fake.sink.handleSocketOpen();
+    disposeSocket(socket);
+    expect(fake.closes).toHaveLength(1);
+    fake.sink.handleSocketMessage({ data: 'x', binary: false });
+    expect(messages).toBe(0);
+  });
+
+  it('is safe to call on a fresh socket', () => {
+    const fake = fakeBackend();
+    setSocketBackend(fake.backend);
+    const socket = createSocket({ url: 'ws://x' });
+    expect(() => disposeSocket(socket)).not.toThrow();
+  });
+});
+
+describe('enableSocketSignals', () => {
+  it('returns the same group on repeated calls', () => {
+    const fake = fakeBackend();
+    setSocketBackend(fake.backend);
+    const socket = createSocket({ url: 'ws://x' });
+    expect(enableSocketSignals(socket)).toBe(enableSocketSignals(socket));
+  });
+
+  it('leaves a bare socket without signals', () => {
+    const fake = fakeBackend();
+    setSocketBackend(fake.backend);
+    const socket = createSocket({ url: 'ws://x' });
+    expect(socket.runtime.signals).toBeNull();
+  });
+});
+
+describe('getSocketBackend', () => {
+  it('lazily returns a web backend by default', () => {
+    expect(typeof getSocketBackend().openSocket).toBe('function');
+  });
+
+  it('returns the installed backend', () => {
+    const fake = fakeBackend();
+    setSocketBackend(fake.backend);
+    expect(getSocketBackend()).toBe(fake.backend);
+  });
+});
+
+describe('getSocketReadyState', () => {
+  it('reflects connecting → open → closing → closed transitions', () => {
+    const fake = fakeBackend();
+    setSocketBackend(fake.backend);
+    const socket = createSocket({ url: 'ws://x' });
+    expect(getSocketReadyState(socket)).toBe('connecting');
+    fake.sink.handleSocketOpen();
+    expect(getSocketReadyState(socket)).toBe('open');
+    closeSocket(socket);
+    expect(getSocketReadyState(socket)).toBe('closing');
+    fake.sink.handleSocketClose({ code: 1000, reason: '', wasClean: true });
+    expect(getSocketReadyState(socket)).toBe('closed');
+  });
+});
+
+describe('sendSocketMessage', () => {
+  it('sends through the connection and returns true when open', () => {
+    const fake = fakeBackend();
+    setSocketBackend(fake.backend);
+    const socket = createSocket({ url: 'ws://x' });
+    fake.sink.handleSocketOpen();
+    expect(sendSocketMessage(socket, 'ping')).toBe(true);
+    expect(fake.sent).toEqual(['ping']);
+  });
+
+  it('returns false without throwing when not open', () => {
+    const fake = fakeBackend();
+    setSocketBackend(fake.backend);
+    const socket = createSocket({ url: 'ws://x' });
+    expect(sendSocketMessage(socket, 'ping')).toBe(false);
+    expect(fake.sent).toEqual([]);
+  });
+
+  it('propagates a false send result from the connection', () => {
+    const fake = fakeBackend();
+    fake.sendReturns = false;
+    setSocketBackend(fake.backend);
+    const socket = createSocket({ url: 'ws://x' });
+    fake.sink.handleSocketOpen();
+    expect(sendSocketMessage(socket, 'ping')).toBe(false);
+  });
+});
+
+describe('setSocketBackend', () => {
+  it('restores the lazy web default when passed null', () => {
+    const fake = fakeBackend();
+    setSocketBackend(fake.backend);
+    expect(getSocketBackend()).toBe(fake.backend);
+    setSocketBackend(null);
+    const web = getSocketBackend();
+    expect(web).not.toBe(fake.backend);
+    expect(typeof web.openSocket).toBe('function');
+  });
+});
+
+function noopSink(): SocketEventSink {
+  return {
+    handleSocketOpen() {},
+    handleSocketMessage() {},
+    handleSocketClose() {},
+    handleSocketError() {},
+  };
+}
+
+function sinkCollecting(received: SocketMessage[]): SocketEventSink {
+  return { ...noopSink(), handleSocketMessage: (m) => received.push(m) };
+}
+
+// A minimal stand-in for the DOM WebSocket, recording constructor args, sends, and close, and
+// exposing dispatchable onopen/onmessage/onclose/onerror handlers.
+class FakeWebSocket {
+  static CONNECTING = 0;
+  static OPEN = 1;
+  static CLOSING = 2;
+  static CLOSED = 3;
+  static last: FakeWebSocket | null = null;
+
+  url: string;
+  protocols?: readonly string[];
+  binaryType = 'blob';
+  readyState = FakeWebSocket.CONNECTING;
+  sent: (string | ArrayBuffer)[] = [];
+  closed: { code?: number; reason?: string } | null = null;
+  onopen: ((event: Event) => void) | null = null;
+  onmessage: ((event: MessageEvent) => void) | null = null;
+  onclose: ((event: CloseEvent) => void) | null = null;
+  onerror: ((event: Event) => void) | null = null;
+
+  constructor(url: string, protocols?: string | string[]) {
+    this.url = url;
+    if (protocols !== undefined) this.protocols = typeof protocols === 'string' ? [protocols] : protocols;
+    FakeWebSocket.last = this;
+  }
+
+  send(data: string | ArrayBuffer): void {
+    this.sent.push(data);
+  }
+
+  close(code?: number, reason?: string): void {
+    this.closed = { code, reason };
+  }
+}
+
+function installFakeWebSocket(): () => void {
+  const original = (globalThis as { WebSocket?: unknown }).WebSocket;
+  FakeWebSocket.last = null;
+  (globalThis as { WebSocket?: unknown }).WebSocket = FakeWebSocket;
+  return () => {
+    (globalThis as { WebSocket?: unknown }).WebSocket = original;
+  };
+}