@couch-kit/host 1.7.9 → 1.7.11

package/README.md

@@ -26,10 +26,10 @@ Then install the required peer dependencies:
 
 ```bash
 npx expo install expo-file-system expo-network
-bun add react-native-tcp-socket react-native-nitro-modules
+bun add react-native-nitro-modules
 ```
 
-> **Note:** This library requires Expo modules (`expo-file-system`, `expo-network`), `react-native-tcp-socket`, and `react-native-nitro-modules` as peer dependencies. These must be installed in your consumer app. React Native's autolinking will handle native setup automatically.
+> **Note:** This library requires Expo modules (`expo-file-system`, `expo-network`) and `react-native-nitro-modules` as peer dependencies. These must be installed in your consumer app. React Native's autolinking will handle native setup automatically.
 
 ## Compatibility
 
@@ -39,9 +39,8 @@ bun add react-native-tcp-socket react-native-nitro-modules
 | `react-native`               | `>= 0.72.0`     |
 | `react-native-nitro-modules` | `>= 0.33.0`     |
 | `expo`                       | `>= 51.0.0`     |
-| `expo-file-system`           | `>= 17.0.0`     |
+| `expo-file-system`           | `>= 19.0.0`    |
 | `expo-network`               | `>= 7.0.0`      |
-| `react-native-tcp-socket`    | `>= 6.0.0`      |
 
 > **New Architecture:** This package supports React Native's New Architecture (Fabric/TurboModules) via React Native 0.83+.
 
@@ -58,6 +57,8 @@ Config:
 - `staticDir?`: absolute path to the directory of static files to serve. **Required on Android** — APK assets live inside a zip archive and cannot be served directly, so use this to point to a writable filesystem path where you've extracted the `www/` assets at runtime. On iOS, defaults to the bundle directory + `/www`.
 - `devMode?`: if true, do not start the TV static file server; instead point phones at `devServerUrl`
 - `devServerUrl?`: URL of your laptop dev server (e.g. `http://192.168.1.50:5173`)
+- `stateThrottleMs?`: minimum interval (ms) between state broadcasts (default `33` ≈ 30fps)
+- `disconnectTimeout?`: time (ms) before a disconnected player is permanently removed (default `300000` = 5 minutes)
 - `debug?`: enable verbose logs
 
 ### `useGameHost()`
