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

package/dist/index.js

@@ -1517,6 +1517,7 @@ __export(src_exports, {
   importAll: () => importAll,
   initializeNoyaSingleton: () => initializeNoyaSingleton,
   parseAppDataParameter: () => parseAppDataParameter,
+  parseInspectorParameter: () => parseInspectorParameter,
   replaceDeep: () => replaceDeep,
   resourceToCreateParameters: () => resourceToCreateParameters,
   resourceToMediaItem: () => resourceToMediaItem,
@@ -7798,6 +7799,16 @@ function parseAppDataParameter(options) {
     return null;
   }
 }
+function parseInspectorParameter(options) {
+  const window2 = options?.window ?? globalThis;
+  const location = window2.location;
+  if (!location) return null;
+  const params = new URLSearchParams((location.hash || "").replace(/^#/, ""));
+  const inspector = params.get("inspector");
+  if (inspector === "true") return true;
+  if (inspector === "false") return false;
+  return null;
+}
 function applyClientIdentityFromAppData(appData) {
   if (appData.clientId !== void 0) {
     (0, import_state_manager3.setClientId)(appData.clientId);
@@ -7812,6 +7823,8 @@ function applyClientIdentityFromAppData(appData) {
 function getAppData(initialState, schema, options) {
   const resolvedInitialState = initialState instanceof Function ? initialState() : initialState;
   let appData = parseAppDataParameter(options) ?? createDefaultAppData(resolvedInitialState);
+  const inspector = parseInspectorParameter(options);
+  if (inspector !== null) appData.inspector = inspector;
   if (options?.overrideExistingState || appData.initialState === null) {
     appData.initialState = resolvedInitialState;
   }
@@ -8597,6 +8610,32 @@ function useResourceUrl(idOrStableId, options) {
 
 // src/WebSocketConnection.ts
 var import_state_manager7 = require("@noya-app/state-manager");
+function simulationSessionIdentity(state) {
+  if (!state || typeof state !== "object" || Array.isArray(state)) return;
+  const game = Reflect.get(state, "$game");
+  if (!game || typeof game !== "object" || Array.isArray(game)) return;
+  const startedAt = Reflect.get(game, "startedAt");
+  if (startedAt === null || typeof startedAt === "string" || typeof startedAt === "number" && Number.isFinite(startedAt)) {
+    return `startedAt:${typeof startedAt}:${String(startedAt)}`;
+  }
+}
+function simulationStateSequence(state) {
+  if (!state || typeof state !== "object" || Array.isArray(state)) return;
+  const simulation = Reflect.get(state, "simulation");
+  const simulationTick = simulation && typeof simulation === "object" ? Reflect.get(simulation, "tick") : void 0;
+  if (Number.isSafeInteger(simulationTick) && simulationTick >= 0) {
+    return simulationTick;
+  }
+  const game = Reflect.get(state, "$game");
+  const gameTick = game && typeof game === "object" ? Reflect.get(game, "simulationTick") : void 0;
+  return Number.isSafeInteger(gameTick) && gameTick >= 0 ? gameTick : void 0;
+}
+function sameSimulationSession(left, right) {
+  return left.sessionIdentity === void 0 || right.sessionIdentity === void 0 || left.sessionIdentity === right.sessionIdentity;
+}
+function createRealtimeInputSessionId() {
+  return typeof crypto !== "undefined" && typeof crypto.randomUUID === "function" ? crypto.randomUUID() : `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+}
 var WebSocketConnection = class {
   constructor(url, options = {}) {
     this.url = url;
@@ -8611,12 +8650,40 @@ var WebSocketConnection = class {
   }
   ws;
   closedForever = false;
+  heartbeatIntervalHandle;
+  silentTimeoutHandle;
+  simulationClockPulseIntervalHandle;
+  simulationClockPulseSocket;
+  simulationClockDirectFailed = false;
+  heartbeatSequence = 0;
+  pendingSimulationFrames = /* @__PURE__ */ new Map();
+  frameFlushHandle;
+  frameFlushScheduler;
+  droppedSimulationFrames = 0;
+  pendingFrameReceipts = /* @__PURE__ */ new Map();
+  deliveredSimulationFrameCursors = /* @__PURE__ */ new Map();
+  queuedRealtimeInputs = [];
+  /**
+   * A batch stays here until the server explicitly confirms ingestion.
+   * Reconnects resend these exact batches, so a frame that was already in
+   * flight can never create a hole in an input stream.
+   */
+  unconfirmedRealtimeBatches = [];
+  lastSentRealtimeSequences = /* @__PURE__ */ new Map();
+  realtimeInputSessionId = createRealtimeInputSessionId();
+  nextRealtimeInputBatchSequence = 0;
+  realtimeInputWatchdogHandle;
+  realtimeBatchesSent = 0;
+  realtimeInputsSent = 0;
   async connect() {
     if (this.closedForever) return;
     this.ws.connect(this.url.toString());
   }
   handleOpen = () => {
     if (this.closedForever) return;
+    this.startHeartbeat();
+    this.replayUnconfirmedRealtimeBatches();
+    this.armRealtimeInputWatchdog();
     if (this.options.debug) {
       console.info("ws connected");
     }
@@ -8627,16 +8694,124 @@ var WebSocketConnection = class {
   };
   handleMessage = (event) => {
     if (this.closedForever) return;
+    this.armSilentTimeout();
     if (this.options.debug) {
       console.info("ws receiving message ", event.data);
     }
     const parsed = JSON.parse(event.data);
+    if (parsed.type === "simulationClockConfig") {
+      this.applySimulationClockConfig(parsed);
+      return;
+    }
+    if (parsed.type === "simulationFrame") {
+      const cursor = {
+        sequence: parsed.frame.sequence,
+        sessionIdentity: simulationSessionIdentity(parsed.frame.state)
+      };
+      const receipt = {
+        type: "simulationFrameReceipt",
+        scriptId: parsed.frame.scriptId,
+        sequence: parsed.frame.sequence
+      };
+      const pendingReceipt = this.pendingFrameReceipts.get(
+        parsed.frame.scriptId
+      );
+      if (!pendingReceipt || receipt.sequence > pendingReceipt.sequence) {
+        this.pendingFrameReceipts.set(parsed.frame.scriptId, receipt);
+      }
+      const delivered = this.deliveredSimulationFrameCursors.get(
+        parsed.frame.scriptId
+      );
+      const pending = this.pendingSimulationFrames.get(parsed.frame.scriptId);
+      const pendingCursor = pending ? {
+        sequence: pending.frame.sequence,
+        sessionIdentity: simulationSessionIdentity(pending.frame.state)
+      } : void 0;
+      if (delivered && sameSimulationSession(delivered, cursor) && cursor.sequence <= delivered.sequence || pendingCursor && sameSimulationSession(pendingCursor, cursor) && cursor.sequence <= pendingCursor.sequence) {
+        this.droppedSimulationFrames += 1;
+        this.scheduleSimulationFrameFlush();
+        return;
+      }
+      if (pending) this.droppedSimulationFrames += 1;
+      this.pendingSimulationFrames.set(parsed.frame.scriptId, parsed);
+      this.scheduleSimulationFrameFlush();
+      return;
+    }
+    if (parsed.type === "object" && this.shouldSuppressNonMonotonicObject(parsed.object)) {
+      return;
+    }
+    if (parsed.type === "realtimeInputReceipt") {
+      this.confirmRealtimeInputBatches(parsed.sessionId, parsed.sequence);
+      return;
+    }
+    this.flushSimulationFrames();
+    this.emitReceivedMessage(parsed);
+  };
+  emitReceivedMessage(message) {
     this.options.onConnectionEvent?.({
       type: "receive",
-      message: parsed
+      message
     });
-  };
+  }
+  scheduleSimulationFrameFlush() {
+    if (this.frameFlushHandle !== void 0) return;
+    const flush = () => {
+      this.frameFlushHandle = void 0;
+      this.frameFlushScheduler = void 0;
+      this.flushSimulationFrames();
+    };
+    if (typeof requestAnimationFrame === "function") {
+      this.frameFlushScheduler = "animationFrame";
+      this.frameFlushHandle = requestAnimationFrame(flush);
+    } else {
+      this.frameFlushScheduler = "timeout";
+      this.frameFlushHandle = setTimeout(flush, 0);
+    }
+  }
+  flushSimulationFrames() {
+    this.cancelSimulationFrameFlush();
+    this.flushPendingFrameReceipts();
+    const frames = Array.from(this.pendingSimulationFrames.values());
+    this.pendingSimulationFrames.clear();
+    for (const frame of frames) {
+      this.deliveredSimulationFrameCursors.set(frame.frame.scriptId, {
+        sequence: frame.frame.sequence,
+        sessionIdentity: simulationSessionIdentity(frame.frame.state)
+      });
+      this.emitReceivedMessage(frame);
+    }
+  }
+  shouldSuppressNonMonotonicObject(state) {
+    const sequence = simulationStateSequence(state);
+    if (sequence === void 0) return false;
+    const cursor = {
+      sequence,
+      sessionIdentity: simulationSessionIdentity(state)
+    };
+    const previous = Array.from(this.deliveredSimulationFrameCursors.values());
+    const comparable = previous.filter(
+      (entry) => sameSimulationSession(entry, cursor)
+    );
+    if (cursor.sessionIdentity !== void 0 && previous.some((entry) => entry.sessionIdentity !== void 0) && comparable.length === 0) {
+      this.deliveredSimulationFrameCursors.clear();
+      return false;
+    }
+    return comparable.some((entry) => entry.sequence > cursor.sequence);
+  }
+  cancelSimulationFrameFlush() {
+    if (this.frameFlushHandle === void 0) return;
+    if (this.frameFlushScheduler === "animationFrame") {
+      cancelAnimationFrame(this.frameFlushHandle);
+    } else {
+      clearTimeout(this.frameFlushHandle);
+    }
+    this.frameFlushHandle = void 0;
+    this.frameFlushScheduler = void 0;
+  }
   handleClose = () => {
+    this.stopHeartbeat();
+    this.stopSimulationClockPulses();
+    this.stopRealtimeInputWatchdog();
     if (this.closedForever) return;
     if (this.options.debug) {
       console.info("ws disconnected");
@@ -8646,8 +8821,140 @@ var WebSocketConnection = class {
       state: "CLOSED"
     });
   };
+  startHeartbeat() {
+    this.stopHeartbeat();
+    this.armSilentTimeout();
+    const intervalMs = this.options.heartbeatIntervalMs ?? 15e3;
+    if (intervalMs <= 0) return;
+    this.heartbeatIntervalHandle = setInterval(() => {
+      if (this.closedForever || this.ws.state !== "OPEN") return;
+      this.send({
+        type: "ping",
+        id: `heartbeat-${Date.now()}-${++this.heartbeatSequence}`,
+        clientSentAt: Date.now()
+      });
+    }, intervalMs);
+  }
+  armSilentTimeout() {
+    if (this.silentTimeoutHandle !== void 0) {
+      clearTimeout(this.silentTimeoutHandle);
+      this.silentTimeoutHandle = void 0;
+    }
+    const timeoutMs = this.options.silentTimeoutMs ?? 45e3;
+    if (timeoutMs <= 0 || this.closedForever || this.ws.state !== "OPEN")
+      return;
+    this.silentTimeoutHandle = setTimeout(() => {
+      this.silentTimeoutHandle = void 0;
+      if (this.closedForever || this.ws.state !== "OPEN") return;
+      this.stopSimulationClockPulses();
+      this.stopHeartbeat();
+      this.ws.reconnect();
+    }, timeoutMs);
+  }
+  stopHeartbeat() {
+    if (this.heartbeatIntervalHandle !== void 0) {
+      clearInterval(this.heartbeatIntervalHandle);
+      this.heartbeatIntervalHandle = void 0;
+    }
+    if (this.silentTimeoutHandle !== void 0) {
+      clearTimeout(this.silentTimeoutHandle);
+      this.silentTimeoutHandle = void 0;
+    }
+    this.cancelSimulationFrameFlush();
+    this.pendingSimulationFrames.clear();
+    this.pendingFrameReceipts.clear();
+  }
+  applySimulationClockConfig(config) {
+    this.stopSimulationClockPulses();
+    if (config.enabled !== true || !Number.isFinite(config.intervalMs) || config.intervalMs <= 0 || this.closedForever || this.ws.state !== "OPEN") {
+      return;
+    }
+    const intervalMs = Math.max(1, Math.floor(config.intervalMs));
+    if (config.pulsePath !== void 0) {
+      this.openSimulationClockPulseSocket(config.pulsePath);
+    }
+    this.simulationClockPulseIntervalHandle = setInterval(() => {
+      if (this.closedForever || this.ws.state !== "OPEN") return;
+      const pulse = JSON.stringify({ type: "simulationClockPulse" });
+      if (this.simulationClockPulseSocket?.state === "OPEN") {
+        this.simulationClockPulseSocket.send(pulse);
+        return;
+      }
+      if (this.simulationClockPulseSocket && !this.simulationClockDirectFailed) {
+        return;
+      }
+      this.sendTransportMessage({ type: "simulationClockPulse" });
+    }, intervalMs);
+  }
+  openSimulationClockPulseSocket(pulsePath) {
+    if (!pulsePath.startsWith("/") || pulsePath.includes("?") || pulsePath.includes("#")) {
+      this.simulationClockDirectFailed = true;
+      return;
+    }
+    const pulseUrl = new URL(this.url);
+    pulseUrl.pathname = pulsePath;
+    pulseUrl.hash = "";
+    const socket = new import_state_manager7.ReconnectingWebSocket({
+      onopen: () => {
+        if (this.simulationClockPulseSocket !== socket) return;
+        this.simulationClockDirectFailed = false;
+      },
+      onclose: () => {
+        if (this.simulationClockPulseSocket !== socket) return;
+        this.simulationClockDirectFailed = true;
+      },
+      onerror: () => {
+        if (this.simulationClockPulseSocket !== socket) return;
+        this.simulationClockDirectFailed = true;
+      }
+    });
+    this.simulationClockPulseSocket = socket;
+    this.simulationClockDirectFailed = false;
+    try {
+      socket.connect(pulseUrl.toString());
+    } catch {
+      this.simulationClockPulseSocket = void 0;
+      this.simulationClockDirectFailed = true;
+      socket.shutdown();
+    }
+  }
+  stopSimulationClockPulses() {
+    if (this.simulationClockPulseIntervalHandle !== void 0) {
+      clearInterval(this.simulationClockPulseIntervalHandle);
+      this.simulationClockPulseIntervalHandle = void 0;
+    }
+    const socket = this.simulationClockPulseSocket;
+    this.simulationClockPulseSocket = void 0;
+    this.simulationClockDirectFailed = false;
+    socket?.shutdown();
+  }
+  getSimulationFrameDiagnostics() {
+    return {
+      pending: this.pendingSimulationFrames.size,
+      dropped: this.droppedSimulationFrames,
+      pendingReceipts: this.pendingFrameReceipts.size,
+      queuedRealtimeInputs: this.queuedRealtimeInputs.length,
+      replayRealtimeInputs: this.unconfirmedRealtimeBatches.reduce(
+        (count, batch) => count + batch.messages.length,
+        0
+      ),
+      unconfirmedRealtimeBatches: this.unconfirmedRealtimeBatches.length,
+      realtimeBatchesSent: this.realtimeBatchesSent,
+      realtimeInputsSent: this.realtimeInputsSent,
+      realtimeWatchdogArmed: this.realtimeInputWatchdogHandle !== void 0,
+      simulationClockPulsesActive: this.simulationClockPulseIntervalHandle !== void 0
+    };
+  }
   send(message) {
     if (this.closedForever) return;
+    if (message.type === "enqueueInput" && message.transport === "realtime" && this.getRealtimeInputSequence(message)) {
+      this.queuedRealtimeInputs.push(message);
+      this.armRealtimeInputWatchdog();
+      return;
+    }
+    this.sendTransportMessage(message);
+  }
+  sendTransportMessage(message) {
     if (this.options.debug) {
       console.info("ws sending message", message);
     }
@@ -8657,9 +8964,124 @@ var WebSocketConnection = class {
     });
     this.ws.send(JSON.stringify(message));
   }
+  getRealtimeInputSequence(message) {
+    const payload = message.payload;
+    if (!payload || typeof payload !== "object") return;
+    const streamId = Reflect.get(payload, "streamId");
+    const sequence = Reflect.get(payload, "sequence");
+    if (typeof streamId !== "string" || streamId.length === 0 || !Number.isInteger(sequence) || sequence < 0) {
+      return;
+    }
+    return {
+      key: `${message.queue}\0${streamId}`,
+      sequence
+    };
+  }
+  getContiguousRealtimeInputCount() {
+    const sequences = new Map(this.lastSentRealtimeSequences);
+    let count = 0;
+    for (const message of this.queuedRealtimeInputs) {
+      if (count >= import_state_manager7.MAX_CLIENT_MESSAGE_BATCH_SIZE) break;
+      const input = this.getRealtimeInputSequence(message);
+      if (!input) break;
+      const previous = sequences.get(input.key);
+      if (input.sequence !== (previous === void 0 ? 0 : previous + 1)) {
+        break;
+      }
+      sequences.set(input.key, input.sequence);
+      count += 1;
+    }
+    return { count, sequences };
+  }
+  flushRealtimeBatch(receipt) {
+    if (this.closedForever || this.ws.state !== "OPEN") return false;
+    const canSendInputBatch = this.unconfirmedRealtimeBatches.length < import_state_manager7.MAX_REALTIME_INPUT_BATCHES_IN_FLIGHT;
+    const contiguous = this.getContiguousRealtimeInputCount();
+    const messages = canSendInputBatch ? this.queuedRealtimeInputs.slice(0, contiguous.count) : [];
+    if (!receipt && messages.length === 0) return false;
+    const batch = {
+      type: "clientMessageBatch",
+      ...receipt && { receipt },
+      ...messages.length > 0 && {
+        inputBatch: {
+          sessionId: this.realtimeInputSessionId,
+          sequence: this.nextRealtimeInputBatchSequence
+        }
+      },
+      messages
+    };
+    this.sendTransportMessage(batch);
+    if (messages.length > 0) {
+      this.queuedRealtimeInputs.splice(0, messages.length);
+      this.lastSentRealtimeSequences = contiguous.sequences;
+      this.unconfirmedRealtimeBatches.push(batch);
+      this.nextRealtimeInputBatchSequence += 1;
+      this.realtimeInputsSent += messages.length;
+    }
+    this.realtimeBatchesSent += 1;
+    return true;
+  }
+  flushPendingFrameReceipts() {
+    for (const [scriptId, receipt] of Array.from(
+      this.pendingFrameReceipts.entries()
+    )) {
+      if (!this.flushRealtimeBatch(receipt)) continue;
+      if (this.pendingFrameReceipts.get(scriptId) === receipt) {
+        this.pendingFrameReceipts.delete(scriptId);
+      }
+    }
+    if (this.queuedRealtimeInputs.length > 0) {
+      this.armRealtimeInputWatchdog();
+    } else {
+      this.stopRealtimeInputWatchdog();
+    }
+  }
+  armRealtimeInputWatchdog() {
+    if (this.realtimeInputWatchdogHandle !== void 0 || this.queuedRealtimeInputs.length === 0 || this.closedForever || this.ws.state !== "OPEN") {
+      return;
+    }
+    const configuredDelay = this.options.realtimeInputWatchdogMs;
+    const delay = configuredDelay !== void 0 && Number.isFinite(configuredDelay) ? Math.max(1, Math.floor(configuredDelay)) : 200;
+    this.realtimeInputWatchdogHandle = setTimeout(() => {
+      this.realtimeInputWatchdogHandle = void 0;
+      this.flushRealtimeBatch();
+      if (this.queuedRealtimeInputs.length > 0) {
+        this.armRealtimeInputWatchdog();
+      }
+    }, delay);
+  }
+  stopRealtimeInputWatchdog() {
+    if (this.realtimeInputWatchdogHandle === void 0) return;
+    clearTimeout(this.realtimeInputWatchdogHandle);
+    this.realtimeInputWatchdogHandle = void 0;
+  }
+  replayUnconfirmedRealtimeBatches() {
+    if (this.closedForever || this.ws.state !== "OPEN") return;
+    for (const batch of this.unconfirmedRealtimeBatches) {
+      this.sendTransportMessage(batch);
+    }
+  }
+  confirmRealtimeInputBatches(sessionId, sequence) {
+    if (sessionId !== this.realtimeInputSessionId || !Number.isInteger(sequence) || sequence < 0) {
+      return;
+    }
+    this.unconfirmedRealtimeBatches = this.unconfirmedRealtimeBatches.filter(
+      (batch) => !batch.inputBatch || batch.inputBatch.sequence > sequence
+    );
+    if (this.queuedRealtimeInputs.length > 0) {
+      this.armRealtimeInputWatchdog();
+    }
+  }
   close() {
     if (this.closedForever) return;
     this.closedForever = true;
+    this.stopHeartbeat();
+    this.stopSimulationClockPulses();
+    this.stopRealtimeInputWatchdog();
+    this.queuedRealtimeInputs = [];
+    this.unconfirmedRealtimeBatches = [];
+    this.lastSentRealtimeSequences.clear();
+    this.deliveredSimulationFrameCursors.clear();
     this.ws.shutdown();
     this.ws.listeners.forEach((listener) => {
       this.ws.removeListener(listener);
@@ -8696,6 +9118,7 @@ var WebSocketConnection = class {
   importAll,
   initializeNoyaSingleton,
   parseAppDataParameter,
+  parseInspectorParameter,
   replaceDeep,
   resourceToCreateParameters,
   resourceToMediaItem,