@usions/sdk 2.20.2 → 2.22.0

package/src/browser.js

@@ -1,10 +1,130 @@
 var Usion = (function () {
   'use strict';
 
+  /**
+   * Usion SDK Errors — stable, machine-readable error codes.
+   *
+   * Developers should branch on `err.code`, never on message text. Messages
+   * are human-readable and may change; codes are part of the public API and
+   * follow the deprecation policy (never removed within a major version).
+   */
+
+  /** @type {Record<string, string>} */
+  const ERROR_CODES = {
+    NOT_CONNECTED: 'NOT_CONNECTED',           // No live connection for this call
+    NO_ROOM: 'NO_ROOM',                       // No room id provided/known
+    ROOM_NOT_FOUND: 'ROOM_NOT_FOUND',         // Room does not exist server-side
+    NOT_PARTICIPANT: 'NOT_PARTICIPANT',       // Caller is not a player in the room
+    NOT_IN_ROOM: 'NOT_IN_ROOM',               // Socket not in the room — rejoin required
+    NOT_AUTHORITY: 'NOT_AUTHORITY',           // Authority-only call (e.g. lobby start)
+    NOT_AUTHENTICATED: 'NOT_AUTHENTICATED',   // Missing/invalid auth server-side
+    JOIN_TIMEOUT: 'JOIN_TIMEOUT',             // Join did not complete in time
+    CONNECT_TIMEOUT: 'CONNECT_TIMEOUT',       // Connect did not complete in time
+    INIT_TIMEOUT: 'INIT_TIMEOUT',             // init() got no INIT from the host in time
+    MATCH_TIMEOUT: 'MATCH_TIMEOUT',           // matchmaking.find() opts.timeout elapsed
+    STATE_TOO_LARGE: 'STATE_TOO_LARGE',       // setState payload over the quota
+    INVALID_STATE: 'INVALID_STATE',           // setState payload not a JSON object
+    STALE_STATE: 'STALE_STATE',               // setState older than the stored checkpoint
+    INVALID_NEXT_TURN: 'INVALID_NEXT_TURN',   // nextTurn is not a player in the room
+    INVALID_INPUT: 'INVALID_INPUT',           // Missing/malformed argument server-side
+    NOT_FOUND: 'NOT_FOUND',                   // Referenced entity (service, lobby, …) missing
+    QUOTA_EXCEEDED: 'QUOTA_EXCEEDED',         // Bucket key/size quota reached (cloud KV)
+    VALUE_TOO_LARGE: 'VALUE_TOO_LARGE',       // Single value over the per-value quota
+    LOBBY_FULL: 'LOBBY_FULL',                 // Lobby at max_players
+    LOBBY_CLOSED: 'LOBBY_CLOSED',             // Lobby exists but is not open
+    CONFLICT: 'CONFLICT',                     // Concurrent-write conflict; retry
+    RATE_LIMITED: 'RATE_LIMITED',             // Too many calls; back off (see retryAfter)
+    REQUEST_TIMEOUT: 'REQUEST_TIMEOUT',       // Host/parent did not reply in time
+    QUEUE_FULL: 'QUEUE_FULL',                 // Offline action queue at capacity
+    CANCELLED: 'CANCELLED',                   // Cancelled by a local cancel() call
+    SUPERSEDED: 'SUPERSEDED',                 // Replaced by a newer identical request
+    UNSUPPORTED: 'UNSUPPORTED',               // Not available in this transport
+    UNKNOWN: 'UNKNOWN',                       // Unmapped error (see message)
+  };
+
+  class UsionError extends Error {
+    /**
+     * @param {string} code - One of ERROR_CODES
+     * @param {string} [message] - Human-readable detail (may change between versions)
+     */
+    constructor(code, message) {
+      super(message || code);
+      this.name = 'UsionError';
+      this.code = ERROR_CODES[code] ? code : ERROR_CODES.UNKNOWN;
+      /** @type {number|undefined} Seconds until a RATE_LIMITED call may retry. */
+      this.retryAfter = undefined;
+    }
+  }
+
+  // Backend error strings → stable codes. Order matters: first match wins.
+  // Fallback path only: the backend now sends a structured `code` on every
+  // error ack, which toUsionError prefers. These patterns cover old backends
+  // and hosts that strip the code.
+  /** @type {Array<[RegExp, string]>} */
+  const BACKEND_PATTERNS = [
+    [/not authenticated/i, ERROR_CODES.NOT_AUTHENTICATED],
+    [/room_id required|no room id/i, ERROR_CODES.NO_ROOM],
+    [/room not found/i, ERROR_CODES.ROOM_NOT_FOUND],
+    [/not in room/i, ERROR_CODES.NOT_IN_ROOM],
+    [/not a participant/i, ERROR_CODES.NOT_PARTICIPANT],
+    [/room authority/i, ERROR_CODES.NOT_AUTHORITY],
+    [/exceeds .*limit/i, ERROR_CODES.STATE_TOO_LARGE],
+    [/stale checkpoint|stale state/i, ERROR_CODES.STALE_STATE],
+    [/state must be/i, ERROR_CODES.INVALID_STATE],
+    [/next_turn must be/i, ERROR_CODES.INVALID_NEXT_TURN],
+    [/rate limit|too many/i, ERROR_CODES.RATE_LIMITED],
+    [/join timeout/i, ERROR_CODES.JOIN_TIMEOUT],
+    [/connection timeout|connect timeout/i, ERROR_CODES.CONNECT_TIMEOUT],
+    [/request timeout/i, ERROR_CODES.REQUEST_TIMEOUT],
+    [/not connected/i, ERROR_CODES.NOT_CONNECTED],
+    [/quota exceeded/i, ERROR_CODES.QUOTA_EXCEEDED],
+    [/value too large/i, ERROR_CODES.VALUE_TOO_LARGE],
+    [/lobby is full/i, ERROR_CODES.LOBBY_FULL],
+    [/lobby is not open/i, ERROR_CODES.LOBBY_CLOSED],
+    [/not found|unknown service/i, ERROR_CODES.NOT_FOUND],
+    [/conflict/i, ERROR_CODES.CONFLICT],
+    [/cancelled/i, ERROR_CODES.CANCELLED],
+    [/superseded/i, ERROR_CODES.SUPERSEDED],
+  ];
+
+  /**
+   * Normalize anything — a structured backend ack ({ error, code?, retry_after? }),
+   * an Error, or a raw string — into a UsionError with the best stable code.
+   * A machine-readable `code` on the input always wins over message matching.
+   * @param {*} err
+   * @param {string} [fallbackCode] - Code to use when nothing matches
+   * @returns {UsionError}
+   */
+  function toUsionError(err, fallbackCode) {
+    if (err instanceof UsionError) return err;
+
+    // Structured input (backend ack object or an Error carrying a code).
+    if (err && typeof err === 'object') {
+      const code = typeof err.code === 'string' && ERROR_CODES[err.code] ? err.code : null;
+      const message = err.message || err.error;
+      if (code) {
+        const ue = new UsionError(code, typeof message === 'string' ? message : code);
+        const retryAfter = err.retry_after != null ? err.retry_after : err.retryAfter;
+        if (typeof retryAfter === 'number' && isFinite(retryAfter)) ue.retryAfter = retryAfter;
+        return ue;
+      }
+      if (!(err instanceof Error) && typeof message === 'string') err = message;
+    }
+
+    const message = err && err.message ? err.message : String(err || 'Unknown error');
+    for (let i = 0; i < BACKEND_PATTERNS.length; i++) {
+      if (BACKEND_PATTERNS[i][0].test(message)) {
+        return new UsionError(BACKEND_PATTERNS[i][1], message);
+      }
+    }
+    return new UsionError(fallbackCode || ERROR_CODES.UNKNOWN, message);
+  }
+
   /**
    * Usion SDK Core — init, _post, _request, message handling
    */
 
+
   // Request ID counter for tracking async responses
   let _requestId = 0;
   const _pendingRequests = {};
@@ -69,7 +189,7 @@ var Usion = (function () {
    * Core Usion object with init, _post, _request
    */
   const core = {
-    version: '2.20.2', // injected from package.json at build
+    version: '2.22.0', // injected from package.json at build
     config: {},
     _initialized: false,
     _initCallback: null,
@@ -78,24 +198,60 @@ var Usion = (function () {
     _backButtonCallback: null,
 
     /**
-     * Initialize the SDK with config from parent app
-     * @param {function} callback - Called with config when ready
+     * Initialize the SDK with config from parent app.
+     *
+     * Callback form (unchanged): `Usion.init(cb)` — cb(config) fires when the
+     * host's INIT arrives. Promise form: every call ALSO returns a
+     * Promise<config>, so `const config = await Usion.init()` works.
+     *
+     * `opts.timeout` (ms, optional) rejects the promise with
+     * UsionError(INIT_TIMEOUT) if no INIT arrives in time — the "embedded but
+     * host silent" case that otherwise hangs forever. The callback still fires
+     * if INIT arrives late. Both `init(cb, opts)` and `init(opts)` are accepted.
+     *
+     * @param {function|{timeout?: number}} [callback] - Called with config when ready
+     * @param {{timeout?: number}} [opts]
+     * @returns {Promise<object>} Resolves with config
      */
-    init: function(callback) {
+    init: function(callback, opts) {
       const self = this;
+      if (callback && typeof callback === 'object') {
+        opts = callback;
+        callback = null;
+      }
+      opts = opts || {};
 
       // Prevent double initialization - just update callback
       if (self._initialized) {
         if (callback) callback(self.config);
-        return;
+        return Promise.resolve(self.config);
       }
 
       // Store callback for when config arrives
-      self._initCallback = callback;
+      if (callback) self._initCallback = callback;
+
+      // One shared promise for every init() call before INIT arrives.
+      if (!self._initPromise) {
+        self._initPromise = new Promise(function(resolve, reject) {
+          self._initResolve = resolve;
+          self._initReject = reject;
+        });
+        // Callback-style users never touch the promise — don't let an
+        // INIT_TIMEOUT rejection surface as an unhandled-rejection error.
+        self._initPromise.catch(function() {});
+      }
+      if (opts.timeout > 0 && !self._initTimer) {
+        self._initTimer = setTimeout(function() {
+          self._initTimer = null;
+          if (self._initialized || !self._initReject) return;
+          self._initReject(new UsionError(ERROR_CODES.INIT_TIMEOUT,
+            'No INIT from host within ' + opts.timeout + 'ms — host silent or running standalone'));
+        }, opts.timeout);
+      }
 
       // Only register message handler once
       if (self._messageHandlerRegistered) {
-        return;
+        return self._initPromise;
       }
       self._messageHandlerRegistered = true;
 
@@ -151,6 +307,15 @@ var Usion = (function () {
           if (self._initCallback) {
             self._initCallback(data.config);
           }
+
+          // Settle the promise form
+          if (self._initTimer) {
+            clearTimeout(self._initTimer);
+            self._initTimer = null;
+          }
+          if (self._initResolve) {
+            self._initResolve(data.config);
+          }
         }
 
         // Handle response messages for async requests
@@ -159,7 +324,9 @@ var Usion = (function () {
           delete _pendingRequests[data._requestId];
 
           if (data.error) {
-            reject(new Error(data.error));
+            // Preserve the backend's stable code/retry_after when the host
+            // relayed them (see errors.js).
+            reject(toUsionError(data));
           } else {
             resolve(data);
           }
@@ -218,6 +385,8 @@ var Usion = (function () {
 
       // Signal ready to parent
       this._post({ type: 'READY' });
+
+      return self._initPromise;
     },
 
     /**
@@ -339,7 +508,7 @@ var Usion = (function () {
         // Setup timeout
         const timer = setTimeout(function() {
           delete _pendingRequests[requestId];
-          reject(new Error('Request timeout'));
+          reject(new UsionError(ERROR_CODES.REQUEST_TIMEOUT, 'Request timeout'));
         }, timeout);
 
         // Store pending request
@@ -513,13 +682,17 @@ var Usion = (function () {
 
       /**
        * Get current wallet balance
+       * @param {object} [opts]
+       * @param {boolean} [opts.fresh] - Bypass the cache and re-query the host.
+       *   Use after out-of-band balance changes (e.g. a server-side settle).
        * @returns {Promise<number>} Balance in credits
        */
-      getBalance: function() {
+      getBalance: function(opts) {
         const self = this;
+        const fresh = !!(opts && opts.fresh);
 
         // If we have cached balance, return it
-        if (self._balance !== null) {
+        if (!fresh && self._balance !== null) {
           return Promise.resolve(self._balance);
         }
 
@@ -586,11 +759,14 @@ var Usion = (function () {
             settled = true;
             cleanup();
             // Update cached balance from the authoritative new balance, else
-            // best-effort subtract (no-op if balance is unknown).
+            // best-effort subtract now and re-query the host so the cache
+            // converges on the real value (an estimate would otherwise stick
+            // until reload).
             if (response && response.newBalance !== undefined) {
               self._balance = response.newBalance;
-            } else if (self._balance !== null) {
-              self._balance -= amount;
+            } else {
+              if (self._balance !== null) self._balance -= amount;
+              self.getBalance({ fresh: true }).catch(function() { /* keep estimate */ });
             }
             resolve(response);
           }
@@ -1191,9 +1367,10 @@ var Usion = (function () {
      * Listen for messages from parent app
      * @param {string} type - Message type to listen for
      * @param {function} callback - Handler function
+     * @returns {function} Unsubscribe function
      */
     on: function(type, callback) {
-      window.addEventListener('message', function(event) {
+      function listener(event) {
         if (!isTrustedMessageSource(event)) return;
 
         let data;
@@ -1206,7 +1383,11 @@ var Usion = (function () {
         if (data.type === type) {
           callback(data);
         }
-      });
+      }
+      window.addEventListener('message', listener);
+      return function() {
+        window.removeEventListener('message', listener);
+      };
     }
   };
 
@@ -1564,7 +1745,20 @@ var Usion = (function () {
         // backend channel — robust to listener registration order.
         if (Usion._bindBackendSocket) Usion._bindBackendSocket(self.socket);
 
+        // Socket.IO v4 emits 'reconnect' on the Manager, not the Socket — a
+        // Socket-level 'reconnect' listener never fires. Track attempts on the
+        // Manager and treat any connect after the first (per socket) as the
+        // reconnect signal, dispatched below AFTER rejoin gating is in place.
+        var hadConnect = false;
+        if (self.socket.io && typeof self.socket.io.on === 'function') {
+          self.socket.io.on('reconnect_attempt', function(n) {
+            self._reconnAttempts = n;
+          });
+        }
+
         self.socket.on('connect', function() {
+          var isReconnect = hadConnect;
+          hadConnect = true;
           self.connected = true;
           self._connecting = false;
           Usion.log('Game socket connected');
@@ -1595,12 +1789,21 @@ var Usion = (function () {
               .then(function() {
                 self._rejoinPromise = null;
                 // Send any moves queued while offline, now that membership
-                // and sync are restored. (Socket.IO v4 emits 'reconnect' on
-                // the Manager, not the Socket, so this is the reliable hook.)
+                // and sync are restored. (This connect handler is the reliable
+                // hook — see the Manager-vs-Socket note above.)
                 if (self._flushOfflineQueue) self._flushOfflineQueue();
               });
           }
 
+          // Dispatched after _rejoinPromise is set, so anything reacting to
+          // 'reconnect' (offline-queue flush, connection-state machine) sees
+          // sends gated behind the rejoin+resync.
+          if (isReconnect) {
+            Usion.log('Game socket reconnected');
+            self._dispatch('reconnect', self._reconnAttempts || 1);
+            self._reconnAttempts = 0;
+          }
+
           resolve();
         });
 
@@ -1623,11 +1826,6 @@ var Usion = (function () {
           self._dispatch('disconnect', reason);
         });
 
-        self.socket.on('reconnect', function(attemptNumber) {
-          Usion.log('Game socket reconnected after ' + attemptNumber + ' attempts');
-          self._dispatch('reconnect', attemptNumber);
-        });
-
         // Game event handlers
         self.socket.on('game:joined', function(data) {
           if (data.sequence !== undefined) {
@@ -1714,82 +1912,6 @@ var Usion = (function () {
     };
   }
 
-  /**
-   * Usion SDK Errors — stable, machine-readable error codes.
-   *
-   * Developers should branch on `err.code`, never on message text. Messages
-   * are human-readable and may change; codes are part of the public API and
-   * follow the deprecation policy (never removed within a major version).
-   */
-
-  /** @type {Record<string, string>} */
-  const ERROR_CODES = {
-    NOT_CONNECTED: 'NOT_CONNECTED',           // No live connection for this call
-    NO_ROOM: 'NO_ROOM',                       // No room id provided/known
-    ROOM_NOT_FOUND: 'ROOM_NOT_FOUND',         // Room does not exist server-side
-    NOT_PARTICIPANT: 'NOT_PARTICIPANT',       // Caller is not a player in the room
-    NOT_AUTHORITY: 'NOT_AUTHORITY',           // Authority-only call (e.g. setState)
-    NOT_AUTHENTICATED: 'NOT_AUTHENTICATED',   // Missing/invalid auth server-side
-    JOIN_TIMEOUT: 'JOIN_TIMEOUT',             // Join did not complete in time
-    CONNECT_TIMEOUT: 'CONNECT_TIMEOUT',       // Connect did not complete in time
-    STATE_TOO_LARGE: 'STATE_TOO_LARGE',       // setState payload over the quota
-    INVALID_STATE: 'INVALID_STATE',           // setState payload not a JSON object
-    INVALID_NEXT_TURN: 'INVALID_NEXT_TURN',   // nextTurn is not a player in the room
-    RATE_LIMITED: 'RATE_LIMITED',             // Too many calls; back off
-    REQUEST_TIMEOUT: 'REQUEST_TIMEOUT',       // Host/parent did not reply in time
-    QUEUE_FULL: 'QUEUE_FULL',                 // Offline action queue at capacity
-    UNSUPPORTED: 'UNSUPPORTED',               // Not available in this transport
-    UNKNOWN: 'UNKNOWN',                       // Unmapped error (see message)
-  };
-
-  class UsionError extends Error {
-    /**
-     * @param {string} code - One of ERROR_CODES
-     * @param {string} [message] - Human-readable detail (may change between versions)
-     */
-    constructor(code, message) {
-      super(message || code);
-      this.name = 'UsionError';
-      this.code = ERROR_CODES[code] ? code : ERROR_CODES.UNKNOWN;
-    }
-  }
-
-  // Backend error strings → stable codes. Order matters: first match wins.
-  /** @type {Array<[RegExp, string]>} */
-  const BACKEND_PATTERNS = [
-    [/not authenticated/i, ERROR_CODES.NOT_AUTHENTICATED],
-    [/room_id required|no room id/i, ERROR_CODES.NO_ROOM],
-    [/room not found/i, ERROR_CODES.ROOM_NOT_FOUND],
-    [/not a participant/i, ERROR_CODES.NOT_PARTICIPANT],
-    [/room authority/i, ERROR_CODES.NOT_AUTHORITY],
-    [/exceeds .*limit/i, ERROR_CODES.STATE_TOO_LARGE],
-    [/state must be/i, ERROR_CODES.INVALID_STATE],
-    [/next_turn must be/i, ERROR_CODES.INVALID_NEXT_TURN],
-    [/rate limit|too many/i, ERROR_CODES.RATE_LIMITED],
-    [/join timeout/i, ERROR_CODES.JOIN_TIMEOUT],
-    [/connection timeout|connect timeout/i, ERROR_CODES.CONNECT_TIMEOUT],
-    [/request timeout/i, ERROR_CODES.REQUEST_TIMEOUT],
-    [/not connected/i, ERROR_CODES.NOT_CONNECTED],
-  ];
-
-  /**
-   * Normalize anything (backend `{error}` string, Error, raw string) into a
-   * UsionError with the best-matching stable code.
-   * @param {*} err
-   * @param {string} [fallbackCode] - Code to use when nothing matches
-   * @returns {UsionError}
-   */
-  function toUsionError(err, fallbackCode) {
-    if (err instanceof UsionError) return err;
-    const message = err && err.message ? err.message : String(err || 'Unknown error');
-    for (let i = 0; i < BACKEND_PATTERNS.length; i++) {
-      if (BACKEND_PATTERNS[i][0].test(message)) {
-        return new UsionError(BACKEND_PATTERNS[i][1], message);
-      }
-    }
-    return new UsionError(fallbackCode || ERROR_CODES.UNKNOWN, message);
-  }
-
   /**
    * Usion SDK Game Proxy — postMessage relay through parent app
    */
@@ -2038,12 +2160,20 @@ var Usion = (function () {
         self.socket.emit('game:join', { room_id: roomId }, function(response) {
           if (response.error) {
             self._joined = false;
-            reject(toUsionError(response.message || response.error));
+            reject(toUsionError(response));
           } else {
             self._joined = true;
             if (response.sequence !== undefined) {
               self._lastSequence = response.sequence;
+              // The joined state reflects everything up to this sequence —
+              // actions at or below it must not be re-delivered (same
+              // baseline the proxy transport sets from GAME_JOINED).
+              self._lastActionApplied = Math.max(self._lastActionApplied, response.sequence);
             }
+            // Transport parity: proxy and direct modes dispatch 'joined';
+            // the socket transport now does too, so onJoined / recovery
+            // logic behaves the same everywhere.
+            self._dispatch('joined', response);
             resolve(response);
           }
         });
@@ -2133,36 +2263,81 @@ var Usion = (function () {
       // move can't go out before the client has resynced.
       const gate = self._rejoinPromise || Promise.resolve();
       return gate.then(function() {
-        return new Promise(function(resolve, reject) {
-          if (!self.socket || !self.connected) {
-            if (queueOffline) {
-              self._queueOfflineAction(actionType, actionData, opts).then(resolve, reject);
-              return;
-            }
-            reject(new UsionError(ERROR_CODES.NOT_CONNECTED, 'Not connected'));
-            return;
+        if (!self.socket || !self.connected) {
+          if (queueOffline) {
+            return self._queueOfflineAction(actionType, actionData, opts);
           }
+          throw new UsionError(ERROR_CODES.NOT_CONNECTED, 'Not connected');
+        }
+        const payload = {
+          room_id: self.roomId,
+          action_type: actionType,
+          action_data: actionData
+        };
+        if (nextTurn) payload.next_turn = nextTurn;
+        return self._emitAction(payload, true);
+      });
+    };
 
-          const payload = {
-            room_id: self.roomId,
-            action_type: actionType,
-            action_data: actionData
-          };
-          if (nextTurn) payload.next_turn = nextTurn;
-          self.socket.emit('game:action', payload, function(response) {
-            if (response.error) {
-              reject(toUsionError(response.message || response.error));
-            } else {
-              if (response.sequence !== undefined) {
-                self._lastSequence = response.sequence;
-              }
-              resolve(response);
+    /**
+     * @private Emit game:action and handle the ack. On NOT_IN_ROOM (the server
+     * detected a detached socket — connected but no room membership), auto-
+     * rejoin + resync once and retry the same action, so a move made in the
+     * detached window is delivered instead of silently lost.
+     */
+    game._emitAction = function(payload, retryOnNotInRoom) {
+      const self = this;
+      return new Promise(function(resolve, reject) {
+        if (!self.socket || !self.connected) {
+          reject(new UsionError(ERROR_CODES.NOT_CONNECTED, 'Not connected'));
+          return;
+        }
+        self.socket.emit('game:action', payload, function(response) {
+          if (response && response.error) {
+            const ue = toUsionError(response);
+            if (retryOnNotInRoom && ue.code === ERROR_CODES.NOT_IN_ROOM) {
+              self._autoRejoin()
+                .then(function() { return self._emitAction(payload, false); })
+                .then(resolve, reject);
+              return;
             }
-          });
+            reject(ue);
+          } else {
+            if (response && response.sequence !== undefined) {
+              self._lastSequence = response.sequence;
+            }
+            resolve(response);
+          }
         });
       });
     };
 
+    /**
+     * @private Recover a detached socket: the server said we're not in the
+     * Socket.IO room (NOT_IN_ROOM), so rejoin + resync exactly like the
+     * post-reconnect path, gating action() sends on _rejoinPromise meanwhile.
+     */
+    game._autoRejoin = function() {
+      const self = this;
+      if (self._rejoinPromise) return self._rejoinPromise;
+      if (!self.roomId || !self.socket || !self.connected) return Promise.resolve();
+      Usion.log('Server reports socket not in room - auto-rejoining ' + self.roomId);
+      self._joined = false;
+      self._joinPromise = null;
+      self._rejoinPromise = self.join(self.roomId)
+        .then(function() {
+          self.requestSync(self._lastSequence || 0);
+        })
+        .catch(function(err) {
+          Usion.log('Auto-rejoin failed: ' + (err && err.message ? err.message : String(err)));
+        })
+        .then(function() {
+          self._rejoinPromise = null;
+          if (self._flushOfflineQueue) self._flushOfflineQueue();
+        });
+      return self._rejoinPromise;
+    };
+
     // ── Offline action queue (opt-in via action(..., { queueOffline: true })) ──
 
     const OFFLINE_QUEUE_MAX = 20;
@@ -2237,11 +2412,17 @@ var Usion = (function () {
         return Promise.resolve({ success: false, error: 'not_supported_in_direct_mode', code: ERROR_CODES.UNSUPPORTED });
       }
 
+      // The checkpoint carries the action sequence this state reflects. The
+      // server persists it and rejects OLDER checkpoints (STALE_STATE), so two
+      // concurrent writers can't clobber newer state with older.
+      const checkpointSeq = self._lastSequence || 0;
+
       if (self._useProxy) {
-        return Usion._request('GAME_SET_STATE', { room_id: self.roomId, state: state || {} })
+        return Usion._request('GAME_SET_STATE', { room_id: self.roomId, state: state || {}, sequence: checkpointSeq })
           .then(function(res) {
             if (res && res.error) {
-              return { success: false, error: res.error, code: toUsionError(res.error).code };
+              const rue = toUsionError(res);
+              return { success: false, error: rue.message, code: rue.code };
             }
             return res || { success: true };
           })
@@ -2258,10 +2439,12 @@ var Usion = (function () {
         }
         self.socket.emit('game:set_state', {
           room_id: self.roomId,
-          state: state || {}
+          state: state || {},
+          sequence: checkpointSeq
         }, function(response) {
           if (response && response.error) {
-            resolve({ success: false, error: response.error, code: toUsionError(response.error).code });
+            const ue = toUsionError(response);
+            resolve({ success: false, error: ue.message, code: ue.code });
           } else {
             resolve(response || { success: true });
           }
@@ -2294,10 +2477,18 @@ var Usion = (function () {
         return;
       }
 
+      // Still fire-and-forget for the game, but the server now acks failures
+      // (previously dropped silently): surface them via onError, and on
+      // NOT_IN_ROOM (detached socket) auto-rejoin so the stream recovers.
       self.socket.emit('game:realtime', {
         room_id: self.roomId,
         action_type: actionType,
         action_data: actionData
+      }, function(response) {
+        if (!response || !response.error) return;
+        const ue = toUsionError(response);
+        self._dispatch('error', { code: ue.code, message: ue.message, source: 'realtime' });
+        if (ue.code === ERROR_CODES.NOT_IN_ROOM) self._autoRejoin();
       });
     };
 
@@ -2373,7 +2564,7 @@ var Usion = (function () {
 
         self.socket.emit('game:forfeit', { room_id: self.roomId }, function(response) {
           if (response.error) {
-            reject(toUsionError(response.message || response.error));
+            reject(toUsionError(response));
           } else {
             resolve(response);
           }
@@ -4615,6 +4806,285 @@ var Usion = (function () {
     game.getRtt = function () { return this._pingMeter ? this._pingMeter.rtt : null; };
   }
 
+  /**
+   * Usion SDK Game Reliability — the reconnection-lifecycle surface promised in
+   * v2.16: sequence getters, the unified connection-state machine, and
+   * syncedState (reconnect-safe authoritative shared state).
+   *
+   * Everything here rides the events the game module already dispatches
+   * ('disconnect' / 'reconnect' / 'joined' / 'sync' / 'action'), so it behaves
+   * identically across the socket, embedded-proxy, and direct transports.
+   */
+
+  function applyGameReliability(game, Usion) {
+    // ── Sequence getters ──────────────────────────────────────────────────────
+
+    /** Highest action sequence seen (from joins, syncs, and live actions). */
+    game.getLastSequence = function () { return this._lastSequence || 0; };
+
+    /** Highest action sequence applied locally; trails while catching up. */
+    game.getLastAppliedSequence = function () { return this._lastActionApplied || 0; };
+
+    // ── Connection-state machine ──────────────────────────────────────────────
+    // connected → disconnected → rejoining → reconnected → connected.
+    // 'reconnected' is a transient notification state: observers see it, then
+    // the machine settles back to 'connected' in the same tick.
+
+    game._connState = 'disconnected';
+    game._awaitResync = false;
+
+    game._setConnState = function (state) {
+      if (this._connState === state) return;
+      this._connState = state;
+      this._dispatch('connectionState', state);
+    };
+
+    /** Current connection state, synchronously. */
+    game.getConnectionState = function () { return this._connState; };
+
+    /**
+     * Observe connection-state transitions — one hook to drive a
+     * "Reconnecting…" overlay and gate input, identical on every transport.
+     * Single handler (last wins); returns an unsubscribe fn. For multiple
+     * listeners use game.on('connectionState', cb).
+     */
+    game.onConnectionState = function (callback) { return this._setHandler('connectionState', callback); };
+
+    /**
+     * Fires once per reconnect, after the resync completes, with
+     * { state, lastSequence, viaSync }. Restore local state here — it does NOT
+     * fire for a manually-requested sync.
+     */
+    game.onReconnected = function (callback) { return this._setHandler('reconnected', callback); };
+
+    game.on('disconnect', function () {
+      game._awaitResync = false;
+      game._setConnState('disconnected');
+    });
+
+    game.on('reconnect', function () {
+      if (game.roomId) {
+        game._awaitResync = true;
+        game._setConnState('rejoining');
+      } else {
+        game._setConnState('connected');
+      }
+    });
+
+    game.on('sync', function (data) {
+      if (!game._awaitResync) return;
+      game._awaitResync = false;
+      game._dispatch('reconnected', {
+        state: (data && data.game_state) || null,
+        lastSequence: game._lastSequence || 0,
+        viaSync: true,
+      });
+      game._setConnState('reconnected');
+      game._setConnState('connected');
+    });
+
+    // Transport-level connects (initial connect in every mode) resolve through
+    // connect()/connectDirect() — reflect them in the state machine.
+    function wrapConnect(name) {
+      var orig = game[name];
+      if (typeof orig !== 'function') return;
+      game[name] = function () {
+        var self = this;
+        return orig.apply(self, arguments).then(function (result) {
+          if (!self._awaitResync) self._setConnState('connected');
+          return result;
+        });
+      };
+    }
+    wrapConnect('connect');
+    wrapConnect('connectDirect');
+
+    // ── Host tracking ─────────────────────────────────────────────────────────
+    // Kept on the game module (registered at module creation, so it never
+    // misses an event) — a syncedState created AFTER the join still knows who
+    // the authority is.
+
+    game._hostId = null;
+    function trackHost(d) {
+      if (!d) return;
+      if (d.host_id) game._hostId = d.host_id;
+      else if (d.player_ids && d.player_ids.length) game._hostId = d.player_ids[0];
+    }
+    game.on('joined', trackHost);
+    game.on('playerJoined', trackHost);
+
+    // ── syncedState ───────────────────────────────────────────────────────────
+
+    /**
+     * Reconnect-safe authoritative shared state. Commits are sequenced actions
+     * applied through `reduce` on every client in the same order (deduped by
+     * sequence); the authority (player_ids[0] by default) auto-checkpoints via
+     * setState, and (re)joining clients recover automatically (checkpoint +
+     * un-checkpointed tail). Degrades to local-apply in direct mode.
+     * Full contract: SyncedStateOptions / SyncedState in types/index.d.ts.
+     */
+    game.syncedState = function (initial, opts) {
+      opts = opts || {};
+      var self = this;
+      var reduce = typeof opts.reduce === 'function'
+        ? opts.reduce
+        : function (state, action) { return Object.assign({}, state, action.data); };
+      var checkpointEvery = opts.checkpointEvery != null ? opts.checkpointEvery : 1;
+      var authorityMode = opts.authority === 'all' ? 'all' : 'host';
+      var defaultType = opts.type || 'update';
+
+      var state = initial === undefined ? {} : initial;
+      var appliedSeq = 0;
+      var sinceCheckpoint = 0;
+      var lastGapRequest = -1;
+      var changeCbs = [];
+      var offs = [];
+
+      function notify(reason) {
+        var copy = changeCbs.slice();
+        for (var i = 0; i < copy.length; i++) {
+          try { copy[i](state, reason); } catch (e) { Usion.log('syncedState onChange error: ' + e.message); }
+        }
+      }
+
+      function isAuthority() {
+        if (authorityMode === 'all') return true;
+        var me = self.playerId || (Usion.user && Usion.user.getId && Usion.user.getId());
+        return !!(me && self._hostId && me === self._hostId);
+      }
+
+      function doCheckpoint() {
+        if (self.directMode) {
+          return Promise.resolve({ success: false, error: 'not_supported_in_direct_mode' });
+        }
+        // The wrapper carries the sequence the checkpoint reflects, so recovery
+        // knows exactly where the un-checkpointed tail starts.
+        return self.setState({ __usionSyncedState: 1, seq: appliedSeq, state: state });
+      }
+
+      function maybeAutoCheckpoint() {
+        if (!(checkpointEvery > 0) || !isAuthority()) return;
+        sinceCheckpoint += 1;
+        if (sinceCheckpoint >= checkpointEvery) {
+          sinceCheckpoint = 0;
+          doCheckpoint();
+        }
+      }
+
+      function applyOne(playerId, type, data, sequence) {
+        if (sequence !== undefined && sequence <= appliedSeq) return false; // dedupe
+        var next;
+        try {
+          next = reduce(state, { playerId: playerId, type: type, data: data, sequence: sequence });
+        } catch (e) {
+          Usion.log('syncedState reduce error: ' + e.message);
+          return false;
+        }
+        if (next !== undefined) state = next;
+        if (sequence !== undefined) appliedSeq = sequence;
+        return true;
+      }
+
+      function onAction(d) {
+        if (!d) return;
+        if (applyOne(d.player_id, d.action_type, d.action_data, d.sequence)) {
+          notify('action');
+          maybeAutoCheckpoint();
+        }
+      }
+
+      // Recover from a join ack or sync payload: load the checkpoint (if it is
+      // ours and newer), replay the action tail in order, and if the server's
+      // sequence is still ahead of us, ask once for the missing range.
+      function recover(d) {
+        if (!d) return;
+        var changed = false;
+
+        var gs = d.game_state;
+        if (gs && gs.__usionSyncedState && typeof gs.seq === 'number'
+            && gs.seq >= appliedSeq && gs.state !== undefined) {
+          state = gs.state;
+          appliedSeq = gs.seq;
+          changed = true;
+        }
+
+        var actions = d.actions;
+        if (actions && actions.length) {
+          var sorted = actions.slice().sort(function (a, b) {
+            return (a.sequence || 0) - (b.sequence || 0);
+          });
+          for (var i = 0; i < sorted.length; i++) {
+            var item = sorted[i];
+            if (item && applyOne(item.player_id, item.action_type, item.action_data, item.sequence)) {
+              changed = true;
+            }
+          }
+        }
+
+        if (changed) notify('recover');
+
+        // Gap fill: the checkpoint may lag the room sequence (checkpointEvery>1).
+        // Request the tail from OUR applied sequence — once per position, so a
+        // trimmed history can't loop us.
+        if (d.sequence !== undefined && d.sequence > appliedSeq && lastGapRequest !== appliedSeq) {
+          lastGapRequest = appliedSeq;
+          try { self.requestSync(appliedSeq); } catch (e) { /* non-fatal */ }
+        }
+      }
+
+      offs.push(self.on('action', onAction));
+      offs.push(self.on('sync', recover));
+      offs.push(self.on('joined', recover));
+
+      return {
+        /** Current state value. */
+        get: function () { return state; },
+
+        /**
+         * Commit a change: commit(data) with the default action type, or
+         * commit(type, data, opts) to name it (opts forwarded to game.action,
+         * e.g. nextTurn / queueOffline). Applied exactly once via the echo.
+         */
+        commit: function (typeOrData, data, actionOpts) {
+          var t, payload, o;
+          if (typeof typeOrData === 'string') { t = typeOrData; payload = data; o = actionOpts; }
+          else { t = defaultType; payload = typeOrData; o = data; }
+          if (self.directMode) {
+            // No platform echo in direct mode — apply locally, then send.
+            if (applyOne(self.playerId, t, payload, undefined)) notify('action');
+            return self.action(t, payload, o);
+          }
+          return self.action(t, payload, o);
+        },
+
+        /** Subscribe to changes: cb(state, reason). Returns an unsubscribe fn. */
+        onChange: function (cb) {
+          changeCbs.push(cb);
+          return function () {
+            var i = changeCbs.indexOf(cb);
+            if (i >= 0) changeCbs.splice(i, 1);
+          };
+        },
+
+        /** Whether this client is the checkpointing authority. */
+        isAuthority: isAuthority,
+
+        /** Force a server checkpoint now (no-op result in direct mode). */
+        checkpoint: function () { return doCheckpoint(); },
+
+        /** Sequence of the last action applied into this state. */
+        getSequence: function () { return appliedSeq; },
+
+        /** Detach all listeners; the instance stops receiving updates. */
+        destroy: function () {
+          for (var i = 0; i < offs.length; i++) { try { offs[i](); } catch (e) { /* noop */ } }
+          offs.length = 0;
+          changeCbs.length = 0;
+        },
+      };
+    };
+  }
+
   /**
    * Usion SDK Game Core — game module base, connect routing, event registrations
    */
@@ -4640,6 +5110,8 @@ var Usion = (function () {
     reconnect: 'reconnect',
     connection_error: 'connectionError',
     room_assigned: 'roomAssigned',
+    connection_state: 'connectionState',
+    reconnected: 'reconnected',
   };
 
   function _normalizeEventName(event) {
@@ -4735,26 +5207,31 @@ var Usion = (function () {
         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() {
+            // Load the Socket.IO client: same-origin copy first, then the
+            // platform-hosted copy (same origin as the SDK itself — reachable
+            // wherever the app is), and only then the public CDN, which
+            // restricted networks often block.
+            var sources = [
+              '/socket.io.min.js',
+              'https://usions.com/socket.io.min.js',
+              'https://cdn.socket.io/4.7.2/socket.io.min.js'
+            ];
+            (function tryLoad(i) {
+              if (i >= sources.length) {
                 self._connecting = false;
                 reject(new Error('Failed to load Socket.IO client'));
+                return;
+              }
+              var script = document.createElement('script');
+              script.src = sources[i];
+              script.onload = function() {
+                self._initSocket(socketUrl, token, resolve, reject);
               };
-              document.head.appendChild(cdnScript);
-            };
-            document.head.appendChild(script);
+              script.onerror = function() {
+                tryLoad(i + 1);
+              };
+              document.head.appendChild(script);
+            })(0);
           } else {
             self._initSocket(socketUrl, token, resolve, reject);
           }
@@ -4853,6 +5330,8 @@ var Usion = (function () {
     applyGameProxy(game, Usion);
     applyGameMethods(game, Usion);
     applyGameNetcode(game, Usion);
+    // Applied last: wraps connect/connectDirect and rides dispatched events.
+    applyGameReliability(game, Usion);
 
     // Foreground catch-up safety net (generic across every transport).
     //
@@ -5103,12 +5582,14 @@ var Usion = (function () {
    *
    *   const m = await Usion.matchmaking.find();    // resolves when matched
    *   await Usion.game.connect(); await Usion.game.join(m.roomId);
-   *   // ...or cancel while waiting:
+   *   // ...or bound the wait / cancel while waiting:
+   *   const m2 = await Usion.matchmaking.find(null, { timeout: 30000 });
    *   Usion.matchmaking.cancel();
    *   Usion.matchmaking.onMatch(({ roomId, players }) => { ... });
    */
+
   function createMatchmakingModule(Usion) {
-    let pending = null;          // { resolve, reject } for an in-flight find()
+    let pending = null;          // active find() entry: { resolve, reject }
     let onMatchCb = null;
     let bound = false;
 
@@ -5132,24 +5613,64 @@ var Usion = (function () {
 
       /**
        * 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).
+       * when matched with { roomId, players, serviceId }. Without `opts.timeout`
+       * it stays pending until a match (use cancel() to stop waiting); with it,
+       * rejects MATCH_TIMEOUT (and leaves the queue) once the wait elapses.
+       * @param {string} [serviceId]
+       * @param {{size?: number, timeout?: number}} [opts]
        */
       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 };
-          });
+
+        if (pending) {
+          const old = pending; pending = null;
+          old.reject(new UsionError(ERROR_CODES.SUPERSEDED, 'Superseded by a newer find()'));
+        }
+
+        let timer = null;
+        const entry = {};
+        const promise = new Promise(function (resolve, reject) {
+          entry.resolve = function (r) {
+            if (timer) clearTimeout(timer);
+            resolve(r);
+          };
+          entry.reject = function (e) {
+            if (timer) clearTimeout(timer);
+            if (pending === entry) pending = null;
+            reject(e);
+          };
         });
+
+        // Register BEFORE emitting mm:join: when someone is already waiting in
+        // the queue, mm:matched can arrive ahead of the join ack — registering
+        // afterwards dropped that instant match and left find() hanging forever.
+        pending = entry;
+
+        if (opts.timeout > 0) {
+          timer = setTimeout(function () {
+            timer = null;
+            Usion._backendEmit('mm:cancel', {}).catch(function () { /* best-effort dequeue */ });
+            entry.reject(new UsionError(ERROR_CODES.MATCH_TIMEOUT,
+              'No match within ' + opts.timeout + 'ms'));
+          }, opts.timeout);
+        }
+
+        Usion._backendEmit('mm:join', { service_id: sid, size: opts.size || 2 })
+          .catch(function (err) {
+            if (pending === entry) entry.reject(toUsionError(err));
+          });
+
+        return promise;
       },
 
       /** Leave the queue / stop waiting. */
       cancel: function () {
-        if (pending) { pending.reject(new Error('cancelled')); pending = null; }
+        if (pending) {
+          const old = pending; pending = null;
+          old.reject(new UsionError(ERROR_CODES.CANCELLED, 'cancelled'));
+        }
         return Usion._backendEmit('mm:cancel', {});
       },
     };
@@ -5399,6 +5920,7 @@ var Usion = (function () {
    * 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;
@@ -5433,30 +5955,61 @@ var Usion = (function () {
     /**
      * Emit a backend request and await its ack. Routes to the SDK socket when
      * standalone, or through the parent host when embedded.
+     * Standalone apps that never call Usion.game.connect() (e.g. a non-game
+     * app using cloud/leaderboard/notify) get an automatic one-time connect —
+     * the backend channel is not coupled to starting a game.
+     * Rejections are always UsionError (stable `code`, plus `retryAfter` on
+     * RATE_LIMITED), regardless of transport.
      * @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) {
+
+      function emitOn(sock) {
         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);
+          const timer = setTimeout(function () {
+            if (done) return; done = true;
+            reject(new UsionError(ERROR_CODES.REQUEST_TIMEOUT, 'Backend request timeout'));
+          }, timeout);
           try {
-            s.emit(event, data || {}, function (resp) {
+            sock.emit(event, data || {}, function (resp) {
               if (done) return; done = true; clearTimeout(timer);
-              if (resp && resp.error) reject(new Error(resp.message || resp.error));
+              if (resp && resp.error) reject(toUsionError(resp));
               else resolve(resp);
             });
-          } catch (e) { clearTimeout(timer); reject(e); }
+          } catch (e) { clearTimeout(timer); reject(toUsionError(e)); }
         });
       }
+
+      const s = self.game && self.game.socket;
+      if (s && s.connected) return emitOn(s);
       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 self._request('BACKEND_EMIT', { event: event, data: data || {} }, timeout)
+          .catch(function (e) { throw toUsionError(e); });
+      }
+
+      // Standalone without a live socket. If no socket exists yet, auto-connect
+      // once (connect() dedupes concurrent callers via _connectPromise). A
+      // socket that exists but is mid-reconnect is left to Socket.IO's own
+      // reconnection — the caller gets a coded error and can retry.
+      const connectionMode = (self.config && self.config.connectionMode) || 'platform';
+      if (!s && connectionMode !== 'direct'
+          && self.game && typeof self.game.connect === 'function') {
+        return self.game.connect().then(function () {
+          const sock = self.game.socket;
+          if (sock && sock.connected) return emitOn(sock);
+          throw new UsionError(ERROR_CODES.NOT_CONNECTED, 'No backend connection');
+        }).catch(function (e) {
+          if (e instanceof UsionError) throw e;
+          throw new UsionError(ERROR_CODES.NOT_CONNECTED,
+            'Backend connect failed: ' + (e && e.message ? e.message : String(e)));
+        });
       }
-      return Promise.reject(new Error('No backend connection — call Usion.game.connect() first'));
+      return Promise.reject(new UsionError(ERROR_CODES.NOT_CONNECTED,
+        'No backend connection — socket is offline or reconnecting'));
     };
   }