@usions/sdk 2.21.0 → 2.22.0

package/src/modules/backend-channel.js

@@ -14,6 +14,8 @@
  * 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.
  */
+import { UsionError, toUsionError, ERROR_CODES } from './errors.js';
+
 export function applyBackendChannel(Usion) {
   Usion._backendHandlers = {};
   Usion._boundSockets = typeof WeakSet !== 'undefined' ? new WeakSet() : null;
@@ -48,29 +50,60 @@ export function applyBackendChannel(Usion) {
   /**
    * 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'));
   };
 }

package/src/modules/core.js

@@ -2,6 +2,8 @@
  * Usion SDK Core — init, _post, _request, message handling
  */
 
+import { UsionError, toUsionError, ERROR_CODES } from './errors.js';
+
 // Request ID counter for tracking async responses
 let _requestId = 0;
 export const _pendingRequests = {};
@@ -75,24 +77,60 @@ export const core = {
   _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;
 
@@ -148,6 +186,15 @@ export const core = {
         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
@@ -156,7 +203,9 @@ export const core = {
         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);
         }
@@ -215,6 +264,8 @@ export const core = {
 
     // Signal ready to parent
     this._post({ type: 'READY' });
+
+    return self._initPromise;
   },
 
   /**
@@ -336,7 +387,7 @@ export const core = {
       // 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

package/src/modules/errors.js

@@ -12,16 +12,29 @@ export const ERROR_CODES = {
   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_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
-  RATE_LIMITED: 'RATE_LIMITED',             // Too many calls; back off
+  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)
 };
@@ -35,18 +48,25 @@ export class UsionError extends Error {
     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],
@@ -54,17 +74,40 @@ const BACKEND_PATTERNS = [
   [/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 (backend `{error}` string, Error, raw string) into a
- * UsionError with the best-matching stable code.
+ * 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}
  */
 export 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)) {

package/src/modules/game-core.js

@@ -126,26 +126,31 @@ export function createGameModule(Usion) {
       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);
         }

package/src/modules/game-methods.js

@@ -66,7 +66,7 @@ export function applyGameMethods(game, Usion) {
       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) {
@@ -169,36 +169,81 @@ export function applyGameMethods(game, Usion) {
     // 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;
@@ -273,11 +318,17 @@ export function applyGameMethods(game, Usion) {
       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 };
         })
@@ -294,10 +345,12 @@ export function applyGameMethods(game, Usion) {
       }
       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 });
         }
@@ -330,10 +383,18 @@ export function applyGameMethods(game, Usion) {
       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();
     });
   };
 
@@ -409,7 +470,7 @@ export function applyGameMethods(game, Usion) {
 
       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);
         }

package/src/modules/matchmaking.js

@@ -7,12 +7,15 @@
  *
  *   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 }) => { ... });
  */
+import { UsionError, toUsionError, ERROR_CODES } from './errors.js';
+
 export 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;
 
@@ -36,25 +39,64 @@ export function createMatchmakingModule(Usion) {
 
     /**
      * 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();
-      const self = this;
-      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', {});
     },
   };

package/src/modules/misc.js

@@ -127,9 +127,10 @@ export const miscMethods = {
    * 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;
@@ -142,6 +143,10 @@ export const miscMethods = {
       if (data.type === type) {
         callback(data);
       }
-    });
+    }
+    window.addEventListener('message', listener);
+    return function() {
+      window.removeEventListener('message', listener);
+    };
   }
 };