@couch-kit/client 0.14.0 → 0.15.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @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

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

@@ -98,9 +98,11 @@ function useServerTime(socket) {
       timer = setTimeout(sync, delay);
     };
     sync();
+    const pending = pings.current;
     return () => {
       if (timer !== null)
         clearTimeout(timer);
+      pending.clear();
     };
   }, [socket]);
   return { getServerTime, rtt: timeSync.rtt, handlePong };
@@ -111,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
@@ -144,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);
@@ -169,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 [];
   }
@@ -181,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);
@@ -188,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;
@@ -214,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);
@@ -235,6 +265,8 @@ function useGameClient(config) {
       }
     };
     transport.onmessage = (data) => {
+      if (!isCurrent())
+        return;
       let msg;
       try {
         msg = JSON.parse(data);
@@ -248,6 +280,8 @@ function useGameClient(config) {
             setPlayerId(effect.playerId);
             break;
           case "hydrate":
+            lastServerState.current = effect.state;
+            cancelRollback();
             dispatchLocal({
               type: InternalActionTypes.HYDRATE,
               payload: effect.state
@@ -256,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?.();
@@ -279,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,
@@ -352,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);
@@ -394,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);
     };
@@ -491,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:
@@ -640,27 +711,29 @@ function useDebugPanel(options) {
   };
 }
 export {
-  useServerTime,
-  useRelayRoom,
-  usePreload,
-  useGameClient,
-  useDebugPanel,
-  shouldReconnect,
-  resolveWebSocketUrl,
-  resolveSessionSecret,
-  relayRoomUrl,
-  normalizeRoomCode,
-  nextSyncInterval,
-  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

@@ -44,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 {

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

@@ -38,7 +38,9 @@ export declare function nextSyncInterval(current: number): number;
  * 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":"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;;;;;;;;;;;;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;EA8DtE"}
+{"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.14.0",
+  "version": "0.15.0",
   "publishConfig": {
     "access": "public",
     "provenance": true
@@ -52,7 +52,12 @@
     "@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

@@ -46,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];
 

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

@@ -66,7 +66,9 @@ export function nextSyncInterval(current: number): number {
  * 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) {
@@ -141,8 +143,11 @@ export function useServerTime(socket: ClientTransport | null) {
     // Initial sync
     sync();
 
+    const pending = pings.current;
     return () => {
       if (timer !== null) clearTimeout(timer);
+      // PONGs for this socket's pings can no longer arrive.
+      pending.clear();
     };
   }, [socket]);