@couch-kit/client 0.8.9 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # @couch-kit/client
 
+## 0.10.0
+
+### Minor Changes
+
+- [#141](https://github.com/faluciano/react-native-couch-kit/pull/141) [`5142ccd`](https://github.com/faluciano/react-native-couch-kit/commit/5142ccdb2ef37ab85cc57eac1e50f99b567cde70) Thanks [@faluciano](https://github.com/faluciano)! - Relay connections now address the room in the URL: the socket opens against
+  `<relayUrl>/r/<roomId>` instead of `<relayUrl>`, and the new `relayRoomUrl()`
+  helper builds it.
+
+  The `CREATE_ROOM` / `JOIN_ROOM` handshake is unchanged, so relays that hold
+  every room in one process (the Bun reference server in `services/relay`) ignore
+  the path and keep working. Putting the room in the URL lets a relay route a
+  connection _before_ reading any frames, which is what per-room hosting — such as
+  a Cloudflare Durable Object — requires.
+
+  No consumer code changes: both `createRelayTransport` and `RelayDisplayHost`
+  already take `roomId`, and build the URL themselves.
+
+## 0.9.0
+
+### Minor Changes
+
+- [#124](https://github.com/faluciano/react-native-couch-kit/pull/124) [`782d495`](https://github.com/faluciano/react-native-couch-kit/commit/782d4956c73918af35bff73410bf5e39d7261e56) Thanks [@faluciano](https://github.com/faluciano)! - **New features**
+
+  Add an injectable client transport so the web controller can connect over
+  transports other than the default LAN WebSocket. `useGameClient` now accepts a
+  `createTransport` factory, and the package exports a `ClientTransport` interface
+  plus `createWebSocketTransport` (the default).
+
+  Ship a cross-network relay transport (`createRelayTransport`) and the shared
+  relay wire protocol, enabling a hosted browser display to reach phones across
+  networks through a game-agnostic relay server. The default WebSocket behavior is
+  unchanged and fully backward compatible.
+
 ## 0.8.9
 
 ### Patch Changes

package/dist/index.js

@@ -17,6 +17,35 @@ import {
   DEFAULT_SYNC_INTERVAL,
   MAX_PENDING_PINGS
 } from "@couch-kit/core";
+
+// src/transport.ts
+var TransportReadyState = {
+  CONNECTING: 0,
+  OPEN: 1,
+  CLOSING: 2,
+  CLOSED: 3
+};
+function createWebSocketTransport(url) {
+  const ws = new WebSocket(url);
+  const transport = {
+    get readyState() {
+      return ws.readyState;
+    },
+    send(data) {
+      ws.send(data);
+    },
+    close(code, reason) {
+      ws.close(code, reason);
+    }
+  };
+  ws.onopen = () => transport.onopen?.();
+  ws.onmessage = (event) => transport.onmessage?.(event.data);
+  ws.onclose = (event) => transport.onclose?.(event.code, event.reason);
+  ws.onerror = (event) => transport.onerror?.(event);
+  return transport;
+}
+
+// src/time-sync.ts
 function calculateTimeSync(clientSendTime, clientReceiveTime, serverTime) {
   const rtt = clientReceiveTime - clientSendTime;
   const latency = rtt / 2;
@@ -43,7 +72,7 @@ function useServerTime(socket) {
     }
   }, []);
   useEffect(() => {
-    if (!socket || socket.readyState !== WebSocket.OPEN)
+    if (!socket || socket.readyState !== TransportReadyState.OPEN)
       return;
     const sync = () => {
       if (pings.current.size >= MAX_PENDING_PINGS) {
@@ -158,22 +187,29 @@ function useGameClient(config) {
   const connect = useCallback2(() => {
     const cfg = configRef.current;
     intentionalClose.current = false;
-    const wsUrl = resolveWebSocketUrl({ url: cfg.url, wsPort: cfg.wsPort }, typeof window !== "undefined" ? window.location : null);
-    if (!wsUrl)
-      return;
-    if (cfg.debug)
-      console.log(`[GameClient] Connecting to ${wsUrl}`);
+    let transport;
+    if (cfg.createTransport) {
+      if (cfg.debug)
+        console.log("[GameClient] Connecting via custom transport");
+      transport = cfg.createTransport();
+    } else {
+      const wsUrl = resolveWebSocketUrl({ url: cfg.url, wsPort: cfg.wsPort }, typeof window !== "undefined" ? window.location : null);
+      if (!wsUrl)
+        return;
+      if (cfg.debug)
+        console.log(`[GameClient] Connecting to ${wsUrl}`);
+      transport = createWebSocketTransport(wsUrl);
+    }
+    socketRef.current = transport;
     setStatus("connecting");
-    const ws = new WebSocket(wsUrl);
-    socketRef.current = ws;
-    ws.onopen = () => {
+    transport.onopen = () => {
       const currentCfg = configRef.current;
       setStatus("connected");
       reconnectAttempts.current = 0;
       currentCfg.onConnect?.();
       const secret = resolveSessionSecret(typeof localStorage !== "undefined" ? localStorage : null);
       try {
-        ws.send(JSON.stringify({
+        transport.send(JSON.stringify({
           type: MessageTypes3.JOIN,
           payload: {
             name: currentCfg.name || "Player",
@@ -186,10 +222,10 @@ function useGameClient(config) {
           console.error("[GameClient] Failed to send JOIN:", e);
       }
     };
-    ws.onmessage = (event) => {
+    transport.onmessage = (data) => {
       let msg;
       try {
-        msg = JSON.parse(event.data);
+        msg = JSON.parse(data);
       } catch (e) {
         console.error("Failed to parse message", e);
         return;
@@ -211,12 +247,12 @@ function useGameClient(config) {
         }
       }
     };
-    ws.onclose = (event) => {
+    transport.onclose = (code) => {
       setStatus("disconnected");
       configRef.current.onDisconnect?.();
       if (!shouldReconnect({
         intentionalClose: intentionalClose.current,
-        closeCode: event.code,
+        closeCode: code,
         attempts: reconnectAttempts.current,
         maxRetries
       }))
@@ -229,7 +265,7 @@ function useGameClient(config) {
         connect();
       }, delay);
     };
-    ws.onerror = (e) => {
+    transport.onerror = (e) => {
       if (configRef.current.debug)
         console.error("[GameClient] Error", e);
       setStatus("error");
@@ -264,7 +300,7 @@ function useGameClient(config) {
   }, [disconnect, connect]);
   const sendAction = useCallback2((action) => {
     dispatchLocal(action);
-    if (socketRef.current?.readyState === WebSocket.OPEN) {
+    if (socketRef.current?.readyState === TransportReadyState.OPEN) {
       socketRef.current.send(JSON.stringify({
         type: MessageTypes3.ACTION,
         payload: action
@@ -282,6 +318,107 @@ function useGameClient(config) {
     reconnect
   };
 }
+// src/relay-protocol.ts
+var RelayMessageTypes = {
+  CREATE_ROOM: "CREATE_ROOM",
+  ROOM_CREATED: "ROOM_CREATED",
+  JOIN_ROOM: "JOIN_ROOM",
+  ROOM_JOINED: "ROOM_JOINED",
+  PEER_JOINED: "PEER_JOINED",
+  PEER_LEFT: "PEER_LEFT",
+  DATA: "DATA",
+  ERROR: "ERROR"
+};
+var RelayErrorCodes = {
+  ROOM_NOT_FOUND: "ROOM_NOT_FOUND",
+  ROOM_EXISTS: "ROOM_EXISTS",
+  ROOM_FULL: "ROOM_FULL",
+  NOT_IN_ROOM: "NOT_IN_ROOM",
+  MESSAGE_TOO_LARGE: "MESSAGE_TOO_LARGE",
+  MALFORMED: "MALFORMED"
+};
+function relayRoomUrl(url, roomId) {
+  const trimmed = url.replace(/\/+$/, "");
+  const [base, query] = trimmed.split("?", 2);
+  const path = `${base}/r/${encodeURIComponent(roomId)}`;
+  return query ? `${path}?${query}` : path;
+}
+// src/relay-transport.ts
+var POLICY_CLOSE_CODE = 1008;
+
+class RelayClientTransport {
+  ws;
+  roomId;
+  state = TransportReadyState.CONNECTING;
+  pendingCloseCode = null;
+  onopen;
+  onmessage;
+  onclose;
+  onerror;
+  constructor(options) {
+    this.roomId = options.roomId;
+    this.ws = new WebSocket(relayRoomUrl(options.url, options.roomId));
+    this.ws.onopen = () => {
+      this.ws.send(JSON.stringify({
+        type: RelayMessageTypes.JOIN_ROOM,
+        roomId: this.roomId
+      }));
+    };
+    this.ws.onmessage = (event) => {
+      let msg;
+      try {
+        msg = JSON.parse(event.data);
+      } catch {
+        return;
+      }
+      this.handleRelayMessage(msg);
+    };
+    this.ws.onclose = (event) => {
+      this.state = TransportReadyState.CLOSED;
+      const code = this.pendingCloseCode ?? event.code;
+      this.onclose?.(code, event.reason);
+    };
+    this.ws.onerror = (event) => this.onerror?.(event);
+  }
+  get readyState() {
+    return this.state;
+  }
+  send(data) {
+    if (this.state !== TransportReadyState.OPEN)
+      return;
+    this.ws.send(JSON.stringify({
+      type: RelayMessageTypes.DATA,
+      roomId: this.roomId,
+      data
+    }));
+  }
+  close(code, reason) {
+    this.state = TransportReadyState.CLOSING;
+    if (code !== undefined && (code === 1000 || code >= 3000 && code <= 4999)) {
+      this.ws.close(code, reason);
+    } else {
+      this.ws.close();
+    }
+  }
+  handleRelayMessage(msg) {
+    switch (msg.type) {
+      case RelayMessageTypes.ROOM_JOINED:
+        this.state = TransportReadyState.OPEN;
+        this.onopen?.();
+        break;
+      case RelayMessageTypes.DATA:
+        this.onmessage?.(msg.data);
+        break;
+      case RelayMessageTypes.ERROR:
+        this.pendingCloseCode = POLICY_CLOSE_CODE;
+        this.ws.close();
+        break;
+    }
+  }
+}
+function createRelayTransport(options) {
+  return () => new RelayClientTransport(options);
+}
 // src/assets.ts
 import { useState as useState3, useEffect as useEffect3, useRef as useRef3 } from "react";
 import { MessageTypes as MessageTypes4 } from "@couch-kit/core";
@@ -424,8 +561,15 @@ export {
   shouldReconnect,
   resolveWebSocketUrl,
   resolveSessionSecret,
+  relayRoomUrl,
   interpretHostMessage,
+  createWebSocketTransport,
+  createRelayTransport,
   computeBackoffDelay,
   calculateTimeSync,
-  SESSION_SECRET_KEY
+  TransportReadyState,
+  SESSION_SECRET_KEY,
+  RelayMessageTypes,
+  RelayErrorCodes,
+  RelayClientTransport
 };

package/lib/client.d.ts

@@ -1,4 +1,5 @@
 import { type IGameState, type IAction } from "@couch-kit/core";
+import { type CreateClientTransport } from "./transport";
 export interface ClientConfig<S extends IGameState, A extends IAction> {
     url?: string;
     wsPort?: number;
@@ -15,6 +16,13 @@ export interface ClientConfig<S extends IGameState, A extends IAction> {
     onConnect?: () => void;
     onDisconnect?: () => void;
     debug?: boolean;
+    /**
+     * Provide a custom transport factory (e.g. a cross-network relay). When
+     * omitted, the client connects over the default LAN WebSocket derived from
+     * `url`/`wsPort`. Called on every (re)connect, so it must return a fresh,
+     * already-connecting transport each time.
+     */
+    createTransport?: CreateClientTransport;
 }
 /**
  * React hook that connects the web controller to the TV host via WebSocket.
@@ -35,7 +43,7 @@ export interface ClientConfig<S extends IGameState, A extends IAction> {
  * ```
  */
 export declare function useGameClient<S extends IGameState, A extends IAction>(config: ClientConfig<S, A>): {
-    status: "connecting" | "connected" | "disconnected" | "error";
+    status: "connected" | "connecting" | "disconnected" | "error";
     state: S;
     playerId: string | null;
     sendAction: (action: A) => void;

package/lib/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AACA,OAAO,EAQL,KAAK,UAAU,EACf,KAAK,OAAO,EAEb,MAAM,iBAAiB,CAAC;AAUzB,MAAM,WAAW,YAAY,CAAC,CAAC,SAAS,UAAU,EAAE,CAAC,SAAS,OAAO;IACnE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,KAAK,CAAC,CAAC;IACpC,YAAY,EAAE,CAAC,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,mEAAmE;IACnE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wEAAwE;IACxE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,IAAI,CAAC;IAC1B,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,UAAU,EAAE,CAAC,SAAS,OAAO,EACnE,MAAM,EAAE,YAAY,CAAC,CAAC,EAAE,CAAC,CAAC;;;;yBAoMc,CAAC;;IAqBvC,8EAA8E;;IAE9E,0EAA0E;;IAE1E,+EAA+E;;EAGlF"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AACA,OAAO,EAQL,KAAK,UAAU,EACf,KAAK,OAAO,EAEb,MAAM,iBAAiB,CAAC;AASzB,OAAO,EAIL,KAAK,qBAAqB,EAC3B,MAAM,aAAa,CAAC;AAErB,MAAM,WAAW,YAAY,CAAC,CAAC,SAAS,UAAU,EAAE,CAAC,SAAS,OAAO;IACnE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,KAAK,CAAC,CAAC;IACpC,YAAY,EAAE,CAAC,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,mEAAmE;IACnE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wEAAwE;IACxE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,IAAI,CAAC;IAC1B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;;;OAKG;IACH,eAAe,CAAC,EAAE,qBAAqB,CAAC;CACzC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,UAAU,EAAE,CAAC,SAAS,OAAO,EACnE,MAAM,EAAE,YAAY,CAAC,CAAC,EAAE,CAAC,CAAC;;;;yBA6Mc,CAAC;;IAqBvC,8EAA8E;;IAE9E,0EAA0E;;IAE1E,+EAA+E;;EAGlF"}

package/lib/index.d.ts

@@ -1,5 +1,8 @@
 export * from "./client";
 export * from "./connection";
+export * from "./transport";
+export * from "./relay-protocol";
+export * from "./relay-transport";
 export * from "./time-sync";
 export * from "./assets";
 export * from "./debug-panel";

package/lib/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AACzB,cAAc,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AACzB,cAAc,eAAe,CAAC"}

package/lib/relay-protocol.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Wire protocol for the cross-network **relay** transport.
+ *
+ * The relay is a small, game-agnostic WebSocket server that routes the existing
+ * Couch Kit JSON protocol between a browser **display host** (which owns the
+ * authoritative `GameHostRuntime`) and one or more **phones**, in a star
+ * topology keyed by a room id. The relay never inspects game payloads — it only
+ * tracks room membership and routes envelopes.
+ *
+ * These types are shared by the relay client transport (this package), the
+ * reference display host, and the relay server so all three agree on the wire
+ * format.
+ */
+/** Envelope/control message discriminators exchanged with the relay server. */
+export declare const RelayMessageTypes: {
+    /** Display → relay: create and host a room under `roomId`. */
+    readonly CREATE_ROOM: "CREATE_ROOM";
+    /** Relay → display: room created; includes the display's own `peerId`. */
+    readonly ROOM_CREATED: "ROOM_CREATED";
+    /** Phone → relay: join an existing room. */
+    readonly JOIN_ROOM: "JOIN_ROOM";
+    /** Relay → phone: joined; includes the phone's assigned `peerId`. */
+    readonly ROOM_JOINED: "ROOM_JOINED";
+    /** Relay → display: a phone joined the room. */
+    readonly PEER_JOINED: "PEER_JOINED";
+    /** Relay → display: a phone left the room. */
+    readonly PEER_LEFT: "PEER_LEFT";
+    /** Bidirectional: carries an opaque Couch Kit JSON message as `data`. */
+    readonly DATA: "DATA";
+    /** Relay → client: a protocol/room error. */
+    readonly ERROR: "ERROR";
+};
+/** Error codes the relay may report in an {@link RelayErrorMessage}. */
+export declare const RelayErrorCodes: {
+    readonly ROOM_NOT_FOUND: "ROOM_NOT_FOUND";
+    readonly ROOM_EXISTS: "ROOM_EXISTS";
+    readonly ROOM_FULL: "ROOM_FULL";
+    readonly NOT_IN_ROOM: "NOT_IN_ROOM";
+    readonly MESSAGE_TOO_LARGE: "MESSAGE_TOO_LARGE";
+    readonly MALFORMED: "MALFORMED";
+};
+export type RelayErrorCode = (typeof RelayErrorCodes)[keyof typeof RelayErrorCodes];
+/** Display → relay: create and host a room. */
+export interface CreateRoomMessage {
+    type: typeof RelayMessageTypes.CREATE_ROOM;
+    roomId: string;
+}
+/** Relay → display: room created; `peerId` is the display's own id. */
+export interface RoomCreatedMessage {
+    type: typeof RelayMessageTypes.ROOM_CREATED;
+    roomId: string;
+    peerId: string;
+}
+/** Phone → relay: join an existing room. */
+export interface JoinRoomMessage {
+    type: typeof RelayMessageTypes.JOIN_ROOM;
+    roomId: string;
+}
+/** Relay → phone: joined; `peerId` is the phone's relay-assigned id. */
+export interface RoomJoinedMessage {
+    type: typeof RelayMessageTypes.ROOM_JOINED;
+    roomId: string;
+    peerId: string;
+}
+/** Relay → display: a phone joined; `peerId` becomes its connection id. */
+export interface PeerJoinedMessage {
+    type: typeof RelayMessageTypes.PEER_JOINED;
+    roomId: string;
+    peerId: string;
+}
+/** Relay → display: a phone left. */
+export interface PeerLeftMessage {
+    type: typeof RelayMessageTypes.PEER_LEFT;
+    roomId: string;
+    peerId: string;
+}
+/**
+ * Bidirectional data envelope carrying an opaque Couch Kit JSON message.
+ *
+ * - Phone → relay: `data` only; the relay injects `from` and routes to the host.
+ * - Relay → display: `from` = sending phone's `peerId`.
+ * - Display → relay: `to` present = unicast to that phone; `to` absent =
+ *   broadcast to every phone in the room.
+ * - Relay → phone: `data` only.
+ *
+ * `data` is the already-serialized Couch Kit message string, so the relay
+ * treats it as opaque.
+ */
+export interface DataMessage {
+    type: typeof RelayMessageTypes.DATA;
+    roomId: string;
+    from?: string;
+    to?: string;
+    data: string;
+}
+/** Relay → client: a protocol/room error. */
+export interface RelayErrorMessage {
+    type: typeof RelayMessageTypes.ERROR;
+    code: RelayErrorCode;
+    message: string;
+}
+/** Any message a client may send to the relay. */
+export type RelayClientMessage = CreateRoomMessage | JoinRoomMessage | DataMessage;
+/** Any message the relay may send to a client. */
+export type RelayServerMessage = RoomCreatedMessage | RoomJoinedMessage | PeerJoinedMessage | PeerLeftMessage | DataMessage | RelayErrorMessage;
+/** Every relay wire message. */
+export type RelayMessage = RelayClientMessage | RelayServerMessage;
+/**
+ * Builds the socket URL for a room: the configured relay URL with `/r/<roomId>`
+ * appended.
+ *
+ * The room has to be in the URL, not just in the `CREATE_ROOM` / `JOIN_ROOM`
+ * message, so that a relay can route the connection before reading any frames —
+ * which is exactly what a per-room Cloudflare Durable Object must do. Relays
+ * that keep every room in one process (the Bun reference server) ignore the
+ * path, so this is safe to send to either.
+ *
+ * @param url - Base relay URL, e.g. `wss://relay.example.com`.
+ * @param roomId - Room code to address.
+ */
+export declare function relayRoomUrl(url: string, roomId: string): string;
+//# sourceMappingURL=relay-protocol.d.ts.map

package/lib/relay-protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relay-protocol.d.ts","sourceRoot":"","sources":["../src/relay-protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,+EAA+E;AAC/E,eAAO,MAAM,iBAAiB;IAC5B,8DAA8D;aAC9D,WAAW,EAAE,aAAa;IAC1B,0EAA0E;aAC1E,YAAY,EAAE,cAAc;IAC5B,4CAA4C;aAC5C,SAAS,EAAE,WAAW;IACtB,qEAAqE;aACrE,WAAW,EAAE,aAAa;IAC1B,gDAAgD;aAChD,WAAW,EAAE,aAAa;IAC1B,8CAA8C;aAC9C,SAAS,EAAE,WAAW;IACtB,yEAAyE;aACzE,IAAI,EAAE,MAAM;IACZ,6CAA6C;aAC7C,KAAK,EAAE,OAAO;CACN,CAAC;AAEX,wEAAwE;AACxE,eAAO,MAAM,eAAe;aAC1B,cAAc,EAAE,gBAAgB;aAChC,WAAW,EAAE,aAAa;aAC1B,SAAS,EAAE,WAAW;aACtB,WAAW,EAAE,aAAa;aAC1B,iBAAiB,EAAE,mBAAmB;aACtC,SAAS,EAAE,WAAW;CACd,CAAC;AAEX,MAAM,MAAM,cAAc,GACxB,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,OAAO,eAAe,CAAC,CAAC;AAEzD,+CAA+C;AAC/C,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,OAAO,iBAAiB,CAAC,WAAW,CAAC;IAC3C,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,uEAAuE;AACvE,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,OAAO,iBAAiB,CAAC,YAAY,CAAC;IAC5C,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,4CAA4C;AAC5C,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,OAAO,iBAAiB,CAAC,SAAS,CAAC;IACzC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,wEAAwE;AACxE,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,OAAO,iBAAiB,CAAC,WAAW,CAAC;IAC3C,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,2EAA2E;AAC3E,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,OAAO,iBAAiB,CAAC,WAAW,CAAC;IAC3C,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,qCAAqC;AACrC,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,OAAO,iBAAiB,CAAC,SAAS,CAAC;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,OAAO,iBAAiB,CAAC,IAAI,CAAC;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;CACd;AAED,6CAA6C;AAC7C,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,OAAO,iBAAiB,CAAC,KAAK,CAAC;IACrC,IAAI,EAAE,cAAc,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,kDAAkD;AAClD,MAAM,MAAM,kBAAkB,GAC1B,iBAAiB,GACjB,eAAe,GACf,WAAW,CAAC;AAEhB,kDAAkD;AAClD,MAAM,MAAM,kBAAkB,GAC1B,kBAAkB,GAClB,iBAAiB,GACjB,iBAAiB,GACjB,eAAe,GACf,WAAW,GACX,iBAAiB,CAAC;AAEtB,gCAAgC;AAChC,MAAM,MAAM,YAAY,GAAG,kBAAkB,GAAG,kBAAkB,CAAC;AAEnE;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAKhE"}

package/lib/relay-transport.d.ts

@@ -0,0 +1,49 @@
+import { type ClientTransport, type CreateClientTransport } from "./transport";
+/** Options for {@link createRelayTransport} / {@link RelayClientTransport}. */
+export interface RelayTransportOptions {
+    /** WebSocket URL of the relay server (e.g. `wss://relay.example.com`). */
+    url: string;
+    /** Room code identifying the display host to connect to. */
+    roomId: string;
+}
+/**
+ * A {@link ClientTransport} that reaches the display host through the
+ * cross-network relay instead of a direct LAN WebSocket.
+ *
+ * It opens a WebSocket to the relay, joins `roomId`, and then presents the same
+ * open/message/close surface as the default transport — wrapping each outbound
+ * game message in a relay `DATA` envelope and unwrapping inbound ones. Room-level
+ * failures (unknown/full room) are surfaced as a terminal close so the client's
+ * reconnect logic does not hammer a room that will never accept it.
+ */
+export declare class RelayClientTransport implements ClientTransport {
+    private readonly ws;
+    private readonly roomId;
+    private state;
+    /** When set, the code reported to `onclose` instead of the raw socket code. */
+    private pendingCloseCode;
+    onopen?: () => void;
+    onmessage?: (data: string) => void;
+    onclose?: (code: number, reason?: string) => void;
+    onerror?: (error?: unknown) => void;
+    constructor(options: RelayTransportOptions);
+    get readyState(): number;
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+    private handleRelayMessage;
+}
+/**
+ * Build a {@link CreateClientTransport} factory for `useGameClient` that
+ * connects through the relay.
+ *
+ * @example
+ * ```tsx
+ * useGameClient({
+ *   reducer,
+ *   initialState,
+ *   createTransport: createRelayTransport({ url: RELAY_URL, roomId }),
+ * });
+ * ```
+ */
+export declare function createRelayTransport(options: RelayTransportOptions): CreateClientTransport;
+//# sourceMappingURL=relay-transport.d.ts.map

package/lib/relay-transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relay-transport.d.ts","sourceRoot":"","sources":["../src/relay-transport.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAC3B,MAAM,aAAa,CAAC;AAOrB,+EAA+E;AAC/E,MAAM,WAAW,qBAAqB;IACpC,0EAA0E;IAC1E,GAAG,EAAE,MAAM,CAAC;IACZ,4DAA4D;IAC5D,MAAM,EAAE,MAAM,CAAC;CAChB;AASD;;;;;;;;;GASG;AACH,qBAAa,oBAAqB,YAAW,eAAe;IAC1D,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAY;IAC/B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,KAAK,CAA0C;IACvD,+EAA+E;IAC/E,OAAO,CAAC,gBAAgB,CAAuB;IAE/C,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;IACpB,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACnC,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IAClD,OAAO,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IAEpC,YAAY,OAAO,EAAE,qBAAqB,EAgCzC;IAED,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CASvB;IAED,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAQ1C;IAED,OAAO,CAAC,kBAAkB;CAkB3B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,qBAAqB,GAC7B,qBAAqB,CAEvB"}

package/lib/time-sync.d.ts

@@ -1,3 +1,4 @@
+import { type ClientTransport } from "./transport";
 /**
  * Computes the clock offset and round-trip time between client and server.
  *
@@ -24,10 +25,10 @@ export declare function calculateTimeSync(clientSendTime: number, clientReceiveT
  * called directly. Access `getServerTime()` and `rtt` from the
  * `useGameClient` return value instead.
  *
- * @param socket - The active WebSocket connection (or `null` if not yet connected).
+ * @param socket - The active client transport (or `null` if not yet connected).
  * @returns An object with `getServerTime` (returns estimated server time), `rtt`, and `handlePong` (callback for PONG messages).
  */
-export declare function useServerTime(socket: WebSocket | null): {
+export declare function useServerTime(socket: ClientTransport | null): {
     getServerTime: () => number;
     rtt: number;
     handlePong: (payload: {

package/lib/time-sync.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"time-sync.d.ts","sourceRoot":"","sources":["../src/time-sync.ts"],"names":[],"mappings":"AAaA;;;;;;;;;;;GAWG;AAEH,wBAAgB,iBAAiB,CAC/B,cAAc,EAAE,MAAM,EACtB,iBAAiB,EAAE,MAAM,EACzB,UAAU,EAAE,MAAM;;;EAQnB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI;;;0BAgBxC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE;EAgDtE"}
+{"version":3,"file":"time-sync.d.ts","sourceRoot":"","sources":["../src/time-sync.ts"],"names":[],"mappings":"AAOA,OAAO,EAAuB,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC;AAOxE;;;;;;;;;;;GAWG;AAEH,wBAAgB,iBAAiB,CAC/B,cAAc,EAAE,MAAM,EACtB,iBAAiB,EAAE,MAAM,EACzB,UAAU,EAAE,MAAM;;;EAQnB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI;;;0BAgB9C;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE;EAgDtE"}

package/lib/transport.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Transport abstraction for the web game client.
+ *
+ * The client hook (`useGameClient`) speaks to the host through a small
+ * WebSocket-shaped interface rather than a concrete `WebSocket`. This lets the
+ * default LAN WebSocket transport and alternative transports (e.g. a
+ * cross-network relay) be swapped in without touching the hook's JOIN handshake,
+ * reconnect/backoff, session-recovery, or state-hydration logic.
+ *
+ * The interface intentionally mirrors the subset of the `WebSocket` API the
+ * client relies on, so the default implementation is a thin wrapper and the
+ * behavior of the LAN path is unchanged.
+ */
+/**
+ * Ready-state constants mirroring the `WebSocket` readyState values. A transport
+ * reports these so the client can gate sends on an open connection without
+ * depending on the global `WebSocket` constructor (which may be absent in some
+ * runtimes/tests).
+ */
+export declare const TransportReadyState: {
+    readonly CONNECTING: 0;
+    readonly OPEN: 1;
+    readonly CLOSING: 2;
+    readonly CLOSED: 3;
+};
+/**
+ * The minimal message-transport surface the client requires.
+ *
+ * Implementations deliver and receive already-serialized JSON strings. Event
+ * callbacks are assigned by the client after construction, so a transport must
+ * begin connecting on construction and invoke `onopen` once ready.
+ */
+export interface ClientTransport {
+    /** Current connection state; compare against {@link TransportReadyState}. */
+    readonly readyState: number;
+    /** Send a serialized JSON message to the host. */
+    send(data: string): void;
+    /**
+     * Close the connection. `code`/`reason` follow WebSocket close semantics so
+     * the client's recoverable-vs-terminal reconnect logic keeps working
+     * (1008 policy / 1011 internal error are treated as terminal).
+     */
+    close(code?: number, reason?: string): void;
+    /** Invoked once the connection is open and ready to send. */
+    onopen?: () => void;
+    /** Invoked with the raw JSON string of each inbound host message. */
+    onmessage?: (data: string) => void;
+    /** Invoked when the connection closes, with a WebSocket-compatible code. */
+    onclose?: (code: number, reason?: string) => void;
+    /** Invoked on a transport-level error. */
+    onerror?: (error?: unknown) => void;
+}
+/**
+ * Factory that creates a fresh {@link ClientTransport}. `useGameClient` calls
+ * this each time it (re)connects, so implementations must return a new,
+ * already-connecting transport on every call.
+ */
+export type CreateClientTransport = () => ClientTransport;
+/**
+ * The default LAN transport: a thin wrapper around the browser `WebSocket` that
+ * adapts its event objects to the normalized {@link ClientTransport} callbacks
+ * (`onmessage(data)` instead of `event.data`; `onclose(code)` instead of
+ * `event.code`). Behavior is identical to using `WebSocket` directly.
+ */
+export declare function createWebSocketTransport(url: string): ClientTransport;
+//# sourceMappingURL=transport.d.ts.map

package/lib/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB;aAC9B,UAAU,EAAE,CAAC;aACb,IAAI,EAAE,CAAC;aACP,OAAO,EAAE,CAAC;aACV,MAAM,EAAE,CAAC;CACD,CAAC;AAEX;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,6EAA6E;IAC7E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,kDAAkD;IAClD,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB;;;;OAIG;IACH,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5C,6DAA6D;IAC7D,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;IACpB,qEAAqE;IACrE,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACnC,4EAA4E;IAC5E,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IAClD,0CAA0C;IAC1C,OAAO,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;CACrC;AAED;;;;GAIG;AACH,MAAM,MAAM,qBAAqB,GAAG,MAAM,eAAe,CAAC;AAE1D;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,CAuBrE"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@couch-kit/client",
-  "version": "0.8.9",
+  "version": "0.10.0",
   "publishConfig": {
     "access": "public",
     "provenance": true
@@ -45,7 +45,6 @@
     "build": "bun build ./src/index.ts --outdir ./dist --target browser --external react --external @couch-kit/core && tsc -p tsconfig.build.json",
     "prepublishOnly": "bun run build",
     "test": "bun test",
-    "lint": "eslint src/",
     "typecheck": "tsc --noEmit",
     "clean": "rm -rf dist lib"
   },
@@ -54,7 +53,7 @@
   },
   "devDependencies": {
     "react": "^19.0.0",
-    "typescript": "^6.0.0"
+    "typescript": "^7.0.0"
   },
   "peerDependencies": {
     "react": ">=18.0.0"

package/src/client.ts

@@ -19,6 +19,12 @@ import {
   resolveSessionSecret,
   interpretHostMessage,
 } from "./connection";
+import {
+  TransportReadyState,
+  createWebSocketTransport,
+  type ClientTransport,
+  type CreateClientTransport,
+} from "./transport";
 
 export interface ClientConfig<S extends IGameState, A extends IAction> {
   url?: string; // Full WebSocket URL (overrides auto-detection)
@@ -36,6 +42,13 @@ export interface ClientConfig<S extends IGameState, A extends IAction> {
   onConnect?: () => void;
   onDisconnect?: () => void;
   debug?: boolean;
+  /**
+   * Provide a custom transport factory (e.g. a cross-network relay). When
+   * omitted, the client connects over the default LAN WebSocket derived from
+   * `url`/`wsPort`. Called on every (re)connect, so it must return a fresh,
+   * already-connecting transport each time.
+   */
+  createTransport?: CreateClientTransport;
 }
 
 /**
@@ -71,7 +84,7 @@ export function useGameClient<S extends IGameState, A extends IAction>(
     config.initialState,
   );
 
-  const socketRef = useRef<WebSocket | null>(null);
+  const socketRef = useRef<ClientTransport | null>(null);
   const reconnectAttempts = useRef(0);
   const reconnectTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
   const intentionalClose = useRef(false);
@@ -98,26 +111,34 @@ export function useGameClient<S extends IGameState, A extends IAction>(
     const cfg = configRef.current;
     intentionalClose.current = false;
 
-    // 1. Magic Client: Determine URL
-    // If explicit URL provided, use it.
-    // Otherwise, assume we are being served by the Host's static server,
-    // so derive the WebSocket URL from window.location.
-    // Convention: WS port = HTTP port + 2 (e.g., HTTP 8080 -> WS 8082)
-    // Port + 1 is skipped to avoid conflicts with Metro bundler (which uses 8081)
-    const wsUrl = resolveWebSocketUrl(
-      { url: cfg.url, wsPort: cfg.wsPort },
-      typeof window !== "undefined" ? window.location : null,
-    );
+    // 1. Build the transport.
+    // If a custom transport factory is provided (e.g. a cross-network relay),
+    // use it. Otherwise fall back to the default LAN WebSocket:
+    //   - If an explicit URL is provided, use it.
+    //   - Otherwise derive the WebSocket URL from window.location, assuming we
+    //     are served by the Host's static server.
+    //   Convention: WS port = HTTP port + 2 (e.g., HTTP 8080 -> WS 8082).
+    //   Port + 1 is skipped to avoid conflicts with Metro bundler (uses 8081).
+    let transport: ClientTransport;
+    if (cfg.createTransport) {
+      if (cfg.debug) console.log("[GameClient] Connecting via custom transport");
+      transport = cfg.createTransport();
+    } else {
+      const wsUrl = resolveWebSocketUrl(
+        { url: cfg.url, wsPort: cfg.wsPort },
+        typeof window !== "undefined" ? window.location : null,
+      );
 
-    if (!wsUrl) return;
+      if (!wsUrl) return;
 
-    if (cfg.debug) console.log(`[GameClient] Connecting to ${wsUrl}`);
-    setStatus("connecting");
+      if (cfg.debug) console.log(`[GameClient] Connecting to ${wsUrl}`);
+      transport = createWebSocketTransport(wsUrl);
+    }
 
-    const ws = new WebSocket(wsUrl);
-    socketRef.current = ws;
+    socketRef.current = transport;
+    setStatus("connecting");
 
-    ws.onopen = () => {
+    transport.onopen = () => {
       const currentCfg = configRef.current;
       setStatus("connected");
       reconnectAttempts.current = 0;
@@ -130,7 +151,7 @@ export function useGameClient<S extends IGameState, A extends IAction>(
 
       // Join with secret
       try {
-        ws.send(
+        transport.send(
           JSON.stringify({
             type: MessageTypes.JOIN,
             payload: {
@@ -146,10 +167,10 @@ export function useGameClient<S extends IGameState, A extends IAction>(
       }
     };
 
-    ws.onmessage = (event) => {
+    transport.onmessage = (data) => {
       let msg: HostMessage;
       try {
-        msg = JSON.parse(event.data) as HostMessage;
+        msg = JSON.parse(data) as HostMessage;
       } catch (e) {
         console.error("Failed to parse message", e);
         return;
@@ -174,7 +195,7 @@ export function useGameClient<S extends IGameState, A extends IAction>(
       }
     };
 
-    ws.onclose = (event) => {
+    transport.onclose = (code) => {
       setStatus("disconnected");
       configRef.current.onDisconnect?.();
 
@@ -183,7 +204,7 @@ export function useGameClient<S extends IGameState, A extends IAction>(
       if (
         !shouldReconnect({
           intentionalClose: intentionalClose.current,
-          closeCode: event.code,
+          closeCode: code,
           attempts: reconnectAttempts.current,
           maxRetries,
         })
@@ -206,12 +227,13 @@ export function useGameClient<S extends IGameState, A extends IAction>(
       }, delay);
     };
 
-    ws.onerror = (e) => {
+    transport.onerror = (e) => {
       if (configRef.current.debug) console.error("[GameClient] Error", e);
       setStatus("error");
     };
     // Only re-create the connect function when URL/port actually changes.
-    // Config values like name, avatar, callbacks are read from configRef.
+    // Config values like name, avatar, callbacks, and createTransport are read
+    // from configRef.
   }, [config.url, config.wsPort, maxRetries, baseDelay, maxDelay]);
 
   // Initial Connection
@@ -258,7 +280,7 @@ export function useGameClient<S extends IGameState, A extends IAction>(
     dispatchLocal(action);
 
     // 2. Send to Host
-    if (socketRef.current?.readyState === WebSocket.OPEN) {
+    if (socketRef.current?.readyState === TransportReadyState.OPEN) {
       socketRef.current.send(
         JSON.stringify({
           type: MessageTypes.ACTION,

package/src/index.ts

@@ -1,5 +1,8 @@
 export * from "./client";
 export * from "./connection";
+export * from "./transport";
+export * from "./relay-protocol";
+export * from "./relay-transport";
 export * from "./time-sync";
 export * from "./assets";
 export * from "./debug-panel";

package/src/relay-protocol.ts

@@ -0,0 +1,151 @@
+/**
+ * Wire protocol for the cross-network **relay** transport.
+ *
+ * The relay is a small, game-agnostic WebSocket server that routes the existing
+ * Couch Kit JSON protocol between a browser **display host** (which owns the
+ * authoritative `GameHostRuntime`) and one or more **phones**, in a star
+ * topology keyed by a room id. The relay never inspects game payloads — it only
+ * tracks room membership and routes envelopes.
+ *
+ * These types are shared by the relay client transport (this package), the
+ * reference display host, and the relay server so all three agree on the wire
+ * format.
+ */
+
+/** Envelope/control message discriminators exchanged with the relay server. */
+export const RelayMessageTypes = {
+  /** Display → relay: create and host a room under `roomId`. */
+  CREATE_ROOM: "CREATE_ROOM",
+  /** Relay → display: room created; includes the display's own `peerId`. */
+  ROOM_CREATED: "ROOM_CREATED",
+  /** Phone → relay: join an existing room. */
+  JOIN_ROOM: "JOIN_ROOM",
+  /** Relay → phone: joined; includes the phone's assigned `peerId`. */
+  ROOM_JOINED: "ROOM_JOINED",
+  /** Relay → display: a phone joined the room. */
+  PEER_JOINED: "PEER_JOINED",
+  /** Relay → display: a phone left the room. */
+  PEER_LEFT: "PEER_LEFT",
+  /** Bidirectional: carries an opaque Couch Kit JSON message as `data`. */
+  DATA: "DATA",
+  /** Relay → client: a protocol/room error. */
+  ERROR: "ERROR",
+} as const;
+
+/** Error codes the relay may report in an {@link RelayErrorMessage}. */
+export const RelayErrorCodes = {
+  ROOM_NOT_FOUND: "ROOM_NOT_FOUND",
+  ROOM_EXISTS: "ROOM_EXISTS",
+  ROOM_FULL: "ROOM_FULL",
+  NOT_IN_ROOM: "NOT_IN_ROOM",
+  MESSAGE_TOO_LARGE: "MESSAGE_TOO_LARGE",
+  MALFORMED: "MALFORMED",
+} as const;
+
+export type RelayErrorCode =
+  (typeof RelayErrorCodes)[keyof typeof RelayErrorCodes];
+
+/** Display → relay: create and host a room. */
+export interface CreateRoomMessage {
+  type: typeof RelayMessageTypes.CREATE_ROOM;
+  roomId: string;
+}
+
+/** Relay → display: room created; `peerId` is the display's own id. */
+export interface RoomCreatedMessage {
+  type: typeof RelayMessageTypes.ROOM_CREATED;
+  roomId: string;
+  peerId: string;
+}
+
+/** Phone → relay: join an existing room. */
+export interface JoinRoomMessage {
+  type: typeof RelayMessageTypes.JOIN_ROOM;
+  roomId: string;
+}
+
+/** Relay → phone: joined; `peerId` is the phone's relay-assigned id. */
+export interface RoomJoinedMessage {
+  type: typeof RelayMessageTypes.ROOM_JOINED;
+  roomId: string;
+  peerId: string;
+}
+
+/** Relay → display: a phone joined; `peerId` becomes its connection id. */
+export interface PeerJoinedMessage {
+  type: typeof RelayMessageTypes.PEER_JOINED;
+  roomId: string;
+  peerId: string;
+}
+
+/** Relay → display: a phone left. */
+export interface PeerLeftMessage {
+  type: typeof RelayMessageTypes.PEER_LEFT;
+  roomId: string;
+  peerId: string;
+}
+
+/**
+ * Bidirectional data envelope carrying an opaque Couch Kit JSON message.
+ *
+ * - Phone → relay: `data` only; the relay injects `from` and routes to the host.
+ * - Relay → display: `from` = sending phone's `peerId`.
+ * - Display → relay: `to` present = unicast to that phone; `to` absent =
+ *   broadcast to every phone in the room.
+ * - Relay → phone: `data` only.
+ *
+ * `data` is the already-serialized Couch Kit message string, so the relay
+ * treats it as opaque.
+ */
+export interface DataMessage {
+  type: typeof RelayMessageTypes.DATA;
+  roomId: string;
+  from?: string;
+  to?: string;
+  data: string;
+}
+
+/** Relay → client: a protocol/room error. */
+export interface RelayErrorMessage {
+  type: typeof RelayMessageTypes.ERROR;
+  code: RelayErrorCode;
+  message: string;
+}
+
+/** Any message a client may send to the relay. */
+export type RelayClientMessage =
+  | CreateRoomMessage
+  | JoinRoomMessage
+  | DataMessage;
+
+/** Any message the relay may send to a client. */
+export type RelayServerMessage =
+  | RoomCreatedMessage
+  | RoomJoinedMessage
+  | PeerJoinedMessage
+  | PeerLeftMessage
+  | DataMessage
+  | RelayErrorMessage;
+
+/** Every relay wire message. */
+export type RelayMessage = RelayClientMessage | RelayServerMessage;
+
+/**
+ * Builds the socket URL for a room: the configured relay URL with `/r/<roomId>`
+ * appended.
+ *
+ * The room has to be in the URL, not just in the `CREATE_ROOM` / `JOIN_ROOM`
+ * message, so that a relay can route the connection before reading any frames —
+ * which is exactly what a per-room Cloudflare Durable Object must do. Relays
+ * that keep every room in one process (the Bun reference server) ignore the
+ * path, so this is safe to send to either.
+ *
+ * @param url - Base relay URL, e.g. `wss://relay.example.com`.
+ * @param roomId - Room code to address.
+ */
+export function relayRoomUrl(url: string, roomId: string): string {
+  const trimmed = url.replace(/\/+$/, "");
+  const [base, query] = trimmed.split("?", 2);
+  const path = `${base}/r/${encodeURIComponent(roomId)}`;
+  return query ? `${path}?${query}` : path;
+}

package/src/relay-transport.ts

@@ -0,0 +1,145 @@
+import {
+  TransportReadyState,
+  type ClientTransport,
+  type CreateClientTransport,
+} from "./transport";
+import {
+  RelayMessageTypes,
+  relayRoomUrl,
+  type RelayServerMessage,
+} from "./relay-protocol";
+
+/** Options for {@link createRelayTransport} / {@link RelayClientTransport}. */
+export interface RelayTransportOptions {
+  /** WebSocket URL of the relay server (e.g. `wss://relay.example.com`). */
+  url: string;
+  /** Room code identifying the display host to connect to. */
+  roomId: string;
+}
+
+/**
+ * Terminal close code (WebSocket policy violation). `close()` can't be called
+ * with reserved codes like 1008, so the transport reports this to the client
+ * directly via `onclose` while closing the socket with a permitted code.
+ */
+const POLICY_CLOSE_CODE = 1008;
+
+/**
+ * A {@link ClientTransport} that reaches the display host through the
+ * cross-network relay instead of a direct LAN WebSocket.
+ *
+ * It opens a WebSocket to the relay, joins `roomId`, and then presents the same
+ * open/message/close surface as the default transport — wrapping each outbound
+ * game message in a relay `DATA` envelope and unwrapping inbound ones. Room-level
+ * failures (unknown/full room) are surfaced as a terminal close so the client's
+ * reconnect logic does not hammer a room that will never accept it.
+ */
+export class RelayClientTransport implements ClientTransport {
+  private readonly ws: WebSocket;
+  private readonly roomId: string;
+  private state: number = TransportReadyState.CONNECTING;
+  /** When set, the code reported to `onclose` instead of the raw socket code. */
+  private pendingCloseCode: number | null = null;
+
+  onopen?: () => void;
+  onmessage?: (data: string) => void;
+  onclose?: (code: number, reason?: string) => void;
+  onerror?: (error?: unknown) => void;
+
+  constructor(options: RelayTransportOptions) {
+    this.roomId = options.roomId;
+    this.ws = new WebSocket(relayRoomUrl(options.url, options.roomId));
+
+    this.ws.onopen = () => {
+      // The relay socket is up; ask to join the room. The transport is not yet
+      // "open" to the client until the relay confirms with ROOM_JOINED.
+      this.ws.send(
+        JSON.stringify({
+          type: RelayMessageTypes.JOIN_ROOM,
+          roomId: this.roomId,
+        }),
+      );
+    };
+
+    this.ws.onmessage = (event: MessageEvent) => {
+      let msg: RelayServerMessage;
+      try {
+        msg = JSON.parse(event.data as string) as RelayServerMessage;
+      } catch {
+        return;
+      }
+      this.handleRelayMessage(msg);
+    };
+
+    this.ws.onclose = (event: CloseEvent) => {
+      this.state = TransportReadyState.CLOSED;
+      const code = this.pendingCloseCode ?? event.code;
+      this.onclose?.(code, event.reason);
+    };
+
+    this.ws.onerror = (event) => this.onerror?.(event);
+  }
+
+  get readyState(): number {
+    return this.state;
+  }
+
+  send(data: string): void {
+    if (this.state !== TransportReadyState.OPEN) return;
+    this.ws.send(
+      JSON.stringify({
+        type: RelayMessageTypes.DATA,
+        roomId: this.roomId,
+        data,
+      }),
+    );
+  }
+
+  close(code?: number, reason?: string): void {
+    this.state = TransportReadyState.CLOSING;
+    // WebSocket.close only permits 1000 or 3000-4999; pass through only those.
+    if (code !== undefined && (code === 1000 || (code >= 3000 && code <= 4999))) {
+      this.ws.close(code, reason);
+    } else {
+      this.ws.close();
+    }
+  }
+
+  private handleRelayMessage(msg: RelayServerMessage): void {
+    switch (msg.type) {
+      case RelayMessageTypes.ROOM_JOINED:
+        this.state = TransportReadyState.OPEN;
+        this.onopen?.();
+        break;
+      case RelayMessageTypes.DATA:
+        this.onmessage?.(msg.data);
+        break;
+      case RelayMessageTypes.ERROR:
+        // Room-level failures are terminal: report a policy close so the client
+        // does not attempt to reconnect, then close the underlying socket.
+        this.pendingCloseCode = POLICY_CLOSE_CODE;
+        this.ws.close();
+        break;
+      // PEER_JOINED / PEER_LEFT / ROOM_CREATED are host-facing; ignored here.
+    }
+  }
+}
+
+/**
+ * Build a {@link CreateClientTransport} factory for `useGameClient` that
+ * connects through the relay.
+ *
+ * @example
+ * ```tsx
+ * useGameClient({
+ *   reducer,
+ *   initialState,
+ *   createTransport: createRelayTransport({ url: RELAY_URL, roomId }),
+ * });
+ * ```
+ */
+export function createRelayTransport(
+  options: RelayTransportOptions,
+): CreateClientTransport {
+  return () => new RelayClientTransport(options);
+}

package/src/time-sync.ts

@@ -5,6 +5,7 @@ import {
   DEFAULT_SYNC_INTERVAL,
   MAX_PENDING_PINGS,
 } from "@couch-kit/core";
+import { TransportReadyState, type ClientTransport } from "./transport";
 
 interface TimeSyncState {
   offset: number; // Difference between server time and local time
@@ -47,10 +48,10 @@ export function calculateTimeSync(
  * called directly. Access `getServerTime()` and `rtt` from the
  * `useGameClient` return value instead.
  *
- * @param socket - The active WebSocket connection (or `null` if not yet connected).
+ * @param socket - The active client transport (or `null` if not yet connected).
  * @returns An object with `getServerTime` (returns estimated server time), `rtt`, and `handlePong` (callback for PONG messages).
  */
-export function useServerTime(socket: WebSocket | null) {
+export function useServerTime(socket: ClientTransport | null) {
   const [timeSync, setTimeSync] = useState<TimeSyncState>({
     offset: 0,
     rtt: 0,
@@ -85,7 +86,7 @@ export function useServerTime(socket: WebSocket | null) {
 
   // Periodic Sync
   useEffect(() => {
-    if (!socket || socket.readyState !== WebSocket.OPEN) return;
+    if (!socket || socket.readyState !== TransportReadyState.OPEN) return;
 
     const sync = () => {
       // Prevent unbounded growth if PONGs are lost

package/src/transport.ts

@@ -0,0 +1,92 @@
+/**
+ * Transport abstraction for the web game client.
+ *
+ * The client hook (`useGameClient`) speaks to the host through a small
+ * WebSocket-shaped interface rather than a concrete `WebSocket`. This lets the
+ * default LAN WebSocket transport and alternative transports (e.g. a
+ * cross-network relay) be swapped in without touching the hook's JOIN handshake,
+ * reconnect/backoff, session-recovery, or state-hydration logic.
+ *
+ * The interface intentionally mirrors the subset of the `WebSocket` API the
+ * client relies on, so the default implementation is a thin wrapper and the
+ * behavior of the LAN path is unchanged.
+ */
+
+/**
+ * Ready-state constants mirroring the `WebSocket` readyState values. A transport
+ * reports these so the client can gate sends on an open connection without
+ * depending on the global `WebSocket` constructor (which may be absent in some
+ * runtimes/tests).
+ */
+export const TransportReadyState = {
+  CONNECTING: 0,
+  OPEN: 1,
+  CLOSING: 2,
+  CLOSED: 3,
+} as const;
+
+/**
+ * The minimal message-transport surface the client requires.
+ *
+ * Implementations deliver and receive already-serialized JSON strings. Event
+ * callbacks are assigned by the client after construction, so a transport must
+ * begin connecting on construction and invoke `onopen` once ready.
+ */
+export interface ClientTransport {
+  /** Current connection state; compare against {@link TransportReadyState}. */
+  readonly readyState: number;
+  /** Send a serialized JSON message to the host. */
+  send(data: string): void;
+  /**
+   * Close the connection. `code`/`reason` follow WebSocket close semantics so
+   * the client's recoverable-vs-terminal reconnect logic keeps working
+   * (1008 policy / 1011 internal error are treated as terminal).
+   */
+  close(code?: number, reason?: string): void;
+  /** Invoked once the connection is open and ready to send. */
+  onopen?: () => void;
+  /** Invoked with the raw JSON string of each inbound host message. */
+  onmessage?: (data: string) => void;
+  /** Invoked when the connection closes, with a WebSocket-compatible code. */
+  onclose?: (code: number, reason?: string) => void;
+  /** Invoked on a transport-level error. */
+  onerror?: (error?: unknown) => void;
+}
+
+/**
+ * Factory that creates a fresh {@link ClientTransport}. `useGameClient` calls
+ * this each time it (re)connects, so implementations must return a new,
+ * already-connecting transport on every call.
+ */
+export type CreateClientTransport = () => ClientTransport;
+
+/**
+ * The default LAN transport: a thin wrapper around the browser `WebSocket` that
+ * adapts its event objects to the normalized {@link ClientTransport} callbacks
+ * (`onmessage(data)` instead of `event.data`; `onclose(code)` instead of
+ * `event.code`). Behavior is identical to using `WebSocket` directly.
+ */
+export function createWebSocketTransport(url: string): ClientTransport {
+  const ws = new WebSocket(url);
+
+  const transport: ClientTransport = {
+    get readyState() {
+      return ws.readyState;
+    },
+    send(data: string) {
+      ws.send(data);
+    },
+    close(code?: number, reason?: string) {
+      ws.close(code, reason);
+    },
+  };
+
+  ws.onopen = () => transport.onopen?.();
+  ws.onmessage = (event: MessageEvent) =>
+    transport.onmessage?.(event.data as string);
+  ws.onclose = (event: CloseEvent) =>
+    transport.onclose?.(event.code, event.reason);
+  ws.onerror = (event) => transport.onerror?.(event);
+
+  return transport;
+}