@couch-kit/display 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,58 @@
 # @couch-kit/display
 
+## 0.5.0
+
+### Minor Changes
+
+- [#206](https://github.com/faluciano/react-native-couch-kit/pull/206) [`a438965`](https://github.com/faluciano/react-native-couch-kit/commit/a43896586f43a2f7e4811fb9c4394a25b1018d69) Thanks [@faluciano](https://github.com/faluciano)! - Make `RelayDisplayHost` aware of its relay connection.
+
+  - New `status` (`connecting` → `open` → `closed`) and `onStatusChange` option. When the relay connection drops, every player is marked disconnected, the status becomes `closed`, and the loss is reported through `onError` — previously the display kept running with no sign that the room was gone.
+  - Nothing is written to a socket that is not open. A display that dispatched before the socket opened threw from the broadcast timer.
+  - Room broadcasts are skipped while no phone is in the room, saving a billed relay message per state change in an empty lobby.
+  - `stateThrottleMs` defaults to 50ms here (`DEFAULT_RELAY_STATE_THROTTLE_MS`) so a continuously updating game stays inside the relay's 30 messages/second limit, which closes the display's socket when exceeded.
+  - Relay errors reach `onError` as `RelayError` with the relay's `code`.
+
+### Patch Changes
+
+- Updated dependencies [[`ddec122`](https://github.com/faluciano/react-native-couch-kit/commit/ddec122d9e415c54f157d6998c2b719ab31586b3), [`9465677`](https://github.com/faluciano/react-native-couch-kit/commit/9465677b63ad58273b8c0dee98ebece5d477a074)]:
+  - @couch-kit/client@0.15.0
+  - @couch-kit/runtime@0.4.0
+
+## 0.4.0
+
+### Minor Changes
+
+- [#164](https://github.com/faluciano/react-native-couch-kit/pull/164) [`a157126`](https://github.com/faluciano/react-native-couch-kit/commit/a157126424e4d73dcc7185118d5be0db6719792e) Thanks [@faluciano](https://github.com/faluciano)! - Send a projected state update as one relay frame instead of one per player
+
+  A game with a `project` function sends every player their own view, which meant
+  one WebSocket frame per player for every state change. Relays bill and
+  rate-limit per inbound frame, so a four-player table paid four messages for one
+  update and spent four of the display's 30-per-second budget.
+
+  `GameRuntimeTransport` gains an optional `sendMany(entries)`. When a transport
+  implements it, the runtime hands over the whole projected batch at once;
+  transports that do not — the LAN WebSocket path — keep receiving one `send` per
+  connection and are unaffected.
+
+  `RelayDisplayHost` implements it with a new `DATA_MULTI` envelope carrying a
+  peer-id-to-payload map, which the relay unpacks into ordinary `DATA` frames.
+  Phones need no update — nothing on the client side can tell a batched update
+  from a unicast one. If the combined frame would exceed the relay's 256KB
+  ceiling, the display falls back to individual frames rather than send something
+  the relay would drop.
+
+  Relays must be updated before displays: both bundled implementations
+  (`services/relay`, `services/relay-worker`) understand `DATA_MULTI`, and an
+  older relay answers it with `MALFORMED`. The type is host-only — a phone sending
+  it is rejected, so it cannot be used to reach another phone directly.
+
+### Patch Changes
+
+- Updated dependencies [[`a157126`](https://github.com/faluciano/react-native-couch-kit/commit/a157126424e4d73dcc7185118d5be0db6719792e), [`a157126`](https://github.com/faluciano/react-native-couch-kit/commit/a157126424e4d73dcc7185118d5be0db6719792e)]:
+  - @couch-kit/runtime@0.3.0
+  - @couch-kit/client@0.14.0
+  - @couch-kit/core@0.10.0
+
 ## 0.3.0
 
 ### Minor Changes

package/README.md

@@ -69,13 +69,34 @@ plus the relay coordinates:
 | `reducer`   | The shared game reducer                        |
 | `initialState` | The shared initial state                    |
 
-Instance methods:
+| `onStatusChange` | Called when the relay connection changes: `connecting` → `open` → `closed` |
+| `onError`   | Receives runtime and relay errors; relay errors are `RelayError` with a `code` |
+| `stateThrottleMs` | Minimum interval between state broadcasts. Defaults to 50ms here (not the LAN default of 33ms) so a continuously updating game stays inside the relay's per-connection rate limit |
+
+Instance members:
 
 - `getState()` — current authoritative state.
 - `subscribe(listener)` — subscribe to state changes; returns an unsubscribe fn.
 - `dispatch(action)` — dispatch a trusted host-side action.
+- `status` — `connecting` until the relay confirms the room, then `open`;
+  `closed` once the relay connection is gone.
 - `stop()` — tear down the runtime and close the relay socket.
 
+### When the relay connection drops
+
+A relay room lives exactly as long as its display's socket. If that socket
+closes — the tab loses its network, the relay restarts — the relay closes every
+phone in the room, and the display host:
+
+- marks every player `connected: false` in the game state,
+- moves to `status: "closed"` and calls `onStatusChange("closed")`,
+- reports the loss through `onError`.
+
+It does not reconnect: a new connection is a new room with a new code. The game
+state stays readable, so the display can show what happened rather than a board
+that silently stopped updating. Phones see `disconnectReason: "HOST_LEFT"`,
+which `describeRelayError` turns into a message for the join screen.
+
 The host maps relay `PEER_JOINED` / `DATA` / `PEER_LEFT` to the runtime's
 `handleConnection` / `handleMessage` / `handleDisconnect`, and implements the
 runtime's transport by wrapping outbound messages in relay `DATA` envelopes

package/dist/index.js

@@ -8,20 +8,39 @@ import {
   RelayMessageTypes,
   relayRoomUrl
 } from "@couch-kit/client";
+var DEFAULT_RELAY_STATE_THROTTLE_MS = 50;
+
+class RelayError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "RelayError";
+    this.code = code;
+  }
+}
 
 class RelayDisplayHost {
   runtime;
   ws;
   assignedRoomId;
   onRoomCode;
+  onStatusChange;
   peers = new Set;
+  currentStatus = "connecting";
+  socketOpen = false;
+  stopped = false;
   constructor(options) {
-    const { url, roomId, onRoomCode, ...runtimeConfig } = options;
+    const { url, roomId, onRoomCode, onStatusChange, ...runtimeConfig } = options;
     this.assignedRoomId = roomId ?? null;
     this.onRoomCode = onRoomCode;
-    this.runtime = new GameHostRuntime(runtimeConfig);
+    this.onStatusChange = onStatusChange;
+    this.runtime = new GameHostRuntime({
+      ...runtimeConfig,
+      stateThrottleMs: runtimeConfig.stateThrottleMs ?? DEFAULT_RELAY_STATE_THROTTLE_MS
+    });
     this.ws = new WebSocket(relayRoomUrl(url, roomId));
     this.ws.onopen = () => {
+      this.socketOpen = true;
       this.ws.send(JSON.stringify({
         type: RelayMessageTypes.CREATE_ROOM,
         roomId: this.assignedRoomId ?? undefined
@@ -37,24 +56,74 @@ class RelayDisplayHost {
       this.handleRelayMessage(msg);
     };
     this.ws.onerror = (event) => this.runtime.handleError(event instanceof Error ? event : new Error("Relay socket error"));
+    this.ws.onclose = (event) => this.handleSocketClose(event);
     const transport = {
       send: (connectionId, message) => this.sendEnvelope(message, connectionId),
-      broadcast: (message) => this.sendEnvelope(message)
+      broadcast: (message) => this.sendEnvelope(message),
+      sendMany: (entries) => this.sendMultiEnvelope(entries)
     };
     this.runtime.setTransport(transport);
   }
   get roomCode() {
     return this.assignedRoomId;
   }
+  get status() {
+    return this.currentStatus;
+  }
   getState = () => this.runtime.getState();
   subscribe = (listener) => this.runtime.subscribe(listener);
   dispatch = (action) => this.runtime.dispatch(action);
   stop() {
+    this.stopped = true;
+    this.socketOpen = false;
+    this.peers.clear();
     this.runtime.setTransport(null);
     this.runtime.stop();
     this.ws.close();
+    this.setStatus("closed");
+  }
+  setStatus(status) {
+    if (this.currentStatus === status)
+      return;
+    this.currentStatus = status;
+    this.onStatusChange?.(status);
+  }
+  handleSocketClose(event) {
+    this.socketOpen = false;
+    if (this.stopped)
+      return;
+    for (const peerId of this.peers) {
+      this.runtime.handleDisconnect(peerId);
+    }
+    this.peers.clear();
+    this.setStatus("closed");
+    this.runtime.handleError(new Error(`Relay connection closed (code ${event?.code ?? "unknown"})` + (event?.reason ? `: ${event.reason}` : "")));
+  }
+  sendMultiEnvelope(entries) {
+    if (!this.socketOpen)
+      return;
+    const payloads = {};
+    for (const { connectionId, message } of entries) {
+      payloads[connectionId] = JSON.stringify(message);
+    }
+    const frame = JSON.stringify({
+      type: RelayMessageTypes.DATA_MULTI,
+      roomId: this.assignedRoomId ?? undefined,
+      payloads
+    });
+    if (frameByteLength(frame) > DEFAULT_MAX_MESSAGE_BYTES) {
+      for (const { connectionId, message } of entries) {
+        this.sendEnvelope(message, connectionId);
+      }
+      return;
+    }
+    this.ws.send(frame);
   }
   sendEnvelope(message, to) {
+    if (!this.socketOpen)
+      return;
+    if (to === undefined && this.peers.size === 0)
+      return;
     const envelope = {
       type: RelayMessageTypes.DATA,
       roomId: this.assignedRoomId ?? undefined,
@@ -90,14 +159,17 @@ class RelayDisplayHost {
       }
       case RelayMessageTypes.ROOM_CREATED:
         this.assignedRoomId = msg.roomId;
+        this.setStatus("open");
         this.onRoomCode?.(msg.roomId);
         break;
       case RelayMessageTypes.ERROR:
-        this.runtime.handleError(new Error(msg.message));
+        this.runtime.handleError(new RelayError(msg.code, msg.message));
         break;
     }
   }
 }
 export {
-  RelayDisplayHost
+  DEFAULT_RELAY_STATE_THROTTLE_MS,
+  RelayDisplayHost,
+  RelayError
 };

package/lib/relay-display-host.d.ts

@@ -1,5 +1,32 @@
 import { type GameHostRuntimeConfig } from "@couch-kit/runtime";
 import type { IGameState, IAction } from "@couch-kit/core";
+import { type RelayErrorCode } from "@couch-kit/client";
+/**
+ * Default minimum interval (ms) between state broadcasts through a relay.
+ *
+ * Slower than the LAN default on purpose: a relay rate-limits every connection
+ * (30 messages/second on the reference relays) and answers a breach by closing
+ * the socket — which, for the display, ends the room. 20 broadcasts/second
+ * leaves headroom for the unicast traffic the display also sends (WELCOME,
+ * PONG, errors), so a game that updates continuously cannot talk itself out of
+ * its own room.
+ */
+export declare const DEFAULT_RELAY_STATE_THROTTLE_MS = 50;
+/**
+ * Where the display's relay connection stands.
+ *
+ * - `connecting` — socket opening, or open but the room not yet confirmed.
+ * - `open` — the room exists and phones can join.
+ * - `closed` — the relay connection is gone, and the room with it. Terminal:
+ *   the game state is still readable, but a new {@link RelayDisplayHost} (and a
+ *   new room code) is needed for phones to rejoin.
+ */
+export type RelayDisplayStatus = "connecting" | "open" | "closed";
+/** An error reported by the relay, carrying its machine-readable code. */
+export declare class RelayError extends Error {
+    readonly code: RelayErrorCode;
+    constructor(code: RelayErrorCode, message: string);
+}
 /**
  * Options for {@link RelayDisplayHost}.
  *
@@ -27,6 +54,12 @@ export interface RelayDisplayHostOptions<S extends IGameState, A extends IAction
      * placeholder until this fires — roughly a round trip to the relay.
      */
     onRoomCode?: (roomCode: string) => void;
+    /**
+     * Called whenever {@link RelayDisplayHost.status} changes. `closed` is the
+     * one worth acting on: the room is gone, so show the players something
+     * rather than a board that will never update again.
+     */
+    onStatusChange?: (status: RelayDisplayStatus) => void;
 }
 /**
  * Browser **display host** for the cross-network relay transport.
@@ -51,8 +84,13 @@ export declare class RelayDisplayHost<S extends IGameState, A extends IAction> {
     /** Null until the relay confirms the room, when the code is relay-assigned. */
     private assignedRoomId;
     private readonly onRoomCode?;
+    private readonly onStatusChange?;
     /** Connected phone connection ids (relay peer ids). */
     private readonly peers;
+    private currentStatus;
+    /** Whether frames can be written; a socket still connecting throws on send. */
+    private socketOpen;
+    private stopped;
     constructor(options: RelayDisplayHostOptions<S, A>);
     /**
      * The room code phones join with, or `null` before the relay has assigned
@@ -60,6 +98,8 @@ export declare class RelayDisplayHost<S extends IGameState, A extends IAction> {
      * arrives.
      */
     get roomCode(): string | null;
+    /** Where the relay connection stands. See {@link RelayDisplayStatus}. */
+    get status(): RelayDisplayStatus;
     /** Current authoritative game state. */
     getState: () => S;
     /** Subscribe to state changes (for `useSyncExternalStore` or manual render). */
@@ -68,6 +108,28 @@ export declare class RelayDisplayHost<S extends IGameState, A extends IAction> {
     dispatch: (action: A) => void;
     /** Tear down the runtime and relay socket. */
     stop(): void;
+    private setStatus;
+    /**
+     * The relay connection ended. The relay drops the room with its host, so
+     * every phone is gone too: mark them disconnected so the state on screen
+     * says so, and report the loss unless this was our own {@link stop}.
+     */
+    private handleSocketClose;
+    /**
+     * Sends per-connection messages as one `DATA_MULTI` frame, which the relay
+     * unpacks into an ordinary `DATA` frame per phone.
+     *
+     * A projected game re-sends every player's view on every state change, so on
+     * a four-player table this is the difference between one billed relay message
+     * and four — and between one and four against the relay's per-connection rate
+     * limit, which the display shares across all its fan-out.
+     *
+     * Falls back to individual sends if the combined frame would exceed the
+     * relay's message ceiling: N views in one envelope is N times the bytes, and
+     * a frame the relay rejects delivers nothing to anyone. Splitting costs
+     * messages; being dropped costs the game.
+     */
+    private sendMultiEnvelope;
     private sendEnvelope;
     private handleRelayMessage;
 }

package/lib/relay-display-host.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"relay-display-host.d.ts","sourceRoot":"","sources":["../src/relay-display-host.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,qBAAqB,EAE3B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,UAAU,EAAE,OAAO,EAAe,MAAM,iBAAiB,CAAC;AAOxE;;;;;;GAMG;AACH,MAAM,WAAW,uBAAuB,CAAC,CAAC,SAAS,UAAU,EAAE,CAAC,SAAS,OAAO,CAC9E,SAAQ,qBAAqB,CAAC,CAAC,EAAE,CAAC,CAAC;IACnC,gDAAgD;IAChD,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;CACzC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,gBAAgB,CAAC,CAAC,SAAS,UAAU,EAAE,CAAC,SAAS,OAAO;IACnE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwB;IAChD,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAY;IAC/B,+EAA+E;IAC/E,OAAO,CAAC,cAAc,CAAgB;IACtC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAA6B;IACzD,uDAAuD;IACvD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAqB;IAE3C,YAAY,OAAO,EAAE,uBAAuB,CAAC,CAAC,EAAE,CAAC,CAAC,EAwCjD;IAED;;;;OAIG;IACH,IAAI,QAAQ,IAAI,MAAM,GAAG,IAAI,CAE5B;IAED,wCAAwC;IACxC,QAAQ,QAAO,CAAC,CAA4B;IAE5C,gFAAgF;IAChF,SAAS,aAAc,MAAM,IAAI,KAAG,CAAC,MAAM,IAAI,CAAC,CACb;IAEnC,8CAA8C;IAC9C,QAAQ,WAAY,CAAC,KAAG,IAAI,CAAkC;IAE9D,8CAA8C;IAC9C,IAAI,IAAI,IAAI,CAIX;IAED,OAAO,CAAC,YAAY;IAapB,OAAO,CAAC,kBAAkB;CA2C3B"}
+{"version":3,"file":"relay-display-host.d.ts","sourceRoot":"","sources":["../src/relay-display-host.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,KAAK,qBAAqB,EAE3B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,UAAU,EAAE,OAAO,EAAe,MAAM,iBAAiB,CAAC;AACxE,OAAO,EAGL,KAAK,cAAc,EAEpB,MAAM,mBAAmB,CAAC;AAE3B;;;;;;;;;GASG;AACH,eAAO,MAAM,+BAA+B,KAAK,CAAC;AAElD;;;;;;;;GAQG;AACH,MAAM,MAAM,kBAAkB,GAAG,YAAY,GAAG,MAAM,GAAG,QAAQ,CAAC;AAElE,0EAA0E;AAC1E,qBAAa,UAAW,SAAQ,KAAK;IACnC,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAE9B,YAAY,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,EAIhD;CACF;AAED;;;;;;GAMG;AACH,MAAM,WAAW,uBAAuB,CACtC,CAAC,SAAS,UAAU,EACpB,CAAC,SAAS,OAAO,CACjB,SAAQ,qBAAqB,CAAC,CAAC,EAAE,CAAC,CAAC;IACnC,gDAAgD;IAChD,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC;;;;OAIG;IACH,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,kBAAkB,KAAK,IAAI,CAAC;CACvD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,gBAAgB,CAAC,CAAC,SAAS,UAAU,EAAE,CAAC,SAAS,OAAO;IACnE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwB;IAChD,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAY;IAC/B,+EAA+E;IAC/E,OAAO,CAAC,cAAc,CAAgB;IACtC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAA6B;IACzD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAuC;IACvE,uDAAuD;IACvD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAqB;IAC3C,OAAO,CAAC,aAAa,CAAoC;IACzD,+EAA+E;IAC/E,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,OAAO,CAAS;IAExB,YAAY,OAAO,EAAE,uBAAuB,CAAC,CAAC,EAAE,CAAC,CAAC,EAiDjD;IAED;;;;OAIG;IACH,IAAI,QAAQ,IAAI,MAAM,GAAG,IAAI,CAE5B;IAED,yEAAyE;IACzE,IAAI,MAAM,IAAI,kBAAkB,CAE/B;IAED,wCAAwC;IACxC,QAAQ,QAAO,CAAC,CAA4B;IAE5C,gFAAgF;IAChF,SAAS,aAAc,MAAM,IAAI,KAAG,CAAC,MAAM,IAAI,CAAC,CACb;IAEnC,8CAA8C;IAC9C,QAAQ,WAAY,CAAC,KAAG,IAAI,CAAkC;IAE9D,8CAA8C;IAC9C,IAAI,IAAI,IAAI,CAQX;IAED,OAAO,CAAC,SAAS;IAMjB;;;;OAIG;IACH,OAAO,CAAC,iBAAiB;IAiBzB;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,iBAAiB;IAwBzB,OAAO,CAAC,YAAY;IAqBpB,OAAO,CAAC,kBAAkB;CA4C3B"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@couch-kit/display",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "publishConfig": {
     "access": "public",
     "provenance": true
@@ -51,9 +51,9 @@
     "clean": "rm -rf dist lib"
   },
   "dependencies": {
-    "@couch-kit/client": "0.13.0",
-    "@couch-kit/core": "0.9.3",
-    "@couch-kit/runtime": "0.2.0"
+    "@couch-kit/client": "0.15.0",
+    "@couch-kit/core": "0.10.0",
+    "@couch-kit/runtime": "0.4.0"
   },
   "devDependencies": {
     "typescript": "^7.0.0"

package/src/relay-display-host.ts

@@ -2,6 +2,7 @@ import {
   GameHostRuntime,
   frameByteLength,
   DEFAULT_MAX_MESSAGE_BYTES,
+  type AddressedMessage,
   type GameHostRuntimeConfig,
   type GameRuntimeTransport,
 } from "@couch-kit/runtime";
@@ -9,9 +10,44 @@ import type { IGameState, IAction, HostMessage } from "@couch-kit/core";
 import {
   RelayMessageTypes,
   relayRoomUrl,
+  type RelayErrorCode,
   type RelayServerMessage,
 } from "@couch-kit/client";
 
+/**
+ * Default minimum interval (ms) between state broadcasts through a relay.
+ *
+ * Slower than the LAN default on purpose: a relay rate-limits every connection
+ * (30 messages/second on the reference relays) and answers a breach by closing
+ * the socket — which, for the display, ends the room. 20 broadcasts/second
+ * leaves headroom for the unicast traffic the display also sends (WELCOME,
+ * PONG, errors), so a game that updates continuously cannot talk itself out of
+ * its own room.
+ */
+export const DEFAULT_RELAY_STATE_THROTTLE_MS = 50;
+
+/**
+ * Where the display's relay connection stands.
+ *
+ * - `connecting` — socket opening, or open but the room not yet confirmed.
+ * - `open` — the room exists and phones can join.
+ * - `closed` — the relay connection is gone, and the room with it. Terminal:
+ *   the game state is still readable, but a new {@link RelayDisplayHost} (and a
+ *   new room code) is needed for phones to rejoin.
+ */
+export type RelayDisplayStatus = "connecting" | "open" | "closed";
+
+/** An error reported by the relay, carrying its machine-readable code. */
+export class RelayError extends Error {
+  readonly code: RelayErrorCode;
+
+  constructor(code: RelayErrorCode, message: string) {
+    super(message);
+    this.name = "RelayError";
+    this.code = code;
+  }
+}
+
 /**
  * Options for {@link RelayDisplayHost}.
  *
@@ -19,8 +55,10 @@ import {
  * object used by the RN-TV host) and the shared relay coordinates; the display
  * host owns the authoritative runtime and the relay socket.
  */
-export interface RelayDisplayHostOptions<S extends IGameState, A extends IAction>
-  extends GameHostRuntimeConfig<S, A> {
+export interface RelayDisplayHostOptions<
+  S extends IGameState,
+  A extends IAction,
+> extends GameHostRuntimeConfig<S, A> {
   /** WebSocket URL of the shared relay server. */
   url: string;
   /**
@@ -40,6 +78,12 @@ export interface RelayDisplayHostOptions<S extends IGameState, A extends IAction
    * placeholder until this fires — roughly a round trip to the relay.
    */
   onRoomCode?: (roomCode: string) => void;
+  /**
+   * Called whenever {@link RelayDisplayHost.status} changes. `closed` is the
+   * one worth acting on: the room is gone, so show the players something
+   * rather than a board that will never update again.
+   */
+  onStatusChange?: (status: RelayDisplayStatus) => void;
 }
 
 /**
@@ -65,17 +109,29 @@ export class RelayDisplayHost<S extends IGameState, A extends IAction> {
   /** Null until the relay confirms the room, when the code is relay-assigned. */
   private assignedRoomId: string | null;
   private readonly onRoomCode?: (roomCode: string) => void;
+  private readonly onStatusChange?: (status: RelayDisplayStatus) => void;
   /** Connected phone connection ids (relay peer ids). */
   private readonly peers = new Set<string>();
+  private currentStatus: RelayDisplayStatus = "connecting";
+  /** Whether frames can be written; a socket still connecting throws on send. */
+  private socketOpen = false;
+  private stopped = false;
 
   constructor(options: RelayDisplayHostOptions<S, A>) {
-    const { url, roomId, onRoomCode, ...runtimeConfig } = options;
+    const { url, roomId, onRoomCode, onStatusChange, ...runtimeConfig } =
+      options;
     this.assignedRoomId = roomId ?? null;
     this.onRoomCode = onRoomCode;
-    this.runtime = new GameHostRuntime<S, A>(runtimeConfig);
+    this.onStatusChange = onStatusChange;
+    this.runtime = new GameHostRuntime<S, A>({
+      ...runtimeConfig,
+      stateThrottleMs:
+        runtimeConfig.stateThrottleMs ?? DEFAULT_RELAY_STATE_THROTTLE_MS,
+    });
     this.ws = new WebSocket(relayRoomUrl(url, roomId));
 
     this.ws.onopen = () => {
+      this.socketOpen = true;
       // No roomId asks the relay to allocate one. Sending the field as
       // undefined omits it from the JSON, which is what the relay reads as
       // "you pick".
@@ -102,10 +158,12 @@ export class RelayDisplayHost<S extends IGameState, A extends IAction> {
         event instanceof Error ? event : new Error("Relay socket error"),
       );
 
+    this.ws.onclose = (event: CloseEvent) => this.handleSocketClose(event);
+
     const transport: GameRuntimeTransport = {
-      send: (connectionId, message) =>
-        this.sendEnvelope(message, connectionId),
+      send: (connectionId, message) => this.sendEnvelope(message, connectionId),
       broadcast: (message) => this.sendEnvelope(message),
+      sendMany: (entries) => this.sendMultiEnvelope(entries),
     };
     this.runtime.setTransport(transport);
   }
@@ -119,6 +177,11 @@ export class RelayDisplayHost<S extends IGameState, A extends IAction> {
     return this.assignedRoomId;
   }
 
+  /** Where the relay connection stands. See {@link RelayDisplayStatus}. */
+  get status(): RelayDisplayStatus {
+    return this.currentStatus;
+  }
+
   /** Current authoritative game state. */
   getState = (): S => this.runtime.getState();
 
@@ -131,12 +194,90 @@ export class RelayDisplayHost<S extends IGameState, A extends IAction> {
 
   /** Tear down the runtime and relay socket. */
   stop(): void {
+    this.stopped = true;
+    this.socketOpen = false;
+    this.peers.clear();
     this.runtime.setTransport(null);
     this.runtime.stop();
     this.ws.close();
+    this.setStatus("closed");
+  }
+
+  private setStatus(status: RelayDisplayStatus): void {
+    if (this.currentStatus === status) return;
+    this.currentStatus = status;
+    this.onStatusChange?.(status);
+  }
+
+  /**
+   * The relay connection ended. The relay drops the room with its host, so
+   * every phone is gone too: mark them disconnected so the state on screen
+   * says so, and report the loss unless this was our own {@link stop}.
+   */
+  private handleSocketClose(event: CloseEvent): void {
+    this.socketOpen = false;
+    if (this.stopped) return;
+
+    for (const peerId of this.peers) {
+      this.runtime.handleDisconnect(peerId);
+    }
+    this.peers.clear();
+    this.setStatus("closed");
+    this.runtime.handleError(
+      new Error(
+        `Relay connection closed (code ${event?.code ?? "unknown"})` +
+          (event?.reason ? `: ${event.reason}` : ""),
+      ),
+    );
+  }
+
+  /**
+   * Sends per-connection messages as one `DATA_MULTI` frame, which the relay
+   * unpacks into an ordinary `DATA` frame per phone.
+   *
+   * A projected game re-sends every player's view on every state change, so on
+   * a four-player table this is the difference between one billed relay message
+   * and four — and between one and four against the relay's per-connection rate
+   * limit, which the display shares across all its fan-out.
+   *
+   * Falls back to individual sends if the combined frame would exceed the
+   * relay's message ceiling: N views in one envelope is N times the bytes, and
+   * a frame the relay rejects delivers nothing to anyone. Splitting costs
+   * messages; being dropped costs the game.
+   */
+  private sendMultiEnvelope(entries: readonly AddressedMessage[]): void {
+    if (!this.socketOpen) return;
+
+    const payloads: Record<string, string> = {};
+    for (const { connectionId, message } of entries) {
+      payloads[connectionId] = JSON.stringify(message);
+    }
+
+    const frame = JSON.stringify({
+      type: RelayMessageTypes.DATA_MULTI,
+      roomId: this.assignedRoomId ?? undefined,
+      payloads,
+    });
+
+    if (frameByteLength(frame) > DEFAULT_MAX_MESSAGE_BYTES) {
+      for (const { connectionId, message } of entries) {
+        this.sendEnvelope(message, connectionId);
+      }
+      return;
+    }
+
+    this.ws.send(frame);
   }
 
   private sendEnvelope(message: HostMessage, to?: string): void {
+    // Nothing to write to yet (or any more): a socket that is still connecting
+    // throws on send, and the runtime may broadcast before it opens.
+    if (!this.socketOpen) return;
+    // A room broadcast with nobody in it is a frame the relay bills and
+    // rate-limits for no reader. A phone that joins later gets the whole state
+    // in its WELCOME.
+    if (to === undefined && this.peers.size === 0) return;
+
     const envelope: Record<string, unknown> = {
       type: RelayMessageTypes.DATA,
       // The relay routes by the sender's membership, not this field, so it is
@@ -184,10 +325,11 @@ export class RelayDisplayHost<S extends IGameState, A extends IAction> {
         // Carries the code when the relay chose it, and confirms the code when
         // the caller supplied one.
         this.assignedRoomId = msg.roomId;
+        this.setStatus("open");
         this.onRoomCode?.(msg.roomId);
         break;
       case RelayMessageTypes.ERROR:
-        this.runtime.handleError(new Error(msg.message));
+        this.runtime.handleError(new RelayError(msg.code, msg.message));
         break;
       // ROOM_JOINED is an acknowledgement; no action needed.
     }