@colyseus/core 0.18.0 → 0.18.1

package/src/RoomMessages.ts

@@ -0,0 +1,342 @@
+import { decode, type Iterator } from '@colyseus/schema';
+import { unpack } from 'msgpackr';
+
+import { CloseCode, ErrorCode, Protocol, ResponseStatus, type MessageContext } from '@colyseus/shared-types';
+import { getMessageBytes } from './Protocol.ts';
+import { createNanoEvents } from './utils/nanoevents.ts';
+import { standardValidate, type StandardSchemaV1 } from './utils/StandardSchema.ts';
+import { isDevMode } from './utils/DevMode.ts';
+import { debugMessage, debugAndPrintError } from './Debug.ts';
+import { OnMessageException } from './errors/RoomExceptions.ts';
+import type { Client, ClientPrivate } from './Transport.ts';
+import type { Room } from './Room.ts';
+
+/** Normalize a thrown value into the `{ name, message, code? }` shape echoed in a
+ *  ROOM_RESPONSE error reply. */
+function toResponseError(e: any): { name: string; message: string; code?: any } {
+  if (e instanceof Error) {
+    const code = (e as any).code;
+    return (code !== undefined)
+      ? { name: e.name, message: e.message, code }
+      : { name: e.name, message: e.message };
+  }
+  return { name: "Error", message: String(e) };
+}
+
+// The handler's terminal action — NOT the wire ResponseStatus: `none` and
+// `resolved` both reply OK (plain return value vs `ctx.resolve(value)`), a
+// distinction a single OK can't carry; ERROR is never a handler decision
+// (thrown/no-handler). Projected onto ResponseStatus once, in onRequest's reply.
+const OUTCOME_NONE = 0, OUTCOME_REJECTED = 1, OUTCOME_RESOLVED = 2;
+
+/**
+ * Runtime {@link MessageContext} for a {@link Protocol.ROOM_REQUEST} dispatch.
+ * `reject`/`resolve` record the decision on the ctx; `onRequest` reads it after the
+ * handler returns, so a bare side-effecting call works as well as `return
+ * ctx.reject(r)` (the branded return is compile-time only — the runtime return is
+ * unused).
+ */
+class DispatchContext implements MessageContext {
+  readonly id: number | undefined;
+  _outcome = OUTCOME_NONE;
+  _reason: any = undefined;
+  _value: any = undefined;
+
+  constructor(id: number | undefined) {
+    this.id = id;
+  }
+
+  reject(reason?: any): any {
+    this._outcome = OUTCOME_REJECTED;
+    this._reason = reason;
+    return undefined;
+  }
+
+  resolve(value?: any): any {
+    this._outcome = OUTCOME_RESOLVED;
+    this._value = value;
+    return undefined;
+  }
+}
+
+/** Shared no-op context for fire-and-forget `ROOM_DATA` (no reply channel, so
+ *  `reject`/`resolve` go nowhere). `id` is `undefined`; zero per-message allocation. */
+const SEND_CONTEXT: MessageContext = Object.freeze({
+  id: undefined,
+  reject: () => undefined as any,
+  resolve: () => undefined as any,
+});
+
+/**
+ * Per-room message-routing layer, owned by {@link Room}. Owns the user-message
+ * handler registry (`onMessage`/`onMessageBytes` + per-type validators) and
+ * decodes/dispatches the user-message wire frames (ROOM_DATA / ROOM_REQUEST /
+ * ROOM_DATA_BYTES). Room's `_onMessage` keeps the protocol/lifecycle frames
+ * (JOIN/PING/LEAVE/input) and calls one of these per frame, preserving the
+ * original dispatch order. Reads back into its Room only for `onUncaughtException`
+ * (handler wrapping) and `roomId`/`roomName` (logging).
+ *
+ * @internal
+ */
+export class RoomMessages {
+  private room: Room<any>;
+
+  /** Handler registry (nanoevents). Public so Room can re-expose it as
+   *  `onMessageEvents` for @colyseus/playground introspection and
+   *  @colyseus/testing handler-swapping. */
+  events = createNanoEvents();
+
+  /** Per-type StandardSchema validators. Public for the same reason as
+   *  {@link events} (`onMessageValidators`). */
+  validators: { [type: string]: StandardSchemaV1 } = {};
+
+  constructor(room: Room<any>) {
+    this.room = room;
+  }
+
+  /**
+   * Register a handler (body of {@link Room.onMessage}). Wraps the callback via
+   * the room's `onUncaughtException` when set, stores the validator, and returns
+   * the unbind closure.
+   */
+  on(
+    _messageType: '*' | string | number,
+    _validationSchema: StandardSchemaV1 | ((...args: any[]) => void),
+    _callback?: (...args: any[]) => void,
+  ): () => void {
+    const messageType = _messageType.toString();
+
+    const validationSchema = (typeof _callback === 'function')
+      ? _validationSchema as StandardSchemaV1
+      : undefined;
+
+    const callback = (validationSchema === undefined)
+      ? _validationSchema as (...args: any[]) => void
+      : _callback;
+
+    const removeListener = this.events.on(messageType, (this.room.onUncaughtException !== undefined)
+      ? this.#wrapMessageHandler(callback, _messageType)
+      : callback);
+
+    if (validationSchema !== undefined) {
+      this.validators[messageType] = validationSchema;
+    }
+
+    // returns a method to unbind the callback
+    return () => {
+      removeListener();
+      if (this.events.events[messageType].length === 0) {
+        delete this.validators[messageType];
+      }
+    };
+  }
+
+  /**
+   * Wrap a user message handler so a sync throw or async rejection is reported to
+   * `room.onUncaughtException` as an {@link OnMessageException} carrying the correct
+   * `client` / `payload` / `type`. The handler is invoked with a different argument
+   * shape per dispatch path, so those fields are normalized here rather than relying
+   * on positional forwarding (which silently mis-mapped `type` once a context arg was
+   * added — see ROOM_DATA/ROOM_REQUEST passing `SEND_CONTEXT`/`ctx`):
+   *
+   *   - typed handler (DATA / REQUEST / BYTES): `(client, payload, ctx?)` → `type` is
+   *     the registered `_messageType`.
+   *   - wildcard `'*'` handler:                 `(client, type, payload)` → `type` is
+   *     the received message type.
+   *
+   * The error is swallowed (never rethrown) so a faulty handler can't break dispatch;
+   * the handler's return value (or promise) is passed through for the REQUEST path.
+   */
+  #wrapMessageHandler(callback: (...args: any[]) => any, registeredType: '*' | string | number) {
+    const onError = this.room.onUncaughtException!.bind(this.room);
+    const isWildcard = (registeredType === '*');
+
+    return (...args: any[]): any => {
+      const report = (e: Error) => onError(
+        new OnMessageException(
+          e, e.message,
+          args[0],                                  // client
+          isWildcard ? args[2] : args[1],           // payload
+          isWildcard ? args[1] : registeredType,    // type
+        ),
+        'onMessage',
+      );
+
+      try {
+        const result = callback(...args);
+        return (typeof result?.catch === 'function') ? result.catch(report) : result;
+      } catch (e: any) {
+        report(e);
+      }
+    };
+  }
+
+  /** Dispatch a `ROOM_DATA` frame: decode type + msgpack payload, validate, emit. */
+  onData(client: Client & ClientPrivate, buffer: Buffer, it: Iterator): void {
+    const messageType = (decode.stringCheck(buffer, it))
+      ? decode.string(buffer, it)
+      : decode.number(buffer, it);
+
+    let message;
+    try {
+      message = (buffer.byteLength > it.offset)
+        ? unpack(buffer.subarray(it.offset, buffer.byteLength))
+        : undefined;
+      debugMessage("received: '%s' -> %j (roomId: %s)", messageType, message, this.room.roomId);
+
+      // custom message validation
+      if (this.validators[messageType] !== undefined) {
+        message = standardValidate(this.validators[messageType], message);
+      }
+
+    } catch (e: any) {
+      debugAndPrintError(e);
+      client.leave(CloseCode.WITH_ERROR);
+      return;
+    }
+
+    if (this.events.events[messageType]) {
+      this.events.emit(messageType as string, client, message, SEND_CONTEXT);
+
+    } else if (this.events.events['*']) {
+      this.events.emit('*', client, messageType, message);
+
+    } else {
+      this.#noHandler(client, messageType, message);
+    }
+  }
+
+  /** Dispatch a `ROOM_REQUEST` frame: same handlers as ROOM_DATA, but the client
+   *  opted into a reply, so echo the `requestId` with the outcome. The handler's
+   *  reply is decided by what it returns / does to `ctx`: `ctx.reject(reason)` →
+   *  `REJECTED(reason)`, `ctx.resolve(value)` → `OK(value)`, a thrown error or
+   *  missing handler → `ERROR`, else `OK(return)`. */
+  onRequest(client: Client & ClientPrivate, buffer: Buffer, it: Iterator): void {
+    const requestId = decode.number(buffer, it);
+
+    const messageType = (decode.stringCheck(buffer, it))
+      ? decode.string(buffer, it)
+      : decode.number(buffer, it);
+
+    let message;
+    try {
+      message = (buffer.byteLength > it.offset)
+        ? unpack(buffer.subarray(it.offset, buffer.byteLength))
+        : undefined;
+      debugMessage("request #%d: '%s' -> %j (roomId: %s)", requestId, messageType, message, this.room.roomId);
+
+      // custom message validation (shared with the ROOM_DATA path)
+      if (this.validators[messageType] !== undefined) {
+        message = standardValidate(this.validators[messageType], message);
+      }
+
+    } catch (e: any) {
+      // Reply with an error so the caller's pending request resolves instead of timing out.
+      debugAndPrintError(e);
+      this.#replyToRequest(client, requestId, ResponseStatus.ERROR, toResponseError(e));
+      return;
+    }
+
+    // Answered by the FIRST handler registered for the type (emit would discard
+    // returns); wildcard handlers have no response contract, so they're ineligible.
+    const handler = this.events.events[messageType as string]?.[0];
+
+    if (handler === undefined) {
+      this.#replyToRequest(client, requestId, ResponseStatus.ERROR, {
+        name: "no_handler",
+        message: `room "${this.room.roomName}" has no onMessage("${messageType}") handler to answer this request.`,
+      });
+      return;
+    }
+
+    const ctx = new DispatchContext(requestId);
+
+    // Sync handlers reply in this tick with no promise machinery; only a thenable
+    // return defers to the microtask queue. A sync throw (unwrapped handler) and an
+    // async rejection both fall to the ERROR reply. With onUncaughtException set the
+    // handler is wrapped (swallows its own errors), so it never throws / its promise
+    // resolves undefined, and the error reports there.
+    let response: any;
+    try {
+      response = handler(client, message, ctx);
+      if (response !== null && typeof response === 'object' && typeof response.then === 'function') {
+        response.then(
+          (resolved: any) => this.#finalizeRequest(client, requestId, ctx, resolved),
+          (e: any) => {
+            debugAndPrintError(e);
+            this.#replyToRequest(client, requestId, ResponseStatus.ERROR, toResponseError(e));
+          },
+        );
+        return;
+      }
+    } catch (e: any) {
+      debugAndPrintError(e);
+      this.#replyToRequest(client, requestId, ResponseStatus.ERROR, toResponseError(e));
+      return;
+    }
+
+    this.#finalizeRequest(client, requestId, ctx, response);
+  }
+
+  /** Finalize a request: project the handler's outcome onto a ROOM_RESPONSE reply —
+   *  `ctx.reject` → REJECTED(reason), `ctx.resolve(value)` → OK(value), else OK(return). */
+  #finalizeRequest(client: Client, requestId: number, ctx: DispatchContext, response: any): void {
+    if (ctx._outcome === OUTCOME_REJECTED) {
+      this.#replyToRequest(client, requestId, ResponseStatus.REJECTED, ctx._reason);
+    } else if (ctx._outcome === OUTCOME_RESOLVED) {
+      this.#replyToRequest(client, requestId, ResponseStatus.OK, ctx._value);
+    } else {
+      this.#replyToRequest(client, requestId, ResponseStatus.OK, response);
+    }
+  }
+
+  /** Dispatch a `ROOM_DATA_BYTES` frame: raw bytes routed to `_$b`-prefixed handlers. */
+  onDataBytes(client: Client & ClientPrivate, buffer: Buffer, it: Iterator): void {
+    const messageType = (decode.stringCheck(buffer, it))
+      ? decode.string(buffer, it)
+      : decode.number(buffer, it);
+
+    let message: any = buffer.subarray(it.offset, buffer.byteLength);
+    debugMessage("received: '%s' -> %j (roomId: %s)", messageType, message, this.room.roomId);
+
+    const bytesMessageType = `_$b${messageType}`;
+
+    // custom message validation
+    try {
+      if (this.validators[bytesMessageType] !== undefined) {
+        message = standardValidate(this.validators[bytesMessageType], message);
+      }
+    } catch (e: any) {
+      debugAndPrintError(e);
+      client.leave(CloseCode.WITH_ERROR);
+      return;
+    }
+
+    if (this.events.events[bytesMessageType]) {
+      this.events.emit(bytesMessageType, client, message);
+
+    } else if (this.events.events['*']) {
+      this.events.emit('*', client, messageType, message);
+
+    } else {
+      this.#noHandler(client, messageType, message);
+    }
+  }
+
+  /** Emit a ROOM_RESPONSE reply immediately. */
+  #replyToRequest(client: Client, requestId: number, status: ResponseStatus, payload?: any): void {
+    debugMessage("response #%d: status=%d -> %j (roomId: %s)", requestId, status, payload, this.room.roomId);
+    client.enqueueRaw(getMessageBytes[Protocol.ROOM_RESPONSE](requestId, status, payload));
+  }
+
+  /** No handler for the type: error the client in dev, drop it in production. */
+  #noHandler(client: Client, messageType: string | number, _message: unknown): void {
+    const errorMessage = `room onMessage for "${messageType}" not registered.`;
+    debugMessage(`${errorMessage} (roomId: ${this.room.roomId})`);
+    if (isDevMode) {
+      client.error(ErrorCode.INVALID_PAYLOAD, errorMessage);
+    } else {
+      client.leave(CloseCode.WITH_ERROR, errorMessage);
+    }
+  }
+}

