@couch-kit/client 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,59 @@
+# @couch-kit/client
+
+## 0.3.0
+
+### Minor Changes
+
+- 95cafe9: Fix critical bugs and improve reliability across all packages.
+
+  **@couch-kit/core**: Make `IGameState.status` a flexible `string` type instead of a restrictive union, allowing games to define custom phases like `"round_end"` or `"game_over"`.
+
+  **@couch-kit/client**: Fix WELCOME message handler to hydrate state immediately on connect instead of waiting for the next STATE_UPDATE broadcast. Add `name` and `avatar` config options to `useGameClient` so games can customize player identity. Wrap `localStorage` access in try/catch for Safari private browsing and restrictive WebView compatibility.
+
+  **@couch-kit/host**: Rewrite WebSocket frame processing with proper buffer management — process all complete frames per TCP packet instead of only the first (fixes silent data loss). Add RFC 6455 opcode handling for close frames (send close response), ping frames (respond with pong), and graceful handling of binary/unknown frames. Fix corrupt JSON no longer permanently blocking a connection. Retain post-handshake data that arrives in the same TCP packet. Improve socket ID generation from ~5-6 chars to 21 chars to eliminate collision risk. Update stale `declarations.d.ts` to match actual `react-native-nitro-http-server` import.
+
+  **@couch-kit/cli**: Fix `simulate` command default WebSocket URL from port 8081 to 8082 to match actual server port.
+
+### Patch Changes
+
+- Updated dependencies [95cafe9]
+  - @couch-kit/core@0.2.0
+
+## 0.2.0
+
+### Minor Changes
+
+- 38bc20e: Change default WebSocket port convention from HTTP+1 to HTTP+2 to avoid conflicts with Metro bundler (which uses port 8081). Add configurable `wsPort` option to client config. Both host and client now derive WS port as `httpPort + 2` by default (e.g., HTTP 8080 -> WS 8082).
+
+## 0.1.0
+
+### Minor Changes
+
+- - **Session Recovery:** Added support for session recovery. The client now stores a secret and sends it on join. The host tracks these secrets and restores the session (mapping the new socket to the old session).
+  - **Automatic Hydration:** The client now automatically handles the `HYDRATE` action. Users no longer need to implement this in their reducer.
+  - **Large Message Support:** The Host WebSocket implementation now supports messages larger than 64KB (64-bit frame lengths).
+
+### Patch Changes
+
+- Updated dependencies
+  - @couch-kit/core@0.1.0
+
+## 0.0.4
+
+### Patch Changes
+
+- Fix dependency resolution for @couch-kit/core
+
+## 0.0.3
+
+### Patch Changes
+
+- Fix dependency mismatch: update dependencies to point to published @couch-kit/core@0.0.2
+
+## 0.0.2
+
+### Patch Changes
+
+- Initial public release. Removed example apps, refactored logging, and prepared strictly typed packages for usage.
+- Updated dependencies
+  - @couch-kit/core@0.0.2

package/README.md

