@couch-kit/runtime 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,60 @@
 # @couch-kit/runtime
 
+## 0.3.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)]:
+  - @couch-kit/core@0.10.0
+
+## 0.2.0
+
+### Minor Changes
+
+- [#155](https://github.com/faluciano/react-native-couch-kit/pull/155) [`4f297a1`](https://github.com/faluciano/react-native-couch-kit/commit/4f297a19c442541703c3bee7bee26354ae3476a4) Thanks [@faluciano](https://github.com/faluciano)! - Hidden information can now be hidden for real: `GameHostRuntimeConfig` takes an
+  optional `project(state, playerId)` that narrows the authoritative state to what
+  one player may see.
+
+  Without it the runtime broadcasts the same state to everyone, so hiding a hand
+  depends on the client choosing not to look — any player could read opponents'
+  cards from devtools. With it, the data never reaches their device: the runtime
+  sends each connection its own projection, in `WELCOME`, `RECONNECTED`, and every
+  state update.
+
+  Games with no hidden information omit `project` and are unchanged — state is
+  still broadcast in one frame.
+
+  Because a projected client holds a _view_ rather than the whole state, it cannot
+  run the game reducer, so `ClientConfig.reducer` is now optional. Omit it and the
+  client renders what the host sends (no optimistic updates); a round trip is
+  imperceptible for turn-based games, and it is what makes the guarantee real.
+
 ## 0.1.0
 
 ### Minor Changes

package/dist/index.cjs

@@ -434,7 +434,7 @@ class GameHostRuntime {
               type: import_core5.MessageTypes.RECONNECTED,
               payload: {
                 playerId,
-                state: this.state
+                state: this.viewFor(playerId)
               }
             });
           } else {
@@ -442,7 +442,7 @@ class GameHostRuntime {
               type: import_core5.MessageTypes.WELCOME,
               payload: {
                 playerId,
-                state: this.state,
+                state: this.viewFor(playerId),
                 serverTime: Date.now()
               }
             });
@@ -560,13 +560,40 @@ class GameHostRuntime {
     }
     this.broadcastScheduler.schedule(this.broadcastState);
   }
+  viewFor(playerId) {
+    const project = this.config.project;
+    return project ? project(this.state, playerId) : this.state;
+  }
   broadcastState = () => {
-    if (!this.transport)
+    const transport = this.transport;
+    if (!transport)
       return;
     const actions = this.actionQueue;
     this.actionQueue = [];
     this.stateDirty = false;
-    this.transport.broadcast(createStateUpdateMessage(this.state, actions));
+    if (!this.config.project) {
+      transport.broadcast(createStateUpdateMessage(this.state, actions));
+      return;
+    }
+    const entries = [];
+    for (const connectionId of this.joinedConnections) {
+      const playerId = this.sessionManager.getPlayerIdForSocket(connectionId);
+      if (!playerId)
+        continue;
+      entries.push({
+        connectionId,
+        message: createStateUpdateMessage(this.viewFor(playerId), actions)
+      });
+    }
+    if (entries.length === 0)
+      return;
+    if (transport.sendMany) {
+      transport.sendMany(entries);
+      return;
+    }
+    for (const { connectionId, message } of entries) {
+      this.send(connectionId, message);
+    }
   };
   send(connectionId, message) {
     this.transport?.send(connectionId, message);

package/dist/index.js

@@ -389,7 +389,7 @@ class GameHostRuntime {
               type: MessageTypes3.RECONNECTED,
               payload: {
                 playerId,
-                state: this.state
+                state: this.viewFor(playerId)
               }
             });
           } else {
@@ -397,7 +397,7 @@ class GameHostRuntime {
               type: MessageTypes3.WELCOME,
               payload: {
                 playerId,
-                state: this.state,
+                state: this.viewFor(playerId),
                 serverTime: Date.now()
               }
             });
@@ -515,13 +515,40 @@ class GameHostRuntime {
     }
     this.broadcastScheduler.schedule(this.broadcastState);
   }
