@noya-app/noya-multiplayer-react 0.1.89 → 0.2.0

package/src/__tests__/WebSocketConnection.test.ts

@@ -0,0 +1,1180 @@
+import { afterEach, describe, expect, it, jest } from "bun:test";
+import { ConnectionEvent, WebSocketConnection } from "../WebSocketConnection";
+
+const OriginalWebSocket = globalThis.WebSocket;
+const OriginalRequestAnimationFrame = globalThis.requestAnimationFrame;
+const OriginalCancelAnimationFrame = globalThis.cancelAnimationFrame;
+
+class MockWebSocket {
+  static CONNECTING = 0;
+  static OPEN = 1;
+  static CLOSING = 2;
+  static CLOSED = 3;
+  static instances: MockWebSocket[] = [];
+
+  readyState = MockWebSocket.CONNECTING;
+  sent: string[] = [];
+  closeCount = 0;
+  onopen: ((event: Event) => void) | null = null;
+  onmessage: ((event: MessageEvent) => void) | null = null;
+  onclose: ((event: CloseEvent) => void) | null = null;
+  onerror: ((event: Event) => void) | null = null;
+
+  constructor(readonly url = "") {
+    MockWebSocket.instances.push(this);
+  }
+
+  open() {
+    this.readyState = MockWebSocket.OPEN;
+    this.onopen?.(new Event("open"));
+  }
+
+  receive(message: object) {
+    this.onmessage?.(
+      new MessageEvent("message", { data: JSON.stringify(message) })
+    );
+  }
+
+  send(data: string) {
+    this.sent.push(data);
+  }
+
+  close() {
+    if (this.readyState === MockWebSocket.CLOSED) return;
+
+    this.closeCount += 1;
+    this.readyState = MockWebSocket.CLOSED;
+    this.onclose?.(new CloseEvent("close"));
+  }
+}
+
+function installAnimationFrameController() {
+  let nextHandle = 1;
+  const callbacks = new Map<number, FrameRequestCallback>();
+  globalThis.requestAnimationFrame = (callback) => {
+    const handle = nextHandle++;
+    callbacks.set(handle, callback);
+    return handle;
+  };
+  globalThis.cancelAnimationFrame = (handle) => {
+    callbacks.delete(handle);
+  };
+
+  return {
+    flush() {
+      const pending = Array.from(callbacks.values());
+      callbacks.clear();
+      for (const callback of pending) callback(Date.now());
+    },
+  };
+}
+
+afterEach(() => {
+  jest.useRealTimers();
+  globalThis.WebSocket = OriginalWebSocket;
+  globalThis.requestAnimationFrame = OriginalRequestAnimationFrame;
+  globalThis.cancelAnimationFrame = OriginalCancelAnimationFrame;
+  MockWebSocket.instances = [];
+});
+
+describe("WebSocketConnection heartbeat recovery", () => {
+  it("sends typed pings and treats pongs as receive progress", () => {
+    jest.useFakeTimers({ now: 0 });
+    globalThis.WebSocket = MockWebSocket as unknown as typeof WebSocket;
+    const events: ConnectionEvent<{ value: number }>[] = [];
+    const connection = new WebSocketConnection<{ value: number }>(
+      new URL("wss://example.com"),
+      {
+        heartbeatIntervalMs: 100,
+        silentTimeoutMs: 250,
+        onConnectionEvent: (event) => events.push(event),
+      }
+    );
+
+    connection.connect();
+    const socket = MockWebSocket.instances[0];
+    socket.open();
+    jest.advanceTimersByTime(100);
+
+    const ping = JSON.parse(socket.sent[0]);
+    expect(ping).toMatchObject({ type: "ping" });
+    expect(ping.id).toStartWith("heartbeat-");
+    expect(ping.clientSentAt).toBe(100);
+
+    const pong = {
+      type: "pong",
+      id: ping.id,
+      clientSentAt: ping.clientSentAt,
+      serverReceivedAt: 100,
+      serverSentAt: 100,
+    };
+    socket.receive(pong);
+    jest.advanceTimersByTime(249);
+
+    expect(socket.closeCount).toBe(0);
+    expect(events).toContainEqual({
+      type: "receive",
+      message: pong,
+    });
+
+    connection.close();
+  });
+
+  it("forces a reconnect after an open socket stays silent", () => {
+    jest.useFakeTimers({ now: 0 });
+    globalThis.WebSocket = MockWebSocket as unknown as typeof WebSocket;
+    const connection = new WebSocketConnection<{ value: number }>(
+      new URL("wss://example.com"),
+      {
+        heartbeatIntervalMs: 100,
+        silentTimeoutMs: 250,
+      }
+    );
+
+    connection.connect();
+    const first = MockWebSocket.instances[0];
+    first.open();
+    jest.advanceTimersByTime(250);
+
+    expect(first.closeCount).toBe(1);
+
+    jest.advanceTimersByTime(1_000);
+    expect(MockWebSocket.instances).toHaveLength(2);
+
+    const second = MockWebSocket.instances[1];
+    second.open();
+    jest.advanceTimersByTime(100);
+    expect(JSON.parse(second.sent[0])).toMatchObject({ type: "ping" });
+
+    connection.close();
+  });
+
+  it("cleans up heartbeat and watchdog timers on shutdown", () => {
+    jest.useFakeTimers({ now: 0 });
+    globalThis.WebSocket = MockWebSocket as unknown as typeof WebSocket;
+    const connection = new WebSocketConnection<{ value: number }>(
+      new URL("wss://example.com"),
+      {
+        heartbeatIntervalMs: 100,
+        silentTimeoutMs: 250,
+      }
+    );
+
+    connection.connect();
+    const socket = MockWebSocket.instances[0];
+    socket.open();
+    connection.close();
+    jest.advanceTimersByTime(10_000);
+
+    expect(socket.sent).toEqual([]);
+    expect(socket.closeCount).toBe(1);
+    expect(MockWebSocket.instances).toHaveLength(1);
+  });
+
+  it("stays quiet without a negotiated clock config, including after frames", () => {
+    jest.useFakeTimers({ now: 0 });
+    globalThis.WebSocket = MockWebSocket as unknown as typeof WebSocket;
+    const animationFrames = installAnimationFrameController();
+    const connection = new WebSocketConnection<{ value: number }>(
+      new URL("wss://example.com"),
+      {
+        heartbeatIntervalMs: 0,
+        silentTimeoutMs: 0,
+      }
+    );
+    connection.connect();
+    const socket = MockWebSocket.instances[0];
+    socket.open();
+
+    socket.receive({
+      type: "simulationFrame",
+      frame: {
+        scriptId: "simulation",
+        sequence: 1,
+        state: { value: 1 },
+        serverInvocation: { invocation: 1, timestamp: 0 },
+      },
+    });
+    animationFrames.flush();
+    socket.sent = [];
+
+    jest.advanceTimersByTime(500);
+    expect(socket.sent).toEqual([]);
+    expect(connection.getSimulationFrameDiagnostics()).toMatchObject({
+      simulationClockPulsesActive: false,
+    });
+    connection.close();
+  });
+
+  it("enables and disables clock pulses only from negotiated config", () => {
+    jest.useFakeTimers({ now: 0 });
+    globalThis.WebSocket = MockWebSocket as unknown as typeof WebSocket;
+    const connection = new WebSocketConnection<{ value: number }>(
+      new URL("wss://example.com"),
+      {
+        heartbeatIntervalMs: 0,
+        silentTimeoutMs: 0,
+      }
+    );
+    connection.connect();
+    const socket = MockWebSocket.instances[0];
+    socket.open();
+    socket.receive({
+      type: "simulationClockConfig",
+      enabled: true,
+      intervalMs: 50,
+    });
+    jest.advanceTimersByTime(100);
+    expect(socket.sent.map((message) => JSON.parse(message))).toEqual([
+      { type: "simulationClockPulse" },
+      { type: "simulationClockPulse" },
+    ]);
+
+    socket.receive({ type: "simulationClockConfig", enabled: false });
+    jest.advanceTimersByTime(500);
+    expect(socket.sent).toHaveLength(2);
+    expect(connection.getSimulationFrameDiagnostics()).toMatchObject({
+      simulationClockPulsesActive: false,
+    });
+    connection.close();
+  });
+
+  it("uses the negotiated secondary socket, falls back on failure, and resumes after reconnect", () => {
+    jest.useFakeTimers({ now: 0 });
+    globalThis.WebSocket = MockWebSocket as unknown as typeof WebSocket;
+    const connection = new WebSocketConnection<{ value: number }>(
+      new URL("wss://example.com/m?token=private-token"),
+      {
+        heartbeatIntervalMs: 0,
+        silentTimeoutMs: 0,
+      }
+    );
+    connection.connect();
+    const main = MockWebSocket.instances[0];
+    main.open();
+    main.receive({
+      type: "simulationClockConfig",
+      enabled: true,
+      intervalMs: 50,
+      pulsePath: "/m/pulse",
+    });
+
+    const firstPulse = MockWebSocket.instances[1];
+    expect(firstPulse.url).toBe(
+      "wss://example.com/m/pulse?token=private-token"
+    );
+    jest.advanceTimersByTime(50);
+    expect(main.sent).toEqual([]);
+    firstPulse.open();
+    jest.advanceTimersByTime(100);
+    expect(firstPulse.sent.map((message) => JSON.parse(message))).toEqual([
+      { type: "simulationClockPulse" },
+      { type: "simulationClockPulse" },
+    ]);
+    expect(main.sent).toEqual([]);
+
+    firstPulse.close();
+    jest.advanceTimersByTime(50);
+    expect(main.sent.map((message) => JSON.parse(message))).toEqual([
+      { type: "simulationClockPulse" },
+    ]);
+    jest.advanceTimersByTime(950);
+    const secondPulse = MockWebSocket.instances[2];
+    secondPulse.open();
+    main.sent = [];
+    jest.advanceTimersByTime(50);
+    expect(secondPulse.sent.map((message) => JSON.parse(message))).toEqual([
+      { type: "simulationClockPulse" },
+    ]);
+    expect(main.sent).toEqual([]);
+
+    main.receive({ type: "simulationClockConfig", enabled: false });
+    expect(secondPulse.closeCount).toBe(1);
+    jest.advanceTimersByTime(500);
+    expect(secondPulse.sent).toHaveLength(1);
+    connection.close();
+  });
+
+  it("closes the secondary pulse socket on main silence and permanent close", () => {
+    jest.useFakeTimers({ now: 0 });
+    globalThis.WebSocket = MockWebSocket as unknown as typeof WebSocket;
+    const connection = new WebSocketConnection<{ value: number }>(
+      new URL("wss://example.com/m?token=private-token"),
+      {
+        heartbeatIntervalMs: 0,
+        silentTimeoutMs: 125,
+      }
+    );
+    connection.connect();
+    const main = MockWebSocket.instances[0];
+    main.open();
+    main.receive({
+      type: "simulationClockConfig",
+      enabled: true,
+      intervalMs: 50,
+      pulsePath: "/m/pulse",
+    });
+    const pulse = MockWebSocket.instances[1];
+    pulse.open();
+    jest.advanceTimersByTime(125);
+    expect(main.closeCount).toBe(1);
+    expect(pulse.closeCount).toBe(1);
+
+    connection.close();
+    jest.advanceTimersByTime(500);
+    expect(pulse.sent).toHaveLength(2);
+  });
+
+  it("cleans up negotiated clock pulses on silence and close", () => {
+    jest.useFakeTimers({ now: 0 });
+    globalThis.WebSocket = MockWebSocket as unknown as typeof WebSocket;
+    const connection = new WebSocketConnection<{ value: number }>(
+      new URL("wss://example.com"),
+      {
+        heartbeatIntervalMs: 0,
+        silentTimeoutMs: 125,
+      }
+    );
+    connection.connect();
+    const socket = MockWebSocket.instances[0];
+    socket.open();
+    socket.receive({
+      type: "simulationClockConfig",
+      enabled: true,
+      intervalMs: 50,
+    });
+    jest.advanceTimersByTime(125);
+    expect(socket.closeCount).toBe(1);
+    expect(connection.getSimulationFrameDiagnostics()).toMatchObject({
+      simulationClockPulsesActive: false,
+    });
+
+    connection.close();
+    jest.advanceTimersByTime(500);
+    expect(connection.getSimulationFrameDiagnostics()).toMatchObject({
+      simulationClockPulsesActive: false,
+    });
+  });
+
+  it("coalesces burst simulation frames to the latest sequence", () => {
+    jest.useFakeTimers({ now: 0 });
+    globalThis.WebSocket = MockWebSocket as unknown as typeof WebSocket;
+    globalThis.requestAnimationFrame =
+      undefined as unknown as typeof requestAnimationFrame;
+    const events: ConnectionEvent<{ value: number }>[] = [];
+    const connection = new WebSocketConnection<{ value: number }>(
+      new URL("wss://example.com"),
+      {
+        heartbeatIntervalMs: 0,
+        silentTimeoutMs: 0,
+        onConnectionEvent: (event) => events.push(event),
+      }
+    );
+    connection.connect();
+    const socket = MockWebSocket.instances[0];
+    socket.open();
+    for (const sequence of [2, 1]) {
+      socket.receive({
+        type: "simulationFrame",
+        frame: {
+          scriptId: "simulation",
+          sequence,
+          state: { value: sequence },
+          serverInvocation: {
+            scriptId: "simulation",
+            invocation: sequence,
+            timestamp: sequence * 100,
+          },
+        },
+      });
+    }
+    expect(socket.sent).toEqual([]);
+    expect(events.filter((event) => event.type === "receive")).toHaveLength(0);
+    jest.runOnlyPendingTimers();
+
+    expect(socket.sent.map((message) => JSON.parse(message))).toEqual([
+      {
+        type: "clientMessageBatch",
+        receipt: {
+          type: "simulationFrameReceipt",
+          scriptId: "simulation",
+          sequence: 2,
+        },
+        messages: [],
+      },
+    ]);
+    const received = events.filter(
+      (event): event is Extract<typeof event, { type: "receive" }> =>
+        event.type === "receive"
+    );
+    expect(received).toHaveLength(1);
+    expect(received[0].message).toMatchObject({
+      type: "simulationFrame",
+      frame: { sequence: 2, state: { value: 2 } },
+    });
+    expect(connection.getSimulationFrameDiagnostics()).toEqual({
+      pending: 0,
+      dropped: 1,
+      pendingReceipts: 0,
+      queuedRealtimeInputs: 0,
+      replayRealtimeInputs: 0,
+      unconfirmedRealtimeBatches: 0,
+      realtimeBatchesSent: 1,
+      realtimeInputsSent: 0,
+      realtimeWatchdogArmed: false,
+      simulationClockPulsesActive: false,
+    });
+    connection.close();
+  });
+
+  it("keeps outer reconnect resumption monotonic while acknowledging rewound frames", () => {
+    jest.useFakeTimers({ now: 0 });
+    globalThis.WebSocket = MockWebSocket as unknown as typeof WebSocket;
+    globalThis.requestAnimationFrame =
+      undefined as unknown as typeof requestAnimationFrame;
+    type State = {
+      simulation: { tick: number };
+      $game: { startedAt: number; simulationTick: number };
+    };
+    const received: Array<
+      Extract<ConnectionEvent<State>, { type: "receive" }>["message"]
+    > = [];
+    const connection = new WebSocketConnection<State>(
+      new URL("wss://example.com"),
+      {
+        heartbeatIntervalMs: 0,
+        silentTimeoutMs: 0,
+        onConnectionEvent: (event) => {
+          if (event.type === "receive") received.push(event.message);
+        },
+      }
+    );
+    const state = (tick: number): State => ({
+      simulation: { tick },
+      $game: { startedAt: 1, simulationTick: 0 },
+    });
+    const frame = (sequence: number) => ({
+      type: "simulationFrame" as const,
+      frame: {
+        scriptId: "snakes-realtime",
+        sequence,
+        state: state(sequence),
+        serverInvocation: {
+          scriptId: "snakes-realtime",
+          invocation: sequence,
+          timestamp: sequence * 100,
+        },
+      },
+    });
+
+    connection.connect();
+    const first = MockWebSocket.instances[0];
+    first.open();
+    first.receive(frame(10));
+    jest.runOnlyPendingTimers();
+    first.close();
+    jest.advanceTimersByTime(1_000);
+
+    const second = MockWebSocket.instances[1];
+    second.open();
+    second.receive({ type: "object", object: state(8) });
+    second.receive(frame(8));
+    jest.runOnlyPendingTimers();
+    second.receive(frame(9));
+    jest.runOnlyPendingTimers();
+    second.receive(frame(11));
+    jest.runOnlyPendingTimers();
+
+    expect(
+      received.map((message) =>
+        message.type === "simulationFrame"
+          ? ["frame", message.frame.sequence]
+          : [message.type]
+      )
+    ).toEqual([
+      ["frame", 10],
+      ["frame", 11],
+    ]);
+    expect(
+      second.sent
+        .map((message) => JSON.parse(message))
+        .filter((message) => message.receipt)
+        .map((message) => message.receipt.sequence)
+    ).toEqual([8, 9, 11]);
+    connection.close();
+  });
+
+  it("acknowledges each script before independently coalescing its frame", () => {
+    jest.useFakeTimers({ now: 0 });
+    globalThis.WebSocket = MockWebSocket as unknown as typeof WebSocket;
+    globalThis.requestAnimationFrame =
+      undefined as unknown as typeof requestAnimationFrame;
+    const events: ConnectionEvent<{ value: number }>[] = [];
+    const connection = new WebSocketConnection<{ value: number }>(
+      new URL("wss://example.com"),
+      {
+        heartbeatIntervalMs: 0,
+        silentTimeoutMs: 0,
+        onConnectionEvent: (event) => events.push(event),
+      }
+    );
+    connection.connect();
+    const socket = MockWebSocket.instances[0];
+    socket.open();
+
+    for (const [scriptId, sequence] of [
+      ["movement", 3],
+      ["particles", 8],
+      ["movement", 4],
+    ] as const) {
+      socket.receive({
+        type: "simulationFrame",
+        frame: {
+          scriptId,
+          sequence,
+          state: { value: sequence },
+          serverInvocation: {
+            scriptId,
+            invocation: sequence,
+            timestamp: sequence * 100,
+          },
+        },
+      });
+    }
+
+    expect(socket.sent).toEqual([]);
+    expect(events.filter((event) => event.type === "receive")).toHaveLength(0);
+
+    jest.runOnlyPendingTimers();
+    expect(socket.sent.map((message) => JSON.parse(message))).toEqual([
+      {
+        type: "clientMessageBatch",
+        receipt: {
+          type: "simulationFrameReceipt",
+          scriptId: "movement",
+          sequence: 4,
+        },
+        messages: [],
+      },
+      {
+        type: "clientMessageBatch",
+        receipt: {
+          type: "simulationFrameReceipt",
+          scriptId: "particles",
+          sequence: 8,
+        },
+        messages: [],
+      },
+    ]);
+    const receivedFrames = events
+      .filter(
+        (
+          event
+        ): event is Extract<
+          ConnectionEvent<{ value: number }>,
+          { type: "receive" }
+        > => event.type === "receive"
+      )
+      .map((event) => event.message)
+      .filter((message) => message.type === "simulationFrame")
+      .map((message) => [message.frame.scriptId, message.frame.sequence]);
+    expect(receivedFrames).toEqual([
+      ["movement", 4],
+      ["particles", 8],
+    ]);
+    connection.close();
+  });
+
+  it("flushes pending frames before later non-frame messages", () => {
+    jest.useFakeTimers({ now: 0 });
+    globalThis.WebSocket = MockWebSocket as unknown as typeof WebSocket;
+    globalThis.requestAnimationFrame =
+      undefined as unknown as typeof requestAnimationFrame;
+    const cancelAnimationFrame = jest.fn((_handle: number) => {});
+    globalThis.cancelAnimationFrame = cancelAnimationFrame;
+    const events: ConnectionEvent<{ value: number }>[] = [];
+    const connection = new WebSocketConnection<{ value: number }>(
+      new URL("wss://example.com"),
+      {
+        heartbeatIntervalMs: 0,
+        silentTimeoutMs: 0,
+        onConnectionEvent: (event) => events.push(event),
+      }
+    );
+    connection.connect();
+    const socket = MockWebSocket.instances[0];
+    socket.open();
+    socket.receive({
+      type: "simulationFrame",
+      frame: {
+        scriptId: "simulation",
+        sequence: 1,
+        state: { value: 1 },
+        serverInvocation: {
+          scriptId: "simulation",
+          invocation: 1,
+          timestamp: 100,
+        },
+      },
+    });
+    socket.receive({
+      type: "acceptPatch",
+      id: "lifecycle",
+      patches: [{ op: "replace", path: ["value"], value: 2 }],
+    });
+
+    const received = events
+      .filter(
+        (event): event is Extract<typeof event, { type: "receive" }> =>
+          event.type === "receive"
+      )
+      .map((event) => event.message.type);
+    expect(received).toEqual(["simulationFrame", "acceptPatch"]);
+    expect(cancelAnimationFrame).not.toHaveBeenCalled();
+    expect(jest.getTimerCount()).toBe(0);
+    jest.runOnlyPendingTimers();
+    expect(events.filter((event) => event.type === "receive")).toHaveLength(2);
+    connection.close();
+  });
+
+  for (const inputRateHz of [0, 5, 10, 30]) {
+    it(`preserves injected 10 Hz frame cadence and ordered ${inputRateHz} Hz input batching`, () => {
+      jest.useFakeTimers({ now: 0 });
+      globalThis.WebSocket = MockWebSocket as unknown as typeof WebSocket;
+      const animationFrames = installAnimationFrameController();
+      const deliveryTimes: number[] = [];
+      const injectionTimes: number[] = [];
+      const connection = new WebSocketConnection<{ value: number }>(
+        new URL("wss://example.com"),
+        {
+          heartbeatIntervalMs: 0,
+          silentTimeoutMs: 0,
+          realtimeInputWatchdogMs: 200,
+          onConnectionEvent: (event) => {
+            if (
+              event.type === "receive" &&
+              event.message.type === "simulationFrame"
+            ) {
+              deliveryTimes.push(Date.now());
+            }
+          },
+        }
+      );
+      connection.connect();
+      const socket = MockWebSocket.instances[0];
+      socket.open();
+      let inputSequence = 0;
+      const inputIntervalMs =
+        inputRateHz === 0 ? Number.POSITIVE_INFINITY : 1000 / inputRateHz;
+      let nextInputAt = 0;
+      let inspectedBatchCount = 0;
+
+      for (let now = 0; now <= 1_000; now += 1) {
+        if (now > 0) jest.advanceTimersByTime(1);
+        if (inputRateHz > 0 && now >= nextInputAt) {
+          connection.send({
+            type: "enqueueInput",
+            queue: "noya.game.realtime",
+            transport: "realtime",
+            payload: {
+              streamId: "movement",
+              sequence: inputSequence,
+              input: { dx: 1 },
+            },
+          });
+          inputSequence += 1;
+          nextInputAt += inputIntervalMs;
+        }
+        if (now % 100 === 0) {
+          const sequence = now / 100;
+          injectionTimes.push(Date.now());
+          socket.receive({
+            type: "simulationFrame",
+            frame: {
+              scriptId: "simulation",
+              sequence,
+              state: { value: sequence },
+              serverInvocation: {
+                scriptId: "simulation",
+                invocation: sequence,
+                timestamp: now,
+              },
+            },
+          });
+          animationFrames.flush();
+          for (
+            ;
+            inspectedBatchCount < socket.sent.length;
+            inspectedBatchCount += 1
+          ) {
+            const batch = JSON.parse(socket.sent[inspectedBatchCount]);
+            if (!batch.inputBatch) continue;
+            socket.receive({
+              type: "realtimeInputReceipt",
+              ...batch.inputBatch,
+            });
+          }
+        }
+      }
+
+      const batches = socket.sent.map((message) => JSON.parse(message));
+      const inputSequences = batches.flatMap((batch) =>
+        batch.messages.map(
+          (message: { payload: { sequence: number } }) =>
+            message.payload.sequence
+        )
+      );
+      expect(batches).toHaveLength(11);
+      expect(batches.every((batch) => batch.receipt)).toBe(true);
+      expect(inputSequences).toEqual(
+        Array.from({ length: inputSequence }, (_, index) => index)
+      );
+      expect(
+        deliveryTimes.map((time, index) => time - injectionTimes[index])
+      ).toEqual(Array(11).fill(0));
+      expect(
+        deliveryTimes.slice(1).map((time, index) => time - deliveryTimes[index])
+      ).toEqual(
+        injectionTimes
+          .slice(1)
+          .map((time, index) => time - injectionTimes[index])
+      );
+      connection.close();
+    });
+  }
+
+  it("batches 30 Hz input into frame-rate upstream events under a three-frame server window", () => {
+    jest.useFakeTimers({ now: 0 });
+    globalThis.WebSocket = MockWebSocket as unknown as typeof WebSocket;
+    const animationFrames = installAnimationFrameController();
+    const connection = new WebSocketConnection<{ value: number }>(
+      new URL("wss://example.com"),
+      {
+        heartbeatIntervalMs: 0,
+        silentTimeoutMs: 0,
+        realtimeInputWatchdogMs: 200,
+      }
+    );
+    connection.connect();
+    const socket = MockWebSocket.instances[0];
+    socket.open();
+
+    const serverWindowSize = 3;
+    const inFlightFrames: number[] = [];
+    let pendingFrame: number | undefined;
+    let maxInFlightFrames = 0;
+    let processedUpstreamEvents = 0;
+    let nextUpstreamEvent = 0;
+    let ingestedInputBatchSequence = -1;
+    const ingestedInputSequences: number[] = [];
+    const frameReceiptSequences: number[] = [];
+    const cumulativeInputReceipts: number[] = [];
+
+    const deliverFrame = (sequence: number) => {
+      inFlightFrames.push(sequence);
+      maxInFlightFrames = Math.max(maxInFlightFrames, inFlightFrames.length);
+      socket.receive({
+        type: "simulationFrame",
+        frame: {
+          scriptId: "simulation",
+          sequence,
+          state: { value: sequence },
+          serverInvocation: {
+            scriptId: "simulation",
+            invocation: sequence,
+            timestamp: sequence * 100,
+          },
+        },
+      });
+    };
+    const publishFrame = (sequence: number) => {
+      if (inFlightFrames.length < serverWindowSize) {
+        deliverFrame(sequence);
+      } else {
+        pendingFrame = sequence;
+      }
+    };
+    const processUpstreamEvents = () => {
+      do {
+        while (nextUpstreamEvent < socket.sent.length) {
+          const batch = JSON.parse(socket.sent[nextUpstreamEvent++]);
+          processedUpstreamEvents += 1;
+          if (batch.receipt) {
+            frameReceiptSequences.push(batch.receipt.sequence);
+            const acknowledgedIndex = inFlightFrames.indexOf(
+              batch.receipt.sequence
+            );
+            if (acknowledgedIndex >= 0) {
+              inFlightFrames.splice(0, acknowledgedIndex + 1);
+            }
+            if (
+              pendingFrame !== undefined &&
+              inFlightFrames.length < serverWindowSize
+            ) {
+              const sequence = pendingFrame;
+              pendingFrame = undefined;
+              deliverFrame(sequence);
+            }
+          }
+          if (batch.inputBatch) {
+            expect(batch.inputBatch.sequence).toBe(
+              ingestedInputBatchSequence + 1
+            );
+            ingestedInputBatchSequence = batch.inputBatch.sequence;
+            ingestedInputSequences.push(
+              ...batch.messages.map(
+                (message: { payload: { sequence: number } }) =>
+                  message.payload.sequence
+              )
+            );
+            cumulativeInputReceipts.push(ingestedInputBatchSequence);
+            socket.receive({
+              type: "realtimeInputReceipt",
+              sessionId: batch.inputBatch.sessionId,
+              sequence: ingestedInputBatchSequence,
+            });
+          }
+        }
+        animationFrames.flush();
+      } while (nextUpstreamEvent < socket.sent.length);
+    };
+
+    let generatedInputCount = 0;
+    let nextInputAt = 0;
+    for (let now = 0; now <= 1_200; now += 1) {
+      if (now > 0) jest.advanceTimersByTime(1);
+      if (now <= 1_000 && now >= nextInputAt) {
+        connection.send({
+          type: "enqueueInput",
+          queue: "noya.game.realtime",
+          transport: "realtime",
+          payload: {
+            streamId: "movement",
+            sequence: generatedInputCount,
+            input: { dx: 1 },
+          },
+        });
+        generatedInputCount += 1;
+        nextInputAt += 1000 / 30;
+      }
+      if (now <= 1_000 && now % 100 === 0) {
+        publishFrame(now / 100);
+        animationFrames.flush();
+      }
+      if (now % 300 === 0) {
+        processUpstreamEvents();
+      }
+    }
+
+    expect(maxInFlightFrames).toBe(serverWindowSize);
+    expect(processedUpstreamEvents).toBeLessThanOrEqual(13);
+    expect(processedUpstreamEvents).toBeGreaterThanOrEqual(10);
+    expect(ingestedInputSequences).toEqual(
+      Array.from({ length: generatedInputCount }, (_, index) => index)
+    );
+    expect(frameReceiptSequences.at(-1)).toBe(10);
+    expect(cumulativeInputReceipts).toEqual(
+      Array.from(
+        { length: ingestedInputBatchSequence + 1 },
+        (_, index) => index
+      )
+    );
+    connection.close();
+  });
+
+  it("uses a low-rate watchdog when no simulation frame arrives", () => {
+    jest.useFakeTimers({ now: 0 });
+    globalThis.WebSocket = MockWebSocket as unknown as typeof WebSocket;
+    const connection = new WebSocketConnection<{ value: number }>(
+      new URL("wss://example.com"),
+      {
+        heartbeatIntervalMs: 0,
+        silentTimeoutMs: 0,
+        realtimeInputWatchdogMs: 200,
+      }
+    );
+    connection.connect();
+    const socket = MockWebSocket.instances[0];
+    socket.open();
+    for (const sequence of [0, 1, 2]) {
+      connection.send({
+        type: "enqueueInput",
+        queue: "noya.game.realtime",
+        transport: "realtime",
+        payload: {
+          streamId: "movement",
+          sequence,
+          input: { dx: sequence },
+        },
+      });
+    }
+
+    jest.advanceTimersByTime(199);
+    expect(socket.sent).toEqual([]);
+    jest.advanceTimersByTime(1);
+    expect(socket.sent.map((message) => JSON.parse(message))).toEqual([
+      {
+        type: "clientMessageBatch",
+        inputBatch: {
+          sessionId: expect.any(String),
+          sequence: 0,
+        },
+        messages: [
+          expect.objectContaining({
+            payload: expect.objectContaining({ sequence: 0 }),
+          }),
+          expect.objectContaining({
+            payload: expect.objectContaining({ sequence: 1 }),
+          }),
+          expect.objectContaining({
+            payload: expect.objectContaining({ sequence: 2 }),
+          }),
+        ],
+      },
+    ]);
+    connection.close();
+  });
+
+  it("replays a batch when disconnect happens immediately after send", () => {
+    jest.useFakeTimers({ now: 0 });
+    globalThis.WebSocket = MockWebSocket as unknown as typeof WebSocket;
+    const connection = new WebSocketConnection<{ value: number }>(
+      new URL("wss://example.com"),
+      {
+        heartbeatIntervalMs: 0,
+        silentTimeoutMs: 0,
+        realtimeInputWatchdogMs: 200,
+      }
+    );
+    connection.connect();
+    const first = MockWebSocket.instances[0];
+    first.open();
+    connection.send({
+      type: "enqueueInput",
+      queue: "noya.game.realtime",
+      transport: "realtime",
+      payload: { streamId: "movement", sequence: 0, input: { dx: 1 } },
+    });
+    jest.advanceTimersByTime(200);
+    const originalBatch = JSON.parse(first.sent[0]);
+    first.close();
+    jest.advanceTimersByTime(1_000);
+
+    const second = MockWebSocket.instances[1];
+    second.open();
+    expect(second.sent.map((message) => JSON.parse(message))).toEqual([
+      originalBatch,
+    ]);
+    expect(
+      second.sent
+        .map((message) => JSON.parse(message))
+        .flatMap((batch) => batch.messages)
+        .map((message) => message.payload.sequence)
+    ).toEqual([0]);
+    connection.close();
+  });
+
+  it("does not treat a pre-existing in-flight frame as input ingestion", () => {
+    jest.useFakeTimers({ now: 0 });
+    globalThis.WebSocket = MockWebSocket as unknown as typeof WebSocket;
+    const animationFrames = installAnimationFrameController();
+    const connection = new WebSocketConnection<{ value: number }>(
+      new URL("wss://example.com"),
+      {
+        heartbeatIntervalMs: 0,
+        silentTimeoutMs: 0,
+        realtimeInputWatchdogMs: 200,
+      }
+    );
+    connection.connect();
+    const first = MockWebSocket.instances[0];
+    first.open();
+    first.receive({
+      type: "simulationFrame",
+      frame: {
+        scriptId: "simulation",
+        sequence: 7,
+        state: { value: 7 },
+        serverInvocation: {
+          scriptId: "simulation",
+          invocation: 7,
+          timestamp: 0,
+        },
+      },
+    });
+    connection.send({
+      type: "enqueueInput",
+      queue: "noya.game.realtime",
+      transport: "realtime",
+      payload: { streamId: "movement", sequence: 0, input: { dx: 1 } },
+    });
+    animationFrames.flush();
+    expect(
+      connection.getSimulationFrameDiagnostics().replayRealtimeInputs
+    ).toBe(1);
+    first.close();
+    jest.advanceTimersByTime(1_000);
+
+    const second = MockWebSocket.instances[1];
+    second.open();
+    expect(
+      second.sent
+        .map((message) => JSON.parse(message))
+        .flatMap((batch) => batch.messages)
+        .map((message) => message.payload.sequence)
+    ).toEqual([0]);
+    connection.close();
+  });
+
+  it("drops replay history only after cumulative ingestion confirmation", () => {
+    jest.useFakeTimers({ now: 0 });
+    globalThis.WebSocket = MockWebSocket as unknown as typeof WebSocket;
+    const connection = new WebSocketConnection<{ value: number }>(
+      new URL("wss://example.com"),
+      {
+        heartbeatIntervalMs: 0,
+        silentTimeoutMs: 0,
+        realtimeInputWatchdogMs: 200,
+      }
+    );
+    connection.connect();
+    const first = MockWebSocket.instances[0];
+    first.open();
+    connection.send({
+      type: "enqueueInput",
+      queue: "noya.game.realtime",
+      transport: "realtime",
+      payload: { streamId: "movement", sequence: 0, input: { dx: 1 } },
+    });
+    jest.advanceTimersByTime(200);
+    const sentBatch = JSON.parse(first.sent[0]);
+    first.receive({
+      type: "realtimeInputReceipt",
+      ...sentBatch.inputBatch,
+    });
+    expect(connection.getSimulationFrameDiagnostics()).toMatchObject({
+      replayRealtimeInputs: 0,
+      unconfirmedRealtimeBatches: 0,
+    });
+    first.close();
+    jest.advanceTimersByTime(1_000);
+
+    const second = MockWebSocket.instances[1];
+    second.open();
+    expect(second.sent).toEqual([]);
+    connection.close();
+  });
+
+  it("bounds unconfirmed replay batches without introducing input gaps", () => {
+    jest.useFakeTimers({ now: 0 });
+    globalThis.WebSocket = MockWebSocket as unknown as typeof WebSocket;
+    const animationFrames = installAnimationFrameController();
+    const connection = new WebSocketConnection<{ value: number }>(
+      new URL("wss://example.com"),
+      {
+        heartbeatIntervalMs: 0,
+        silentTimeoutMs: 0,
+        realtimeInputWatchdogMs: 200,
+      }
+    );
+    connection.connect();
+    const socket = MockWebSocket.instances[0];
+    socket.open();
+    const receiveFrame = (sequence: number) => {
+      socket.receive({
+        type: "simulationFrame",
+        frame: {
+          scriptId: "simulation",
+          sequence,
+          state: { value: sequence },
+          serverInvocation: {
+            scriptId: "simulation",
+            invocation: sequence,
+            timestamp: sequence * 100,
+          },
+        },
+      });
+      animationFrames.flush();
+    };
+
+    for (const sequence of [0, 1, 2, 3]) {
+      connection.send({
+        type: "enqueueInput",
+        queue: "noya.game.realtime",
+        transport: "realtime",
+        payload: {
+          streamId: "movement",
+          sequence,
+          input: { dx: sequence },
+        },
+      });
+      receiveFrame(sequence);
+    }
+    expect(connection.getSimulationFrameDiagnostics()).toMatchObject({
+      queuedRealtimeInputs: 1,
+      replayRealtimeInputs: 3,
+      unconfirmedRealtimeBatches: 3,
+    });
+
+    const inputBatches = socket.sent
+      .map((message) => JSON.parse(message))
+      .filter((batch) => batch.inputBatch);
+    socket.receive({
+      type: "realtimeInputReceipt",
+      sessionId: inputBatches[0].inputBatch.sessionId,
+      sequence: 1,
+    });
+    receiveFrame(4);
+
+    const sentSequences = socket.sent
+      .map((message) => JSON.parse(message))
+      .flatMap((batch) => batch.messages)
+      .map((message) => message.payload.sequence);
+    expect(sentSequences).toEqual([0, 1, 2, 3]);
+    expect(connection.getSimulationFrameDiagnostics()).toMatchObject({
+      queuedRealtimeInputs: 0,
+      replayRealtimeInputs: 2,
+      unconfirmedRealtimeBatches: 2,
+    });
+    connection.close();
+  });
+
+  it("keeps discrete and game-action inputs immediate", () => {
+    jest.useFakeTimers({ now: 0 });
+    globalThis.WebSocket = MockWebSocket as unknown as typeof WebSocket;
+    const connection = new WebSocketConnection<{ value: number }>(
+      new URL("wss://example.com"),
+      {
+        heartbeatIntervalMs: 0,
+        silentTimeoutMs: 0,
+      }
+    );
+    connection.connect();
+    const socket = MockWebSocket.instances[0];
+    socket.open();
+    connection.send({
+      type: "enqueueInput",
+      queue: "controller",
+      payload: { delta: 1 },
+    });
+    connection.send({
+      type: "enqueueInput",
+      queue: "noya.game.actions",
+      payload: { actionId: "move-1", action: { type: "move" } },
+    });
+
+    expect(socket.sent.map((message) => JSON.parse(message))).toEqual([
+      {
+        type: "enqueueInput",
+        queue: "controller",
+        payload: { delta: 1 },
+      },
+      {
+        type: "enqueueInput",
+        queue: "noya.game.actions",
+        payload: { actionId: "move-1", action: { type: "move" } },
+      },
+    ]);
+    connection.close();
+  });
+});