@couch-kit/client 0.13.0 → 0.15.0

package/CHANGELOG.md

@@ -1,5 +1,72 @@
 # @couch-kit/client
 
+## 0.15.0
+
+### Minor Changes
+
+- [#206](https://github.com/faluciano/react-native-couch-kit/pull/206) [`ddec122`](https://github.com/faluciano/react-native-couch-kit/commit/ddec122d9e415c54f157d6998c2b719ab31586b3) Thanks [@faluciano](https://github.com/faluciano)! - Fix the `useGameClient` connection lifecycle and make optimistic updates self-correcting.
+
+  - Time sync now actually runs. The ping loop only started if the socket was already open when the hook first saw it, which it never was, so no `PING` was ever sent: `rtt` stayed `0` and `getServerTime()` returned the local clock. It now starts when the socket opens. Games that use neither can pass `timeSync: false` to skip the pings (on a relay each one is a billed message).
+  - No more duplicate connections. A socket closed by cleanup, `disconnect()` or `reconnect()` still fires its `close` event later; that event used to overwrite the new connection's status and schedule a second, parallel reconnect. This happened on every mount under React `StrictMode` and whenever `url`, `wsPort` or the retry options changed. Events from a replaced transport are now ignored.
+  - Optimistic updates no longer get stuck. The host stays silent when an action changes nothing, so an optimistic update it ignored stood forever. The client now falls back to the last host state if no update arrives within `optimisticTimeoutMs` (default 2000, `0` disables), and immediately on a host `ERROR`.
+  - New `onError` callback receives host rejections (`RATE_LIMITED`, `NOT_JOINED`, …), which were silently dropped before. `interpretHostMessage` now returns an `error` effect for `ERROR` messages.
+  - `disconnectReason` resets to `null` once a connection opens, as documented.
+  - A stored session secret the host would reject is replaced instead of reused, so a corrupted `ck_secret` no longer fails every JOIN.
+  - The relay transport reports a room whose display disconnected as a terminal `HOST_LEFT` close (new `RelayErrorCodes.HOST_LEFT`, `RELAY_CLOSE_HOST_LEFT`), and `describeRelayError` explains it.
+
+## 0.14.0
+
+### Minor Changes
+
+- [#164](https://github.com/faluciano/react-native-couch-kit/pull/164) [`a157126`](https://github.com/faluciano/react-native-couch-kit/commit/a157126424e4d73dcc7185118d5be0db6719792e) Thanks [@faluciano](https://github.com/faluciano)! - Send a projected state update as one relay frame instead of one per player
+
+  A game with a `project` function sends every player their own view, which meant
+  one WebSocket frame per player for every state change. Relays bill and
+  rate-limit per inbound frame, so a four-player table paid four messages for one
+  update and spent four of the display's 30-per-second budget.
+
+  `GameRuntimeTransport` gains an optional `sendMany(entries)`. When a transport
+  implements it, the runtime hands over the whole projected batch at once;
+  transports that do not — the LAN WebSocket path — keep receiving one `send` per
+  connection and are unaffected.
+
+  `RelayDisplayHost` implements it with a new `DATA_MULTI` envelope carrying a
+  peer-id-to-payload map, which the relay unpacks into ordinary `DATA` frames.
+  Phones need no update — nothing on the client side can tell a batched update
+  from a unicast one. If the combined frame would exceed the relay's 256KB
+  ceiling, the display falls back to individual frames rather than send something
+  the relay would drop.
+
+  Relays must be updated before displays: both bundled implementations
+  (`services/relay`, `services/relay-worker`) understand `DATA_MULTI`, and an
+  older relay answers it with `MALFORMED`. The type is host-only — a phone sending
+  it is rejected, so it cannot be used to reach another phone directly.
+
+- [#164](https://github.com/faluciano/react-native-couch-kit/pull/164) [`a157126`](https://github.com/faluciano/react-native-couch-kit/commit/a157126424e4d73dcc7185118d5be0db6719792e) Thanks [@faluciano](https://github.com/faluciano)! - Back the time-sync ping off to 30s once the clock estimate settles
+
+  `useGameClient`'s clock sync pinged every 5 seconds for the life of the
+  connection. It now starts there and doubles to a 30-second ceiling
+  (`MAX_SYNC_INTERVAL`), resetting to the fast interval whenever a new socket is
+  established, including after a reconnect.
+
+  The first few pings are what converge the offset; the clock difference they
+  measure does not drift on a human timescale, so the fast interval stops earning
+  its cost within about a minute. On a relay transport it is not free: each ping
+  is a message in and a `PONG` back out, and pings are the only traffic an idle
+  table generates at all. A four-player lobby went from 5,760 relay messages an
+  hour to under 1,000 while sitting untouched.
+
+  `rtt` and `getServerTime()` are unchanged in accuracy — both are updated by the
+  same `PONG` handling as before, just less often once settled. Games needing the
+  old cadence can dispatch their own pings; the constants
+  (`DEFAULT_SYNC_INTERVAL`, `MAX_SYNC_INTERVAL`, `SYNC_BACKOFF_FACTOR`) are
+  exported from `@couch-kit/core`.
+
+### Patch Changes
+
+- Updated dependencies [[`a157126`](https://github.com/faluciano/react-native-couch-kit/commit/a157126424e4d73dcc7185118d5be0db6719792e)]:
+  - @couch-kit/core@0.10.0
+
 ## 0.13.0
 
 ### Minor Changes

package/README.md

@@ -4,7 +4,7 @@ The client-side React hooks for the web controller.
 
 ## Features
 
-- **Default connection:** By default, connects to `ws(s)://{window.location.hostname}:8082`.
+- **Default connection:** By default, connects to `ws(s)://{window.location.hostname}:8082/ws`.
 - **Time synchronization:** `useServerTime()` helps estimate server time using periodic ping/pong.
 - **Asset preloading:** `usePreload()` is a small helper for preloading images and fetching other URLs.
 - **Optimistic UI:** State updates apply locally immediately while being sent to the server.
@@ -27,15 +27,18 @@ Config:
 
 - `reducer`: `(state, action) => state` (your shared reducer)
 - `initialState`: initial state used until the host hydrates
-- `url?`: explicit WebSocket URL. If omitted, the hook uses `ws(s)://{window.location.hostname}:8082`.
+- `url?`: explicit WebSocket URL. If omitted, the hook uses `ws(s)://{window.location.hostname}:8082/ws`.
 - `wsPort?`: WebSocket port override (default: auto-detected from page URL using HTTP port + 2)
 - `name?`: player display name (default: `"Player"`)
 - `avatar?`: player avatar emoji (default: `"\u{1F600}"`)
 - `maxRetries?`: maximum reconnection attempts before giving up (default: `5`)
 - `baseDelay?`: base delay in ms for exponential backoff reconnection (default: `1000`)
 - `maxDelay?`: maximum delay in ms cap for reconnection backoff (default: `10000`)
+- `optimisticTimeoutMs?`: how long an optimistic update may stand without the host confirming it (default: `2000`; `0` disables). See [Optimistic updates](#optimistic-updates).
+- `timeSync?`: exchange PING/PONG with the host to power `getServerTime()` and `rtt` (default: `true`). Turn it off if you use neither — on a relay every ping is a billed message.
 - `debug?`: enable console logs
 - `onConnect?`, `onDisconnect?`: lifecycle callbacks
+- `onError?`: called with `{ code, message }` when the host rejects something this client sent (`RATE_LIMITED`, `NOT_JOINED`, `FORBIDDEN_ACTION`, `INVALID_SECRET`, …)
 
 Returns:
 
@@ -43,11 +46,25 @@ Returns:
 - `state`: current controller state (optimistic + hydrated)
 - `playerId`: stable public identifier derived from the session secret. Persists across page refreshes and reconnections (the same player always gets the same `playerId`).
 - `sendAction(action)`: optimistic dispatch + send to host
+- `disconnectReason`: why the last connection ended, when the transport knows (for the relay, a code such as `ROOM_NOT_FOUND` or `HOST_LEFT`); `null` once connected again
 - `getServerTime()`: NTP-ish server time based on periodic ping/pong
 - `rtt`: round-trip time (ms) to the server, updated periodically via PING/PONG
 - `disconnect()`: manually disconnect from the host (prevents automatic reconnection)
 - `reconnect()`: manually reconnect to the host (resets the reconnection attempt counter)
 
+### Optimistic updates
+
+With a `reducer`, `sendAction` applies the action locally before the host
+answers. The host is still the authority, and it only broadcasts when its state
+actually changes — so an action it ignores (an illegal move, a rate-limited tap,
+one sent while offline) produces no update at all. The client therefore treats
+silence as a "no": if no state update arrives within `optimisticTimeoutMs`, it
+falls back to the last state the host sent. A host `ERROR` does the same
+immediately and is passed to `onError`.
+
+The hook is safe under React `StrictMode` and across option changes: a
+connection that has been replaced can no longer affect the current one.
+
 ## State Sync Contract
 
 The host broadcasts full state snapshots. The client automatically applies them using a higher-order reducer wrapper.
@@ -77,7 +94,7 @@ In dev, pass the TV WebSocket URL explicitly:
 useGameClient({
   reducer,
   initialState,
-  url: "ws://TV_IP:8082",
+  url: "ws://TV_IP:8082/ws",
 });
 ```
 

package/dist/index.js

@@ -15,6 +15,8 @@ import {
   MessageTypes,
   generateId,
   DEFAULT_SYNC_INTERVAL,
+  MAX_SYNC_INTERVAL,
+  SYNC_BACKOFF_FACTOR,
   MAX_PENDING_PINGS
 } from "@couch-kit/core";
 
@@ -53,6 +55,9 @@ function calculateTimeSync(clientSendTime, clientReceiveTime, serverTime) {
   const offset = expectedServerTime - clientReceiveTime;
   return { offset, rtt };
 }
+function nextSyncInterval(current) {
+  return Math.min(current * SYNC_BACKOFF_FACTOR, MAX_SYNC_INTERVAL);
+}
 function useServerTime(socket) {
   const [timeSync, setTimeSync] = useState({
     offset: 0,
@@ -74,6 +79,8 @@ function useServerTime(socket) {
   useEffect(() => {
     if (!socket || socket.readyState !== TransportReadyState.OPEN)
       return;
+    let delay = DEFAULT_SYNC_INTERVAL;
+    let timer = null;
     const sync = () => {
       if (pings.current.size >= MAX_PENDING_PINGS) {
         const oldest = pings.current.keys().next().value;
@@ -87,10 +94,16 @@ function useServerTime(socket) {
         type: MessageTypes.PING,
         payload: { id, timestamp }
       }));
+      delay = nextSyncInterval(delay);
+      timer = setTimeout(sync, delay);
     };
     sync();
-    const interval = setInterval(sync, DEFAULT_SYNC_INTERVAL);
-    return () => clearInterval(interval);
+    const pending = pings.current;
+    return () => {
+      if (timer !== null)
+        clearTimeout(timer);
+      pending.clear();
+    };
   }, [socket]);
   return { getServerTime, rtt: timeSync.rtt, handlePong };
 }
@@ -100,9 +113,11 @@ import {
   MessageTypes as MessageTypes2,
   DEFAULT_WS_PORT_OFFSET,
   DEFAULT_WS_PATH,
-  generateId as generateId2
+  generateId as generateId2,
+  isValidSecret
 } from "@couch-kit/core";
 var SESSION_SECRET_KEY = "ck_secret";
+var DEFAULT_OPTIMISTIC_TIMEOUT = 2000;
 var NON_RECOVERABLE_CLOSE_CODES = new Set([
   1008,
   1011
@@ -133,7 +148,7 @@ function resolveSessionSecret(storage, generate = generateId2) {
     if (!storage)
       return generate();
     const stored = storage.getItem(SESSION_SECRET_KEY);
-    if (stored)
+    if (stored && isValidSecret(stored))
       return stored;
     const secret = generate();
     storage.setItem(SESSION_SECRET_KEY, secret);
@@ -158,6 +173,8 @@ function interpretHostMessage(msg) {
         { kind: "setPlayerId", playerId: msg.payload.playerId },
         { kind: "hydrate", state: msg.payload.state }
       ];
+    case MessageTypes2.ERROR:
+      return [{ kind: "error", error: msg.payload }];
     default:
       return [];
   }
@@ -170,6 +187,9 @@ function useGameClient(config) {
   const [disconnectReason, setDisconnectReason] = useState2(null);
   const [state, dispatchLocal] = useReducer(createGameReducer(config.reducer ?? ((current) => current)), config.initialState);
   const socketRef = useRef2(null);
+  const [openTransport, setOpenTransport] = useState2(null);
+  const lastServerState = useRef2(null);
+  const rollbackTimer = useRef2(null);
   const reconnectAttempts = useRef2(0);
   const reconnectTimer = useRef2(null);
   const intentionalClose = useRef2(false);
@@ -177,11 +197,27 @@ function useGameClient(config) {
   useEffect2(() => {
     configRef.current = config;
   });
-  const { getServerTime, rtt, handlePong } = useServerTime(socketRef.current);
+  const { getServerTime, rtt, handlePong } = useServerTime(config.timeSync === false ? null : openTransport);
   const handlePongRef = useRef2(handlePong);
   useEffect2(() => {
     handlePongRef.current = handlePong;
   });
+  const cancelRollback = useCallback2(() => {
+    if (rollbackTimer.current !== null) {
+      clearTimeout(rollbackTimer.current);
+      rollbackTimer.current = null;
+    }
+  }, []);
+  const rollbackToServerState = useCallback2(() => {
+    cancelRollback();
+    const serverState = lastServerState.current;
+    if (serverState === null)
+      return;
+    dispatchLocal({
+      type: InternalActionTypes.HYDRATE,
+      payload: serverState
+    });
+  }, [cancelRollback]);
   const maxRetries = config.maxRetries ?? DEFAULT_MAX_RETRIES;
   const baseDelay = config.baseDelay ?? DEFAULT_BASE_DELAY;
   const maxDelay = config.maxDelay ?? DEFAULT_MAX_DELAY;
@@ -203,9 +239,14 @@ function useGameClient(config) {
     }
     socketRef.current = transport;
     setStatus("connecting");
+    const isCurrent = () => socketRef.current === transport;
     transport.onopen = () => {
+      if (!isCurrent())
+        return;
       const currentCfg = configRef.current;
       setStatus("connected");
+      setDisconnectReason(null);
+      setOpenTransport(transport);
       reconnectAttempts.current = 0;
       currentCfg.onConnect?.();
       const secret = resolveSessionSecret(typeof localStorage !== "undefined" ? localStorage : null);
@@ -224,6 +265,8 @@ function useGameClient(config) {
       }
     };
     transport.onmessage = (data) => {
+      if (!isCurrent())
+        return;
       let msg;
       try {
         msg = JSON.parse(data);
@@ -237,6 +280,8 @@ function useGameClient(config) {
             setPlayerId(effect.playerId);
             break;
           case "hydrate":
+            lastServerState.current = effect.state;
+            cancelRollback();
             dispatchLocal({
               type: InternalActionTypes.HYDRATE,
               payload: effect.state
@@ -245,10 +290,20 @@ function useGameClient(config) {
           case "pong":
             handlePongRef.current(effect.payload);
             break;
+          case "error":
+            if (configRef.current.debug)
+              console.warn("[GameClient] Host error:", effect.error);
+            rollbackToServerState();
+            configRef.current.onError?.(effect.error);
+            break;
         }
       }
     };
     transport.onclose = (code, reason) => {
+      if (!isCurrent())
+        return;
+      socketRef.current = null;
+      setOpenTransport(null);
       setStatus("disconnected");
       setDisconnectReason(reason ? reason : null);
       configRef.current.onDisconnect?.();
@@ -268,47 +323,66 @@ function useGameClient(config) {
       }, delay);
     };
     transport.onerror = (e) => {
+      if (!isCurrent())
+        return;
       if (configRef.current.debug)
         console.error("[GameClient] Error", e);
       setStatus("error");
     };
-  }, [config.url, config.wsPort, maxRetries, baseDelay, maxDelay]);
-  useEffect2(() => {
-    connect();
-    return () => {
-      intentionalClose.current = true;
-      if (socketRef.current)
-        socketRef.current.close();
-      if (reconnectTimer.current)
-        clearTimeout(reconnectTimer.current);
-    };
-  }, [connect]);
-  const disconnect = useCallback2(() => {
+  }, [
+    config.url,
+    config.wsPort,
+    maxRetries,
+    baseDelay,
+    maxDelay,
+    cancelRollback,
+    rollbackToServerState
+  ]);
+  const closeCurrent = useCallback2(() => {
     intentionalClose.current = true;
     if (reconnectTimer.current) {
       clearTimeout(reconnectTimer.current);
       reconnectTimer.current = null;
     }
-    if (socketRef.current) {
-      socketRef.current.close();
-      socketRef.current = null;
-    }
+    cancelRollback();
+    const transport = socketRef.current;
+    if (!transport)
+      return;
+    socketRef.current = null;
+    setOpenTransport(null);
+    transport.close();
+    configRef.current.onDisconnect?.();
+  }, [cancelRollback]);
+  useEffect2(() => {
+    connect();
+    return closeCurrent;
+  }, [connect, closeCurrent]);
+  const disconnect = useCallback2(() => {
+    closeCurrent();
     setStatus("disconnected");
-  }, []);
+  }, [closeCurrent]);
   const reconnect = useCallback2(() => {
-    disconnect();
+    closeCurrent();
     reconnectAttempts.current = 0;
-    setTimeout(() => connect(), 50);
-  }, [disconnect, connect]);
+    connect();
+  }, [closeCurrent, connect]);
   const sendAction = useCallback2((action) => {
     dispatchLocal(action);
+    const cfg = configRef.current;
+    const timeout = cfg.optimisticTimeoutMs ?? DEFAULT_OPTIMISTIC_TIMEOUT;
+    if (cfg.reducer && timeout > 0 && rollbackTimer.current === null) {
+      rollbackTimer.current = setTimeout(() => {
+        rollbackTimer.current = null;
+        rollbackToServerState();
+      }, timeout);
+    }
     if (socketRef.current?.readyState === TransportReadyState.OPEN) {
       socketRef.current.send(JSON.stringify({
         type: MessageTypes3.ACTION,
         payload: action
       }));
     }
-  }, []);
+  }, [rollbackToServerState]);
   return {
     status,
     state,
@@ -330,6 +404,7 @@ var RelayMessageTypes = {
   PEER_JOINED: "PEER_JOINED",
   PEER_LEFT: "PEER_LEFT",
   DATA: "DATA",
+  DATA_MULTI: "DATA_MULTI",
   ERROR: "ERROR"
 };
 var RelayErrorCodes = {
@@ -340,8 +415,10 @@ var RelayErrorCodes = {
   MESSAGE_TOO_LARGE: "MESSAGE_TOO_LARGE",
   MALFORMED: "MALFORMED",
   RATE_LIMITED: "RATE_LIMITED",
-  SERVER_BUSY: "SERVER_BUSY"
+  SERVER_BUSY: "SERVER_BUSY",
+  HOST_LEFT: "HOST_LEFT"
 };
+var RELAY_CLOSE_HOST_LEFT = 4001;
 function relayRoomUrl(url, roomId) {
   const trimmed = url.replace(/\/+$/, "");
   const [base, query] = trimmed.split("?", 2);
@@ -382,6 +459,10 @@ class RelayClientTransport {
     };
     this.ws.onclose = (event) => {
       this.state = TransportReadyState.CLOSED;
+      if (this.pendingCloseCode === null && event.code === RELAY_CLOSE_HOST_LEFT) {
+        this.pendingCloseCode = POLICY_CLOSE_CODE;
+        this.pendingCloseReason = RelayErrorCodes.HOST_LEFT;
+      }
       const code = this.pendingCloseCode ?? event.code;
       this.onclose?.(code, this.pendingCloseReason ?? event.reason);
     };
@@ -479,6 +560,8 @@ function describeRelayError(reason) {
       return "That room isn't open. Check the code on the screen.";
     case RelayErrorCodes.ROOM_FULL:
       return "That room is full.";
+    case RelayErrorCodes.HOST_LEFT:
+      return "The host screen closed, so this game has ended.";
     case RelayErrorCodes.RATE_LIMITED:
       return "Too many messages — slow down and try again.";
     case RelayErrorCodes.ROOM_EXISTS:
@@ -628,26 +711,29 @@ function useDebugPanel(options) {
   };
 }
 export {
-  useServerTime,
-  useRelayRoom,
-  usePreload,
-  useGameClient,
-  useDebugPanel,
-  shouldReconnect,
-  resolveWebSocketUrl,
-  resolveSessionSecret,
-  relayRoomUrl,
-  normalizeRoomCode,
-  interpretHostMessage,
-  describeRelayError,
-  createWebSocketTransport,
-  createRelayTransport,
-  computeBackoffDelay,
-  calculateTimeSync,
-  TransportReadyState,
-  SESSION_SECRET_KEY,
-  RelayMessageTypes,
-  RelayErrorCodes,
+  DEFAULT_OPTIMISTIC_TIMEOUT,
+  RELAY_CLOSE_HOST_LEFT,
+  RELAY_MINT_PATH,
   RelayClientTransport,
-  RELAY_MINT_PATH
+  RelayErrorCodes,
+  RelayMessageTypes,
+  SESSION_SECRET_KEY,
+  TransportReadyState,
+  calculateTimeSync,
+  computeBackoffDelay,
+  createRelayTransport,
+  createWebSocketTransport,
+  describeRelayError,
+  interpretHostMessage,
+  nextSyncInterval,
+  normalizeRoomCode,
+  relayRoomUrl,
+  resolveSessionSecret,
+  resolveWebSocketUrl,
+  shouldReconnect,
+  useDebugPanel,
+  useGameClient,
+  usePreload,
+  useRelayRoom,
+  useServerTime
 };

package/lib/client.d.ts

@@ -1,4 +1,5 @@
 import { type IGameState, type IAction } from "@couch-kit/core";
+import { type HostError } from "./connection";
 import { type CreateClientTransport } from "./transport";
 export interface ClientConfig<S extends IGameState, A extends IAction> {
     url?: string;
@@ -23,8 +24,30 @@ export interface ClientConfig<S extends IGameState, A extends IAction> {
     baseDelay?: number;
     /** Maximum delay (ms) cap for reconnection backoff (default: 10000). */
     maxDelay?: number;
+    /**
+     * How long (ms) an optimistic update may stand without the host confirming
+     * it (default: 2000). The host only broadcasts when its state changes, so an
+     * action it ignores — an illegal move, a rate-limited tap, one sent while
+     * offline — produces no update, and without this the client would keep
+     * showing a state the host never had. When the window passes with no update
+     * the client falls back to the last state the host sent. Set to `0` to
+     * disable. Has no effect without a `reducer`.
+     */
+    optimisticTimeoutMs?: number;
+    /**
+     * Keep the clock in sync with the host by exchanging PING/PONG (default:
+     * `true`). Powers `getServerTime()` and `rtt`. A game that uses neither can
+     * turn it off: on a relay transport every ping, and the host's answer, is a
+     * billed message.
+     */
+    timeSync?: boolean;
     onConnect?: () => void;
     onDisconnect?: () => void;
+    /**
+     * Called when the host rejects something this client sent (`RATE_LIMITED`,
+     * `NOT_JOINED`, `FORBIDDEN_ACTION`, `INVALID_SECRET`, …).
+     */
+    onError?: (error: HostError) => void;
     debug?: boolean;
     /**
      * Provide a custom transport factory (e.g. a cross-network relay). When

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;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;;;;;;;;;OASG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,KAAK,CAAC,CAAC;IACrC,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;;;;IA2OxB;;;;OAIG;;yBAvBmC,CAAC;;IA2BvC,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;AAEzB,OAAO,EAOL,KAAK,SAAS,EACf,MAAM,cAAc,CAAC;AACtB,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;;;;;;;;;OASG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,KAAK,CAAC,CAAC;IACrC,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;;;;;;;;OAQG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,IAAI,CAAC;IAC1B;;;OAGG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,SAAS,KAAK,IAAI,CAAC;IACrC,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;;;;IAgUxB;;;;OAIG;;yBArCM,CAAC;;IAyCV,8EAA8E;;IAE9E,0EAA0E;;IAE1E,+EAA+E;;EAGlF"}

package/lib/connection.d.ts

@@ -10,6 +10,11 @@ import { type HostMessage } from "@couch-kit/core";
  */
 /** localStorage key under which the session-recovery secret is persisted. */
 export declare const SESSION_SECRET_KEY = "ck_secret";
+/**
+ * Default time (ms) an optimistic update may stand without the host confirming
+ * it before the client falls back to the last state the host sent.
+ */
+export declare const DEFAULT_OPTIMISTIC_TIMEOUT = 2000;
 /** Connection options relevant to deriving the WebSocket URL. */
 export interface UrlResolutionConfig {
     /** Full WebSocket URL. When set, it is used verbatim. */
@@ -65,9 +70,12 @@ export type SecretStorage = Pick<Storage, "getItem" | "setItem">;
  * Resolve the session-recovery secret.
  *
  * Reuses an existing secret from storage when present, otherwise generates a
- * new one and persists it. When storage is unavailable or throws (e.g. Safari
- * private browsing, restrictive WebViews), a fresh secret is generated without
- * persistence so a JOIN can still proceed.
+ * new one and persists it. A stored value the host would reject (corrupted or
+ * written by something else) is replaced rather than reused — otherwise every
+ * JOIN would fail with `INVALID_SECRET` until the user cleared site data. When
+ * storage is unavailable or throws (e.g. Safari private browsing, restrictive
+ * WebViews), a fresh secret is generated without persistence so a JOIN can
+ * still proceed.
  */
 export declare function resolveSessionSecret(storage: SecretStorage | null | undefined, generate?: () => string): string;
 /**
@@ -84,15 +92,24 @@ export type HostMessageEffect<S> = {
 } | {
     kind: "pong";
     payload: PongPayload;
+} | {
+    kind: "error";
+    error: HostError;
 };
+/**
+ * A rejection reported by the host — e.g. `RATE_LIMITED`, `NOT_JOINED`,
+ * `FORBIDDEN_ACTION`, `INVALID_SECRET`.
+ */
+export type HostError = Extract<HostMessage, {
+    type: "ERROR";
+}>["payload"];
 /** Payload of a `PONG` host message. */
 export type PongPayload = Extract<HostMessage, {
     type: "PONG";
 }>["payload"];
 /**
  * Translate a parsed host message into the ordered list of effects the client
- * should apply. Unknown/irrelevant message types (e.g. `ERROR`) yield no
- * effects.
+ * should apply. Unknown message types yield no effects.
  */
 export declare function interpretHostMessage<S>(msg: HostMessage): HostMessageEffect<S>[];
 //# sourceMappingURL=connection.d.ts.map

package/lib/connection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../src/connection.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,KAAK,WAAW,EACjB,MAAM,iBAAiB,CAAC;AAEzB;;;;;;;;GAQG;AAEH,6EAA6E;AAC7E,eAAO,MAAM,kBAAkB,cAAc,CAAC;AAQ9C,iEAAiE;AACjE,MAAM,WAAW,mBAAmB;IAClC,yDAAyD;IACzD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,0EAA0E;IAC1E,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,wEAAwE;AACxE,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,mBAAmB,EAC3B,QAAQ,EAAE,YAAY,GAAG,IAAI,GAAG,SAAS,GACxC,MAAM,GAAG,IAAI,CAUf;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,GACf,MAAM,CAER;AAED,sDAAsD;AACtD,MAAM,WAAW,iBAAiB;IAChC,gFAAgF;IAChF,gBAAgB,EAAE,OAAO,CAAC;IAC1B,uDAAuD;IACvD,SAAS,EAAE,MAAM,CAAC;IAClB,oDAAoD;IACpD,QAAQ,EAAE,MAAM,CAAC;IACjB,yDAAyD;IACzD,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,iBAAiB,GAAG,OAAO,CAIpE;AAED,oEAAoE;AACpE,MAAM,MAAM,aAAa,GAAG,IAAI,CAAC,OAAO,EAAE,SAAS,GAAG,SAAS,CAAC,CAAC;AAEjE;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,aAAa,GAAG,IAAI,GAAG,SAAS,EACzC,QAAQ,GAAE,MAAM,MAAmB,GAClC,MAAM,CAWR;AAED;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,CAAC,CAAC,IAC3B;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACzC;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GAC7B;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,WAAW,CAAA;CAAE,CAAC;AAE3C,wCAAwC;AACxC,MAAM,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,EAAE;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC,SAAS,CAAC,CAAC;AAE5E;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EACpC,GAAG,EAAE,WAAW,GACf,iBAAiB,CAAC,CAAC,CAAC,EAAE,CAmBxB"}
+{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../src/connection.ts"],"names":[],"mappings":"AAAA,OAAO,EAML,KAAK,WAAW,EACjB,MAAM,iBAAiB,CAAC;AAEzB;;;;;;;;GAQG;AAEH,6EAA6E;AAC7E,eAAO,MAAM,kBAAkB,cAAc,CAAC;AAE9C;;;GAGG;AACH,eAAO,MAAM,0BAA0B,OAAO,CAAC;AAQ/C,iEAAiE;AACjE,MAAM,WAAW,mBAAmB;IAClC,yDAAyD;IACzD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,0EAA0E;IAC1E,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,wEAAwE;AACxE,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,mBAAmB,EAC3B,QAAQ,EAAE,YAAY,GAAG,IAAI,GAAG,SAAS,GACxC,MAAM,GAAG,IAAI,CAUf;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,GACf,MAAM,CAER;AAED,sDAAsD;AACtD,MAAM,WAAW,iBAAiB;IAChC,gFAAgF;IAChF,gBAAgB,EAAE,OAAO,CAAC;IAC1B,uDAAuD;IACvD,SAAS,EAAE,MAAM,CAAC;IAClB,oDAAoD;IACpD,QAAQ,EAAE,MAAM,CAAC;IACjB,yDAAyD;IACzD,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,iBAAiB,GAAG,OAAO,CAIpE;AAED,oEAAoE;AACpE,MAAM,MAAM,aAAa,GAAG,IAAI,CAAC,OAAO,EAAE,SAAS,GAAG,SAAS,CAAC,CAAC;AAEjE;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,aAAa,GAAG,IAAI,GAAG,SAAS,EACzC,QAAQ,GAAE,MAAM,MAAmB,GAClC,MAAM,CAWR;AAED;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,CAAC,CAAC,IAC3B;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACzC;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GAC7B;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,WAAW,CAAA;CAAE,GACtC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,SAAS,CAAA;CAAE,CAAC;AAExC;;;GAGG;AACH,MAAM,MAAM,SAAS,GAAG,OAAO,CAAC,WAAW,EAAE;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC,CAAC,SAAS,CAAC,CAAC;AAE3E,wCAAwC;AACxC,MAAM,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,EAAE;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC,SAAS,CAAC,CAAC;AAE5E;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EACpC,GAAG,EAAE,WAAW,GACf,iBAAiB,CAAC,CAAC,CAAC,EAAE,CAqBxB"}

package/lib/relay-protocol.d.ts

@@ -27,6 +27,8 @@ export declare const RelayMessageTypes: {
     readonly PEER_LEFT: "PEER_LEFT";
     /** Bidirectional: carries an opaque Couch Kit JSON message as `data`. */
     readonly DATA: "DATA";
+    /** Display → relay: one frame carrying a different payload per phone. */
+    readonly DATA_MULTI: "DATA_MULTI";
     /** Relay → client: a protocol/room error. */
     readonly ERROR: "ERROR";
 };
@@ -42,7 +44,19 @@ export declare const RelayErrorCodes: {
     readonly RATE_LIMITED: "RATE_LIMITED";
     /** Relay is at its room capacity. */
     readonly SERVER_BUSY: "SERVER_BUSY";
+    /**
+     * The display hosting the room disconnected, so the room is gone. Never sent
+     * as an `ERROR` frame: the relay closes each phone's socket with
+     * {@link RELAY_CLOSE_HOST_LEFT} and the client transport reports this code as
+     * the close reason.
+     */
+    readonly HOST_LEFT: "HOST_LEFT";
 };
+/**
+ * WebSocket close code the relay uses when a room's host disconnects and its
+ * phones are dropped with it.
+ */
+export declare const RELAY_CLOSE_HOST_LEFT = 4001;
 export type RelayErrorCode = (typeof RelayErrorCodes)[keyof typeof RelayErrorCodes];
 /** Display → relay: create and host a room. */
 export interface CreateRoomMessage {
@@ -97,6 +111,22 @@ export interface DataMessage {
     to?: string;
     data: string;
 }
+/**
+ * Display → relay: one envelope carrying a different payload per phone.
+ *
+ * `payloads` maps a phone's `peerId` to the already-serialized Couch Kit
+ * message for that phone. The relay unpacks it into ordinary
+ * {@link DataMessage} frames, so phones never see this type — it exists purely
+ * so a projected game costs one inbound relay message per state change instead
+ * of one per player. Peer ids the room does not know are skipped.
+ *
+ * Host-only: the relay rejects it from a phone.
+ */
+export interface DataMultiMessage {
+    type: typeof RelayMessageTypes.DATA_MULTI;
+    roomId: string;
+    payloads: Record<string, string>;
+}
 /** Relay → client: a protocol/room error. */
 export interface RelayErrorMessage {
     type: typeof RelayMessageTypes.ERROR;
@@ -104,7 +134,7 @@ export interface RelayErrorMessage {
     message: string;
 }
 /** Any message a client may send to the relay. */
-export type RelayClientMessage = CreateRoomMessage | JoinRoomMessage | DataMessage;
+export type RelayClientMessage = CreateRoomMessage | JoinRoomMessage | DataMessage | DataMultiMessage;
 /** Any message the relay may send to a client. */
 export type RelayServerMessage = RoomCreatedMessage | RoomJoinedMessage | PeerJoinedMessage | PeerLeftMessage | DataMessage | RelayErrorMessage;
 /** Every relay wire message. */

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

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

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

@@ -1 +1 @@
-{"version":3,"file":"relay-room.d.ts","sourceRoot":"","sources":["../src/relay-room.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAQH,MAAM,WAAW,kBAAkB;IACjC,4EAA4E;IAC5E,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,iFAAiF;IACjF,QAAQ,CAAC,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3C,8DAA8D;IAC9D,QAAQ,CAAC,WAAW,EAAE,MAAM,IAAI,CAAC;CAClC;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEvD;AAcD;;;;;GAKG;AACH,wBAAgB,YAAY,IAAI,kBAAkB,CA+BjD;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAmBvE"}
+{"version":3,"file":"relay-room.d.ts","sourceRoot":"","sources":["../src/relay-room.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAQH,MAAM,WAAW,kBAAkB;IACjC,4EAA4E;IAC5E,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,iFAAiF;IACjF,QAAQ,CAAC,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3C,8DAA8D;IAC9D,QAAQ,CAAC,WAAW,EAAE,MAAM,IAAI,CAAC;CAClC;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEvD;AAcD;;;;;GAKG;AACH,wBAAgB,YAAY,IAAI,kBAAkB,CA+BjD;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAqBvE"}

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

@@ -1 +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;IAC/C;;;;OAIG;IACH,OAAO,CAAC,kBAAkB,CAAuB;IAEjD,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;CAqB3B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,qBAAqB,GAC7B,qBAAqB,CAEvB"}
+{"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;AASrB,+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;IAC/C;;;;OAIG;IACH,OAAO,CAAC,kBAAkB,CAAuB;IAEjD,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,EA0CzC;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,CAW1C;IAED,OAAO,CAAC,kBAAkB;CAqB3B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,qBAAqB,GAC7B,qBAAqB,CAEvB"}

package/lib/time-sync.d.ts

@@ -15,6 +15,19 @@ export declare function calculateTimeSync(clientSendTime: number, clientReceiveT
     offset: number;
     rtt: number;
 };
+/**
+ * The interval to wait before the next PING, given the one just used.
+ *
+ * Grows geometrically to {@link MAX_SYNC_INTERVAL}: the first pings after
+ * connecting are what converge the offset, and re-measuring it every few
+ * seconds forever buys nothing — the clock difference does not move, while on a
+ * relay transport each ping is a billed message in both directions and the only
+ * traffic an idle table generates at all.
+ *
+ * @param current - Interval (ms) used for the ping just sent.
+ * @returns The next interval, capped at {@link MAX_SYNC_INTERVAL}.
+ */
+export declare function nextSyncInterval(current: number): number;
 /**
  * React hook that synchronizes the client clock with the host server.
  *
@@ -25,7 +38,9 @@ export declare function calculateTimeSync(clientSendTime: number, clientReceiveT
  * called directly. Access `getServerTime()` and `rtt` from the
  * `useGameClient` return value instead.
  *
- * @param socket - The active client transport (or `null` if not yet connected).
+ * @param socket - The **open** client transport, or `null` while there is none.
+ *   Syncing starts when this becomes an open transport, so pass a value that
+ *   changes identity on open (state, not a ref read during render).
  * @returns An object with `getServerTime` (returns estimated server time), `rtt`, and `handlePong` (callback for PONG messages).
  */
 export declare function useServerTime(socket: ClientTransport | null): {

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

@@ -1 +1 @@
-{"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"}
+{"version":3,"file":"time-sync.d.ts","sourceRoot":"","sources":["../src/time-sync.ts"],"names":[],"mappings":"AASA,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;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAExD;AAED;;;;;;;;;;;;;;GAcG;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;EAiEtE"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@couch-kit/client",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "publishConfig": {
     "access": "public",
     "provenance": true
@@ -49,10 +49,15 @@
     "clean": "rm -rf dist lib"
   },
   "dependencies": {
-    "@couch-kit/core": "0.9.3"
+    "@couch-kit/core": "0.10.0"
   },
   "devDependencies": {
+    "@happy-dom/global-registrator": "^20.10.6",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/react": "^16.3.2",
+    "@types/react-dom": "^19",
     "react": "^19.0.0",
+    "react-dom": "^19.0.0",
     "typescript": "^7.0.0"
   },
   "peerDependencies": {

package/src/client.ts

@@ -18,6 +18,8 @@ import {
   shouldReconnect,
   resolveSessionSecret,
   interpretHostMessage,
+  DEFAULT_OPTIMISTIC_TIMEOUT,
+  type HostError,
 } from "./connection";
 import {
   TransportReadyState,
@@ -49,8 +51,30 @@ export interface ClientConfig<S extends IGameState, A extends IAction> {
   baseDelay?: number;
   /** Maximum delay (ms) cap for reconnection backoff (default: 10000). */
   maxDelay?: number;
+  /**
+   * How long (ms) an optimistic update may stand without the host confirming
+   * it (default: 2000). The host only broadcasts when its state changes, so an
+   * action it ignores — an illegal move, a rate-limited tap, one sent while
+   * offline — produces no update, and without this the client would keep
+   * showing a state the host never had. When the window passes with no update
+   * the client falls back to the last state the host sent. Set to `0` to
+   * disable. Has no effect without a `reducer`.
+   */
+  optimisticTimeoutMs?: number;
+  /**
+   * Keep the clock in sync with the host by exchanging PING/PONG (default:
+   * `true`). Powers `getServerTime()` and `rtt`. A game that uses neither can
+   * turn it off: on a relay transport every ping, and the host's answer, is a
+   * billed message.
+   */
+  timeSync?: boolean;
   onConnect?: () => void;
   onDisconnect?: () => void;
+  /**
+   * Called when the host rejects something this client sent (`RATE_LIMITED`,
+   * `NOT_JOINED`, `FORBIDDEN_ACTION`, `INVALID_SECRET`, …).
+   */
+  onError?: (error: HostError) => void;
   debug?: boolean;
   /**
    * Provide a custom transport factory (e.g. a cross-network relay). When
@@ -102,6 +126,15 @@ export function useGameClient<S extends IGameState, A extends IAction>(
   );
 
   const socketRef = useRef<ClientTransport | null>(null);
+  // The transport once it is open, as state: time sync has to re-run when the
+  // socket *opens*, and a ref read during render cannot signal that.
+  const [openTransport, setOpenTransport] = useState<ClientTransport | null>(
+    null,
+  );
+  // Last state the host sent, and the pending fallback to it (see
+  // `optimisticTimeoutMs`).
+  const lastServerState = useRef<S | null>(null);
+  const rollbackTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
   const reconnectAttempts = useRef(0);
   const reconnectTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
   const intentionalClose = useRef(false);
@@ -113,13 +146,33 @@ export function useGameClient<S extends IGameState, A extends IAction>(
   });
 
   // Time Sync Hook
-  const { getServerTime, rtt, handlePong } = useServerTime(socketRef.current);
+  const { getServerTime, rtt, handlePong } = useServerTime(
+    config.timeSync === false ? null : openTransport,
+  );
 
   const handlePongRef = useRef(handlePong);
   useEffect(() => {
     handlePongRef.current = handlePong;
   });
 
+  const cancelRollback = useCallback(() => {
+    if (rollbackTimer.current !== null) {
+      clearTimeout(rollbackTimer.current);
+      rollbackTimer.current = null;
+    }
+  }, []);
+
+  /** Replaces local state with the last state the host sent, if any. */
+  const rollbackToServerState = useCallback(() => {
+    cancelRollback();
+    const serverState = lastServerState.current;
+    if (serverState === null) return;
+    dispatchLocal({
+      type: InternalActionTypes.HYDRATE,
+      payload: serverState,
+    } as InternalAction<S>);
+  }, [cancelRollback]);
+
   const maxRetries = config.maxRetries ?? DEFAULT_MAX_RETRIES;
   const baseDelay = config.baseDelay ?? DEFAULT_BASE_DELAY;
   const maxDelay = config.maxDelay ?? DEFAULT_MAX_DELAY;
@@ -138,7 +191,8 @@ export function useGameClient<S extends IGameState, A extends IAction>(
     //   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");
+      if (cfg.debug)
+        console.log("[GameClient] Connecting via custom transport");
       transport = cfg.createTransport();
     } else {
       const wsUrl = resolveWebSocketUrl(
@@ -155,9 +209,18 @@ export function useGameClient<S extends IGameState, A extends IAction>(
     socketRef.current = transport;
     setStatus("connecting");
 
+    // Every handler ignores a transport that is no longer the current one. A
+    // socket closed by cleanup, `disconnect()` or a reconnect still fires its
+    // events later; without this they would overwrite the new connection's
+    // status and schedule a second, parallel reconnect.
+    const isCurrent = () => socketRef.current === transport;
+
     transport.onopen = () => {
+      if (!isCurrent()) return;
       const currentCfg = configRef.current;
       setStatus("connected");
+      setDisconnectReason(null);
+      setOpenTransport(transport);
       reconnectAttempts.current = 0;
       currentCfg.onConnect?.();
 
@@ -185,6 +248,7 @@ export function useGameClient<S extends IGameState, A extends IAction>(
     };
 
     transport.onmessage = (data) => {
+      if (!isCurrent()) return;
       let msg: HostMessage;
       try {
         msg = JSON.parse(data) as HostMessage;
@@ -199,7 +263,10 @@ export function useGameClient<S extends IGameState, A extends IAction>(
             setPlayerId(effect.playerId);
             break;
           case "hydrate":
-            // Full state replacement from the host's authoritative state.
+            // Full state replacement from the host's authoritative state. It
+            // supersedes any optimistic update, so no fallback is needed.
+            lastServerState.current = effect.state;
+            cancelRollback();
             dispatchLocal({
               type: InternalActionTypes.HYDRATE,
               payload: effect.state,
@@ -208,11 +275,22 @@ export function useGameClient<S extends IGameState, A extends IAction>(
           case "pong":
             handlePongRef.current(effect.payload);
             break;
+          case "error":
+            if (configRef.current.debug)
+              console.warn("[GameClient] Host error:", effect.error);
+            // Whatever was rejected, the host's state did not change: drop
+            // any optimistic update now instead of waiting out the timer.
+            rollbackToServerState();
+            configRef.current.onError?.(effect.error);
+            break;
         }
       }
     };
 
     transport.onclose = (code, reason) => {
+      if (!isCurrent()) return;
+      socketRef.current = null;
+      setOpenTransport(null);
       setStatus("disconnected");
       // Terminal room-level failures carry a relay error code (ROOM_NOT_FOUND,
       // ROOM_FULL, …). Surfacing it lets the UI explain the failure rather than
@@ -249,67 +327,98 @@ export function useGameClient<S extends IGameState, A extends IAction>(
     };
 
     transport.onerror = (e) => {
+      if (!isCurrent()) return;
       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, and createTransport are read
     // from configRef.
-  }, [config.url, config.wsPort, maxRetries, baseDelay, maxDelay]);
+  }, [
+    config.url,
+    config.wsPort,
+    maxRetries,
+    baseDelay,
+    maxDelay,
+    cancelRollback,
+    rollbackToServerState,
+  ]);
+
+  /**
+   * Closes the current transport for good. It is detached *before* closing, so
+   * its late `close`/`error` events are ignored and cannot trigger a reconnect
+   * or clobber the status of whatever connection replaces it.
+   */
+  const closeCurrent = useCallback(() => {
+    intentionalClose.current = true;
+    if (reconnectTimer.current) {
+      clearTimeout(reconnectTimer.current);
+      reconnectTimer.current = null;
+    }
+    cancelRollback();
+    const transport = socketRef.current;
+    if (!transport) return;
+    socketRef.current = null;
+    setOpenTransport(null);
+    transport.close();
+    configRef.current.onDisconnect?.();
+  }, [cancelRollback]);
 
   // Initial Connection
   useEffect(() => {
     connect();
-    return () => {
-      intentionalClose.current = true;
-      if (socketRef.current) socketRef.current.close();
-      if (reconnectTimer.current) clearTimeout(reconnectTimer.current);
-    };
-  }, [connect]);
+    return closeCurrent;
+  }, [connect, closeCurrent]);
 
   /**
    * Manually disconnect from the host.
    * Prevents automatic reconnection.
    */
   const disconnect = useCallback(() => {
-    intentionalClose.current = true;
-    if (reconnectTimer.current) {
-      clearTimeout(reconnectTimer.current);
-      reconnectTimer.current = null;
-    }
-    if (socketRef.current) {
-      socketRef.current.close();
-      socketRef.current = null;
-    }
+    closeCurrent();
     setStatus("disconnected");
-  }, []);
+  }, [closeCurrent]);
 
   /**
    * Manually reconnect to the host.
    * Resets the reconnection attempt counter.
    */
   const reconnect = useCallback(() => {
-    disconnect();
+    closeCurrent();
     reconnectAttempts.current = 0;
-    // Small delay to let the close complete
-    setTimeout(() => connect(), 50);
-  }, [disconnect, connect]);
+    connect();
+  }, [closeCurrent, connect]);
 
   // Action Dispatcher
-  const sendAction = useCallback((action: A) => {
-    // 1. Optimistic Update
-    dispatchLocal(action);
-
-    // 2. Send to Host
-    if (socketRef.current?.readyState === TransportReadyState.OPEN) {
-      socketRef.current.send(
-        JSON.stringify({
-          type: MessageTypes.ACTION,
-          payload: action,
-        }),
-      );
-    }
-  }, []);
+  const sendAction = useCallback(
+    (action: A) => {
+      // 1. Optimistic Update
+      dispatchLocal(action);
+
+      // The host stays silent when an action changes nothing, so an optimistic
+      // update it ignored would otherwise stand forever. Arm a single fallback to
+      // the last server state; the next STATE_UPDATE cancels it.
+      const cfg = configRef.current;
+      const timeout = cfg.optimisticTimeoutMs ?? DEFAULT_OPTIMISTIC_TIMEOUT;
+      if (cfg.reducer && timeout > 0 && rollbackTimer.current === null) {
+        rollbackTimer.current = setTimeout(() => {
+          rollbackTimer.current = null;
+          rollbackToServerState();
+        }, timeout);
+      }
+
+      // 2. Send to Host
+      if (socketRef.current?.readyState === TransportReadyState.OPEN) {
+        socketRef.current.send(
+          JSON.stringify({
+            type: MessageTypes.ACTION,
+            payload: action,
+          }),
+        );
+      }
+    },
+    [rollbackToServerState],
+  );
 
   return {
     status,

package/src/connection.ts

@@ -3,6 +3,7 @@ import {
   DEFAULT_WS_PORT_OFFSET,
   DEFAULT_WS_PATH,
   generateId,
+  isValidSecret,
   type HostMessage,
 } from "@couch-kit/core";
 
@@ -19,6 +20,12 @@ import {
 /** localStorage key under which the session-recovery secret is persisted. */
 export const SESSION_SECRET_KEY = "ck_secret";
 
+/**
+ * Default time (ms) an optimistic update may stand without the host confirming
+ * it before the client falls back to the last state the host sent.
+ */
+export const DEFAULT_OPTIMISTIC_TIMEOUT = 2000;
+
 /** The subset of `WebSocket` close codes that must NOT trigger a reconnect. */
 const NON_RECOVERABLE_CLOSE_CODES = new Set<number>([
   1008, // policy violation (e.g. INVALID_SECRET / FORBIDDEN_ACTION)
@@ -110,9 +117,12 @@ export type SecretStorage = Pick<Storage, "getItem" | "setItem">;
  * Resolve the session-recovery secret.
  *
  * Reuses an existing secret from storage when present, otherwise generates a
- * new one and persists it. When storage is unavailable or throws (e.g. Safari
- * private browsing, restrictive WebViews), a fresh secret is generated without
- * persistence so a JOIN can still proceed.
+ * new one and persists it. A stored value the host would reject (corrupted or
+ * written by something else) is replaced rather than reused — otherwise every
+ * JOIN would fail with `INVALID_SECRET` until the user cleared site data. When
+ * storage is unavailable or throws (e.g. Safari private browsing, restrictive
+ * WebViews), a fresh secret is generated without persistence so a JOIN can
+ * still proceed.
  */
 export function resolveSessionSecret(
   storage: SecretStorage | null | undefined,
@@ -121,7 +131,7 @@ export function resolveSessionSecret(
   try {
     if (!storage) return generate();
     const stored = storage.getItem(SESSION_SECRET_KEY);
-    if (stored) return stored;
+    if (stored && isValidSecret(stored)) return stored;
     const secret = generate();
     storage.setItem(SESSION_SECRET_KEY, secret);
     return secret;
@@ -138,15 +148,21 @@ export function resolveSessionSecret(
 export type HostMessageEffect<S> =
   | { kind: "setPlayerId"; playerId: string }
   | { kind: "hydrate"; state: S }
-  | { kind: "pong"; payload: PongPayload };
+  | { kind: "pong"; payload: PongPayload }
+  | { kind: "error"; error: HostError };
+
+/**
+ * A rejection reported by the host — e.g. `RATE_LIMITED`, `NOT_JOINED`,
+ * `FORBIDDEN_ACTION`, `INVALID_SECRET`.
+ */
+export type HostError = Extract<HostMessage, { type: "ERROR" }>["payload"];
 
 /** Payload of a `PONG` host message. */
 export type PongPayload = Extract<HostMessage, { type: "PONG" }>["payload"];
 
 /**
  * Translate a parsed host message into the ordered list of effects the client
- * should apply. Unknown/irrelevant message types (e.g. `ERROR`) yield no
- * effects.
+ * should apply. Unknown message types yield no effects.
  */
 export function interpretHostMessage<S>(
   msg: HostMessage,
@@ -166,6 +182,8 @@ export function interpretHostMessage<S>(
         { kind: "setPlayerId", playerId: msg.payload.playerId },
         { kind: "hydrate", state: msg.payload.state as S },
       ];
+    case MessageTypes.ERROR:
+      return [{ kind: "error", error: msg.payload }];
     default:
       return [];
   }

package/src/relay-protocol.ts

@@ -28,6 +28,8 @@ export const RelayMessageTypes = {
   PEER_LEFT: "PEER_LEFT",
   /** Bidirectional: carries an opaque Couch Kit JSON message as `data`. */
   DATA: "DATA",
+  /** Display → relay: one frame carrying a different payload per phone. */
+  DATA_MULTI: "DATA_MULTI",
   /** Relay → client: a protocol/room error. */
   ERROR: "ERROR",
 } as const;
@@ -44,8 +46,21 @@ export const RelayErrorCodes = {
   RATE_LIMITED: "RATE_LIMITED",
   /** Relay is at its room capacity. */
   SERVER_BUSY: "SERVER_BUSY",
+  /**
+   * The display hosting the room disconnected, so the room is gone. Never sent
+   * as an `ERROR` frame: the relay closes each phone's socket with
+   * {@link RELAY_CLOSE_HOST_LEFT} and the client transport reports this code as
+   * the close reason.
+   */
+  HOST_LEFT: "HOST_LEFT",
 } as const;
 
+/**
+ * WebSocket close code the relay uses when a room's host disconnects and its
+ * phones are dropped with it.
+ */
+export const RELAY_CLOSE_HOST_LEFT = 4001;
+
 export type RelayErrorCode =
   (typeof RelayErrorCodes)[keyof typeof RelayErrorCodes];
 
@@ -109,6 +124,23 @@ export interface DataMessage {
   data: string;
 }
 
+/**
+ * Display → relay: one envelope carrying a different payload per phone.
+ *
+ * `payloads` maps a phone's `peerId` to the already-serialized Couch Kit
+ * message for that phone. The relay unpacks it into ordinary
+ * {@link DataMessage} frames, so phones never see this type — it exists purely
+ * so a projected game costs one inbound relay message per state change instead
+ * of one per player. Peer ids the room does not know are skipped.
+ *
+ * Host-only: the relay rejects it from a phone.
+ */
+export interface DataMultiMessage {
+  type: typeof RelayMessageTypes.DATA_MULTI;
+  roomId: string;
+  payloads: Record<string, string>;
+}
+
 /** Relay → client: a protocol/room error. */
 export interface RelayErrorMessage {
   type: typeof RelayMessageTypes.ERROR;
@@ -118,9 +150,7 @@ export interface RelayErrorMessage {
 
 /** Any message a client may send to the relay. */
 export type RelayClientMessage =
-  | CreateRoomMessage
-  | JoinRoomMessage
-  | DataMessage;
+  CreateRoomMessage | JoinRoomMessage | DataMessage | DataMultiMessage;
 
 /** Any message the relay may send to a client. */
 export type RelayServerMessage =

package/src/relay-room.ts

@@ -93,6 +93,8 @@ export function describeRelayError(reason: string | null): string | null {
       return "That room isn't open. Check the code on the screen.";
     case RelayErrorCodes.ROOM_FULL:
       return "That room is full.";
+    case RelayErrorCodes.HOST_LEFT:
+      return "The host screen closed, so this game has ended.";
     case RelayErrorCodes.RATE_LIMITED:
       return "Too many messages — slow down and try again.";
     case RelayErrorCodes.ROOM_EXISTS:

package/src/relay-transport.ts

@@ -4,6 +4,8 @@ import {
   type CreateClientTransport,
 } from "./transport";
 import {
+  RELAY_CLOSE_HOST_LEFT,
+  RelayErrorCodes,
   RelayMessageTypes,
   relayRoomUrl,
   type RelayServerMessage,
@@ -79,6 +81,16 @@ export class RelayClientTransport implements ClientTransport {
 
     this.ws.onclose = (event: CloseEvent) => {
       this.state = TransportReadyState.CLOSED;
+      // The host leaving ends the room: retrying the same code can only come
+      // back ROOM_NOT_FOUND, so report it as terminal with a reason the UI can
+      // explain.
+      if (
+        this.pendingCloseCode === null &&
+        event.code === RELAY_CLOSE_HOST_LEFT
+      ) {
+        this.pendingCloseCode = POLICY_CLOSE_CODE;
+        this.pendingCloseReason = RelayErrorCodes.HOST_LEFT;
+      }
       const code = this.pendingCloseCode ?? event.code;
       this.onclose?.(code, this.pendingCloseReason ?? event.reason);
     };
@@ -104,7 +116,10 @@ export class RelayClientTransport implements ClientTransport {
   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))) {
+    if (
+      code !== undefined &&
+      (code === 1000 || (code >= 3000 && code <= 4999))
+    ) {
       this.ws.close(code, reason);
     } else {
       this.ws.close();

package/src/time-sync.ts

@@ -3,6 +3,8 @@ import {
   MessageTypes,
   generateId,
   DEFAULT_SYNC_INTERVAL,
+  MAX_SYNC_INTERVAL,
+  SYNC_BACKOFF_FACTOR,
   MAX_PENDING_PINGS,
 } from "@couch-kit/core";
 import { TransportReadyState, type ClientTransport } from "./transport";
@@ -38,6 +40,22 @@ export function calculateTimeSync(
   return { offset, rtt };
 }
 
+/**
+ * The interval to wait before the next PING, given the one just used.
+ *
+ * Grows geometrically to {@link MAX_SYNC_INTERVAL}: the first pings after
+ * connecting are what converge the offset, and re-measuring it every few
+ * seconds forever buys nothing — the clock difference does not move, while on a
+ * relay transport each ping is a billed message in both directions and the only
+ * traffic an idle table generates at all.
+ *
+ * @param current - Interval (ms) used for the ping just sent.
+ * @returns The next interval, capped at {@link MAX_SYNC_INTERVAL}.
+ */
+export function nextSyncInterval(current: number): number {
+  return Math.min(current * SYNC_BACKOFF_FACTOR, MAX_SYNC_INTERVAL);
+}
+
 /**
  * React hook that synchronizes the client clock with the host server.
  *
@@ -48,7 +66,9 @@ export function calculateTimeSync(
  * called directly. Access `getServerTime()` and `rtt` from the
  * `useGameClient` return value instead.
  *
- * @param socket - The active client transport (or `null` if not yet connected).
+ * @param socket - The **open** client transport, or `null` while there is none.
+ *   Syncing starts when this becomes an open transport, so pass a value that
+ *   changes identity on open (state, not a ref read during render).
  * @returns An object with `getServerTime` (returns estimated server time), `rtt`, and `handlePong` (callback for PONG messages).
  */
 export function useServerTime(socket: ClientTransport | null) {
@@ -85,9 +105,19 @@ export function useServerTime(socket: ClientTransport | null) {
   );
 
   // Periodic Sync
+  //
+  // The interval backs off from DEFAULT_SYNC_INTERVAL to MAX_SYNC_INTERVAL
+  // rather than staying fast forever: the first few pings are what converge the
+  // offset, and after that we are re-measuring a clock difference that does not
+  // move. A self-rescheduling timeout is used instead of setInterval because
+  // the delay changes between ticks. Backoff state lives inside the effect, so
+  // a new socket — including a reconnect — starts fast again.
   useEffect(() => {
     if (!socket || socket.readyState !== TransportReadyState.OPEN) return;
 
+    let delay = DEFAULT_SYNC_INTERVAL;
+    let timer: ReturnType<typeof setTimeout> | null = null;
+
     const sync = () => {
       // Prevent unbounded growth if PONGs are lost
       if (pings.current.size >= MAX_PENDING_PINGS) {
@@ -105,13 +135,20 @@ export function useServerTime(socket: ClientTransport | null) {
           payload: { id, timestamp },
         }),
       );
+
+      delay = nextSyncInterval(delay);
+      timer = setTimeout(sync, delay);
     };
 
     // Initial sync
     sync();
 
-    const interval = setInterval(sync, DEFAULT_SYNC_INTERVAL);
-    return () => clearInterval(interval);
+    const pending = pings.current;
+    return () => {
+      if (timer !== null) clearTimeout(timer);
+      // PONGs for this socket's pings can no longer arrive.
+      pending.clear();
+    };
   }, [socket]);
 
   return { getServerTime, rtt: timeSync.rtt, handlePong };