@couch-kit/host 1.2.6 → 1.3.0

package/README.md

@@ -73,12 +73,16 @@ Returns:
 
 ## System Actions
 
-The host automatically dispatches internal system actions (`__PLAYER_JOINED__`, `__PLAYER_LEFT__`, `__HYDRATE__`) into `createGameReducer`, which handles them for you. **You do not need to handle these in your reducer.**
+The host automatically dispatches internal system actions (`__PLAYER_JOINED__`, `__PLAYER_LEFT__`, `__PLAYER_RECONNECTED__`, `__PLAYER_REMOVED__`, `__HYDRATE__`) into `createGameReducer`, which handles them for you. **You do not need to handle these in your reducer.**
 
 Player tracking (`state.players`) is managed automatically:
 
 - When a player joins, they are added to `state.players` with `connected: true`.
 - When a player disconnects, they are marked as `connected: false`.
+- If a player reconnects from the same device/browser, they are automatically reassigned their previous player data via `__PLAYER_RECONNECTED__` (sets `connected: true`, preserves hand, score, etc.).
+- If a disconnected player does not reconnect within the timeout window (default: 5 minutes), they are permanently removed from `state.players` via `__PLAYER_REMOVED__`.
+
+Game logic that iterates over `state.players` should account for players being removed after the timeout.
 
 To react to player events outside of state (e.g., logging, analytics), use the callback config options:
 