@@ -183,8 +184,8 @@ function GameScreen() {
 
 To iterate on your web controller without rebuilding the Android app constantly:
 
-1.  Start your web project locally (`vite dev` usually runs on `localhost:5173`).
-2.  Configure the Host to point to your laptop:
+1. Start your web project locally (`vite dev` usually runs on `localhost:5173`).
+2. Configure the Host to point to your laptop:
 
 ```tsx
 <GameHostProvider
@@ -206,3 +207,51 @@ Important: when the controller is served from the laptop, the client-side hook c
 In production, the host serves static controller assets from the iOS bundle directory + `/www` by default. On Android, `staticDir` must be provided since bundle assets live inside the APK.
 
 The CLI `couch-kit bundle` copies your web build output into `android/app/src/main/assets/www` (default). Ensure your app packaging makes those assets available under the expected `www` folder.
+
+## Additional Hooks
+
+### `useActionRecorder()`
+
+Records game actions with timestamps for session replay and debugging. Useful for testing, bug reproduction, and replay-based features.
+
+```tsx
+import { useActionRecorder, useGameHost } from "@couch-kit/host";
+
+function GameScreen() {
+  const { state } = useGameHost();
+  const { isRecording, recordedCount, startRecording, stopRecording, recordAction } =
+    useActionRecorder();
+
+  const handleStartRecording = () => startRecording(state);
+  const handleStop = () => {
+    const recording = stopRecording();
+    // Save recording JSON for later replay via `couch-kit replay`
+    console.log(JSON.stringify(recording));
+  };
+
+  return (
+    <View>
+      <Text>Actions recorded: {recordedCount}</Text>
+      <Button title={isRecording ? "Stop" : "Record"} onPress={isRecording ? handleStop : handleStartRecording} />
+    </View>
+  );
+}
+```
+
+Returns:
+
+- `isRecording`: whether a recording session is active
+- `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
+
+### `getBestIpAddress()`
+
+Returns the device's best LAN IPv4 address (or `null`). Used internally by the provider but exported for custom networking UI (e.g., displaying a manual connect URL).
+
+```tsx
+import { getBestIpAddress } from "@couch-kit/host";
+
+const ip = await getBestIpAddress(); // e.g. "192.168.1.99"
+```

package/lib/broadcast-scheduler.d.ts

@@ -0,0 +1,30 @@
+import { MessageTypes, type HostMessage } from "@couch-kit/core";
+/** Default state broadcast throttle (~30fps). */
+export declare const DEFAULT_STATE_THROTTLE_MS = 33;
+export type StateUpdateMessage = Extract<HostMessage, {
+    type: typeof MessageTypes.STATE_UPDATE;
+}>;
+export interface TimerScheduler<TTimer> {
+    setTimeout(callback: () => void, delayMs: number): TTimer;
+    clearTimeout(timer: TTimer): void;
+}
+export interface BroadcastSchedulerOptions<TTimer> {
+    stateThrottleMs?: number;
+    scheduler?: TimerScheduler<TTimer>;
+}
+/**
+ * Debounced state-broadcast scheduler used by the host provider.
+ * Rapid state changes are coalesced into one broadcast after the latest change.
+ */
+export declare class BroadcastScheduler<TTimer = ReturnType<typeof setTimeout>> {
+    private stateThrottleMs;
+    private readonly scheduler;
+    private timer;
+    constructor(options?: BroadcastSchedulerOptions<TTimer>);
+    schedule(callback: () => void): void;
+    cancel(): void;
+    setStateThrottleMs(stateThrottleMs: number): void;
+    hasPendingBroadcast(): boolean;
+}
+export declare function createStateUpdateMessage(newState: unknown, actions: readonly unknown[], timestamp?: number): StateUpdateMessage;
+//# sourceMappingURL=broadcast-scheduler.d.ts.map

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

@@ -0,0 +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;IAQ3D,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"}

package/lib/index.d.ts

@@ -4,4 +4,8 @@ export * from "./websocket";
 export * from "./network";
 export * from "./assets";
 export * from "./action-recorder";
+export * from "./rate-limiter";
+export * from "./session-manager";
+export * from "./message-validation";
+export * from "./broadcast-scheduler";
 //# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.tsx"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.tsx"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC"}

package/lib/message-validation.d.ts

@@ -0,0 +1,20 @@
+import { MessageTypes, type ClientMessage } from "@couch-kit/core";
+type ClientMessageOf<TType extends ClientMessage["type"]> = Extract<ClientMessage, {
+    type: TType;
+}>;
+export type ValidatedClientMessage = {
+    type: typeof MessageTypes.JOIN;
+    payload: {
+        name: string;
+        secret?: unknown;
+        avatar?: unknown;
+        [key: string]: unknown;
+    };
+} | ClientMessageOf<"ACTION"> | ClientMessageOf<"PING"> | ClientMessageOf<"ASSETS_LOADED">;
+/**
+ * Validates that an incoming message has the expected shape.
+ * Returns true if the message has a processable client-message shape.
+ */
+export declare function isValidClientMessage(msg: unknown): msg is ValidatedClientMessage;
+export {};
+//# sourceMappingURL=message-validation.d.ts.map

package/lib/message-validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-validation.d.ts","sourceRoot":"","sources":["../src/message-validation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,KAAK,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEnE,KAAK,eAAe,CAAC,KAAK,SAAS,aAAa,CAAC,MAAM,CAAC,IAAI,OAAO,CACjE,aAAa,EACb;IAAE,IAAI,EAAE,KAAK,CAAA;CAAE,CAChB,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAC9B;IACE,IAAI,EAAE,OAAO,YAAY,CAAC,IAAI,CAAC;IAC/B,OAAO,EAAE;QACP,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,CAAC,EAAE,OAAO,CAAC;QACjB,MAAM,CAAC,EAAE,OAAO,CAAC;QACjB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;KACxB,CAAC;CACH,GACD,eAAe,CAAC,QAAQ,CAAC,GACzB,eAAe,CAAC,MAAM,CAAC,GACvB,eAAe,CAAC,eAAe,CAAC,CAAC;AAErC;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,OAAO,GACX,GAAG,IAAI,sBAAsB,CA8B/B"}

package/lib/provider.d.ts

@@ -11,6 +11,8 @@ export interface GameHostConfig<S extends IGameState, A extends IAction> {
     debug?: boolean;
     /** Timeout (ms) before a disconnected player is permanently removed (default: 5 minutes). */
     disconnectTimeout?: number;
+    /** State broadcast throttle interval in milliseconds (default: 33ms, ~30fps). */
+    stateThrottleMs?: number;
     /** Called when a player successfully joins. */
     onPlayerJoined?: (playerId: string, name: string) => void;
     /** Called when a player disconnects. */

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;AAGf,OAAO,EAUL,KAAK,UAAU,EACf,KAAK,OAAO,EAGb,MAAM,iBAAiB,CAAC;AAQzB,MAAM,WAAW,cAAc,CAAC,CAAC,SAAS,UAAU,EAAE,CAAC,SAAS,OAAO;IACrE,YAAY,EAAE,CAAC,CAAC;IAChB,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,KAAK,CAAC,CAAC;IACpC,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,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,6FAA6F;IAC7F,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,+CAA+C;IAC/C,cAAc,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC1D,wCAAwC;IACxC,YAAY,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IAC1C,yCAAyC;IACzC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CAClC;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;AA4CD;;;;;;;;;;;;;;;GAeG;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,qBAobA;AAED;;;;;;;;;GASG;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;AAGf,OAAO,EAQL,KAAK,UAAU,EACf,KAAK,OAAO,EAEb,MAAM,iBAAiB,CAAC;AAazB,MAAM,WAAW,cAAc,CAAC,CAAC,SAAS,UAAU,EAAE,CAAC,SAAS,OAAO;IACrE,YAAY,EAAE,CAAC,CAAC;IAChB,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,KAAK,CAAC,CAAC;IACpC,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,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,6FAA6F;IAC7F,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,iFAAiF;IACjF,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,+CAA+C;IAC/C,cAAc,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC1D,wCAAwC;IACxC,YAAY,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IAC1C,yCAAyC;IACzC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CAClC;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;AAQD;;;;;;;;;;;;;;;GAeG;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,qBA2WA;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,UAAU,EAAE,CAAC,SAAS,OAAO,KAK/C,oBAAoB,CAAC,CAAC,EAAE,CAAC,CAAC,CAC7C"}

package/lib/rate-limiter.d.ts

@@ -0,0 +1,32 @@
+/** Maximum actions per rate-limit window. */
+export declare const RATE_LIMIT_MAX = 60;
+/** Rate-limit window duration (ms). */
+export declare const RATE_LIMIT_WINDOW = 1000;
+export interface RateLimitInfo {
+    count: number;
+    windowStart: number;
+}
+export interface RateLimitResult extends RateLimitInfo {
+    allowed: boolean;
+}
+export interface ActionRateLimiterOptions {
+    maxActions?: number;
+    windowMs?: number;
+    now?: () => number;
+}
+/**
+ * Per-socket action limiter that preserves the host provider's original
+ * fixed-window algorithm.
+ */
+export declare class ActionRateLimiter {
+    private readonly maxActions;
+    private readonly windowMs;
+    private readonly now;
+    private readonly limits;
+    constructor(options?: ActionRateLimiterOptions);
+    record(socketId: string): RateLimitResult;
+    reset(socketId: string): void;
+    clear(): void;
+    get(socketId: string): RateLimitInfo | undefined;
+}
+//# sourceMappingURL=rate-limiter.d.ts.map

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

@@ -0,0 +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"}

package/lib/session-manager.d.ts

@@ -0,0 +1,62 @@
+import { type IGameState, type InternalAction } from "@couch-kit/core";
+export interface SessionTimerScheduler<TTimer> {
+    setTimeout(callback: () => void, delayMs: number): TTimer;
+    clearTimeout(timer: TTimer): void;
+}
+export interface JoinSessionPayload {
+    name: string;
+    avatar?: string;
+    secret: string;
+}
+export interface HostSessionManagerOptions<TTimer> {
+    disconnectTimeout?: number;
+    getDisconnectTimeout?: () => number;
+    scheduler?: SessionTimerScheduler<TTimer>;
+    derivePlayerId?: (secret: string) => Promise<string>;
+    derivePlayerIdLegacy?: (secret: string) => string;
+}
+export type JoinSessionResult<S extends IGameState> = {
+    playerId: string;
+    socketId: string;
+    secret: string;
+    isReconnect: boolean;
+    action: InternalAction<S>;
+};
+export type DisconnectSessionResult<S extends IGameState> = {
+    kind: "unknown";
+} | {
+    kind: "stale";
+    playerId: string;
+    secret: string;
+} | {
+    kind: "left";
+    playerId: string;
+    secret: string;
+    action: InternalAction<S>;
+};
+type PlayersSource<S extends IGameState> = S["players"] | (() => S["players"]);
+/**
+ * Tracks host player sessions by secret and socket ID, including reconnects and
+ * delayed cleanup of disconnected players.
+ */
+export declare class HostSessionManager<TTimer = ReturnType<typeof setTimeout>> {
+    private readonly sessions;
+    private readonly reverseMap;
+    private readonly cleanupTimers;
+    private readonly socketIdToPlayerId;
+    private readonly scheduler;
+    private readonly getDisconnectTimeout;
+    private readonly derivePlayerIdFn;
+    private readonly derivePlayerIdLegacyFn;
+    constructor(options?: HostSessionManagerOptions<TTimer>);
+    handleJoin<S extends IGameState>(socketId: string, payload: JoinSessionPayload, playersSource: PlayersSource<S>): Promise<JoinSessionResult<S>>;
+    handleDisconnect<S extends IGameState>(socketId: string): DisconnectSessionResult<S>;
+    scheduleRemoval(playerId: string, secret: string, onRemove: (playerId: string) => void): void;
+    cancelRemoval(playerId: string): void;
+    clearRemovalTimers(): void;
+    getPlayerIdForSocket(socketId: string): string | undefined;
+    getSocketIdForSecret(secret: string): string | undefined;
+    hasPendingRemoval(playerId: string): boolean;
+}
+export {};
+//# sourceMappingURL=session-manager.d.ts.map

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

@@ -0,0 +1 @@
+{"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/host",
-  "version": "1.7.9",
+  "version": "1.7.11",
   "publishConfig": {
     "access": "public",
     "provenance": true
@@ -58,13 +58,13 @@
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "@couch-kit/core": "0.9.1",
+    "@couch-kit/core": "0.9.2",
     "buffer": "^6.0.3",
     "js-sha1": "^0.7.0",
     "react-native-nitro-http-server": "^1.6.1"
   },
   "devDependencies": {
-    "@types/react": "^19.1.1",
+    "@types/react": "^19.2.17",
     "react": "19.0.4",
     "react-native": "0.83.2",
     "del-cli": "^5.1.0",

package/src/broadcast-scheduler.ts

@@ -0,0 +1,84 @@
+import { MessageTypes, type HostMessage } from "@couch-kit/core";
+
+/** Default state broadcast throttle (~30fps). */
+export const DEFAULT_STATE_THROTTLE_MS = 33;
+
+export type StateUpdateMessage = Extract<
+  HostMessage,
+  { type: typeof MessageTypes.STATE_UPDATE }
+>;
+
+export interface TimerScheduler<TTimer> {
+  setTimeout(callback: () => void, delayMs: number): TTimer;
+  clearTimeout(timer: TTimer): void;
+}
+
+const defaultTimerScheduler: TimerScheduler<ReturnType<typeof setTimeout>> = {
+  setTimeout: (callback, delayMs) => setTimeout(callback, delayMs),
+  clearTimeout: (timer) => clearTimeout(timer),
+};
+
+export interface BroadcastSchedulerOptions<TTimer> {
+  stateThrottleMs?: number;
+  scheduler?: TimerScheduler<TTimer>;
+}
+
+/**
+ * Debounced state-broadcast scheduler used by the host provider.
+ * Rapid state changes are coalesced into one broadcast after the latest change.
+ */
+export class BroadcastScheduler<TTimer = ReturnType<typeof setTimeout>> {
+  private stateThrottleMs: number;
+  private readonly scheduler: TimerScheduler<TTimer>;
+  private timer: TTimer | null = null;
+
+  constructor(options: BroadcastSchedulerOptions<TTimer> = {}) {
+    this.stateThrottleMs =
+      options.stateThrottleMs ?? DEFAULT_STATE_THROTTLE_MS;
+    this.scheduler =
+      options.scheduler ??
+      (defaultTimerScheduler as unknown as TimerScheduler<TTimer>);
+  }
+
+  schedule(callback: () => void): void {
+    this.cancel();
+    this.timer = this.scheduler.setTimeout(() => {
+      this.timer = null;
+      callback();
+    }, this.stateThrottleMs);
+  }
+
+  cancel(): void {
+    if (this.timer) {
+      this.scheduler.clearTimeout(this.timer);
+      this.timer = null;
+    }
+  }
+
+  setStateThrottleMs(stateThrottleMs: number): void {
+    this.stateThrottleMs = stateThrottleMs;
+  }
+
+  hasPendingBroadcast(): boolean {
+    return this.timer !== null;
+  }
+}
+
+export function createStateUpdateMessage(
+  newState: unknown,
+  actions: readonly unknown[],
+  timestamp: number = Date.now(),
+): StateUpdateMessage {
+  return {
+    type: MessageTypes.STATE_UPDATE,
+    payload: {
+      newState,
+      timestamp,
+      ...(actions.length === 1
+        ? { action: actions[0] }
+        : actions.length > 1
+          ? { action: actions }
+          : {}),
+    },
+  };
+}

package/src/index.tsx

@@ -4,3 +4,7 @@ export * from "./websocket";
 export * from "./network";
 export * from "./assets";
 export * from "./action-recorder";
+export * from "./rate-limiter";
+export * from "./session-manager";
+export * from "./message-validation";
+export * from "./broadcast-scheduler";

package/src/message-validation.ts

@@ -0,0 +1,58 @@
+import { MessageTypes, type ClientMessage } from "@couch-kit/core";
+
+type ClientMessageOf<TType extends ClientMessage["type"]> = Extract<
+  ClientMessage,
+  { type: TType }
+>;
+
+export type ValidatedClientMessage =
+  | {
+      type: typeof MessageTypes.JOIN;
+      payload: {
+        name: string;
+        secret?: unknown;
+        avatar?: unknown;
+        [key: string]: unknown;
+      };
+    }
+  | ClientMessageOf<"ACTION">
+  | ClientMessageOf<"PING">
+  | ClientMessageOf<"ASSETS_LOADED">;
+
+/**
+ * Validates that an incoming message has the expected shape.
+ * Returns true if the message has a processable client-message shape.
+ */
+export function isValidClientMessage(
+  msg: unknown,
+): msg is ValidatedClientMessage {
+  if (typeof msg !== "object" || msg === null) return false;
+  const m = msg as Record<string, unknown>;
+  if (typeof m.type !== "string") return false;
+
+  switch (m.type) {
+    case MessageTypes.JOIN:
+      return (
+        typeof m.payload === "object" &&
+        m.payload !== null &&
+        typeof (m.payload as Record<string, unknown>).name === "string"
+      );
+    case MessageTypes.ACTION:
+      return (
+        typeof m.payload === "object" &&
+        m.payload !== null &&
+        typeof (m.payload as Record<string, unknown>).type === "string"
+      );
+    case MessageTypes.PING:
+      return (
+        typeof m.payload === "object" &&
+        m.payload !== null &&
+        typeof (m.payload as Record<string, unknown>).id === "string" &&
+        typeof (m.payload as Record<string, unknown>).timestamp === "number"
+      );
+    case MessageTypes.ASSETS_LOADED:
+      return m.payload === true;
+    default:
+      return false;
+  }
+}

package/src/provider.tsx

@@ -16,20 +16,22 @@ import {
   DEFAULT_WS_PORT_OFFSET,
   DEFAULT_DISCONNECT_TIMEOUT,
   createGameReducer,
-  derivePlayerId,
-  derivePlayerIdLegacy,
   isValidSecret,
   type IGameState,
   type IAction,
   type InternalAction,
-  type ClientMessage,
 } from "@couch-kit/core";
-
-/** Maximum actions per rate-limit window. */
-const RATE_LIMIT_MAX = 60;
-
-/** Rate-limit window duration (ms). */
-const RATE_LIMIT_WINDOW = 1000;
+import { isValidClientMessage } from "./message-validation";
+import { ActionRateLimiter } from "./rate-limiter";
+import {
+  HostSessionManager,
+  type JoinSessionPayload,
+} from "./session-manager";
+import {
+  BroadcastScheduler,
+  DEFAULT_STATE_THROTTLE_MS,
+  createStateUpdateMessage,
+} from "./broadcast-scheduler";
 
 export interface GameHostConfig<S extends IGameState, A extends IAction> {
   initialState: S;
@@ -42,6 +44,8 @@ export interface GameHostConfig<S extends IGameState, A extends IAction> {
   debug?: boolean;
   /** Timeout (ms) before a disconnected player is permanently removed (default: 5 minutes). */
   disconnectTimeout?: number;
+  /** State broadcast throttle interval in milliseconds (default: 33ms, ~30fps). */
+  stateThrottleMs?: number;
   /** Called when a player successfully joins. */
   onPlayerJoined?: (playerId: string, name: string) => void;
   /** Called when a player disconnects. */
@@ -63,42 +67,6 @@ const GameHostContext = createContext<GameHostContextValue<any, any> | null>(
   null,
 );
 
-/**
- * Validates that an incoming message has the expected shape.
- * Returns true if the message is a valid ClientMessage, false otherwise.
- */
-function isValidClientMessage(msg: unknown): msg is ClientMessage {
-  if (typeof msg !== "object" || msg === null) return false;
-  const m = msg as Record<string, unknown>;
-  if (typeof m.type !== "string") return false;
-
-  switch (m.type) {
-    case MessageTypes.JOIN:
-      return (
-        typeof m.payload === "object" &&
-        m.payload !== null &&
-        typeof (m.payload as Record<string, unknown>).name === "string"
-      );
-    case MessageTypes.ACTION:
-      return (
-        typeof m.payload === "object" &&
-        m.payload !== null &&
-        typeof (m.payload as Record<string, unknown>).type === "string"
-      );
-    case MessageTypes.PING:
-      return (
-        typeof m.payload === "object" &&
-        m.payload !== null &&
-        typeof (m.payload as Record<string, unknown>).id === "string" &&
-        typeof (m.payload as Record<string, unknown>).timestamp === "number"
-      );
-    case MessageTypes.ASSETS_LOADED:
-      return m.payload === true;
-    default:
-      return false;
-  }
-}
-
 /**
  * React context provider that turns a React Native TV app into a local game server.
  *
@@ -193,15 +161,11 @@ export function GameHostProvider<S extends IGameState, A extends IAction>({
   // 2. Start WebSocket Server (Convention: HTTP port + 2, avoids Metro on 8081)
   const wsServer = useRef<GameWebSocketServer | null>(null);
 
-  // Track active sessions: secret -> socketId
-  const sessions = useRef<Map<string, string>>(new Map());
-
-  // Reverse lookup: socketId -> secret (for disconnect resolution)
-  const reverseMap = useRef<Map<string, string>>(new Map());
-
-  // Stale player cleanup timers: playerId -> timer
-  const cleanupTimers = useRef<Map<string, ReturnType<typeof setTimeout>>>(
-    new Map(),
+  const sessionManager = useRef(
+    new HostSessionManager({
+      getDisconnectTimeout: () =>
+        configRef.current.disconnectTimeout ?? DEFAULT_DISCONNECT_TIMEOUT,
+    }),
   );
 
   // Track socket IDs that have received their WELCOME message
@@ -212,19 +176,13 @@ export function GameHostProvider<S extends IGameState, A extends IAction>({
     Map<string, { playerId: string; isReconnect: boolean }>
   >(new Map());
 
-  // Cache: socketId -> playerId (avoids async derivation in hot paths)
-  const socketIdToPlayerId = useRef<Map<string, string>>(new Map());
-
   // Track which players have finished loading assets
   const assetsLoaded = useRef<Map<string, boolean>>(new Map());
 
   // Queue of actions dispatched since last broadcast (for STATE_UPDATE.action)
   const actionQueue = useRef<unknown[]>([]);
 
-  // Rate limiting: track action count per socket
-  const rateLimits = useRef<
-    Map<string, { count: number; windowStart: number }>
-  >(new Map());
+  const rateLimiter = useRef(new ActionRateLimiter());
 
   useEffect(() => {
     const port = config.wsPort || httpPort + DEFAULT_WS_PORT_OFFSET;
@@ -274,7 +232,11 @@ export function GameHostProvider<S extends IGameState, A extends IAction>({
           const { secret, ...payload } = message.payload;
 
           // Validate secret format
-          if (!secret || !isValidSecret(secret)) {
+          if (
+            !secret ||
+            typeof secret !== "string" ||
+            !isValidSecret(secret)
+          ) {
             server.send(socketId, {
               type: MessageTypes.ERROR,
               payload: {
@@ -285,80 +247,38 @@ export function GameHostProvider<S extends IGameState, A extends IAction>({
             return;
           }
 
-          // Async dual-derivation: try SHA-256 first, fall back to legacy
-          derivePlayerId(secret).then((hashedId) => {
-            let playerId = hashedId;
-
-            // Migration: if a player exists under the legacy ID, use that instead
-            const legacyId = derivePlayerIdLegacy(secret);
-            if (
-              !stateRef.current.players[playerId] &&
-              stateRef.current.players[legacyId]
-            ) {
-              playerId = legacyId;
-            }
-
-            // Cache the resolved playerId for this socket
-            socketIdToPlayerId.current.set(socketId, playerId);
-
-            // Update session maps
-            sessions.current.set(secret, socketId);
-            reverseMap.current.set(socketId, secret);
-
-            // Cancel any pending cleanup timer for this player
-            const existingTimer = cleanupTimers.current.get(playerId);
-            if (existingTimer) {
-              clearTimeout(existingTimer);
-              cleanupTimers.current.delete(playerId);
-            }
-
-            // Check if this is a returning player
-            const existingPlayer = stateRef.current.players[playerId];
-            if (existingPlayer) {
-              // Reconnection — restore existing player
-              dispatch({
-                type: InternalActionTypes.PLAYER_RECONNECTED,
-                payload: { playerId },
-              } as InternalAction<S>);
-
-              // Reset assets loaded status on reconnect
-              assetsLoaded.current.set(playerId, false);
+          sessionManager.current
+            .handleJoin<S>(
+              socketId,
+              message.payload as JoinSessionPayload,
+              () => stateRef.current.players,
+            )
+            .then(({ playerId, isReconnect, action }) => {
+              dispatch(action);
 
-              // Queue RECONNECTED message
-              pendingWelcome.current.set(socketId, {
-                playerId,
-                isReconnect: true,
-              });
-            } else {
-              // New player
-              dispatch({
-                type: InternalActionTypes.PLAYER_JOINED,
-                payload: { id: playerId, ...payload },
-              } as InternalAction<S>);
-
-              // Initialize assets loaded status
+              // Initialize/reset assets loaded status
               assetsLoaded.current.set(playerId, false);
 
-              // Queue WELCOME message
+              // Queue WELCOME/RECONNECTED message
               pendingWelcome.current.set(socketId, {
                 playerId,
-                isReconnect: false,
+                isReconnect,
               });
-            }
 
-            configRef.current.onPlayerJoined?.(playerId, payload.name);
-          }).catch((err) => {
-            if (configRef.current.debug) {
-              console.error("[GameHost] Failed to derive player ID:", err);
-            }
-            server.send(socketId, {
-              type: MessageTypes.ERROR,
-              payload: {
-                code: "JOIN_FAILED",
-                message: "Failed to process join request",
-              },
+              configRef.current.onPlayerJoined?.(playerId, payload.name);
+            })
+            .catch((err) => {
+              if (configRef.current.debug) {
+                console.error("[GameHost] Failed to derive player ID:", err);
+              }
+              server.send(socketId, {
+                type: MessageTypes.ERROR,
+                payload: {
+                  code: "JOIN_FAILED",
+                  message: "Failed to process join request",
+                },
+              });
             });
-          });
           break;
         }
 
@@ -390,14 +310,7 @@ export function GameHostProvider<S extends IGameState, A extends IAction>({
           }
 
           // Rate limiting
-          const now = Date.now();
-          let rateInfo = rateLimits.current.get(socketId);
-          if (!rateInfo || now - rateInfo.windowStart > RATE_LIMIT_WINDOW) {
-            rateInfo = { count: 0, windowStart: now };
-            rateLimits.current.set(socketId, rateInfo);
-          }
-          rateInfo.count++;
-          if (rateInfo.count > RATE_LIMIT_MAX) {
+          if (!rateLimiter.current.record(socketId).allowed) {
             if (configRef.current.debug)
               console.warn(`[GameHost] Rate limited ${socketId}`);
             server.send(socketId, {
@@ -411,7 +324,8 @@ export function GameHostProvider<S extends IGameState, A extends IAction>({
           }
 
           // Use cached playerId (populated at JOIN time)
-          const resolvedPlayerId = socketIdToPlayerId.current.get(socketId);
+          const resolvedPlayerId =
+            sessionManager.current.getPlayerIdForSocket(socketId);
           dispatch({ ...actionPayload, playerId: resolvedPlayerId });
           actionQueue.current.push(actionPayload);
           break;
@@ -429,7 +343,8 @@ export function GameHostProvider<S extends IGameState, A extends IAction>({
           break;
 
         case MessageTypes.ASSETS_LOADED: {
-          const loadedPlayerId = socketIdToPlayerId.current.get(socketId);
+          const loadedPlayerId =
+            sessionManager.current.getPlayerIdForSocket(socketId);
           if (loadedPlayerId) {
             assetsLoaded.current.set(loadedPlayerId, true);
             if (configRef.current.debug)
@@ -446,48 +361,36 @@ export function GameHostProvider<S extends IGameState, A extends IAction>({
 
       welcomedClients.current.delete(socketId);
 
-      // Use cached playerId
-      const playerId = socketIdToPlayerId.current.get(socketId);
-      socketIdToPlayerId.current.delete(socketId);
-
-      // Clean up reverse map
-      const secret = reverseMap.current.get(socketId);
-      reverseMap.current.delete(socketId);
-
       // Clean up rate limits
-      rateLimits.current.delete(socketId);
+      rateLimiter.current.reset(socketId);
 
-      if (!playerId || !secret) return; // Unknown socket, nothing to do
+      const result = sessionManager.current.handleDisconnect<S>(socketId);
+      if (result.kind === "unknown") return; // Unknown socket, nothing to do
 
       // Clean up assets loaded tracking
-      assetsLoaded.current.delete(playerId);
+      assetsLoaded.current.delete(result.playerId);
 
-      // RACE GUARD: Only mark as left if this socket is still the active one for this secret
-      if (sessions.current.get(secret) !== socketId) {
+      if (result.kind === "stale") {
         // Player already reconnected on a newer socket — skip
         return;
       }
 
       // Mark disconnected (don't remove from sessions — allow reconnect)
-      dispatch({
-        type: InternalActionTypes.PLAYER_LEFT,
-        payload: { playerId },
-      } as InternalAction<S>);
+      dispatch(result.action);
 
-      configRef.current.onPlayerLeft?.(playerId);
+      configRef.current.onPlayerLeft?.(result.playerId);
 
       // Start stale player cleanup timer
-      const timeout =
-        configRef.current.disconnectTimeout ?? DEFAULT_DISCONNECT_TIMEOUT;
-      const timer = setTimeout(() => {
-        cleanupTimers.current.delete(playerId);
-        sessions.current.delete(secret);
-        dispatch({
-          type: InternalActionTypes.PLAYER_REMOVED,
-          payload: { playerId },
-        } as InternalAction<S>);
-      }, timeout);
-      cleanupTimers.current.set(playerId, timer);
+      sessionManager.current.scheduleRemoval(
+        result.playerId,
+        result.secret,
+        (playerId) => {
+          dispatch({
+            type: InternalActionTypes.PLAYER_REMOVED,
+            payload: { playerId },
+          } as InternalAction<S>);
+        },
+      );
     });
 
     server.on("error", (error) => {
@@ -498,50 +401,42 @@ export function GameHostProvider<S extends IGameState, A extends IAction>({
 
     return () => {
       server.stop();
-      for (const timer of cleanupTimers.current.values()) {
-        clearTimeout(timer);
-      }
-      cleanupTimers.current.clear();
+      sessionManager.current.clearRemovalTimers();
     };
   }, []); // Run once on mount
 
   // 3. Throttled State Broadcasts (~30fps)
   // Batches rapid state changes so at most one broadcast is sent per ~33ms frame,
   // reducing serialization overhead and network traffic for fast-updating games.
-  const broadcastTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const broadcastScheduler = useRef(
+    new BroadcastScheduler({
+      stateThrottleMs: config.stateThrottleMs,
+    }),
+  );
+
+  useEffect(() => {
+    broadcastScheduler.current.setStateThrottleMs(
+      config.stateThrottleMs ?? DEFAULT_STATE_THROTTLE_MS,
+    );
+  }, [config.stateThrottleMs]);
 
   const broadcastState = useCallback(() => {
     if (wsServer.current) {
       const actions = actionQueue.current;
       actionQueue.current = [];
-      wsServer.current.broadcast({
-        type: MessageTypes.STATE_UPDATE,
-        payload: {
-          newState: stateRef.current,
-          timestamp: Date.now(),
-          ...(actions.length === 1
-            ? { action: actions[0] }
-            : actions.length > 1
-              ? { action: actions }
-              : {}),
-        },
-      });
+      wsServer.current.broadcast(
+        createStateUpdateMessage(stateRef.current, actions),
+      );
     }
   }, []);
 
   useEffect(() => {
     // Cancel any pending broadcast and schedule a fresh one.
     // This ensures the broadcast always uses the latest stateRef.
-    if (broadcastTimer.current) {
-      clearTimeout(broadcastTimer.current);
-    }
-    broadcastTimer.current = setTimeout(broadcastState, 33); // ~30fps
+    broadcastScheduler.current.schedule(broadcastState);
 
     return () => {
-      if (broadcastTimer.current) {
-        clearTimeout(broadcastTimer.current);
-        broadcastTimer.current = null;
-      }
+      broadcastScheduler.current.cancel();
     };
   }, [state, broadcastState]);
 

package/src/rate-limiter.ts

@@ -0,0 +1,66 @@
+/** Maximum actions per rate-limit window. */
+export const RATE_LIMIT_MAX = 60;
+
+/** Rate-limit window duration (ms). */
+export const RATE_LIMIT_WINDOW = 1000;
+
+export interface RateLimitInfo {
+  count: number;
+  windowStart: number;
+}
+
+export interface RateLimitResult extends RateLimitInfo {
+  allowed: boolean;
+}
+
+export interface ActionRateLimiterOptions {
+  maxActions?: number;
+  windowMs?: number;
+  now?: () => number;
+}
+
+/**
+ * Per-socket action limiter that preserves the host provider's original
+ * fixed-window algorithm.
+ */
+export class ActionRateLimiter {
+  private readonly maxActions: number;
+  private readonly windowMs: number;
+  private readonly now: () => number;
+  private readonly limits = new Map<string, RateLimitInfo>();
+
+  constructor(options: ActionRateLimiterOptions = {}) {
+    this.maxActions = options.maxActions ?? RATE_LIMIT_MAX;
+    this.windowMs = options.windowMs ?? RATE_LIMIT_WINDOW;
+    this.now = options.now ?? Date.now;
+  }
+
+  record(socketId: string): RateLimitResult {
+    const now = this.now();
+    let rateInfo = this.limits.get(socketId);
+
+    if (!rateInfo || now - rateInfo.windowStart > this.windowMs) {
+      rateInfo = { count: 0, windowStart: now };
+      this.limits.set(socketId, rateInfo);
+    }
+
+    rateInfo.count++;
+
+    return {
+      ...rateInfo,
+      allowed: rateInfo.count <= this.maxActions,
+    };
+  }
+
+  reset(socketId: string): void {
+    this.limits.delete(socketId);
+  }
+
+  clear(): void {
+    this.limits.clear();
+  }
+
+  get(socketId: string): RateLimitInfo | undefined {
+    return this.limits.get(socketId);
+  }
+}

package/src/session-manager.ts

@@ -0,0 +1,192 @@
+import {
+  DEFAULT_DISCONNECT_TIMEOUT,
+  InternalActionTypes,
+  derivePlayerId,
+  derivePlayerIdLegacy,
+  type IGameState,
+  type InternalAction,
+} from "@couch-kit/core";
+
+export interface SessionTimerScheduler<TTimer> {
+  setTimeout(callback: () => void, delayMs: number): TTimer;
+  clearTimeout(timer: TTimer): void;
+}
+
+const defaultSessionTimerScheduler: SessionTimerScheduler<
+  ReturnType<typeof setTimeout>
+> = {
+  setTimeout: (callback, delayMs) => setTimeout(callback, delayMs),
+  clearTimeout: (timer) => clearTimeout(timer),
+};
+
+export interface JoinSessionPayload {
+  name: string;
+  avatar?: string;
+  secret: string;
+}
+
+export interface HostSessionManagerOptions<TTimer> {
+  disconnectTimeout?: number;
+  getDisconnectTimeout?: () => number;
+  scheduler?: SessionTimerScheduler<TTimer>;
+  derivePlayerId?: (secret: string) => Promise<string>;
+  derivePlayerIdLegacy?: (secret: string) => string;
+}
+
+export type JoinSessionResult<S extends IGameState> = {
+  playerId: string;
+  socketId: string;
+  secret: string;
+  isReconnect: boolean;
+  action: InternalAction<S>;
+};
+
+export type DisconnectSessionResult<S extends IGameState> =
+  | { kind: "unknown" }
+  | { kind: "stale"; playerId: string; secret: string }
+  | {
+      kind: "left";
+      playerId: string;
+      secret: string;
+      action: InternalAction<S>;
+    };
+
+type PlayersSource<S extends IGameState> =
+  | S["players"]
+  | (() => S["players"]);
+
+/**
+ * Tracks host player sessions by secret and socket ID, including reconnects and
+ * delayed cleanup of disconnected players.
+ */
+export class HostSessionManager<
+  TTimer = ReturnType<typeof setTimeout>,
+> {
+  private readonly sessions = new Map<string, string>();
+  private readonly reverseMap = new Map<string, string>();
+  private readonly cleanupTimers = new Map<string, TTimer>();
+  private readonly socketIdToPlayerId = new Map<string, string>();
+  private readonly scheduler: SessionTimerScheduler<TTimer>;
+  private readonly getDisconnectTimeout: () => number;
+  private readonly derivePlayerIdFn: (secret: string) => Promise<string>;
+  private readonly derivePlayerIdLegacyFn: (secret: string) => string;
+
+  constructor(options: HostSessionManagerOptions<TTimer> = {}) {
+    this.scheduler =
+      options.scheduler ??
+      (defaultSessionTimerScheduler as unknown as SessionTimerScheduler<TTimer>);
+    this.getDisconnectTimeout =
+      options.getDisconnectTimeout ??
+      (() => options.disconnectTimeout ?? DEFAULT_DISCONNECT_TIMEOUT);
+    this.derivePlayerIdFn = options.derivePlayerId ?? derivePlayerId;
+    this.derivePlayerIdLegacyFn =
+      options.derivePlayerIdLegacy ?? derivePlayerIdLegacy;
+  }
+
+  async handleJoin<S extends IGameState>(
+    socketId: string,
+    payload: JoinSessionPayload,
+    playersSource: PlayersSource<S>,
+  ): Promise<JoinSessionResult<S>> {
+    const hashedId = await this.derivePlayerIdFn(payload.secret);
+    const players =
+      typeof playersSource === "function" ? playersSource() : playersSource;
+    let playerId = hashedId;
+
+    const legacyId = this.derivePlayerIdLegacyFn(payload.secret);
+    if (!players[playerId] && players[legacyId]) {
+      playerId = legacyId;
+    }
+
+    this.socketIdToPlayerId.set(socketId, playerId);
+    this.sessions.set(payload.secret, socketId);
+    this.reverseMap.set(socketId, payload.secret);
+    this.cancelRemoval(playerId);
+
+    const isReconnect = !!players[playerId];
+    const action = isReconnect
+      ? ({
+          type: InternalActionTypes.PLAYER_RECONNECTED,
+          payload: { playerId },
+        } as InternalAction<S>)
+      : ({
+          type: InternalActionTypes.PLAYER_JOINED,
+          payload: { id: playerId, name: payload.name, avatar: payload.avatar },
+        } as InternalAction<S>);
+
+    return {
+      playerId,
+      socketId,
+      secret: payload.secret,
+      isReconnect,
+      action,
+    };
+  }
+
+  handleDisconnect<S extends IGameState>(
+    socketId: string,
+  ): DisconnectSessionResult<S> {
+    const playerId = this.socketIdToPlayerId.get(socketId);
+    this.socketIdToPlayerId.delete(socketId);
+
+    const secret = this.reverseMap.get(socketId);
+    this.reverseMap.delete(socketId);
+
+    if (!playerId || !secret) return { kind: "unknown" };
+
+    if (this.sessions.get(secret) !== socketId) {
+      return { kind: "stale", playerId, secret };
+    }
+
+    return {
+      kind: "left",
+      playerId,
+      secret,
+      action: {
+        type: InternalActionTypes.PLAYER_LEFT,
+        payload: { playerId },
+      } as InternalAction<S>,
+    };
+  }
+
+  scheduleRemoval(
+    playerId: string,
+    secret: string,
+    onRemove: (playerId: string) => void,
+  ): void {
+    const timer = this.scheduler.setTimeout(() => {
+      this.cleanupTimers.delete(playerId);
+      this.sessions.delete(secret);
+      onRemove(playerId);
+    }, this.getDisconnectTimeout());
+
+    this.cleanupTimers.set(playerId, timer);
+  }
+
+  cancelRemoval(playerId: string): void {
+    const existingTimer = this.cleanupTimers.get(playerId);
+    if (existingTimer) {
+      this.scheduler.clearTimeout(existingTimer);
+      this.cleanupTimers.delete(playerId);
+    }
+  }
+
+  clearRemovalTimers(): void {
+    for (const timer of this.cleanupTimers.values()) {
+      this.scheduler.clearTimeout(timer);
+    }
+    this.cleanupTimers.clear();
+  }
+
+  getPlayerIdForSocket(socketId: string): string | undefined {
+    return this.socketIdToPlayerId.get(socketId);
+  }
+
+  getSocketIdForSecret(secret: string): string | undefined {
+    return this.sessions.get(secret);
+  }
+
+  hasPendingRemoval(playerId: string): boolean {
+    return this.cleanupTimers.has(playerId);
+  }
+}