@colyseus/core 0.18.0 → 0.18.1

package/src/Room.ts

@@ -1,15 +1,11 @@
-import { unpack } from 'msgpackr';
-import { decode, Encoder, Reflection, type Iterator, $changes } from '@colyseus/schema';
-import { InputDecoder } from '@colyseus/schema/input';
-import { type InputAccessor, type InputAPI, type InputOptions, type NumericFieldsOf, InputAccessorImpl, InputBufferImpl, NO_OP_INPUT_ACCESSOR } from './input/InputBuffer.ts';
-export { type InputAccessor, type InputAPI, type InputOptions, type NumericFieldsOf } from './input/InputBuffer.ts';
+import { decode, type Iterator, $changes } from '@colyseus/schema';
+import { validateSubSteps } from './input/InputBuffer.ts';
+import type { InputAPI, DefineInputOptions, IdleDeclared } from './input/types.ts';
+import { RoomInput } from './input/RoomInput.ts';
+import { RoomMessages } from './RoomMessages.ts';
+import { Rewind, type RewindOptions } from './Rewind.ts';
+export { type InputAccessor, type InputAPI, type NormalizedInputOptions, type ConsumeOptions, type IdleInput, type IdleContext, type SanitizeInput, type NumericFieldsOf, type DefineInputOptions, type IdleDeclared } from './input/types.ts';
 
-/**
- * Module-level cache of `Reflection.encode` output keyed by input
- * constructor — pays the encoding cost once per Room class regardless of
- * room instance count. WeakMap so unused classes can be GC'd.
- */
-const _inputReflectionCache = new WeakMap<Function, Uint8Array>();
 import { ClockTimer as Clock } from '@colyseus/timer';
 
 import { EventEmitter } from 'events';
@@ -24,26 +20,26 @@ import { SchemaSerializer } from './serializer/SchemaSerializer.ts';
 
 import { getMessageBytes } from './Protocol.ts';
 import { type Type, Deferred, generateId, wrapTryCatch } from './utils/Utils.ts';
-import { createNanoEvents } from './utils/nanoevents.ts';
 import { isDevMode } from './utils/DevMode.ts';
 
 import { debugAndPrintError, debugMatchMaking, debugMessage } from './Debug.ts';
 import { ServerError } from './errors/ServerError.ts';
 import { ClientState, type AuthContext, type Client, type ClientPrivate, ClientArray, type ISendOptions, type MessageArgs } from './Transport.ts';
-import { type RoomMethodName, OnAuthException, OnCreateException, OnDisposeException, OnDropException, OnJoinException, OnLeaveException, OnMessageException, OnReconnectException, type RoomException, SimulationIntervalException, TimedEventException } from './errors/RoomExceptions.ts';
+import { type RoomMethodName, OnAuthException, OnCreateException, OnDisposeException, OnDropException, OnJoinException, OnLeaveException, OnReconnectException, type RoomException, TimestepException, TimedEventException } from './errors/RoomExceptions.ts';
 
-import { standardValidate, type StandardSchemaV1 } from './utils/StandardSchema.ts';
+import { type StandardSchemaV1 } from './utils/StandardSchema.ts';
 import * as matchMaker from './MatchMaker.ts';
 
 import {
   CloseCode,
   ErrorCode,
-  HandshakeSection,
   Protocol,
-  ResponseStatus,
+  PROTOCOL_CODE_MASK,
+  PROTOCOL_MODIFIER_MASK,
   type MessageHandlerWithFormat as SharedMessageHandlerWithFormat,
   type MessageHandler as SharedMessageHandler,
   type Messages as SharedMessages,
+  type MessageContext,
 } from '@colyseus/shared-types';
 
 import {
@@ -62,23 +58,49 @@ const DEFAULT_PATCH_RATE = 1000 / 20; // 20fps (50ms)
 const DEFAULT_SIMULATION_INTERVAL = 1000 / 60; // 60fps (16.66ms)
 const noneSerializer = new NoneSerializer();
 
-// Shape an Error (or thrown value) into a plain, msgpack-friendly object for a
-// ROOM_RESPONSE error payload. Only `name`/`message`/`code` cross the wire —
-// stacks stay on the server.
-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) };
-}
+/** Shared `enqueueRaw` options routing a frame onto `_pendingFrames` to ride the
+ *  next patch. Frozen + shared (read-only) → zero per-call allocation. */
+const AFTER_PATCH_OPTS = Object.freeze({ afterNextPatch: true });
 
 export const DEFAULT_SEAT_RESERVATION_TIME = Number(process.env.COLYSEUS_SEAT_RESERVATION_TIME || 15);
 
 export type SimulationCallback = (deltaTime: number) => void;
 
