@couch-kit/host 1.2.7 → 1.3.1

package/README.md

@@ -26,10 +26,10 @@ Then install the required peer dependencies:
 
 ```bash
 npx expo install expo-file-system expo-network
-bun add react-native-tcp-socket
+bun add react-native-tcp-socket react-native-nitro-modules
 ```
 
-> **Note:** This library requires Expo modules (`expo-file-system`, `expo-network`) and `react-native-tcp-socket` as peer dependencies. These must be installed in your consumer app. React Native's autolinking will handle native setup automatically.
+> **Note:** This library requires Expo modules (`expo-file-system`, `expo-network`), `react-native-tcp-socket`, and `react-native-nitro-modules` as peer dependencies. These must be installed in your consumer app. React Native's autolinking will handle native setup automatically.
 
 ## Compatibility
 
@@ -45,8 +45,6 @@ bun add react-native-tcp-socket
 
 > **New Architecture:** This package supports React Native's New Architecture (Fabric/TurboModules) via React Native 0.83+.
 
-## Usage
-
 ## API
 
 ### `<GameHostProvider config={...}>`
@@ -71,14 +69,48 @@ Returns:
 - `serverUrl`: HTTP URL phones should open (or `devServerUrl` in dev mode)
 - `serverError`: static server error (if startup fails)
 
+### `useExtractAssets(manifest)`
+
+Extracts bundled web assets from the APK to a writable directory so the native HTTP server can serve them.
+
+On Android, assets live inside the APK and cannot be served directly. This hook copies each file listed in the manifest from the APK to the device filesystem. On iOS, extraction is skipped since assets are accessible from the bundle directory.
+
+```tsx
+import { useExtractAssets } from "@couch-kit/host";
+import manifest from "./www/manifest.json";
+
+function App() {
+  const { staticDir, loading, error } = useExtractAssets(manifest);
+
+  if (loading) return <Text>Extracting assets...</Text>;
+  if (error) return <Text>Error: {error}</Text>;
+
+  return (
+    <GameHostProvider config={{ staticDir, reducer, initialState }}>
+      ...
+    </GameHostProvider>
+  );
+}
+```
+
+| Property    | Type                  | Description                                       |
+| ----------- | --------------------- | ------------------------------------------------- |
+| `staticDir` | `string \| undefined` | Filesystem path to extracted assets, or undefined |
+| `loading`   | `boolean`             | Whether extraction is in progress                 |
+| `error`     | `string \| null`      | Error message if extraction failed                |
+
 ## 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:
 
@@ -157,6 +189,8 @@ To iterate on your web controller without rebuilding the Android app constantly:
 ```tsx
 <GameHostProvider
     config={{
+        reducer: gameReducer,
+        initialState,
         devMode: true,
         devServerUrl: 'http://192.168.1.50:5173' // Your laptop's IP
     }}

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,qBA4OA;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.7",
+  "version": "1.3.1",
   "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/assets.ts

@@ -1,6 +1,6 @@
 import { useEffect, useState } from "react";
 import * as FileSystem from "expo-file-system";
-import { Paths, Directory } from "expo-file-system/next";
+import { Paths, Directory } from "expo-file-system";
 import { Platform } from "react-native";
 import { toErrorMessage } from "@couch-kit/core";
 

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,
@@ -130,12 +132,12 @@ export function GameHostProvider<S extends IGameState, A extends IAction>({
     if (!wsServer.current) return;
 
     const server = wsServer.current;
-    for (const [socketId] of pendingWelcome.current) {
+    for (const [socketId, playerId] of pendingWelcome.current) {
       welcomedClients.current.add(socketId);
       server.send(socketId, {
         type: MessageTypes.WELCOME,
         payload: {
-          playerId: socketId,
+          playerId,
           state,
           serverTime: Date.now(),
         },
@@ -162,9 +164,17 @@ 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());
 
@@ -212,22 +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);
+          // Validate secret format
+          if (!secret || !isValidSecret(secret)) {
+            server.send(socketId, {
+              type: MessageTypes.ERROR,
+              payload: {
+                code: "INVALID_SECRET",
+                message: "Invalid or missing session secret",
+              },
+            });
+            return;
           }
 
-          // Dispatch the internal PLAYER_JOINED action
-          dispatch({
-            type: InternalActionTypes.PLAYER_JOINED,
-            payload: { id: socketId, ...payload },
-          } as InternalAction<S>);
+          const playerId = derivePlayerId(secret);
 
-          // Queue WELCOME to be sent after React re-renders and stateRef is updated.
-          // A useEffect watches for pending welcomes and sends them with fresh state.
-          pendingWelcome.current.set(socketId, socketId);
+          // Update session maps
+          sessions.current.set(secret, socketId);
+          reverseMap.current.set(socketId, secret);
 
-          configRef.current.onPlayerJoined?.(socketId, payload.name);
+          // Cancel any pending cleanup timer for this player
+          const existingTimer = cleanupTimers.current.get(playerId);
+          if (existingTimer) {
+            clearTimeout(existingTimer);
+            cleanupTimers.current.delete(playerId);
+          }
+
+          // 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;
         }
 
@@ -238,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(
@@ -255,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;
         }
 
@@ -278,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) => {
@@ -297,6 +369,10 @@ 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
 

package/src/server.ts

@@ -1,6 +1,6 @@
 import { useEffect, useState } from "react";
 import { StaticServer } from "react-native-nitro-http-server";
-import { Paths } from "expo-file-system/next";
+import { Paths } from "expo-file-system";
 import { getBestIpAddress } from "./network";
 import { DEFAULT_HTTP_PORT, toErrorMessage } from "@couch-kit/core";
 
@@ -58,7 +58,7 @@ export const useStaticServer = (config: CouchKitHostConfig) => {
           if (!bundleUri) {
             throw new Error(
               "No staticDir provided and Paths.bundle is unavailable. " +
-              "On Android, you must pass staticDir from useExtractAssets.",
+                "On Android, you must pass staticDir from useExtractAssets.",
             );
           }
           path = `${bundleUri.replace(/^file:\/\//, "")}www`;