@usions/sdk 2.1.5 → 2.10.0

package/src/browser.js

@@ -13,6 +13,58 @@ var Usion = (function () {
     return ++_requestId;
   }
 
+  // Trusted origin of the host shell that embedded us (web iframe only).
+  // Resolved lazily from the real embedder, never from message contents.
+  let _parentOrigin = null;
+
+  function _resolveParentOrigin() {
+    try {
+      if (window.location.ancestorOrigins && window.location.ancestorOrigins.length) {
+        return window.location.ancestorOrigins[0];
+      }
+    } catch (e) { /* not supported */ }
+    try {
+      if (typeof document !== 'undefined' && document.referrer) {
+        return new URL(document.referrer).origin;
+      }
+    } catch (e) { /* malformed referrer */ }
+    return null;
+  }
+
+  /**
+   * Decide whether an incoming postMessage may be trusted.
+   *
+   * The host shell is the only legitimate sender. A sibling iframe or any other
+   * script on the page must NOT be able to forge messages (e.g. a fake
+   * PAYMENT_SUCCESS that unlocks paid value for free).
+   *
+   * - React Native WebView: messages are delivered in-process and carry no
+   *   usable origin/source, so they are trusted.
+   * - Web iframe: the only window that equals `window.parent` is the real
+   *   embedder. `event.source` is set by the browser and cannot be spoofed, so
+   *   `event.source === window.parent` rejects siblings and self-posts. We then
+   *   cross-check `event.origin` against the embedder's origin as defense-in-depth.
+   * - Not embedded (standalone / tests): nothing to protect against; allowed.
+   *
+   * @param {MessageEvent} event
+   * @returns {boolean}
+   */
+  function isTrustedMessageSource(event) {
+    if (typeof window === 'undefined') return true;
+    if (window.ReactNativeWebView) return true;
+    if (window.parent === window) return true;
+
+    if (event && event.source && event.source !== window.parent) return false;
+
+    if (_parentOrigin === null) {
+      _parentOrigin = _resolveParentOrigin();
+    }
+    if (_parentOrigin && event && event.origin && event.origin !== _parentOrigin) {
+      return false;
+    }
+    return true;
+  }
+
   /**
    * Core Usion object with init, _post, _request
    */
@@ -49,6 +101,9 @@ var Usion = (function () {
 
       // Setup global message handler
       window.addEventListener('message', function(event) {
+        // Reject messages from anything other than the host shell.
+        if (!isTrustedMessageSource(event)) return;
+
         let data;
         try {
           data = typeof event.data === 'string' ? JSON.parse(event.data) : event.data;
@@ -129,6 +184,12 @@ var Usion = (function () {
         if (data.type === 'BOT_MESSAGE' && self.bot && self.bot._messageHandler) {
           self.bot._messageHandler(data.message);
         }
+
+        // Handle backend server-push events relayed by the host (embedded mode).
+        if (data.type === 'BACKEND_EVENT' && data.event && self._backendHandlers) {
+          const h = self._backendHandlers[data.event];
+          if (h) h(data.data);
+        }
       });
 
       // Signal ready to parent
@@ -394,6 +455,10 @@ var Usion = (function () {
 
           // Listen for response
           function handler(event) {
+            // Only honor payment results from the trusted host shell — a forged
+            // PAYMENT_SUCCESS must never resolve this promise.
+            if (!isTrustedMessageSource(event)) return;
+
             let response;
             try {
               response = typeof event.data === 'string' ? JSON.parse(event.data) : event.data;
@@ -780,6 +845,7 @@ var Usion = (function () {
    * Usion SDK Misc — submit, error, exit, share, log, on, requestPayment (legacy)
    */
 
+
   const miscMethods = {
     /**
      * Request payment from user (legacy method)
@@ -886,6 +952,8 @@ var Usion = (function () {
      */
     on: function(type, callback) {
       window.addEventListener('message', function(event) {
+        if (!isTrustedMessageSource(event)) return;
+
         let data;
         try {
           data = typeof event.data === 'string' ? JSON.parse(event.data) : event.data;
@@ -975,6 +1043,9 @@ var Usion = (function () {
 
       self._connecting = true;
       self.directMode = true;
+      self._autoReconnect = config.autoReconnect !== undefined
+        ? config.autoReconnect
+        : !(Usion.config && Usion.config.autoReconnect === false);
       self._connectPromise = self._fetchDirectAccess(config)
         .then(function(access) {
           self.directConfig = access;
@@ -1103,6 +1174,10 @@ var Usion = (function () {
           if (self._eventHandlers.disconnect) {
             self._eventHandlers.disconnect(evt && evt.reason ? evt.reason : 'direct socket closed');
           }
+          // Seamless resume: if the drop wasn't an intentional disconnect()
+          // (which clears directMode), transparently re-establish + re-join +
+          // resync from the last sequence.
+          if (self.directMode && self._autoReconnect !== false) self._scheduleDirectReconnect();
         };
 
         ws.onmessage = function(evt) {
@@ -1111,6 +1186,39 @@ var Usion = (function () {
       });
     };
 
+    /**
+     * Reconnect a dropped direct-mode socket with capped exponential backoff,
+     * then re-join the room and request a resync (Dota-style "fetch latest
+     * snapshot = instant rejoin"). Keeps retrying while still in directMode.
+     * @private
+     */
+    game._scheduleDirectReconnect = function() {
+      var self = this;
+      if (self._reconnecting) return;
+      self._reconnecting = true;
+      var attempt = self._reconnectAttempt || 0;
+      var go = function() {
+        if (!self.directMode) { self._reconnecting = false; return; } // disconnected meanwhile
+        attempt += 1;
+        self._reconnectAttempt = attempt;
+        self._fetchDirectAccess({})
+          .then(function(access) { self.directConfig = access; return self._initDirectSocket(access); })
+          .then(function() {
+            self.connected = true;
+            self._reconnecting = false;
+            self._reconnectAttempt = 0;
+            if (self._eventHandlers.reconnect) self._eventHandlers.reconnect(attempt);
+            if (self.roomId) self.requestSync(self._lastSequence || 0); // resync / resume
+          })
+          .catch(function() {
+            if (!self.directMode) { self._reconnecting = false; return; }
+            var delay = Math.min(1000 * Math.pow(2, attempt - 1), 15000);
+            setTimeout(go, delay);
+          });
+      };
+      setTimeout(go, 500);
+    };
+
     game._sendDirect = function(type, payload) {
       if (!this.directSocket || this.directSocket.readyState !== WebSocket.OPEN) return;
       this._directSeq = this._directSeq + 1;
@@ -1154,6 +1262,11 @@ var Usion = (function () {
         return;
       }
       if (data.type === 'pong') {
+        // Resolve a pending game.ping() RTT probe, if any.
+        if (this._pongWaiters && this._pongWaiters.length) {
+          const waiter = this._pongWaiters.shift();
+          if (waiter) waiter();
+        }
         if (this._eventHandlers.sync) this._eventHandlers.sync(payload);
         return;
       }
@@ -1209,6 +1322,10 @@ var Usion = (function () {
           reconnectionDelayMax: 10000
         });
 
+        // Route allow-listed backend server events (lobby, etc.) to the unified
+        // backend channel — robust to listener registration order.
+        if (Usion._bindBackendSocket) Usion._bindBackendSocket(self.socket);
+
         self.socket.on('connect', function() {
           self.connected = true;
           self._connecting = false;
@@ -1367,6 +1484,7 @@ var Usion = (function () {
    * Usion SDK Game Proxy — postMessage relay through parent app
    */
 
+
   /**
    * Add proxy connection methods to game module
    * @param {object} game - The game module object
@@ -1423,6 +1541,8 @@ var Usion = (function () {
       self._proxyListenerSetup = true;
 
       window.addEventListener('message', function(event) {
+        if (!isTrustedMessageSource(event)) return;
+
         var data;
         try {
           data = typeof event.data === 'string' ? JSON.parse(event.data) : event.data;
@@ -1636,7 +1756,10 @@ var Usion = (function () {
       const self = this;
 
       if (self.directMode) {
-        self._sendDirect(actionType || 'action', actionData || {});
+        self._sendDirect('action', {
+          action_type: actionType || 'default',
+          action_data: actionData || {}
+        });
         return Promise.resolve({ success: true });
       }
 
@@ -1836,6 +1959,109 @@ var Usion = (function () {
       }
     };
 
+    // ───────────────────────────────────────────────────────────
+    // Cross-reload state persistence
+    // ───────────────────────────────────────────────────────────
+    // When a mini-app's iframe is unmounted and later re-mounted (e.g. the
+    // user navigates back to the chat and re-opens the game from the same
+    // room), the entire JS context is destroyed. Server-side room state is
+    // preserved, but anything the game holds in memory — board state, phase,
+    // whose turn it is, placement choices — is lost. The platform sync
+    // mechanism only replays raw actions; reconstructing client-visible
+    // state from a zero baseline is fragile or impossible.
+    //
+    // These helpers give every game a uniform way to snapshot whatever it
+    // needs to localStorage. Keys are scoped to (player_id, room_id) so a
+    // single browser can hold independent state for different rooms or
+    // accounts without collision, and "play a different match in the same
+    // room" naturally collides — which is the correct outcome.
+
+    const STATE_KEY_PREFIX = '_usion_game_state:';
+
+    function _stateKey(self) {
+      const rid = self.roomId || (Usion.config && Usion.config.roomId);
+      const pid = self.playerId
+        || (Usion.user && typeof Usion.user.getId === 'function' && Usion.user.getId())
+        || (Usion.config && Usion.config.userId);
+      if (!rid || !pid) return null;
+      return STATE_KEY_PREFIX + pid + ':' + rid;
+    }
+
+    /**
+     * Persist arbitrary JSON-serializable game state across iframe reloads.
+     * The mini-app decides the schema; the SDK only stores/retrieves.
+     * @param {*} state - Any JSON-serializable value
+     * @returns {boolean} true if saved, false if not (no room/player yet, or storage error)
+     */
+    game.saveState = function(state) {
+      const self = this;
+      const key = _stateKey(self);
+      if (!key) return false;
+      try {
+        localStorage.setItem(key, JSON.stringify({ state: state, savedAt: Date.now() }));
+        return true;
+      } catch (e) {
+        // Quota exceeded, private-mode rejection, etc. — non-fatal.
+        return false;
+      }
+    };
+
+    /**
+     * Retrieve previously-saved state for the current (player, room).
+     * @returns {*} The saved state value, or null if none / unreadable.
+     */
+    game.loadState = function() {
+      const self = this;
+      const key = _stateKey(self);
+      if (!key) return null;
+      try {
+        const raw = localStorage.getItem(key);
+        if (!raw) return null;
+        const parsed = JSON.parse(raw);
+        return parsed && parsed.state !== undefined ? parsed.state : null;
+      } catch (e) {
+        return null;
+      }
+    };
+
+    /**
+     * Drop any persisted state for the current (player, room).
+     * Call this when the game ends or starts fresh, so the next iframe
+     * mount in the same room doesn't pick up stale data.
+     */
+    game.clearState = function() {
+      const self = this;
+      const key = _stateKey(self);
+      if (!key) return;
+      try { localStorage.removeItem(key); } catch (e) { /* non-fatal */ }
+    };
+
+    /**
+     * Forward a debug snapshot to the parent platform. The platform renders
+     * it in a top-right overlay when the iframe host is opened with
+     * `?debug=1`. The payload schema is up to the game — anything JSON-
+     * serializable. No-op when not running inside an iframe.
+     *
+     * Games should call this at every meaningful state transition (turn
+     * change, action sent, action received, sync, phase change, etc.) so
+     * the overlay reflects live state.
+     *
+     * @param {object} payload - Arbitrary JSON-serializable debug data
+     */
+    game.debug = function(payload) {
+      try {
+        // Must work in both web iframes (window.parent !== window) and
+        // React Native WebView (window.parent === window, but a host bridge
+        // exists at window.ReactNativeWebView). Usion._post handles routing
+        // for both; this guard just avoids no-op work in standalone pages.
+        var inFrame = window.parent && window.parent !== window;
+        var inRNWebView = !!window.ReactNativeWebView;
+        if (inFrame || inRNWebView) {
+          Usion._post({ type: 'GAME_DEBUG', payload: payload || {} });
+        }
+      } catch (e) { /* non-fatal */ }
+    };
+
     /**
      * Get connection status
      * @returns {boolean}
@@ -1849,152 +2075,2452 @@ var Usion = (function () {
   }
 
   /**
-   * Usion SDK Game Core — game module base, connect routing, event registrations
+   * Usion SDK Netcode — Snapshot interpolation.
+   *
+   * Render every entity slightly in the past and interpolate between the two
+   * snapshots straddling "renderTime", so motion stays smooth and late /
+   * duplicate / out-of-order / dropped packets are absorbed for free. This is
+   * the single biggest perceived-lag fix for real-time games.
+   *
+   * Practices adopted (Valve Source "Interpolation" + geckos.io):
+   *  - Interpolation delay (buffer) sized in server-frames, with an **adaptive**
+   *    mode that grows the buffer with measured network jitter (cl_interp_ratio).
+   *  - **Capped extrapolation** when the buffer underruns (packet loss): project
+   *    forward from the last known velocity, bounded (Source caps at 0.25s) so
+   *    prediction error stays small.
+   *  - Optional **server-time domain**: if snapshots carry a server `time`, render
+   *    against an estimated server clock (robust to bursty arrival). Default stays
+   *    the client arrival-time domain — zero clock sync required.
+   *
+   * Key-spec syntax: 'x y angle(deg) r(rad)'.
    */
 
+  function shortestAngle(a, b, twoPi) {
+    let d = (b - a) % twoPi;
+    const half = twoPi / 2;
+    if (d > half) d -= twoPi;
+    if (d < -half) d += twoPi;
+    return d;
+  }
 
-  /**
-   * Create the game module with all sub-modules applied
-   * @param {object} Usion - Reference to the main Usion object
-   */
-  function createGameModule(Usion) {
-    const game = {
-      socket: null,
-      directSocket: null,
-      roomId: null,
-      playerId: null,
-      connected: false,
-      directMode: false,
-      directConfig: null,
-      _directSeq: 0,
-      _eventHandlers: {},
-      _lastSequence: 0,
-      _connecting: false,
-      _connectPromise: null,
-      _joined: false,
-      _joinPromise: null,
-      _useProxy: false,
-      _proxyListenerSetup: false,
-      _heartbeatInterval: null,
+  function parseKeys(spec) {
+    return String(spec || '')
+      .trim()
+      .split(/\s+/)
+      .filter(Boolean)
+      .map((tok) => {
+        const m = tok.match(/^(.+?)\((deg|rad)\)$/);
+        return m ? { key: m[1], type: m[2] } : { key: tok, type: 'linear' };
+      });
+  }
 
-      /**
-       * Connect to the game socket server
-       * @param {string} socketUrl - Socket.IO server URL (optional, uses config)
-       * @param {string} token - JWT auth token (optional, uses user.getToken())
-       * @returns {Promise} Resolves when connected
-       */
-      connect: function(socketUrl, token) {
-        const self = this;
-        var connectionMode = (Usion.config && Usion.config.connectionMode) || 'platform';
-        if (connectionMode === 'direct') {
-          return self.connectDirect();
-        }
+  function lerpField(a, b, t, type) {
+    if (type === 'deg') return a + shortestAngle(a, b, 360) * t;
+    if (type === 'rad') return a + shortestAngle(a, b, Math.PI * 2) * t;
+    return a + (b - a) * t;
+  }
 
-        // If already connected (direct or proxy), return immediately
-        if (self._useProxy && self.connected) {
-          return Promise.resolve();
-        }
-        if (self.socket && self.connected) {
-          return Promise.resolve();
-        }
+  /** Time-ordered ring buffer of snapshots. Newest last. */
+  class Vault {
+    constructor(maxSize = 120) {
+      this._items = [];
+      this._maxSize = maxSize;
+    }
+    add(snapshot) {
+      this._items.push(snapshot);
+      if (this._items.length > this._maxSize) this._items.shift();
+    }
+    get size() { return this._items.length; }
+    setMaxSize(n) { this._maxSize = Math.max(2, n | 0); }
+    latest() { return this._items.length ? this._items[this._items.length - 1] : null; }
+    prevLatest() { return this._items.length >= 2 ? this._items[this._items.length - 2] : null; }
+    clear() { this._items = []; }
+
+    /** [older, newer] snapshots straddling `time`, clamping at the ends. */
+    straddle(time) {
+      const items = this._items;
+      if (items.length === 0) return [null, null];
+      if (items.length === 1) return [items[0], items[0]];
+      if (time <= items[0].time) return [items[0], items[0]];
+      const last = items[items.length - 1];
+      if (time >= last.time) return [last, last];
+      for (let i = items.length - 1; i > 0; i--) {
+        if (items[i - 1].time <= time && time <= items[i].time) return [items[i - 1], items[i]];
+      }
+      return [last, last];
+    }
+  }
 
-        // If currently connecting, return the existing promise
-        if (self._connecting && self._connectPromise) {
-          return self._connectPromise;
-        }
+  function asEntityArray(state, group) {
+    if (group) return Array.isArray(state[group]) ? state[group] : [];
+    return Array.isArray(state) ? state : [];
+  }
 
-        // When running inside an iframe or WebView, use parent as socket proxy
-        // (checked BEFORE token validation — iframe games don't need a token)
-        var isInFrame = !!window.__USION_PROXY__
-                     || window.parent !== window
-                     || !!window.ReactNativeWebView
-                     || !!Usion._isEmbedded;
+  class SnapshotInterpolation {
+    /**
+     * @param {object} [opts]
+     * @param {number} [opts.serverFps=20]      Expected snapshot rate (sets default buffer).
+     * @param {number} [opts.bufferMs]          Fixed interpolation delay (default ≈ 3 frames).
+     * @param {boolean} [opts.adaptive=false]   Grow the buffer with measured jitter.
+     * @param {number} [opts.minBufferMs]       Lower clamp for adaptive buffer.
+     * @param {number} [opts.maxBufferMs]       Upper clamp for adaptive buffer.
+     * @param {number} [opts.extrapolationMs=0] Max forward extrapolation on underrun (0 = off).
+     * @param {boolean} [opts.serverTime=false] Use snapshot.time (server clock) domain.
+     * @param {number} [opts.maxSize=120]
+     * @param {function} [opts.now]
+     */
+    constructor(opts = {}) {
+      const serverFps = opts.serverFps || 20;
+      this._frameMs = 1000 / serverFps;
+      this.vault = new Vault(opts.maxSize || 120);
+      this._fixedBuffer = opts.bufferMs != null ? opts.bufferMs : Math.ceil(this._frameMs * 3);
+      this._bufferMs = this._fixedBuffer;
+      this._adaptive = !!opts.adaptive;
+      this._minBuffer = opts.minBufferMs != null ? opts.minBufferMs : Math.ceil(this._frameMs * 2);
+      this._maxBuffer = opts.maxBufferMs != null ? opts.maxBufferMs : Math.ceil(this._frameMs * 8);
+      this._extrapolationMs = opts.extrapolationMs || 0;
+      this._useServerTime = !!opts.serverTime;
+      this._now = opts.now || (() => Date.now());
+
+      // adaptive/jitter + server-clock estimation state
+      this._lastArrival = null;
+      this._avgInterval = this._frameMs;
+      this._jitter = 0;
+      this._offset = null; // EWMA(arrival - serverTime)
+    }
 
-        if (isInFrame) {
-          Usion.log('Running in iframe \u2013 using parent app as socket proxy');
-          return self._connectViaProxy();
+    getBufferMs() { return this._bufferMs; }
+    setBufferMs(ms) { this._fixedBuffer = Math.max(0, ms | 0); this._bufferMs = this._fixedBuffer; }
+    getJitter() { return this._jitter; }
+
+    /**
+     * Add a received snapshot. `state` is an entity array (each needs a stable
+     * `id`) or a map of named groups → entity arrays. Pass `{ state, time }` to
+     * supply a server timestamp for the server-time domain.
+     */
+    add(snapshot) {
+      if (!snapshot) return;
+      const arrival = this._now();
+      const state = snapshot.state !== undefined ? snapshot.state : snapshot;
+      const serverTime = snapshot.time;
+
+      // Jitter / interval estimate (EWMA), used by the adaptive buffer.
+      if (this._lastArrival != null) {
+        const interval = arrival - this._lastArrival;
+        this._avgInterval += 0.1 * (interval - this._avgInterval);
+        this._jitter += 0.1 * (Math.abs(interval - this._avgInterval) - this._jitter);
+        if (this._adaptive) {
+          const target = this._avgInterval + 2 * this._jitter;
+          this._bufferMs = Math.max(this._minBuffer, Math.min(this._maxBuffer, target));
         }
+      }
+      this._lastArrival = arrival;
 
-        // Use config values as defaults (only for direct socket connections)
-        socketUrl = socketUrl || Usion.config.socketUrl;
-        token = token || Usion.user.getToken();
+      // Server-clock offset estimate.
+      if (this._useServerTime && typeof serverTime === 'number') {
+        const o = arrival - serverTime;
+        this._offset = this._offset == null ? o : this._offset + 0.05 * (o - this._offset);
+      }
 
-        if (!socketUrl) {
-          return Promise.reject(new Error('No socket URL provided'));
-        }
-        if (!token) {
-          return Promise.reject(new Error('No auth token available'));
+      // Stamp the time used for the interpolation domain.
+      const time = (this._useServerTime && typeof serverTime === 'number') ? serverTime : arrival;
+      this.vault.add({ time, state });
+    }
+
+    _renderTime() {
+      if (this._useServerTime && this._offset != null) return (this._now() - this._offset) - this._bufferMs;
+      return this._now() - this._bufferMs;
+    }
+
+    /**
+     * Interpolated entities for the current render instant.
+     * @param {string} keys   e.g. 'x y' or 'x y angle(deg)'
+     * @param {string} [group]
+     * @returns {Array|null}
+     */
+    calc(keys, group) {
+      const renderTime = this._renderTime();
+      const latest = this.vault.latest();
+      if (!latest) return null;
+      const specs = parseKeys(keys);
+
+      // Buffer underrun: render time is ahead of the newest snapshot.
+      if (renderTime > latest.time) {
+        if (this._extrapolationMs > 0) return this._extrapolate(renderTime, specs, group);
+        return asEntityArray(latest.state, group).map((e) => Object.assign({}, e));
+      }
+
+      const [older, newer] = this.vault.straddle(renderTime);
+      if (!older || !newer) return null;
+
+      let t = 0;
+      if (newer.time !== older.time) {
+        t = (renderTime - older.time) / (newer.time - older.time);
+        t = t < 0 ? 0 : t > 1 ? 1 : t;
+      }
+      return this._blend(asEntityArray(older.state, group), asEntityArray(newer.state, group), t, specs);
+    }
+
+    _blend(oldEntities, newEntities, t, specs) {
+      const oldById = {};
+      for (let i = 0; i < oldEntities.length; i++) oldById[oldEntities[i].id] = oldEntities[i];
+      return newEntities.map((nentity) => {
+        const oentity = oldById[nentity.id];
+        const out = Object.assign({}, nentity);
+        if (oentity) {
+          for (let i = 0; i < specs.length; i++) {
+            const { key, type } = specs[i];
+            const a = oentity[key];
+            const b = nentity[key];
+            if (typeof a === 'number' && typeof b === 'number') out[key] = lerpField(a, b, t, type);
+          }
         }
+        return out;
+      });
+    }
 
-        self._connecting = true;
-        self._connectPromise = new Promise(function(resolve, reject) {
-          // Check if socket.io-client is available
-          if (typeof io === 'undefined') {
-            // Load socket.io client
-            var script = document.createElement('script');
-            script.src = '/socket.io.min.js';
-            script.onload = function() {
-              self._initSocket(socketUrl, token, resolve, reject);
-            };
-            script.onerror = function() {
-              // Local file not available, try CDN as fallback
-              var cdnScript = document.createElement('script');
-              cdnScript.src = 'https://cdn.socket.io/4.7.2/socket.io.min.js';
-              cdnScript.onload = function() {
-                self._initSocket(socketUrl, token, resolve, reject);
-              };
-              cdnScript.onerror = function() {
-                self._connecting = false;
-                reject(new Error('Failed to load Socket.IO client'));
-              };
-              document.head.appendChild(cdnScript);
-            };
-            document.head.appendChild(script);
-          } else {
-            self._initSocket(socketUrl, token, resolve, reject);
+    _extrapolate(renderTime, specs, group) {
+      const newer = this.vault.latest();
+      const older = this.vault.prevLatest();
+      const newEntities = asEntityArray(newer.state, group);
+      if (!older || newer.time <= older.time) return newEntities.map((e) => Object.assign({}, e));
+
+      const dt = Math.min(renderTime - newer.time, this._extrapolationMs); // cap
+      const span = newer.time - older.time;
+      const oldById = {};
+      const oldEntities = asEntityArray(older.state, group);
+      for (let i = 0; i < oldEntities.length; i++) oldById[oldEntities[i].id] = oldEntities[i];
+
+      return newEntities.map((nentity) => {
+        const oentity = oldById[nentity.id];
+        const out = Object.assign({}, nentity);
+        if (oentity) {
+          for (let i = 0; i < specs.length; i++) {
+            const { key } = specs[i]; // linear extrapolation (angles handled as linear here)
+            const a = oentity[key];
+            const b = nentity[key];
+            if (typeof a === 'number' && typeof b === 'number') {
+              const vel = (b - a) / span;
+              out[key] = b + vel * dt;
+            }
           }
-        });
+        }
+        return out;
+      });
+    }
+  }
 
-        return self._connectPromise;
-      },
+  /**
+   * Usion SDK Netcode — Client-side prediction + server reconciliation.
+   *
+   * Apply local input instantly (tagged with a sequence number); when the
+   * authoritative state arrives carrying the last input the server processed,
+   * snap to it and replay every still-unacknowledged input on top. The local
+   * player sees zero input delay while staying consistent with the server.
+   *
+   * Error smoothing (Overwatch / Gabriel Gambetta): hard-snapping the render
+   * position on every correction looks jittery. Instead we keep the visible
+   * position as `corrected + error`, where `error` is the gap a correction
+   * introduced, and decay that error to zero over a few frames — so corrections
+   * are smooth and, in the common case, invisible. Enable via `opts.smooth`.
+   *
+   * The game supplies a pure `apply(state, input) -> newState` (must not mutate).
+   */
+  function parseSmoothKeys(smooth) {
+    if (!smooth) return null;
+    let keys = smooth.keys != null ? smooth.keys : smooth;
+    if (typeof keys === 'string') keys = keys.trim().split(/\s+/).filter(Boolean);
+    return Array.isArray(keys) && keys.length ? keys : null;
+  }
 
-      // Event handler registrations
-      onJoined: function(callback) { this._eventHandlers.joined = callback; },
-      onPlayerJoined: function(callback) { this._eventHandlers.playerJoined = callback; },
-      onPlayerLeft: function(callback) { this._eventHandlers.playerLeft = callback; },
-      onStateUpdate: function(callback) { this._eventHandlers.stateUpdate = callback; },
-      onSync: function(callback) { this._eventHandlers.sync = callback; },
-      onAction: function(callback) { this._eventHandlers.action = callback; },
-      onRealtime: function(callback) { this._eventHandlers.realtime = callback; },
-      onGameFinished: function(callback) { this._eventHandlers.finished = callback; },
-      onGameRestarted: function(callback) { this._eventHandlers.restarted = callback; },
-      onError: function(callback) { this._eventHandlers.error = callback; },
-      onRematchRequest: function(callback) { this._eventHandlers.rematchRequest = callback; },
-      onDisconnect: function(callback) { this._eventHandlers.disconnect = callback; },
-      onReconnect: function(callback) { this._eventHandlers.reconnect = callback; },
-      onConnectionError: function(callback) { this._eventHandlers.connectionError = callback; },
+  class Predictor {
+    /**
+     * @param {object} opts
+     * @param {(state:any, input:any)=>any} opts.apply  Pure state transition.
+     * @param {any} [opts.initialState]
+     * @param {{keys?:string|string[], rate?:number, snapTo?:number}|string} [opts.smooth]
+     *   Error-smoothing config. `keys` are numeric fields to blend; `rate` is the
+     *   per-frame decay (0..1, default 0.2); `snapTo` is the residual below which
+     *   the error is zeroed (default 0.001).
+     */
+    constructor(opts = {}) {
+      if (typeof opts.apply !== 'function') throw new Error('Predictor requires an apply(state, input) function');
+      this._apply = opts.apply;
+      this._state = opts.initialState !== undefined ? opts.initialState : null;
+      this._seq = 0;
+      this._pending = [];
+      this._smoothKeys = parseSmoothKeys(opts.smooth);
+      this._smoothRate = (opts.smooth && opts.smooth.rate != null) ? opts.smooth.rate : 0.2;
+      this._snapTo = (opts.smooth && opts.smooth.snapTo != null) ? opts.smooth.snapTo : 0.001;
+      this._error = {};
+    }
 
-      /**
-       * Register a generic event handler
-       * @param {string} event - Event name
-       * @param {function} callback - Handler function
-       */
-      on: function(event, callback) {
-        if (this.socket) {
-          this.socket.on(event, callback);
+    get state() { return this._state; }
+    get pending() { return this._pending.slice(); }
+    get lastSeq() { return this._seq; }
+
+    /** Apply an input locally and record it. Attach the returned `seq` when sending. */
+    predict(input) {
+      this._seq += 1;
+      const seq = this._seq;
+      this._pending.push({ seq, input });
+      this._state = this._apply(this._state, input);
+      return { seq, state: this._state };
+    }
+
+    /**
+     * Reconcile against authoritative server state.
+     * @param {any} serverState   Authoritative state.
+     * @param {number} ackedSeq   Highest input sequence the server has applied.
+     * @returns {any} the corrected predicted state (authoritative + replayed inputs)
+     */
+    reconcile(serverState, ackedSeq) {
+      const before = this._state;
+      const ack = ackedSeq == null ? -1 : ackedSeq;
+      this._pending = this._pending.filter((p) => p.seq > ack);
+      let s = serverState;
+      for (let i = 0; i < this._pending.length; i++) s = this._apply(s, this._pending[i].input);
+
+      // Accumulate the correction gap into the error offset for smoothing.
+      if (this._smoothKeys && before && s) {
+        for (let i = 0; i < this._smoothKeys.length; i++) {
+          const k = this._smoothKeys[i];
+          if (typeof before[k] === 'number' && typeof s[k] === 'number') {
+            this._error[k] = (this._error[k] || 0) + (before[k] - s[k]);
+          }
         }
       }
-    };
+      this._state = s;
+      return this._state;
+    }
 
-    // Apply sub-modules
-    applyGameDirect(game, Usion);
-    applyGameSocket(game, Usion);
-    applyGameProxy(game, Usion);
-    applyGameMethods(game, Usion);
+    /**
+     * The state to render: corrected state plus the decaying error offset.
+     * Call once per rendered frame; it decays the error toward zero.
+     * @param {number} [rate] Override the per-frame decay factor.
+     * @returns {any}
+     */
+    view(rate) {
+      if (!this._smoothKeys || !this._state || typeof this._state !== 'object') return this._state;
+      const r = rate != null ? rate : this._smoothRate;
+      const out = Array.isArray(this._state) ? this._state.slice() : Object.assign({}, this._state);
+      for (let i = 0; i < this._smoothKeys.length; i++) {
+        const k = this._smoothKeys[i];
+        let e = this._error[k] || 0;
+        if (typeof out[k] === 'number' && e !== 0) out[k] = out[k] + e;
+        e *= (1 - r);
+        if (Math.abs(e) < this._snapTo) e = 0;
+        this._error[k] = e;
+      }
+      return out;
+    }
 
-    return game;
+    /** Hard reset (e.g. on rematch). */
+    reset(state) {
+      this._state = state !== undefined ? state : null;
+      this._seq = 0;
+      this._pending = [];
+      this._error = {};
+    }
   }
 
+  /**
+   * Usion SDK Netcode — Outbound send coalescing at a fixed tick rate.
+   *
+   * Games tend to emit on every input event or every animation frame (often
+   * 60+/s). Each emit is a separate Socket.IO message and, in platform mode,
+   * a separate server-side broadcast (and historically a Redis write). That
+   * floods the wire and the server far beyond what gameplay needs.
+   *
+   * The Coalescer buffers outbound messages and flushes them on a fixed tick
+   * (e.g. 20 Hz). Two modes per channel:
+   *   - queue(type, data): latest-wins — only the newest value per type is sent
+   *     each tick. Ideal for state snapshots, cursor/position updates.
+   *   - append(type, data): buffered — every value is kept and sent as a batch.
+   *     Use for discrete inputs you can't afford to drop.
+   *
+   * `onFlush(entries)` receives `[{ type, data }]` in insertion order. The
+   * Coalescer is transport-agnostic; the caller decides how to send each entry
+   * (game.realtime, game.action, a WebRTC datachannel, etc.).
+   */
+  class Coalescer {
+    /**
+     * @param {object} opts
+     * @param {number} [opts.hz=20]                 Flush frequency.
+     * @param {(entries:Array<{type:string,data:any}>)=>void} opts.onFlush
+     * @param {boolean} [opts.autoStart=true]
+     * @param {Function} [opts.setInterval]         Injectable for tests.
+     * @param {Function} [opts.clearInterval]
+     */
+    constructor(opts = {}) {
+      if (typeof opts.onFlush !== 'function') {
+        throw new Error('Coalescer requires an onFlush(entries) callback');
+      }
+      this._onFlush = opts.onFlush;
+      this._hz = opts.hz || 20;
+      this._setInterval = opts.setInterval || (typeof setInterval !== 'undefined' ? setInterval : null);
+      this._clearInterval = opts.clearInterval || (typeof clearInterval !== 'undefined' ? clearInterval : null);
+      this._order = [];          // slot keys in first-seen order
+      this._slots = {};          // key -> { mode:'latest'|'list', value, list }
+      this._timer = null;
+      if (opts.autoStart !== false) this.start();
+    }
+
+    get running() { return this._timer !== null; }
+
+    _ensure(type, mode) {
+      let slot = this._slots[type];
+      if (!slot) {
+        slot = { mode, value: undefined, list: [] };
+        this._slots[type] = slot;
+        this._order.push(type);
+      }
+      return slot;
+    }
+
+    /** Latest-wins: only the newest data for `type` is sent on the next flush. */
+    queue(type, data) {
+      const slot = this._ensure(type, 'latest');
+      slot.mode = 'latest';
+      slot.value = data;
+    }
+
+    /** Buffered: every value for `type` is kept and sent on the next flush. */
+    append(type, data) {
+      const slot = this._ensure(type, 'list');
+      slot.mode = 'list';
+      slot.list.push(data);
+    }
+
+    /** Build pending entries (insertion order) and clear the buffer. */
+    drain() {
+      const entries = [];
+      for (let i = 0; i < this._order.length; i++) {
+        const type = this._order[i];
+        const slot = this._slots[type];
+        if (slot.mode === 'latest') {
+          if (slot.value !== undefined) entries.push({ type, data: slot.value });
+        } else {
+          for (let j = 0; j < slot.list.length; j++) entries.push({ type, data: slot.list[j] });
+        }
+      }
+      this._order = [];
+      this._slots = {};
+      return entries;
+    }
+
+    /** Flush now (also called automatically on each tick). */
+    flush() {
+      if (this._order.length === 0) return;
+      const entries = this.drain();
+      if (entries.length) this._onFlush(entries);
+    }
+
+    start() {
+      if (this._timer || !this._setInterval) return;
+      this._timer = this._setInterval(() => this.flush(), Math.max(1, Math.round(1000 / this._hz)));
+    }
+
+    stop() {
+      if (this._timer && this._clearInterval) this._clearInterval(this._timer);
+      this._timer = null;
+    }
+  }
+
+  /**
+   * Usion SDK Netcode — Round-trip-time meter.
+   *
+   * Tracks RTT with an exponentially-weighted moving average plus a jitter
+   * estimate, so games (and the debug overlay) can surface real latency and so
+   * the interpolation buffer can be tuned to network conditions. Transport
+   * agnostic: feed it raw samples, or use begin()/end() to time individual
+   * probes.
+   */
+  class PingMeter {
+    /**
+     * @param {object} [opts]
+     * @param {number} [opts.alpha=0.2]  EWMA smoothing factor (0..1).
+     * @param {Function} [opts.now]      Clock source (default Date.now).
+     */
+    constructor(opts = {}) {
+      this._alpha = opts.alpha != null ? opts.alpha : 0.2;
+      this._now = opts.now || (() => Date.now());
+      this._rtt = null;
+      this._jitter = 0;
+      this._last = null;
+      this._id = 0;
+      this._outstanding = {};
+    }
+
+    /** Smoothed round-trip time in ms (null until the first sample). */
+    get rtt() { return this._rtt; }
+    /** One-way latency estimate (≈ rtt / 2). */
+    get latency() { return this._rtt == null ? null : this._rtt / 2; }
+    /** Smoothed absolute variation between samples (ms). */
+    get jitter() { return this._jitter; }
+    /** Most recent raw RTT sample (ms). */
+    get last() { return this._last; }
+
+    /** Start timing a probe; pass the returned id to end(). */
+    begin() {
+      const id = ++this._id;
+      this._outstanding[id] = this._now();
+      return id;
+    }
+
+    /** Complete a probe started with begin(); returns the RTT sample or null. */
+    end(id) {
+      const sent = this._outstanding[id];
+      if (sent == null) return null;
+      delete this._outstanding[id];
+      return this.sample(this._now() - sent);
+    }
+
+    /** Feed a raw RTT sample (ms). Returns the same value. */
+    sample(rttMs) {
+      if (!(rttMs >= 0)) return null;
+      if (this._rtt == null) {
+        this._rtt = rttMs;
+      } else {
+        this._jitter += this._alpha * (Math.abs(rttMs - this._rtt) - this._jitter);
+        this._rtt += this._alpha * (rttMs - this._rtt);
+      }
+      this._last = rttMs;
+      return rttMs;
+    }
+
+    reset() {
+      this._rtt = null;
+      this._jitter = 0;
+      this._last = null;
+      this._outstanding = {};
+    }
+  }
+
+  /**
+   * Usion SDK Netcode — WebRTC peer-to-peer data channels.
+   *
+   * WebSocket runs over TCP (ordered+reliable) → one lost packet stalls
+   * everything behind it (head-of-line blocking). WebRTC data channels run over
+   * UDP/SCTP and can be unreliable+unordered, so the newest state always gets
+   * through. Gameplay flows peer-to-peer (no backend hop, no HOL blocking).
+   *
+   * Practices adopted (WebRTC game-networking guidance):
+   *  - **Two channels**: 'unreliable' (ordered:false, maxRetransmits:0) for
+   *    gameplay, 'reliable' (ordered:true) for must-arrive events.
+   *  - **Sequence numbers** on the unreliable channel → drop stale/out-of-order
+   *    frames (the receiver only ever advances).
+   *  - **TURN-ready**: ~15–20% of sessions need a relay; pass iceServers (use the
+   *    `MeshConnection.iceServers()` helper). Trickle ICE is used by default.
+   *  - **Reconnect**: monitor (ice)connectionState and recover via ICE restart.
+   *
+   * Signaling I/O is injected, so the same class works in every connection mode
+   * and is testable with a fake RTCPeerConnection.
+   */
+  const DEFAULT_ICE = [{ urls: 'stun:stun.l.google.com:19302' }];
+
+  function isBinary$1(d) {
+    return d instanceof ArrayBuffer || ArrayBuffer.isView(d);
+  }
+
+  class MeshConnection {
+    /**
+     * @param {object} opts
+     * @param {'host'|'guest'} opts.role
+     * @param {(payload:object)=>void} opts.sendSignal
+     * @param {Array} [opts.iceServers]
+     * @param {boolean} [opts.sequenced=true]    Drop stale frames on the unreliable channel.
+     * @param {boolean} [opts.autoReconnect=true] Recover via ICE restart (host).
+     * @param {number}  [opts.maxRestarts=5]
+     * @param {Function} [opts.RTCPeerConnection] Injectable for tests.
+     * @param {Function} [opts.setTimeout]        Injectable for tests.
+     */
+    constructor(opts = {}) {
+      if (opts.role !== 'host' && opts.role !== 'guest') throw new Error("MeshConnection requires role 'host' or 'guest'");
+      if (typeof opts.sendSignal !== 'function') throw new Error('MeshConnection requires a sendSignal(payload) function');
+      this.role = opts.role;
+      this._sendSignal = opts.sendSignal;
+      this._iceServers = opts.iceServers || DEFAULT_ICE;
+      this._sequenced = opts.sequenced !== false;
+      this._autoReconnect = opts.autoReconnect !== false;
+      this._maxRestarts = opts.maxRestarts != null ? opts.maxRestarts : 5;
+      this._RTCPeerConnection = opts.RTCPeerConnection || (typeof RTCPeerConnection !== 'undefined' ? RTCPeerConnection : null);
+      this._setTimeout = opts.setTimeout || (typeof setTimeout !== 'undefined' ? setTimeout : null);
+
+      this.connected = false;
+      this._pc = null;
+      this._unreliable = null;
+      this._reliable = null;
+      this._sendSeq = 0;
+      this._recvSeq = 0;
+      this._restarts = 0;
+
+      this.onOpen = null;          // () => void
+      this.onMessage = null;       // (data, channel) => void
+      this.onClose = null;         // () => void
+      this.onError = null;         // (err) => void
+      this.onStateChange = null;   // (state:string) => void
+    }
+
+    /** Build an iceServers array with optional TURN relay. */
+    static iceServers(cfg = {}) {
+      const list = [{ urls: cfg.stun || 'stun:stun.l.google.com:19302' }];
+      if (cfg.turn) {
+        const entry = { urls: cfg.turn };
+        if (cfg.turnUsername) entry.username = cfg.turnUsername;
+        if (cfg.turnCredential) entry.credential = cfg.turnCredential;
+        list.push(entry);
+      }
+      return list;
+    }
+
+    async start() {
+      if (!this._RTCPeerConnection) throw new Error('RTCPeerConnection unavailable');
+      const pc = new this._RTCPeerConnection({ iceServers: this._iceServers });
+      this._pc = pc;
+
+      pc.onicecandidate = (e) => { if (e && e.candidate) this._sendSignal({ type: 'ice', candidate: e.candidate }); };
+      const onState = () => this._handleStateChange(pc.connectionState || pc.iceConnectionState);
+      pc.onconnectionstatechange = onState;
+      pc.oniceconnectionstatechange = onState;
+
+      if (this.role === 'host') {
+        this._bindChannel((this._unreliable = pc.createDataChannel('unreliable', { ordered: false, maxRetransmits: 0 })), 'unreliable');
+        this._bindChannel((this._reliable = pc.createDataChannel('reliable', { ordered: true })), 'reliable');
+        await this._makeOffer(false);
+      } else {
+        pc.ondatachannel = (e) => {
+          const ch = e.channel;
+          if (ch.label === 'unreliable') this._bindChannel((this._unreliable = ch), 'unreliable');
+          else if (ch.label === 'reliable') this._bindChannel((this._reliable = ch), 'reliable');
+        };
+      }
+    }
+
+    async _makeOffer(iceRestart) {
+      const pc = this._pc;
+      const offer = await pc.createOffer(iceRestart ? { iceRestart: true } : undefined);
+      await pc.setLocalDescription(offer);
+      this._sendSignal({ type: 'offer', sdp: pc.localDescription, restart: !!iceRestart });
+    }
+
+    _handleStateChange(state) {
+      if (this.onStateChange) this.onStateChange(state);
+      if (state === 'connected') { this._restarts = 0; return; }
+      if (state === 'failed' || state === 'disconnected' || state === 'closed') {
+        if (this.connected) { this.connected = false; if (this.onClose) this.onClose(); }
+        if (this._autoReconnect && this.role === 'host' && state !== 'closed' && this._restarts < this._maxRestarts) {
+          this._restarts += 1;
+          const delay = Math.min(1000 * this._restarts, 5000);
+          if (this._setTimeout) this._setTimeout(() => { this._makeOffer(true).catch((err) => { if (this.onError) this.onError(err); }); }, delay);
+        }
+      }
+    }
+
+    async handleSignal(payload) {
+      const pc = this._pc;
+      if (!pc || !payload || !payload.type) return;
+      try {
+        if (payload.type === 'offer') {
+          await pc.setRemoteDescription(payload.sdp);
+          const answer = await pc.createAnswer();
+          await pc.setLocalDescription(answer);
+          this._sendSignal({ type: 'answer', sdp: pc.localDescription });
+        } else if (payload.type === 'answer') {
+          await pc.setRemoteDescription(payload.sdp);
+        } else if (payload.type === 'ice' && payload.candidate) {
+          await pc.addIceCandidate(payload.candidate);
+        }
+      } catch (err) {
+        if (this.onError) this.onError(err);
+      }
+    }
+
+    _bindChannel(ch, label) {
+      ch.binaryType = 'arraybuffer';
+      ch.onopen = () => {
+        if (label === 'unreliable' && !this.connected) { this.connected = true; if (this.onOpen) this.onOpen(); }
+      };
+      ch.onmessage = (e) => {
+        if (!this.onMessage) return;
+        let data = e.data;
+        if (isBinary$1(data)) { this.onMessage(data, label); return; }
+        try { data = typeof data === 'string' ? JSON.parse(data) : data; } catch (_) { this.onMessage(e.data, label); return; }
+        if (label === 'unreliable' && this._sequenced && data && typeof data.__s === 'number') {
+          if (data.__s <= this._recvSeq) return; // stale / out-of-order — drop
+          this._recvSeq = data.__s;
+          this.onMessage(data.m, label);
+          return;
+        }
+        this.onMessage(data, label);
+      };
+      ch.onclose = () => { if (this.connected) { this.connected = false; if (this.onClose) this.onClose(); } };
+      ch.onerror = (e) => { if (this.onError) this.onError(e); };
+    }
+
+    /** Send over the unreliable/unordered channel (sequenced unless binary). */
+    send(data) {
+      const ch = this._unreliable;
+      if (!ch || ch.readyState !== 'open') return false;
+      if (isBinary$1(data)) { ch.send(data); return true; }
+      if (this._sequenced) { this._sendSeq += 1; ch.send(JSON.stringify({ __s: this._sendSeq, m: data })); }
+      else ch.send(typeof data === 'string' ? data : JSON.stringify(data));
+      return true;
+    }
+
+    /** Send over the reliable/ordered channel. */
+    sendReliable(data) {
+      const ch = this._reliable;
+      if (!ch || ch.readyState !== 'open') return false;
+      if (isBinary$1(data)) ch.send(data);
+      else ch.send(typeof data === 'string' ? data : JSON.stringify(data));
+      return true;
+    }
+
+    close() {
+      try { if (this._unreliable) this._unreliable.close(); } catch (_) {}
+      try { if (this._reliable) this._reliable.close(); } catch (_) {}
+      try { if (this._pc) this._pc.close(); } catch (_) {}
+      this._unreliable = this._reliable = this._pc = null;
+      this.connected = false;
+    }
+  }
+
+  /**
+   * Usion SDK Netcode — N-peer full mesh.
+   *
+   * Manages one MeshConnection per remote peer so >2 players can talk directly
+   * peer-to-peer. For each pair, the peer with the lexicographically smaller id
+   * is the host (deterministic role assignment avoids offer/answer "glare").
+   * Signaling is routed per-peer (`sendSignal(toPeerId, payload)`); feed inbound
+   * signaling with `handleSignal(fromPeerId, payload)`.
+   */
+
+  class MeshNetwork {
+    /**
+     * @param {object} opts
+     * @param {string} opts.selfId
+     * @param {(toPeerId:string, payload:object)=>void} opts.sendSignal
+     * @param {Array} [opts.iceServers]
+     * @param {Function} [opts.RTCPeerConnection]
+     * @param {Function} [opts.setTimeout]
+     * @param {boolean} [opts.sequenced]
+     * @param {boolean} [opts.autoReconnect]
+     */
+    constructor(opts = {}) {
+      if (!opts.selfId) throw new Error('MeshNetwork requires a selfId');
+      if (typeof opts.sendSignal !== 'function') throw new Error('MeshNetwork requires sendSignal(toPeerId, payload)');
+      this.selfId = opts.selfId;
+      this._sendSignal = opts.sendSignal;
+      this._opts = opts;
+      this._peers = {}; // peerId -> MeshConnection
+
+      this.onPeerOpen = null;    // (peerId) => void
+      this.onPeerClose = null;   // (peerId) => void
+      this.onMessage = null;     // (peerId, data, channel) => void
+      this.onError = null;       // (peerId, err) => void
+    }
+
+    get peerIds() { return Object.keys(this._peers); }
+    get connectedCount() { let n = 0; for (const id in this._peers) if (this._peers[id].connected) n += 1; return n; }
+    peer(peerId) { return this._peers[peerId] || null; }
+
+    _roleFor(peerId) { return this.selfId < peerId ? 'host' : 'guest'; }
+
+    _ensurePeer(peerId) {
+      if (this._peers[peerId]) return this._peers[peerId];
+      const self = this;
+      const conn = new MeshConnection({
+        role: this._roleFor(peerId),
+        iceServers: this._opts.iceServers,
+        RTCPeerConnection: this._opts.RTCPeerConnection,
+        setTimeout: this._opts.setTimeout,
+        sequenced: this._opts.sequenced,
+        autoReconnect: this._opts.autoReconnect,
+        sendSignal: (payload) => self._sendSignal(peerId, payload),
+      });
+      conn.onOpen = () => { if (self.onPeerOpen) self.onPeerOpen(peerId); };
+      conn.onClose = () => { if (self.onPeerClose) self.onPeerClose(peerId); };
+      conn.onMessage = (data, channel) => { if (self.onMessage) self.onMessage(peerId, data, channel); };
+      conn.onError = (err) => { if (self.onError) self.onError(peerId, err); };
+      this._peers[peerId] = conn;
+      return conn;
+    }
+
+    /** Connect to a peer (creates the connection and starts negotiation). */
+    async addPeer(peerId) {
+      if (peerId === this.selfId) return null;
+      const conn = this._ensurePeer(peerId);
+      await conn.start();
+      return conn;
+    }
+
+    /** Sync the mesh to a roster of peer ids: connect to new ones, drop missing. */
+    async setRoster(peerIds) {
+      const want = {};
+      for (let i = 0; i < peerIds.length; i++) if (peerIds[i] !== this.selfId) want[peerIds[i]] = true;
+      for (const id in want) if (!this._peers[id]) await this.addPeer(id);
+      for (const id in this._peers) if (!want[id]) this.removePeer(id);
+    }
+
+    removePeer(peerId) {
+      const conn = this._peers[peerId];
+      if (!conn) return;
+      try { conn.close(); } catch (_) {}
+      delete this._peers[peerId];
+    }
+
+    /** Route an inbound signaling message from a peer. */
+    async handleSignal(fromPeerId, payload) {
+      if (!fromPeerId || fromPeerId === this.selfId) return;
+      const conn = this._ensurePeer(fromPeerId);
+      if (!conn._pc) await conn.start(); // lazily start guest side on first offer
+      await conn.handleSignal(payload);
+    }
+
+    /** Send to one peer over the unreliable channel. */
+    send(peerId, data) { const c = this._peers[peerId]; return c ? c.send(data) : false; }
+    sendReliable(peerId, data) { const c = this._peers[peerId]; return c ? c.sendReliable(data) : false; }
+
+    /** Broadcast to all connected peers (unreliable). */
+    broadcast(data) { for (const id in this._peers) this._peers[id].send(data); }
+    broadcastReliable(data) { for (const id in this._peers) this._peers[id].sendReliable(data); }
+
+    close() { for (const id in this._peers) { try { this._peers[id].close(); } catch (_) {} } this._peers = {}; }
+  }
+
+  /**
+   * Usion SDK Netcode — WebTransport (HTTP/3 / QUIC) client transport.
+   *
+   * The lowest-latency *client-server* path for browser games (Baseline across
+   * major browsers since 2026). Unlike WebSocket (TCP → head-of-line blocking)
+   * it offers UDP-like unreliable **datagrams** — the newest snapshot always
+   * gets through — plus reliable **streams** for must-arrive events, over a
+   * single QUIC connection, without WebRTC's ICE/STUN/TURN/SDP complexity.
+   *
+   * Uses the native `WebTransport` API (zero dependency). On the server, pair
+   * with an HTTP/3 server such as the open-source `@fails-components/webtransport`
+   * (Node). Same interface shape as MeshConnection so it drops into the same
+   * snapshot sender/receiver + interpolation pipeline.
+   *
+   * Framing:
+   *   - datagram = [seq:uint32 BE][type:uint8][payload]  (one datagram = one msg)
+   *   - stream   = [len:uint32 BE][type:uint8][payload]  (len = 1 + payload bytes)
+   *   - type 0 = binary (Uint8Array), 1 = JSON (utf8). Sequenced datagrams drop
+   *     stale/out-of-order frames (receiver only advances).
+   */
+  const _enc$1 = typeof TextEncoder !== 'undefined' ? new TextEncoder() : null;
+  const _dec$1 = typeof TextDecoder !== 'undefined' ? new TextDecoder() : null;
+
+  function toBytes(s) { return _enc$1 ? _enc$1.encode(s) : Uint8Array.from(Buffer.from(s, 'utf8')); }
+  function fromBytes(b) { return _dec$1 ? _dec$1.decode(b) : Buffer.from(b).toString('utf8'); }
+  function isBinary(d) { return d instanceof ArrayBuffer || ArrayBuffer.isView(d); }
+
+  /** Encode a value to { type, bytes }: binary passthrough or JSON utf8. */
+  function encodePayload(data) {
+    if (isBinary(data)) return { type: 0, bytes: data instanceof Uint8Array ? data : new Uint8Array(data.buffer || data) };
+    return { type: 1, bytes: toBytes(JSON.stringify(data)) };
+  }
+  function decodePayload(type, bytes) {
+    if (type === 1) { try { return JSON.parse(fromBytes(bytes)); } catch (_) { return null; } }
+    return bytes;
+  }
+
+  /** datagram frame: [seq:4][type:1][payload] */
+  function encodeDatagram(seq, data) {
+    const { type, bytes } = encodePayload(data);
+    const out = new Uint8Array(5 + bytes.length);
+    new DataView(out.buffer).setUint32(0, seq >>> 0, false);
+    out[4] = type;
+    out.set(bytes, 5);
+    return out;
+  }
+  function decodeDatagram(frame) {
+    const b = frame instanceof Uint8Array ? frame : new Uint8Array(frame);
+    if (b.length < 5) return null;
+    const seq = new DataView(b.buffer, b.byteOffset, b.byteLength).getUint32(0, false);
+    return { seq: seq, value: decodePayload(b[4], b.subarray(5)) };
+  }
+
+  /** stream frame: [len:4][type:1][payload], len = 1 + payload length */
+  function encodeStreamFrame(data) {
+    const { type, bytes } = encodePayload(data);
+    const out = new Uint8Array(4 + 1 + bytes.length);
+    new DataView(out.buffer).setUint32(0, 1 + bytes.length, false);
+    out[4] = type;
+    out.set(bytes, 5);
+    return out;
+  }
+
+  /** Stateful deframer for the reliable byte stream. push(bytes) → [values]. */
+  class StreamDeframer {
+    constructor() { this._buf = new Uint8Array(0); }
+    push(chunk) {
+      const c = chunk instanceof Uint8Array ? chunk : new Uint8Array(chunk);
+      const merged = new Uint8Array(this._buf.length + c.length);
+      merged.set(this._buf, 0); merged.set(c, this._buf.length);
+      this._buf = merged;
+      const out = [];
+      while (this._buf.length >= 4) {
+        const len = new DataView(this._buf.buffer, this._buf.byteOffset, 4).getUint32(0, false);
+        if (this._buf.length < 4 + len) break;
+        const type = this._buf[4];
+        const payload = this._buf.subarray(5, 4 + len);
+        out.push(decodePayload(type, payload.slice()));
+        this._buf = this._buf.subarray(4 + len);
+      }
+      return out;
+    }
+  }
+
+  class WebTransportConnection {
+    /**
+     * @param {object} opts
+     * @param {string} opts.url                          https:// HTTP/3 endpoint
+     * @param {Array}  [opts.serverCertificateHashes]    for self-signed dev certs
+     * @param {boolean}[opts.sequenced=true]             drop stale datagrams
+     * @param {Function}[opts.WebTransport]              injectable for tests
+     */
+    constructor(opts = {}) {
+      if (!opts.url) throw new Error('WebTransportConnection requires a url');
+      this._url = opts.url;
+      this._opts = opts;
+      this._sequenced = opts.sequenced !== false;
+      this._WT = opts.WebTransport || (typeof WebTransport !== 'undefined' ? WebTransport : null);
+
+      this.connected = false;
+      this._t = null;
+      this._dgWriter = null;
+      this._streamWriter = null;
+      this._deframer = new StreamDeframer();
+      this._sendSeq = 0;
+      this._recvSeq = 0;
+
+      this.onOpen = null;        // () => void
+      this.onMessage = null;     // (data, channel:'datagram'|'reliable') => void
+      this.onClose = null;       // () => void
+      this.onError = null;       // (err) => void
+    }
+
+    async connect() {
+      if (!this._WT) throw new Error('WebTransport unavailable in this environment');
+      const init = {};
+      if (this._opts.serverCertificateHashes) init.serverCertificateHashes = this._opts.serverCertificateHashes;
+      const t = new this._WT(this._url, init);
+      this._t = t;
+      if (t.ready && typeof t.ready.then === 'function') await t.ready;
+
+      if (t.datagrams && t.datagrams.writable) this._dgWriter = t.datagrams.writable.getWriter();
+      if (typeof t.createBidirectionalStream === 'function') {
+        try {
+          const s = await t.createBidirectionalStream();
+          this._streamWriter = s.writable.getWriter();
+          this._pumpReadable(s.readable, 'reliable');
+        } catch (e) { /* reliable stream optional */ }
+      }
+      if (t.datagrams && t.datagrams.readable) this._pumpDatagrams(t.datagrams.readable);
+      if (t.closed && typeof t.closed.then === 'function') t.closed.then(() => this._onClosed(), () => this._onClosed());
+
+      this.connected = true;
+      if (this.onOpen) this.onOpen();
+    }
+
+    async _pumpDatagrams(readable) {
+      try {
+        const reader = readable.getReader();
+        for (;;) {
+          const { value, done } = await reader.read();
+          if (done) break;
+          if (value) this._onDatagramBytes(value);
+        }
+      } catch (e) { if (this.onError) this.onError(e); }
+    }
+
+    async _pumpReadable(readable, channel) {
+      try {
+        const reader = readable.getReader();
+        for (;;) {
+          const { value, done } = await reader.read();
+          if (done) break;
+          if (value) { const msgs = this._deframer.push(value); for (let i = 0; i < msgs.length; i++) if (this.onMessage) this.onMessage(msgs[i], channel); }
+        }
+      } catch (e) { if (this.onError) this.onError(e); }
+    }
+
+    /** Handle one inbound datagram frame (also the test entry point). */
+    _onDatagramBytes(frame) {
+      const parsed = decodeDatagram(frame);
+      if (!parsed) return;
+      if (this._sequenced) {
+        if (parsed.seq <= this._recvSeq) return; // stale / out-of-order
+        this._recvSeq = parsed.seq;
+      }
+      if (this.onMessage) this.onMessage(parsed.value, 'datagram');
+    }
+
+    /** Send over the unreliable datagram channel (sequenced). */
+    send(data) {
+      if (!this._dgWriter) return false;
+      this._sendSeq += 1;
+      try { this._dgWriter.write(encodeDatagram(this._sendSeq, data)); return true; }
+      catch (e) { return false; }
+    }
+
+    /** Send over the reliable ordered stream. */
+    sendReliable(data) {
+      if (!this._streamWriter) return false;
+      try { this._streamWriter.write(encodeStreamFrame(data)); return true; }
+      catch (e) { return false; }
+    }
+
+    _onClosed() {
+      if (this.connected) { this.connected = false; if (this.onClose) this.onClose(); }
+    }
+
+    close() {
+      try { if (this._dgWriter) this._dgWriter.releaseLock && this._dgWriter.releaseLock(); } catch (_) {}
+      try { if (this._t) this._t.close(); } catch (_) {}
+      this._t = this._dgWriter = this._streamWriter = null;
+      this.connected = false;
+    }
+  }
+
+  /**
+   * Usion SDK Netcode — network condition simulator.
+   *
+   * Every serious game studio tests under degraded networks. NetworkSim wraps a
+   * send (or receive) function and injects artificial **latency**, **jitter**,
+   * **packet loss**, and **duplication** so creators can feel and tune their game
+   * on a bad connection — locally, before shipping. Pure and deterministic when
+   * you inject `random` / `setTimeout` (used in tests).
+   */
+  class NetworkSim {
+    /**
+     * @param {object} [opts]
+     * @param {number} [opts.latencyMs=0]  Base one-way delay added to each message.
+     * @param {number} [opts.jitterMs=0]   Random +/- variation around the latency.
+     * @param {number} [opts.lossPct=0]    Probability (0–100) a message is dropped.
+     * @param {number} [opts.dupPct=0]     Probability (0–100) a message is duplicated.
+     * @param {Function} [opts.setTimeout] Injectable scheduler (tests).
+     * @param {Function} [opts.clearTimeout]
+     * @param {Function} [opts.random]     Injectable RNG (tests).
+     */
+    constructor(opts = {}) {
+      this._set = opts.setTimeout || (typeof setTimeout !== 'undefined' ? setTimeout : null);
+      this._clear = opts.clearTimeout || (typeof clearTimeout !== 'undefined' ? clearTimeout : null);
+      this._rand = opts.random || Math.random;
+      this._timers = new Set();
+      this.set(opts);
+    }
+
+    /** Update conditions live. */
+    set(opts = {}) {
+      if (opts.latencyMs != null) this.latencyMs = Math.max(0, opts.latencyMs);
+      else if (this.latencyMs == null) this.latencyMs = 0;
+      if (opts.jitterMs != null) this.jitterMs = Math.max(0, opts.jitterMs);
+      else if (this.jitterMs == null) this.jitterMs = 0;
+      if (opts.lossPct != null) this.lossPct = Math.max(0, Math.min(100, opts.lossPct));
+      else if (this.lossPct == null) this.lossPct = 0;
+      if (opts.dupPct != null) this.dupPct = Math.max(0, Math.min(100, opts.dupPct));
+      else if (this.dupPct == null) this.dupPct = 0;
+      return this;
+    }
+
+    /** Delay for one message: latency ± jitter (never negative). */
+    _delay() {
+      const j = this.jitterMs ? (this._rand() * 2 - 1) * this.jitterMs : 0;
+      const d = this.latencyMs + j;
+      return d > 0 ? d : 0;
+    }
+
+    _schedule(fn, delay) {
+      if (!this._set) { fn(); return; }
+      const id = this._set(() => { this._timers.delete(id); fn(); }, delay);
+      this._timers.add(id);
+    }
+
+    /**
+     * Wrap a delivery function so calls are delayed/dropped/duplicated per the
+     * current conditions. The returned function has the same signature.
+     */
+    wrap(fn) {
+      const self = this;
+      return function (...args) {
+        // Fast path: no degradation configured.
+        if (!self.latencyMs && !self.jitterMs && !self.lossPct && !self.dupPct) return fn.apply(this, args);
+        if (self.lossPct && self._rand() * 100 < self.lossPct) return undefined; // dropped
+        const ctx = this;
+        self._schedule(() => fn.apply(ctx, args), self._delay());
+        if (self.dupPct && self._rand() * 100 < self.dupPct) self._schedule(() => fn.apply(ctx, args), self._delay());
+        return undefined;
+      };
+    }
+
+    /** Cancel all in-flight scheduled deliveries. */
+    flush() {
+      if (this._clear) for (const id of this._timers) this._clear(id);
+      this._timers.clear();
+    }
+  }
+
+  /**
+   * Usion SDK Netcode — deterministic lockstep (the League-of-Legends / RTS model).
+   *
+   * Instead of streaming world state, every client runs the **same deterministic
+   * simulation** and exchanges only **inputs**. Bandwidth is tiny even with
+   * hundreds of units, and you get **replays for free** (re-run the input log).
+   *
+   * A frame advances only once every player's input for that frame is known.
+   * Local inputs are scheduled `inputDelay` frames ahead so they have time to
+   * reach peers before that frame is simulated (this hides latency). The game
+   * owns its simulation; this class only orders inputs and tells you when to step.
+   *
+   * Determinism is the contract: your `step(frame, inputsByPlayer)` must be
+   * fully deterministic (no Date.now/Math.random without a seeded source, no
+   * floating-point divergence) or clients will desync.
+   */
+  class Lockstep {
+    /**
+     * @param {object} opts
+     * @param {string} opts.playerId
+     * @param {string[]} opts.players              All player ids in the match.
+     * @param {(frame:number, inputs:Object)=>void} opts.step  Deterministic sim step.
+     * @param {(msg:{frame:number,playerId:string,input:any})=>void} [opts.send]
+     * @param {number} [opts.inputDelay=2]         Frames of input delay (latency hiding).
+     * @param {any} [opts.idleInput=null]          Input used for the seeded startup frames.
+     */
+    constructor(opts = {}) {
+      if (!opts.playerId) throw new Error('Lockstep requires playerId');
+      if (!Array.isArray(opts.players) || opts.players.length === 0) throw new Error('Lockstep requires players[]');
+      if (typeof opts.step !== 'function') throw new Error('Lockstep requires a step(frame, inputs) function');
+      this.playerId = opts.playerId;
+      this._players = opts.players.slice();
+      this._step = opts.step;
+      this._send = opts.send || function () {};
+      this._inputDelay = opts.inputDelay != null ? opts.inputDelay : 2;
+      this._idle = opts.idleInput != null ? opts.idleInput : null;
+
+      this._inputs = {};        // frame -> { playerId: input }
+      this._frame = 0;          // next frame to simulate
+      this._submitFrame = this._inputDelay; // next frame the local player will fill
+      this._replay = [];        // [{ frame, inputs }]
+
+      // Seed the first `inputDelay` frames as idle so the sim can start.
+      for (let f = 0; f < this._inputDelay; f++) {
+        this._inputs[f] = {};
+        for (let i = 0; i < this._players.length; i++) this._inputs[f][this._players[i]] = this._idle;
+      }
+    }
+
+    get frame() { return this._frame; }
+    get players() { return this._players.slice(); }
+
+    /** Submit the local player's input for the next schedulable frame. */
+    submit(input) {
+      const frame = this._submitFrame++;
+      if (!this._inputs[frame]) this._inputs[frame] = {};
+      this._inputs[frame][this.playerId] = input;
+      this._send({ frame: frame, playerId: this.playerId, input: input });
+      return frame;
+    }
+
+    /** Record a remote player's input. */
+    receive(msg) {
+      if (!msg || msg.frame == null || !msg.playerId) return;
+      if (!this._inputs[msg.frame]) this._inputs[msg.frame] = {};
+      this._inputs[msg.frame][msg.playerId] = msg.input;
+    }
+
+    _ready(frame) {
+      const fr = this._inputs[frame];
+      if (!fr) return false;
+      for (let i = 0; i < this._players.length; i++) if (!(this._players[i] in fr)) return false;
+      return true;
+    }
+
+    /**
+     * Advance the simulation by every frame whose inputs are fully known.
+     * @returns {number} frames advanced this call.
+     */
+    tick() {
+      let advanced = 0;
+      while (this._ready(this._frame)) {
+        const inputs = this._inputs[this._frame];
+        this._step(this._frame, inputs);
+        this._replay.push({ frame: this._frame, inputs: inputs });
+        delete this._inputs[this._frame];
+        this._frame += 1;
+        advanced += 1;
+      }
+      return advanced;
+    }
+
+    /** True if the sim is blocked waiting on a missing input (stall detection). */
+    isStalled() { return !this._ready(this._frame); }
+
+    /** The ordered input log — persist it to enable replays. */
+    getReplay() { return this._replay.slice(); }
+
+    /** Re-simulate a recorded match by replaying its input log. */
+    static replay(log, step) {
+      for (let i = 0; i < log.length; i++) step(log[i].frame, log[i].inputs);
+    }
+  }
+
+  /**
+   * Usion SDK Netcode — server-side lag compensation ("server rewind").
+   *
+   * The fairness technique behind CS:GO/CS2 and Valorant. The authoritative
+   * server records a short history of world snapshots; when a client claims an
+   * action (e.g. a shot) the server **rewinds** the world to what that client
+   * actually saw — accounting for their latency and interpolation delay — and
+   * resolves the hit against that past state. Without this, high-ping players
+   * must "lead" their targets and hit registration feels broken.
+   *
+   * Entities are matched by `id` and interpolated between the two recorded
+   * snapshots straddling the rewind time (same math as client interpolation).
+   * Pure and testable; use it inside your game server (direct mode).
+   */
+  function lerp(a, b, t) { return a + (b - a) * t; }
+
+  class LagCompensator {
+    /**
+     * @param {object} [opts]
+     * @param {number} [opts.historyMs=1000]  How far back to retain snapshots.
+     * @param {number} [opts.maxSize=256]      Hard cap on retained snapshots.
+     * @param {function} [opts.now]            Clock source (default Date.now).
+     */
+    constructor(opts = {}) {
+      this._historyMs = opts.historyMs || 1000;
+      this._maxSize = opts.maxSize || 256;
+      this._now = opts.now || (() => Date.now());
+      this._history = []; // [{ time, entities:[{id,...}] }] oldest→newest
+    }
+
+    /**
+     * Record the authoritative world state for this tick.
+     * @param {Array} entities  Array of entities (each with a stable `id`).
+     * @param {number} [time]   Server time (default now()).
+     */
+    record(entities, time) {
+      const t = time != null ? time : this._now();
+      this._history.push({ time: t, entities: entities.map((e) => Object.assign({}, e)) });
+      const cutoff = t - this._historyMs;
+      while (this._history.length > this._maxSize || (this._history.length > 2 && this._history[0].time < cutoff)) {
+        this._history.shift();
+      }
+    }
+
+    get size() { return this._history.length; }
+    clear() { this._history = []; }
+
+    /**
+     * Reconstruct the world as it was at `time` (interpolated), keyed by id.
+     * @param {number} time  Absolute server time to rewind to.
+     * @param {string[]} [keys]  Numeric fields to interpolate (default: all numbers).
+     * @returns {Object<string, object>} entities by id, or {} if no history.
+     */
+    rewind(time, keys) {
+      const h = this._history;
+      if (h.length === 0) return {};
+      if (time <= h[0].time) return byId(h[0].entities);
+      if (time >= h[h.length - 1].time) return byId(h[h.length - 1].entities);
+
+      let older = h[0], newer = h[h.length - 1];
+      for (let i = h.length - 1; i > 0; i--) {
+        if (h[i - 1].time <= time && time <= h[i].time) { older = h[i - 1]; newer = h[i]; break; }
+      }
+      const span = newer.time - older.time;
+      const t = span > 0 ? (time - older.time) / span : 0;
+      const oldById = byId(older.entities);
+      const out = {};
+      const newById = byId(newer.entities);
+      for (const id in newById) {
+        const b = newById[id];
+        const a = oldById[id];
+        const e = Object.assign({}, b);
+        if (a) {
+          const fields = keys || Object.keys(b);
+          for (let k = 0; k < fields.length; k++) {
+            const key = fields[k];
+            if (typeof a[key] === 'number' && typeof b[key] === 'number') e[key] = lerp(a[key], b[key], t);
+          }
+        }
+        out[id] = e;
+      }
+      return out;
+    }
+
+    /**
+     * Convenience: rewind to what a client saw, given their measured round-trip
+     * time and interpolation buffer. rewindMs is clamped to `maxRewindMs` (cap
+     * it — Valorant caps ~35ms; CS allows more).
+     * @returns {Object<string, object>} entities by id
+     */
+    rewindForClient(rttMs, interpBufferMs, opts) {
+      opts = opts || {};
+      const maxRewind = opts.maxRewindMs != null ? opts.maxRewindMs : 250;
+      let rewindMs = (rttMs || 0) / 2 + (interpBufferMs || 0);
+      if (rewindMs > maxRewind) rewindMs = maxRewind;
+      return this.rewind(this._now() - rewindMs, opts.keys);
+    }
+  }
+
+  function byId(entities) {
+    const m = {};
+    for (let i = 0; i < entities.length; i++) m[entities[i].id] = entities[i];
+    return m;
+  }
+
+  /**
+   * Usion SDK Netcode — Delta compression for JSON game state.
+   *
+   * Real-time games typically re-send their entire world every tick. Most of
+   * that payload is unchanged. `diff` produces a minimal patch describing only
+   * what changed since the previous state; `patch` reconstructs the new state
+   * from a base + patch. Both are plain JSON, so the patch rides on the existing
+   * realtime/action channels unchanged.
+   *
+   * Wire format:
+   *   - Objects → `{ k: <patch> }` for changed keys, `_d: [keys]` for deletions.
+   *   - **Entity arrays** (every element a plain object with a stable `id`) →
+   *     keyed diff `{ _ka:{id:patch}, _add:[entities], _del:[ids], _ord:[ids] }`.
+   *     This is O(changes), not O(index shift): inserting/removing an element no
+   *     longer rewrites every following index. (Gaffer-on-Games "state sync".)
+   *   - Other arrays → index diff `{ _a:{i:patch}, _n:length }`.
+   *   - Primitives / type changes → `{ _s: value }`.
+   *   - No change → `undefined`.
+   *
+   * `quantize` rounds numeric fields to a fixed resolution before diffing, so
+   * sub-resolution jitter doesn't produce spurious deltas and payloads shrink
+   * (the single biggest, simplest snapshot-compression win — Gaffer on Games).
+   */
+
+  const SET = '_s';   // wholesale set
+  const DEL = '_d';   // deleted object keys
+  const ARR$1 = '_a';   // index array patches
+  const LEN = '_n';   // index array length
+  const KA = '_ka';   // keyed-array: per-id patches
+  const ADD = '_add'; // keyed-array: added entities (full)
+  const KDEL = '_del';// keyed-array: removed ids
+  const ORD = '_ord'; // keyed-array: explicit id order (only when it changes)
+
+  function isPlainObject(v) {
+    return v !== null && typeof v === 'object' && !Array.isArray(v);
+  }
+
+  function isEntityArray(v) {
+    if (!Array.isArray(v) || v.length === 0) return false;
+    for (let i = 0; i < v.length; i++) {
+      const e = v[i];
+      if (!isPlainObject(e) || (typeof e.id !== 'string' && typeof e.id !== 'number')) return false;
+    }
+    return true;
+  }
+
+  function sameOrder(a, b) {
+    if (a.length !== b.length) return false;
+    for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false;
+    return true;
+  }
+
+  /**
+   * Compute a minimal patch turning `prev` into `next`.
+   * @returns the patch, or `undefined` when nothing changed.
+   */
+  function diff(prev, next) {
+    if (prev === next) return undefined;
+
+    const prevArr = Array.isArray(prev);
+    const nextArr = Array.isArray(next);
+
+    // Type changed (or one side primitive) — send the whole value.
+    if (prevArr !== nextArr || isPlainObject(prev) !== isPlainObject(next)) {
+      return { [SET]: next };
+    }
+
+    if (nextArr) {
+      // Keyed (entity) arrays: diff by id so index shifts are free.
+      if (isEntityArray(prev) && isEntityArray(next)) return diffKeyedArray(prev, next);
+      return diffIndexArray(prev, next);
+    }
+
+    if (isPlainObject(next)) return diffObject(prev, next);
+
+    // Two differing primitives.
+    return { [SET]: next };
+  }
+
+  function diffObject(prev, next) {
+    const out = {};
+    let changed = false;
+    for (const k in next) {
+      if (!Object.prototype.hasOwnProperty.call(next, k)) continue;
+      const d = diff(prev[k], next[k]);
+      if (d !== undefined) { out[k] = d; changed = true; }
+    }
+    const deleted = [];
+    for (const k in prev) {
+      if (!Object.prototype.hasOwnProperty.call(prev, k)) continue;
+      if (!Object.prototype.hasOwnProperty.call(next, k)) deleted.push(k);
+    }
+    if (deleted.length) { out[DEL] = deleted; changed = true; }
+    return changed ? out : undefined;
+  }
+
+  function diffIndexArray(prev, next) {
+    const out = { [ARR$1]: {} };
+    let changed = false;
+    for (let i = 0; i < next.length; i++) {
+      const d = i < prev.length ? diff(prev[i], next[i]) : { [SET]: next[i] };
+      if (d !== undefined) { out[ARR$1][i] = d; changed = true; }
+    }
+    if (next.length !== prev.length) { out[LEN] = next.length; changed = true; }
+    return changed ? out : undefined;
+  }
+
+  function diffKeyedArray(prev, next) {
+    const prevById = {};
+    const prevIds = [];
+    for (let i = 0; i < prev.length; i++) { prevById[prev[i].id] = prev[i]; prevIds.push(prev[i].id); }
+    const nextIds = [];
+    const out = {};
+    let changed = false;
+
+    for (let i = 0; i < next.length; i++) {
+      const e = next[i];
+      nextIds.push(e.id);
+      if (Object.prototype.hasOwnProperty.call(prevById, e.id)) {
+        const d = diff(prevById[e.id], e);
+        if (d !== undefined) {
+          if (!out[KA]) out[KA] = {};
+          out[KA][e.id] = d;
+          changed = true;
+        }
+      } else {
+        if (!out[ADD]) out[ADD] = [];
+        out[ADD].push(e);
+        changed = true;
+      }
+    }
+
+    const nextIdSet = {};
+    for (let i = 0; i < nextIds.length; i++) nextIdSet[nextIds[i]] = true;
+    for (let i = 0; i < prevIds.length; i++) {
+      if (!nextIdSet[prevIds[i]]) {
+        if (!out[KDEL]) out[KDEL] = [];
+        out[KDEL].push(prevIds[i]);
+        changed = true;
+      }
+    }
+
+    if (!sameOrder(prevIds, nextIds)) { out[ORD] = nextIds; changed = true; }
+    return changed ? out : undefined;
+  }
+
+  /**
+   * Apply a patch produced by `diff` to `base`, returning the new value.
+   * Does not mutate `base`. A nullish patch returns `base` unchanged.
+   */
+  function patch(base, p) {
+    if (p === undefined || p === null) return base;
+    if (Object.prototype.hasOwnProperty.call(p, SET)) return p[SET];
+
+    // Keyed (entity) array.
+    if (p[KA] || p[ADD] || p[KDEL] || p[ORD]) return patchKeyedArray(base, p);
+
+    // Index array.
+    if (Object.prototype.hasOwnProperty.call(p, ARR$1) || Object.prototype.hasOwnProperty.call(p, LEN)) {
+      const src = Array.isArray(base) ? base : [];
+      const len = Object.prototype.hasOwnProperty.call(p, LEN) ? p[LEN] : src.length;
+      const out = src.slice(0, len);
+      const patches = p[ARR$1] || {};
+      for (const i in patches) {
+        if (!Object.prototype.hasOwnProperty.call(patches, i)) continue;
+        out[i] = patch(out[i], patches[i]);
+      }
+      return out;
+    }
+
+    // Object patch.
+    const out = isPlainObject(base) ? Object.assign({}, base) : {};
+    const deleted = p[DEL];
+    for (const k in p) {
+      if (k === DEL) continue;
+      if (!Object.prototype.hasOwnProperty.call(p, k)) continue;
+      out[k] = patch(out[k], p[k]);
+    }
+    if (Array.isArray(deleted)) for (let i = 0; i < deleted.length; i++) delete out[deleted[i]];
+    return out;
+  }
+
+  function patchKeyedArray(base, p) {
+    const baseArr = Array.isArray(base) ? base : [];
+    const byId = {};
+    const baseOrder = [];
+    for (let i = 0; i < baseArr.length; i++) {
+      const e = baseArr[i];
+      if (e && (typeof e.id === 'string' || typeof e.id === 'number')) { byId[e.id] = e; baseOrder.push(e.id); }
+    }
+    // Apply per-id field patches.
+    if (p[KA]) for (const id in p[KA]) {
+      if (Object.prototype.hasOwnProperty.call(p[KA], id) && byId[id] !== undefined) byId[id] = patch(byId[id], p[KA][id]);
+    }
+    // Additions.
+    if (p[ADD]) for (let i = 0; i < p[ADD].length; i++) { const e = p[ADD][i]; byId[e.id] = e; }
+    // Removals.
+    const removed = {};
+    if (p[KDEL]) for (let i = 0; i < p[KDEL].length; i++) removed[p[KDEL][i]] = true;
+
+    if (p[ORD]) {
+      const out = [];
+      for (let i = 0; i < p[ORD].length; i++) {
+        const id = p[ORD][i];
+        if (byId[id] !== undefined) out.push(byId[id]);
+      }
+      return out;
+    }
+    // No order change: keep base order minus removals, patched in place.
+    const out = [];
+    for (let i = 0; i < baseOrder.length; i++) {
+      const id = baseOrder[i];
+      if (!removed[id]) out.push(byId[id]);
+    }
+    return out;
+  }
+
+  /**
+   * Round every numeric field to `precision` decimal places (default 2),
+   * returning a new value. Apply before diffing so sub-resolution jitter and
+   * float noise don't generate spurious deltas, and payloads stay small.
+   */
+  function quantize(value, precision = 2) {
+    const f = Math.pow(10, precision);
+    function q(v) {
+      if (typeof v === 'number') return Number.isFinite(v) ? Math.round(v * f) / f : v;
+      if (Array.isArray(v)) return v.map(q);
+      if (isPlainObject(v)) {
+        const o = {};
+        for (const k in v) if (Object.prototype.hasOwnProperty.call(v, k)) o[k] = q(v[k]);
+        return o;
+      }
+      return v;
+    }
+    return q(value);
+  }
+
+  /**
+   * Usion SDK Netcode — compact binary codec (zero-dependency).
+   *
+   * A tiny MessagePack-style serializer for JSON-like snapshot payloads. Pair it
+   * with the snapshot sender/receiver (`encode`/`decode` options) to send game
+   * state as binary over the WebRTC data channel or a binary-capable WebSocket —
+   * meaningfully smaller than JSON, especially after quantization (small ints
+   * pack into 1–2 bytes). WebRTC/Socket.IO transmit ArrayBuffers natively.
+   *
+   * NOT for the iframe/WebView proxy path (that bridge relays JSON) — use binary
+   * on direct/mesh transports.
+   *
+   * Wire tags:  0xc0 null · 0xc2 false · 0xc3 true · 0xc4 int(zigzag varint) ·
+   *             0xc5 float64 · 0xc6 string · 0xc7 array · 0xc8 object
+   */
+  const NULL = 0xc0, FALSE = 0xc2, TRUE = 0xc3, INT = 0xc4, F64 = 0xc5, STR = 0xc6, ARR = 0xc7, OBJ = 0xc8;
+
+  const _enc = typeof TextEncoder !== 'undefined' ? new TextEncoder() : null;
+  const _dec = typeof TextDecoder !== 'undefined' ? new TextDecoder() : null;
+
+  function pushVarint(out, n) {
+    // unsigned LEB128
+    n = n >>> 0;
+    while (n > 0x7f) { out.push((n & 0x7f) | 0x80); n >>>= 7; }
+    out.push(n);
+  }
+  function zigzag(n) { return ((n << 1) ^ (n >> 31)) >>> 0; }
+  function unzigzag(u) { return (u >>> 1) ^ -(u & 1); }
+
+  function encodeValue(out, v) {
+    if (v === null || v === undefined) { out.push(NULL); return; }
+    const t = typeof v;
+    if (t === 'boolean') { out.push(v ? TRUE : FALSE); return; }
+    if (t === 'number') {
+      if (Number.isInteger(v) && v >= -2147483648 && v <= 2147483647) {
+        out.push(INT); pushVarint(out, zigzag(v));
+      } else {
+        out.push(F64);
+        const b = new Uint8Array(8); new DataView(b.buffer).setFloat64(0, v, true);
+        for (let i = 0; i < 8; i++) out.push(b[i]);
+      }
+      return;
+    }
+    if (t === 'string') {
+      out.push(STR);
+      const bytes = _enc ? _enc.encode(v) : Buffer.from(v, 'utf8');
+      pushVarint(out, bytes.length);
+      for (let i = 0; i < bytes.length; i++) out.push(bytes[i]);
+      return;
+    }
+    if (Array.isArray(v)) {
+      out.push(ARR); pushVarint(out, v.length);
+      for (let i = 0; i < v.length; i++) encodeValue(out, v[i]);
+      return;
+    }
+    if (t === 'object') {
+      const keys = Object.keys(v);
+      out.push(OBJ); pushVarint(out, keys.length);
+      for (let i = 0; i < keys.length; i++) {
+        const k = keys[i];
+        const kb = _enc ? _enc.encode(k) : Buffer.from(k, 'utf8');
+        pushVarint(out, kb.length);
+        for (let j = 0; j < kb.length; j++) out.push(kb[j]);
+        encodeValue(out, v[k]);
+      }
+      return;
+    }
+    out.push(NULL);
+  }
+
+  /** Encode a JSON-like value to a Uint8Array. */
+  function encode(value) {
+    const out = [];
+    encodeValue(out, value);
+    return Uint8Array.from(out);
+  }
+
+  function reader(bytes) {
+    let off = 0;
+    const dv = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    function varint() {
+      let shift = 0, result = 0, b;
+      do { b = bytes[off++]; result |= (b & 0x7f) << shift; shift += 7; } while (b & 0x80);
+      return result >>> 0;
+    }
+    function str() {
+      const len = varint();
+      const slice = bytes.subarray(off, off + len);
+      off += len;
+      return _dec ? _dec.decode(slice) : Buffer.from(slice).toString('utf8');
+    }
+    function value() {
+      const tag = bytes[off++];
+      switch (tag) {
+        case NULL: return null;
+        case TRUE: return true;
+        case FALSE: return false;
+        case INT: return unzigzag(varint());
+        case F64: { const v = dv.getFloat64(off, true); off += 8; return v; }
+        case STR: return str();
+        case ARR: { const n = varint(); const a = new Array(n); for (let i = 0; i < n; i++) a[i] = value(); return a; }
+        case OBJ: { const n = varint(); const o = {}; for (let i = 0; i < n; i++) { const k = str(); o[k] = value(); } return o; }
+        default: return null;
+      }
+    }
+    return value;
+  }
+
+  /** Decode a Uint8Array / ArrayBuffer produced by `encode`. */
+  function decode(buf) {
+    const bytes = buf instanceof Uint8Array ? buf : new Uint8Array(buf);
+    return reader(bytes)();
+  }
+
+  /**
+   * Usion SDK Game Netcode — convenience wiring of the netcode toolkit onto the
+   * game module. These helpers ride on the existing realtime/action channels, so
+   * they work in every connection mode with no host/backend change (the one
+   * exception is RTT measurement — see game.ping below).
+   */
+
+  function applyGameNetcode(game, Usion) {
+    game.diff = diff;
+    game.patch = patch;
+    game.quantize = quantize;
+    game.encode = encode;
+    game.decode = decode;
+
+    game.createInterpolation = function (opts) { return new SnapshotInterpolation(opts || {}); };
+    game.createPredictor = function (opts) { return new Predictor(opts || {}); };
+    game.createLagCompensator = function (opts) { return new LagCompensator(opts || {}); };
+    game.createLockstep = function (opts) { return new Lockstep(opts || {}); };
+
+    // ── Realtime channel router ──────────────────────────────────────────────
+    // Multiplexes realtime by action_type so replicate / mesh / mesh-network and
+    // the game's own onRealtime can coexist. Also the inject point for the
+    // network simulator's inbound side.
+    game._channels = game._channels || {};
+    game._userRealtime = game._userRealtime || null;
+    game._inboundDispatch = null;
+    function dispatchRealtime(data) {
+      const at = data && data.action_type;
+      if (at && game._channels[at]) { game._channels[at](data && (data.action_data !== undefined ? data.action_data : data), data); return; }
+      if (game._userRealtime) game._userRealtime(data);
+    }
+    game._dispatchRealtime = dispatchRealtime;
+    game._installRealtimeRouter = function () {
+      if (game._routerInstalled) return;
+      if (game._eventHandlers.realtime && game._eventHandlers.realtime !== game._router) game._userRealtime = game._eventHandlers.realtime;
+      game._router = function (data) { (game._inboundDispatch || game._dispatchRealtime)(data); };
+      game._eventHandlers.realtime = game._router;
+      game._routerInstalled = true;
+    };
+    /** Register a handler for one realtime action_type. Returns an unsubscribe fn. */
+    game._onChannel = function (type, handler) { game._channels[type] = handler; game._installRealtimeRouter(); return function () { delete game._channels[type]; }; };
+    // Route onRealtime through the router so channels keep working.
+    game.onRealtime = function (cb) { game._userRealtime = cb; game._installRealtimeRouter(); };
+
+    /** Fixed-rate outbound sender (defaults to game.realtime). */
+    game.createSender = function (opts) {
+      opts = opts || {};
+      const self = this;
+      const send = opts.send || function (type, data) { self.realtime(type, data); };
+      return new Coalescer({
+        hz: opts.hz || 20,
+        autoStart: opts.autoStart !== false,
+        onFlush: function (entries) { for (let i = 0; i < entries.length; i++) send(entries[i].type, entries[i].data); },
+      });
+    };
+
+    /**
+     * Coalesced, sequence-guarded, delta-compressed snapshot sender.
+     *
+     * Deltas are computed against the **last keyframe** (not the previous frame),
+     * so a single lost delta on an unreliable channel never desyncs — the next
+     * delta still applies to the keyframe the receiver holds. Each message
+     * carries a monotonic seq (`s`) and, for deltas, the keyframe seq it's based
+     * on (`b`); the receiver uses these to drop stale/out-of-order frames and to
+     * hold until it has the right keyframe. Optional float `precision`
+     * (quantization) and binary `encode` shrink the wire further.
+     *
+     * Pass `source` (a getter) to auto-read the state each tick — the basis for
+     * game.replicate(). Pair with game.createSnapshotReceiver().
+     */
+    game.createSnapshotSender = function (opts) {
+      opts = opts || {};
+      const self = this;
+      const channel = opts.channel || 'state';
+      const useDelta = opts.delta !== false;
+      const keyframeEvery = opts.keyframeEvery != null ? opts.keyframeEvery : 30;
+      const precision = opts.precision;
+      const enc = opts.encode === true ? encode : (typeof opts.encode === 'function' ? opts.encode : null);
+      const send = opts.send || function (type, data) { self.realtime(type, data); };
+      const source = typeof opts.source === 'function' ? opts.source : null;
+      let keyframeState = null; // an immutable clone (deltas diff against this)
+      let keyframeSeq = 0;
+      let seq = 0;
+      let sinceKey = 0;
+
+      function snapshotClone(v) { return v == null ? v : JSON.parse(JSON.stringify(v)); }
+
+      function emit(raw) {
+        if (raw === undefined || raw === null) return;
+        const state = precision != null ? quantize(raw, precision) : raw;
+        let payload;
+        const wantKey = !useDelta || keyframeState === null || sinceKey >= keyframeEvery;
+        if (wantKey) {
+          seq += 1; keyframeState = snapshotClone(state); keyframeSeq = seq; sinceKey = 0;
+          payload = { s: seq, f: state };
+        } else {
+          const d = diff(keyframeState, state);
+          if (d === undefined) return; // nothing changed — don't burn a seq
+          seq += 1; sinceKey += 1;
+          payload = { s: seq, b: keyframeSeq, d: d };
+        }
+        send(channel, enc ? enc(payload) : payload);
+      }
+
+      // Two drive modes: a `source` getter (read every tick) or queued send().
+      const hz = opts.hz || 20;
+      let queued;
+      const co = source ? null : new Coalescer({
+        hz: hz, autoStart: opts.autoStart !== false,
+        onFlush: function (entries) { for (let i = 0; i < entries.length; i++) if (entries[i].type === '__snap') queued = entries[i].data; emit(queued); },
+      });
+      let timer = null;
+      function start() {
+        if (co) { co.start(); return; }
+        if (timer || typeof setInterval === 'undefined') return;
+        timer = setInterval(function () { emit(source()); }, Math.max(1, Math.round(1000 / hz)));
+      }
+      function stop() { if (co) co.stop(); if (timer) { clearInterval(timer); timer = null; } }
+      if (source && opts.autoStart !== false) start();
+
+      return {
+        send: function (state) { if (co) co.queue('__snap', state); else emit(state); },
+        flush: function () { if (co) co.flush(); else if (source) emit(source()); },
+        start: start,
+        stop: stop,
+        reset: function () { keyframeState = null; keyframeSeq = 0; seq = 0; sinceKey = 0; },
+      };
+    };
+
+    /**
+     * Receiver for createSnapshotSender. Holds the keyframe baseline + last
+     * applied seq, so it safely drops stale/out-of-order frames and ignores
+     * deltas whose keyframe it missed (until the next keyframe arrives).
+     * @returns {{ receive:(msg:any)=>any, state:any, stats:object, reset:()=>void }}
+     */
+    game.createSnapshotReceiver = function (opts) {
+      opts = opts || {};
+      const dec = opts.decode === true ? decode : (typeof opts.decode === 'function' ? opts.decode : null);
+      let base = null, baseSeq = -1, current = null, appliedSeq = -1, dropped = 0;
+      return {
+        receive: function (msg) {
+          if (dec && (msg instanceof ArrayBuffer || ArrayBuffer.isView(msg))) msg = dec(msg);
+          if (!msg) return current;
+          if (msg.f !== undefined) {
+            if (msg.s !== undefined && msg.s <= appliedSeq) { dropped += 1; return current; }
+            base = msg.f; baseSeq = msg.s !== undefined ? msg.s : 0; current = msg.f; appliedSeq = baseSeq;
+            return current;
+          }
+          if (msg.d !== undefined) {
+            if (msg.b !== undefined && msg.b !== baseSeq) { dropped += 1; return current; } // missed keyframe
+            if (msg.s !== undefined && msg.s <= appliedSeq) { dropped += 1; return current; } // stale/dup
+            current = patch(base, msg.d);
+            if (msg.s !== undefined) appliedSeq = msg.s;
+            return current;
+          }
+          return current;
+        },
+        get state() { return current; },
+        get stats() { return { appliedSeq: appliedSeq, baseSeq: baseSeq, dropped: dropped }; },
+        reset: function () { base = null; baseSeq = -1; current = null; appliedSeq = -1; dropped = 0; },
+      };
+    };
+
+    /**
+     * Declarative state replication (host side). Mutate the plain object you pass
+     * in; the SDK auto-diffs and broadcasts it every tick (sequence-guarded,
+     * delta-compressed, optional quantize/binary). Clients read it with
+     * game.replica(). This is the ~40-lines-into-2 ergonomic.
+     * @returns {{ state:any, flush:()=>void, start:()=>void, stop:()=>void }}
+     */
+    game.replicate = function (obj, opts) {
+      opts = opts || {};
+      let state = obj != null ? obj : {};
+      const sender = this.createSnapshotSender(Object.assign({}, opts, { source: function () { return state; } }));
+      return {
+        get state() { return state; },
+        set state(v) { state = v; },
+        flush: function () { sender.flush(); },
+        start: function () { sender.start(); },
+        stop: function () { sender.stop(); },
+      };
+    };
+
+    /**
+     * Declarative state replication (client side). Receives what a host
+     * replicate()s on the same channel, drops stale/out-of-order frames, and
+     * (optionally) interpolates. Read `.state` for the latest authoritative state,
+     * or `.view()` for smoothed entities when `interpolate` keys are given.
+     * @returns {{ state:any, view:()=>any, onChange:(cb)=>void, stop:()=>void }}
+     */
+    game.replica = function (opts) {
+      opts = opts || {};
+      const channel = opts.channel || 'state';
+      const rx = this.createSnapshotReceiver({ decode: opts.decode });
+      const interp = opts.interpolate ? this.createInterpolation(typeof opts.interpolate === 'object' ? opts.interpolate : {}) : null;
+      const keys = typeof opts.interpolate === 'string' ? opts.interpolate : (opts.keys || (opts.interpolate && opts.interpolate.keys));
+      const group = opts.group || (opts.interpolate && opts.interpolate.group);
+      let onChange = null;
+      const off = this._onChannel(channel, function (data) {
+        const next = rx.receive(data);
+        if (interp && next != null) interp.add(next);
+        if (onChange) onChange(next);
+      });
+      return {
+        get state() { return rx.state; },
+        view: function () { return interp ? interp.calc(keys || 'x y', group) : rx.state; },
+        onChange: function (cb) { onChange = cb; },
+        stop: function () { off(); },
+      };
+    };
+
+    /**
+     * One-line WebRTC peer-to-peer setup (2 peers). Signaling rides the realtime
+     * channel via the router; gameplay then flows directly peer-to-peer over UDP.
+     */
+    game.createMesh = function (opts) {
+      opts = opts || {};
+      const self = this;
+      const channel = opts.signalChannel || 'signal';
+      const mesh = new MeshConnection(Object.assign({}, opts, {
+        sendSignal: function (payload) { self.realtime(channel, payload); },
+      }));
+      this._onChannel(channel, function (payload) { if (payload && payload.type) mesh.handleSignal(payload); });
+      return mesh;
+    };
+
+    /**
+     * N-peer full mesh. Signaling routed per-peer over the realtime channel (each
+     * message carries {to, from}); messages addressed to us are dispatched to the
+     * right peer connection. selfId defaults to the current user id.
+     * @returns {MeshNetwork}
+     */
+    game.createMeshNetwork = function (opts) {
+      opts = opts || {};
+      const self = this;
+      const channel = opts.signalChannel || 'mesh';
+      const selfId = opts.selfId || (Usion.user && Usion.user.getId && Usion.user.getId());
+      const net = new MeshNetwork(Object.assign({}, opts, {
+        selfId: selfId,
+        sendSignal: function (toPeerId, payload) { self.realtime(channel, { to: toPeerId, from: selfId, payload: payload }); },
+      }));
+      this._onChannel(channel, function (ad) { if (ad && ad.to === selfId && ad.from) net.handleSignal(ad.from, ad.payload); });
+      return net;
+    };
+
+    /**
+     * Inject artificial latency / jitter / packet loss locally to test how the
+     * game feels on a bad network (every studio has this). Affects both outbound
+     * realtime sends and inbound realtime dispatch. Call with null/false to turn
+     * it off. No-op safety: realtime must exist on the game module.
+     * @param {{latencyMs?:number,jitterMs?:number,lossPct?:number,dupPct?:number}|null} opts
+     */
+    game.simulateNetwork = function (opts) {
+      const self = this;
+      self._installRealtimeRouter();
+      if (!self._realtimeRaw && typeof self.realtime === 'function') self._realtimeRaw = self.realtime.bind(self);
+      if (!opts) {
+        if (self._realtimeRaw) self.realtime = self._realtimeRaw;
+        self._inboundDispatch = null;
+        if (self._sim) self._sim.flush();
+        self._sim = null;
+        return;
+      }
+      if (!self._sim) self._sim = new NetworkSim(opts);
+      else self._sim.set(opts);
+      if (self._realtimeRaw) self.realtime = self._sim.wrap(self._realtimeRaw);
+      self._inboundDispatch = self._sim.wrap(self._dispatchRealtime);
+      return self._sim;
+    };
+
+    /**
+     * Create a WebTransport (HTTP/3) connection — the lowest-latency client-server
+     * path (UDP-like datagrams, no TCP head-of-line blocking). `url` defaults to
+     * Usion.config.webTransportUrl. Call `connect()`, then `send()` (datagram) /
+     * `sendReliable()`; feed `onMessage` into a snapshot receiver. Direct/standalone
+     * games only (the iframe/WebView proxy relay can't carry datagrams).
+     * @returns {WebTransportConnection}
+     */
+    game.createWebTransport = function (opts) {
+      opts = opts || {};
+      const url = opts.url || (Usion.config && (Usion.config.webTransportUrl || Usion.config.wtUrl));
+      return new WebTransportConnection(Object.assign({}, opts, { url: url }));
+    };
+
+    /**
+     * Measure round-trip time once (single outstanding probe), updating the
+     * rolling estimate (game.getRtt). Direct mode uses the protocol ping/pong;
+     * platform mode uses a lightweight server ack. Resolves to ms, or null if
+     * unavailable (proxy mode, or not connected).
+     * @returns {Promise<number|null>}
+     */
+    game.ping = function () {
+      const self = this;
+      if (!self._pingMeter) self._pingMeter = new PingMeter();
+      if (self._pingInFlight) return self._pingInFlight; // single outstanding probe
+
+      let promise;
+      if (self.directMode) {
+        if (!self.directSocket || self.directSocket.readyState !== 1) return Promise.resolve(null);
+        promise = new Promise(function (resolve) {
+          const id = self._pingMeter.begin();
+          let done = false;
+          const finish = function () { if (done) return; done = true; resolve(self._pingMeter.end(id)); };
+          self._pongWaiters.push(finish);
+          self._sendDirect('ping', { t: Date.now() });
+          setTimeout(function () {
+            if (done) return; done = true;
+            const idx = self._pongWaiters.indexOf(finish);
+            if (idx >= 0) self._pongWaiters.splice(idx, 1);
+            delete self._pingMeter._outstanding[id];
+            resolve(null);
+          }, 3000);
+        });
+      } else if (self.socket && self.connected && !self._useProxy) {
+        promise = new Promise(function (resolve) {
+          const start = Date.now();
+          let done = false;
+          try {
+            self.socket.emit('game:ping', { t: start }, function () { if (done) return; done = true; resolve(self._pingMeter.sample(Date.now() - start)); });
+          } catch (e) { resolve(null); return; }
+          setTimeout(function () { if (done) return; done = true; resolve(null); }, 3000);
+        });
+      } else {
+        return Promise.resolve(null); // proxy mode has no point-to-point ack
+      }
+
+      self._pingInFlight = promise;
+      promise.then(function () { self._pingInFlight = null; }, function () { self._pingInFlight = null; });
+      return promise;
+    };
+
+    /** Latest smoothed round-trip time in ms (null until first ping). */
+    game.getRtt = function () { return this._pingMeter ? this._pingMeter.rtt : null; };
+  }
+
+  /**
+   * Usion SDK Game Core — game module base, connect routing, event registrations
+   */
+
+
+  /**
+   * Create the game module with all sub-modules applied
+   * @param {object} Usion - Reference to the main Usion object
+   */
+  function createGameModule(Usion) {
+    const game = {
+      socket: null,
+      directSocket: null,
+      roomId: null,
+      playerId: null,
+      connected: false,
+      directMode: false,
+      directConfig: null,
+      _directSeq: 0,
+      _eventHandlers: {},
+      _lastSequence: 0,
+      _connecting: false,
+      _connectPromise: null,
+      _joined: false,
+      _joinPromise: null,
+      _useProxy: false,
+      _proxyListenerSetup: false,
+      _heartbeatInterval: null,
+      _pingMeter: null,
+      _pongWaiters: [],
+
+      /**
+       * Connect to the game socket server
+       * @param {string} socketUrl - Socket.IO server URL (optional, uses config)
+       * @param {string} token - JWT auth token (optional, uses user.getToken())
+       * @returns {Promise} Resolves when connected
+       */
+      connect: function(socketUrl, token) {
+        const self = this;
+        var connectionMode = (Usion.config && Usion.config.connectionMode) || 'platform';
+        if (connectionMode === 'direct') {
+          return self.connectDirect();
+        }
+
+        // If already connected (direct or proxy), return immediately
+        if (self._useProxy && self.connected) {
+          return Promise.resolve();
+        }
+        if (self.socket && self.connected) {
+          return Promise.resolve();
+        }
+
+        // If currently connecting, return the existing promise
+        if (self._connecting && self._connectPromise) {
+          return self._connectPromise;
+        }
+
+        // When running inside an iframe or WebView, use parent as socket proxy
+        // (checked BEFORE token validation — iframe games don't need a token)
+        var isInFrame = !!window.__USION_PROXY__
+                     || window.parent !== window
+                     || !!window.ReactNativeWebView
+                     || !!Usion._isEmbedded;
+
+        if (isInFrame) {
+          Usion.log('Running in iframe \u2013 using parent app as socket proxy');
+          return self._connectViaProxy();
+        }
+
+        // Use config values as defaults (only for direct socket connections)
+        socketUrl = socketUrl || Usion.config.socketUrl;
+        token = token || Usion.user.getToken();
+
+        if (!socketUrl) {
+          return Promise.reject(new Error('No socket URL provided'));
+        }
+        if (!token) {
+          return Promise.reject(new Error('No auth token available'));
+        }
+
+        self._connecting = true;
+        self._connectPromise = new Promise(function(resolve, reject) {
+          // Check if socket.io-client is available
+          if (typeof io === 'undefined') {
+            // Load socket.io client
+            var script = document.createElement('script');
+            script.src = '/socket.io.min.js';
+            script.onload = function() {
+              self._initSocket(socketUrl, token, resolve, reject);
+            };
+            script.onerror = function() {
+              // Local file not available, try CDN as fallback
+              var cdnScript = document.createElement('script');
+              cdnScript.src = 'https://cdn.socket.io/4.7.2/socket.io.min.js';
+              cdnScript.onload = function() {
+                self._initSocket(socketUrl, token, resolve, reject);
+              };
+              cdnScript.onerror = function() {
+                self._connecting = false;
+                reject(new Error('Failed to load Socket.IO client'));
+              };
+              document.head.appendChild(cdnScript);
+            };
+            document.head.appendChild(script);
+          } else {
+            self._initSocket(socketUrl, token, resolve, reject);
+          }
+        });
+
+        return self._connectPromise;
+      },
+
+      // Event handler registrations
+      onJoined: function(callback) { this._eventHandlers.joined = callback; },
+      onPlayerJoined: function(callback) { this._eventHandlers.playerJoined = callback; },
+      onPlayerLeft: function(callback) { this._eventHandlers.playerLeft = callback; },
+      onStateUpdate: function(callback) { this._eventHandlers.stateUpdate = callback; },
+      onSync: function(callback) { this._eventHandlers.sync = callback; },
+      onAction: function(callback) { this._eventHandlers.action = callback; },
+      onRealtime: function(callback) { this._eventHandlers.realtime = callback; },
+      onGameFinished: function(callback) { this._eventHandlers.finished = callback; },
+      onGameRestarted: function(callback) { this._eventHandlers.restarted = callback; },
+      onError: function(callback) { this._eventHandlers.error = callback; },
+      onRematchRequest: function(callback) { this._eventHandlers.rematchRequest = callback; },
+      onDisconnect: function(callback) { this._eventHandlers.disconnect = callback; },
+      onReconnect: function(callback) { this._eventHandlers.reconnect = callback; },
+      onConnectionError: function(callback) { this._eventHandlers.connectionError = callback; },
+
+      /**
+       * Register a generic event handler
+       * @param {string} event - Event name
+       * @param {function} callback - Handler function
+       */
+      on: function(event, callback) {
+        if (this.socket) {
+          this.socket.on(event, callback);
+        }
+      }
+    };
+
+    // Apply sub-modules
+    applyGameDirect(game, Usion);
+    applyGameSocket(game, Usion);
+    applyGameProxy(game, Usion);
+    applyGameMethods(game, Usion);
+    applyGameNetcode(game, Usion);
+
+    return game;
+  }
+
+  /**
+   * Usion SDK Lobby — parties, ready-up, and matchmaking.
+   *
+   * The social rendezvous layer that game rooms can't provide: form a party by
+   * code, ready up together, and start as a group — plus a thin wrapper over the
+   * platform's stranger matchmaking. Rides the platform Socket.IO connection
+   * (Usion.game.socket), so connect first with Usion.game.connect().
+   *
+   *   const { code } = await Usion.lobby.create({ maxPlayers: 4 });
+   *   Usion.lobby.onUpdate(({ members }) => renderLobby(members));
+   *   await Usion.lobby.setReady(true);
+   *   // host, once everyone's ready: create a room then start the party in it
+   *   const room = await Usion.lobby.queue(serviceId);     // or your own room API
+   *   await Usion.lobby.start(room.id);
+   *   Usion.lobby.onStarted(({ room_id }) => Usion.game.join(room_id));
+   *
+   * Works in every mode: it rides the unified backend channel (Usion._backendEmit
+   * / _backendOn), which uses the SDK's own socket when standalone and relays
+   * through the parent app when embedded (iframe/WebView).
+   */
+  function createLobbyModule(Usion) {
+    const state = { code: null, host: null, status: null, members: [] };
+    const handlers = {};
+    let bound = false;
+
+    function bind() {
+      if (bound) return;
+      bound = true;
+      Usion._backendOn('lobby:update', function (d) {
+        state.code = d.code; state.host = d.host; state.status = d.status; state.members = d.members || [];
+        if (handlers.update) handlers.update(d);
+      });
+      Usion._backendOn('lobby:started', function (d) {
+        state.status = 'started';
+        if (handlers.started) handlers.started(d);
+      });
+    }
+
+    function ack(event, data) {
+      bind();
+      return Usion._backendEmit(event, data);
+    }
+
+    return {
+      get state() { return state; },
+
+      /** Register a handler for lobby membership/ready changes. */
+      onUpdate: function (cb) { handlers.update = cb; bind(); },
+      /** Register a handler for when the host starts the party. */
+      onStarted: function (cb) { handlers.started = cb; bind(); },
+
+      /** Create a party. Resolves with { code }. You become the host. */
+      create: async function (opts) {
+        opts = opts || {};
+        const r = await ack('lobby:create', { max_players: opts.maxPlayers || 8, public: !!opts.public });
+        if (r && r.code) state.code = r.code;
+        return r;
+      },
+
+      /** Join a party by code. */
+      join: async function (code) {
+        const r = await ack('lobby:join', { code: String(code || '').toUpperCase() });
+        if (r && r.code) state.code = r.code;
+        return r;
+      },
+
+      /** Leave the current party. */
+      leave: function () { state.code = null; return ack('lobby:leave', {}).catch(function () {}); },
+
+      /** Set your ready state. */
+      setReady: function (ready) { return ack('lobby:ready', { ready: ready !== false }); },
+
+      /** True when every member is ready. */
+      allReady: function () { return state.members.length > 0 && state.members.every(function (m) { return m.ready; }); },
+
+      /** Whether the current user is the party host. */
+      isHost: function () {
+        const id = Usion.user && Usion.user.getId && Usion.user.getId();
+        return !!(state.host && id && state.host === id);
+      },
+
+      /** Host: start the party in an already-created game room. */
+      start: function (roomId) { return ack('lobby:start', { room_id: roomId }); },
+
+      /**
+       * Stranger matchmaking — find or create a game room for a service via the
+       * platform's REST matchmaker. Resolves with the room.
+       */
+      queue: async function (serviceId, opts) {
+        opts = opts || {};
+        const apiUrl = (Usion.config && Usion.config.apiUrl) || '';
+        const token = Usion.user && Usion.user.getToken && Usion.user.getToken();
+        if (!apiUrl) throw new Error('No apiUrl configured');
+        const res = await fetch(apiUrl.replace(/\/$/, '') + '/games/matchmake', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer ' + token },
+          body: JSON.stringify({ service_id: serviceId, conversation_id: opts.conversationId || ('standalone_' + serviceId) }),
+        });
+        if (!res.ok) throw new Error('Matchmake failed: HTTP ' + res.status);
+        return res.json();
+      },
+    };
+  }
+
+  /**
+   * Usion SDK Leaderboard — scores for mini-games.
+   *
+   * Opt-in per game (the service must have `leaderboard.enabled`). Rides the
+   * unified backend channel, so it works in standalone AND embedded games.
+   *
+   *   await Usion.leaderboard.submit(1500);              // your score
+   *   const friends = await Usion.leaderboard.friends();  // people you've messaged + you
+   *   const top = await Usion.leaderboard.top();          // global top N
+   *   const me = await Usion.leaderboard.me();            // { score, rank, total }
+   *
+   * The **friends** board is scoped to users you've messaged (your conversations)
+   * plus yourself — that's the "see the scores of people I've chatted with" view.
+   * Entries: { user_id, name, avatar, score, rank, is_me, metadata }.
+   */
+  function createLeaderboardModule(Usion) {
+    function serviceId(opts) {
+      return (opts && opts.serviceId) || (Usion.config && Usion.config.serviceId);
+    }
+
+    return {
+      /** Submit a score (best score is kept, per the service's order config). */
+      submit: function (score, metadata, opts) {
+        return Usion._backendEmit('lb:submit', { service_id: serviceId(opts), score: score, metadata: metadata != null ? metadata : null });
+      },
+
+      /** Leaderboard of people you've messaged (plus you). Returns entries[]. */
+      friends: function (opts) {
+        opts = opts || {};
+        return Usion._backendEmit('lb:friends', { service_id: serviceId(opts), limit: opts.limit || 50 })
+          .then(function (r) { return (r && r.entries) || []; });
+      },
+
+      /** Global top N. Returns entries[]. */
+      top: function (opts) {
+        opts = opts || {};
+        return Usion._backendEmit('lb:top', { service_id: serviceId(opts), limit: opts.limit || 20 })
+          .then(function (r) { return (r && r.entries) || []; });
+      },
+
+      /** Your own score + global rank: { score, rank, total }. */
+      me: function (opts) {
+        return Usion._backendEmit('lb:me', { service_id: serviceId(opts) });
+      },
+    };
+  }
+
+  /**
+   * Usion SDK Matchmaking — pair up with online strangers ("quick match").
+   *
+   * Lets a mini-app connect players who don't know each other: join a queue, and
+   * when enough players are waiting the platform creates a room and matches you.
+   * Rides the unified backend channel, so it works standalone AND embedded.
+   *
+   *   const m = await Usion.matchmaking.find();    // resolves when matched
+   *   await Usion.game.connect(); await Usion.game.join(m.roomId);
+   *   // ...or cancel while waiting:
+   *   Usion.matchmaking.cancel();
+   *   Usion.matchmaking.onMatch(({ roomId, players }) => { ... });
+   */
+  function createMatchmakingModule(Usion) {
+    let pending = null;          // { resolve, reject } for an in-flight find()
+    let onMatchCb = null;
+    let bound = false;
+
+    function normalize(d) {
+      return { roomId: d && d.room_id, players: (d && d.player_ids) || [], serviceId: d && d.service_id };
+    }
+
+    function bind() {
+      if (bound) return;
+      bound = true;
+      Usion._backendOn('mm:matched', function (d) {
+        const r = normalize(d);
+        if (onMatchCb) onMatchCb(r);
+        if (pending) { const p = pending; pending = null; p.resolve(r); }
+      });
+    }
+
+    return {
+      /** Register a handler called whenever a match is found. */
+      onMatch: function (cb) { onMatchCb = cb; bind(); },
+
+      /**
+       * Join the queue for `serviceId` (defaults to the current game) and resolve
+       * when matched with { roomId, players, serviceId }. Stays pending until a
+       * match (use cancel() to stop waiting).
+       */
+      find: function (serviceId, opts) {
+        opts = opts || {};
+        const sid = serviceId || (Usion.config && Usion.config.serviceId);
+        bind();
+        return Usion._backendEmit('mm:join', { service_id: sid, size: opts.size || 2 }).then(function () {
+          return new Promise(function (resolve, reject) {
+            if (pending) pending.reject(new Error('superseded'));
+            pending = { resolve: resolve, reject: reject };
+          });
+        });
+      },
+
+      /** Leave the queue / stop waiting. */
+      cancel: function () {
+        if (pending) { pending.reject(new Error('cancelled')); pending = null; }
+        return Usion._backendEmit('mm:cancel', {});
+      },
+    };
+  }
+
+  /**
+   * Usion SDK — unified backend channel.
+   *
+   * One switchboard for backend request/response + server push that works in
+   * every mode, so features (lobby, matchmaking, presence, …) never reach for a
+   * specific socket:
+   *
+   *   - standalone / platform : uses the SDK's own Socket.IO socket (game.socket)
+   *   - embedded (iframe/WebView): relays through the parent app via postMessage
+   *     (BACKEND_EMIT request → host emits on its authenticated socket; the host
+   *     forwards allow-listed server pushes back as BACKEND_EVENT)
+   *
+   * Security: in embedded mode the host MUST restrict which events it relays to a
+   * safe, namespaced allow-list (e.g. lobby:* / mm:*) so a mini-app can't abuse
+   * the user's authenticated connection. The backend re-validates every call.
+   */
+  function applyBackendChannel(Usion) {
+    Usion._backendHandlers = {};
+    Usion._boundSockets = typeof WeakSet !== 'undefined' ? new WeakSet() : null;
+
+    /**
+     * Bind a Socket.IO socket so any allow-listed server event is routed to the
+     * registered _backendOn handlers (via onAny — robust to registration order).
+     */
+    Usion._bindBackendSocket = function (socket) {
+      if (!socket || typeof socket.onAny !== 'function') return;
+      if (this._boundSockets) {
+        if (this._boundSockets.has(socket)) return;
+        this._boundSockets.add(socket);
+      }
+      const self = this;
+      socket.onAny(function (event, payload) {
+        const h = self._backendHandlers[event];
+        if (h) h(payload);
+      });
+    };
+
+    /** Subscribe to a backend server-push event (works in all modes). */
+    Usion._backendOn = function (event, handler) {
+      this._backendHandlers[event] = handler;
+      const s = this.game && this.game.socket;
+      if (s) {
+        if (typeof s.onAny === 'function') this._bindBackendSocket(s);
+        else if (typeof s.on === 'function') s.on(event, handler); // fallback (tests / minimal sockets)
+      }
+    };
+
+    /**
+     * Emit a backend request and await its ack. Routes to the SDK socket when
+     * standalone, or through the parent host when embedded.
+     * @returns {Promise<any>}
+     */
+    Usion._backendEmit = function (event, data, timeout) {
+      const self = this;
+      timeout = timeout || 8000;
+      const s = self.game && self.game.socket;
+      if (s && s.connected) {
+        return new Promise(function (resolve, reject) {
+          let done = false;
+          const timer = setTimeout(function () { if (done) return; done = true; reject(new Error('Backend request timeout')); }, timeout);
+          try {
+            s.emit(event, data || {}, function (resp) {
+              if (done) return; done = true; clearTimeout(timer);
+              if (resp && resp.error) reject(new Error(resp.message || resp.error));
+              else resolve(resp);
+            });
+          } catch (e) { clearTimeout(timer); reject(e); }
+        });
+      }
+      if (self._isEmbedded) {
+        // Host relays this onto its authenticated socket and replies with the ack.
+        return self._request('BACKEND_EMIT', { event: event, data: data || {} }, timeout);
+      }
+      return Promise.reject(new Error('No backend connection — call Usion.game.connect() first'));
+    };
+  }
+
+  /**
+   * Usion SDK Netcode — public namespace.
+   *
+   * A small, zero-dependency, transport-agnostic toolkit for smooth low-latency
+   * multiplayer. Works across all Usion connection modes (platform / direct /
+   * proxy) and both platforms, computing on top of the existing realtime/action
+   * plumbing — no host or backend changes required to use it.
+   *
+   *   SnapshotInterpolation — smooth rendering; adaptive buffer + capped extrapolation
+   *   Predictor             — client prediction + reconciliation + error smoothing
+   *   Coalescer             — fixed-Hz outbound send batching
+   *   PingMeter             — RTT / jitter telemetry
+   *   MeshConnection        — WebRTC P2P (sequenced, TURN-ready, auto-reconnect)
+   *   MeshNetwork           — N-peer full mesh
+   *   diff / patch / quantize — JSON delta compression (id-keyed arrays)
+   *   encode / decode        — compact binary codec
+   */
+
+  const netcode = {
+    SnapshotInterpolation, Vault, Predictor, Coalescer, PingMeter,
+    MeshConnection, MeshNetwork, WebTransportConnection, NetworkSim, Lockstep, LagCompensator,
+    diff, patch, quantize, encode, decode,
+  };
+
   /**
    * Usion Mini App SDK v2.1
    *
@@ -2022,6 +4548,14 @@ var Usion = (function () {
   Usion.bot = createBotModule(Usion);
   Usion.fileStorage = createFileStorageModule(Usion);
   Usion.game = createGameModule(Usion);
+  // Unified backend channel (used by lobby etc.; works standalone + embedded).
+  applyBackendChannel(Usion);
+  Usion.lobby = createLobbyModule(Usion);
+  Usion.leaderboard = createLeaderboardModule(Usion);
+  Usion.matchmaking = createMatchmakingModule(Usion);
+
+  // Netcode toolkit (transport-agnostic, zero-dependency).
+  Usion.netcode = netcode;
 
   // Attach results methods directly on Usion
   Object.assign(Usion, createResultsMethods(Usion));