@couch-kit/host 1.7.10 → 1.7.12

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 react-native-nitro-modules
+bun add react-native-nitro-modules
 ```
 
-> **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.
+> **Note:** This library requires Expo modules (`expo-file-system`, `expo-network`) 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
 
@@ -39,9 +39,8 @@ bun add react-native-tcp-socket react-native-nitro-modules
 | `react-native`               | `>= 0.72.0`     |
 | `react-native-nitro-modules` | `>= 0.33.0`     |
 | `expo`                       | `>= 51.0.0`     |
-| `expo-file-system`           | `>= 17.0.0`     |
+| `expo-file-system`           | `>= 19.0.0`    |
 | `expo-network`               | `>= 7.0.0`      |
-| `react-native-tcp-socket`    | `>= 6.0.0`      |
 
 > **New Architecture:** This package supports React Native's New Architecture (Fabric/TurboModules) via React Native 0.83+.
 
@@ -58,6 +57,8 @@ Config:
 - `staticDir?`: absolute path to the directory of static files to serve. **Required on Android** — APK assets live inside a zip archive and cannot be served directly, so use this to point to a writable filesystem path where you've extracted the `www/` assets at runtime. On iOS, defaults to the bundle directory + `/www`.
 - `devMode?`: if true, do not start the TV static file server; instead point phones at `devServerUrl`
 - `devServerUrl?`: URL of your laptop dev server (e.g. `http://192.168.1.50:5173`)
+- `stateThrottleMs?`: minimum interval (ms) between state broadcasts (default `33` ≈ 30fps)
+- `disconnectTimeout?`: time (ms) before a disconnected player is permanently removed (default `300000` = 5 minutes)
 - `debug?`: enable verbose logs
 
 ### `useGameHost()`
