@couch-kit/client 0.8.6 → 0.8.7

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # @couch-kit/client
 
+## 0.8.7
+
+### Patch Changes
+
+- [#70](https://github.com/faluciano/react-native-couch-kit/pull/70) [`7897e88`](https://github.com/faluciano/react-native-couch-kit/commit/7897e887967c440b5b973c8dc753bf1fa705b993) Thanks [@faluciano](https://github.com/faluciano)! - Extract the client's connection logic (WebSocket URL resolution, reconnect
+  backoff, session-secret recovery, and host-message interpretation) into a
+  framework-free `connection` module with full unit test coverage. No behavior
+  change; these pure helpers are now exported for reuse and testing.
+
 ## 0.8.6
 
 ### Patch Changes

package/dist/index.js

@@ -1,14 +1,11 @@
 // src/client.ts
 import { useState as useState2, useEffect as useEffect2, useRef as useRef2, useCallback as useCallback2, useReducer } from "react";
 import {
-  MessageTypes as MessageTypes2,
+  MessageTypes as MessageTypes3,
   InternalActionTypes,
-  DEFAULT_WS_PORT_OFFSET,
-  DEFAULT_WS_PATH,
   DEFAULT_MAX_RETRIES,
   DEFAULT_BASE_DELAY,
   DEFAULT_MAX_DELAY,
-  generateId as generateId2,
   createGameReducer
 } from "@couch-kit/core";
 
@@ -69,6 +66,74 @@ function useServerTime(socket) {
   return { getServerTime, rtt: timeSync.rtt, handlePong };
 }
 
