@couch-kit/host 0.5.1 → 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.1",
+  "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

@@ -87,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,
@@ -318,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);