@@ -183,8 +184,8 @@ function GameScreen() {
 
 To iterate on your web controller without rebuilding the Android app constantly:
 
-1.  Start your web project locally (`vite dev` usually runs on `localhost:5173`).
-2.  Configure the Host to point to your laptop:
+1. Start your web project locally (`vite dev` usually runs on `localhost:5173`).
+2. Configure the Host to point to your laptop:
 
 ```tsx
 <GameHostProvider
@@ -206,3 +207,51 @@ Important: when the controller is served from the laptop, the client-side hook c
 In production, the host serves static controller assets from the iOS bundle directory + `/www` by default. On Android, `staticDir` must be provided since bundle assets live inside the APK.
 
 The CLI `couch-kit bundle` copies your web build output into `android/app/src/main/assets/www` (default). Ensure your app packaging makes those assets available under the expected `www` folder.
+
+## Additional Hooks
+
+### `useActionRecorder()`
+
+Records game actions with timestamps for session replay and debugging. Useful for testing, bug reproduction, and replay-based features.
+
+```tsx
+import { useActionRecorder, useGameHost } from "@couch-kit/host";
+
+function GameScreen() {
+  const { state } = useGameHost();
+  const { isRecording, recordedCount, startRecording, stopRecording, recordAction } =
+    useActionRecorder();
+
+  const handleStartRecording = () => startRecording(state);
+  const handleStop = () => {
+    const recording = stopRecording();
+    // Save recording JSON for later replay via `couch-kit replay`
+    console.log(JSON.stringify(recording));
+  };
+
+  return (
+    <View>
+      <Text>Actions recorded: {recordedCount}</Text>
+      <Button title={isRecording ? "Stop" : "Record"} onPress={isRecording ? handleStop : handleStartRecording} />
+    </View>
+  );
+}
+```
+
+Returns:
+
+- `isRecording`: whether a recording session is active
+- `recordedCount`: number of actions captured so far
+- `startRecording(currentState, metadata?)`: begin recording from the given state
+- `stopRecording()`: end recording and return the `ActionRecording` object (or `null`)
+- `recordAction(action, state)`: capture a single action + resulting state
+
+### `getBestIpAddress()`
+
+Returns the device's best LAN IPv4 address (or `null`). Used internally by the provider but exported for custom networking UI (e.g., displaying a manual connect URL).
+
+```tsx
+import { getBestIpAddress } from "@couch-kit/host";
+
+const ip = await getBestIpAddress(); // e.g. "192.168.1.99"
+```

package/lib/action-authorization.d.ts

@@ -0,0 +1,28 @@
+/** Error codes surfaced when a client ACTION is rejected before dispatch. */
+export type ActionRejectionCode = "FORBIDDEN_ACTION" | "NOT_JOINED";
+/** Outcome of authorizing an inbound client ACTION message. */
+export type ActionAuthorization = {
+    kind: "allow";
+    playerId: string;
+} | {
+    kind: "reject";
+    code: ActionRejectionCode;
+    message: string;
+};
+/**
+ * Decide whether an inbound client ACTION may be dispatched.
+ *
+ * Rejects, in order:
+ * - **Internal action types** — clients must not be able to inject framework
+ *   actions (`__HYDRATE__`, `__PLAYER_JOINED__`, etc.) to forge state.
+ * - **Un-joined sockets** — a socket with no resolved player ID never completed
+ *   a JOIN, so its actions have no owner and must not mutate state.
+ *
+ * The decision is pure so it can be unit-tested without a WebSocket or React.
+ *
+ * @param actionType - The `type` field of the client's action payload.
+ * @param resolvedPlayerId - The player ID cached for the socket at JOIN time, or
+ *   `undefined` if the socket has not joined.
+ */
+export declare function authorizeClientAction(actionType: string, resolvedPlayerId: string | undefined): ActionAuthorization;
+//# sourceMappingURL=action-authorization.d.ts.map

package/lib/action-authorization.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"action-authorization.d.ts","sourceRoot":"","sources":["../src/action-authorization.ts"],"names":[],"mappings":"AAEA,6EAA6E;AAC7E,MAAM,MAAM,mBAAmB,GAAG,kBAAkB,GAAG,YAAY,CAAC;AAEpE,+DAA+D;AAC/D,MAAM,MAAM,mBAAmB,GAC3B;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACnC;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,mBAAmB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAUnE;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,MAAM,EAClB,gBAAgB,EAAE,MAAM,GAAG,SAAS,GACnC,mBAAmB,CAkBrB"}

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,EAQL,KAAK,UAAU,EACf,KAAK,OAAO,EAEb,MAAM,iBAAiB,CAAC;AAazB,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,6FAA6F;IAC7F,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,iFAAiF;IACjF,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,+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;AAQD;;;;;;;;;;;;;;;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,qBA2WA;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,EAEb,MAAM,iBAAiB,CAAC;AAczB,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,6FAA6F;IAC7F,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,iFAAiF;IACjF,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,+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;AAQD;;;;;;;;;;;;;;;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,qBAqWA;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.7.10",
+  "version": "1.7.12",
   "publishConfig": {
     "access": "public",
     "provenance": true
@@ -58,13 +58,13 @@
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "@couch-kit/core": "0.9.1",
+    "@couch-kit/core": "0.9.2",
     "buffer": "^6.0.3",
     "js-sha1": "^0.7.0",
     "react-native-nitro-http-server": "^1.6.1"
   },
   "devDependencies": {
-    "@types/react": "^19.1.1",
+    "@types/react": "^19.2.17",
     "react": "19.0.4",
     "react-native": "0.83.2",
     "del-cli": "^5.1.0",

package/src/action-authorization.ts

@@ -0,0 +1,55 @@
+import { InternalActionTypes } from "@couch-kit/core";
+
+/** Error codes surfaced when a client ACTION is rejected before dispatch. */
+export type ActionRejectionCode = "FORBIDDEN_ACTION" | "NOT_JOINED";
+
+/** Outcome of authorizing an inbound client ACTION message. */
+export type ActionAuthorization =
+  | { kind: "allow"; playerId: string }
+  | { kind: "reject"; code: ActionRejectionCode; message: string };
+
+const INTERNAL_ACTION_TYPES = new Set<string>([
+  InternalActionTypes.HYDRATE,
+  InternalActionTypes.PLAYER_JOINED,
+  InternalActionTypes.PLAYER_LEFT,
+  InternalActionTypes.PLAYER_RECONNECTED,
+  InternalActionTypes.PLAYER_REMOVED,
+]);
+
+/**
+ * Decide whether an inbound client ACTION may be dispatched.
+ *
+ * Rejects, in order:
+ * - **Internal action types** — clients must not be able to inject framework
+ *   actions (`__HYDRATE__`, `__PLAYER_JOINED__`, etc.) to forge state.
+ * - **Un-joined sockets** — a socket with no resolved player ID never completed
+ *   a JOIN, so its actions have no owner and must not mutate state.
+ *
+ * The decision is pure so it can be unit-tested without a WebSocket or React.
+ *
+ * @param actionType - The `type` field of the client's action payload.
+ * @param resolvedPlayerId - The player ID cached for the socket at JOIN time, or
+ *   `undefined` if the socket has not joined.
+ */
+export function authorizeClientAction(
+  actionType: string,
+  resolvedPlayerId: string | undefined,
+): ActionAuthorization {
+  if (INTERNAL_ACTION_TYPES.has(actionType)) {
+    return {
+      kind: "reject",
+      code: "FORBIDDEN_ACTION",
+      message: "Internal action types cannot be dispatched by clients",
+    };
+  }
+
+  if (!resolvedPlayerId) {
+    return {
+      kind: "reject",
+      code: "NOT_JOINED",
+      message: "You must JOIN before dispatching actions",
+    };
+  }
+
+  return { kind: "allow", playerId: resolvedPlayerId };
+}

package/src/provider.tsx

@@ -27,6 +27,7 @@ import {
   HostSessionManager,
   type JoinSessionPayload,
 } from "./session-manager";
+import { authorizeClientAction } from "./action-authorization";
 import {
   BroadcastScheduler,
   DEFAULT_STATE_THROTTLE_MS,
@@ -283,28 +284,25 @@ export function GameHostProvider<S extends IGameState, A extends IAction>({
         }
 
         case MessageTypes.ACTION: {
-          // Only accept actions with a user-defined type string,
-          // reject internal action types to prevent injection.
           const actionPayload = message.payload as A;
-          if (
-            actionPayload.type === InternalActionTypes.HYDRATE ||
-            actionPayload.type === InternalActionTypes.PLAYER_JOINED ||
-            actionPayload.type === InternalActionTypes.PLAYER_LEFT ||
-            actionPayload.type === InternalActionTypes.PLAYER_RECONNECTED ||
-            actionPayload.type === InternalActionTypes.PLAYER_REMOVED
-          ) {
+
+          // Authorize before doing any work: reject client-injected internal
+          // action types and actions from sockets that never completed a JOIN.
+          const resolvedPlayerId =
+            sessionManager.current.getPlayerIdForSocket(socketId);
+          const auth = authorizeClientAction(
+            actionPayload.type,
+            resolvedPlayerId,
+          );
+          if (auth.kind === "reject") {
             if (configRef.current.debug)
               console.warn(
-                `[GameHost] Rejected internal action from ${socketId}:`,
+                `[GameHost] Rejected action from ${socketId} (${auth.code}):`,
                 actionPayload.type,
               );
             server.send(socketId, {
               type: MessageTypes.ERROR,
-              payload: {
-                code: "FORBIDDEN_ACTION",
-                message:
-                  "Internal action types cannot be dispatched by clients",
-              },
+              payload: { code: auth.code, message: auth.message },
             });
             return;
           }
@@ -323,10 +321,7 @@ export function GameHostProvider<S extends IGameState, A extends IAction>({
             return;
           }
 
-          // Use cached playerId (populated at JOIN time)
-          const resolvedPlayerId =
-            sessionManager.current.getPlayerIdForSocket(socketId);
-          dispatch({ ...actionPayload, playerId: resolvedPlayerId });
+          dispatch({ ...actionPayload, playerId: auth.playerId });
           actionQueue.current.push(actionPayload);
           break;
         }