@couch-kit/host 2.0.0 → 2.1.0

package/README.md

@@ -216,12 +216,19 @@ Records game actions with timestamps for session replay and debugging. Useful fo
 
 ```tsx
 import { useActionRecorder, useGameHost } from "@couch-kit/host";
+import type { GameAction } from "./shared/gameLogic";
 
 function GameScreen() {
-  const { state } = useGameHost();
+  const { state, dispatch } = useGameHost();
   const { isRecording, recordedCount, startRecording, stopRecording, recordAction } =
     useActionRecorder();
 
+  // Recording is not automatic: call recordAction for each action you dispatch.
+  const dispatchAndRecord = (action: GameAction) => {
+    dispatch(action);
+    recordAction(action);
+  };
+
   const handleStartRecording = () => startRecording(state);
   const handleStop = () => {
     const recording = stopRecording();
@@ -233,6 +240,7 @@ function GameScreen() {
     <View>
       <Text>Actions recorded: {recordedCount}</Text>
       <Button title={isRecording ? "Stop" : "Record"} onPress={isRecording ? handleStop : handleStartRecording} />
+      <Button title="Reset" onPress={() => dispatchAndRecord({ type: "RESET" })} />
     </View>
   );
 }
@@ -244,7 +252,9 @@ Returns:
 - `recordedCount`: number of actions captured so far
 - `startRecording(currentState, metadata?)`: begin recording from the given state
 - `stopRecording()`: end recording and return the `ActionRecording` object (or `null`)
-- `recordAction(action, state)`: capture a single action + resulting state
+- `recordAction(action)`: capture a single action with a timestamp. Nothing is recorded automatically — call it alongside `dispatch`. Resulting states are not stored; replay recomputes them from `initialState` and the reducer. No-op when no recording is active.
+- `exportRecording()`: the current recording as a JSON string (or `null`)
+- `discardRecording()`: drop the current recording and reset the count
 
 ### `getBestIpAddress()`
 

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/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,kBAAkB;IACjC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,eAAe,WAAY,kBAAkB;;;;CAyEzD,CAAC"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,kBAAkB;IACjC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,eAAe,WAAY,kBAAkB;;;;CA6FzD,CAAC"}

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,EAUlC;IAED,OAAO,CAAC,GAAG;IAME,KAAK,kBAqGjB;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.0",
+  "version": "2.1.0",
   "publishConfig": {
     "access": "public",
     "provenance": true
@@ -57,8 +57,8 @@
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "@couch-kit/core": "0.10.0",
-    "@couch-kit/runtime": "0.3.0",
+    "@couch-kit/core": "0.10.1",
+    "@couch-kit/runtime": "0.5.0",
     "react-native-nitro-http-server": "^1.9.2"
   },
   "devDependencies": {
@@ -69,7 +69,7 @@
     "react": "19.3.0",
     "react-dom": "19.3.0",
     "react-native": "0.87.1",
-    "react-native-nitro-modules": "0.35.10",
+    "react-native-nitro-modules": "0.37.1",
     "del-cli": "^7.0.0",
     "jest": "^30.0.0"
   },

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/server.ts

@@ -29,13 +29,26 @@ export const useStaticServer = (config: CouchKitHostConfig) => {
 
   useEffect(() => {
     let server: StaticServer | null = null;
+    // Set by cleanup. Starting is asynchronous, so an effect that was torn down
+    // mid-start (a config change, StrictMode's double mount, an unmount) must
+    // neither publish its result nor leave its server holding the port.
+    let cancelled = false;
     setLoading(true);
+    setError(null);
+
+    const stop = (target: StaticServer | null) => {
+      if (!target) return;
+      void Promise.resolve(target.stop()).catch(() => {
+        // Nothing useful to do if a server we no longer want fails to stop.
+      });
+    };
 
     const startServer = async () => {
       // In Dev Mode, we don't start the static server.
       // We just resolve the IP so the host knows where it is.
       if (config.devMode && config.devServerUrl) {
         const ip = await getBestIpAddress();
+        if (cancelled) return;
         if (ip) {
           // In dev mode, the URL is the laptop's dev server,
           // but we might need the TV's IP for the WebSocket connection later.
@@ -65,13 +78,21 @@ export const useStaticServer = (config: CouchKitHostConfig) => {
         }
         const port = config.port || DEFAULT_HTTP_PORT;
 
-        server = new StaticServer();
+        const started = new StaticServer();
+        server = started;
 
         // Use '0.0.0.0' to bind to all interfaces (local network)
-        await server.start(port, path, "0.0.0.0");
+        await started.start(port, path, "0.0.0.0");
+        if (cancelled) {
+          // Cleanup ran while the server was still starting, when a stop may
+          // not have taken; stop it again now that it is actually up.
+          stop(started);
+          return;
+        }
 
         // We prefer the actual IP over "localhost" returned by some libs
         const ip = await getBestIpAddress();
+        if (cancelled) return;
         if (ip) {
           setUrl(`http://${ip}:${port}/index.html`);
         } else {
@@ -79,18 +100,17 @@ export const useStaticServer = (config: CouchKitHostConfig) => {
           setUrl(`http://localhost:${port}/index.html`);
         }
       } catch (e) {
-        setError(new Error(toErrorMessage(e)));
+        if (!cancelled) setError(new Error(toErrorMessage(e)));
       } finally {
-        setLoading(false);
+        if (!cancelled) setLoading(false);
       }
     };
 
     startServer();
 
     return () => {
-      if (server) {
-        server.stop();
-      }
+      cancelled = true;
+      stop(server);
     };
   }, [config.port, config.devMode, config.devServerUrl, config.staticDir]);
 

package/src/websocket.ts

@@ -73,8 +73,7 @@ export class GameWebSocketServer extends EventEmitter<WebSocketServerEvents> {
     super();
     this.port = config.port;
     this.debug = !!config.debug;
-    this.maxMessageBytes =
-      config.maxMessageBytes ?? DEFAULT_MAX_MESSAGE_BYTES;
+    this.maxMessageBytes = config.maxMessageBytes ?? DEFAULT_MAX_MESSAGE_BYTES;
     // Only `port`, `debug`, and `maxMessageBytes` are honored. `maxFrameSize`,
     // `keepaliveInterval`, and `keepaliveTimeout` are deprecated no-ops: the
     // nitro-http WebSocket transport does not expose these knobs, so they are
@@ -150,10 +149,7 @@ export class GameWebSocketServer extends EventEmitter<WebSocketServerEvents> {
         // Handle errors
         ws.onerror = (event: { message: string }) => {
           this.log(`[WebSocket] Error on ${socketId}:`, event.message);
-          this.emit(
-            "error",
-            new Error(`WebSocket error: ${event.message}`),
-          );
+          this.emit("error", new Error(`WebSocket error: ${event.message}`));
         };
       },
     );
@@ -260,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;