@couch-kit/core 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # @couch-kit/core
 
+## 0.5.0
+
+### Minor Changes
+
+- Fix player state not restored on page refresh
+
+  Players now maintain their identity across page refreshes and network reconnections. The library uses a stable player ID derived from a persistent session secret (stored in localStorage) instead of the ephemeral WebSocket socket ID.
+
+  **New features:**
+  - `__PLAYER_RECONNECTED__` internal action: dispatched when a returning player reconnects, preserving all game data (hand, score, turn, etc.)
+  - `__PLAYER_REMOVED__` internal action: dispatched when a disconnected player times out (default: 5 minutes), permanently removing them from state
+  - Race-safe disconnect handling: prevents marking a player as disconnected if they've already reconnected on a new socket
+  - Secret validation: malformed session secrets are rejected at the JOIN boundary
+
+  **Breaking changes:**
+  - `state.players` keys are now stable derived player IDs instead of ephemeral socket IDs
+  - `playerId` returned by `useGameClient()` and sent in `WELCOME` messages is now a stable identifier that persists across reconnections
+  - `secret` field in `JOIN` payload is now required (was optional)
+
+  **Security:**
+  - Raw session secret is never stored on `IPlayer` or broadcast to clients
+  - Only the derived public player ID is shared in game state
+
 ## 0.4.0
 
 ### Minor Changes

package/README.md

@@ -21,6 +21,8 @@ A higher-order reducer that wraps your game reducer with automatic handling of i
 - `__HYDRATE__` -- Replaces state wholesale (used for server-to-client state sync).
 - `__PLAYER_JOINED__` -- Adds a player to `state.players`.
 - `__PLAYER_LEFT__` -- Marks a player as disconnected in `state.players`.
+- `__PLAYER_RECONNECTED__` -- Dispatched when a returning player reconnects with a valid session. Sets `connected: true` and preserves all existing player data.
+- `__PLAYER_REMOVED__` -- Dispatched when a disconnected player times out (default: 5 minutes). Permanently removes the player from `state.players`.
 
 **You do not need to call this yourself.** Both `GameHostProvider` and `useGameClient` wrap your reducer automatically. Just write a plain reducer that handles your own action types:
 

package/dist/index.js

@@ -2,7 +2,9 @@
 var InternalActionTypes = {
   HYDRATE: "__HYDRATE__",
   PLAYER_JOINED: "__PLAYER_JOINED__",
-  PLAYER_LEFT: "__PLAYER_LEFT__"
+  PLAYER_LEFT: "__PLAYER_LEFT__",
+  PLAYER_RECONNECTED: "__PLAYER_RECONNECTED__",
+  PLAYER_REMOVED: "__PLAYER_REMOVED__"
 };
 function createGameReducer(reducer) {
   return (state, action) => {
@@ -38,6 +40,29 @@ function createGameReducer(reducer) {
           }
         };
       }
+      case InternalActionTypes.PLAYER_RECONNECTED: {
+        const { playerId } = action.payload;
+        const player = state.players[playerId];
+        if (!player)
+          return state;
+        return {
+          ...state,
+          players: {
+            ...state.players,
+            [playerId]: { ...player, connected: true }
+          }
+        };
+      }
+      case InternalActionTypes.PLAYER_REMOVED: {
+        const { playerId } = action.payload;
+        if (!state.players[playerId])
+          return state;
+        const { [playerId]: _, ...remainingPlayers } = state.players;
+        return {
+          ...state,
+          players: remainingPlayers
+        };
+      }
       default:
         return reducer(state, action);
     }
@@ -79,6 +104,13 @@ function generateId() {
   const b = Math.random().toString(36).substring(2, 10);
   return a + b;
 }