+  viewFor(playerId) {
+    const project = this.config.project;
+    return project ? project(this.state, playerId) : this.state;
+  }
   broadcastState = () => {
-    if (!this.transport)
+    const transport = this.transport;
+    if (!transport)
       return;
     const actions = this.actionQueue;
     this.actionQueue = [];
     this.stateDirty = false;
-    this.transport.broadcast(createStateUpdateMessage(this.state, actions));
+    if (!this.config.project) {
+      transport.broadcast(createStateUpdateMessage(this.state, actions));
+      return;
+    }
+    const entries = [];
+    for (const connectionId of this.joinedConnections) {
+      const playerId = this.sessionManager.getPlayerIdForSocket(connectionId);
+      if (!playerId)
+        continue;
+      entries.push({
+        connectionId,
+        message: createStateUpdateMessage(this.viewFor(playerId), actions)
+      });
+    }
+    if (entries.length === 0)
+      return;
+    if (transport.sendMany) {
+      transport.sendMany(entries);
+      return;
+    }
+    for (const { connectionId, message } of entries) {
+      this.send(connectionId, message);
+    }
   };
   send(connectionId, message) {
     this.transport?.send(connectionId, message);

package/lib/broadcast-scheduler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"broadcast-scheduler.d.ts","sourceRoot":"","sources":["../src/broadcast-scheduler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,KAAK,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAEjE,iDAAiD;AACjD,eAAO,MAAM,yBAAyB,KAAK,CAAC;AAE5C,MAAM,MAAM,kBAAkB,GAAG,OAAO,CACtC,WAAW,EACX;IAAE,IAAI,EAAE,OAAO,YAAY,CAAC,YAAY,CAAA;CAAE,CAC3C,CAAC;AAEF,MAAM,WAAW,cAAc,CAAC,MAAM;IACpC,UAAU,CAAC,QAAQ,EAAE,MAAM,IAAI,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC;IAC1D,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACnC;AAOD,MAAM,WAAW,yBAAyB,CAAC,MAAM;IAC/C,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,SAAS,CAAC,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC;CACpC;AAED;;;GAGG;AACH,qBAAa,kBAAkB,CAAC,MAAM,GAAG,UAAU,CAAC,OAAO,UAAU,CAAC;IACpE,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAyB;IACnD,OAAO,CAAC,KAAK,CAAuB;gBAExB,OAAO,GAAE,yBAAyB,CAAC,MAAM,CAAM;IAO3D,QAAQ,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI;IAQpC,MAAM,IAAI,IAAI;IAOd,kBAAkB,CAAC,eAAe,EAAE,MAAM,GAAG,IAAI;IAIjD,mBAAmB,IAAI,OAAO;CAG/B;AAED,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,OAAO,EACjB,OAAO,EAAE,SAAS,OAAO,EAAE,EAC3B,SAAS,GAAE,MAAmB,GAC7B,kBAAkB,CAapB"}
+{"version":3,"file":"broadcast-scheduler.d.ts","sourceRoot":"","sources":["../src/broadcast-scheduler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,KAAK,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAEjE,iDAAiD;AACjD,eAAO,MAAM,yBAAyB,KAAK,CAAC;AAE5C,MAAM,MAAM,kBAAkB,GAAG,OAAO,CACtC,WAAW,EACX;IAAE,IAAI,EAAE,OAAO,YAAY,CAAC,YAAY,CAAA;CAAE,CAC3C,CAAC;AAEF,MAAM,WAAW,cAAc,CAAC,MAAM;IACpC,UAAU,CAAC,QAAQ,EAAE,MAAM,IAAI,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC;IAC1D,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACnC;AAOD,MAAM,WAAW,yBAAyB,CAAC,MAAM;IAC/C,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,SAAS,CAAC,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC;CACpC;AAED;;;GAGG;AACH,qBAAa,kBAAkB,CAAC,MAAM,GAAG,UAAU,CAAC,OAAO,UAAU,CAAC;IACpE,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAyB;IACnD,OAAO,CAAC,KAAK,CAAuB;IAEpC,YAAY,OAAO,GAAE,yBAAyB,CAAC,MAAM,CAAM,EAK1D;IAED,QAAQ,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAMnC;IAED,MAAM,IAAI,IAAI,CAKb;IAED,kBAAkB,CAAC,eAAe,EAAE,MAAM,GAAG,IAAI,CAEhD;IAED,mBAAmB,IAAI,OAAO,CAE7B;CACF;AAED,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,OAAO,EACjB,OAAO,EAAE,SAAS,OAAO,EAAE,EAC3B,SAAS,GAAE,MAAmB,GAC7B,kBAAkB,CAapB"}

package/lib/rate-limiter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rate-limiter.d.ts","sourceRoot":"","sources":["../src/rate-limiter.ts"],"names":[],"mappings":"AAAA,6CAA6C;AAC7C,eAAO,MAAM,cAAc,KAAK,CAAC;AAEjC,uCAAuC;AACvC,eAAO,MAAM,iBAAiB,OAAO,CAAC;AAEtC,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,eAAgB,SAAQ,aAAa;IACpD,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,wBAAwB;IACvC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAoC;gBAE/C,OAAO,GAAE,wBAA6B;IAMlD,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,eAAe;IAiBzC,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAI7B,KAAK,IAAI,IAAI;IAIb,GAAG,CAAC,QAAQ,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS;CAGjD"}
+{"version":3,"file":"rate-limiter.d.ts","sourceRoot":"","sources":["../src/rate-limiter.ts"],"names":[],"mappings":"AAAA,6CAA6C;AAC7C,eAAO,MAAM,cAAc,KAAK,CAAC;AAEjC,uCAAuC;AACvC,eAAO,MAAM,iBAAiB,OAAO,CAAC;AAEtC,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,eAAgB,SAAQ,aAAa;IACpD,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,wBAAwB;IACvC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAoC;IAE3D,YAAY,OAAO,GAAE,wBAA6B,EAIjD;IAED,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,eAAe,CAexC;IAED,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAE5B;IAED,KAAK,IAAI,IAAI,CAEZ;IAED,GAAG,CAAC,QAAQ,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAE/C;CACF"}

package/lib/runtime.d.ts

@@ -1,13 +1,49 @@
 import { type GameReducer, type HostMessage, type IAction, type IGameState } from "@couch-kit/core";
+/** One connection's share of a {@link GameRuntimeTransport.sendMany} delivery. */
+export interface AddressedMessage {
+    connectionId: string;
+    message: HostMessage;
+}
 /** Minimal message-delivery surface required by the authoritative runtime. */
 export interface GameRuntimeTransport {
     send(connectionId: string, message: HostMessage): void;
     broadcast(message: HostMessage): void;
+    /**
+     * Delivers a batch of per-connection messages, for transports that can carry
+     * them in one frame.
+     *
+     * Optional: the runtime falls back to a {@link GameRuntimeTransport.send} per
+     * entry, which is what a plain LAN WebSocket transport wants anyway. It earns
+     * its keep on the relay, where each frame the display sends is separately
+     * billed and rate-limited, so a projected state update costs one message
+     * rather than one per player.
+     */
+    sendMany?(entries: readonly AddressedMessage[]): void;
 }
 /** Configuration shared by every authoritative Couch Kit host transport. */
 export interface GameHostRuntimeConfig<S extends IGameState, A extends IAction> {
     initialState: S;
     reducer: GameReducer<S, A>;
+    /**
+     * Narrows the authoritative state to what one player is allowed to see.
+     *
+     * Without it, every player receives the whole state and any hiding is left to
+     * the client — which makes hidden information a convention rather than a
+     * rule. With it, the data a player must not see never reaches their device:
+     * the runtime sends each connection its own projection instead of one shared
+     * broadcast.
+     *
+     * Omit for games with no hidden information; state is broadcast as before.
+     *
+     * The projection is what clients receive, so their state type is the *view*,
+     * not `S`. A client cannot run the game reducer over a partial view, so
+     * `useGameClient` must be used without a `reducer` (no optimistic updates)
+     * when a projection is configured.
+     *
+     * @param state - Current authoritative state.
+     * @param playerId - Player the projection is for.
+     */
+    project?: (state: S, playerId: string) => unknown;
     debug?: boolean;
     /** Timeout before a disconnected player is permanently removed. */
     disconnectTimeout?: number;
@@ -59,6 +95,11 @@ export declare class GameHostRuntime<S extends IGameState, A extends IAction> {
     /** Cancels runtime timers and releases transport-specific state. */
     stop(): void;
     private applyAction;
+    /**
+     * What `playerId` is allowed to see. Identity unless a projection is
+     * configured, so games without hidden information are unaffected.
+     */
+    private viewFor;
     private readonly broadcastState;
     private send;
     private invokeLifecycleCallback;

package/lib/runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"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"}

package/lib/session-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session-manager.d.ts","sourceRoot":"","sources":["../src/session-manager.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,KAAK,UAAU,EACf,KAAK,cAAc,EACpB,MAAM,iBAAiB,CAAC;AAEzB,MAAM,WAAW,qBAAqB,CAAC,MAAM;IAC3C,UAAU,CAAC,QAAQ,EAAE,MAAM,IAAI,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC;IAC1D,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACnC;AASD,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,yBAAyB,CAAC,MAAM;IAC/C,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,oBAAoB,CAAC,EAAE,MAAM,MAAM,CAAC;IACpC,SAAS,CAAC,EAAE,qBAAqB,CAAC,MAAM,CAAC,CAAC;IAC1C,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACrD,oBAAoB,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,CAAC;CACnD;AAED,MAAM,MAAM,iBAAiB,CAAC,CAAC,SAAS,UAAU,IAAI;IACpD,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,OAAO,CAAC;IACrB,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC,CAAC;CAC3B,CAAC;AAEF,MAAM,MAAM,uBAAuB,CAAC,CAAC,SAAS,UAAU,IACpD;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,GACnB;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACnD;IACE,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC,CAAC;CAC3B,CAAC;AAEN,KAAK,aAAa,CAAC,CAAC,SAAS,UAAU,IAAI,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC;AAE/E;;;GAGG;AACH,qBAAa,kBAAkB,CAAC,MAAM,GAAG,UAAU,CAAC,OAAO,UAAU,CAAC;IACpE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA6B;IACtD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA6B;IACxD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA6B;IAC3D,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAA6B;IAChE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAgC;IAC1D,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAe;IACpD,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAsC;IACvE,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAA6B;gBAExD,OAAO,GAAE,yBAAyB,CAAC,MAAM,CAAM;IAYrD,UAAU,CAAC,CAAC,SAAS,UAAU,EACnC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,kBAAkB,EAC3B,aAAa,EAAE,aAAa,CAAC,CAAC,CAAC,GAC9B,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC;IAoChC,gBAAgB,CAAC,CAAC,SAAS,UAAU,EACnC,QAAQ,EAAE,MAAM,GACf,uBAAuB,CAAC,CAAC,CAAC;IAwB7B,eAAe,CACb,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,GACnC,IAAI;IAUP,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAQrC,kBAAkB,IAAI,IAAI;IAO1B,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAQ1D,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAUzC,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAIxD,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;CAG7C"}
+{"version":3,"file":"session-manager.d.ts","sourceRoot":"","sources":["../src/session-manager.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@couch-kit/runtime",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "publishConfig": {
     "access": "public",
     "provenance": true
@@ -52,14 +52,13 @@
     "build": "bun build ./src/index.ts --outdir ./dist --target browser --external @couch-kit/core && bun build ./src/index.ts --outfile ./dist/index.cjs --target browser --format cjs --external @couch-kit/core && tsc -p tsconfig.build.json",
     "prepublishOnly": "bun run build",
     "test": "bun test",
-    "lint": "eslint src/",
     "typecheck": "tsc --noEmit",
     "clean": "rm -rf dist lib"
   },
   "dependencies": {
-    "@couch-kit/core": "0.9.3"
+    "@couch-kit/core": "0.10.0"
   },
   "devDependencies": {
-    "typescript": "^6.0.0"
+    "typescript": "^7.0.0"
   }
 }

package/src/runtime.ts

@@ -23,10 +23,27 @@ import {
   type JoinSessionPayload,
 } from "./session-manager.js";
 
+/** One connection's share of a {@link GameRuntimeTransport.sendMany} delivery. */
+export interface AddressedMessage {
+  connectionId: string;
+  message: HostMessage;
+}
+
 /** Minimal message-delivery surface required by the authoritative runtime. */
 export interface GameRuntimeTransport {
   send(connectionId: string, message: HostMessage): void;
   broadcast(message: HostMessage): void;
+  /**
+   * Delivers a batch of per-connection messages, for transports that can carry
+   * them in one frame.
+   *
+   * Optional: the runtime falls back to a {@link GameRuntimeTransport.send} per
+   * entry, which is what a plain LAN WebSocket transport wants anyway. It earns
+   * its keep on the relay, where each frame the display sends is separately
+   * billed and rate-limited, so a projected state update costs one message
+   * rather than one per player.
+   */
+  sendMany?(entries: readonly AddressedMessage[]): void;
 }
 
 /** Configuration shared by every authoritative Couch Kit host transport. */
@@ -36,6 +53,26 @@ export interface GameHostRuntimeConfig<
 > {
   initialState: S;
   reducer: GameReducer<S, A>;
+  /**
+   * Narrows the authoritative state to what one player is allowed to see.
+   *
+   * Without it, every player receives the whole state and any hiding is left to
+   * the client — which makes hidden information a convention rather than a
+   * rule. With it, the data a player must not see never reaches their device:
+   * the runtime sends each connection its own projection instead of one shared
+   * broadcast.
+   *
+   * Omit for games with no hidden information; state is broadcast as before.
+   *
+   * The projection is what clients receive, so their state type is the *view*,
+   * not `S`. A client cannot run the game reducer over a partial view, so
+   * `useGameClient` must be used without a `reducer` (no optimistic updates)
+   * when a projection is configured.
+   *
+   * @param state - Current authoritative state.
+   * @param playerId - Player the projection is for.
+   */
+  project?: (state: S, playerId: string) => unknown;
   debug?: boolean;
   /** Timeout before a disconnected player is permanently removed. */
   disconnectTimeout?: number;
@@ -215,7 +252,7 @@ export class GameHostRuntime<S extends IGameState, A extends IAction> {
               type: MessageTypes.RECONNECTED,
               payload: {
                 playerId,
-                state: this.state,
+                state: this.viewFor(playerId),
               },
             });
           } else {
@@ -223,7 +260,7 @@ export class GameHostRuntime<S extends IGameState, A extends IAction> {
               type: MessageTypes.WELCOME,
               payload: {
                 playerId,
-                state: this.state,
+                state: this.viewFor(playerId),
                 serverTime: Date.now(),
               },
             });
@@ -374,13 +411,50 @@ export class GameHostRuntime<S extends IGameState, A extends IAction> {
     this.broadcastScheduler.schedule(this.broadcastState);
   }
 
+  /**
+   * What `playerId` is allowed to see. Identity unless a projection is
+   * configured, so games without hidden information are unaffected.
+   */
+  private viewFor(playerId: string): unknown {
+    const project = this.config.project;
+    return project ? project(this.state, playerId) : this.state;
+  }
+
   private readonly broadcastState = (): void => {
-    if (!this.transport) return;
+    const transport = this.transport;
+    if (!transport) return;
 
     const actions = this.actionQueue;
     this.actionQueue = [];
     this.stateDirty = false;
-    this.transport.broadcast(createStateUpdateMessage(this.state, actions));
+
+    if (!this.config.project) {
+      transport.broadcast(createStateUpdateMessage(this.state, actions));
+      return;
+    }
+
+    // Projected games get one message per connection rather than a broadcast:
+    // a shared frame cannot carry different views. Transports that can batch
+    // (see GameRuntimeTransport.sendMany) still put them on the wire as a
+    // single frame; the rest fall back to N sends, bounded by players-per-room.
+    const entries: AddressedMessage[] = [];
+    for (const connectionId of this.joinedConnections) {
+      const playerId = this.sessionManager.getPlayerIdForSocket(connectionId);
+      if (!playerId) continue;
+      entries.push({
+        connectionId,
+        message: createStateUpdateMessage(this.viewFor(playerId), actions),
+      });
+    }
+    if (entries.length === 0) return;
+
+    if (transport.sendMany) {
+      transport.sendMany(entries);
+      return;
+    }
+    for (const { connectionId, message } of entries) {
+      this.send(connectionId, message);
+    }
   };
 
   private send(connectionId: string, message: HostMessage): void {