@usions/sdk 2.21.0 → 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.21.0', // 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);
+      };
     }
   };
 
@@ -1731,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
    */
@@ -2055,7 +2160,7 @@ 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) {
@@ -2158,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;
@@ -2262,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 };
           })
@@ -2283,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 });
           }
@@ -2319,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();
       });
     };
 
@@ -2398,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);
           }
@@ -5041,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);
+              };
+              script.onerror = function() {
+                tryLoad(i + 1);
               };
-              document.head.appendChild(cdnScript);
-            };
-            document.head.appendChild(script);
+              document.head.appendChild(script);
+            })(0);
           } else {
             self._initSocket(socketUrl, token, resolve, reject);
           }
@@ -5411,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;
 
@@ -5440,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', {});
       },
     };
@@ -5707,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;
@@ -5741,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'));
     };
   }