@couch-kit/host 2.0.1 → 2.1.1

package/lib/action-recorder.d.ts

@@ -24,20 +24,51 @@ export interface ActionRecorderControls<S extends IGameState = IGameState, A ext
     isRecording: boolean;
     /** Number of actions recorded so far */
     recordedCount: number;
-    /** Start recording actions. Captures current state as initial state. */
-    startRecording: (currentState: S, metadata?: Record<string, unknown>) => void;
+    /**
+     * Start recording actions, capturing `currentState` as the initial state.
+     * With a {@link ActionRecorderOptions.source}, `currentState` may be omitted
+     * and the source's current state is used.
+     */
+    startRecording: (currentState?: S, metadata?: Record<string, unknown>) => void;
     /** Stop recording and return the recording */
     stopRecording: () => ActionRecording<S, A> | null;
-    /** Record a single action (call this when dispatching) */
+    /**
+     * Record a single action. Only needed without a
+     * {@link ActionRecorderOptions.source}, which records every action itself.
+     */
     recordAction: (action: A) => void;
     /** Export the current recording as JSON string */
     exportRecording: () => string | null;
     /** Discard the current recording */
     discardRecording: () => void;
 }
+/**
+ * Where a recorder reads actions from on its own. `useGameHost()` returns one.
+ */
+export interface ActionRecorderSource<S extends IGameState = IGameState> {
+    getState: () => S;
+    subscribeActions: (listener: (action: IAction) => void) => () => void;
+}
+export interface ActionRecorderOptions<S extends IGameState = IGameState> {
+    /**
+     * Records every action the host reduces — including players' actions and
+     * join/leave lifecycle actions, which never pass through the host's own
+     * `dispatch`. Without it, only actions passed to `recordAction` are
+     * recorded, which on a host means only the host's own dispatches.
+     *
+     * Recordings made this way contain internal actions (`__PLAYER_JOINED__`
+     * and friends); `replayActions` handles them.
+     *
+     * @example
+     * const host = useGameHost<GameState, GameAction>();
+     * const recorder = useActionRecorder({ source: host });
+     * recorder.startRecording();
+     */
+    source?: ActionRecorderSource<S>;
+}
 /**
  * Hook that enables recording of game actions for later replay.
  * Used on the host side to capture game sessions.
  */
-export declare function useActionRecorder<S extends IGameState = IGameState, A extends IAction = IAction>(): ActionRecorderControls<S, A>;
+export declare function useActionRecorder<S extends IGameState = IGameState, A extends IAction = IAction>(options?: ActionRecorderOptions<S>): ActionRecorderControls<S, A>;
 //# sourceMappingURL=action-recorder.d.ts.map