+function isValidSecret(secret) {
+  const hex = secret.replace(/-/g, "");
+  return hex.length >= 32 && /^[0-9a-f]+$/i.test(hex);
+}
+function derivePlayerId(secret) {
+  return secret.replace(/-/g, "").slice(0, 16);
+}
 function toErrorMessage(error) {
   if (error instanceof Error)
     return error.message;
@@ -86,7 +118,9 @@ function toErrorMessage(error) {
 }
 export {
   toErrorMessage,
+  isValidSecret,
   generateId,
+  derivePlayerId,
   createGameReducer,
   MessageTypes,
   MAX_PENDING_PINGS,

package/lib/constants.d.ts

@@ -26,6 +26,18 @@ export declare const KEEPALIVE_TIMEOUT = 10000;
  * falling back to `crypto.getRandomValues()` for older environments.
  */
 export declare function generateId(): string;
+/**
+ * Validates that a string looks like a UUID (with or without dashes, 32+ hex chars).
+ */
+export declare function isValidSecret(secret: string): boolean;
+/**
+ * Derives a stable, public player ID from a secret UUID.
+ *
+ * Strips dashes and takes the first 16 hex characters. This is NOT a
+ * cryptographic hash — it simply avoids exposing the raw secret in
+ * state that gets broadcast to all clients.
+ */
+export declare function derivePlayerId(secret: string): string;
 /**
  * Safely extract an error message from an unknown caught value.
  * In JavaScript, anything can be thrown -- this normalizes it.

package/lib/constants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,wDAAwD;AAExD,oDAAoD;AACpD,eAAO,MAAM,iBAAiB,OAAO,CAAC;AAEtC,4EAA4E;AAC5E,eAAO,MAAM,sBAAsB,IAAI,CAAC;AAExC,2DAA2D;AAC3D,eAAO,MAAM,cAAc,QAAc,CAAC;AAE1C,4DAA4D;AAC5D,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAErC,oEAAoE;AACpE,eAAO,MAAM,kBAAkB,OAAO,CAAC;AAEvC,+DAA+D;AAC/D,eAAO,MAAM,iBAAiB,QAAQ,CAAC;AAEvC,4CAA4C;AAC5C,eAAO,MAAM,qBAAqB,OAAO,CAAC;AAE1C,0DAA0D;AAC1D,eAAO,MAAM,iBAAiB,KAAK,CAAC;AAEpC,gDAAgD;AAChD,eAAO,MAAM,kBAAkB,QAAQ,CAAC;AAExC,gEAAgE;AAChE,eAAO,MAAM,iBAAiB,QAAQ,CAAC;AAEvC;;;;;GAKG;AACH,wBAAgB,UAAU,IAAI,MAAM,CAwBnC;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAGrD"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,wDAAwD;AAExD,oDAAoD;AACpD,eAAO,MAAM,iBAAiB,OAAO,CAAC;AAEtC,4EAA4E;AAC5E,eAAO,MAAM,sBAAsB,IAAI,CAAC;AAExC,2DAA2D;AAC3D,eAAO,MAAM,cAAc,QAAc,CAAC;AAE1C,4DAA4D;AAC5D,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAErC,oEAAoE;AACpE,eAAO,MAAM,kBAAkB,OAAO,CAAC;AAEvC,+DAA+D;AAC/D,eAAO,MAAM,iBAAiB,QAAQ,CAAC;AAEvC,4CAA4C;AAC5C,eAAO,MAAM,qBAAqB,OAAO,CAAC;AAE1C,0DAA0D;AAC1D,eAAO,MAAM,iBAAiB,KAAK,CAAC;AAEpC,gDAAgD;AAChD,eAAO,MAAM,kBAAkB,QAAQ,CAAC;AAExC,gEAAgE;AAChE,eAAO,MAAM,iBAAiB,QAAQ,CAAC;AAEvC;;;;;GAKG;AACH,wBAAgB,UAAU,IAAI,MAAM,CAwBnC;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAGrD;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAErD;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAGrD"}

package/lib/protocol.d.ts

@@ -3,7 +3,7 @@ export type ClientMessage = {
     payload: {
         name: string;
         avatar?: string;
-        secret?: string;
+        secret: string;
     };
 } | {
     type: "ACTION";
@@ -45,6 +45,7 @@ export type HostMessage = {
 } | {
     type: "RECONNECTED";
     payload: {
+        playerId: string;
         state: unknown;
     };
 } | {

package/lib/protocol.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"AACA,MAAM,MAAM,aAAa,GACrB;IACE,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC7D,GACD;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,CAAA;CAAE,GAChE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,GAC5D;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,OAAO,EAAE,IAAI,CAAA;CAAE,CAAC;AAG7C,MAAM,MAAM,WAAW,GACnB;IACE,IAAI,EAAE,SAAS,CAAC;IAChB,OAAO,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,OAAO,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;CACnE,GACD;IACE,IAAI,EAAE,cAAc,CAAC;IACrB,OAAO,EAAE;QAAE,MAAM,CAAC,EAAE,OAAO,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;CACrE,GACD;IACE,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;CACpE,GACD;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,OAAO,EAAE;QAAE,KAAK,EAAE,OAAO,CAAA;KAAE,CAAA;CAAE,GACpD;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CAAC;AAElE,eAAO,MAAM,YAAY;;;;;;;;;;CAaf,CAAC"}
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"AACA,MAAM,MAAM,aAAa,GACrB;IACE,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CAC5D,GACD;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,CAAA;CAAE,GAChE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,GAC5D;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,OAAO,EAAE,IAAI,CAAA;CAAE,CAAC;AAG7C,MAAM,MAAM,WAAW,GACnB;IACE,IAAI,EAAE,SAAS,CAAC;IAChB,OAAO,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,OAAO,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;CACnE,GACD;IACE,IAAI,EAAE,cAAc,CAAC;IACrB,OAAO,EAAE;QAAE,MAAM,CAAC,EAAE,OAAO,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;CACrE,GACD;IACE,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;CACpE,GACD;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,OAAO,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,CAAA;CAAE,GACtE;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CAAC;AAElE,eAAO,MAAM,YAAY;;;;;;;;;;CAaf,CAAC"}

package/lib/types.d.ts

@@ -36,6 +36,12 @@ export interface IAction {
 /**
  * Internal actions managed automatically by `createGameReducer`.
  * These are dispatched by the framework -- consumers do not need to handle them.
+ *
+ * - `__HYDRATE__` -- Replaces state wholesale (server-to-client sync).
+ * - `__PLAYER_JOINED__` -- Adds a player to `state.players`.
+ * - `__PLAYER_LEFT__` -- Marks a player as disconnected (`connected: false`).
+ * - `__PLAYER_RECONNECTED__` -- Restores a returning player (`connected: true`), preserving existing data.
+ * - `__PLAYER_REMOVED__` -- Permanently removes a timed-out disconnected player from `state.players`.
  */
 export type InternalAction<S extends IGameState = IGameState> = {
     type: "__HYDRATE__";
@@ -46,19 +52,30 @@ export type InternalAction<S extends IGameState = IGameState> = {
         id: string;
         name: string;
         avatar?: string;
-        secret?: string;
     };
 } | {
     type: "__PLAYER_LEFT__";
     payload: {
         playerId: string;
     };
+} | {
+    type: "__PLAYER_RECONNECTED__";
+    payload: {
+        playerId: string;
+    };
+} | {
+    type: "__PLAYER_REMOVED__";
+    payload: {
+        playerId: string;
+    };
 };
 /** Well-known internal action type strings. */
 export declare const InternalActionTypes: {
     readonly HYDRATE: "__HYDRATE__";
     readonly PLAYER_JOINED: "__PLAYER_JOINED__";
     readonly PLAYER_LEFT: "__PLAYER_LEFT__";
+    readonly PLAYER_RECONNECTED: "__PLAYER_RECONNECTED__";
+    readonly PLAYER_REMOVED: "__PLAYER_REMOVED__";
 };
 /**
  * Type alias for a game reducer function.
@@ -73,6 +90,8 @@ export type GameReducer<S extends IGameState, A extends IAction> = (state: S, ac
  * - `__HYDRATE__` -- Replaces state wholesale (used for server→client state sync).
  * - `__PLAYER_JOINED__` -- Adds a player to `state.players`.
  * - `__PLAYER_LEFT__` -- Marks a player as disconnected in `state.players`.
+ * - `__PLAYER_RECONNECTED__` -- Restores a returning player's connection status, preserving all existing data.
+ * - `__PLAYER_REMOVED__` -- Permanently removes a timed-out disconnected player from `state.players`.
  *
  * The wrapped reducer accepts both `A` (user actions) and `InternalAction<S>`.
  * User reducers only need to handle their own action types.

package/lib/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;IAChB,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED;;;;;GAKG;AACH,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,MAAM,MAAM,cAAc,CAAC,CAAC,SAAS,UAAU,GAAG,UAAU,IACxD;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,OAAO,EAAE,CAAC,CAAA;CAAE,GACnC;IACE,IAAI,EAAE,mBAAmB,CAAC;IAC1B,OAAO,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACzE,GACD;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,OAAO,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CAAC;AAE/D,+CAA+C;AAC/C,eAAO,MAAM,mBAAmB;;;;CAItB,CAAC;AAEX;;;;;GAKG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,UAAU,EAAE,CAAC,SAAS,OAAO,IAAI,CACjE,KAAK,EAAE,CAAC,EACR,MAAM,EAAE,CAAC,KACN,CAAC,CAAC;AAEP;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,UAAU,EAAE,CAAC,SAAS,OAAO,EACvE,OAAO,EAAE,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,GACzB,WAAW,CAAC,CAAC,EAAE,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,CAAC,CA4CvC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;IAChB,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED;;;;;GAKG;AACH,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,cAAc,CAAC,CAAC,SAAS,UAAU,GAAG,UAAU,IACxD;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,OAAO,EAAE,CAAC,CAAA;CAAE,GACnC;IACE,IAAI,EAAE,mBAAmB,CAAC;IAC1B,OAAO,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACxD,GACD;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,OAAO,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,GAC1D;IAAE,IAAI,EAAE,wBAAwB,CAAC;IAAC,OAAO,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,GACjE;IAAE,IAAI,EAAE,oBAAoB,CAAC;IAAC,OAAO,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CAAC;AAElE,+CAA+C;AAC/C,eAAO,MAAM,mBAAmB;;;;;;CAMtB,CAAC;AAEX;;;;;GAKG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,UAAU,EAAE,CAAC,SAAS,OAAO,IAAI,CACjE,KAAK,EAAE,CAAC,EACR,MAAM,EAAE,CAAC,KACN,CAAC,CAAC;AAEP;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,UAAU,EAAE,CAAC,SAAS,OAAO,EACvE,OAAO,EAAE,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,GACzB,WAAW,CAAC,CAAC,EAAE,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,CAAC,CAuEvC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@couch-kit/core",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Shared types, protocol, and game reducer for Couch Kit party games",
   "license": "MIT",
   "repository": {

package/src/constants.ts

@@ -62,6 +62,25 @@ export function generateId(): string {
   return a + b;
 }
 
+/**
+ * Validates that a string looks like a UUID (with or without dashes, 32+ hex chars).
+ */
+export function isValidSecret(secret: string): boolean {
+  const hex = secret.replace(/-/g, "");
+  return hex.length >= 32 && /^[0-9a-f]+$/i.test(hex);
+}
+
+/**
+ * Derives a stable, public player ID from a secret UUID.
+ *
+ * Strips dashes and takes the first 16 hex characters. This is NOT a
+ * cryptographic hash — it simply avoids exposing the raw secret in
+ * state that gets broadcast to all clients.
+ */
+export function derivePlayerId(secret: string): string {
+  return secret.replace(/-/g, "").slice(0, 16);
+}
+
 /**
  * Safely extract an error message from an unknown caught value.
  * In JavaScript, anything can be thrown -- this normalizes it.

package/src/protocol.ts

@@ -2,7 +2,7 @@
 export type ClientMessage =
   | {
       type: "JOIN";
-      payload: { name: string; avatar?: string; secret?: string };
+      payload: { name: string; avatar?: string; secret: string };
     }
   | { type: "ACTION"; payload: { type: string; payload?: unknown } }
   | { type: "PING"; payload: { id: string; timestamp: number } }
@@ -22,7 +22,7 @@ export type HostMessage =
       type: "PONG";
       payload: { id: string; origTimestamp: number; serverTime: number };
     }
-  | { type: "RECONNECTED"; payload: { state: unknown } }
+  | { type: "RECONNECTED"; payload: { playerId: string; state: unknown } }
   | { type: "ERROR"; payload: { code: string; message: string } };
 
 export const MessageTypes = {

package/src/types.ts

@@ -39,20 +39,30 @@ export interface IAction {
 /**
  * Internal actions managed automatically by `createGameReducer`.
  * These are dispatched by the framework -- consumers do not need to handle them.
+ *
+ * - `__HYDRATE__` -- Replaces state wholesale (server-to-client sync).
+ * - `__PLAYER_JOINED__` -- Adds a player to `state.players`.
+ * - `__PLAYER_LEFT__` -- Marks a player as disconnected (`connected: false`).
+ * - `__PLAYER_RECONNECTED__` -- Restores a returning player (`connected: true`), preserving existing data.
+ * - `__PLAYER_REMOVED__` -- Permanently removes a timed-out disconnected player from `state.players`.
  */
 export type InternalAction<S extends IGameState = IGameState> =
   | { type: "__HYDRATE__"; payload: S }
   | {
       type: "__PLAYER_JOINED__";
-      payload: { id: string; name: string; avatar?: string; secret?: string };
+      payload: { id: string; name: string; avatar?: string };
     }
-  | { type: "__PLAYER_LEFT__"; payload: { playerId: string } };
+  | { type: "__PLAYER_LEFT__"; payload: { playerId: string } }
+  | { type: "__PLAYER_RECONNECTED__"; payload: { playerId: string } }
+  | { type: "__PLAYER_REMOVED__"; payload: { playerId: string } };
 
 /** Well-known internal action type strings. */
 export const InternalActionTypes = {
   HYDRATE: "__HYDRATE__",
   PLAYER_JOINED: "__PLAYER_JOINED__",
   PLAYER_LEFT: "__PLAYER_LEFT__",
+  PLAYER_RECONNECTED: "__PLAYER_RECONNECTED__",
+  PLAYER_REMOVED: "__PLAYER_REMOVED__",
 } as const;
 
 /**
@@ -72,6 +82,8 @@ export type GameReducer<S extends IGameState, A extends IAction> = (
  * - `__HYDRATE__` -- Replaces state wholesale (used for server→client state sync).
  * - `__PLAYER_JOINED__` -- Adds a player to `state.players`.
  * - `__PLAYER_LEFT__` -- Marks a player as disconnected in `state.players`.
+ * - `__PLAYER_RECONNECTED__` -- Restores a returning player's connection status, preserving all existing data.
+ * - `__PLAYER_REMOVED__` -- Permanently removes a timed-out disconnected player from `state.players`.
  *
  * The wrapped reducer accepts both `A` (user actions) and `InternalAction<S>`.
  * User reducers only need to handle their own action types.
@@ -118,6 +130,33 @@ export function createGameReducer<S extends IGameState, A extends IAction>(
         };
       }
 
+      case InternalActionTypes.PLAYER_RECONNECTED: {
+        const { playerId } = (
+          action as InternalAction<S> & { type: "__PLAYER_RECONNECTED__" }
+        ).payload;
+        const player = state.players[playerId];
+        if (!player) return state;
+        return {
+          ...state,
+          players: {
+            ...state.players,
+            [playerId]: { ...player, connected: true },
+          },
+        };
+      }
+
+      case InternalActionTypes.PLAYER_REMOVED: {
+        const { playerId } = (
+          action as InternalAction<S> & { type: "__PLAYER_REMOVED__" }
+        ).payload;
+        if (!state.players[playerId]) return state;
+        const { [playerId]: _, ...remainingPlayers } = state.players;
+        return {
+          ...state,
+          players: remainingPlayers,
+        };
+      }
+
       default:
         return reducer(state, action as A);
     }