@couch-kit/client 0.16.1 → 0.17.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @couch-kit/client
 
+## 0.17.0
+
+### Minor Changes
+
+- [#227](https://github.com/faluciano/react-native-couch-kit/pull/227) [`8ef31ad`](https://github.com/faluciano/react-native-couch-kit/commit/8ef31adc53dc7342f1d81f8ba2e4acb6c8c1433e) Thanks [@faluciano](https://github.com/faluciano)! - **New features:** A phone can get out of the dead ends that used to need a page reload.
+
+  - `connectionKey` option. Changing it opens a fresh connection with the retry budget reset. With a relay, pass the room code: a phone that typed a wrong code (`ROOM_NOT_FOUND`, which is final) now connects as soon as the right code is entered. Retry the same code with `reconnect()`.
+  - `reconnectOnResume` (default `true`): when the page becomes visible again, is restored from the back/forward cache, or the browser comes back online, the client reconnects at once with a fresh retry budget. A phone that slept through its five retries used to stay disconnected. Final closes and `disconnect()` are not undone.
+  - `disconnectReason` now clears when a new connection starts, not when it opens.
+  - `sendAction` returns `true` if the action was sent and `false` when there is no open connection. An action that was not sent is no longer applied optimistically.
+  - New exported types `ClientStatus` and `UseGameClientResult`, and helpers `isRecoverableClose` and `sessionSecretKey`.
+
+  **Security:** The relay transport keeps a separate session secret per relay and room (`ClientTransport.sessionScope`, also settable as the `sessionScope` option). Anyone can open a relay room and share its link; with one secret per site, that room's display could collect a phone's secret and rejoin the player's real room as them. The LAN default is unchanged, so existing players keep their identity.
+
+### Patch Changes
+
+- Updated dependencies [[`8ef31ad`](https://github.com/faluciano/react-native-couch-kit/commit/8ef31adc53dc7342f1d81f8ba2e4acb6c8c1433e)]:
+  - @couch-kit/core@0.10.3
+
 ## 0.16.1
 
 ### Patch Changes

package/README.md

@@ -36,6 +36,10 @@ Config:
 - `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.
+- `createTransport?`: custom transport factory, e.g. `createRelayTransport({ url, roomId })` for cross-network play
+- `connectionKey?`: identifies what `createTransport` connects to. Changing it opens a fresh connection with the retry budget reset. With a relay, pass the room code, so a phone that typed a wrong code connects as soon as the right one is entered. To retry the *same* code, call `reconnect()`.
+- `reconnectOnResume?`: reconnect at once when the page becomes visible again, is restored from the back/forward cache, or the browser comes back online (default: `true`). A phone that slept through its retries otherwise stays disconnected. Final closes and `disconnect()` are not undone.
+- `sessionScope?`: keep a separate session secret (and so a separate player identity) per scope. The relay transport scopes the secret to its relay and room automatically, so a secret sent to one room never reaches another.
 - `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`, …)
@@ -45,7 +49,7 @@ Returns:
 - `status`: `'connecting' | 'connected' | 'disconnected' | 'error'`
 - `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
+- `sendAction(action)`: optimistic dispatch + send to host. Returns `true` if sent, `false` when there is no open connection (nothing is applied or queued then). The host can still reject a sent action; that arrives through `onError`.
 - `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

package/dist/index.js

@@ -117,6 +117,9 @@ import {
   isValidSecret
 } from "@couch-kit/core";
 var SESSION_SECRET_KEY = "ck_secret";
+function sessionSecretKey(scope) {
+  return scope ? `${SESSION_SECRET_KEY}:${scope}` : SESSION_SECRET_KEY;
+}
 var DEFAULT_OPTIMISTIC_TIMEOUT = 2000;
 var NON_RECOVERABLE_CLOSE_CODES = new Set([
   1008,
@@ -136,22 +139,26 @@ function resolveWebSocketUrl(config, location) {
 function computeBackoffDelay(attempt, baseDelay, maxDelay) {
   return Math.min(baseDelay * Math.pow(2, attempt), maxDelay);
 }
+function isRecoverableClose(closeCode) {
+  return !NON_RECOVERABLE_CLOSE_CODES.has(closeCode);
+}
 function shouldReconnect(decision) {
   if (decision.intentionalClose)
     return false;
-  if (NON_RECOVERABLE_CLOSE_CODES.has(decision.closeCode))
+  if (!isRecoverableClose(decision.closeCode))
     return false;
   return decision.attempts < decision.maxRetries;
 }
-function resolveSessionSecret(storage, generate = generateId2) {
+function resolveSessionSecret(storage, generate = generateId2, scope) {
+  const key = sessionSecretKey(scope);
   try {
     if (!storage)
       return generate();
-    const stored = storage.getItem(SESSION_SECRET_KEY);
+    const stored = storage.getItem(key);
     if (stored && isValidSecret(stored))
       return stored;
     const secret = generate();
-    storage.setItem(SESSION_SECRET_KEY, secret);
+    storage.setItem(key, secret);
     return secret;
   } catch {
     return generate();
@@ -193,6 +200,7 @@ function useGameClient(config) {
   const reconnectAttempts = useRef2(0);
   const reconnectTimer = useRef2(null);
   const intentionalClose = useRef2(false);
+  const resumable = useRef2(false);
   const configRef = useRef2(config);
   useEffect2(() => {
     configRef.current = config;
@@ -239,6 +247,7 @@ function useGameClient(config) {
     }
     socketRef.current = transport;
     setStatus("connecting");
+    setDisconnectReason(null);
     const isCurrent = () => socketRef.current === transport;
     transport.onopen = () => {
       if (!isCurrent())
@@ -249,7 +258,7 @@ function useGameClient(config) {
       setOpenTransport(transport);
       reconnectAttempts.current = 0;
       currentCfg.onConnect?.();
-      const secret = resolveSessionSecret(typeof localStorage !== "undefined" ? localStorage : null);
+      const secret = resolveSessionSecret(typeof localStorage !== "undefined" ? localStorage : null, undefined, transport.sessionScope ?? currentCfg.sessionScope);
       try {
         transport.send(JSON.stringify({
           type: MessageTypes3.JOIN,
@@ -306,6 +315,7 @@ function useGameClient(config) {
       setOpenTransport(null);
       setStatus("disconnected");
       setDisconnectReason(reason ? reason : null);
+      resumable.current = !intentionalClose.current && isRecoverableClose(code);
       configRef.current.onDisconnect?.();
       if (!shouldReconnect({
         intentionalClose: intentionalClose.current,
@@ -332,6 +342,7 @@ function useGameClient(config) {
   }, [
     config.url,
     config.wsPort,
+    config.connectionKey,
     maxRetries,
     baseDelay,
     maxDelay,
@@ -340,6 +351,7 @@ function useGameClient(config) {
   ]);
   const closeCurrent = useCallback2(() => {
     intentionalClose.current = true;
+    resumable.current = false;
     if (reconnectTimer.current) {
       clearTimeout(reconnectTimer.current);
       reconnectTimer.current = null;
@@ -354,9 +366,39 @@ function useGameClient(config) {
     configRef.current.onDisconnect?.();
   }, [cancelRollback]);
   useEffect2(() => {
+    reconnectAttempts.current = 0;
     connect();
     return closeCurrent;
   }, [connect, closeCurrent]);
+  useEffect2(() => {
+    if (config.reconnectOnResume === false)
+      return;
+    if (typeof window === "undefined")
+      return;
+    const resume = () => {
+      if (typeof document !== "undefined" && document.visibilityState === "hidden") {
+        return;
+      }
+      if (socketRef.current || !resumable.current)
+        return;
+      if (reconnectTimer.current) {
+        clearTimeout(reconnectTimer.current);
+        reconnectTimer.current = null;
+      }
+      if (configRef.current.debug)
+        console.log("[GameClient] Page resumed, reconnecting");
+      reconnectAttempts.current = 0;
+      connect();
+    };
+    document?.addEventListener("visibilitychange", resume);
+    window.addEventListener("online", resume);
+    window.addEventListener("pageshow", resume);
+    return () => {
+      document?.removeEventListener("visibilitychange", resume);
+      window.removeEventListener("online", resume);
+      window.removeEventListener("pageshow", resume);
+    };
+  }, [connect, config.reconnectOnResume]);
   const disconnect = useCallback2(() => {
     closeCurrent();
     setStatus("disconnected");
@@ -367,6 +409,12 @@ function useGameClient(config) {
     connect();
   }, [closeCurrent, connect]);
   const sendAction = useCallback2((action) => {
+    const transport = socketRef.current;
+    if (transport?.readyState !== TransportReadyState.OPEN) {
+      if (configRef.current.debug)
+        console.warn("[GameClient] Not connected, action dropped:", action);
+      return false;
+    }
     dispatchLocal(action);
     const cfg = configRef.current;
     const timeout = cfg.optimisticTimeoutMs ?? DEFAULT_OPTIMISTIC_TIMEOUT;
@@ -376,12 +424,18 @@ function useGameClient(config) {
         rollbackToServerState();
       }, timeout);
     }
-    if (socketRef.current?.readyState === TransportReadyState.OPEN) {
-      socketRef.current.send(JSON.stringify({
+    try {
+      transport.send(JSON.stringify({
         type: MessageTypes3.ACTION,
         payload: action
       }));
+    } catch (e) {
+      if (configRef.current.debug)
+        console.error("[GameClient] Failed to send action:", e);
+      rollbackToServerState();
+      return false;
     }
+    return true;
   }, [rollbackToServerState]);
   return {
     status,
@@ -435,6 +489,7 @@ var POLICY_CLOSE_CODE = 1008;
 class RelayClientTransport {
   ws;
   roomId;
+  sessionScope;
   state = TransportReadyState.CONNECTING;
   pendingCloseCode = null;
   pendingCloseReason = null;
@@ -444,6 +499,7 @@ class RelayClientTransport {
   onerror;
   constructor(options) {
     this.roomId = options.roomId;
+    this.sessionScope = `relay:${options.url}#${options.roomId.toUpperCase()}`;
     this.ws = new WebSocket(relayRoomUrl(options.url, options.roomId));
     this.ws.onopen = () => {
       this.ws.send(JSON.stringify({
@@ -734,11 +790,13 @@ export {
   createWebSocketTransport,
   describeRelayError,
   interpretHostMessage,
+  isRecoverableClose,
   nextSyncInterval,
   normalizeRoomCode,
   relayRoomUrl,
   resolveSessionSecret,
   resolveWebSocketUrl,
+  sessionSecretKey,
   shouldReconnect,
   useDebugPanel,
   useGameClient,

package/lib/client.d.ts

@@ -1,6 +1,8 @@
 import { type IGameState, type IAction } from "@couch-kit/core";
 import { type HostError } from "./connection";
 import { type CreateClientTransport } from "./transport";
+/** Connection status reported by {@link useGameClient}. */
+export type ClientStatus = "connecting" | "connected" | "disconnected" | "error";
 export interface ClientConfig<S extends IGameState, A extends IAction> {
     url?: string;
     wsPort?: number;
@@ -56,6 +58,30 @@ export interface ClientConfig<S extends IGameState, A extends IAction> {
      * already-connecting transport each time.
      */
     createTransport?: CreateClientTransport;
+    /**
+     * Identifies what `createTransport` connects to. Changing it closes the
+     * current connection and opens a fresh one, with the retry budget reset.
+     *
+     * `createTransport` itself is read on each connect but is usually a new
+     * function every render, so it cannot signal a change. With a relay, pass
+     * the room code: a phone that typed a wrong code (`ROOM_NOT_FOUND`, which is
+     * final) then connects as soon as the player enters the right one. To retry
+     * the *same* code, call `reconnect()`.
+     */
+    connectionKey?: string | number | null;
+    /**
+     * Reconnect at once when the page becomes visible again, is restored from
+     * the back/forward cache, or the browser comes back online (default:
+     * `true`). A phone that slept through the reconnect attempts would otherwise
+     * stay disconnected until the page was reloaded. Final closes (a room that
+     * does not exist, a rejected secret) and `disconnect()` are not undone.
+     */
+    reconnectOnResume?: boolean;
+    /**
+     * Scope for the session secret when the transport does not set its own (see
+     * `ClientTransport.sessionScope`). Players keep one identity per scope.
+     */
+    sessionScope?: string;
 }
 /**
  * React hook that connects the web controller to the TV host via WebSocket.
@@ -65,7 +91,7 @@ export interface ClientConfig<S extends IGameState, A extends IAction> {
  * reconnection with exponential backoff.
  *
  * @param config - Client configuration including reducer, initial state, and connection options.
- * @returns An object with `status`, `state`, `playerId`, `sendAction`, `getServerTime`, `rtt`, `disconnect`, and `reconnect`.
+ * @returns An object with `status`, `state`, `playerId`, `disconnectReason`, `sendAction`, `getServerTime`, `rtt`, `disconnect`, and `reconnect`.
  *
  * @example
  * ```tsx
@@ -76,7 +102,7 @@ export interface ClientConfig<S extends IGameState, A extends IAction> {
  * ```
  */
 export declare function useGameClient<S extends IGameState, A extends IAction>(config: ClientConfig<S, A>): {
-    status: "connected" | "connecting" | "disconnected" | "error";
+    status: ClientStatus;
     state: S;
     playerId: string | null;
     /**
@@ -85,7 +111,7 @@ export declare function useGameClient<S extends IGameState, A extends IAction>(c
      * `null` when connected or when the cause is unknown.
      */
     disconnectReason: string | null;
-    sendAction: (action: A) => void;
+    sendAction: (action: A) => boolean;
     getServerTime: () => number;
     /** Round-trip time (ms) to the server. Updated periodically via PING/PONG. */
     rtt: number;
@@ -94,4 +120,6 @@ export declare function useGameClient<S extends IGameState, A extends IAction>(c
     /** Manually reconnect to the host. Resets the reconnection attempt counter. */
     reconnect: () => void;
 };
+/** What {@link useGameClient} returns. */
+export type UseGameClientResult<S extends IGameState, A extends IAction> = ReturnType<typeof useGameClient<S, A>>;
 //# sourceMappingURL=client.d.ts.map

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;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"}
+{"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,EAQL,KAAK,SAAS,EACf,MAAM,cAAc,CAAC;AACtB,OAAO,EAIL,KAAK,qBAAqB,EAC3B,MAAM,aAAa,CAAC;AAErB,2DAA2D;AAC3D,MAAM,MAAM,YAAY,GACtB,YAAY,GAAG,WAAW,GAAG,cAAc,GAAG,OAAO,CAAC;AAExD,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;IACxC;;;;;;;;;OASG;IACH,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IACvC;;;;;;OAMG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,UAAU,EAAE,CAAC,SAAS,OAAO,EACnE,MAAM,EAAE,YAAY,CAAC,CAAC,EAAE,CAAC,CAAC;;;;IAiYxB;;;;OAIG;;yBAlDM,CAAC,KAAG,OAAO;;IAsDpB,8EAA8E;;IAE9E,0EAA0E;;IAE1E,+EAA+E;;EAGlF;AAED,0CAA0C;AAC1C,MAAM,MAAM,mBAAmB,CAC7B,CAAC,SAAS,UAAU,EACpB,CAAC,SAAS,OAAO,IACf,UAAU,CAAC,OAAO,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC"}

package/lib/connection.d.ts

@@ -10,6 +10,12 @@ 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";
+/**
+ * The storage key for a session scope: {@link SESSION_SECRET_KEY} itself when
+ * unscoped (so existing LAN players keep their identity), otherwise suffixed
+ * with the scope.
+ */
+export declare function sessionSecretKey(scope?: string): string;
 /**
  * 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.
@@ -56,6 +62,11 @@ export interface ReconnectDecision {
     /** Maximum number of reconnection attempts permitted. */
     maxRetries: number;
 }
+/**
+ * Whether a close with this code may be retried at all, regardless of how many
+ * attempts remain. Policy (1008) and internal-error (1011) closes are final.
+ */
+export declare function isRecoverableClose(closeCode: number): boolean;
 /**
  * Decide whether the client should attempt an automatic reconnect.
  *
@@ -76,8 +87,11 @@ export type SecretStorage = Pick<Storage, "getItem" | "setItem">;
  * 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.
+ *
+ * `scope` keeps a separate secret per scope (see
+ * `ClientTransport.sessionScope`).
  */
-export declare function resolveSessionSecret(storage: SecretStorage | null | undefined, generate?: () => string): string;
+export declare function resolveSessionSecret(storage: SecretStorage | null | undefined, generate?: () => string, scope?: string): string;
 /**
  * A side-effect descriptor produced by {@link interpretHostMessage}. The client
  * hook executes these against React state so the routing logic itself stays

package/lib/connection.d.ts.map

@@ -1 +1 @@
-{"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"}
+{"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;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED;;;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;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAE7D;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;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,aAAa,GAAG,IAAI,GAAG,SAAS,EACzC,QAAQ,GAAE,MAAM,MAAmB,EACnC,KAAK,CAAC,EAAE,MAAM,GACb,MAAM,CAYR;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-transport.d.ts

@@ -19,6 +19,12 @@ export interface RelayTransportOptions {
 export declare class RelayClientTransport implements ClientTransport {
     private readonly ws;
     private readonly roomId;
+    /**
+     * One session secret per relay and room. Anyone can open a relay room and
+     * share its link; a secret shared across rooms would let that room's display
+     * collect it and rejoin the player's real room as them.
+     */
+    readonly sessionScope: string;
     private state;
     /** When set, the code reported to `onclose` instead of the raw socket code. */
     private pendingCloseCode;

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;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"}
+{"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;;;;OAIG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,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,EA2CzC;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/transport.d.ts

@@ -49,6 +49,14 @@ export interface ClientTransport {
     onclose?: (code: number, reason?: string) => void;
     /** Invoked on a transport-level error. */
     onerror?: (error?: unknown) => void;
+    /**
+     * Scope for the session secret this transport's JOIN carries. The client
+     * keeps one secret per scope, so a secret sent to one game never reaches
+     * another. The relay transport sets it to the relay URL and room code: any
+     * party can open a relay room, and a phone's secret is what proves it is
+     * that player. Omit for a single trusted host (the LAN default).
+     */
+    readonly sessionScope?: string;
 }
 /**
  * Factory that creates a fresh {@link ClientTransport}. `useGameClient` calls

package/lib/transport.d.ts.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@couch-kit/client",
-  "version": "0.16.1",
+  "version": "0.17.0",
   "publishConfig": {
     "access": "public",
     "provenance": true
@@ -49,7 +49,7 @@
     "clean": "rm -rf dist lib"
   },
   "dependencies": {
-    "@couch-kit/core": "0.10.2"
+    "@couch-kit/core": "0.10.3"
   },
   "devDependencies": {
     "@happy-dom/global-registrator": "^21.0.0",

package/src/client.ts

@@ -16,6 +16,7 @@ import {
   resolveWebSocketUrl,
   computeBackoffDelay,
   shouldReconnect,
+  isRecoverableClose,
   resolveSessionSecret,
   interpretHostMessage,
   DEFAULT_OPTIMISTIC_TIMEOUT,
@@ -28,6 +29,10 @@ import {
   type CreateClientTransport,
 } from "./transport";
 
+/** Connection status reported by {@link useGameClient}. */
+export type ClientStatus =
+  "connecting" | "connected" | "disconnected" | "error";
+
 export interface ClientConfig<S extends IGameState, A extends IAction> {
   url?: string; // Full WebSocket URL (overrides auto-detection)
   wsPort?: number; // WebSocket port (default: auto-detected as HTTP port + 2)
@@ -83,6 +88,30 @@ export interface ClientConfig<S extends IGameState, A extends IAction> {
    * already-connecting transport each time.
    */
   createTransport?: CreateClientTransport;
+  /**
+   * Identifies what `createTransport` connects to. Changing it closes the
+   * current connection and opens a fresh one, with the retry budget reset.
+   *
+   * `createTransport` itself is read on each connect but is usually a new
+   * function every render, so it cannot signal a change. With a relay, pass
+   * the room code: a phone that typed a wrong code (`ROOM_NOT_FOUND`, which is
+   * final) then connects as soon as the player enters the right one. To retry
+   * the *same* code, call `reconnect()`.
+   */
+  connectionKey?: string | number | null;
+  /**
+   * Reconnect at once when the page becomes visible again, is restored from
+   * the back/forward cache, or the browser comes back online (default:
+   * `true`). A phone that slept through the reconnect attempts would otherwise
+   * stay disconnected until the page was reloaded. Final closes (a room that
+   * does not exist, a rejected secret) and `disconnect()` are not undone.
+   */
+  reconnectOnResume?: boolean;
+  /**
+   * Scope for the session secret when the transport does not set its own (see
+   * `ClientTransport.sessionScope`). Players keep one identity per scope.
+   */
+  sessionScope?: string;
 }
 
 /**
@@ -93,7 +122,7 @@ export interface ClientConfig<S extends IGameState, A extends IAction> {
  * reconnection with exponential backoff.
  *
  * @param config - Client configuration including reducer, initial state, and connection options.
- * @returns An object with `status`, `state`, `playerId`, `sendAction`, `getServerTime`, `rtt`, `disconnect`, and `reconnect`.
+ * @returns An object with `status`, `state`, `playerId`, `disconnectReason`, `sendAction`, `getServerTime`, `rtt`, `disconnect`, and `reconnect`.
  *
  * @example
  * ```tsx
@@ -106,9 +135,7 @@ export interface ClientConfig<S extends IGameState, A extends IAction> {
 export function useGameClient<S extends IGameState, A extends IAction>(
   config: ClientConfig<S, A>,
 ) {
-  const [status, setStatus] = useState<
-    "connecting" | "connected" | "disconnected" | "error"
-  >("disconnected");
+  const [status, setStatus] = useState<ClientStatus>("disconnected");
   const [playerId, setPlayerId] = useState<string | null>(null);
   /**
    * Why the last connection ended, when the transport knows. For the relay this
@@ -138,6 +165,9 @@ export function useGameClient<S extends IGameState, A extends IAction>(
   const reconnectAttempts = useRef(0);
   const reconnectTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
   const intentionalClose = useRef(false);
+  // The last close may be retried: not intentional, not a final close code.
+  // What resuming the page acts on once the backoff has given up.
+  const resumable = useRef(false);
 
   // Keep refs for values used inside connect() to avoid stale closures
   const configRef = useRef(config);
@@ -208,6 +238,7 @@ export function useGameClient<S extends IGameState, A extends IAction>(
 
     socketRef.current = transport;
     setStatus("connecting");
+    setDisconnectReason(null);
 
     // Every handler ignores a transport that is no longer the current one. A
     // socket closed by cleanup, `disconnect()` or a reconnect still fires its
@@ -227,6 +258,8 @@ export function useGameClient<S extends IGameState, A extends IAction>(
       // Session Recovery Logic -- use cryptographically random secrets
       const secret = resolveSessionSecret(
         typeof localStorage !== "undefined" ? localStorage : null,
+        undefined,
+        transport.sessionScope ?? currentCfg.sessionScope,
       );
 
       // Join with secret
@@ -296,6 +329,7 @@ export function useGameClient<S extends IGameState, A extends IAction>(
       // ROOM_FULL, …). Surfacing it lets the UI explain the failure rather than
       // sit on "connecting" forever.
       setDisconnectReason(reason ? reason : null);
+      resumable.current = !intentionalClose.current && isRecoverableClose(code);
       configRef.current.onDisconnect?.();
 
       // Don't reconnect if the close was intentional or if the server
@@ -331,12 +365,13 @@ export function useGameClient<S extends IGameState, A extends IAction>(
       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.
+    // Only re-create the connect function when what it connects to changes:
+    // URL/port, or the caller's connectionKey. Config values like name,
+    // avatar, callbacks, and createTransport are read from configRef.
   }, [
     config.url,
     config.wsPort,
+    config.connectionKey,
     maxRetries,
     baseDelay,
     maxDelay,
@@ -351,6 +386,7 @@ export function useGameClient<S extends IGameState, A extends IAction>(
    */
   const closeCurrent = useCallback(() => {
     intentionalClose.current = true;
+    resumable.current = false;
     if (reconnectTimer.current) {
       clearTimeout(reconnectTimer.current);
       reconnectTimer.current = null;
@@ -364,12 +400,49 @@ export function useGameClient<S extends IGameState, A extends IAction>(
     configRef.current.onDisconnect?.();
   }, [cancelRollback]);
 
-  // Initial Connection
+  // Initial connection, and a fresh one (with a fresh retry budget) whenever
+  // the target changes.
   useEffect(() => {
+    reconnectAttempts.current = 0;
     connect();
     return closeCurrent;
   }, [connect, closeCurrent]);
 
+  // Resume: a phone that slept, or lost its network, may have used up every
+  // retry while it could not connect. Try again the moment it is back.
+  useEffect(() => {
+    if (config.reconnectOnResume === false) return;
+    if (typeof window === "undefined") return;
+
+    const resume = () => {
+      if (
+        typeof document !== "undefined" &&
+        document.visibilityState === "hidden"
+      ) {
+        return;
+      }
+      // A live or connecting transport needs nothing; a final close stays final.
+      if (socketRef.current || !resumable.current) return;
+      if (reconnectTimer.current) {
+        clearTimeout(reconnectTimer.current);
+        reconnectTimer.current = null;
+      }
+      if (configRef.current.debug)
+        console.log("[GameClient] Page resumed, reconnecting");
+      reconnectAttempts.current = 0;
+      connect();
+    };
+
+    document?.addEventListener("visibilitychange", resume);
+    window.addEventListener("online", resume);
+    window.addEventListener("pageshow", resume);
+    return () => {
+      document?.removeEventListener("visibilitychange", resume);
+      window.removeEventListener("online", resume);
+      window.removeEventListener("pageshow", resume);
+    };
+  }, [connect, config.reconnectOnResume]);
+
   /**
    * Manually disconnect from the host.
    * Prevents automatic reconnection.
@@ -389,9 +462,24 @@ export function useGameClient<S extends IGameState, A extends IAction>(
     connect();
   }, [closeCurrent, connect]);
 
-  // Action Dispatcher
+  /**
+   * Sends an action to the host, applying it locally first when a `reducer`
+   * is configured.
+   *
+   * @returns `true` if the action was sent, `false` if there is no open
+   *   connection. Nothing is queued, and no optimistic update is applied, for
+   *   an action that was not sent. Sent actions can still be rejected by the
+   *   host; those arrive through `onError`.
+   */
   const sendAction = useCallback(
-    (action: A) => {
+    (action: A): boolean => {
+      const transport = socketRef.current;
+      if (transport?.readyState !== TransportReadyState.OPEN) {
+        if (configRef.current.debug)
+          console.warn("[GameClient] Not connected, action dropped:", action);
+        return false;
+      }
+
       // 1. Optimistic Update
       dispatchLocal(action);
 
@@ -408,14 +496,20 @@ export function useGameClient<S extends IGameState, A extends IAction>(
       }
 
       // 2. Send to Host
-      if (socketRef.current?.readyState === TransportReadyState.OPEN) {
-        socketRef.current.send(
+      try {
+        transport.send(
           JSON.stringify({
             type: MessageTypes.ACTION,
             payload: action,
           }),
         );
+      } catch (e) {
+        if (configRef.current.debug)
+          console.error("[GameClient] Failed to send action:", e);
+        rollbackToServerState();
+        return false;
       }
+      return true;
     },
     [rollbackToServerState],
   );
@@ -440,3 +534,9 @@ export function useGameClient<S extends IGameState, A extends IAction>(
     reconnect,
   };
 }
+
+/** What {@link useGameClient} returns. */
+export type UseGameClientResult<
+  S extends IGameState,
+  A extends IAction,
+> = ReturnType<typeof useGameClient<S, A>>;

package/src/connection.ts

@@ -20,6 +20,15 @@ import {
 /** localStorage key under which the session-recovery secret is persisted. */
 export const SESSION_SECRET_KEY = "ck_secret";
 
+/**
+ * The storage key for a session scope: {@link SESSION_SECRET_KEY} itself when
+ * unscoped (so existing LAN players keep their identity), otherwise suffixed
+ * with the scope.
+ */
+export function sessionSecretKey(scope?: string): string {
+  return scope ? `${SESSION_SECRET_KEY}:${scope}` : SESSION_SECRET_KEY;
+}
+
 /**
  * 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.
@@ -97,6 +106,14 @@ export interface ReconnectDecision {
   maxRetries: number;
 }
 
+/**
+ * Whether a close with this code may be retried at all, regardless of how many
+ * attempts remain. Policy (1008) and internal-error (1011) closes are final.
+ */
+export function isRecoverableClose(closeCode: number): boolean {
+  return !NON_RECOVERABLE_CLOSE_CODES.has(closeCode);
+}
+
 /**
  * Decide whether the client should attempt an automatic reconnect.
  *
@@ -106,7 +123,7 @@ export interface ReconnectDecision {
  */
 export function shouldReconnect(decision: ReconnectDecision): boolean {
   if (decision.intentionalClose) return false;
-  if (NON_RECOVERABLE_CLOSE_CODES.has(decision.closeCode)) return false;
+  if (!isRecoverableClose(decision.closeCode)) return false;
   return decision.attempts < decision.maxRetries;
 }
 
@@ -123,17 +140,22 @@ export type SecretStorage = Pick<Storage, "getItem" | "setItem">;
  * 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.
+ *
+ * `scope` keeps a separate secret per scope (see
+ * `ClientTransport.sessionScope`).
  */
 export function resolveSessionSecret(
   storage: SecretStorage | null | undefined,
   generate: () => string = generateId,
+  scope?: string,
 ): string {
+  const key = sessionSecretKey(scope);
   try {
     if (!storage) return generate();
-    const stored = storage.getItem(SESSION_SECRET_KEY);
+    const stored = storage.getItem(key);
     if (stored && isValidSecret(stored)) return stored;
     const secret = generate();
-    storage.setItem(SESSION_SECRET_KEY, secret);
+    storage.setItem(key, secret);
     return secret;
   } catch {
     return generate();

package/src/relay-transport.ts

@@ -39,6 +39,12 @@ const POLICY_CLOSE_CODE = 1008;
 export class RelayClientTransport implements ClientTransport {
   private readonly ws: WebSocket;
   private readonly roomId: string;
+  /**
+   * One session secret per relay and room. Anyone can open a relay room and
+   * share its link; a secret shared across rooms would let that room's display
+   * collect it and rejoin the player's real room as them.
+   */
+  readonly sessionScope: string;
   private state: number = TransportReadyState.CONNECTING;
   /** When set, the code reported to `onclose` instead of the raw socket code. */
   private pendingCloseCode: number | null = null;
@@ -56,6 +62,7 @@ export class RelayClientTransport implements ClientTransport {
 
   constructor(options: RelayTransportOptions) {
     this.roomId = options.roomId;
+    this.sessionScope = `relay:${options.url}#${options.roomId.toUpperCase()}`;
     this.ws = new WebSocket(relayRoomUrl(options.url, options.roomId));
 
     this.ws.onopen = () => {

package/src/transport.ts

@@ -51,6 +51,14 @@ export interface ClientTransport {
   onclose?: (code: number, reason?: string) => void;
   /** Invoked on a transport-level error. */
   onerror?: (error?: unknown) => void;
+  /**
+   * Scope for the session secret this transport's JOIN carries. The client
+   * keeps one secret per scope, so a secret sent to one game never reaches
+   * another. The relay transport sets it to the relay URL and room code: any
+   * party can open a relay room, and a phone's secret is what proves it is
+   * that player. Omit for a single trusted host (the LAN default).
+   */
+  readonly sessionScope?: string;
 }
 
 /**