package/src/Server.ts

@@ -1,5 +1,6 @@
 import { greet } from "@colyseus/greeting-banner";
 import type express from 'express';
+import type { Server as HttpServer } from 'node:http';
 
 import { debugAndPrintError } from './Debug.ts';
 import * as matchMaker from './MatchMaker.ts';
@@ -9,13 +10,12 @@ import { type OnCreateOptions, Room } from './Room.ts';
 import { Deferred, registerGracefulShutdown, dynamicImport, type Type } from './utils/Utils.ts';
 
 import type { Presence } from "./presence/Presence.ts";
-import { LocalPresence } from './presence/LocalPresence.ts';
-import { LocalDriver } from './matchmaker/LocalDriver/LocalDriver.ts';
 
 import { setTransport, Transport } from './Transport.ts';
 import { logger, setLogger } from './Logger.ts';
 import { setDevMode, isDevMode } from './utils/DevMode.ts';
 import { type Router, bindRouterToTransport, createRouter } from './router/index.ts';
+import { prereadRequestBodies } from './router/node.ts';
 import { type SDKTypes as SharedSDKTypes } from '@colyseus/shared-types';
 import { getDefaultRouter } from './router/default_routes.ts';
 
@@ -141,8 +141,6 @@ export class Server<
 
     setDevMode(options.devMode === true);
 
