@couch-kit/host 0.5.0 → 0.5.2

package/README.md

@@ -50,14 +50,20 @@ Returns:
 - `serverUrl`: HTTP URL phones should open (or `devServerUrl` in dev mode)
 - `serverError`: static server error (if startup fails)
 
-## System Actions (Important)
+## System Actions
 
-The host will dispatch a few **system action types** into your reducer. Treat these as reserved:
+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.**
 
-- `PLAYER_JOINED`: payload `{ id: string, name: string, avatar?: string, secret?: string }`
-- `PLAYER_LEFT`: payload `{ playerId: string }`
+Player tracking (`state.players`) is managed automatically:
 
-If you want to track players in `state.players`, handle these action types in your reducer. The `secret` field can be used to identify returning players.
+- When a player joins, they are added to `state.players` with `connected: true`.
+- When a player disconnects, they are marked as `connected: false`.
+
+To react to player events outside of state (e.g., logging, analytics), use the callback config options:
+
+- `onPlayerJoined?: (playerId: string, name: string) => void` -- called when a player successfully joins.
+- `onPlayerLeft?: (playerId: string) => void` -- called when a player disconnects.
+- `onError?: (error: Error) => void` -- called when a server error occurs.
 
 ### 1. Configure the Provider
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@couch-kit/host",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "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 @@
     "clean": "del-cli lib"
   },
   "dependencies": {
-    "@couch-kit/core": "0.3.1",
+    "@couch-kit/core": "0.3.2",
     "buffer": "^6.0.3",
     "js-sha1": "^0.7.0",
     "react-native-fs": "^2.20.0",
@@ -60,8 +60,8 @@
     "react-native-tcp-socket": "^6.0.6"
   },
   "devDependencies": {
-    "@types/react": "~17.0.21",
-    "@types/react-native": "0.70.0",
+    "@types/react": "^18.2.0",
+    "@types/react-native": "^0.72.0",
     "react": "18.2.0",
     "react-native": "0.72.6",
     "del-cli": "^5.1.0",

package/src/provider.tsx

@@ -14,6 +14,7 @@ import {
   InternalActionTypes,
   DEFAULT_HTTP_PORT,
   DEFAULT_WS_PORT_OFFSET,
+  createGameReducer,
   type IGameState,
   type IAction,
   type InternalAction,
@@ -22,7 +23,7 @@ import {
 
 export interface GameHostConfig<S extends IGameState, A extends IAction> {
   initialState: S;
-  reducer: (state: S, action: A | InternalAction<S>) => S;
+  reducer: (state: S, action: A) => S;
   port?: number; // Static server port (default 8080)
   wsPort?: number; // WebSocket port (default: HTTP port + 2, i.e. 8082)
   devMode?: boolean;
@@ -39,7 +40,7 @@ export interface GameHostConfig<S extends IGameState, A extends IAction> {
 
 interface GameHostContextValue<S extends IGameState, A extends IAction> {
   state: S;
-  dispatch: (action: A | InternalAction<S>) => void;
+  dispatch: (action: A) => void;
   serverUrl: string | null;
   serverError: Error | null;
 }
@@ -86,6 +87,22 @@ function isValidClientMessage(msg: unknown): msg is ClientMessage {
   }
 }
 
+/**
+ * React context provider that turns a React Native TV app into a local game server.
+ *
+ * Starts a static file server (for the web controller) and a WebSocket game server
+ * (for real-time state sync). Manages the canonical game state using the provided
+ * reducer and broadcasts state updates to all connected clients.
+ *
+ * @param config - Host configuration including reducer, initial state, ports, and callbacks.
+ *
+ * @example
+ * ```tsx
+ * <GameHostProvider config={{ reducer: gameReducer, initialState }}>
+ *   <GameScreen />
+ * </GameHostProvider>
+ * ```
+ */
 export function GameHostProvider<S extends IGameState, A extends IAction>({
   children,
   config,
@@ -93,7 +110,12 @@ export function GameHostProvider<S extends IGameState, A extends IAction>({
   children: React.ReactNode;
   config: GameHostConfig<S, A>;
 }) {
-  const [state, dispatch] = useReducer(config.reducer, config.initialState);
+  // Wrap the user's reducer with createGameReducer to handle internal actions
+  // (HYDRATE, PLAYER_JOINED, PLAYER_LEFT) automatically.
+  const [state, dispatch] = useReducer(
+    createGameReducer(config.reducer),
+    config.initialState,
+  );
 
   // Keep a ref to state so we can access it inside callbacks/effects that don't depend on it
   const stateRef = useRef(state);
@@ -312,6 +334,16 @@ export function GameHostProvider<S extends IGameState, A extends IAction>({
   );
 }
 
+/**
+ * React hook to access the game host context.
+ *
+ * Must be used within a `<GameHostProvider>`. Returns the canonical game state,
+ * a dispatch function for actions, the server URL (for QR codes), and any
+ * server startup errors.
+ *
+ * @returns An object with `state`, `dispatch`, `serverUrl`, and `serverError`.
+ * @throws If used outside of a `<GameHostProvider>`.
+ */
 export function useGameHost<S extends IGameState, A extends IAction>() {
   const context = useContext(GameHostContext);
   if (!context) {

package/src/server.ts

@@ -11,6 +11,16 @@ export interface CouchKitHostConfig {
   staticDir?: string; // Override the default www directory path (required on Android)
 }
 
+/**
+ * React hook that manages a static HTTP file server for serving the web controller.
+ *
+ * In production mode, starts a `StaticServer` bound to `0.0.0.0` on the configured port,
+ * serving files from `staticDir` (or `${RNFS.MainBundlePath}/www` by default).
+ * In dev mode, skips the server and returns `devServerUrl` directly.
+ *
+ * @param config - Server configuration including port, dev mode, and static directory.
+ * @returns An object with `url` (the server URL or null), `error`, and `loading`.
+ */
 export const useStaticServer = (config: CouchKitHostConfig) => {
   const [url, setUrl] = useState<string | null>(null);
   const [error, setError] = useState<Error | null>(null);