@couch-kit/runtime 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @couch-kit/runtime
 
+## 0.4.0
+
+### Minor Changes
+
+- [#206](https://github.com/faluciano/react-native-couch-kit/pull/206) [`9465677`](https://github.com/faluciano/react-native-couch-kit/commit/9465677b63ad58273b8c0dee98ebece5d477a074) Thanks [@faluciano](https://github.com/faluciano)! - Make state broadcasts a real throttle and harden JOIN handling.
+
+  - `BroadcastScheduler` no longer resets its timer on every change. It was a debounce: a host updating faster than `stateThrottleMs` sent nothing until the updates paused. The first change now opens a window and everything inside it is coalesced into one broadcast when the window closes.
+  - Projected games (`project`) no longer attach client actions to `STATE_UPDATE`. They leaked one player's action payload to every other player, which is what a projection exists to prevent.
+  - Actions that leave state unchanged are no longer queued for the next `STATE_UPDATE`, and the queue is capped. Previously they accumulated without bound until an unrelated change flushed them all.
+  - A JOIN whose socket closes while the player ID is being derived no longer touches session state. It used to cancel the player's pending removal (leaving a disconnected ghost forever) and could orphan their live connection. `HostSessionManager` gains `derivePlayerIdFor` and `registerJoin` for this; `handleJoin` is unchanged.
+  - JOIN fields are sanitized: the name is trimmed, capped at 64 characters and never blank; an avatar that is not a string of at most 16 KiB is dropped (the avatar is re-sent on every state update). A non-string `avatar` is rejected as `INVALID_MESSAGE`. New exports: `sanitizePlayerName`, `sanitizePlayerAvatar`, `MAX_PLAYER_NAME_LENGTH`, `MAX_PLAYER_AVATAR_LENGTH`, `DEFAULT_PLAYER_NAME`.
+
 ## 0.3.0
 
 ### Minor Changes

package/dist/index.cjs

@@ -39,18 +39,23 @@ var __export = (target, all) => {
 // src/index.ts
 var exports_src = {};
 __export(exports_src, {
-  isValidClientMessage: () => isValidClientMessage,
-  frameByteLength: () => frameByteLength,
-  createStateUpdateMessage: () => createStateUpdateMessage,
-  authorizeClientAction: () => authorizeClientAction,
-  RATE_LIMIT_WINDOW: () => RATE_LIMIT_WINDOW,
-  RATE_LIMIT_MAX: () => RATE_LIMIT_MAX,
-  HostSessionManager: () => HostSessionManager,
-  GameHostRuntime: () => GameHostRuntime,
-  DEFAULT_STATE_THROTTLE_MS: () => DEFAULT_STATE_THROTTLE_MS,
-  DEFAULT_MAX_MESSAGE_BYTES: () => DEFAULT_MAX_MESSAGE_BYTES,
+  ActionRateLimiter: () => ActionRateLimiter,
   BroadcastScheduler: () => BroadcastScheduler,
-  ActionRateLimiter: () => ActionRateLimiter
+  DEFAULT_MAX_MESSAGE_BYTES: () => DEFAULT_MAX_MESSAGE_BYTES,
+  DEFAULT_PLAYER_NAME: () => DEFAULT_PLAYER_NAME,
+  DEFAULT_STATE_THROTTLE_MS: () => DEFAULT_STATE_THROTTLE_MS,
+  GameHostRuntime: () => GameHostRuntime,
+  HostSessionManager: () => HostSessionManager,
+  MAX_PLAYER_AVATAR_LENGTH: () => MAX_PLAYER_AVATAR_LENGTH,
+  MAX_PLAYER_NAME_LENGTH: () => MAX_PLAYER_NAME_LENGTH,
+  RATE_LIMIT_MAX: () => RATE_LIMIT_MAX,
+  RATE_LIMIT_WINDOW: () => RATE_LIMIT_WINDOW,
+  authorizeClientAction: () => authorizeClientAction,
+  createStateUpdateMessage: () => createStateUpdateMessage,
+  frameByteLength: () => frameByteLength,
+  isValidClientMessage: () => isValidClientMessage,
+  sanitizePlayerAvatar: () => sanitizePlayerAvatar,
+  sanitizePlayerName: () => sanitizePlayerName
 });
 module.exports = __toCommonJS(exports_src);
 
@@ -92,19 +97,25 @@ class BroadcastScheduler {
   stateThrottleMs;
   scheduler;
   timer = null;
+  pending = null;
   constructor(options = {}) {
     this.stateThrottleMs = options.stateThrottleMs ?? DEFAULT_STATE_THROTTLE_MS;
     this.scheduler = options.scheduler ?? defaultTimerScheduler;
   }
   schedule(callback) {
-    this.cancel();
+    this.pending = callback;
+    if (this.timer !== null)
+      return;
     this.timer = this.scheduler.setTimeout(() => {
       this.timer = null;
-      callback();
+      const pending = this.pending;
+      this.pending = null;
+      pending?.();
     }, this.stateThrottleMs);
   }
   cancel() {
-    if (this.timer) {
+    this.pending = null;
+    if (this.timer !== null) {
       this.scheduler.clearTimeout(this.timer);
       this.timer = null;
     }
@@ -148,6 +159,26 @@ function frameByteLength(data) {
   }
   return bytes;
 }
+var MAX_PLAYER_NAME_LENGTH = 64;
+var MAX_PLAYER_AVATAR_LENGTH = 16 * 1024;
+var DEFAULT_PLAYER_NAME = "Player";
+function truncate(value, max) {
+  if (value.length <= max)
+    return value;
+  return Array.from(value.slice(0, max * 2)).slice(0, max).join("");
+}
+function sanitizePlayerName(name) {
+  const trimmed = truncate(name.trim(), MAX_PLAYER_NAME_LENGTH).trim();
+  return trimmed.length > 0 ? trimmed : DEFAULT_PLAYER_NAME;
+}
+function sanitizePlayerAvatar(avatar) {
+  if (typeof avatar !== "string")
+    return;
+  if (avatar.length === 0 || avatar.length > MAX_PLAYER_AVATAR_LENGTH) {
+    return;
+  }
+  return avatar;
+}
 function isValidClientMessage(msg) {
   if (typeof msg !== "object" || msg === null)
     return false;
@@ -155,8 +186,12 @@ function isValidClientMessage(msg) {
   if (typeof m.type !== "string")
     return false;
   switch (m.type) {
-    case import_core3.MessageTypes.JOIN:
-      return typeof m.payload === "object" && m.payload !== null && typeof m.payload.name === "string";
+    case import_core3.MessageTypes.JOIN: {
+      if (typeof m.payload !== "object" || m.payload === null)
+        return false;
+      const { name, avatar } = m.payload;
+      return typeof name === "string" && (avatar === undefined || avatar === null || typeof avatar === "string");
+    }
     case import_core3.MessageTypes.ACTION:
       return typeof m.payload === "object" && m.payload !== null && typeof m.payload.type === "string";
     case import_core3.MessageTypes.PING:
@@ -229,8 +264,14 @@ class HostSessionManager {
     this.derivePlayerIdFn = options.derivePlayerId ?? import_core4.derivePlayerId;
     this.derivePlayerIdLegacyFn = options.derivePlayerIdLegacy ?? import_core4.derivePlayerIdLegacy;
   }
+  derivePlayerIdFor(secret) {
+    return this.derivePlayerIdFn(secret);
+  }
   async handleJoin(socketId, payload, playersSource) {
     const hashedId = await this.derivePlayerIdFn(payload.secret);
+    return this.registerJoin(socketId, payload, hashedId, playersSource);
+  }
+  registerJoin(socketId, payload, hashedId, playersSource) {
     const players = typeof playersSource === "function" ? playersSource() : playersSource;
     let playerId = hashedId;
     const legacyId = this.derivePlayerIdLegacyFn(payload.secret);
@@ -322,6 +363,8 @@ class HostSessionManager {
 }
 
 // src/runtime.ts
+var MAX_QUEUED_ACTIONS = 64;
+
 class GameHostRuntime {
   config;
   reducer;
@@ -395,7 +438,7 @@ class GameHostRuntime {
     this.log(`[GameRuntime] Msg from ${connectionId}:`, message);
     switch (message.type) {
       case import_core5.MessageTypes.JOIN: {
-        const { secret, ...payload } = message.payload;
+        const { secret } = message.payload;
         if (!secret || typeof secret !== "string" || !import_core5.isValidSecret(secret)) {
           this.send(connectionId, {
             type: import_core5.MessageTypes.ERROR,
@@ -418,16 +461,21 @@ class GameHostRuntime {
         }
         this.pendingJoins.add(connectionId);
         try {
-          const { playerId, isReconnect, action } = await this.sessionManager.handleJoin(connectionId, message.payload, () => this.state.players);
+          const joinPayload = {
+            name: sanitizePlayerName(message.payload.name),
+            avatar: sanitizePlayerAvatar(message.payload.avatar),
+            secret
+          };
+          const hashedId = await this.sessionManager.derivePlayerIdFor(secret);
           if (this.activeConnections.get(connectionId) !== connectionGeneration) {
-            this.sessionManager.abandonConnection(connectionId);
             return;
           }
+          const { playerId, isReconnect, action } = this.sessionManager.registerJoin(connectionId, joinPayload, hashedId, this.state.players);
           this.applyAction(action);
           this.joinedConnections.add(connectionId);
           this.assetsLoaded.set(playerId, false);
           this.invokeLifecycleCallback("onPlayerJoined", this.config.onPlayerJoined ? () => {
-            this.config.onPlayerJoined?.(playerId, payload.name);
+            this.config.onPlayerJoined?.(playerId, joinPayload.name);
           } : undefined);
           if (isReconnect) {
             this.send(connectionId, {
@@ -487,11 +535,16 @@ class GameHostRuntime {
           });
           return;
         }
-        this.applyAction({
+        const changed = this.applyAction({
           ...actionPayload,
           playerId: authorization.playerId
         });
-        this.actionQueue.push(actionPayload);
+        if (changed && !this.config.project) {
+          this.actionQueue.push(actionPayload);
+          if (this.actionQueue.length > MAX_QUEUED_ACTIONS) {
+            this.actionQueue.shift();
+          }
+        }
         break;
       }
       case import_core5.MessageTypes.PING:
@@ -552,13 +605,14 @@ class GameHostRuntime {
   applyAction(action) {
     const nextState = this.reducer(this.state, action);
     if (Object.is(nextState, this.state))
-      return;
+      return false;
     this.state = nextState;
     this.stateDirty = true;
     for (const listener of this.listeners) {
       listener();
     }
     this.broadcastScheduler.schedule(this.broadcastState);
+    return true;
   }
   viewFor(playerId) {
     const project = this.config.project;
@@ -582,7 +636,7 @@ class GameHostRuntime {
         continue;
       entries.push({
         connectionId,
-        message: createStateUpdateMessage(this.viewFor(playerId), actions)
+        message: createStateUpdateMessage(this.viewFor(playerId), [])
       });
     }
     if (entries.length === 0)

package/dist/index.js

@@ -36,19 +36,25 @@ class BroadcastScheduler {
   stateThrottleMs;
   scheduler;
   timer = null;
+  pending = null;
   constructor(options = {}) {
     this.stateThrottleMs = options.stateThrottleMs ?? DEFAULT_STATE_THROTTLE_MS;
     this.scheduler = options.scheduler ?? defaultTimerScheduler;
   }
   schedule(callback) {
-    this.cancel();
+    this.pending = callback;
+    if (this.timer !== null)
+      return;
     this.timer = this.scheduler.setTimeout(() => {
       this.timer = null;
-      callback();
+      const pending = this.pending;
+      this.pending = null;
+      pending?.();
     }, this.stateThrottleMs);
   }
   cancel() {
-    if (this.timer) {
+    this.pending = null;
+    if (this.timer !== null) {
       this.scheduler.clearTimeout(this.timer);
       this.timer = null;
     }
@@ -92,6 +98,26 @@ function frameByteLength(data) {
   }
   return bytes;
 }
+var MAX_PLAYER_NAME_LENGTH = 64;
+var MAX_PLAYER_AVATAR_LENGTH = 16 * 1024;
+var DEFAULT_PLAYER_NAME = "Player";
+function truncate(value, max) {
+  if (value.length <= max)
+    return value;
+  return Array.from(value.slice(0, max * 2)).slice(0, max).join("");
+}
+function sanitizePlayerName(name) {
+  const trimmed = truncate(name.trim(), MAX_PLAYER_NAME_LENGTH).trim();
+  return trimmed.length > 0 ? trimmed : DEFAULT_PLAYER_NAME;
+}
+function sanitizePlayerAvatar(avatar) {
+  if (typeof avatar !== "string")
+    return;
+  if (avatar.length === 0 || avatar.length > MAX_PLAYER_AVATAR_LENGTH) {
+    return;
+  }
+  return avatar;
+}
 function isValidClientMessage(msg) {
   if (typeof msg !== "object" || msg === null)
     return false;
@@ -99,8 +125,12 @@ function isValidClientMessage(msg) {
   if (typeof m.type !== "string")
     return false;
   switch (m.type) {
-    case MessageTypes2.JOIN:
-      return typeof m.payload === "object" && m.payload !== null && typeof m.payload.name === "string";
+    case MessageTypes2.JOIN: {
+      if (typeof m.payload !== "object" || m.payload === null)
+        return false;
+      const { name, avatar } = m.payload;
+      return typeof name === "string" && (avatar === undefined || avatar === null || typeof avatar === "string");
+    }
     case MessageTypes2.ACTION:
       return typeof m.payload === "object" && m.payload !== null && typeof m.payload.type === "string";
     case MessageTypes2.PING:
@@ -184,8 +214,14 @@ class HostSessionManager {
     this.derivePlayerIdFn = options.derivePlayerId ?? derivePlayerId;
     this.derivePlayerIdLegacyFn = options.derivePlayerIdLegacy ?? derivePlayerIdLegacy;
   }
+  derivePlayerIdFor(secret) {
+    return this.derivePlayerIdFn(secret);
+  }
   async handleJoin(socketId, payload, playersSource) {
     const hashedId = await this.derivePlayerIdFn(payload.secret);
+    return this.registerJoin(socketId, payload, hashedId, playersSource);
+  }
+  registerJoin(socketId, payload, hashedId, playersSource) {
     const players = typeof playersSource === "function" ? playersSource() : playersSource;
     let playerId = hashedId;
     const legacyId = this.derivePlayerIdLegacyFn(payload.secret);
@@ -277,6 +313,8 @@ class HostSessionManager {
 }
 
 // src/runtime.ts
+var MAX_QUEUED_ACTIONS = 64;
+
 class GameHostRuntime {
   config;
   reducer;
@@ -350,7 +388,7 @@ class GameHostRuntime {
     this.log(`[GameRuntime] Msg from ${connectionId}:`, message);
     switch (message.type) {
       case MessageTypes3.JOIN: {
-        const { secret, ...payload } = message.payload;
+        const { secret } = message.payload;
         if (!secret || typeof secret !== "string" || !isValidSecret(secret)) {
           this.send(connectionId, {
             type: MessageTypes3.ERROR,
@@ -373,16 +411,21 @@ class GameHostRuntime {
         }
         this.pendingJoins.add(connectionId);
         try {
-          const { playerId, isReconnect, action } = await this.sessionManager.handleJoin(connectionId, message.payload, () => this.state.players);
+          const joinPayload = {
+            name: sanitizePlayerName(message.payload.name),
+            avatar: sanitizePlayerAvatar(message.payload.avatar),
+            secret
+          };
+          const hashedId = await this.sessionManager.derivePlayerIdFor(secret);
           if (this.activeConnections.get(connectionId) !== connectionGeneration) {
-            this.sessionManager.abandonConnection(connectionId);
             return;
           }
+          const { playerId, isReconnect, action } = this.sessionManager.registerJoin(connectionId, joinPayload, hashedId, this.state.players);
           this.applyAction(action);
           this.joinedConnections.add(connectionId);
           this.assetsLoaded.set(playerId, false);
           this.invokeLifecycleCallback("onPlayerJoined", this.config.onPlayerJoined ? () => {
-            this.config.onPlayerJoined?.(playerId, payload.name);
+            this.config.onPlayerJoined?.(playerId, joinPayload.name);
           } : undefined);
           if (isReconnect) {
             this.send(connectionId, {
@@ -442,11 +485,16 @@ class GameHostRuntime {
           });
           return;
         }
-        this.applyAction({
+        const changed = this.applyAction({
           ...actionPayload,
           playerId: authorization.playerId
         });
-        this.actionQueue.push(actionPayload);
+        if (changed && !this.config.project) {
+          this.actionQueue.push(actionPayload);
+          if (this.actionQueue.length > MAX_QUEUED_ACTIONS) {
+            this.actionQueue.shift();
+          }
+        }
         break;
       }
       case MessageTypes3.PING:
@@ -507,13 +555,14 @@ class GameHostRuntime {
   applyAction(action) {
     const nextState = this.reducer(this.state, action);
     if (Object.is(nextState, this.state))
-      return;
+      return false;
     this.state = nextState;
     this.stateDirty = true;
     for (const listener of this.listeners) {
       listener();
     }
     this.broadcastScheduler.schedule(this.broadcastState);
+    return true;
   }
   viewFor(playerId) {
     const project = this.config.project;
@@ -537,7 +586,7 @@ class GameHostRuntime {
         continue;
       entries.push({
         connectionId,
-        message: createStateUpdateMessage(this.viewFor(playerId), actions)
+        message: createStateUpdateMessage(this.viewFor(playerId), [])
       });
     }
     if (entries.length === 0)
@@ -582,16 +631,21 @@ class GameHostRuntime {
   }
 }
 export {
-  isValidClientMessage,
-  frameByteLength,
-  createStateUpdateMessage,
-  authorizeClientAction,
-  RATE_LIMIT_WINDOW,
-  RATE_LIMIT_MAX,
-  HostSessionManager,
-  GameHostRuntime,
-  DEFAULT_STATE_THROTTLE_MS,
-  DEFAULT_MAX_MESSAGE_BYTES,
+  ActionRateLimiter,
   BroadcastScheduler,
-  ActionRateLimiter
+  DEFAULT_MAX_MESSAGE_BYTES,
+  DEFAULT_PLAYER_NAME,
+  DEFAULT_STATE_THROTTLE_MS,
+  GameHostRuntime,
+  HostSessionManager,
+  MAX_PLAYER_AVATAR_LENGTH,
+  MAX_PLAYER_NAME_LENGTH,
+  RATE_LIMIT_MAX,
+  RATE_LIMIT_WINDOW,
+  authorizeClientAction,
+  createStateUpdateMessage,
+  frameByteLength,
+  isValidClientMessage,
+  sanitizePlayerAvatar,
+  sanitizePlayerName
 };

package/lib/broadcast-scheduler.d.ts

@@ -13,13 +13,19 @@ export interface BroadcastSchedulerOptions<TTimer> {
     scheduler?: TimerScheduler<TTimer>;
 }
 /**
- * Debounced state-broadcast scheduler used by the authoritative runtime.
- * Rapid state changes are coalesced into one broadcast after the latest change.
+ * Throttled state-broadcast scheduler used by the authoritative runtime.
+ *
+ * The first change opens a window of `stateThrottleMs`; every change inside it
+ * is coalesced into the single broadcast that fires when the window closes.
+ * The window is never extended by later changes, so a host that updates
+ * faster than the throttle still broadcasts once per window instead of being
+ * starved until the updates pause.
  */
 export declare class BroadcastScheduler<TTimer = ReturnType<typeof setTimeout>> {
     private stateThrottleMs;
     private readonly scheduler;
     private timer;
+    private pending;
     constructor(options?: BroadcastSchedulerOptions<TTimer>);
     schedule(callback: () => void): void;
     cancel(): void;

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;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"}
+{"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;;;;;;;;GAQG;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;IACpC,OAAO,CAAC,OAAO,CAA6B;IAE5C,YAAY,OAAO,GAAE,yBAAyB,CAAC,MAAM,CAAM,EAK1D;IAED,QAAQ,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAWnC;IAED,MAAM,IAAI,IAAI,CAMb;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/message-validation.d.ts

@@ -14,6 +14,26 @@ export declare const DEFAULT_MAX_MESSAGE_BYTES: number;
  * encoder buffer, so an oversized frame can be rejected cheaply.
  */
 export declare function frameByteLength(data: string | ArrayBuffer): number;
+/** Longest player display name the runtime stores; longer names are truncated. */
+export declare const MAX_PLAYER_NAME_LENGTH = 64;
+/**
+ * Longest avatar string the runtime stores. The avatar is part of game state,
+ * so it is re-sent to every player on every state update; anything larger than
+ * a small icon is dropped rather than paid for on each broadcast.
+ */
+export declare const MAX_PLAYER_AVATAR_LENGTH: number;
+/** Display name used when a JOIN supplies a blank one. */
+export declare const DEFAULT_PLAYER_NAME = "Player";
+/**
+ * Normalizes the player-supplied name from a JOIN: trimmed, capped at
+ * {@link MAX_PLAYER_NAME_LENGTH}, and never blank.
+ */
+export declare function sanitizePlayerName(name: string): string;
+/**
+ * Normalizes the player-supplied avatar from a JOIN. Anything that is not a
+ * string of at most {@link MAX_PLAYER_AVATAR_LENGTH} characters is dropped.
+ */
+export declare function sanitizePlayerAvatar(avatar: unknown): string | undefined;
 type ClientMessageOf<TType extends ClientMessage["type"]> = Extract<ClientMessage, {
     type: TType;
 }>;

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

@@ -1 +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;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,QAAa,CAAC;AAEpD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,MAAM,CAmBlE;AAED,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"}
+{"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;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,QAAa,CAAC;AAEpD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,MAAM,CAmBlE;AAED,kFAAkF;AAClF,eAAO,MAAM,sBAAsB,KAAK,CAAC;AAEzC;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,QAAY,CAAC;AAElD,0DAA0D;AAC1D,eAAO,MAAM,mBAAmB,WAAW,CAAC;AAW5C;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAGvD;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAMxE;AAED,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,CAgC/B"}

package/lib/runtime.d.ts

@@ -94,6 +94,7 @@ export declare class GameHostRuntime<S extends IGameState, A extends IAction> {
     handleError(error: Error): void;
     /** Cancels runtime timers and releases transport-specific state. */
     stop(): void;
+    /** @returns whether the action changed the canonical state. */
     private applyAction;
     /**
      * What `playerId` is allowed to see. Identity unless a projection is

package/lib/runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAAA,OAAO,EAML,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,OAAO,EACZ,KAAK,UAAU,EAEhB,MAAM,iBAAiB,CAAC;AAczB,kFAAkF;AAClF,MAAM,WAAW,gBAAgB;IAC/B,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,WAAW,CAAC;CACtB;AAED,8EAA8E;AAC9E,MAAM,WAAW,oBAAoB;IACnC,IAAI,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,IAAI,CAAC;IACvD,SAAS,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,CAAC;IACtC;;;;;;;;;OASG;IACH,QAAQ,CAAC,CAAC,OAAO,EAAE,SAAS,gBAAgB,EAAE,GAAG,IAAI,CAAC;CACvD;AAED,4EAA4E;AAC5E,MAAM,WAAW,qBAAqB,CACpC,CAAC,SAAS,UAAU,EACpB,CAAC,SAAS,OAAO;IAEjB,YAAY,EAAE,CAAC,CAAC;IAChB,OAAO,EAAE,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAC3B;;;;;;;;;;;;;;;;;;OAkBG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC;IAClD,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,mEAAmE;IACnE,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,sDAAsD;IACtD,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,cAAc,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC1D,YAAY,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IAC1C,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CAClC;AAED;;;GAGG;AACH,qBAAa,eAAe,CAAC,CAAC,SAAS,UAAU,EAAE,CAAC,SAAS,OAAO;IAClE,OAAO,CAAC,MAAM,CAA8B;IAC5C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwC;IAChE,OAAO,CAAC,KAAK,CAAI;IACjB,OAAO,CAAC,SAAS,CAA8B;IAC/C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAyB;IACnD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAqB;IACpD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA2B;IACvD,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAqB;IACxD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA8B;IAC3D,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAA6B;IAC/D,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAqB;IACvD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAqB;IAClD,OAAO,CAAC,WAAW,CAAiB;IACpC,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,wBAAwB,CAAK;IAErC,YACE,MAAM,EAAE,qBAAqB,CAAC,CAAC,EAAE,CAAC,CAAC,EACnC,SAAS,GAAE,oBAAoB,GAAG,IAAW,EAa9C;IAED,oDAAoD;IACpD,QAAQ,CAAC,QAAQ,QAAO,CAAC,CAAe;IAExC,6CAA6C;IAC7C,QAAQ,CAAC,SAAS,aAAc,MAAM,IAAI,KAAG,CAAC,MAAM,IAAI,CAAC,CAKvD;IAEF,0EAA0E;IAC1E,YAAY,CAAC,SAAS,EAAE,oBAAoB,GAAG,IAAI,GAAG,IAAI,CAKzD;IAED,2EAA2E;IAC3E,YAAY,CAAC,MAAM,EAAE,qBAAqB,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,IAAI,CAKtD;IAED,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,WAAY,CAAC,KAAG,IAAI,CAEnC;IAEF,8EAA8E;IAC9E,gBAAgB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAG3C;IAED,kEAAkE;IAC5D,aAAa,CACjB,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,OAAO,GAClB,OAAO,CAAC,IAAI,CAAC,CAqLf;IAED,4EAA4E;IAC5E,gBAAgB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CA+B3C;IAED,wEAAwE;IACxE,WAAW,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAG9B;IAED,oEAAoE;IACpE,IAAI,IAAI,IAAI,CAQX;IAED,OAAO,CAAC,WAAW;IAcnB;;;OAGG;IACH,OAAO,CAAC,OAAO;IAKf,OAAO,CAAC,QAAQ,CAAC,cAAc,CAmC7B;IAEF,OAAO,CAAC,IAAI;IAIZ,OAAO,CAAC,uBAAuB;IAgB/B,OAAO,CAAC,WAAW;IAcnB,OAAO,CAAC,GAAG;CAKZ"}
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"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"}

package/lib/session-manager.d.ts

@@ -49,7 +49,22 @@ export declare class HostSessionManager<TTimer = ReturnType<typeof setTimeout>>
     private readonly derivePlayerIdFn;
     private readonly derivePlayerIdLegacyFn;
     constructor(options?: HostSessionManagerOptions<TTimer>);
+    /**
+     * Derives the public player ID for a secret without touching session state.
+     *
+     * Split from {@link HostSessionManager.registerJoin} so a caller can check
+     * that the connection is still alive after the (asynchronous) hash and before
+     * anything is recorded — a join for a socket that already closed must not
+     * displace the player's live session or cancel their pending removal.
+     */
+    derivePlayerIdFor(secret: string): Promise<string>;
     handleJoin<S extends IGameState>(socketId: string, payload: JoinSessionPayload, playersSource: PlayersSource<S>): Promise<JoinSessionResult<S>>;
+    /**
+     * Records a join whose player ID was already derived with
+     * {@link HostSessionManager.derivePlayerIdFor}. Synchronous, so the session
+     * maps and the removal timer change atomically with the caller's own checks.
+     */
+    registerJoin<S extends IGameState>(socketId: string, payload: JoinSessionPayload, hashedId: string, playersSource: PlayersSource<S>): JoinSessionResult<S>;
     handleDisconnect<S extends IGameState>(socketId: string): DisconnectSessionResult<S>;
     scheduleRemoval(playerId: string, secret: string, onRemove: (playerId: string) => void): void;
     cancelRemoval(playerId: string): void;

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

@@ -1 +1 @@
-{"version":3,"file":"session-manager.d.ts","sourceRoot":"","sources":["../src/session-manager.ts"],"names":[],"mappings":"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"}
+{"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.3.0",
+  "version": "0.4.0",
   "publishConfig": {
     "access": "public",
     "provenance": true

package/src/broadcast-scheduler.ts

@@ -24,13 +24,19 @@ export interface BroadcastSchedulerOptions<TTimer> {
 }
 
 /**
- * Debounced state-broadcast scheduler used by the authoritative runtime.
- * Rapid state changes are coalesced into one broadcast after the latest change.
+ * Throttled state-broadcast scheduler used by the authoritative runtime.
+ *
+ * The first change opens a window of `stateThrottleMs`; every change inside it
+ * is coalesced into the single broadcast that fires when the window closes.
+ * The window is never extended by later changes, so a host that updates
+ * faster than the throttle still broadcasts once per window instead of being
+ * starved until the updates pause.
  */
 export class BroadcastScheduler<TTimer = ReturnType<typeof setTimeout>> {
   private stateThrottleMs: number;
   private readonly scheduler: TimerScheduler<TTimer>;
   private timer: TTimer | null = null;
+  private pending: (() => void) | null = null;
 
   constructor(options: BroadcastSchedulerOptions<TTimer> = {}) {
     this.stateThrottleMs = options.stateThrottleMs ?? DEFAULT_STATE_THROTTLE_MS;
@@ -40,15 +46,21 @@ export class BroadcastScheduler<TTimer = ReturnType<typeof setTimeout>> {
   }
 
   schedule(callback: () => void): void {
-    this.cancel();
+    // The latest callback wins, but the window opened by the first call stands.
+    this.pending = callback;
+    if (this.timer !== null) return;
+
     this.timer = this.scheduler.setTimeout(() => {
       this.timer = null;
-      callback();
+      const pending = this.pending;
+      this.pending = null;
+      pending?.();
     }, this.stateThrottleMs);
   }
 
   cancel(): void {
-    if (this.timer) {
+    this.pending = null;
+    if (this.timer !== null) {
       this.scheduler.clearTimeout(this.timer);
       this.timer = null;
     }

package/src/message-validation.ts

@@ -36,6 +36,49 @@ export function frameByteLength(data: string | ArrayBuffer): number {
   return bytes;
 }
 
+/** Longest player display name the runtime stores; longer names are truncated. */
+export const MAX_PLAYER_NAME_LENGTH = 64;
+
+/**
+ * Longest avatar string the runtime stores. The avatar is part of game state,
+ * so it is re-sent to every player on every state update; anything larger than
+ * a small icon is dropped rather than paid for on each broadcast.
+ */
+export const MAX_PLAYER_AVATAR_LENGTH = 16 * 1024;
+
+/** Display name used when a JOIN supplies a blank one. */
+export const DEFAULT_PLAYER_NAME = "Player";
+
+/** Truncates to `max` code points without splitting a surrogate pair. */
+function truncate(value: string, max: number): string {
+  if (value.length <= max) return value;
+  // Slice generously first so a huge string is not spread into an array.
+  return Array.from(value.slice(0, max * 2))
+    .slice(0, max)
+    .join("");
+}
+
+/**
+ * Normalizes the player-supplied name from a JOIN: trimmed, capped at
+ * {@link MAX_PLAYER_NAME_LENGTH}, and never blank.
+ */
+export function sanitizePlayerName(name: string): string {
+  const trimmed = truncate(name.trim(), MAX_PLAYER_NAME_LENGTH).trim();
+  return trimmed.length > 0 ? trimmed : DEFAULT_PLAYER_NAME;
+}
+
+/**
+ * Normalizes the player-supplied avatar from a JOIN. Anything that is not a
+ * string of at most {@link MAX_PLAYER_AVATAR_LENGTH} characters is dropped.
+ */
+export function sanitizePlayerAvatar(avatar: unknown): string | undefined {
+  if (typeof avatar !== "string") return undefined;
+  if (avatar.length === 0 || avatar.length > MAX_PLAYER_AVATAR_LENGTH) {
+    return undefined;
+  }
+  return avatar;
+}
+
 type ClientMessageOf<TType extends ClientMessage["type"]> = Extract<
   ClientMessage,
   { type: TType }
@@ -67,12 +110,14 @@ export function isValidClientMessage(
   if (typeof m.type !== "string") return false;
 
   switch (m.type) {
-    case MessageTypes.JOIN:
+    case MessageTypes.JOIN: {
+      if (typeof m.payload !== "object" || m.payload === null) return false;
+      const { name, avatar } = m.payload as Record<string, unknown>;
       return (
-        typeof m.payload === "object" &&
-        m.payload !== null &&
-        typeof (m.payload as Record<string, unknown>).name === "string"
+        typeof name === "string" &&
+        (avatar === undefined || avatar === null || typeof avatar === "string")
       );
+    }
     case MessageTypes.ACTION:
       return (
         typeof m.payload === "object" &&

package/src/runtime.ts

@@ -16,13 +16,24 @@ import {
   DEFAULT_STATE_THROTTLE_MS,
   createStateUpdateMessage,
 } from "./broadcast-scheduler.js";
-import { isValidClientMessage } from "./message-validation.js";
+import {
+  isValidClientMessage,
+  sanitizePlayerAvatar,
+  sanitizePlayerName,
+} from "./message-validation.js";
 import { ActionRateLimiter } from "./rate-limiter.js";
 import {
   HostSessionManager,
   type JoinSessionPayload,
 } from "./session-manager.js";
 
+/**
+ * Most client actions kept for the next `STATE_UPDATE`. A transport that is
+ * detached for a while must not grow the queue without bound; the newest
+ * actions are the ones a debug log wants.
+ */
+const MAX_QUEUED_ACTIONS = 64;
+
 /** One connection's share of a {@link GameRuntimeTransport.sendMany} delivery. */
 export interface AddressedMessage {
   connectionId: string;
@@ -192,7 +203,7 @@ export class GameHostRuntime<S extends IGameState, A extends IAction> {
 
     switch (message.type) {
       case MessageTypes.JOIN: {
-        const { secret, ...payload } = message.payload;
+        const { secret } = message.payload;
 
         if (!secret || typeof secret !== "string" || !isValidSecret(secret)) {
           this.send(connectionId, {
@@ -221,20 +232,30 @@ export class GameHostRuntime<S extends IGameState, A extends IAction> {
 
         this.pendingJoins.add(connectionId);
         try {
-          const { playerId, isReconnect, action } =
-            await this.sessionManager.handleJoin<S>(
-              connectionId,
-              message.payload as JoinSessionPayload,
-              () => this.state.players,
-            );
-
+          const joinPayload: JoinSessionPayload = {
+            name: sanitizePlayerName(message.payload.name),
+            avatar: sanitizePlayerAvatar(message.payload.avatar),
+            secret,
+          };
+          const hashedId = await this.sessionManager.derivePlayerIdFor(secret);
+
+          // The socket closed while the ID was being derived. Nothing has been
+          // recorded yet, so the player's previous session and any pending
+          // removal are left exactly as they were.
           if (
             this.activeConnections.get(connectionId) !== connectionGeneration
           ) {
-            this.sessionManager.abandonConnection(connectionId);
             return;
           }
 
+          const { playerId, isReconnect, action } =
+            this.sessionManager.registerJoin<S>(
+              connectionId,
+              joinPayload,
+              hashedId,
+              this.state.players,
+            );
+
           this.applyAction(action);
           this.joinedConnections.add(connectionId);
           this.assetsLoaded.set(playerId, false);
@@ -242,7 +263,7 @@ export class GameHostRuntime<S extends IGameState, A extends IAction> {
             "onPlayerJoined",
             this.config.onPlayerJoined
               ? () => {
-                  this.config.onPlayerJoined?.(playerId, payload.name);
+                  this.config.onPlayerJoined?.(playerId, joinPayload.name);
                 }
               : undefined,
           );
@@ -316,11 +337,20 @@ export class GameHostRuntime<S extends IGameState, A extends IAction> {
           return;
         }
 
-        this.applyAction({
+        const changed = this.applyAction({
           ...actionPayload,
           playerId: authorization.playerId,
         } as A);
-        this.actionQueue.push(actionPayload);
+        // Only actions that changed state ride along with the next update: a
+        // no-op schedules no broadcast, so queueing it would grow the queue
+        // until some unrelated change flushed the lot. Projected games never
+        // attach actions (see broadcastState), so nothing is queued for them.
+        if (changed && !this.config.project) {
+          this.actionQueue.push(actionPayload);
+          if (this.actionQueue.length > MAX_QUEUED_ACTIONS) {
+            this.actionQueue.shift();
+          }
+        }
         break;
       }
 
@@ -397,9 +427,10 @@ export class GameHostRuntime<S extends IGameState, A extends IAction> {
     this.transport = null;
   }
 
-  private applyAction(action: A | InternalAction<S>): void {
+  /** @returns whether the action changed the canonical state. */
+  private applyAction(action: A | InternalAction<S>): boolean {
     const nextState = this.reducer(this.state, action);
-    if (Object.is(nextState, this.state)) return;
+    if (Object.is(nextState, this.state)) return false;
 
     this.state = nextState;
     this.stateDirty = true;
@@ -409,6 +440,7 @@ export class GameHostRuntime<S extends IGameState, A extends IAction> {
     }
 
     this.broadcastScheduler.schedule(this.broadcastState);
+    return true;
   }
 
   /**
@@ -437,13 +469,16 @@ export class GameHostRuntime<S extends IGameState, A extends IAction> {
     // 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.
+    //
+    // No actions are attached: a player's action payload is exactly the kind
+    // of thing a projection exists to hide from everyone else.
     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),
+        message: createStateUpdateMessage(this.viewFor(playerId), []),
       });
     }
     if (entries.length === 0) return;

package/src/session-manager.ts

@@ -79,12 +79,38 @@ export class HostSessionManager<TTimer = ReturnType<typeof setTimeout>> {
       options.derivePlayerIdLegacy ?? derivePlayerIdLegacy;
   }
 
+  /**
+   * Derives the public player ID for a secret without touching session state.
+   *
+   * Split from {@link HostSessionManager.registerJoin} so a caller can check
+   * that the connection is still alive after the (asynchronous) hash and before
+   * anything is recorded — a join for a socket that already closed must not
+   * displace the player's live session or cancel their pending removal.
+   */
+  derivePlayerIdFor(secret: string): Promise<string> {
+    return this.derivePlayerIdFn(secret);
+  }
+
   async handleJoin<S extends IGameState>(
     socketId: string,
     payload: JoinSessionPayload,
     playersSource: PlayersSource<S>,
   ): Promise<JoinSessionResult<S>> {
     const hashedId = await this.derivePlayerIdFn(payload.secret);
+    return this.registerJoin<S>(socketId, payload, hashedId, playersSource);
+  }
+
+  /**
+   * Records a join whose player ID was already derived with
+   * {@link HostSessionManager.derivePlayerIdFor}. Synchronous, so the session
+   * maps and the removal timer change atomically with the caller's own checks.
+   */
+  registerJoin<S extends IGameState>(
+    socketId: string,
+    payload: JoinSessionPayload,
+    hashedId: string,
+    playersSource: PlayersSource<S>,
+  ): JoinSessionResult<S> {
     const players =
       typeof playersSource === "function" ? playersSource() : playersSource;
     let playerId = hashedId;