package/lib/provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.tsx"],"names":[],"mappings":"AAAA,OAAO,KAQN,MAAM,OAAO,CAAC;AAGf,OAAO,EAML,KAAK,UAAU,EACf,KAAK,OAAO,EAGb,MAAM,iBAAiB,CAAC;AAEzB,MAAM,WAAW,cAAc,CAAC,CAAC,SAAS,UAAU,EAAE,CAAC,SAAS,OAAO;IACrE,YAAY,EAAE,CAAC,CAAC;IAChB,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,KAAK,CAAC,CAAC;IACpC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,+CAA+C;IAC/C,cAAc,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC1D,wCAAwC;IACxC,YAAY,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IAC1C,yCAAyC;IACzC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CAClC;AAED,UAAU,oBAAoB,CAAC,CAAC,SAAS,UAAU,EAAE,CAAC,SAAS,OAAO;IACpE,KAAK,EAAE,CAAC,CAAC;IACT,QAAQ,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,IAAI,CAAC;IAC9B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,WAAW,EAAE,KAAK,GAAG,IAAI,CAAC;CAC3B;AA4CD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,UAAU,EAAE,CAAC,SAAS,OAAO,EAAE,EACxE,QAAQ,EACR,MAAM,GACP,EAAE;IACD,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;IAC1B,MAAM,EAAE,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;CAC9B,qBA+NA;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,UAAU,EAAE,CAAC,SAAS,OAAO,KAK/C,oBAAoB,CAAC,CAAC,EAAE,CAAC,CAAC,CAC7C"}
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.tsx"],"names":[],"mappings":"AAAA,OAAO,KAQN,MAAM,OAAO,CAAC;AAGf,OAAO,EAQL,KAAK,UAAU,EACf,KAAK,OAAO,EAGb,MAAM,iBAAiB,CAAC;AAEzB,MAAM,WAAW,cAAc,CAAC,CAAC,SAAS,UAAU,EAAE,CAAC,SAAS,OAAO;IACrE,YAAY,EAAE,CAAC,CAAC;IAChB,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,KAAK,CAAC,CAAC;IACpC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,+CAA+C;IAC/C,cAAc,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC1D,wCAAwC;IACxC,YAAY,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IAC1C,yCAAyC;IACzC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CAClC;AAED,UAAU,oBAAoB,CAAC,CAAC,SAAS,UAAU,EAAE,CAAC,SAAS,OAAO;IACpE,KAAK,EAAE,CAAC,CAAC;IACT,QAAQ,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,IAAI,CAAC;IAC9B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,WAAW,EAAE,KAAK,GAAG,IAAI,CAAC;CAC3B;AA4CD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,UAAU,EAAE,CAAC,SAAS,OAAO,EAAE,EACxE,QAAQ,EACR,MAAM,GACP,EAAE;IACD,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;IAC1B,MAAM,EAAE,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;CAC9B,qBAsTA;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,UAAU,EAAE,CAAC,SAAS,OAAO,KAK/C,oBAAoB,CAAC,CAAC,EAAE,CAAC,CAAC,CAC7C"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@couch-kit/host",
-  "version": "1.2.6",
+  "version": "1.3.0",
   "description": "React Native host for local multiplayer party games on Android TV — WebSocket server, state management, and static file serving",
   "license": "MIT",
   "repository": {
@@ -51,7 +51,7 @@
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "@couch-kit/core": "0.4.0",
+    "@couch-kit/core": "0.5.0",
     "buffer": "^6.0.3",
     "js-sha1": "^0.7.0",
     "react-native-nitro-http-server": "^1.5.4"

package/src/provider.tsx

@@ -15,6 +15,8 @@ import {
   DEFAULT_HTTP_PORT,
   DEFAULT_WS_PORT_OFFSET,
   createGameReducer,
+  derivePlayerId,
+  isValidSecret,
   type IGameState,
   type IAction,
   type InternalAction,
@@ -123,6 +125,27 @@ export function GameHostProvider<S extends IGameState, A extends IAction>({
     stateRef.current = state;
   }, [state]);
 
+  // Send WELCOME messages after state has settled (post-render).
+  // This guarantees the joining player is included in the state snapshot.
+  useEffect(() => {
+    if (pendingWelcome.current.size === 0) return;
+    if (!wsServer.current) return;
+
+    const server = wsServer.current;
+    for (const [socketId, playerId] of pendingWelcome.current) {
+      welcomedClients.current.add(socketId);
+      server.send(socketId, {
+        type: MessageTypes.WELCOME,
+        payload: {
+          playerId,
+          state,
+          serverTime: Date.now(),
+        },
+      });
+    }
+    pendingWelcome.current.clear();
+  }, [state]);
+
   // Keep refs for callback props to avoid stale closures
   const configRef = useRef(config);
   useEffect(() => {
@@ -141,12 +164,23 @@ export function GameHostProvider<S extends IGameState, A extends IAction>({
   // 2. Start WebSocket Server (Convention: HTTP port + 2, avoids Metro on 8081)
   const wsServer = useRef<GameWebSocketServer | null>(null);
 
-  // Track active sessions: secret -> playerId
+  // Track active sessions: secret -> socketId
   const sessions = useRef<Map<string, string>>(new Map());
 
+  // Reverse lookup: socketId -> secret (for disconnect resolution)
+  const reverseMap = useRef<Map<string, string>>(new Map());
+
+  // Stale player cleanup timers: playerId -> timer
+  const cleanupTimers = useRef<Map<string, ReturnType<typeof setTimeout>>>(
+    new Map(),
+  );
+
   // Track socket IDs that have received their WELCOME message
   const welcomedClients = useRef<Set<string>>(new Set());
 
+  // Track socket IDs that need a WELCOME message after state settles
+  const pendingWelcome = useRef<Map<string, string>>(new Map()); // socketId -> playerId
+
   useEffect(() => {
     const port = config.wsPort || httpPort + DEFAULT_WS_PORT_OFFSET;
     const server = new GameWebSocketServer({ port, debug: config.debug });
@@ -188,33 +222,51 @@ export function GameHostProvider<S extends IGameState, A extends IAction>({
         case MessageTypes.JOIN: {
           const { secret, ...payload } = message.payload;
 
-          if (secret) {
-            // Update the session map with the new socket ID for this secret
-            sessions.current.set(secret, socketId);
-          }
-
-          // Dispatch the internal PLAYER_JOINED action
-          dispatch({
-            type: InternalActionTypes.PLAYER_JOINED,
-            payload: { id: socketId, ...payload },
-          } as InternalAction<S>);
-
-          // Use queueMicrotask to send WELCOME after the reducer has processed
-          // the PLAYER_JOINED action, so the client receives state that includes
-          // themselves in the players list.
-          queueMicrotask(() => {
-            welcomedClients.current.add(socketId);
+          // Validate secret format
+          if (!secret || !isValidSecret(secret)) {
             server.send(socketId, {
-              type: MessageTypes.WELCOME,
+              type: MessageTypes.ERROR,
               payload: {
-                playerId: socketId,
-                state: stateRef.current,
-                serverTime: Date.now(),
+                code: "INVALID_SECRET",
+                message: "Invalid or missing session secret",
               },
             });
-          });
+            return;
+          }
+
+          const playerId = derivePlayerId(secret);
+
+          // Update session maps
+          sessions.current.set(secret, socketId);
+          reverseMap.current.set(socketId, secret);
+
+          // Cancel any pending cleanup timer for this player
+          const existingTimer = cleanupTimers.current.get(playerId);
+          if (existingTimer) {
+            clearTimeout(existingTimer);
+            cleanupTimers.current.delete(playerId);
+          }
 
-          configRef.current.onPlayerJoined?.(socketId, payload.name);
+          // Check if this is a returning player
+          const existingPlayer = stateRef.current.players[playerId];
+          if (existingPlayer) {
+            // Reconnection — restore existing player
+            dispatch({
+              type: InternalActionTypes.PLAYER_RECONNECTED,
+              payload: { playerId },
+            } as InternalAction<S>);
+          } else {
+            // New player
+            dispatch({
+              type: InternalActionTypes.PLAYER_JOINED,
+              payload: { id: playerId, ...payload },
+            } as InternalAction<S>);
+          }
+
+          // Queue WELCOME
+          pendingWelcome.current.set(socketId, playerId);
+
+          configRef.current.onPlayerJoined?.(playerId, payload.name);
           break;
         }
 
@@ -225,7 +277,9 @@ export function GameHostProvider<S extends IGameState, A extends IAction>({
           if (
             actionPayload.type === InternalActionTypes.HYDRATE ||
             actionPayload.type === InternalActionTypes.PLAYER_JOINED ||
-            actionPayload.type === InternalActionTypes.PLAYER_LEFT
+            actionPayload.type === InternalActionTypes.PLAYER_LEFT ||
+            actionPayload.type === InternalActionTypes.PLAYER_RECONNECTED ||
+            actionPayload.type === InternalActionTypes.PLAYER_REMOVED
           ) {
             if (configRef.current.debug)
               console.warn(
@@ -242,7 +296,12 @@ export function GameHostProvider<S extends IGameState, A extends IAction>({
             });
             return;
           }
-          dispatch(actionPayload);
+          // Resolve playerId from socketId
+          const actionSecret = reverseMap.current.get(socketId);
+          const resolvedPlayerId = actionSecret
+            ? derivePlayerId(actionSecret)
+            : undefined;
+          dispatch({ ...actionPayload, playerId: resolvedPlayerId });
           break;
         }
 
@@ -265,15 +324,41 @@ export function GameHostProvider<S extends IGameState, A extends IAction>({
 
       welcomedClients.current.delete(socketId);
 
-      // We do NOT remove the session from the map here,
-      // allowing them to reconnect later with the same secret.
+      // Resolve socketId -> secret -> playerId
+      const secret = reverseMap.current.get(socketId);
+      reverseMap.current.delete(socketId);
+
+      if (!secret) return; // Unknown socket, nothing to do
+
+      const playerId = derivePlayerId(secret);
 
+      // RACE GUARD: Only mark as left if this socket is still the active one for this secret
+      if (sessions.current.get(secret) !== socketId) {
+        // Player already reconnected on a newer socket — skip
+        return;
+      }
+
+      // Mark disconnected (don't remove from sessions — allow reconnect)
       dispatch({
         type: InternalActionTypes.PLAYER_LEFT,
-        payload: { playerId: socketId },
+        payload: { playerId },
       } as InternalAction<S>);
 
-      configRef.current.onPlayerLeft?.(socketId);
+      configRef.current.onPlayerLeft?.(playerId);
+
+      // Start stale player cleanup timer (5 minutes default)
+      const timer = setTimeout(
+        () => {
+          cleanupTimers.current.delete(playerId);
+          sessions.current.delete(secret);
+          dispatch({
+            type: InternalActionTypes.PLAYER_REMOVED,
+            payload: { playerId },
+          } as InternalAction<S>);
+        },
+        5 * 60 * 1000,
+      );
+      cleanupTimers.current.set(playerId, timer);
     });
 
     server.on("error", (error) => {
@@ -284,13 +369,16 @@ export function GameHostProvider<S extends IGameState, A extends IAction>({
 
     return () => {
       server.stop();
+      for (const timer of cleanupTimers.current.values()) {
+        clearTimeout(timer);
+      }
+      cleanupTimers.current.clear();
     };
   }, []); // Run once on mount
 
   // 3. Throttled State Broadcasts (~30fps)
   // Batches rapid state changes so at most one broadcast is sent per ~33ms frame,
   // reducing serialization overhead and network traffic for fast-updating games.
-  const broadcastPending = useRef(false);
   const broadcastTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
 
   const broadcastState = useCallback(() => {
@@ -303,14 +391,15 @@ export function GameHostProvider<S extends IGameState, A extends IAction>({
         },
       });
     }
-    broadcastPending.current = false;
   }, []);
 
   useEffect(() => {
-    if (!broadcastPending.current) {
-      broadcastPending.current = true;
-      broadcastTimer.current = setTimeout(broadcastState, 33); // ~30fps
+    // Cancel any pending broadcast and schedule a fresh one.
+    // This ensures the broadcast always uses the latest stateRef.
+    if (broadcastTimer.current) {
+      clearTimeout(broadcastTimer.current);
     }
+    broadcastTimer.current = setTimeout(broadcastState, 33); // ~30fps
 
     return () => {
       if (broadcastTimer.current) {