@couch-kit/display 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # @couch-kit/display
 
+## 0.6.0
+
+### Minor Changes
+
+- [#208](https://github.com/faluciano/react-native-couch-kit/pull/208) [`99598d6`](https://github.com/faluciano/react-native-couch-kit/commit/99598d6796b0bd3042aa9f3fbd3bf44ee891b890) Thanks [@faluciano](https://github.com/faluciano)! - `RelayDisplayHost` gains `subscribeActions(listener)`, the runtime's complete action stream: the display's own dispatches, players' actions, and join/leave lifecycle actions. State updates are no longer sent through the relay while no phone has joined the game.
+
+### Patch Changes
+
+- Updated dependencies [[`f4b57e3`](https://github.com/faluciano/react-native-couch-kit/commit/f4b57e3fba385d18396781d22a413a1d8afcb909), [`99598d6`](https://github.com/faluciano/react-native-couch-kit/commit/99598d6796b0bd3042aa9f3fbd3bf44ee891b890), [`99598d6`](https://github.com/faluciano/react-native-couch-kit/commit/99598d6796b0bd3042aa9f3fbd3bf44ee891b890)]:
+  - @couch-kit/client@0.15.1
+  - @couch-kit/core@0.10.1
+  - @couch-kit/runtime@0.5.0
+
+## 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

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,6 +56,7 @@ 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),
@@ -47,15 +67,42 @@ class RelayDisplayHost {
   get roomCode() {
     return this.assignedRoomId;
   }
+  get status() {
+    return this.currentStatus;
+  }
   getState = () => this.runtime.getState();
   subscribe = (listener) => this.runtime.subscribe(listener);
+  subscribeActions = (listener) => this.runtime.subscribeActions(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);
@@ -74,6 +121,10 @@ class RelayDisplayHost {
     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,
@@ -109,14 +160,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 GameHostRuntimeConfig, type RuntimeActionListener } 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: every frame the display sends is
+ * billed by the relay and counted against the display's rate limit, whose
+ * breach closes the socket — and, for the display, ends the room. 20
+ * broadcasts/second is smooth for a party game and leaves the display's budget
+ * (1200 messages/second on the reference relays) to the unicast replies it
+ * also sends: WELCOME, PONG, errors.
+ */
+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,14 +98,29 @@ 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). */
     subscribe: (listener: () => void) => (() => void);
+    /**
+     * Subscribe to every action the runtime reduces — the display's own
+     * dispatches, players' actions, and join/leave lifecycle actions. A
+     * `RelayDisplayHost` can be passed straight to `useActionRecorder({ source })`.
+     */
+    subscribeActions: (listener: RuntimeActionListener<S, A>) => (() => void);
     /** Dispatch a trusted host-display action. */
     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.

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,EAKL,KAAK,qBAAqB,EAE3B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,UAAU,EAAE,OAAO,EAAe,MAAM,iBAAiB,CAAC;AAOxE;;;;;;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;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;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,iBAAiB;IAsBzB,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,EAE1B,KAAK,qBAAqB,EAC3B,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;;;;OAIG;IACH,gBAAgB,aAAc,qBAAqB,CAAC,CAAC,EAAE,CAAC,CAAC,KAAG,CAAC,MAAM,IAAI,CAAC,CAC9B;IAE1C,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.4.0",
+  "version": "0.6.0",
   "publishConfig": {
     "access": "public",
     "provenance": true
@@ -51,9 +51,9 @@
     "clean": "rm -rf dist lib"
   },
   "dependencies": {
-    "@couch-kit/client": "0.14.0",
-    "@couch-kit/core": "0.10.0",
-    "@couch-kit/runtime": "0.3.0"
+    "@couch-kit/client": "0.15.1",
+    "@couch-kit/core": "0.10.1",
+    "@couch-kit/runtime": "0.5.0"
   },
   "devDependencies": {
     "typescript": "^7.0.0"

package/src/relay-display-host.ts

@@ -5,14 +5,50 @@ import {
   type AddressedMessage,
   type GameHostRuntimeConfig,
   type GameRuntimeTransport,
+  type RuntimeActionListener,
 } from "@couch-kit/runtime";
 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: every frame the display sends is
+ * billed by the relay and counted against the display's rate limit, whose
+ * breach closes the socket — and, for the display, ends the room. 20
+ * broadcasts/second is smooth for a party game and leaves the display's budget
+ * (1200 messages/second on the reference relays) to the unicast replies it
+ * also sends: WELCOME, PONG, errors.
+ */
+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}.
  *
@@ -43,6 +79,12 @@ export interface RelayDisplayHostOptions<
    * 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;
 }
 
 /**
@@ -68,17 +110,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".
@@ -105,6 +159,8 @@ 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),
       broadcast: (message) => this.sendEnvelope(message),
@@ -122,6 +178,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();
 
@@ -129,14 +190,54 @@ export class RelayDisplayHost<S extends IGameState, A extends IAction> {
   subscribe = (listener: () => void): (() => void) =>
     this.runtime.subscribe(listener);
 
+  /**
+   * Subscribe to every action the runtime reduces — the display's own
+   * dispatches, players' actions, and join/leave lifecycle actions. A
+   * `RelayDisplayHost` can be passed straight to `useActionRecorder({ source })`.
+   */
+  subscribeActions = (listener: RuntimeActionListener<S, A>): (() => void) =>
+    this.runtime.subscribeActions(listener);
+
   /** Dispatch a trusted host-display action. */
   dispatch = (action: A): void => this.runtime.dispatch(action);
 
   /** 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}` : ""),
+      ),
+    );
   }
 
   /**
@@ -154,6 +255,8 @@ export class RelayDisplayHost<S extends IGameState, A extends IAction> {
    * 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);
@@ -176,6 +279,14 @@ export class RelayDisplayHost<S extends IGameState, A extends IAction> {
   }
 
   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
@@ -223,10 +334,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.
     }