@couch-kit/client 0.11.0 → 0.13.0

package/CHANGELOG.md

@@ -1,5 +1,56 @@
 # @couch-kit/client
 
+## 0.13.0
+
+### Minor Changes
+
+- [#158](https://github.com/faluciano/react-native-couch-kit/pull/158) [`509ea7c`](https://github.com/faluciano/react-native-couch-kit/commit/509ea7c02aa6f2e56ebf01e781d6de74f0ded021) Thanks [@faluciano](https://github.com/faluciano)! - Let the relay assign room codes
+
+  `RelayDisplayHost`'s `roomId` is now optional. Omit it and the relay mints an
+  unused six-character code, reported through the new `onRoomCode` callback and
+  the `roomCode` getter.
+
+  A display could never check its own code for collisions — only the relay knows
+  which codes are live — so a self-chosen code could land on a game already in
+  progress, and did so only after it was on screen. Minted codes are drawn from
+  the CSPRNG over a 32-character alphabet without `O`/`0` or `I`/`1`, giving about
+  1.07 billion codes.
+
+  Existing callers that pass `roomId` keep their current behaviour, including
+  `ROOM_EXISTS` when the code is taken. New callers should expect the code to
+  arrive one round trip after connecting rather than being known up front:
+
+  ```ts
+  const [roomCode, setRoomCode] = useState<string | null>(null);
+  new RelayDisplayHost({ url, onRoomCode: setRoomCode, reducer, initialState });
+  ```
+
+  Relays need a matching update to mint: both bundled implementations
+  (`services/relay`, `services/relay-worker`) support it. A display that omits
+  `roomId` against an older relay gets `MALFORMED`.
+
+## 0.12.0
+
+### Minor Changes
+
+- [#155](https://github.com/faluciano/react-native-couch-kit/pull/155) [`4f297a1`](https://github.com/faluciano/react-native-couch-kit/commit/4f297a19c442541703c3bee7bee26354ae3476a4) Thanks [@faluciano](https://github.com/faluciano)! - Hidden information can now be hidden for real: `GameHostRuntimeConfig` takes an
+  optional `project(state, playerId)` that narrows the authoritative state to what
+  one player may see.
+
+  Without it the runtime broadcasts the same state to everyone, so hiding a hand
+  depends on the client choosing not to look — any player could read opponents'
+  cards from devtools. With it, the data never reaches their device: the runtime
+  sends each connection its own projection, in `WELCOME`, `RECONNECTED`, and every
+  state update.
+
+  Games with no hidden information omit `project` and are unchanged — state is
+  still broadcast in one frame.
+
+  Because a projected client holds a _view_ rather than the whole state, it cannot
+  run the game reducer, so `ClientConfig.reducer` is now optional. Omit it and the
+  client renders what the host sends (no optimistic updates); a round trip is
+  imperceptible for turn-based games, and it is what makes the guarantee real.
+
 ## 0.11.0
 
 ### Minor Changes

package/dist/index.js

@@ -168,7 +168,7 @@ function useGameClient(config) {
   const [status, setStatus] = useState2("disconnected");
   const [playerId, setPlayerId] = useState2(null);
   const [disconnectReason, setDisconnectReason] = useState2(null);
-  const [state, dispatchLocal] = useReducer(createGameReducer(config.reducer), config.initialState);
+  const [state, dispatchLocal] = useReducer(createGameReducer(config.reducer ?? ((current) => current)), config.initialState);
   const socketRef = useRef2(null);
   const reconnectAttempts = useRef2(0);
   const reconnectTimer = useRef2(null);
@@ -345,9 +345,10 @@ var RelayErrorCodes = {
 function relayRoomUrl(url, roomId) {
   const trimmed = url.replace(/\/+$/, "");
   const [base, query] = trimmed.split("?", 2);
-  const path = `${base}/r/${encodeURIComponent(roomId)}`;
+  const path = roomId === undefined ? `${base}${RELAY_MINT_PATH}` : `${base}/r/${encodeURIComponent(roomId)}`;
   return query ? `${path}?${query}` : path;
 }
+var RELAY_MINT_PATH = "/new";
 // src/relay-transport.ts
 var POLICY_CLOSE_CODE = 1008;
 
@@ -647,5 +648,6 @@ export {
   SESSION_SECRET_KEY,
   RelayMessageTypes,
   RelayErrorCodes,
-  RelayClientTransport
+  RelayClientTransport,
+  RELAY_MINT_PATH
 };

package/lib/client.d.ts

@@ -3,7 +3,17 @@ import { type CreateClientTransport } from "./transport";
 export interface ClientConfig<S extends IGameState, A extends IAction> {
     url?: string;
     wsPort?: number;
-    reducer: (state: S, action: A) => S;
+    /**
+     * Applies actions locally for an optimistic update before the host confirms.
+     *
+     * **Omit it when the host projects state per player** (`project` in
+     * `GameHostRuntimeConfig`): the client then holds a *view* rather than the
+     * whole state, and the game reducer cannot run over a partial view. Without a
+     * reducer the client simply renders what the host sends — a round trip that
+     * is imperceptible for turn-based games, and the price of hidden information
+     * never reaching the device.
+     */
+    reducer?: (state: S, action: A) => S;
     initialState: S;
     name?: string;
     avatar?: string;

package/lib/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AACA,OAAO,EAQL,KAAK,UAAU,EACf,KAAK,OAAO,EAEb,MAAM,iBAAiB,CAAC;AASzB,OAAO,EAIL,KAAK,qBAAqB,EAC3B,MAAM,aAAa,CAAC;AAErB,MAAM,WAAW,YAAY,CAAC,CAAC,SAAS,UAAU,EAAE,CAAC,SAAS,OAAO;IACnE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,KAAK,CAAC,CAAC;IACpC,YAAY,EAAE,CAAC,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,mEAAmE;IACnE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wEAAwE;IACxE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,IAAI,CAAC;IAC1B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;;;OAKG;IACH,eAAe,CAAC,EAAE,qBAAqB,CAAC;CACzC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,UAAU,EAAE,CAAC,SAAS,OAAO,EACnE,MAAM,EAAE,YAAY,CAAC,CAAC,EAAE,CAAC,CAAC;;;;IAyOxB;;;;OAIG;;yBAvBmC,CAAC;;IA2BvC,8EAA8E;;IAE9E,0EAA0E;;IAE1E,+EAA+E;;EAGlF"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AACA,OAAO,EAQL,KAAK,UAAU,EACf,KAAK,OAAO,EAEb,MAAM,iBAAiB,CAAC;AASzB,OAAO,EAIL,KAAK,qBAAqB,EAC3B,MAAM,aAAa,CAAC;AAErB,MAAM,WAAW,YAAY,CAAC,CAAC,SAAS,UAAU,EAAE,CAAC,SAAS,OAAO;IACnE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;;;;OASG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,KAAK,CAAC,CAAC;IACrC,YAAY,EAAE,CAAC,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,mEAAmE;IACnE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wEAAwE;IACxE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,IAAI,CAAC;IAC1B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;;;OAKG;IACH,eAAe,CAAC,EAAE,qBAAqB,CAAC;CACzC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,UAAU,EAAE,CAAC,SAAS,OAAO,EACnE,MAAM,EAAE,YAAY,CAAC,CAAC,EAAE,CAAC,CAAC;;;;IA2OxB;;;;OAIG;;yBAvBmC,CAAC;;IA2BvC,8EAA8E;;IAE9E,0EAA0E;;IAE1E,+EAA+E;;EAGlF"}

package/lib/relay-protocol.d.ts

@@ -119,8 +119,19 @@ export type RelayMessage = RelayClientMessage | RelayServerMessage;
  * that keep every room in one process (the Bun reference server) ignore the
  * path, so this is safe to send to either.
  *
+ * Passing no room code addresses {@link RELAY_MINT_PATH} instead, asking the
+ * relay to allocate one; the code comes back in `ROOM_CREATED`.
+ *
  * @param url - Base relay URL, e.g. `wss://relay.example.com`.
- * @param roomId - Room code to address.
+ * @param roomId - Room code to address, or omitted to have one minted.
+ */
+export declare function relayRoomUrl(url: string, roomId?: string): string;
+/**
+ * Path that asks the relay to allocate a room code.
+ *
+ * Reserved, so it can never be mistaken for a room code. Single-process relays
+ * ignore the path and mint from the `CREATE_ROOM` message alone; sharded relays
+ * need it, because they must choose the shard before any frame arrives.
  */
-export declare function relayRoomUrl(url: string, roomId: string): string;
+export declare const RELAY_MINT_PATH = "/new";
 //# sourceMappingURL=relay-protocol.d.ts.map

package/lib/relay-protocol.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"relay-protocol.d.ts","sourceRoot":"","sources":["../src/relay-protocol.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"relay-protocol.d.ts","sourceRoot":"","sources":["../src/relay-protocol.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@couch-kit/client",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "publishConfig": {
     "access": "public",
     "provenance": true

package/src/client.ts

@@ -29,7 +29,17 @@ import {
 export interface ClientConfig<S extends IGameState, A extends IAction> {
   url?: string; // Full WebSocket URL (overrides auto-detection)
   wsPort?: number; // WebSocket port (default: auto-detected as HTTP port + 2)
-  reducer: (state: S, action: A) => S;
+  /**
+   * Applies actions locally for an optimistic update before the host confirms.
+   *
+   * **Omit it when the host projects state per player** (`project` in
+   * `GameHostRuntimeConfig`): the client then holds a *view* rather than the
+   * whole state, and the game reducer cannot run over a partial view. Without a
+   * reducer the client simply renders what the host sends — a round trip that
+   * is imperceptible for turn-based games, and the price of hidden information
+   * never reaching the device.
+   */
+  reducer?: (state: S, action: A) => S;
   initialState: S;
   name?: string; // Player display name (default: "Player")
   avatar?: string; // Player avatar emoji (default: "\u{1F600}")
@@ -83,9 +93,11 @@ export function useGameClient<S extends IGameState, A extends IAction>(
   const [disconnectReason, setDisconnectReason] = useState<string | null>(null);
 
   // Local Optimistic State
-  // Wrap the user's reducer with createGameReducer to handle HYDRATE automatically
+  // Wrap the user's reducer with createGameReducer to handle HYDRATE automatically.
+  // With no reducer (server-projected views) the identity function keeps HYDRATE
+  // working while local application becomes a no-op.
   const [state, dispatchLocal] = useReducer(
-    createGameReducer(config.reducer),
+    createGameReducer(config.reducer ?? ((current: S) => current)),
     config.initialState,
   );
 

package/src/relay-protocol.ts

@@ -144,12 +144,27 @@ export type RelayMessage = RelayClientMessage | RelayServerMessage;
  * that keep every room in one process (the Bun reference server) ignore the
  * path, so this is safe to send to either.
  *
+ * Passing no room code addresses {@link RELAY_MINT_PATH} instead, asking the
+ * relay to allocate one; the code comes back in `ROOM_CREATED`.
+ *
  * @param url - Base relay URL, e.g. `wss://relay.example.com`.
- * @param roomId - Room code to address.
+ * @param roomId - Room code to address, or omitted to have one minted.
  */
-export function relayRoomUrl(url: string, roomId: string): string {
+export function relayRoomUrl(url: string, roomId?: string): string {
   const trimmed = url.replace(/\/+$/, "");
   const [base, query] = trimmed.split("?", 2);
-  const path = `${base}/r/${encodeURIComponent(roomId)}`;
+  const path =
+    roomId === undefined
+      ? `${base}${RELAY_MINT_PATH}`
+      : `${base}/r/${encodeURIComponent(roomId)}`;
   return query ? `${path}?${query}` : path;
 }
+
+/**
+ * Path that asks the relay to allocate a room code.
+ *
+ * Reserved, so it can never be mistaken for a room code. Single-process relays
+ * ignore the path and mint from the `CREATE_ROOM` message alone; sharded relays
+ * need it, because they must choose the shard before any frame arrives.
+ */
+export const RELAY_MINT_PATH = "/new";