-    this.presence = options.presence || new LocalPresence();
-    this.driver = options.driver || new LocalDriver();
     this.options = options;
     this.greet = greet;
 
@@ -150,12 +148,18 @@ export class Server<
 
     this.attach(options);
 
+    // Pass options.presence/driver through as-is (possibly undefined).
+    // matchMaker.setup() falls back to getDefaultPresence/getDefaultDriver,
+    // which auto-select RedisPresence/RedisDriver on Colyseus Cloud.
     matchMaker.setup(
-      this.presence,
-      this.driver,
+      options.presence,
+      options.driver,
       options.publicAddress,
       options.selectProcessIdToCreateRoom,
-    );
+    ).then(() => {
+      this.presence = matchMaker.presence;
+      this.driver = matchMaker.driver;
+    });
 
     if (gracefullyShutdown) {
       registerGracefulShutdown((err) => this.gracefullyShutdown(true, err));
@@ -182,20 +186,7 @@ export class Server<
    * @param listeningListener
    */
   public async listen(port: number | string, hostname?: string, backlog?: number, listeningListener?: Function) {
-    const { beforeListen, database, express } = this.options;
-
-    if (beforeListen) { await beforeListen(); }
-    if (database) { await database.boot(); }
-
-    await this._applyRouterDefaults();
-
-    if (express) {
-      await this._onTransportReady;
-      if (this.transport.getExpressApp) {
-        const expressApp = await this.transport.getExpressApp();
-        await express(expressApp);
-      }
-    }
+    await this._bootServices();
 
     //
     // if Colyseus Cloud is detected, use @colyseus/tools to listen
@@ -240,26 +231,12 @@ export class Server<
     await this._onTransportReady;
 
     return new Promise<void>((resolve, reject) => {
-      // TODO: refactor me!
-      // set transport globally, to be used by matchmaking route
-      setTransport(this.transport);
-
       this.transport.listen(port, hostname, backlog, (err) => {
         if (this.transport.server) {
           this.transport.server.on('error', (err) => reject(err));
         }
 
-        // default router is used if no router is provided
-        if (!this.router) {
-          this.router = getDefaultRouter() as unknown as Routes;
-
-        } else {
-          // make sure default routes are included
-          // https://github.com/Bekacru/better-call/pull/67
-          this.router = this.router.extend({ ...getDefaultRouter().endpoints }) as unknown as Routes;
-        }
-
-        bindRouterToTransport(this.transport, this.router, this.options.express !== undefined);
+        this.bindRoutes();
 
         if (listeningListener) {
           listeningListener(err);
@@ -275,6 +252,82 @@ export class Server<
     });
   }
 
+  /**
+   * Prepare matchmaking and HTTP routes, then return the underlying
+   * `http.Server` *without* binding to a port.
+   *
+   * Use this on serverless platforms that consume an exported HTTP server
+   * instead of a listening one. Vercel, for example, drives the request handler
+   * of a default-exported server (its Express/Hono WebSocket examples use
+   * `export default server`), whereas calling `listen()` there selects Vercel's
+   * "captured server" path, which does not invoke Express-style app handlers.
+   *
+   * The transport must be created with an `http.Server` so it can be exported.
+   * Vercel additionally needs `package.json` `"main"` pointing at the entrypoint:
+   *
+   * ```ts
+   * import { createServer } from "node:http";
+   * const httpServer = createServer();
+   * const server = new Server({
+   *   transport: new WebSocketTransport({ server: httpServer }),
+   *   express: (app) => { app.get("/hello", (req, res) => res.json({ ok: true })); },
+   * });
+   * server.define("my_room", MyRoom);
+   * export default await server.serverless(); // no listen()
+   * ```
+   */
+  public async serverless(): Promise<HttpServer> {
+    await this._bootServices();
+
+    // transport (and its HTTP server) must be ready before binding routes
+    await this._onTransportReady;
+
+    const server = this.transport.server as HttpServer | undefined;
+    if (!server) {
+      throw new Error("serverless() requires a transport backed by an http.Server (pass `{ server }` to the transport).");
+    }
+
+    this.bindRoutes();
+
+    // When the server is consumed via `export default` (rather than listen()),
+    // the request body must be available synchronously — buffer it up-front so
+    // `req.body` is set before the router runs.
+    prereadRequestBodies(server);
+
+    await matchMaker.accept(this.options.isStandaloneMatchMaker);
+
+    if (this.greet) {
+      greet();
+    }
+
+    return server;
+  }
+
+  /**
+   * Set the active transport globally and bind the matchmaking/HTTP routes.
+   * Shared by {@link listen} and {@link serverless}.
+   *
+   * `setTransport()` runs here rather than before `transport.listen()`: the
+   * global transport is only read by the matchmaking route handler, which can't
+   * run until `bindRouterToTransport()` below registers the route.
+   */
+  private bindRoutes() {
+    // set transport globally, to be used by the matchmaking route
+    setTransport(this.transport);
+
+    // default router is used if no router is provided
+    if (!this.router) {
+      this.router = getDefaultRouter() as unknown as Routes;
+
+    } else {
+      // make sure default routes are included
+      // https://github.com/Bekacru/better-call/pull/67
+      this.router = this.router.extend({ ...getDefaultRouter().endpoints }) as unknown as Routes;
+    }
+
+    bindRouterToTransport(this.transport, this.router, this.options.express !== undefined);
+  }
+
   /**
    * Define a new type of room for matchmaking.
    *
@@ -332,8 +385,8 @@ export class Server<
       await matchMaker.gracefullyShutdown();
 
       this.transport.shutdown();
-      this.presence.shutdown();
-      await this.driver.shutdown();
+      this.presence?.shutdown();
+      await this.driver?.shutdown();
 
       // custom "after shutdown" method
       await this.onShutdownCallback();
@@ -387,6 +440,27 @@ export class Server<
     this.onBeforeShutdownCallback = callback;
   }
 
+  // Boot sequence shared by listen() and serverless(): user `beforeListen`
+  // hook, database boot, framework router defaults (auth/db endpoints), then
+  // the express app. serverless() needs this too — its exported server still
+  // serves the express callback and auth/database routes.
+  private async _bootServices(): Promise<void> {
+    const { beforeListen, database, express } = this.options;
+
+    if (beforeListen) { await beforeListen(); }
+    if (database) { await database.boot(); }
+
+    await this._applyRouterDefaults();
+
+    if (express) {
+      await this._onTransportReady;
+      if (this.transport.getExpressApp) {
+        const expressApp = await this.transport.getExpressApp();
+        await express(expressApp);
+      }
+    }
+  }
+
   // Extend the user's router with framework-contributed endpoints. An explicit
   // `auth` option wins over the database's `applyRouterDefaults` so a non-DB
   // setup can still auto-mount @colyseus/auth, and a DB user can opt out.

package/src/Transport.ts

@@ -19,6 +19,11 @@ export function getTransport() { return _transport; }
 
 export abstract class Transport {
     public protocol?: string;
+    /** Self-signed cert SHA-256 hash (byte array), surfaced to clients in the
+     *  matchmake response so a WebTransport client can pin it via
+     *  `serverCertificateHashes`. Set by transports that generate their own cert
+     *  (h3). Undefined for transports using a CA-trusted cert. */
+    public fingerprint?: number[];
     public server?: http.Server | https.Server;
 
     public abstract listen(port?: number | string, hostname?: string, backlog?: number, listeningListener?: Function): this;
@@ -186,7 +191,6 @@ export interface Client<T extends { userData?: any, auth?: any, messages?: Recor
 export interface ClientPrivate {
   readyState: number; // TODO: remove readyState on version 1.0.0. Use only "state" instead.
   _enqueuedMessages?: any[];
-  _afterNextPatchQueue: Array<[string | number | Client, ArrayLike<any>]>;
   _joinedAt: number; // "elapsedTime" when the client joined the room.
 
   /**
@@ -217,7 +221,7 @@ export interface ClientPrivate {
    * once at join (when the Room called `defineInput()`), so the public API
    * call is a Map lookup + property read with no per-call allocation.
    */
-  _inputAccessor?: import('./input/InputBuffer.ts').InputAccessor;
+  _inputAccessor?: import('./input/types.ts').InputAccessor;
 
   /**
    * Used for rate limiting ROOM_INPUT_* packets via maxInputsPerSecond,
@@ -225,6 +229,90 @@ export interface ClientPrivate {
    */
   _numInputsLastSecond?: number;
   _lastInputTime?: number;
+
+  /**
+   * `performance.now()` recorded when the most recent ROOM_INPUT_* packet
+   * from this client was received. Drives the per-recipient `lastTReceived`
+   * field of the {@link ProtocolModifier.TIMED} state prefix.
+   *
+   * `0` until the client has sent its first input.
+   */
+  _lastInputReceivedAt?: number;
+
+  /**
+   * Monotonic count of *reliable* inputs successfully received from this
+   * client. Echoed back in the TIMED prefix as `lastInputSeq` so the
+   * client can correlate to its own send-time table and compute RTT.
+   * Stays at the default `0` until the client sends its first reliable
+   * input.
+   *
+   * Only ROOM_INPUT_RELIABLE bumps this — unreliable's redundant-ring
+   * pattern would double-count.
+   */
+  _receivedInputCount?: number;
+
+  /**
+   * Running baseline for the DELTA-CODED lag-comp stamp on ROOM_INPUT_RELIABLE
+   * frames (the {@link ProtocolModifier.TIMED} prefix). Each frame carries only
+   * the signed change from the previous stamp; this accumulates them back into
+   * the absolute timeline value. Zeroed on (re)connect alongside the SDK's own
+   * baseline so the first delta after a reset is absolute. `0` until allocated.
+   */
+  _reckonBaseline?: number;
+
+  /**
+   * @internal Per-client raw frames staged to ride out right AFTER this client's
+   * next state patch — per-client `afterNextPatch` messages. Lazily allocated.
+   * Pushed by {@link enqueueClientRaw} (the `afterNextPatch` path), flushed as
+   * standalone frames after the patch by {@link Room._flushPendingClientFrames}.
+   * Room-level `broadcast` `afterNextPatch` uses the Room's own queue instead, not
+   * this buffer.
+   */
+  _pendingFrames?: Uint8Array[];
+
+  /**
+   * @internal Back-reference to the Room's "clients with staged frames" list,
+   * shared by reference at join. {@link enqueueClientRaw} pushes the client here
+   * on its first staged frame of a cycle, so the after-patch flush iterates just
+   * those clients rather than scanning every client.
+   */
+  _pendingFrameClients?: Array<Client & ClientPrivate>;
+}
+
+/**
+ * The framework-level send path shared by every transport's `enqueueRaw` — the
+ * single source of truth so each transport implements only the wire-level `raw`.
+ * Routes a raw frame by where it should go:
+ *
+ *  - `afterNextPatch` → stage onto the per-client {@link ClientPrivate._pendingFrames}
+ *    buffer, sent as a standalone frame right AFTER the next state patch; a
+ *    no-allocation push into a reused array. The client announces itself to the
+ *    Room's {@link ClientPrivate._pendingFrameClients} list on its first staged
+ *    frame of a cycle.
+ *  - before JOIN → buffer in `_enqueuedMessages` until the JOIN_ROOM handshake flushes.
+ *  - otherwise → send now via the transport's `raw`.
+ *
+ * @internal
+ */
+export function enqueueClientRaw(
+  client: Client & ClientPrivate,
+  data: Uint8Array | Buffer,
+  options?: ISendOptions,
+): void {
+  if (options?.afterNextPatch) {
+    let frames = client._pendingFrames;
+    if (frames === undefined) { frames = client._pendingFrames = []; }
+    if (frames.length === 0) { client._pendingFrameClients?.push(client); } // first frame this cycle
+    frames.push(data);
+    return;
+  }
+  if (client.state !== ClientState.JOINED) {
+    // During `onJoin` / `onReconnect` the client can't register onMessage
+    // handlers yet — buffer until JOIN_ROOM has been sent.
+    client._enqueuedMessages?.push(data);
+    return;
+  }
+  client.raw(data, options);
 }
 
 export class ClientArray<C extends Client = Client> extends Array<C> {
@@ -236,6 +324,13 @@ export class ClientArray<C extends Client = Client> extends Array<C> {
    */
   private _byId: Map<string, C> = new Map();
 
+  /** The client for `sessionId`, or `undefined` — O(1). The canonical per-session
+   *  lookup (mirrors `room.inputs.get(sessionId)`). */
+  public get(sessionId: string): C | undefined {
+    return this._byId.get(sessionId);
+  }
+
+  /** @deprecated Use {@link get}. */
   public getById(sessionId: string): C | undefined {
     return this._byId.get(sessionId);
   }