+/**
+ * Per-step context passed to a {@link Room.setFixedTimestep} callback. Carries
+ * ONLY the fixed simulation step — never wall-clock/measured time — so feeding a
+ * jittery delta into deterministic sim math is unrepresentable. The same fixed
+ * `dt` is advertised to clients so prediction integrates identically. (The
+ * client's step context additionally carries an `isReplay` flag for rollback
+ * re-simulation; the server is authoritative and never replays, so it has none.)
+ */
+export interface StepContext {
+  /** Fixed step in SECONDS (`1/tickRate`) — the dt to integrate one step with. */
+  readonly dt: number;
+  /** Fixed step in MILLISECONDS (`1000/tickRate`). */
+  readonly dtMs: number;
+  /** Monotonic index of the fixed step being simulated. */
+  readonly tick: number;
+  /**
+   * Physics sub-steps per fixed step (≥ 1; `1` unless declared via
+   * `setFixedTimestep(..., { subSteps })`). Run your engine `subSteps` times at
+   * {@link subDt} inside each step — `for (let i = 0; i < ctx.subSteps; i++)
+   * world.step(ctx.subDt)` — to integrate physics at `tickRate * subSteps` Hz
+   * while inputs flow at `tickRate`. The same numbers are cascaded to predicting
+   * clients (their step context carries identical `subSteps`/`subDt`), so the
+   * sub-stepped trajectory replays bit-identically.
+   */
+  readonly subSteps: number;
+  /** Physics sub-step in SECONDS (`dt / subSteps`); equals {@link dt} when
+   *  `subSteps` is 1, so the loop above is valid for every room. */
+  readonly subDt: number;
+  /** Physics sub-step in MILLISECONDS (`dtMs / subSteps`). */
+  readonly subDtMs: number;
+}
+
+/** Fixed-timestep simulation callback. @see Room.setFixedTimestep */
+export type FixedTimestepCallback = (ctx: StepContext) => void;
+
 export interface RoomOptions {
   state?: object;
   metadata?: any;
@@ -134,7 +156,7 @@ export type Messages<This extends Room> = SharedMessages<This, Client>;
  */
 export function validate<T extends StandardSchemaV1, This = any>(
   format: T,
-  handler: (this: This, client: Client, message: StandardSchemaV1.InferOutput<T>) => void
+  handler: (this: This, client: Client, message: StandardSchemaV1.InferOutput<T>, ctx: MessageContext) => unknown
 ): MessageHandlerWithFormat<T, This> {
   return { format, handler };
 }
@@ -301,6 +323,8 @@ export class Room<T extends RoomOptions = RoomOptions> {
   private _reconnectionAttempts: { [reconnectionToken: string]: Deferred } = {};
 
   public messages?: Messages<any>;
+  /** @internal Message-routing layer: handler registry + user-message decode/dispatch. */
+  #_messages = new RoomMessages(this);
 
   /**
    * Room plugins, keyed by an operator-chosen handle. Each plugin
@@ -343,27 +367,24 @@ export class Room<T extends RoomOptions = RoomOptions> {
    */
   static __pluginLayout?: PluginLayout | null;
 
-  private onMessageEvents = createNanoEvents();
-  private onMessageValidators: {[message: string]: StandardSchemaV1} = {};
+  // Re-expose the registry for @colyseus/playground introspection and
+  // @colyseus/testing handler-swapping (both reach in via bracket access).
+  private get onMessageEvents() { return this.#_messages.events; }
+  private get onMessageValidators() { return this.#_messages.validators; }
 
-  private onMessageFallbacks = {
-    '__no_message_handler': (client: ExtractRoomClient<T>, messageType: string | number, _: unknown) => {
-      const errorMessage = `room onMessage for "${messageType}" not registered.`;
-      debugMessage(`${errorMessage} (roomId: ${this.roomId})`);
-
-      if (isDevMode) {
-        // send error code to client in development mode
-        client.error(ErrorCode.INVALID_PAYLOAD, errorMessage);
+  private _serializer: Serializer<ExtractRoomState<T>> = noneSerializer;
 
-      } else {
-        // immediately close the connection in production
-        client.leave(CloseCode.WITH_ERROR, errorMessage);
-      }
-    }
-  };
+  /** Clients that staged `afterNextPatch` frames since the last patch, so the
+   *  post-patch flush iterates only these — never the full client list. Shared by
+   *  reference onto each client at join. Reset each `broadcastPatch`. */
+  #pendingFrameClients: Array<Client & ClientPrivate> = [];
 
-  private _serializer: Serializer<ExtractRoomState<T>> = noneSerializer;
-  private _afterNextPatchQueue: Array<[string | number | ExtractRoomClient<T>, ArrayLike<any>]> = [];
+  /** `broadcast(..., { afterNextPatch })` in NON-timed rooms, sent as a SHARED
+   *  frame right after the next patch (one encode, N sends). Non-timed patches are
+   *  themselves a shared buffer, so a per-client copy would force N× allocation in
+   *  large rooms — sharing avoids that. TIMED rooms instead stage the broadcast onto
+   *  each client's `_pendingFrames`. Drained each `broadcastPatch`. */
+  #afterPatchBroadcasts: Array<{ bytes: Uint8Array; except: Client[] | undefined }> = [];
 
   private _simulationInterval: NodeJS.Timeout;
 
@@ -589,83 +610,83 @@ export class Room<T extends RoomOptions = RoomOptions> {
   public onLeave?(client: ExtractRoomClient<T>, code?: number): void | Promise<any>;
 
   /**
-   * Per-client input accessor. Set by `defineInput()`. Call `room.input(sessionId)`
-   * each tick to read the latest decoded input and/or the buffered snapshot ring
-   * for that client.
+   * Per-client input accessor. Assign it `= this.defineInput(...)`, then call
+   * `this.inputs.get(sessionId)` each tick to read that client's buffered input
+   * *stream* — iterate it directly, or call `.next()` / `.drain()` / `.latest`.
+   *
+   * (In the `Room<{ input: I }>` generic, `input` is the input *type* of one
+   * frame; `this.inputs` is the per-client accessor over the stream of them.)
    *
    * @example
    * ```typescript
    * class FpsRoom extends Room<{ input: MoveInput }> {
-   *   input = this.defineInput(MoveInput);
+   *   inputs = this.defineInput(MoveInput);
    *
    *   onCreate() {
-   *     this.setSimulationInterval(() => {
-   *       for (const c of this.clients) {
-   *         const input = this.input(c.sessionId);
-   *         if (input.latest) this.apply(c, input.latest);
-   *         // for rollback / lockstep:
-   *         //   const snapshot = input.at(this.clock.ticks);
-   *         //   for (const snapshot of input.drain()) ...
-   *       }
-   *     }, 1000 / 30);
+   *     this.setFixedTimestep((ctx) => {
+   *       for (const [sid, p] of this.state.players)
+   *         for (const input of this.inputs.get(sid))   // consume one-by-one
+   *           applyInput(p, input, ctx.dt);
+   *     }, 30);
    *   }
    * }
    * ```
    */
-  public input?: InputAPI<ExtractRoomInput<T>>;
+  public inputs?: InputAPI<ExtractRoomInput<T>>;
 
   /**
-   * Input configuration. Set via {@link defineInput} only.
-   * @internal
+   * @internal The per-room input subsystem (options, accessor registry, wire
+   * stamp mode, encode/decode/handshake). Created lazily on the first
+   * {@link defineInput} call — rooms without inputs allocate none of it, and its
+   * presence is what enables client-timed state messages. See {@link RoomInput}.
    */
-  private inputOptions?: InputOptions;
+  private _inputController?: RoomInput;
 
   /**
    * Declare the input schema and configuration in a single line. Returns the
-   * callable accessor that gets assigned to `this.input` — call
-   * `this.input(sessionId)` per tick to consume.
+   * input API that gets assigned to `this.inputs` — call
+   * `this.inputs.get(sessionId)` per tick to consume.
    *
    * ```typescript
    * class FpsRoom extends Room<{ input: MoveInput }> {
-   *   input = this.defineInput(MoveInput, {
+   *   inputs = this.defineInput(MoveInput, {
    *     seqField: "tick",       // typed: only numeric fields of MoveInput
    *     bufferMaxSize: 64,
    *   });
    *
-   *   // …or without options — defaults to seqField: "seq", bufferMaxSize: 32:
-   *   // input = this.defineInput(MoveInput);
+   *   // …or without options — no seq dedupe, bufferMaxSize: 32:
+   *   // inputs = this.defineInput(MoveInput);
    * }
    * ```
    *
    * **Defaults** when `opts` (or individual fields) are omitted:
-   * - `seqField`: `"seq"` — framework dedupes by `input.seq` if the schema has
-   *   such a field. Schemas without it gracefully skip dedupe.
+   * - `seqField`: unset — dedupe and `this.inputs.get(sessionId).at(value)` lookup are
+   *   OPT-IN (lockstep / rollback). Name a monotonic numeric field here to enable
+   *   them; redundant frames (`input[seqField]` ≤ the last seen) are then dropped.
+   *   Leave unset for reliable, in-order channels where every frame is unique.
    * - `bufferMaxSize`: `32` — enables per-client snapshot buffering for
-   *   `room.input(sessionId).drain() / .peek() / .at()`. Set to `0` to disable
-   *   buffering (the `.latest` read still works).
+   *   `this.inputs.get(sessionId)` iteration / `.consume() / .drain() / .next() /
+   *   .take() / .peek() / .at()`. Set to `0` to disable buffering (the `.latest`
+   *   read still works).
+   *
+   * **Consuming the buffer** — `for (const inp of this.inputs.get(sessionId))` (sugar
+   * for `.consume()`) is the per-entity loop: it consumes one at a time, so
+   * lag-comp `renderTime` tracks each input. `next()` (take exactly one, ack +1)
+   * suits a shared physics world stepped once for everyone; `drain()` returns the
+   * whole pending set as an array. See {@link InputAccessor} for the full
+   * per-entity-vs-shared-world guidance and why the choice affects the reconcile ack.
    */
-  protected defineInput<C extends new () => any>(
+  protected defineInput<
+    C extends new () => any,
+    O extends DefineInputOptions<InstanceType<C>> = DefineInputOptions<InstanceType<C>>,
+  >(
     type: C,
-    opts?: {
-      seqField?: NumericFieldsOf<InstanceType<C>>;
-      bufferMaxSize?: number;
-    },
-  ): InputAPI<InstanceType<C>> {
-    this.inputOptions = {
-      ctor: type,
-      seqField: opts?.seqField ?? "seq",
-      bufferMaxSize: opts?.bufferMaxSize ?? 32,
-    };
-    if (!_inputReflectionCache.has(type)) {
-      // Reflection.encode walks the schema's TypeContext via a one-shot
-      // Encoder around a throwaway instance; the bytes are SDK-deserializable
-      // back into a constructor through Reflection.decode.
-      _inputReflectionCache.set(type, Reflection.encode(new Encoder(new type())));
-    }
-    return ((sessionId: string): InputAccessor<InstanceType<C>> => {
-      const c = this.clients.getById(sessionId) as unknown as ClientPrivate | undefined;
-      return (c?._inputAccessor as InputAccessor<InstanceType<C>>) ?? NO_OP_INPUT_ACCESSOR;
-    });
+    opts?: O,
+  ): InputAPI<InstanceType<C>, IdleDeclared<O, InstanceType<C>>> {
+    // Lazily spun up on first call; its presence is the "real-time room" gate
+    // (enables client-timed state). Rooms that never call this pay nothing.
+    this._inputController ??= new RoomInput(this);
+    return this._inputController.define<C, O>(type, opts);
   }
 
   /**
@@ -681,7 +702,7 @@ export class Room<T extends RoomOptions = RoomOptions> {
    * - `onMessage`
    * - `onAuth` / `onJoin` / `onLeave` / `onCreate` / `onDispose`
    * - `clock.setTimeout` / `clock.setInterval`
-   * - `setSimulationInterval`
+   * - `setTimestep` / `setFixedTimestep`
    *
    * (Experimental: this feature is subject to change in the future - we're currently getting feedback to improve it)
    */
@@ -783,7 +804,7 @@ export class Room<T extends RoomOptions = RoomOptions> {
 
     } else if (typeof(reconnectionToken) === "string") {
         // potentially a stale client reference, so a reconnection attempt is possible.
-        return this.clients.getById(sessionId)?.reconnectionToken === reconnectionToken;
+        return this.clients.get(sessionId)?.reconnectionToken === reconnectionToken;
     }
 
     return false;
@@ -807,22 +828,29 @@ export class Room<T extends RoomOptions = RoomOptions> {
   }
 
   /**
-   * (Optional) Set a simulation interval that can change the state of the game.
-   * The simulation interval is your game loop.
+   * Set the room's game loop. `onTickCallback` runs every `delay` ms and receives
+   * the MEASURED wall-clock delta since the previous tick (a VARIABLE timestep).
+   * For deterministic, prediction-friendly simulation prefer
+   * {@link Room.setFixedTimestep}, which advances a fixed step via an accumulator.
    *
    * @default 16.6ms (60fps)
    *
-   * @param onTickCallback - You can implement your physics or world updates here!
-   *  This is a good place to update the room state.
-   * @param delay - Interval delay on executing `onTickCallback` in milliseconds.
+   * @param onTickCallback - Your physics / world update — a good place to mutate
+   *  room state. Receives the measured delta (`this.clock.deltaTime`).
+   * @param delay - Interval between ticks in milliseconds.
    */
-  public setSimulationInterval(onTickCallback?: SimulationCallback, delay: number = DEFAULT_SIMULATION_INTERVAL): void {
-    // clear previous interval in case called setSimulationInterval more than once
+  public setTimestep(onTickCallback?: SimulationCallback, delay: number = DEFAULT_SIMULATION_INTERVAL): void {
+    // clear previous loop in case it was set more than once
     if (this._simulationInterval) { clearInterval(this._simulationInterval); }
 
+    // Advertise this loop's rate to predicting clients unless set explicitly.
+    if (onTickCallback && this._inputController && this._inputController.options.tickRate === undefined) {
+      this._inputController.options.tickRate = Math.round(1000 / delay);
+    }
+
     if (onTickCallback) {
       if (this.onUncaughtException !== undefined) {
-        onTickCallback = wrapTryCatch(onTickCallback, this.onUncaughtException.bind(this), SimulationIntervalException, 'setSimulationInterval');
+        onTickCallback = wrapTryCatch(onTickCallback, this.onUncaughtException.bind(this), TimestepException, 'setTimestep');
       }
 
       this._simulationInterval = setInterval(() => {
@@ -833,49 +861,179 @@ export class Room<T extends RoomOptions = RoomOptions> {
   }
 
   /**
-   * Run a fixed-rate simulation tagged with a monotonic server tick number.
-   * Combine with `room.input(sessionId).at(tick)` to retrieve each client's
-   * input *for a specific tick* — the building block for lockstep / rollback
-   * netcode.
+   * @deprecated Renamed to {@link Room.setTimestep} (which pairs with
+   * {@link Room.setFixedTimestep}). Kept for backwards compatibility — forwards
+   * to `setTimestep` unchanged.
+   */
+  public setSimulationInterval(onTickCallback?: SimulationCallback, delay: number = DEFAULT_SIMULATION_INTERVAL): void {
+    this.setTimestep(onTickCallback, delay);
+  }
+
+  /**
+   * Fixed-timestep game loop with a framework-owned accumulator — the right
+   * default for prediction/rollback. Unlike {@link setTimestep} (which
+   * hands you the *measured* wall-clock delta), this runs `step` a whole number
+   * of times per real frame so each step advances by the SAME fixed
+   * `dt = 1/tickRate`; the measured delta only decides HOW MANY steps run. The
+   * fixed dt is delivered via {@link StepContext}, so the jittery wall-clock
+   * delta can't leak into deterministic simulation.
    *
-   * Replaces any previous {@link setSimulationInterval}. The current tick is
-   * exposed via {@link tick}.
+   * `tickRate` is also the SINGLE SOURCE of the simulation rate: it's advertised
+   * to predicting clients via the join handshake (they predict at the matching
+   * `dt`), so don't also pass `tickRate` to {@link defineInput}.
    *
-   * @example
-   * ```typescript
-   * class LockstepRoom extends Room<{ input: MoveInput }> {
-   *   input = this.defineInput(MoveInput, { seqField: "tick", bufferMaxSize: 64 });
+   * **`tickRate` couples three rates** — by design, one input == one fixed step
+   * == one server tick, so lowering `tickRate` to save bandwidth also lowers
+   * the simulation rate. To keep high-fidelity physics on a lower network rate,
+   * pass `{ subSteps: N }`: one input still drives one fixed step, but you
+   * integrate `N` engine sub-steps of `ctx.subDt` (= `ctx.dt / N`) inside it —
+   * physics at `tickRate * N` Hz, inputs at `tickRate`/sec. The same
+   * `subSteps`/`subDt` are cascaded to predicting clients (via the join
+   * handshake, onto their reconciler's step context), so client replay
+   * reproduces the sub-stepped trajectory exactly. Render interpolation already
+   * smooths above the step rate — most games don't need this; reach for it when
+   * the *simulation* needs the extra Hz (fast projectiles, stacking, tunneling).
    *
-   *   onCreate() {
-   *     this.setTickedSimulation((tick, dt) => {
-   *       for (const c of this.clients) {
-   *         const snapshot = this.input(c.sessionId).at(tick);
-   *         if (snapshot) this.apply(c, snapshot);
-   *         // else: predict, freeze, etc. — game-level decision
-   *       }
-   *     }, 1000 / 60);
-   *   }
+   * On a hitch the accumulator runs at most a few catch-up steps then drops the
+   * backlog (no spiral of death). Lag-comp is recorded once per real frame.
+   *
+   * **Consuming input inside the step** — how you consume each client's buffer
+   * depends on who integrates (see {@link InputAccessor}):
+   * - *Per-entity* (each body integrates itself): `for (const cmd of
+   *   this.inputs.get(sid)) applyInput(player, cmd, ctx.dt)` — N inputs =
+   *   N sub-integrations, ack lands on the newest applied, and `renderTime`
+   *   tracks each input (lag comp stays exact per step).
+   * - *Shared world* (one solver step advances every body): consume exactly one
+   *   input per entity per step with `this.inputs.get(sid).next()` (or `take(n)` +
+   *   sub-step), then `world.step()` once. Draining all and applying only the
+   *   latest would jump the reconcile ack past inputs you never simulated.
+   *
+   * @param step - Called once per fixed step with a {@link StepContext}.
+   * @param tickRate - Simulation rate in **Hz**. Defaults to 60.
+   * @param opts - `subSteps`: physics sub-steps per fixed step (integer ≥ 1,
+   *   default 1) — see above.
+   *
+   * @example
+   * ```ts
+   * onCreate() {
+   *   // 30 inputs/sec on the wire, physics integrated at 60 Hz:
+   *   this.setFixedTimestep((ctx) => {
+   *     this.applyInputs(ctx);      // consume ONE input per client per step
+   *     for (let i = 0; i < ctx.subSteps; i++) this.world.step(ctx.subDt);
+   *   }, 30, { subSteps: 2 });
    * }
    * ```
    */
-  public setTickedSimulation(
-    onTickCallback: (tick: number, deltaTime: number) => void,
-    delay: number = DEFAULT_SIMULATION_INTERVAL,
-    startTick: number = 0,
-  ): void {
-    this.#_tick = startTick;
-    this.setSimulationInterval((dt) => {
-      onTickCallback(this.#_tick, dt);
-      this.#_tick++;
-    }, delay);
+  public setFixedTimestep(step: FixedTimestepCallback, tickRate: number = Math.round(1000 / DEFAULT_SIMULATION_INTERVAL), opts?: { subSteps?: number }): void {
+    if (this._simulationInterval) { clearInterval(this._simulationInterval); }
+
+    const stepMs = 1000 / tickRate;
+    const stepSeconds = 1 / tickRate;
+    // Explicit option wins; else an earlier defineInput({ subSteps }) declaration.
+    const subSteps = validateSubSteps(opts?.subSteps, 'setFixedTimestep')
+      ?? this._inputController?.options.subSteps ?? 1;
+
+    // Single source of the fixed rate (and sub-step count): advertise both to
+    // predicting clients so N and dt can't drift between the two sides.
+    if (this._inputController) {
+      this._inputController.options.tickRate = tickRate;
+      this._inputController.options.subSteps = subSteps;
+    }
+
+    let cb = step;
+    if (this.onUncaughtException !== undefined) {
+      cb = wrapTryCatch(step, this.onUncaughtException.bind(this), TimestepException, 'setFixedTimestep');
+    }
+
+    let acc = 0;
+    let tick = 0;
+    // Reused per-step context — no per-step allocation in the hot loop.
+    // subDt = stepSeconds/subSteps: same expression as the client handle's
+    // subStepSeconds, so the per-sub-step dt is bit-identical on both sides.
+    const ctx = {
+      dt: stepSeconds, dtMs: stepMs, tick: 0,
+      subSteps, subDt: stepSeconds / subSteps, subDtMs: stepMs / subSteps,
+    };
+    const MAX_CATCHUP_STEPS = 5;
+
+    this._simulationInterval = setInterval(() => {
+      this.clock.tick();
+      acc += this.clock.deltaTime;
+
+      // Run a whole number of FIXED steps to consume the measured time.
+      let ran = 0;
+      while (acc >= stepMs && ran < MAX_CATCHUP_STEPS) {
+        acc -= stepMs;
+        ctx.tick = tick++;
+        cb(ctx);
+        ran++;
+      }
+      if (ran === MAX_CATCHUP_STEPS) { acc = 0; } // hitch: drop backlog, don't spiral
+    }, stepMs);
+  }
+
+  /** Server-side lag compensation, lazily created. @see allowRewindState */
+  #rewind?: Rewind;
+
+  /** @internal The rewind attachments' timeline mode (snapshot/reckon), or
+   *  `undefined` when no rewind is configured. {@link RoomInput} reads it to
+   *  derive the wire input stamp mode (snapshot → renderTime, reckon → reckonTime). */
+  _timelineMode(): { snapshot?: boolean; reckon?: boolean } | undefined {
+    return this.#rewind?.timelineMode();
   }
 
   /**
-   * Current server tick. Incremented by {@link setTickedSimulation} after each
-   * tick callback returns. Returns 0 when no ticked simulation is running.
+   * Enable server-side lag compensation: returns a {@link Rewind} that records the
+   * position history of the entities you attach and automatically snapshots them
+   * on each broadcast (the patchRate cadence). Attach the collections to rewind,
+   * then read past positions (at a client's renderTime) in your hit tests.
+   *
+   * @example
+   * ```ts
+   * const rewind = this.allowRewindState({ maxRewindMs: 500 });
+   * rewind.attachAll(this.state.enemies, { fields: ["x", "y"] });
+   * // in a hit test — rewind to where the SHOOTER saw the world:
+   * const seen = rewind.lastSeenBy(shooterSessionId);   // needs this.defineInput(...)
+   * const seenX = seen.value(enemy, "x"), seenY = seen.value(enemy, "y");
+   * ```
+   *
+   * Per-client stamps auto-enable from the `attachAll` `mode` of the groups you
+   * rewind — no `renderTime` flag. The default auto-record fires on each
+   * broadcast, snapshotting exactly what the client receives — so the rewind
+   * reproduces the client's interpolation and hits stay exact even when the
+   * broadcast rate differs from the sim rate (`patchRate ≠ timestep`). Call
+   * `rewind.record()` yourself during a tick to take over that cadence (you then
+   * own correctness against your own broadcast rate).
    */
-  public get tick(): number { return this.#_tick; }
-  #_tick: number = 0;
+  public allowRewindState(opts?: RewindOptions): Rewind {
+    this.#rewind = Rewind.get(this, opts);
+    // Resolve `rewind.lastSeenBy(sid)` through the framework-owned input API.
+    // Lazy: read at call time, so field-init order between `inputs` and `rewind`
+    // doesn't matter. A missing input API fails loudly; a client that hasn't
+    // stamped yet legitimately reads 0 → live fallback (NOT a config error).
+    this.#rewind.bindRenderTime((sessionId) => {
+      const api = this._inputController?.api;
+      if (api === undefined) {
+        throw new Error(
+          "rewind.lastSeenBy() found no input API. Declare " +
+          "`inputs = this.defineInput(YourInput)`, or use " +
+          "rewind.at(time) with a render time you track yourself.",
+        );
+      }
+      return api.get(sessionId).renderTime;
+    });
+    // Direct reckon-display stamp: mode:"reckon" groups read at exactly the
+    // instant the client displayed them — immune to its RTT-estimation error.
+    // RAW (not the accessor's resolved getter): _aim's midpoint fallback must
+    // see 0 for unstamped clients.
+    this.#rewind.bindReckonTime((sessionId) =>
+      this._inputController?.rawReckonTime(sessionId) ?? 0,
+    );
+    // Anchor the reckon midpoint FALLBACK at the true processing instant (the
+    // record timestamp is one tick stale by hit-test time — see bindNow).
+    this.#rewind.bindNow(() => this.clock.elapsedTime);
+    return this.#rewind;
+  }
 
   /**
    * @deprecated Use `.patchRate=` instead.
@@ -1106,12 +1264,6 @@ export class Room<T extends RoomOptions = RoomOptions> {
     ...args: MessageArgs<ExtractRoomClient<T>['~messages'][K], IBroadcastOptions>
   ) {
     const [message, options] = args;
-    if (options && options.afterNextPatch) {
-      delete options.afterNextPatch;
-      this._afterNextPatchQueue.push(['broadcast', [type, ...args]]);
-      return;
-    }
-
     this.broadcastMessageType(type, message, options);
   }
 
@@ -1119,12 +1271,6 @@ export class Room<T extends RoomOptions = RoomOptions> {
    * Broadcast bytes (UInt8Arrays) to a particular room
    */
   public broadcastBytes(type: string | number, message: Uint8Array, options: IBroadcastOptions) {
-    if (options && options.afterNextPatch) {
-      delete options.afterNextPatch;
-      this._afterNextPatchQueue.push(['broadcastBytes', arguments]);
-      return;
-    }
-
     this.broadcastMessageType(type as string, message, options);
   }
 
@@ -1144,10 +1290,33 @@ export class Room<T extends RoomOptions = RoomOptions> {
       return false;
     }
 
-    const hasChanges = this._serializer.applyPatches(this.clients, this.state);
+    // When `defineInput()` was called, hand the serializer a fresh `sNow`
+    // each tick. The per-client `lastTReceived` is read off the client at
+    // encode time inside `applyPatches`.
+    const sNow = this.clock.elapsedTime;
+    const hasChanges = this._serializer.applyPatches(
+      this.clients,
+      this.state,
+      this._inputController !== undefined ? { sNow } : undefined,
+    );
+
+    // Deliver any per-client `afterNextPatch` frames as standalone frames right
+    // after the patch (never coalesced into it). Iterates only the clients that
+    // staged frames this cycle (`#pendingFrameClients`), never the full list.
+    this._flushPendingClientFrames();
 
-    // broadcast messages enqueued for "after patch"
-    this._dequeueAfterPatchMessages();
+    // After-patch broadcasts ride here as shared frames (one buffer → N sends).
+    this._flushAfterPatchBroadcasts();
+
+    // Lag-comp: record the snapshot the client just received, on the broadcast
+    // cadence and stamped with the SAME `sNow` the frame carries — so valueAt()
+    // reproduces the client's interpolation over the IDENTICAL pair (exact hits
+    // at any patchRate). Idempotent per `sNow`: a manual record() this tick wins,
+    // and a patchRate faster than the sim simply dedups back to per-tick.
+    const rw = this.#rewind;
+    if (rw !== undefined && rw.lastRecordedAt !== sNow) {
+      rw.record(sNow, this.#_patchRate || undefined);
+    }
 
     return hasChanges;
   }
@@ -1182,43 +1351,19 @@ export class Room<T extends RoomOptions = RoomOptions> {
   );
   public onMessage<T = any, C extends Client = ExtractRoomClient<T>>(
     messageType: string | number,
-    callback: (client: C, message: T) => void,
+    callback: (client: C, message: T, ctx: MessageContext) => unknown,
   );
   public onMessage<T = any, C extends Client = ExtractRoomClient<T>>(
     messageType: string | number,
     validationSchema: StandardSchemaV1<T>,
-    callback: (client: C, message: T) => void,
+    callback: (client: C, message: T, ctx: MessageContext) => unknown,
   );
   public onMessage<T = any>(
     _messageType: '*' | string | number,
     _validationSchema: StandardSchemaV1<T> | ((...args: any[]) => void),
     _callback?: (...args: any[]) => void,
   ) {
-    const messageType = _messageType.toString();
-
-    const validationSchema = (typeof _callback === 'function')
-      ? _validationSchema as StandardSchemaV1<T>
-      : undefined;
-
-    const callback = (validationSchema === undefined)
-      ? _validationSchema as (...args: any[]) => void
-      : _callback;
-
-    const removeListener = this.onMessageEvents.on(messageType, (this.onUncaughtException !== undefined)
-      ? wrapTryCatch(callback, this.onUncaughtException.bind(this), OnMessageException, 'onMessage', false, _messageType)
-      : callback);
-
-    if (validationSchema !== undefined) {
-      this.onMessageValidators[messageType] = validationSchema;
-    }
-
-    // returns a method to unbind the callback
-    return () => {
-      removeListener();
-      if (this.onMessageEvents.events[messageType].length === 0) {
-        delete this.onMessageValidators[messageType];
-      }
-    };
+    return this.#_messages.on(_messageType, _validationSchema as any, _callback);
   }
 
   public onMessageBytes<T = any, C extends Client = ExtractRoomClient<T>>(
@@ -1237,21 +1382,7 @@ export class Room<T extends RoomOptions = RoomOptions> {
     _validationSchema: StandardSchemaV1<T> | ((...args: any[]) => void),
     _callback?: (...args: any[]) => void,
   ) {
-    const messageType = `_$b${_messageType}`;
-
-    const validationSchema = (typeof _callback === 'function')
-      ? _validationSchema as StandardSchemaV1<T>
-      : undefined;
-
-    const callback = (validationSchema === undefined)
-      ? _validationSchema as (...args: any[]) => void
-      : _callback;
-
-    if (validationSchema !== undefined) {
-      return this.onMessage(messageType, validationSchema as any, callback as any);
-    } else {
-      return this.onMessage(messageType, callback as any);
-    }
+    return this.#_messages.on(`_$b${_messageType}`, _validationSchema as any, _callback);
   }
 
   // ---------------------------------------------------------------------------
@@ -1426,18 +1557,8 @@ export class Room<T extends RoomOptions = RoomOptions> {
     // (each new reconnection receives a new reconnection token)
     client.reconnectionToken = generateId();
 
-    // Allocate per-client input instance + decoder if the Room called `defineInput()`.
-    // Done early so onJoin can reference room.input(sessionId).latest.
-    if (this.inputOptions !== undefined) {
-      client._input = new this.inputOptions.ctor();
-      client._inputDecoder = new InputDecoder(client._input);
-      // Buffer is opt-in via bufferMaxSize > 0 (rollback / lockstep).
-      const maxSize = this.inputOptions.bufferMaxSize;
-      if (maxSize > 0) {
-        client._inputBuffer = new InputBufferImpl(maxSize, this.inputOptions.seqField);
-      }
-      client._inputAccessor = new InputAccessorImpl(client);
-    }
+    // Allocate per-client input state early so onJoin can read inputs.get(sid).latest.
+    this._inputController?.allocate(client);
 
     if (this._reservedSeatTimeouts[sessionId]) {
       clearTimeout(this._reservedSeatTimeouts[sessionId]);
@@ -1457,7 +1578,7 @@ export class Room<T extends RoomOptions = RoomOptions> {
     if (
       this._reservedSeats[sessionId] === undefined &&
       connectionOptions?.reconnectionToken &&
-      this.clients.getById(sessionId)?.reconnectionToken === connectionOptions.reconnectionToken
+      this.clients.get(sessionId)?.reconnectionToken === connectionOptions.reconnectionToken
     ) {
       debugMatchMaking('attempting to reconnect client with a stale previous connection - sessionId: \'%s\', roomId: \'%s\'', client.sessionId, this.roomId);
       this._reconnectionAttempts[connectionOptions.reconnectionToken] = new Deferred();
@@ -1496,8 +1617,10 @@ export class Room<T extends RoomOptions = RoomOptions> {
     this._reservedSeats[sessionId][2] = true; // flag seat reservation as "consumed"
     debugMatchMaking('consuming seat reservation, sessionId: \'%s\' (roomId: %s)', client.sessionId, this.roomId);
 
-    // share "after next patch queue" reference with every client.
-    client._afterNextPatchQueue = this._afterNextPatchQueue;
+    // Share the after-patch flush list so a client can announce staged frames
+    // without the flush scanning every client. `_pendingFrames` are delivered as
+    // standalone frames right after the patch by `_flushPendingClientFrames`.
+    (client as Client & ClientPrivate)._pendingFrameClients = this.#pendingFrameClients;
 
     // add temporary callback to keep track of disconnections during `onJoin`.
     client.ref['onleave'] = (_) => client.state = ClientState.LEAVING;
@@ -1507,6 +1630,9 @@ export class Room<T extends RoomOptions = RoomOptions> {
       const reconnectionToken = connectionOptions?.reconnectionToken;
       if (reconnectionToken && this._reconnections[reconnectionToken]?.[0] === sessionId) {
         this.clients.push(client);
+        // After push (no leak on a failed join), before onReconnect; overwrites
+        // the dropped session's stale entry.
+        this._inputController?.register(sessionId, client);
 
         //
         // await for reconnection:
@@ -1572,6 +1698,8 @@ export class Room<T extends RoomOptions = RoomOptions> {
         }
 
         this.clients.push(client);
+        // After push (no leak on a failed join), before onJoin (resolves inputs.get there).
+        this._inputController?.register(sessionId, client);
 
         //
         // Flag sessionId as non-enumarable so hasReachedMaxClients() doesn't count it
@@ -1625,16 +1753,10 @@ export class Room<T extends RoomOptions = RoomOptions> {
       // allow client to send messages after onJoin has succeeded.
       client.ref.on('message', this._onMessage.bind(this, client));
 
-      // Append input reflection as a tagged section when the room declared
-      // input. The SDK uses these bytes to materialize a constructor for
-      // `conn.input()` calls that don't pass an explicit `type`.
-      let extraSections: Array<{ tag: number; bytes: Uint8Array }> | undefined;
-      if (!connectionOptions?.skipHandshake && this.inputOptions !== undefined) {
-        const inputBytes = _inputReflectionCache.get(this.inputOptions.ctor);
-        if (inputBytes !== undefined) {
-          extraSections = [{ tag: HandshakeSection.INPUT_REFLECTION, bytes: inputBytes }];
-        }
-      }
+      // NOT gated by skipHandshake: that flag means "client already has the STATE
+      // schema", but these carry input config the client can't derive locally
+      // (re-parsing on reconnect is idempotent).
+      const extraSections = this._inputController?.handshakeSections();
 
       // confirm room id that matches the room name requested to join
       client.raw(getMessageBytes[Protocol.JOIN_ROOM](
@@ -1786,46 +1908,67 @@ export class Room<T extends RoomOptions = RoomOptions> {
         : [options.except]
       : undefined;
 
+    // `afterNextPatch` in a NON-timed room: the patch is a SHARED buffer, so
+    // coalescing would force N per-client copies. Keep this one shared buffer and
+    // ride it right after the patch (see #afterPatchBroadcasts). `except` is
+    // captured now; recipients resolve at drain time.
+    if (options.afterNextPatch && this._inputController === undefined) {
+      this.#afterPatchBroadcasts.push({ bytes: encodedMessage, except });
+      return;
+    }
+
+    // Otherwise one loop: a TIMED-room `afterNextPatch` broadcast stages onto each
+    // recipient's `_pendingFrames` (flushed right after the patch); an immediate
+    // broadcast sends now.
+    const sendOpts = options.afterNextPatch ? AFTER_PATCH_OPTS : undefined;
     let numClients = this.clients.length;
     while (numClients--) {
       const client = this.clients[numClients];
-
       if (!except || !except.includes(client)) {
-        client.enqueueRaw(encodedMessage);
+        client.enqueueRaw(encodedMessage, sendOpts);
       }
     }
   }
 
-  // Encode and enqueue a ROOM_RESPONSE for a client request. If the client has
-  // already left, `enqueueRaw` is a no-op — no response is needed.
-  #replyToRequest(client: Client, requestId: number, status: ResponseStatus, payload?: any) {
-    debugMessage("response #%d: status=%d -> %j (roomId: %s)", requestId, status, payload, this.roomId);
-    client.enqueueRaw(getMessageBytes[Protocol.ROOM_RESPONSE](requestId, status, payload));
+  /** Drain `#afterPatchBroadcasts` right after the patch — each as ONE shared
+   *  buffer fanned out to its (non-excepted) recipients. `enqueueRaw` handles
+   *  JOINED (send now) vs still-joining (buffer until JOIN) per client. */
+  private _flushAfterPatchBroadcasts() {
+    const queued = this.#afterPatchBroadcasts;
+    if (queued.length === 0) { return; }
+    for (let i = 0; i < queued.length; i++) {
+      const { bytes, except } = queued[i];
+      let numClients = this.clients.length;
+      while (numClients--) {
+        const client = this.clients[numClients];
+        if (!except || !except.includes(client)) { client.enqueueRaw(bytes); }
+      }
+    }
+    queued.length = 0;
   }
 
   private sendFullState(client: Client): void {
-    client.raw(this._serializer.getFullState(client));
+    client.raw(this._serializer.getFullState(
+      client,
+      this._inputController !== undefined ? { sNow: this.clock.elapsedTime } : undefined,
+    ));
   }
 
-  private _dequeueAfterPatchMessages() {
-    const length = this._afterNextPatchQueue.length;
-
-    if (length > 0) {
-      for (let i = 0; i < length; i++) {
-        const [target, args] = this._afterNextPatchQueue[i];
-
-        if (target === "broadcast") {
-          this.broadcast.apply(this, args as any);
-
-        } else {
-          (target as Client).raw.apply(target, args as any);
-        }
+  /** Send each client's staged `afterNextPatch` frames as standalone frames right
+   *  after the patch, then reset the tracker. Iterates only the clients that staged
+   *  frames this cycle (`#pendingFrameClients`), never the full client list; empty
+   *  (→ O(1)) on a tick where nothing was staged. */
+  private _flushPendingClientFrames() {
+    const dirty = this.#pendingFrameClients;
+    if (dirty.length === 0) { return; }
+    for (let i = 0; i < dirty.length; i++) {
+      const frames = dirty[i]._pendingFrames;
+      if (frames !== undefined && frames.length > 0) {
+        for (let j = 0; j < frames.length; j++) { dirty[i].raw(frames[j]); }
+        frames.length = 0;
       }
-
-      // new messages may have been added in the meantime,
-      // let's splice the ones that have been processed
-      this._afterNextPatchQueue.splice(0, length);
     }
+    dirty.length = 0;
   }
 
   private async _reserveSeat(
@@ -1872,6 +2015,8 @@ export class Room<T extends RoomOptions = RoomOptions> {
         delete this._reconnections[devModeReconnectionToken];
         delete this._reservedSeats[sessionId];
         delete this._reservedSeatTimeouts[sessionId];
+        // devMode reconnection bypasses #_onAfterLeave — drop the input accessor here.
+        this._inputController?.release(sessionId);
 
         if (!allowReconnection) {
           await this.#_decrementClientCount();
@@ -1939,7 +2084,7 @@ export class Room<T extends RoomOptions = RoomOptions> {
     }
 
     if (this._autoDisposeTimeout) {
-      clearInterval(this._autoDisposeTimeout);
+      clearTimeout(this._autoDisposeTimeout);
       this._autoDisposeTimeout = undefined;
     }
 
@@ -1947,24 +2092,10 @@ export class Room<T extends RoomOptions = RoomOptions> {
     this.clock.clear();
     this.clock.stop();
 
-    return await (userReturnData || Promise.resolve());
-  }
+    // drop any input accessors still held for in-flight reconnections
+    this._inputController?.dispose();
 
-  /**
-   * After the decoder has mutated `client._input`, push a clone into the
-   * per-client buffer (when buffering is enabled). Honors
-   * `inputOptions.seqField` for dedupe of redundant frames.
-   */
-  #captureInput(client: ClientPrivate) {
-    const buf = client._inputBuffer;
-    if (!buf) { return; } // no consumer registered — skip the clone allocation
-    const inst = client._input!;
-    const seqField = this.inputOptions?.seqField;
-    if (seqField !== undefined) {
-      const value = (inst as any)[seqField] as number;
-      if (typeof value === 'number' && !buf.accept(value)) { return; }
-    }
-    buf.push(inst.clone() as any);
+    return await (userReturnData || Promise.resolve());
   }
 
   private _onMessage(client: ExtractRoomClient<T> & ClientPrivate, buffer: Buffer) {
@@ -1987,153 +2118,25 @@ export class Room<T extends RoomOptions = RoomOptions> {
     }
 
     const it: Iterator = { offset: 1 };
-    const code = buffer[0];
+    // Strip modifier bits (e.g. ProtocolModifier.TIMED on a render-time input)
+    // before dispatch; existing client→server codes set no modifiers.
+    const code = buffer[0] & PROTOCOL_CODE_MASK;
+    const modifiers = buffer[0] & PROTOCOL_MODIFIER_MASK;
 
     if (code === Protocol.ROOM_DATA) {
-      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.roomId);
-
-        // custom message validation
-        if (this.onMessageValidators[messageType] !== undefined) {
-          message = standardValidate(this.onMessageValidators[messageType], message);
-        }
-
-      } catch (e: any) {
-        debugAndPrintError(e);
-        client.leave(CloseCode.WITH_ERROR);
-        return;
-      }
-
-      if (this.onMessageEvents.events[messageType]) {
-        this.onMessageEvents.emit(messageType as string, client, message);
-
-      } else if (this.onMessageEvents.events['*']) {
-        this.onMessageEvents.emit('*', client, messageType, message);
-
-      } else {
-        this.onMessageFallbacks['__no_message_handler'](client, messageType, message);
-      }
+      this.#_messages.onData(client, buffer, it);
 
     } else if (code === Protocol.ROOM_REQUEST) {
-      // A request reuses the same `onMessage(type, ...)` handlers as a plain
-      // ROOM_DATA message — the only difference is the client opted in to a
-      // reply (by passing a callback / using `room.request()`), so the wire
-      // carries a `requestId` we must echo back. The handler's return value
-      // (awaited) becomes the response payload.
-      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.roomId);
-
-        // custom message validation (shared with the ROOM_DATA path)
-        if (this.onMessageValidators[messageType] !== undefined) {
-          message = standardValidate(this.onMessageValidators[messageType], message);
-        }
-
-      } catch (e: any) {
-        // Reply with an error so the client's pending request settles instead
-        // of timing out. (A plain ROOM_DATA would drop the client here, but a
-        // request has a caller waiting on the other end.)
-        debugAndPrintError(e);
-        this.#replyToRequest(client, requestId, ResponseStatus.ERROR, toResponseError(e));
-        return;
-      }
-
-      // A request is answered by the FIRST handler registered for its type.
-      // `onMessageEvents.emit` would run every handler and discard returns, so
-      // we invoke directly to capture the value. Wildcard ('*') handlers are
-      // not eligible — their (client, type, message) shape has no response
-      // contract — so a type with only a wildcard handler gets `no_handler`.
-      const handler = this.onMessageEvents.events[messageType as string]?.[0];
-
-      if (handler === undefined) {
-        this.#replyToRequest(client, requestId, ResponseStatus.ERROR, {
-          name: "no_handler",
-          message: `room "${this.roomName}" has no onMessage("${messageType}") handler to answer this request.`,
-        });
-        return;
-      }
-
-      // `Promise.resolve().then(...)` normalizes sync throws and async
-      // rejections into the same rejection path. When `onUncaughtException`
-      // is configured the handler is wrapped (see `onMessage`) and swallows
-      // its own errors, so the request resolves with `undefined` and the
-      // exception is reported there instead of as an ERROR response.
-      Promise.resolve().then(() => handler(client, message)).then(
-        (response) => this.#replyToRequest(client, requestId, ResponseStatus.OK, response),
-        (e) => {
-          debugAndPrintError(e);
-          this.#replyToRequest(client, requestId, ResponseStatus.ERROR, toResponseError(e));
-        },
-      );
+      this.#_messages.onRequest(client, buffer, it);
 
     } else if (code === Protocol.ROOM_DATA_BYTES) {
-      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.roomId);
-
-      const bytesMessageType = `_$b${messageType}`;
-
-      // custom message validation
-      try {
-        if (this.onMessageValidators[bytesMessageType] !== undefined) {
-          message = standardValidate(this.onMessageValidators[bytesMessageType], message);
-        }
-      } catch (e: any) {
-        debugAndPrintError(e);
-        client.leave(CloseCode.WITH_ERROR);
-        return;
-      }
-
-      if (this.onMessageEvents.events[bytesMessageType]) {
-        this.onMessageEvents.emit(bytesMessageType, client, message);
-
-      } else if (this.onMessageEvents.events['*']) {
-        this.onMessageEvents.emit('*', client, messageType, message);
-
-      } else {
-        this.onMessageFallbacks['__no_message_handler'](client, messageType, message);
-      }
+      this.#_messages.onDataBytes(client, buffer, it);
 
     } else if (code === Protocol.ROOM_INPUT_RELIABLE) {
-      if (client._inputDecoder) {
-        try {
-          client._inputDecoder.decode(buffer.subarray(1));
-        } catch (e: any) {
-          debugAndPrintError(e);
-          return;
-        }
-        this.#captureInput(client);
-      }
+      this._inputController?.decodeReliable(client, buffer, it, modifiers);
 
     } else if (code === Protocol.ROOM_INPUT_UNRELIABLE) {
-      if (client._inputDecoder) {
-        try {
-          client._inputDecoder.decodeAll(buffer.subarray(1), () => this.#captureInput(client));
-        } catch (e: any) {
-          debugAndPrintError(e);
-          return;
-        }
-      }
+      this._inputController?.decodeUnreliable(client, buffer, modifiers);
 
     } else if (code === Protocol.JOIN_ROOM && client.state === ClientState.JOINING) {
       // join room has been acknowledged by the client
@@ -2183,6 +2186,10 @@ export class Room<T extends RoomOptions = RoomOptions> {
       return;
     }
 
+    // Freeze the seat: a held (reconnecting) session idles from the first tick
+    // instead of replaying last-known moves.
+    this._inputController?.freeze(client as unknown as ClientPrivate);
+
     if (method) {
       debugMatchMaking(`${method.name}, sessionId: \'%s\' (close code: %d, roomId: %s)`, client.sessionId, code, this.roomId);
 
@@ -2223,6 +2230,9 @@ export class Room<T extends RoomOptions = RoomOptions> {
 
     // trigger 'leave' only if seat reservation has been fully consumed
     if (this._reservedSeats[client.sessionId] === undefined) {
+      // Session fully gone — drop its accessor. No identity check needed: a
+      // successful reconnect skips this finalizer, so the entry is always this client's.
+      this._inputController?.release(client.sessionId);
       this._events.emit('leave', client, willDispose);
     }
   }
@@ -2309,53 +2319,4 @@ export class Room<T extends RoomOptions = RoomOptions> {
     }
   }
 
-}
-
-/**
- * (WIP) Alternative, method-based room definition.
- * We should be able to define
- */
-
-type RoomLifecycleMethods =
-  | 'messages'
-  | 'onCreate'
-  | 'onJoin'
-  | 'onLeave'
-  | 'onDispose'
-  | 'onCacheRoom'
-  | 'onRestoreRoom'
-  | 'onDrop'
-  | 'onReconnect'
-  | 'onUncaughtException'
-  | 'onAuth'
-  | 'onBeforeShutdown'
-  | 'onBeforePatch';
-
-type DefineRoomOptions<T extends RoomOptions = RoomOptions> =
-  Partial<Pick<Room<T>, RoomLifecycleMethods>> &
-  { state?: ExtractRoomState<T> | (() => ExtractRoomState<T>); } &
-  ThisType<Exclude<Room<T>, RoomLifecycleMethods>> &
-  ThisType<Room<T>>
-;
-
-export function room<T>(options: DefineRoomOptions<T>) {
-  class _ extends Room<T> {
-    messages = options.messages;
-
-    constructor() {
-      super();
-      if (options.state && typeof options.state === 'function') {
-        this.state = options.state();
-      }
-    }
-  }
-
-  // Copy all methods to the prototype
-  for (const key in options) {
-    if (typeof options[key] === 'function') {
-      _.prototype[key] = options[key];
-    }
-  }
-
-  return _ as typeof Room<T>;
 }