+// src/connection.ts
+import {
+  MessageTypes as MessageTypes2,
+  DEFAULT_WS_PORT_OFFSET,
+  DEFAULT_WS_PATH,
+  generateId as generateId2
+} from "@couch-kit/core";
+var SESSION_SECRET_KEY = "ck_secret";
+var NON_RECOVERABLE_CLOSE_CODES = new Set([
+  1008,
+  1011
+]);
+function resolveWebSocketUrl(config, location) {
+  if (config.url)
+    return config.url;
+  if (!location)
+    return null;
+  const protocol = location.protocol === "https:" ? "wss:" : "ws:";
+  const host = location.hostname;
+  const httpPort = parseInt(location.port, 10) || 80;
+  const wsPort = config.wsPort || httpPort + DEFAULT_WS_PORT_OFFSET;
+  return `${protocol}//${host}:${wsPort}${DEFAULT_WS_PATH}`;
+}
+function computeBackoffDelay(attempt, baseDelay, maxDelay) {
+  return Math.min(baseDelay * Math.pow(2, attempt), maxDelay);
+}
+function shouldReconnect(decision) {
+  if (decision.intentionalClose)
+    return false;
+  if (NON_RECOVERABLE_CLOSE_CODES.has(decision.closeCode))
+    return false;
+  return decision.attempts < decision.maxRetries;
+}
+function resolveSessionSecret(storage, generate = generateId2) {
+  try {
+    if (!storage)
+      return generate();
+    const stored = storage.getItem(SESSION_SECRET_KEY);
+    if (stored)
+      return stored;
+    const secret = generate();
+    storage.setItem(SESSION_SECRET_KEY, secret);
+    return secret;
+  } catch {
+    return generate();
+  }
+}
+function interpretHostMessage(msg) {
+  switch (msg.type) {
+    case MessageTypes2.WELCOME:
+      return [
+        { kind: "setPlayerId", playerId: msg.payload.playerId },
+        { kind: "hydrate", state: msg.payload.state }
+      ];
+    case MessageTypes2.STATE_UPDATE:
+      return [{ kind: "hydrate", state: msg.payload.newState }];
+    case MessageTypes2.PONG:
+      return [{ kind: "pong", payload: msg.payload }];
+    case MessageTypes2.RECONNECTED:
+      return [
+        { kind: "setPlayerId", playerId: msg.payload.playerId },
+        { kind: "hydrate", state: msg.payload.state }
+      ];
+    default:
+      return [];
+  }
+}
+
 // src/client.ts
 function useGameClient(config) {
   const [status, setStatus] = useState2("disconnected");
@@ -93,14 +158,7 @@ function useGameClient(config) {
   const connect = useCallback2(() => {
     const cfg = configRef.current;
     intentionalClose.current = false;
-    let wsUrl = cfg.url;
-    if (!wsUrl && typeof window !== "undefined") {
-      const protocol = window.location.protocol === "https:" ? "wss:" : "ws:";
-      const host = window.location.hostname;
-      const httpPort = parseInt(window.location.port, 10) || 80;
-      const wsPort = cfg.wsPort || httpPort + DEFAULT_WS_PORT_OFFSET;
-      wsUrl = `${protocol}//${host}:${wsPort}${DEFAULT_WS_PATH}`;
-    }
+    const wsUrl = resolveWebSocketUrl({ url: cfg.url, wsPort: cfg.wsPort }, typeof window !== "undefined" ? window.location : null);
     if (!wsUrl)
       return;
     if (cfg.debug)
@@ -113,21 +171,10 @@ function useGameClient(config) {
       setStatus("connected");
       reconnectAttempts.current = 0;
       currentCfg.onConnect?.();
-      let secret;
-      try {
-        const stored = localStorage.getItem("ck_secret");
-        if (stored) {
-          secret = stored;
-        } else {
-          secret = generateId2();
-          localStorage.setItem("ck_secret", secret);
-        }
-      } catch {
-        secret = generateId2();
-      }
+      const secret = resolveSessionSecret(typeof localStorage !== "undefined" ? localStorage : null);
       try {
         ws.send(JSON.stringify({
-          type: MessageTypes2.JOIN,
+          type: MessageTypes3.JOIN,
           payload: {
             name: currentCfg.name || "Player",
             avatar: currentCfg.avatar || "\uD83D\uDE00",
@@ -140,53 +187,47 @@ function useGameClient(config) {
       }
     };
     ws.onmessage = (event) => {
+      let msg;
       try {
-        const msg = JSON.parse(event.data);
-        switch (msg.type) {
-          case MessageTypes2.WELCOME:
-            setPlayerId(msg.payload.playerId);
-            dispatchLocal({
-              type: InternalActionTypes.HYDRATE,
-              payload: msg.payload.state
-            });
+        msg = JSON.parse(event.data);
+      } catch (e) {
+        console.error("Failed to parse message", e);
+        return;
+      }
+      for (const effect of interpretHostMessage(msg)) {
+        switch (effect.kind) {
+          case "setPlayerId":
+            setPlayerId(effect.playerId);
             break;
-          case MessageTypes2.STATE_UPDATE:
+          case "hydrate":
             dispatchLocal({
               type: InternalActionTypes.HYDRATE,
-              payload: msg.payload.newState
+              payload: effect.state
             });
             break;
-          case MessageTypes2.PONG:
-            handlePongRef.current(msg.payload);
-            break;
-          case MessageTypes2.RECONNECTED:
-            setPlayerId(msg.payload.playerId);
-            dispatchLocal({
-              type: InternalActionTypes.HYDRATE,
-              payload: msg.payload.state
-            });
+          case "pong":
+            handlePongRef.current(effect.payload);
             break;
         }
-      } catch (e) {
-        console.error("Failed to parse message", e);
       }
     };
     ws.onclose = (event) => {
       setStatus("disconnected");
       configRef.current.onDisconnect?.();
-      if (intentionalClose.current)
-        return;
-      if (event.code === 1008 || event.code === 1011)
+      if (!shouldReconnect({
+        intentionalClose: intentionalClose.current,
+        closeCode: event.code,
+        attempts: reconnectAttempts.current,
+        maxRetries
+      }))
         return;
-      if (reconnectAttempts.current < maxRetries) {
-        const delay = Math.min(baseDelay * Math.pow(2, reconnectAttempts.current), maxDelay);
-        reconnectAttempts.current++;
-        if (configRef.current.debug)
-          console.log(`[GameClient] Reconnecting in ${delay}ms...`);
-        reconnectTimer.current = setTimeout(() => {
-          connect();
-        }, delay);
-      }
+      const delay = computeBackoffDelay(reconnectAttempts.current, baseDelay, maxDelay);
+      reconnectAttempts.current++;
+      if (configRef.current.debug)
+        console.log(`[GameClient] Reconnecting in ${delay}ms...`);
+      reconnectTimer.current = setTimeout(() => {
+        connect();
+      }, delay);
     };
     ws.onerror = (e) => {
       if (configRef.current.debug)
@@ -225,7 +266,7 @@ function useGameClient(config) {
     dispatchLocal(action);
     if (socketRef.current?.readyState === WebSocket.OPEN) {
       socketRef.current.send(JSON.stringify({
-        type: MessageTypes2.ACTION,
+        type: MessageTypes3.ACTION,
         payload: action
       }));
     }
@@ -243,7 +284,7 @@ function useGameClient(config) {
 }
 // src/assets.ts
 import { useState as useState3, useEffect as useEffect3, useRef as useRef3 } from "react";
-import { MessageTypes as MessageTypes3 } from "@couch-kit/core";
+import { MessageTypes as MessageTypes4 } from "@couch-kit/core";
 function arraysEqual(a, b) {
   if (a.length !== b.length)
     return false;
@@ -270,7 +311,7 @@ function usePreload(assets, sendMessage) {
       setProgress(100);
       setFailedAssets([]);
       sendMessageRef.current?.({
-        type: MessageTypes3.ASSETS_LOADED,
+        type: MessageTypes4.ASSETS_LOADED,
         payload: true
       });
       return;
@@ -288,7 +329,7 @@ function usePreload(assets, sendMessage) {
         setFailedAssets([...failed]);
         setLoaded(true);
         sendMessageRef.current?.({
-          type: MessageTypes3.ASSETS_LOADED,
+          type: MessageTypes4.ASSETS_LOADED,
           payload: true
         });
       }
@@ -380,5 +421,11 @@ export {
   usePreload,
   useGameClient,
   useDebugPanel,
-  calculateTimeSync
+  shouldReconnect,
+  resolveWebSocketUrl,
+  resolveSessionSecret,
+  interpretHostMessage,
+  computeBackoffDelay,
+  calculateTimeSync,
+  SESSION_SECRET_KEY
 };

package/lib/client.d.ts.map

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

package/lib/connection.d.ts

@@ -0,0 +1,98 @@
+import { type HostMessage } from "@couch-kit/core";
+/**
+ * Framework-free connection logic for the web game client.
+ *
+ * These helpers contain the pure, side-effect-free decision logic that the
+ * `useGameClient` hook relies on (URL derivation, reconnect/backoff scheduling,
+ * session-secret recovery, and host-message routing). They are kept separate
+ * from the React hook so the behavior can be unit-tested without a WebSocket or
+ * a DOM.
+ */
+/** localStorage key under which the session-recovery secret is persisted. */
+export declare const SESSION_SECRET_KEY = "ck_secret";
+/** Connection options relevant to deriving the WebSocket URL. */
+export interface UrlResolutionConfig {
+    /** Full WebSocket URL. When set, it is used verbatim. */
+    url?: string;
+    /** WebSocket port override. Defaults to the page's HTTP port + offset. */
+    wsPort?: number;
+}
+/** The minimal shape of `window.location` needed to derive a WS URL. */
+export interface LocationLike {
+    protocol: string;
+    hostname: string;
+    port: string;
+}
+/**
+ * Resolve the WebSocket URL to connect to.
+ *
+ * If `config.url` is provided it is returned as-is. Otherwise the URL is
+ * derived from the current page location using the convention
+ * `WS port = HTTP port + DEFAULT_WS_PORT_OFFSET` (HTTP 8080 -> WS 8082; port+1
+ * is skipped to avoid Metro's 8081). Returns `null` when no URL can be
+ * determined (no explicit URL and no location available).
+ */
+export declare function resolveWebSocketUrl(config: UrlResolutionConfig, location: LocationLike | null | undefined): string | null;
+/**
+ * Compute the exponential-backoff delay (ms) for a reconnection attempt.
+ *
+ * `delay = min(baseDelay * 2^attempt, maxDelay)`, where `attempt` is the
+ * zero-based count of reconnects already made.
+ */
+export declare function computeBackoffDelay(attempt: number, baseDelay: number, maxDelay: number): number;
+/** Inputs to the {@link shouldReconnect} decision. */
+export interface ReconnectDecision {
+    /** Whether the disconnect was initiated locally (manual disconnect/unmount). */
+    intentionalClose: boolean;
+    /** The WebSocket close code from the `close` event. */
+    closeCode: number;
+    /** Number of reconnection attempts already made. */
+    attempts: number;
+    /** Maximum number of reconnection attempts permitted. */
+    maxRetries: number;
+}
+/**
+ * Decide whether the client should attempt an automatic reconnect.
+ *
+ * Returns `false` for intentional closes, for non-recoverable server close
+ * codes (1008 policy / 1011 internal error), or once the attempt budget is
+ * exhausted; otherwise `true`.
+ */
+export declare function shouldReconnect(decision: ReconnectDecision): boolean;
+/** The minimal storage surface used for session-secret recovery. */
+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.
+ */
+export declare function resolveSessionSecret(storage: SecretStorage | null | undefined, generate?: () => string): string;
+/**
+ * A side-effect descriptor produced by {@link interpretHostMessage}. The client
+ * hook executes these against React state so the routing logic itself stays
+ * pure and testable.
+ */
+export type HostMessageEffect<S> = {
+    kind: "setPlayerId";
+    playerId: string;
+} | {
+    kind: "hydrate";
+    state: S;
+} | {
+    kind: "pong";
+    payload: PongPayload;
+};
+/** 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.
+ */
+export declare function interpretHostMessage<S>(msg: HostMessage): HostMessageEffect<S>[];
+//# sourceMappingURL=connection.d.ts.map

package/lib/connection.d.ts.map

@@ -0,0 +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"}

package/lib/index.d.ts

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

package/lib/index.d.ts.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@couch-kit/client",
-  "version": "0.8.6",
+  "version": "0.8.7",
   "publishConfig": {
     "access": "public",
     "provenance": true

package/src/client.ts

@@ -2,12 +2,9 @@ import { useState, useEffect, useRef, useCallback, useReducer } from "react";
 import {
   MessageTypes,
   InternalActionTypes,
-  DEFAULT_WS_PORT_OFFSET,
-  DEFAULT_WS_PATH,
   DEFAULT_MAX_RETRIES,
   DEFAULT_BASE_DELAY,
   DEFAULT_MAX_DELAY,
-  generateId,
   createGameReducer,
   type HostMessage,
   type IGameState,
@@ -15,6 +12,13 @@ import {
   type InternalAction,
 } from "@couch-kit/core";
 import { useServerTime } from "./time-sync";
+import {
+  resolveWebSocketUrl,
+  computeBackoffDelay,
+  shouldReconnect,
+  resolveSessionSecret,
+  interpretHostMessage,
+} from "./connection";
 
 export interface ClientConfig<S extends IGameState, A extends IAction> {
   url?: string; // Full WebSocket URL (overrides auto-detection)
@@ -100,15 +104,10 @@ export function useGameClient<S extends IGameState, A extends IAction>(
     // so derive the WebSocket URL from window.location.
     // Convention: WS port = HTTP port + 2 (e.g., HTTP 8080 -> WS 8082)
     // Port + 1 is skipped to avoid conflicts with Metro bundler (which uses 8081)
-    let wsUrl = cfg.url;
-
-    if (!wsUrl && typeof window !== "undefined") {
-      const protocol = window.location.protocol === "https:" ? "wss:" : "ws:";
-      const host = window.location.hostname;
-      const httpPort = parseInt(window.location.port, 10) || 80;
-      const wsPort = cfg.wsPort || httpPort + DEFAULT_WS_PORT_OFFSET;
-      wsUrl = `${protocol}//${host}:${wsPort}${DEFAULT_WS_PATH}`;
-    }
+    const wsUrl = resolveWebSocketUrl(
+      { url: cfg.url, wsPort: cfg.wsPort },
+      typeof window !== "undefined" ? window.location : null,
+    );
 
     if (!wsUrl) return;
 
@@ -125,19 +124,9 @@ export function useGameClient<S extends IGameState, A extends IAction>(
       currentCfg.onConnect?.();
 
       // Session Recovery Logic -- use cryptographically random secrets
-      let secret: string;
-      try {
-        const stored = localStorage.getItem("ck_secret");
-        if (stored) {
-          secret = stored;
-        } else {
-          secret = generateId();
-          localStorage.setItem("ck_secret", secret);
-        }
-      } catch {
-        // localStorage unavailable (Safari private browsing, restrictive WebViews, etc.)
-        secret = generateId();
-      }
+      const secret = resolveSessionSecret(
+        typeof localStorage !== "undefined" ? localStorage : null,
+      );
 
       // Join with secret
       try {
@@ -158,41 +147,30 @@ export function useGameClient<S extends IGameState, A extends IAction>(
     };
 
     ws.onmessage = (event) => {
+      let msg: HostMessage;
       try {
-        const msg = JSON.parse(event.data) as HostMessage;
+        msg = JSON.parse(event.data) as HostMessage;
+      } catch (e) {
+        console.error("Failed to parse message", e);
+        return;
+      }
 
-        switch (msg.type) {
-          case MessageTypes.WELCOME:
-            setPlayerId(msg.payload.playerId);
-            // Hydrate state from server (Single Source of Truth)
-            dispatchLocal({
-              type: InternalActionTypes.HYDRATE,
-              payload: msg.payload.state as S,
-            } as InternalAction<S>);
+      for (const effect of interpretHostMessage<S>(msg)) {
+        switch (effect.kind) {
+          case "setPlayerId":
+            setPlayerId(effect.playerId);
             break;
-
-          case MessageTypes.STATE_UPDATE:
+          case "hydrate":
             // Full state replacement from the host's authoritative state.
             dispatchLocal({
               type: InternalActionTypes.HYDRATE,
-              payload: msg.payload.newState as S,
+              payload: effect.state,
             } as InternalAction<S>);
             break;
-
-          case MessageTypes.PONG:
-            handlePongRef.current(msg.payload);
-            break;
-
-          case MessageTypes.RECONNECTED:
-            setPlayerId(msg.payload.playerId);
-            dispatchLocal({
-              type: InternalActionTypes.HYDRATE,
-              payload: msg.payload.state as S,
-            } as InternalAction<S>);
+          case "pong":
+            handlePongRef.current(effect.payload);
             break;
         }
-      } catch (e) {
-        console.error("Failed to parse message", e);
       }
     };
 
@@ -201,25 +179,31 @@ export function useGameClient<S extends IGameState, A extends IAction>(
       configRef.current.onDisconnect?.();
 
       // Don't reconnect if the close was intentional or if the server
-      // sent a policy/unexpected error close code
-      if (intentionalClose.current) return;
-      if (event.code === 1008 || event.code === 1011) return;
+      // sent a policy/unexpected error close code, or once retries are exhausted.
+      if (
+        !shouldReconnect({
+          intentionalClose: intentionalClose.current,
+          closeCode: event.code,
+          attempts: reconnectAttempts.current,
+          maxRetries,
+        })
+      )
+        return;
 
       // Exponential backoff reconnection
-      if (reconnectAttempts.current < maxRetries) {
-        const delay = Math.min(
-          baseDelay * Math.pow(2, reconnectAttempts.current),
-          maxDelay,
-        );
-        reconnectAttempts.current++;
+      const delay = computeBackoffDelay(
+        reconnectAttempts.current,
+        baseDelay,
+        maxDelay,
+      );
+      reconnectAttempts.current++;
 
-        if (configRef.current.debug)
-          console.log(`[GameClient] Reconnecting in ${delay}ms...`);
+      if (configRef.current.debug)
+        console.log(`[GameClient] Reconnecting in ${delay}ms...`);
 
-        reconnectTimer.current = setTimeout(() => {
-          connect();
-        }, delay);
-      }
+      reconnectTimer.current = setTimeout(() => {
+        connect();
+      }, delay);
     };
 
     ws.onerror = (e) => {

package/src/connection.ts

@@ -0,0 +1,172 @@
+import {
+  MessageTypes,
+  DEFAULT_WS_PORT_OFFSET,
+  DEFAULT_WS_PATH,
+  generateId,
+  type HostMessage,
+} from "@couch-kit/core";
+
+/**
+ * Framework-free connection logic for the web game client.
+ *
+ * These helpers contain the pure, side-effect-free decision logic that the
+ * `useGameClient` hook relies on (URL derivation, reconnect/backoff scheduling,
+ * session-secret recovery, and host-message routing). They are kept separate
+ * from the React hook so the behavior can be unit-tested without a WebSocket or
+ * a DOM.
+ */
+
+/** localStorage key under which the session-recovery secret is persisted. */
+export const SESSION_SECRET_KEY = "ck_secret";
+
+/** 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)
+  1011, // internal server error
+]);
+
+/** Connection options relevant to deriving the WebSocket URL. */
+export interface UrlResolutionConfig {
+  /** Full WebSocket URL. When set, it is used verbatim. */
+  url?: string;
+  /** WebSocket port override. Defaults to the page's HTTP port + offset. */
+  wsPort?: number;
+}
+
+/** The minimal shape of `window.location` needed to derive a WS URL. */
+export interface LocationLike {
+  protocol: string;
+  hostname: string;
+  port: string;
+}
+
+/**
+ * Resolve the WebSocket URL to connect to.
+ *
+ * If `config.url` is provided it is returned as-is. Otherwise the URL is
+ * derived from the current page location using the convention
+ * `WS port = HTTP port + DEFAULT_WS_PORT_OFFSET` (HTTP 8080 -> WS 8082; port+1
+ * is skipped to avoid Metro's 8081). Returns `null` when no URL can be
+ * determined (no explicit URL and no location available).
+ */
+export function resolveWebSocketUrl(
+  config: UrlResolutionConfig,
+  location: LocationLike | null | undefined,
+): string | null {
+  if (config.url) return config.url;
+  if (!location) return null;
+
+  const protocol = location.protocol === "https:" ? "wss:" : "ws:";
+  const host = location.hostname;
+  const httpPort = parseInt(location.port, 10) || 80;
+  const wsPort = config.wsPort || httpPort + DEFAULT_WS_PORT_OFFSET;
+
+  return `${protocol}//${host}:${wsPort}${DEFAULT_WS_PATH}`;
+}
+
+/**
+ * Compute the exponential-backoff delay (ms) for a reconnection attempt.
+ *
+ * `delay = min(baseDelay * 2^attempt, maxDelay)`, where `attempt` is the
+ * zero-based count of reconnects already made.
+ */
+export function computeBackoffDelay(
+  attempt: number,
+  baseDelay: number,
+  maxDelay: number,
+): number {
+  return Math.min(baseDelay * Math.pow(2, attempt), maxDelay);
+}
+
+/** Inputs to the {@link shouldReconnect} decision. */
+export interface ReconnectDecision {
+  /** Whether the disconnect was initiated locally (manual disconnect/unmount). */
+  intentionalClose: boolean;
+  /** The WebSocket close code from the `close` event. */
+  closeCode: number;
+  /** Number of reconnection attempts already made. */
+  attempts: number;
+  /** Maximum number of reconnection attempts permitted. */
+  maxRetries: number;
+}
+
+/**
+ * Decide whether the client should attempt an automatic reconnect.
+ *
+ * Returns `false` for intentional closes, for non-recoverable server close
+ * codes (1008 policy / 1011 internal error), or once the attempt budget is
+ * exhausted; otherwise `true`.
+ */
+export function shouldReconnect(decision: ReconnectDecision): boolean {
+  if (decision.intentionalClose) return false;
+  if (NON_RECOVERABLE_CLOSE_CODES.has(decision.closeCode)) return false;
+  return decision.attempts < decision.maxRetries;
+}
+
+/** The minimal storage surface used for session-secret recovery. */
+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.
+ */
+export function resolveSessionSecret(
+  storage: SecretStorage | null | undefined,
+  generate: () => string = generateId,
+): string {
+  try {
+    if (!storage) return generate();
+    const stored = storage.getItem(SESSION_SECRET_KEY);
+    if (stored) return stored;
+    const secret = generate();
+    storage.setItem(SESSION_SECRET_KEY, secret);
+    return secret;
+  } catch {
+    return generate();
+  }
+}
+
+/**
+ * A side-effect descriptor produced by {@link interpretHostMessage}. The client
+ * hook executes these against React state so the routing logic itself stays
+ * pure and testable.
+ */
+export type HostMessageEffect<S> =
+  | { kind: "setPlayerId"; playerId: string }
+  | { kind: "hydrate"; state: S }
+  | { kind: "pong"; payload: PongPayload };
+
+/** 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.
+ */
+export function interpretHostMessage<S>(
+  msg: HostMessage,
+): HostMessageEffect<S>[] {
+  switch (msg.type) {
+    case MessageTypes.WELCOME:
+      return [
+        { kind: "setPlayerId", playerId: msg.payload.playerId },
+        { kind: "hydrate", state: msg.payload.state as S },
+      ];
+    case MessageTypes.STATE_UPDATE:
+      return [{ kind: "hydrate", state: msg.payload.newState as S }];
+    case MessageTypes.PONG:
+      return [{ kind: "pong", payload: msg.payload }];
+    case MessageTypes.RECONNECTED:
+      return [
+        { kind: "setPlayerId", playerId: msg.payload.playerId },
+        { kind: "hydrate", state: msg.payload.state as S },
+      ];
+    default:
+      return [];
+  }
+}

package/src/index.ts

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