package/lib/action-recorder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"action-recorder.d.ts","sourceRoot":"","sources":["../src/action-recorder.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE3D;;GAEG;AACH,MAAM,WAAW,cAAc,CAAC,CAAC,SAAS,OAAO,GAAG,OAAO;IACzD,MAAM,EAAE,CAAC,CAAC;IACV,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe,CAC9B,CAAC,SAAS,UAAU,GAAG,UAAU,EACjC,CAAC,SAAS,OAAO,GAAG,OAAO;IAE3B,YAAY,EAAE,CAAC,CAAC;IAChB,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,EAAE,CAAC;IAC7B,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB,CACrC,CAAC,SAAS,UAAU,GAAG,UAAU,EACjC,CAAC,SAAS,OAAO,GAAG,OAAO;IAE3B,4CAA4C;IAC5C,WAAW,EAAE,OAAO,CAAC;IACrB,wCAAwC;IACxC,aAAa,EAAE,MAAM,CAAC;IACtB,wEAAwE;IACxE,cAAc,EAAE,CAAC,YAAY,EAAE,CAAC,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;IAC9E,8CAA8C;IAC9C,aAAa,EAAE,MAAM,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC;IAClD,0DAA0D;IAC1D,YAAY,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,IAAI,CAAC;IAClC,kDAAkD;IAClD,eAAe,EAAE,MAAM,MAAM,GAAG,IAAI,CAAC;IACrC,oCAAoC;IACpC,gBAAgB,EAAE,MAAM,IAAI,CAAC;CAC9B;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,CAAC,SAAS,UAAU,GAAG,UAAU,EACjC,CAAC,SAAS,OAAO,GAAG,OAAO,KACxB,sBAAsB,CAAC,CAAC,EAAE,CAAC,CAAC,CA0DhC"}
+{"version":3,"file":"action-recorder.d.ts","sourceRoot":"","sources":["../src/action-recorder.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE3D;;GAEG;AACH,MAAM,WAAW,cAAc,CAAC,CAAC,SAAS,OAAO,GAAG,OAAO;IACzD,MAAM,EAAE,CAAC,CAAC;IACV,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe,CAC9B,CAAC,SAAS,UAAU,GAAG,UAAU,EACjC,CAAC,SAAS,OAAO,GAAG,OAAO;IAE3B,YAAY,EAAE,CAAC,CAAC;IAChB,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,EAAE,CAAC;IAC7B,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB,CACrC,CAAC,SAAS,UAAU,GAAG,UAAU,EACjC,CAAC,SAAS,OAAO,GAAG,OAAO;IAE3B,4CAA4C;IAC5C,WAAW,EAAE,OAAO,CAAC;IACrB,wCAAwC;IACxC,aAAa,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,cAAc,EAAE,CACd,YAAY,CAAC,EAAE,CAAC,EAChB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC/B,IAAI,CAAC;IACV,8CAA8C;IAC9C,aAAa,EAAE,MAAM,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC;IAClD;;;OAGG;IACH,YAAY,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,IAAI,CAAC;IAClC,kDAAkD;IAClD,eAAe,EAAE,MAAM,MAAM,GAAG,IAAI,CAAC;IACrC,oCAAoC;IACpC,gBAAgB,EAAE,MAAM,IAAI,CAAC;CAC9B;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB,CAAC,CAAC,SAAS,UAAU,GAAG,UAAU;IACrE,QAAQ,EAAE,MAAM,CAAC,CAAC;IAClB,gBAAgB,EAAE,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,KAAK,MAAM,IAAI,CAAC;CACvE;AAED,MAAM,WAAW,qBAAqB,CAAC,CAAC,SAAS,UAAU,GAAG,UAAU;IACtE;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,EAAE,oBAAoB,CAAC,CAAC,CAAC,CAAC;CAClC;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,CAAC,SAAS,UAAU,GAAG,UAAU,EACjC,CAAC,SAAS,OAAO,GAAG,OAAO,EAC3B,OAAO,GAAE,qBAAqB,CAAC,CAAC,CAAM,GAAG,sBAAsB,CAAC,CAAC,EAAE,CAAC,CAAC,CA8EtE"}

package/lib/provider.d.ts

@@ -1,6 +1,6 @@
 import React from "react";
 import { type IAction, type IGameState } from "@couch-kit/core";
-import { type GameHostRuntimeConfig } from "@couch-kit/runtime";
+import { type GameHostRuntimeConfig, type RuntimeActionListener } from "@couch-kit/runtime";
 export interface GameHostConfig<S extends IGameState, A extends IAction> extends GameHostRuntimeConfig<S, A> {
     port?: number;
     wsPort?: number;
@@ -18,6 +18,14 @@ interface GameHostContextValue<S extends IGameState, A extends IAction> {
     dispatch: (action: A) => void;
     serverUrl: string | null;
     serverError: Error | null;
+    /** Reads canonical state now, without waiting for a re-render. */
+    getState: () => S;
+    /**
+     * Subscribes to every action the host reduces — its own dispatches, every
+     * player's actions, and player join/leave lifecycle actions. Pass the whole
+     * context to `useActionRecorder({ source })` to record complete sessions.
+     */
+    subscribeActions: (listener: RuntimeActionListener<S, A>) => () => void;
 }
 /**
  * React Native adapter for the transport-neutral authoritative game runtime.

package/lib/provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.tsx"],"names":[],"mappings":"AAAA,OAAO,KAQN,MAAM,OAAO,CAAC;AACf,OAAO,EAGL,KAAK,OAAO,EACZ,KAAK,UAAU,EAChB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAEL,KAAK,qBAAqB,EAC3B,MAAM,oBAAoB,CAAC;AAI5B,MAAM,WAAW,cAAc,CAC7B,CAAC,SAAS,UAAU,EACpB,CAAC,SAAS,OAAO,CACjB,SAAQ,qBAAqB,CAAC,CAAC,EAAE,CAAC,CAAC;IACnC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,UAAU,oBAAoB,CAAC,CAAC,SAAS,UAAU,EAAE,CAAC,SAAS,OAAO;IACpE,KAAK,EAAE,CAAC,CAAC;IACT,QAAQ,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,IAAI,CAAC;IAC9B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,WAAW,EAAE,KAAK,GAAG,IAAI,CAAC;CAC3B;AAOD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,UAAU,EAAE,CAAC,SAAS,OAAO,EAAE,EACxE,QAAQ,EACR,MAAM,GACP,EAAE;IACD,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;IAC1B,MAAM,EAAE,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;CAC9B,qBA4HA;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,UAAU,EAAE,CAAC,SAAS,OAAO,KAK/C,oBAAoB,CAAC,CAAC,EAAE,CAAC,CAAC,CAC7C"}
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.tsx"],"names":[],"mappings":"AAAA,OAAO,KAQN,MAAM,OAAO,CAAC;AACf,OAAO,EAGL,KAAK,OAAO,EACZ,KAAK,UAAU,EAChB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAEL,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAC3B,MAAM,oBAAoB,CAAC;AAI5B,MAAM,WAAW,cAAc,CAC7B,CAAC,SAAS,UAAU,EACpB,CAAC,SAAS,OAAO,CACjB,SAAQ,qBAAqB,CAAC,CAAC,EAAE,CAAC,CAAC;IACnC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,UAAU,oBAAoB,CAAC,CAAC,SAAS,UAAU,EAAE,CAAC,SAAS,OAAO;IACpE,KAAK,EAAE,CAAC,CAAC;IACT,QAAQ,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,IAAI,CAAC;IAC9B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,WAAW,EAAE,KAAK,GAAG,IAAI,CAAC;IAC1B,kEAAkE;IAClE,QAAQ,EAAE,MAAM,CAAC,CAAC;IAClB;;;;OAIG;IACH,gBAAgB,EAAE,CAAC,QAAQ,EAAE,qBAAqB,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,MAAM,IAAI,CAAC;CACzE;AAOD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,UAAU,EAAE,CAAC,SAAS,OAAO,EAAE,EACxE,QAAQ,EACR,MAAM,GACP,EAAE;IACD,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;IAC1B,MAAM,EAAE,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;CAC9B,qBAmIA;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,UAAU,EAAE,CAAC,SAAS,OAAO,KAK/C,oBAAoB,CAAC,CAAC,EAAE,CAAC,CAAC,CAC7C"}

package/lib/websocket.d.ts

@@ -63,6 +63,11 @@ export declare class GameWebSocketServer extends EventEmitter<WebSocketServerEve
      * Wraps each send in try/catch so a single failed send doesn't skip remaining clients.
      */
     broadcast(data: unknown, excludeId?: string): void;
+    /**
+     * Send the same data to each of `socketIds`, serializing it once.
+     * Unknown IDs are skipped; a failed send doesn't skip the remaining clients.
+     */
+    multicast(socketIds: Iterable<string>, data: unknown): void;
     /** Returns the number of currently connected clients. */
     get clientCount(): number;
 }

package/lib/websocket.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"websocket.d.ts","sourceRoot":"","sources":["../src/websocket.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAOH,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAO/C,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;;;OAKG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,8CAA8C;AAC9C,MAAM,MAAM,qBAAqB,GAAG;IAClC,UAAU,EAAE,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IAC/B,OAAO,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;IAC9C,UAAU,EAAE,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IAC/B,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC1B,KAAK,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;CACvB,CAAC;AAOF,qBAAa,mBAAoB,SAAQ,YAAY,CAAC,qBAAqB,CAAC;IAC1E,OAAO,CAAC,MAAM,CAA6B;IAC3C,OAAO,CAAC,OAAO,CAA2C;IAC1D,OAAO,CAAC,IAAI,CAAS;IACrB,OAAO,CAAC,KAAK,CAAU;IACvB,OAAO,CAAC,eAAe,CAAS;IAEhC,YAAY,MAAM,EAAE,eAAe,EASlC;IAED,OAAO,CAAC,GAAG;IAME,KAAK,kBAkGjB;IAEY,IAAI,kBAkBhB;IAED;;;OAGG;IACI,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,QAoB1C;IAED;;;OAGG;IACI,SAAS,CAAC,IAAI,EAAE,OAAO,EAAE,SAAS,CAAC,EAAE,MAAM,QAkBjD;IAED,yDAAyD;IACzD,IAAW,WAAW,IAAI,MAAM,CAE/B;CACF"}
+{"version":3,"file":"websocket.d.ts","sourceRoot":"","sources":["../src/websocket.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAOH,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAO/C,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;;;OAKG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,8CAA8C;AAC9C,MAAM,MAAM,qBAAqB,GAAG;IAClC,UAAU,EAAE,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IAC/B,OAAO,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;IAC9C,UAAU,EAAE,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IAC/B,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC1B,KAAK,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;CACvB,CAAC;AAOF,qBAAa,mBAAoB,SAAQ,YAAY,CAAC,qBAAqB,CAAC;IAC1E,OAAO,CAAC,MAAM,CAA6B;IAC3C,OAAO,CAAC,OAAO,CAA2C;IAC1D,OAAO,CAAC,IAAI,CAAS;IACrB,OAAO,CAAC,KAAK,CAAU;IACvB,OAAO,CAAC,eAAe,CAAS;IAEhC,YAAY,MAAM,EAAE,eAAe,EASlC;IAED,OAAO,CAAC,GAAG;IAME,KAAK,kBAkGjB;IAEY,IAAI,kBAkBhB;IAED;;;OAGG;IACI,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,QAoB1C;IAED;;;OAGG;IACI,SAAS,CAAC,IAAI,EAAE,OAAO,EAAE,SAAS,CAAC,EAAE,MAAM,QAkBjD;IAED;;;OAGG;IACI,SAAS,CAAC,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,OAAO,QAiB1D;IAED,yDAAyD;IACzD,IAAW,WAAW,IAAI,MAAM,CAE/B;CACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@couch-kit/host",
-  "version": "2.0.1",
+  "version": "2.1.1",
   "publishConfig": {
     "access": "public",
     "provenance": true
@@ -57,8 +57,8 @@
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "@couch-kit/core": "0.10.0",
-    "@couch-kit/runtime": "0.4.0",
+    "@couch-kit/core": "0.10.1",
+    "@couch-kit/runtime": "0.6.0",
     "react-native-nitro-http-server": "^1.9.2"
   },
   "devDependencies": {

package/src/action-recorder.ts

@@ -1,4 +1,4 @@
-import { useCallback, useRef, useState } from "react";
+import { useCallback, useEffect, useRef, useState } from "react";
 import type { IAction, IGameState } from "@couch-kit/core";
 
 /**
@@ -34,11 +34,21 @@ export interface ActionRecorderControls<
   isRecording: boolean;
   /** Number of actions recorded so far */
   recordedCount: number;
-  /** Start recording actions. Captures current state as initial state. */
-  startRecording: (currentState: S, metadata?: Record<string, unknown>) => void;
+  /**
+   * Start recording actions, capturing `currentState` as the initial state.
+   * With a {@link ActionRecorderOptions.source}, `currentState` may be omitted
+   * and the source's current state is used.
+   */
+  startRecording: (
+    currentState?: S,
+    metadata?: Record<string, unknown>,
+  ) => void;
   /** Stop recording and return the recording */
   stopRecording: () => ActionRecording<S, A> | null;
-  /** Record a single action (call this when dispatching) */
+  /**
+   * Record a single action. Only needed without a
+   * {@link ActionRecorderOptions.source}, which records every action itself.
+   */
   recordAction: (action: A) => void;
   /** Export the current recording as JSON string */
   exportRecording: () => string | null;
@@ -46,6 +56,32 @@ export interface ActionRecorderControls<
   discardRecording: () => void;
 }
 
+/**
+ * Where a recorder reads actions from on its own. `useGameHost()` returns one.
+ */
+export interface ActionRecorderSource<S extends IGameState = IGameState> {
+  getState: () => S;
+  subscribeActions: (listener: (action: IAction) => void) => () => void;
+}
+
+export interface ActionRecorderOptions<S extends IGameState = IGameState> {
+  /**
+   * Records every action the host reduces — including players' actions and
+   * join/leave lifecycle actions, which never pass through the host's own
+   * `dispatch`. Without it, only actions passed to `recordAction` are
+   * recorded, which on a host means only the host's own dispatches.
+   *
+   * Recordings made this way contain internal actions (`__PLAYER_JOINED__`
+   * and friends); `replayActions` handles them.
+   *
+   * @example
+   * const host = useGameHost<GameState, GameAction>();
+   * const recorder = useActionRecorder({ source: host });
+   * recorder.startRecording();
+   */
+  source?: ActionRecorderSource<S>;
+}
+
 /**
  * Hook that enables recording of game actions for later replay.
  * Used on the host side to capture game sessions.
@@ -53,15 +89,24 @@ export interface ActionRecorderControls<
 export function useActionRecorder<
   S extends IGameState = IGameState,
   A extends IAction = IAction,
->(): ActionRecorderControls<S, A> {
+>(options: ActionRecorderOptions<S> = {}): ActionRecorderControls<S, A> {
+  const { source } = options;
   const [isRecording, setIsRecording] = useState(false);
   const [recordedCount, setRecordedCount] = useState(0);
   const recordingRef = useRef<ActionRecording<S, A> | null>(null);
+  const sourceRef = useRef(source);
+  sourceRef.current = source;
 
   const startRecording = useCallback(
-    (currentState: S, metadata?: Record<string, unknown>) => {
+    (currentState?: S, metadata?: Record<string, unknown>) => {
+      const initialState = currentState ?? sourceRef.current?.getState();
+      if (initialState === undefined) {
+        throw new Error(
+          "startRecording needs the current state when no source is configured",
+        );
+      }
       recordingRef.current = {
-        initialState: currentState,
+        initialState,
         actions: [],
         startTimestamp: Date.now(),
         metadata,
@@ -82,7 +127,12 @@ export function useActionRecorder<
   }, []);
 
   const recordAction = useCallback((action: A) => {
-    if (!recordingRef.current) return;
+    // A stopped recording keeps its actions but takes no new ones.
+    if (
+      !recordingRef.current ||
+      recordingRef.current.endTimestamp !== undefined
+    )
+      return;
 
     recordingRef.current.actions.push({
       action,
@@ -91,6 +141,12 @@ export function useActionRecorder<
     setRecordedCount((c) => c + 1);
   }, []);
 
+  const subscribeActions = source?.subscribeActions;
+  useEffect(() => {
+    if (!subscribeActions) return;
+    return subscribeActions((action) => recordAction(action as A));
+  }, [subscribeActions, recordAction]);
+
   const exportRecording = useCallback((): string | null => {
     if (!recordingRef.current) return null;
     return JSON.stringify(recordingRef.current, null, 2);

package/src/provider.tsx

@@ -16,6 +16,7 @@ import {
 import {
   GameHostRuntime,
   type GameHostRuntimeConfig,
+  type RuntimeActionListener,
 } from "@couch-kit/runtime";
 import { useStaticServer } from "./server";
 import { GameWebSocketServer } from "./websocket";
@@ -41,6 +42,14 @@ interface GameHostContextValue<S extends IGameState, A extends IAction> {
   dispatch: (action: A) => void;
   serverUrl: string | null;
   serverError: Error | null;
+  /** Reads canonical state now, without waiting for a re-render. */
+  getState: () => S;
+  /**
+   * Subscribes to every action the host reduces — its own dispatches, every
+   * player's actions, and player join/leave lifecycle actions. Pass the whole
+   * context to `useActionRecorder({ source })` to record complete sessions.
+   */
+  subscribeActions: (listener: RuntimeActionListener<S, A>) => () => void;
 }
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -139,8 +148,8 @@ export function GameHostProvider<S extends IGameState, A extends IAction>({
           send: (connectionId, message) => {
             server.send(connectionId, message);
           },
-          broadcast: (message) => {
-            server.broadcast(message);
+          broadcast: (message, recipients) => {
+            server.multicast(recipients, message);
           },
         });
 
@@ -175,8 +184,15 @@ export function GameHostProvider<S extends IGameState, A extends IAction>({
   );
 
   const contextValue = useMemo(
-    () => ({ state, dispatch, serverUrl, serverError }),
-    [state, dispatch, serverUrl, serverError],
+    () => ({
+      state,
+      dispatch,
+      serverUrl,
+      serverError,
+      getState: runtime.getState,
+      subscribeActions: runtime.subscribeActions,
+    }),
+    [state, dispatch, serverUrl, serverError, runtime],
   );
 
   return (

package/src/websocket.ts

@@ -256,6 +256,29 @@ export class GameWebSocketServer extends EventEmitter<WebSocketServerEvents> {
     }
   }
 
+  /**
+   * Send the same data to each of `socketIds`, serializing it once.
+   * Unknown IDs are skipped; a failed send doesn't skip the remaining clients.
+   */
+  public multicast(socketIds: Iterable<string>, data: unknown) {
+    try {
+      const message = JSON.stringify(data);
+      for (const id of socketIds) {
+        const client = this.clients.get(id);
+        if (!client) continue;
+        client.ws.send(message).catch((error: Error) => {
+          this.log(`[WebSocket] Failed to send to ${id}:`, error);
+        });
+      }
+    } catch (error) {
+      this.log(`[WebSocket] Failed to serialize multicast message:`, error);
+      this.emit(
+        "error",
+        error instanceof Error ? error : new Error(String(error)),
+      );
+    }
+  }
+
   /** Returns the number of currently connected clients. */
   public get clientCount(): number {
     return this.clients.size;