@couch-kit/client 0.10.1 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,56 @@
 # @couch-kit/client
 
+## 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
+
+- [#147](https://github.com/faluciano/react-native-couch-kit/pull/147) [`abf8bbe`](https://github.com/faluciano/react-native-couch-kit/commit/abf8bbe075e8f5eff00ffee7d9131009195c6a0e) Thanks [@faluciano](https://github.com/faluciano)! - Relay clients can now tell players _why_ a join failed, and ask for a room code
+  when they don't have one.
+
+  A hosted controller opened without `?room=` has no LAN host to fall back to, so
+  it could only sit on "connecting" forever — and a wrong or expired code looked
+  exactly the same. Two additions fix that:
+
+  - `useGameClient` returns `disconnectReason`, carrying the relay's error code
+    (`ROOM_NOT_FOUND`, `ROOM_FULL`, …) for terminal failures. Previously the
+    transport collapsed these to an unexplained close.
+  - New `useRelayRoom()` tracks the room from `?room=CODE` and lets the app set one
+    (updating the URL so reloads and shared links keep it), plus
+    `normalizeRoomCode()` and `describeRelayError()` for the entry UI.
+
+  Games stay in control of rendering; the SDK supplies the state and the wording.
+
+### Patch Changes
+
+- [#147](https://github.com/faluciano/react-native-couch-kit/pull/147) [`abf8bbe`](https://github.com/faluciano/react-native-couch-kit/commit/abf8bbe075e8f5eff00ffee7d9131009195c6a0e) Thanks [@faluciano](https://github.com/faluciano)! - Add the `RATE_LIMITED` and `SERVER_BUSY` relay error codes, which the relay has
+  sent since abuse limits landed but the client's copy of the protocol never knew
+  about — a client could receive a code its own types called impossible.
+
+  A contract test now imports both copies of the wire constants and fails if they
+  ever diverge again.
+
 ## 0.10.1
 
 ### Patch Changes

package/dist/index.js

@@ -167,7 +167,8 @@ function interpretHostMessage(msg) {
 function useGameClient(config) {
   const [status, setStatus] = useState2("disconnected");
   const [playerId, setPlayerId] = useState2(null);
-  const [state, dispatchLocal] = useReducer(createGameReducer(config.reducer), config.initialState);
+  const [disconnectReason, setDisconnectReason] = useState2(null);
+  const [state, dispatchLocal] = useReducer(createGameReducer(config.reducer ?? ((current) => current)), config.initialState);
   const socketRef = useRef2(null);
   const reconnectAttempts = useRef2(0);
   const reconnectTimer = useRef2(null);
@@ -247,8 +248,9 @@ function useGameClient(config) {
         }
       }
     };
-    transport.onclose = (code) => {
+    transport.onclose = (code, reason) => {
       setStatus("disconnected");
+      setDisconnectReason(reason ? reason : null);
       configRef.current.onDisconnect?.();
       if (!shouldReconnect({
         intentionalClose: intentionalClose.current,
@@ -311,6 +313,7 @@ function useGameClient(config) {
     status,
     state,
     playerId,
+    disconnectReason,
     sendAction,
     getServerTime,
     rtt,
@@ -335,7 +338,9 @@ var RelayErrorCodes = {
   ROOM_FULL: "ROOM_FULL",
   NOT_IN_ROOM: "NOT_IN_ROOM",
   MESSAGE_TOO_LARGE: "MESSAGE_TOO_LARGE",
-  MALFORMED: "MALFORMED"
+  MALFORMED: "MALFORMED",
+  RATE_LIMITED: "RATE_LIMITED",
+  SERVER_BUSY: "SERVER_BUSY"
 };
 function relayRoomUrl(url, roomId) {
   const trimmed = url.replace(/\/+$/, "");
@@ -351,6 +356,7 @@ class RelayClientTransport {
   roomId;
   state = TransportReadyState.CONNECTING;
   pendingCloseCode = null;
+  pendingCloseReason = null;
   onopen;
   onmessage;
   onclose;
@@ -376,7 +382,7 @@ class RelayClientTransport {
     this.ws.onclose = (event) => {
       this.state = TransportReadyState.CLOSED;
       const code = this.pendingCloseCode ?? event.code;
-      this.onclose?.(code, event.reason);
+      this.onclose?.(code, this.pendingCloseReason ?? event.reason);
     };
     this.ws.onerror = (event) => this.onerror?.(event);
   }
@@ -411,6 +417,7 @@ class RelayClientTransport {
         break;
       case RelayMessageTypes.ERROR:
         this.pendingCloseCode = POLICY_CLOSE_CODE;
+        this.pendingCloseReason = msg.code;
         this.ws.close();
         break;
     }
@@ -419,8 +426,74 @@ class RelayClientTransport {
 function createRelayTransport(options) {
   return () => new RelayClientTransport(options);
 }
+// src/relay-room.ts
+import { useCallback as useCallback3, useState as useState3 } from "react";
+var ROOM_PARAM = "room";
+function normalizeRoomCode(input) {
+  return input.replace(/[^a-zA-Z0-9]/g, "").toUpperCase();
+}
+function roomFromLocation() {
+  if (typeof window === "undefined")
+    return null;
+  try {
+    const raw = new URLSearchParams(window.location.search).get(ROOM_PARAM);
+    if (!raw)
+      return null;
+    const code = normalizeRoomCode(raw);
+    return code.length > 0 ? code : null;
+  } catch {
+    return null;
+  }
+}
+function useRelayRoom() {
+  const [roomId, setRoom] = useState3(() => roomFromLocation());
+  const syncUrl = useCallback3((code) => {
+    if (typeof window === "undefined")
+      return;
+    try {
+      const url = new URL(window.location.href);
+      if (code)
+        url.searchParams.set(ROOM_PARAM, code);
+      else
+        url.searchParams.delete(ROOM_PARAM);
+      window.history.replaceState(null, "", url.toString());
+    } catch {}
+  }, []);
+  const setRoomId = useCallback3((code) => {
+    const normalized = normalizeRoomCode(code);
+    if (normalized.length === 0)
+      return;
+    setRoom(normalized);
+    syncUrl(normalized);
+  }, [syncUrl]);
+  const clearRoomId = useCallback3(() => {
+    setRoom(null);
+    syncUrl(null);
+  }, [syncUrl]);
+  return { roomId, setRoomId, clearRoomId };
+}
+function describeRelayError(reason) {
+  switch (reason) {
+    case RelayErrorCodes.ROOM_NOT_FOUND:
+      return "That room isn't open. Check the code on the screen.";
+    case RelayErrorCodes.ROOM_FULL:
+      return "That room is full.";
+    case RelayErrorCodes.RATE_LIMITED:
+      return "Too many messages — slow down and try again.";
+    case RelayErrorCodes.ROOM_EXISTS:
+      return "That room is already hosted by another screen.";
+    case RelayErrorCodes.SERVER_BUSY:
+      return "The relay is busy. Try again in a moment.";
+    case RelayErrorCodes.MESSAGE_TOO_LARGE:
+    case RelayErrorCodes.MALFORMED:
+    case RelayErrorCodes.NOT_IN_ROOM:
+      return "The connection was rejected. Try rejoining.";
+    default:
+      return null;
+  }
+}
 // src/assets.ts
-import { useState as useState3, useEffect as useEffect3, useRef as useRef3 } from "react";
+import { useState as useState4, useEffect as useEffect3, useRef as useRef3 } from "react";
 import { MessageTypes as MessageTypes4 } from "@couch-kit/core";
 function arraysEqual(a, b) {
   if (a.length !== b.length)
@@ -432,9 +505,9 @@ function arraysEqual(a, b) {
   return true;
 }
 function usePreload(assets, sendMessage) {
-  const [loaded, setLoaded] = useState3(false);
-  const [progress, setProgress] = useState3(0);
-  const [failedAssets, setFailedAssets] = useState3([]);
+  const [loaded, setLoaded] = useState4(false);
+  const [progress, setProgress] = useState4(0);
+  const [failedAssets, setFailedAssets] = useState4([]);
   const sendMessageRef = useRef3(sendMessage);
   sendMessageRef.current = sendMessage;
   const prevAssets = useRef3(assets);
@@ -497,19 +570,19 @@ function usePreload(assets, sendMessage) {
   return { loaded, progress, failedAssets };
 }
 // src/debug-panel.ts
-import { useCallback as useCallback3, useEffect as useEffect4, useRef as useRef4, useState as useState4 } from "react";
+import { useCallback as useCallback4, useEffect as useEffect4, useRef as useRef4, useState as useState5 } from "react";
 function useDebugPanel(options) {
   const { enabled, state, status, rtt, maxEntries = 50 } = options;
   const nextIdRef = useRef4(0);
   const prevStateRef = useRef4(null);
-  const [actionLog, setActionLog] = useState4([]);
-  const [stateHistory, setStateHistory] = useState4([]);
-  const clearHistory = useCallback3(() => {
+  const [actionLog, setActionLog] = useState5([]);
+  const [stateHistory, setStateHistory] = useState5([]);
+  const clearHistory = useCallback4(() => {
     setActionLog([]);
     setStateHistory([]);
     nextIdRef.current = 0;
   }, []);
-  const logAction = useCallback3((action, source = "local") => {
+  const logAction = useCallback4((action, source = "local") => {
     if (!enabled)
       return;
     setActionLog((prev) => {
@@ -555,6 +628,7 @@ function useDebugPanel(options) {
 }
 export {
   useServerTime,
+  useRelayRoom,
   usePreload,
   useGameClient,
   useDebugPanel,
@@ -562,7 +636,9 @@ export {
   resolveWebSocketUrl,
   resolveSessionSecret,
   relayRoomUrl,
+  normalizeRoomCode,
   interpretHostMessage,
+  describeRelayError,
   createWebSocketTransport,
   createRelayTransport,
   computeBackoffDelay,

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;
@@ -46,6 +56,12 @@ export declare function useGameClient<S extends IGameState, A extends IAction>(c
     status: "connected" | "connecting" | "disconnected" | "error";
     state: S;
     playerId: string | null;
+    /**
+     * Why the last connection ended, if the transport reported a cause — for
+     * the relay, a `RelayErrorCodes` value like `ROOM_NOT_FOUND` or `ROOM_FULL`.
+     * `null` when connected or when the cause is unknown.
+     */
+    disconnectReason: string | null;
     sendAction: (action: A) => void;
     getServerTime: () => number;
     /** Round-trip time (ms) to the server. Updated periodically via PING/PONG. */

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;;;;yBA6Mc,CAAC;;IAqBvC,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/index.d.ts

@@ -3,6 +3,7 @@ export * from "./connection";
 export * from "./transport";
 export * from "./relay-protocol";
 export * from "./relay-transport";
+export * from "./relay-room";
 export * from "./time-sync";
 export * from "./assets";
 export * from "./debug-panel";

package/lib/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AACzB,cAAc,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AACzB,cAAc,eAAe,CAAC"}

package/lib/relay-protocol.d.ts

@@ -38,6 +38,10 @@ export declare const RelayErrorCodes: {
     readonly NOT_IN_ROOM: "NOT_IN_ROOM";
     readonly MESSAGE_TOO_LARGE: "MESSAGE_TOO_LARGE";
     readonly MALFORMED: "MALFORMED";
+    /** Connection exceeded the relay's per-connection message rate limit. */
+    readonly RATE_LIMITED: "RATE_LIMITED";
+    /** Relay is at its room capacity. */
+    readonly SERVER_BUSY: "SERVER_BUSY";
 };
 export type RelayErrorCode = (typeof RelayErrorCodes)[keyof typeof RelayErrorCodes];
 /** Display → relay: create and host a room. */

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/lib/relay-room.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Room-code entry for relay clients.
+ *
+ * A hosted controller has no LAN host to fall back to: opened without a room
+ * code it can only sit there failing. These helpers give it the missing state —
+ * "which room am I trying to join, and why did the last attempt fail" — so the
+ * app can ask for a code instead of hanging.
+ */
+export interface UseRelayRoomResult {
+    /** Room the client should join, or `null` when none has been chosen yet. */
+    readonly roomId: string | null;
+    /** Choose a room. Canonicalised, and reflected in the URL so reloads keep it. */
+    readonly setRoomId: (code: string) => void;
+    /** Forget the current room and return to the entry screen. */
+    readonly clearRoomId: () => void;
+}
+/**
+ * Canonical room code: upper-cased and stripped of spacing or punctuation that
+ * people add when copying a code off a TV ("ab 12" and "AB-12" are `AB12`).
+ */
+export declare function normalizeRoomCode(input: string): string;
+/**
+ * Tracks which room this client is joining, seeded from `?room=CODE`.
+ *
+ * Scanning a QR fills it in; typing a code sets it and updates the URL, so a
+ * reload — or a shared link — lands in the same room.
+ */
+export declare function useRelayRoom(): UseRelayRoomResult;
+/**
+ * Human-readable explanation for a relay failure, or `null` if the reason is
+ * unknown (an ordinary network drop, say, which the client will retry).
+ *
+ * Pass `disconnectReason` from `useGameClient`.
+ */
+export declare function describeRelayError(reason: string | null): string | null;
+//# sourceMappingURL=relay-room.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"relay-room.d.ts","sourceRoot":"","sources":["../src/relay-room.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAQH,MAAM,WAAW,kBAAkB;IACjC,4EAA4E;IAC5E,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,iFAAiF;IACjF,QAAQ,CAAC,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3C,8DAA8D;IAC9D,QAAQ,CAAC,WAAW,EAAE,MAAM,IAAI,CAAC;CAClC;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEvD;AAcD;;;;;GAKG;AACH,wBAAgB,YAAY,IAAI,kBAAkB,CA+BjD;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAmBvE"}

package/lib/relay-transport.d.ts

@@ -22,6 +22,12 @@ export declare class RelayClientTransport implements ClientTransport {
     private state;
     /** When set, the code reported to `onclose` instead of the raw socket code. */
     private pendingCloseCode;
+    /**
+     * Relay error code (e.g. `ROOM_NOT_FOUND`) behind a terminal close, reported
+     * as the close `reason` so the UI can say what actually went wrong instead of
+     * showing an indefinite "connecting".
+     */
+    private pendingCloseReason;
     onopen?: () => void;
     onmessage?: (data: string) => void;
     onclose?: (code: number, reason?: string) => void;

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

@@ -1 +1 @@
-{"version":3,"file":"relay-transport.d.ts","sourceRoot":"","sources":["../src/relay-transport.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAC3B,MAAM,aAAa,CAAC;AAOrB,+EAA+E;AAC/E,MAAM,WAAW,qBAAqB;IACpC,0EAA0E;IAC1E,GAAG,EAAE,MAAM,CAAC;IACZ,4DAA4D;IAC5D,MAAM,EAAE,MAAM,CAAC;CAChB;AASD;;;;;;;;;GASG;AACH,qBAAa,oBAAqB,YAAW,eAAe;IAC1D,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAY;IAC/B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,KAAK,CAA0C;IACvD,+EAA+E;IAC/E,OAAO,CAAC,gBAAgB,CAAuB;IAE/C,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;IACpB,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACnC,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IAClD,OAAO,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IAEpC,YAAY,OAAO,EAAE,qBAAqB,EAgCzC;IAED,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CASvB;IAED,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAQ1C;IAED,OAAO,CAAC,kBAAkB;CAkB3B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,qBAAqB,GAC7B,qBAAqB,CAEvB"}
+{"version":3,"file":"relay-transport.d.ts","sourceRoot":"","sources":["../src/relay-transport.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAC3B,MAAM,aAAa,CAAC;AAOrB,+EAA+E;AAC/E,MAAM,WAAW,qBAAqB;IACpC,0EAA0E;IAC1E,GAAG,EAAE,MAAM,CAAC;IACZ,4DAA4D;IAC5D,MAAM,EAAE,MAAM,CAAC;CAChB;AASD;;;;;;;;;GASG;AACH,qBAAa,oBAAqB,YAAW,eAAe;IAC1D,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAY;IAC/B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,KAAK,CAA0C;IACvD,+EAA+E;IAC/E,OAAO,CAAC,gBAAgB,CAAuB;IAC/C;;;;OAIG;IACH,OAAO,CAAC,kBAAkB,CAAuB;IAEjD,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;IACpB,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACnC,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IAClD,OAAO,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IAEpC,YAAY,OAAO,EAAE,qBAAqB,EAgCzC;IAED,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CASvB;IAED,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAQ1C;IAED,OAAO,CAAC,kBAAkB;CAqB3B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,qBAAqB,GAC7B,qBAAqB,CAEvB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@couch-kit/client",
-  "version": "0.10.1",
+  "version": "0.12.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}")
@@ -76,11 +86,18 @@ export function useGameClient<S extends IGameState, A extends IAction>(
     "connecting" | "connected" | "disconnected" | "error"
   >("disconnected");
   const [playerId, setPlayerId] = useState<string | null>(null);
+  /**
+   * Why the last connection ended, when the transport knows. For the relay this
+   * is a {@link RelayErrorCodes} value such as `ROOM_NOT_FOUND`.
+   */
+  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,
   );
 
@@ -195,8 +212,12 @@ export function useGameClient<S extends IGameState, A extends IAction>(
       }
     };
 
-    transport.onclose = (code) => {
+    transport.onclose = (code, reason) => {
       setStatus("disconnected");
+      // Terminal room-level failures carry a relay error code (ROOM_NOT_FOUND,
+      // ROOM_FULL, …). Surfacing it lets the UI explain the failure rather than
+      // sit on "connecting" forever.
+      setDisconnectReason(reason ? reason : null);
       configRef.current.onDisconnect?.();
 
       // Don't reconnect if the close was intentional or if the server
@@ -294,6 +315,12 @@ export function useGameClient<S extends IGameState, A extends IAction>(
     status,
     state,
     playerId,
+    /**
+     * Why the last connection ended, if the transport reported a cause — for
+     * the relay, a `RelayErrorCodes` value like `ROOM_NOT_FOUND` or `ROOM_FULL`.
+     * `null` when connected or when the cause is unknown.
+     */
+    disconnectReason,
     sendAction,
     getServerTime,
     /** Round-trip time (ms) to the server. Updated periodically via PING/PONG. */

package/src/index.ts

@@ -3,6 +3,7 @@ export * from "./connection";
 export * from "./transport";
 export * from "./relay-protocol";
 export * from "./relay-transport";
+export * from "./relay-room";
 export * from "./time-sync";
 export * from "./assets";
 export * from "./debug-panel";

package/src/relay-protocol.ts

@@ -40,6 +40,10 @@ export const RelayErrorCodes = {
   NOT_IN_ROOM: "NOT_IN_ROOM",
   MESSAGE_TOO_LARGE: "MESSAGE_TOO_LARGE",
   MALFORMED: "MALFORMED",
+  /** Connection exceeded the relay's per-connection message rate limit. */
+  RATE_LIMITED: "RATE_LIMITED",
+  /** Relay is at its room capacity. */
+  SERVER_BUSY: "SERVER_BUSY",
 } as const;
 
 export type RelayErrorCode =

package/src/relay-room.ts

@@ -0,0 +1,109 @@
+/**
+ * Room-code entry for relay clients.
+ *
+ * A hosted controller has no LAN host to fall back to: opened without a room
+ * code it can only sit there failing. These helpers give it the missing state —
+ * "which room am I trying to join, and why did the last attempt fail" — so the
+ * app can ask for a code instead of hanging.
+ */
+
+import { useCallback, useState } from "react";
+import { RelayErrorCodes } from "./relay-protocol";
+
+/** Query parameter carrying the room code, as produced by display QR codes. */
+const ROOM_PARAM = "room";
+
+export interface UseRelayRoomResult {
+  /** Room the client should join, or `null` when none has been chosen yet. */
+  readonly roomId: string | null;
+  /** Choose a room. Canonicalised, and reflected in the URL so reloads keep it. */
+  readonly setRoomId: (code: string) => void;
+  /** Forget the current room and return to the entry screen. */
+  readonly clearRoomId: () => void;
+}
+
+/**
+ * Canonical room code: upper-cased and stripped of spacing or punctuation that
+ * people add when copying a code off a TV ("ab 12" and "AB-12" are `AB12`).
+ */
+export function normalizeRoomCode(input: string): string {
+  return input.replace(/[^a-zA-Z0-9]/g, "").toUpperCase();
+}
+
+function roomFromLocation(): string | null {
+  if (typeof window === "undefined") return null;
+  try {
+    const raw = new URLSearchParams(window.location.search).get(ROOM_PARAM);
+    if (!raw) return null;
+    const code = normalizeRoomCode(raw);
+    return code.length > 0 ? code : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Tracks which room this client is joining, seeded from `?room=CODE`.
+ *
+ * Scanning a QR fills it in; typing a code sets it and updates the URL, so a
+ * reload — or a shared link — lands in the same room.
+ */
+export function useRelayRoom(): UseRelayRoomResult {
+  const [roomId, setRoom] = useState<string | null>(() => roomFromLocation());
+
+  const syncUrl = useCallback((code: string | null): void => {
+    if (typeof window === "undefined") return;
+    try {
+      const url = new URL(window.location.href);
+      if (code) url.searchParams.set(ROOM_PARAM, code);
+      else url.searchParams.delete(ROOM_PARAM);
+      window.history.replaceState(null, "", url.toString());
+    } catch {
+      // A URL we cannot rewrite is not worth failing the join over.
+    }
+  }, []);
+
+  const setRoomId = useCallback(
+    (code: string): void => {
+      const normalized = normalizeRoomCode(code);
+      if (normalized.length === 0) return;
+      setRoom(normalized);
+      syncUrl(normalized);
+    },
+    [syncUrl],
+  );
+
+  const clearRoomId = useCallback((): void => {
+    setRoom(null);
+    syncUrl(null);
+  }, [syncUrl]);
+
+  return { roomId, setRoomId, clearRoomId };
+}
+
+/**
+ * Human-readable explanation for a relay failure, or `null` if the reason is
+ * unknown (an ordinary network drop, say, which the client will retry).
+ *
+ * Pass `disconnectReason` from `useGameClient`.
+ */
+export function describeRelayError(reason: string | null): string | null {
+  switch (reason) {
+    case RelayErrorCodes.ROOM_NOT_FOUND:
+      return "That room isn't open. Check the code on the screen.";
+    case RelayErrorCodes.ROOM_FULL:
+      return "That room is full.";
+    case RelayErrorCodes.RATE_LIMITED:
+      return "Too many messages — slow down and try again.";
+    case RelayErrorCodes.ROOM_EXISTS:
+      return "That room is already hosted by another screen.";
+    case RelayErrorCodes.SERVER_BUSY:
+      return "The relay is busy. Try again in a moment.";
+    case RelayErrorCodes.MESSAGE_TOO_LARGE:
+    case RelayErrorCodes.MALFORMED:
+    case RelayErrorCodes.NOT_IN_ROOM:
+      return "The connection was rejected. Try rejoining.";
+    default:
+      return null;
+  }
+}

package/src/relay-transport.ts

@@ -40,6 +40,12 @@ export class RelayClientTransport implements ClientTransport {
   private state: number = TransportReadyState.CONNECTING;
   /** When set, the code reported to `onclose` instead of the raw socket code. */
   private pendingCloseCode: number | null = null;
+  /**
+   * Relay error code (e.g. `ROOM_NOT_FOUND`) behind a terminal close, reported
+   * as the close `reason` so the UI can say what actually went wrong instead of
+   * showing an indefinite "connecting".
+   */
+  private pendingCloseReason: string | null = null;
 
   onopen?: () => void;
   onmessage?: (data: string) => void;
@@ -74,7 +80,7 @@ export class RelayClientTransport implements ClientTransport {
     this.ws.onclose = (event: CloseEvent) => {
       this.state = TransportReadyState.CLOSED;
       const code = this.pendingCloseCode ?? event.code;
-      this.onclose?.(code, event.reason);
+      this.onclose?.(code, this.pendingCloseReason ?? event.reason);
     };
 
     this.ws.onerror = (event) => this.onerror?.(event);
@@ -116,8 +122,11 @@ export class RelayClientTransport implements ClientTransport {
         break;
       case RelayMessageTypes.ERROR:
         // Room-level failures are terminal: report a policy close so the client
-        // does not attempt to reconnect, then close the underlying socket.
+        // does not attempt to reconnect, then close the underlying socket. The
+        // relay's code travels along as the reason — "ROOM_NOT_FOUND" is
+        // actionable ("check the code"), a silent hang is not.
         this.pendingCloseCode = POLICY_CLOSE_CODE;
+        this.pendingCloseReason = msg.code;
         this.ws.close();
         break;
       // PEER_JOINED / PEER_LEFT / ROOM_CREATED are host-facing; ignored here.