@@ -0,0 +1,151 @@
+# @couch-kit/client
+
+The client-side library for the web controller. Designed to be lightweight and framework-agnostic (though React hooks are provided).
+
+## Features
+
+- **Default connection:** By default, connects to `ws(s)://{window.location.hostname}:8082`.
+- **Time synchronization:** `useServerTime()` helps estimate server time using periodic ping/pong.
+- **Asset preloading:** `usePreload()` is a small helper for preloading images and fetching other URLs.
+- **Optimistic UI:** State updates apply locally immediately while being sent to the server.
+- **Reconnection attempts:** Automatically retries the WebSocket connection when it drops.
+- **Session Recovery:** Persists a secret in local storage to recover the same player session after a page refresh.
+
+## Installation
+
+```bash
+bun add @couch-kit/client
+```
+
+## API
+
+### `useGameClient(config)`
+
+Connects the controller to the TV host WebSocket, applies state updates, and provides an action sender.
+
+Config:
+
+- `reducer`: `(state, action) => state` (your shared reducer)
+- `initialState`: initial state used until the host hydrates
+- `url?`: explicit WebSocket URL. If omitted, the hook uses `ws(s)://{window.location.hostname}:8082`.
+- `debug?`: enable console logs
+- `onConnect?`, `onDisconnect?`: lifecycle callbacks
+
+Returns:
+
+- `status`: `'connecting' | 'connected' | 'disconnected' | 'error'`
+- `state`: current controller state (optimistic + hydrated)
+- `playerId`: server-assigned player id (after `WELCOME`)
+- `sendAction(action)`: optimistic dispatch + send to host
+- `getServerTime()`: NTP-ish server time based on periodic ping/pong
+
+## State Sync Contract
+
+The host broadcasts full state snapshots. The client automatically applies them using a higher-order reducer wrapper.
+
+**You do NOT need to handle `HYDRATE` manually in your reducer.** The library now handles this automatically by intercepting the hydration action before it reaches your reducer logic.
+
+Just write your reducer as if it were local:
+
+```ts
+function reducer(state, action) {
+  switch (action.type) {
+    case "SCORE":
+      return { ...state, score: state.score + 1 };
+    default:
+      return state;
+  }
+}
+```
+
+## Dev Mode (Controller Served From Laptop)
+
+If your controller is served from your laptop (Vite), `window.location.hostname` is the laptop, so the “magic connection” will try to connect WS to the laptop.
+
+In dev, pass the TV WebSocket URL explicitly:
+
+```ts
+useGameClient({
+  reducer,
+  initialState,
+  url: "ws://TV_IP:8082",
+});
+```
+
+## Usage
+
+### 1. The Main Hook
+
+The `useGameClient` hook manages the WebSocket connection and synchronizes state with the TV.
+
+```tsx
+import { useGameClient } from "@couch-kit/client";
+import { gameReducer, initialState } from "./shared/types";
+
+export default function Controller() {
+  const {
+    status, // 'connecting' | 'connected' | 'disconnected' | 'error'
+    state, // The current game state (synced with Host)
+    playerId, // Your unique session ID
+    sendAction, // Function to send actions to Host
+  } = useGameClient({
+    reducer: gameReducer,
+    initialState: initialState,
+    onConnect: () => console.log("Joined the party!"),
+    onDisconnect: () => console.log("Left the party!"),
+  });
+
+  if (status === "connecting") {
+    return <div>Connecting to TV...</div>;
+  }
+
+  return (
+    <div className="controller">
+      <h1>Score: {state.score}</h1>
+      <button onClick={() => sendAction({ type: "JUMP" })}>JUMP!</button>
+    </div>
+  );
+}
+```
+
+### 2. Time Synchronization
+
+For rhythm games or precise countdowns, use `getServerTime()` instead of `Date.now()`. This accounts for network latency.
+
+```tsx
+import { useServerTime } from "@couch-kit/client";
+
+function Countdown({ targetTimestamp }) {
+  const { getServerTime } = useServerTime();
+
+  // Calculate seconds remaining based on SERVER time
+  const now = getServerTime();
+  const remaining = Math.max(0, targetTimestamp - now);
+
+  return <div>{Math.ceil(remaining / 1000)}s</div>;
+}
+```
+
+### 3. Asset Preloading
+
+Ensure heavy assets (images, sounds) are fully loaded before showing the game interface.
+
+```tsx
+import { usePreload } from "@couch-kit/client";
+
+const ASSETS = ["/images/avatar_1.png", "/sounds/buzz.mp3"];
+
+function App() {
+  const { loaded, progress } = usePreload(ASSETS);
+
+  if (!loaded) {
+    return <div>Loading... {Math.round(progress)}%</div>;
+  }
+
+  return <GameController />;
+}
+```
+
+## Notes / Limitations
+
+- `usePreload()` preloads images via `Image()` and uses `fetch()` for other URLs; it does not currently send the protocol `ASSETS_LOADED` message.