@usions/sdk 2.11.0 → 2.12.0

package/src/browser.js

@@ -69,7 +69,7 @@ var Usion = (function () {
    * Core Usion object with init, _post, _request
    */
   const core = {
-    version: '2.1.0',
+    version: '2.12.0', // injected from package.json at build
     config: {},
     _initialized: false,
     _initCallback: null,
@@ -510,7 +510,13 @@ var Usion = (function () {
        * @param {function} callback - Called with new balance
        */
       onBalanceChange: function(callback) {
-        this._balanceChangeHandler = callback;
+        const self = this;
+        self._balanceChangeHandler = callback;
+        return function() {
+          if (self._balanceChangeHandler === callback) {
+            self._balanceChangeHandler = null;
+          }
+        };
       }
     };
   }
@@ -855,6 +861,26 @@ var Usion = (function () {
       return this.wallet.requestPayment(amount, reason, data);
     },
 
+    /**
+     * Live SDK diagnostics snapshot: version, transport, connection and
+     * sequence state. Surfaced automatically in the platform debug overlay
+     * (game.debug attaches it as _diag) and useful in bug reports.
+     */
+    diagnostics: function() {
+      const game = this.game || {};
+      return {
+        version: this.version,
+        transport: game.directMode ? 'direct' : (game._useProxy ? 'proxy' : (game.socket ? 'socket' : 'none')),
+        connected: !!game.connected,
+        joined: !!game._joined,
+        roomId: game.roomId || null,
+        playerId: game.playerId || null,
+        lastSequence: game._lastSequence || 0,
+        lastActionApplied: game._lastActionApplied || 0,
+        rejoining: !!game._rejoinPromise,
+      };
+    },
+
     /**
      * Submit result and signal completion
      * @param {object} data - Result data to send to parent
@@ -1060,9 +1086,7 @@ var Usion = (function () {
           self._connecting = false;
           self.connected = false;
           self.directMode = false;
-          if (self._eventHandlers.connectionError) {
-            self._eventHandlers.connectionError(err);
-          }
+          self._dispatch('connectionError', err);
           throw err;
         });
       return self._connectPromise;
@@ -1171,9 +1195,7 @@ var Usion = (function () {
             clearInterval(self._heartbeatInterval);
             self._heartbeatInterval = null;
           }
-          if (self._eventHandlers.disconnect) {
-            self._eventHandlers.disconnect(evt && evt.reason ? evt.reason : 'direct socket closed');
-          }
+          self._dispatch('disconnect', evt && evt.reason ? evt.reason : 'direct socket closed');
           // Seamless resume: if the drop wasn't an intentional disconnect()
           // (which clears directMode), transparently re-establish + re-join +
           // resync from the last sequence.
@@ -1207,7 +1229,7 @@ var Usion = (function () {
             self.connected = true;
             self._reconnecting = false;
             self._reconnectAttempt = 0;
-            if (self._eventHandlers.reconnect) self._eventHandlers.reconnect(attempt);
+            self._dispatch('reconnect', attempt);
             if (self.roomId) self.requestSync(self._lastSequence || 0); // resync / resume
           })
           .catch(function() {
@@ -1245,20 +1267,20 @@ var Usion = (function () {
 
       if (data.type === 'joined') {
         this._joined = true;
-        if (this._eventHandlers.joined) this._eventHandlers.joined(payload);
+        this._dispatch('joined', payload);
         return;
       }
       if (data.type === 'player_joined') {
-        if (this._eventHandlers.playerJoined) this._eventHandlers.playerJoined(payload);
+        this._dispatch('playerJoined', payload);
         return;
       }
       if (data.type === 'player_left') {
-        if (this._eventHandlers.playerLeft) this._eventHandlers.playerLeft(payload);
+        this._dispatch('playerLeft', payload);
         return;
       }
       if (data.type === 'state_snapshot' || data.type === 'state_delta') {
-        if (this._eventHandlers.realtime) this._eventHandlers.realtime(payload);
-        if (this._eventHandlers.stateUpdate) this._eventHandlers.stateUpdate(payload);
+        this._dispatch('realtime', payload);
+        this._dispatch('stateUpdate', payload);
         return;
       }
       if (data.type === 'pong') {
@@ -1267,15 +1289,15 @@ var Usion = (function () {
           const waiter = this._pongWaiters.shift();
           if (waiter) waiter();
         }
-        if (this._eventHandlers.sync) this._eventHandlers.sync(payload);
+        this._dispatch('sync', payload);
         return;
       }
       if (data.type === 'match_end') {
-        if (this._eventHandlers.finished) this._eventHandlers.finished(payload);
+        this._dispatch('finished', payload);
         return;
       }
-      if (data.type === 'error' && this._eventHandlers.error) {
-        this._eventHandlers.error(payload);
+      if (data.type === 'error') {
+        this._dispatch('error', payload);
       }
     };
   }
@@ -1339,17 +1361,27 @@ var Usion = (function () {
             }
           }, 25000);
 
-          // Re-join room after reconnect
+          // Re-join room after reconnect. The promise is kept on
+          // _rejoinPromise so action() can gate sends until the room
+          // membership and sync are restored — otherwise a stale move could
+          // go out before the client has caught up.
           if (self.roomId) {
             self._joined = false;
             self._joinPromise = null;
-            self.join(self.roomId)
+            self._rejoinPromise = self.join(self.roomId)
               .then(function() {
                 Usion.log('Reconnected - joined room ' + self.roomId);
                 self.requestSync(self._lastSequence || 0);
               })
               .catch(function(err) {
                 Usion.log('Rejoin failed: ' + (err && err.message ? err.message : String(err)));
+              })
+              .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.)
+                if (self._flushOfflineQueue) self._flushOfflineQueue();
               });
           }
 
@@ -1359,9 +1391,7 @@ var Usion = (function () {
         self.socket.on('connect_error', function(err) {
           self._connecting = false;
           Usion.log('Game socket error: ' + err.message);
-          if (self._eventHandlers.connectionError) {
-            self._eventHandlers.connectionError(err);
-          }
+          self._dispatch('connectionError', err);
           reject(err);
         });
 
@@ -1374,104 +1404,92 @@ var Usion = (function () {
             self._heartbeatInterval = null;
           }
           Usion.log('Game socket disconnected: ' + reason);
-          if (self._eventHandlers.disconnect) {
-            self._eventHandlers.disconnect(reason);
-          }
+          self._dispatch('disconnect', reason);
         });
 
         self.socket.on('reconnect', function(attemptNumber) {
           Usion.log('Game socket reconnected after ' + attemptNumber + ' attempts');
-          if (self._eventHandlers.reconnect) {
-            self._eventHandlers.reconnect(attemptNumber);
-          }
+          self._dispatch('reconnect', attemptNumber);
         });
 
         // Game event handlers
         self.socket.on('game:joined', function(data) {
           if (data.sequence !== undefined) {
             self._lastSequence = data.sequence;
+            // Everything up to this sequence is reflected in the joined
+            // state — actions at or below it must not be re-delivered.
+            self._lastActionApplied = Math.max(self._lastActionApplied, data.sequence);
           }
-          if (self._eventHandlers.joined) {
-            self._eventHandlers.joined(data);
-          }
+          self._dispatch('joined', data);
         });
 
         self.socket.on('game:player_joined', function(data) {
-          if (self._eventHandlers.playerJoined) {
-            self._eventHandlers.playerJoined(data);
-          }
+          self._dispatch('playerJoined', data);
         });
 
         self.socket.on('game:player_left', function(data) {
-          if (self._eventHandlers.playerLeft) {
-            self._eventHandlers.playerLeft(data);
-          }
+          self._dispatch('playerLeft', data);
         });
 
         self.socket.on('game:state', function(data) {
           if (data.sequence !== undefined) {
             self._lastSequence = Math.max(self._lastSequence, data.sequence);
           }
-          if (self._eventHandlers.stateUpdate) {
-            self._eventHandlers.stateUpdate(data);
-          }
+          self._dispatch('stateUpdate', data);
         });
 
         self.socket.on('game:sync', function(data) {
           if (data.sequence !== undefined) {
             self._lastSequence = data.sequence;
+            // The sync payload carries all actions up to this sequence; a
+            // live echo of one of them must not be applied a second time.
+            self._lastActionApplied = Math.max(self._lastActionApplied, data.sequence);
           }
-          if (self._eventHandlers.sync) {
-            self._eventHandlers.sync(data);
-          }
+          self._dispatch('sync', data);
           // Also trigger stateUpdate for backwards compat
-          if (self._eventHandlers.stateUpdate) {
-            self._eventHandlers.stateUpdate(data);
-          }
+          self._dispatch('stateUpdate', data);
         });
 
         self.socket.on('game:action', function(data) {
           if (data.sequence !== undefined) {
+            // Drop duplicates: actions are delivered exactly once per
+            // sequence, whether they arrive live, as the sender's own echo,
+            // or replayed after a reconnect.
+            if (data.sequence <= self._lastActionApplied) return;
+            self._lastActionApplied = data.sequence;
             self._lastSequence = Math.max(self._lastSequence, data.sequence);
           }
-          if (self._eventHandlers.action) {
-            self._eventHandlers.action(data);
-          }
+          self._dispatch('action', data);
+        });
+
+        self.socket.on('game:player_connection', function(data) {
+          self._dispatch('playerConnection', data);
         });
 
         self.socket.on('game:realtime', function(data) {
-          if (self._eventHandlers.realtime) {
-            self._eventHandlers.realtime(data);
-          }
+          self._dispatch('realtime', data);
         });
 
         self.socket.on('game:finished', function(data) {
           if (data.sequence !== undefined) {
             self._lastSequence = data.sequence;
           }
-          if (self._eventHandlers.finished) {
-            self._eventHandlers.finished(data);
-          }
+          self._dispatch('finished', data);
         });
 
         self.socket.on('game:error', function(data) {
           Usion.log('Game error: ' + (data.message || data.code));
-          if (self._eventHandlers.error) {
-            self._eventHandlers.error(data);
-          }
+          self._dispatch('error', data);
         });
 
         self.socket.on('game:rematch_request', function(data) {
-          if (self._eventHandlers.rematchRequest) {
-            self._eventHandlers.rematchRequest(data);
-          }
+          self._dispatch('rematchRequest', data);
         });
 
         self.socket.on('game:restarted', function(data) {
           self._lastSequence = 0; // Reset sequence on rematch
-          if (self._eventHandlers.restarted) {
-            self._eventHandlers.restarted(data);
-          }
+          self._lastActionApplied = 0;
+          self._dispatch('restarted', data);
         });
 
       } catch (err) {
@@ -1480,6 +1498,82 @@ 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
    */
@@ -1523,7 +1617,7 @@ var Usion = (function () {
         setTimeout(function() {
           if (!self.connected) {
             self._connecting = false;
-            reject(new Error('Proxy connection timeout'));
+            reject(new UsionError(ERROR_CODES.CONNECT_TIMEOUT, 'Proxy connection timeout'));
           }
         }, 10000);
       });
@@ -1564,69 +1658,97 @@ var Usion = (function () {
             self._connecting = false;
             break;
 
+          case 'GAME_DISCONNECTED':
+            // The host app's socket dropped; it will rejoin and resync for us.
+            self.connected = false;
+            self._dispatch('disconnect', data.reason || 'transport');
+            break;
+
+          case 'GAME_RECONNECTED':
+            self.connected = true;
+            self._dispatch('reconnect', data.attempts || 1);
+            break;
+
+          case 'GAME_PLAYER_CONNECTION':
+            self._dispatch('playerConnection', data);
+            break;
+
           case 'GAME_JOINED':
             self._joined = true;
-            if (data.sequence !== undefined) self._lastSequence = data.sequence;
+            if (data.sequence !== undefined) {
+              self._lastSequence = data.sequence;
+              self._lastActionApplied = Math.max(self._lastActionApplied, data.sequence);
+            }
             if (self._proxyJoinResolve) {
               self._proxyJoinResolve(data);
               self._proxyJoinResolve = null;
             }
-            if (self._eventHandlers.joined) self._eventHandlers.joined(data);
+            self._dispatch('joined', data);
             break;
 
           case 'GAME_JOIN_ERROR':
             self._joined = false;
             if (self._proxyJoinReject) {
-              self._proxyJoinReject(new Error(data.message || 'Join failed'));
+              self._proxyJoinReject(toUsionError(data.message || 'Join failed'));
               self._proxyJoinReject = null;
             }
             break;
 
           case 'GAME_PLAYER_JOINED':
-            if (self._eventHandlers.playerJoined) self._eventHandlers.playerJoined(data);
+            self._dispatch('playerJoined', data);
             break;
 
           case 'GAME_PLAYER_LEFT':
-            if (self._eventHandlers.playerLeft) self._eventHandlers.playerLeft(data);
+            self._dispatch('playerLeft', data);
             break;
 
           case 'GAME_STATE':
             if (data.sequence !== undefined) self._lastSequence = Math.max(self._lastSequence, data.sequence);
-            if (self._eventHandlers.stateUpdate) self._eventHandlers.stateUpdate(data);
+            self._dispatch('stateUpdate', data);
             break;
 
           case 'GAME_ACTION_DATA':
-            if (data.sequence !== undefined) self._lastSequence = Math.max(self._lastSequence, data.sequence);
-            if (self._eventHandlers.action) self._eventHandlers.action(data);
+            if (data.sequence !== undefined) {
+              // Drop duplicates: actions are delivered exactly once per
+              // sequence (live, sender echo, or replay after reconnect).
+              if (data.sequence <= self._lastActionApplied) break;
+              self._lastActionApplied = data.sequence;
+              self._lastSequence = Math.max(self._lastSequence, data.sequence);
+            }
+            self._dispatch('action', data);
             break;
 
           case 'GAME_REALTIME_DATA':
-            if (self._eventHandlers.realtime) self._eventHandlers.realtime(data);
+            self._dispatch('realtime', data);
             break;
 
           case 'GAME_FINISHED':
             if (data.sequence !== undefined) self._lastSequence = data.sequence;
-            if (self._eventHandlers.finished) self._eventHandlers.finished(data);
+            self._dispatch('finished', data);
             break;
 
           case 'GAME_ERROR':
             Usion.log('Game error via proxy: ' + (data.message || data.code));
-            if (self._eventHandlers.error) self._eventHandlers.error(data);
+            self._dispatch('error', data);
             break;
 
           case 'GAME_RESTARTED':
             self._lastSequence = 0;
-            if (self._eventHandlers.restarted) self._eventHandlers.restarted(data);
+            self._lastActionApplied = 0;
+            self._dispatch('restarted', data);
             break;
 
           case 'GAME_REMATCH_REQUEST':
-            if (self._eventHandlers.rematchRequest) self._eventHandlers.rematchRequest(data);
+            self._dispatch('rematchRequest', data);
             break;
 
           case 'GAME_SYNC':
-            if (data.sequence !== undefined) self._lastSequence = data.sequence;
-            if (self._eventHandlers.sync) self._eventHandlers.sync(data);
-            if (self._eventHandlers.stateUpdate) self._eventHandlers.stateUpdate(data);
+            if (data.sequence !== undefined) {
+              self._lastSequence = data.sequence;
+              self._lastActionApplied = Math.max(self._lastActionApplied, data.sequence);
+            }
+            self._dispatch('sync', data);
+            self._dispatch('stateUpdate', data);
             break;
         }
       });
@@ -1637,6 +1759,7 @@ var Usion = (function () {
    * Usion SDK Game Methods — join, leave, action, realtime, sync, etc.
    */
 
+
   /**
    * Add game action methods to game module
    * @param {object} game - The game module object
@@ -1678,7 +1801,7 @@ var Usion = (function () {
           setTimeout(function() {
             if (!self._joined && self._proxyJoinReject) {
               self._proxyJoinReject = null;
-              reject(new Error('Join timeout'));
+              reject(new UsionError(ERROR_CODES.JOIN_TIMEOUT, 'Join timeout'));
             }
           }, 15000);
         });
@@ -1687,19 +1810,19 @@ var Usion = (function () {
 
       self._joinPromise = new Promise(function(resolve, reject) {
         if (!self.socket || !self.connected) {
-          reject(new Error('Not connected'));
+          reject(new UsionError(ERROR_CODES.NOT_CONNECTED, 'Not connected'));
           return;
         }
 
         if (!roomId) {
-          reject(new Error('No room ID provided'));
+          reject(new UsionError(ERROR_CODES.NO_ROOM, 'No room ID provided'));
           return;
         }
 
         self.socket.emit('game:join', { room_id: roomId }, function(response) {
           if (response.error) {
             self._joined = false;
-            reject(new Error(response.message || response.error));
+            reject(toUsionError(response.message || response.error));
           } else {
             self._joined = true;
             if (response.sequence !== undefined) {
@@ -1747,13 +1870,25 @@ var Usion = (function () {
     };
 
     /**
-     * Send a game action
+     * Send a game action.
+     *
+     * RELIABILITY CONTRACT: the platform echoes every action back to the
+     * sender (with the authoritative sequence number). Apply game state ONLY
+     * in onAction — never optimistically on send — so every client applies
+     * the same actions in the same order. The SDK deduplicates by sequence,
+     * so an action is delivered exactly once even across reconnect replays.
+     *
      * @param {string} actionType - Type of action (e.g., 'move')
      * @param {object} actionData - Action data
+     * @param {object} [opts] - Options. opts.nextTurn: player ID whose turn
+     *   is next — the server remembers it and hands it to any (re)joining
+     *   client as current_turn, so turn state survives reconnects.
      * @returns {Promise} Resolves when action is processed
      */
-    game.action = function(actionType, actionData) {
+    game.action = function(actionType, actionData, opts) {
       const self = this;
+      const nextTurn = opts && opts.nextTurn;
+      const queueOffline = !!(opts && opts.queueOffline);
 
       if (self.directMode) {
         self._sendDirect('action', {
@@ -1763,29 +1898,153 @@ var Usion = (function () {
         return Promise.resolve({ success: true });
       }
 
+      // Opt-in offline queue: instead of failing while disconnected, hold
+      // the move and send it (in order) once the connection recovers.
+      // Turn-based games get "your move is saved and sends when you're
+      // back" for free; realtime games should NOT use this (stale inputs).
+      if (queueOffline && !self.connected) {
+        return self._queueOfflineAction(actionType, actionData, opts);
+      }
+
       if (self._useProxy) {
-        Usion._post({ type: 'GAME_ACTION', room_id: self.roomId, action_type: actionType, action_data: actionData });
+        const proxyMsg = { type: 'GAME_ACTION', room_id: self.roomId, action_type: actionType, action_data: actionData };
+        if (nextTurn) proxyMsg.next_turn = nextTurn;
+        Usion._post(proxyMsg);
         return Promise.resolve({ success: true });
       }
 
+      // Gate sends while a post-reconnect rejoin is in flight, so a stale
+      // 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;
+          }
+
+          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);
+            }
+          });
+        });
+      });
+    };
+
+    // ── Offline action queue (opt-in via action(..., { queueOffline: true })) ──
+
+    const OFFLINE_QUEUE_MAX = 20;
+
+    /** @private Hold an action until the connection recovers. */
+    game._queueOfflineAction = function(actionType, actionData, opts) {
+      const self = this;
+      if (!self._offlineQueue) self._offlineQueue = [];
+      if (self._offlineQueue.length >= OFFLINE_QUEUE_MAX) {
+        return Promise.reject(new UsionError(ERROR_CODES.QUEUE_FULL,
+          'Offline action queue is full (' + OFFLINE_QUEUE_MAX + ')'));
+      }
+      Usion.log('Queued action while offline: ' + actionType);
+      return new Promise(function(resolve, reject) {
+        self._offlineQueue.push({
+          actionType: actionType,
+          actionData: actionData,
+          opts: Object.assign({}, opts, { queueOffline: false }),
+          resolve: resolve,
+          reject: reject,
+        });
+        self._ensureOfflineFlushHook();
+      });
+    };
+
+    /** @private Flush queued actions, in order, once reconnected. */
+    game._ensureOfflineFlushHook = function() {
+      const self = this;
+      if (self._offlineFlushHooked) return;
+      self._offlineFlushHooked = true;
+      self.on('reconnect', function() { self._flushOfflineQueue(); });
+    };
+
+    /** @private */
+    game._flushOfflineQueue = function() {
+      const self = this;
+      const queue = self._offlineQueue;
+      if (!queue || !queue.length) return;
+      self._offlineQueue = [];
+      Usion.log('Flushing ' + queue.length + ' queued action(s) after reconnect');
+      // Send strictly in order: each action waits for the previous ack so
+      // the server assigns sequences in the order the player acted.
+      let chain = Promise.resolve();
+      queue.forEach(function(item) {
+        chain = chain.then(function() {
+          return self.action(item.actionType, item.actionData, item.opts)
+            .then(item.resolve, item.reject);
+        });
+      });
+    };
+
+    /**
+     * Checkpoint the authoritative game state on the server. Any client that
+     * joins or rejoins the room receives the latest checkpoint as game_state
+     * in the join ack and in game:sync — recovery becomes "load checkpoint,
+     * replay the tail" instead of replaying every action from zero.
+     *
+     * Only the room authority (player_ids[0] / host) may call this. The
+     * serialized state is capped at 64 KB.
+     *
+     * @param {*} state - JSON-serializable authoritative game state
+     * @returns {Promise<{success: boolean, error?: string}>}
+     */
+    game.setState = function(state) {
+      const self = this;
+
+      if (self.directMode) {
+        // Direct-mode game servers own their state; no platform checkpoint.
+        return Promise.resolve({ success: false, error: 'not_supported_in_direct_mode', code: ERROR_CODES.UNSUPPORTED });
+      }
+
+      if (self._useProxy) {
+        return Usion._request('GAME_SET_STATE', { room_id: self.roomId, state: state || {} })
+          .then(function(res) {
+            if (res && res.error) {
+              return { success: false, error: res.error, code: toUsionError(res.error).code };
+            }
+            return res || { success: true };
+          })
+          .catch(function(err) {
+            const ue = toUsionError(err, ERROR_CODES.REQUEST_TIMEOUT);
+            return { success: false, error: ue.message, code: ue.code };
+          });
+      }
+
       return new Promise(function(resolve, reject) {
         if (!self.socket || !self.connected) {
-          reject(new Error('Not connected'));
+          reject(new UsionError(ERROR_CODES.NOT_CONNECTED, 'Not connected'));
           return;
         }
-
-        self.socket.emit('game:action', {
+        self.socket.emit('game:set_state', {
           room_id: self.roomId,
-          action_type: actionType,
-          action_data: actionData
+          state: state || {}
         }, function(response) {
-          if (response.error) {
-            reject(new Error(response.message || response.error));
+          if (response && response.error) {
+            resolve({ success: false, error: response.error, code: toUsionError(response.error).code });
           } else {
-            if (response.sequence !== undefined) {
-              self._lastSequence = response.sequence;
-            }
-            resolve(response);
+            resolve(response || { success: true });
           }
         });
       });
@@ -1889,13 +2148,13 @@ var Usion = (function () {
 
       return new Promise(function(resolve, reject) {
         if (!self.socket || !self.connected) {
-          reject(new Error('Not connected'));
+          reject(new UsionError(ERROR_CODES.NOT_CONNECTED, 'Not connected'));
           return;
         }
 
         self.socket.emit('game:forfeit', { room_id: self.roomId }, function(response) {
           if (response.error) {
-            reject(new Error(response.message || response.error));
+            reject(toUsionError(response.message || response.error));
           } else {
             resolve(response);
           }
@@ -2057,7 +2316,9 @@ var Usion = (function () {
         var inFrame = window.parent && window.parent !== window;
         var inRNWebView = !!window.ReactNativeWebView;
         if (inFrame || inRNWebView) {
-          Usion._post({ type: 'GAME_DEBUG', payload: payload || {} });
+          var body = Object.assign({}, payload || {});
+          body._diag = Usion.diagnostics ? Usion.diagnostics() : undefined;
+          Usion._post({ type: 'GAME_DEBUG', payload: body });
         }
       } catch (e) { /* non-fatal */ }
     };
@@ -4063,6 +4324,36 @@ var Usion = (function () {
    */
 
 
+  // Map any reasonable spelling of a game event onto the internal handler
+  // name: 'game:player_joined' / 'player_joined' / 'playerJoined' → 'playerJoined'.
+  const _EVENT_ALIASES = {
+    joined: 'joined',
+    player_joined: 'playerJoined',
+    player_left: 'playerLeft',
+    player_connection: 'playerConnection',
+    state: 'stateUpdate',
+    state_update: 'stateUpdate',
+    sync: 'sync',
+    action: 'action',
+    realtime: 'realtime',
+    finished: 'finished',
+    restarted: 'restarted',
+    error: 'error',
+    rematch_request: 'rematchRequest',
+    disconnect: 'disconnect',
+    reconnect: 'reconnect',
+    connection_error: 'connectionError',
+  };
+
+  function _normalizeEventName(event) {
+    let name = String(event || '');
+    if (name.indexOf('game:') === 0) name = name.slice(5);
+    if (_EVENT_ALIASES[name]) return _EVENT_ALIASES[name];
+    // camelCase passthrough ('playerJoined', 'stateUpdate', …)
+    const snake = name.replace(/([A-Z])/g, function(m) { return '_' + m.toLowerCase(); });
+    return _EVENT_ALIASES[snake] || name;
+  }
+
   /**
    * Create the game module with all sub-modules applied
    * @param {object} Usion - Reference to the main Usion object
@@ -4088,6 +4379,11 @@ var Usion = (function () {
       _heartbeatInterval: null,
       _pingMeter: null,
       _pongWaiters: [],
+      // Reliability state: highest action sequence already delivered to the
+      // game (duplicate echoes/replays are dropped), and the in-flight rejoin
+      // promise that gates action() sends right after a reconnect.
+      _lastActionApplied: 0,
+      _rejoinPromise: null,
 
       /**
        * Connect to the game socket server
@@ -4170,34 +4466,85 @@ var Usion = (function () {
         return self._connectPromise;
       },
 
-      // Event handler registrations
-      onJoined: function(callback) { this._eventHandlers.joined = callback; },
-      onPlayerJoined: function(callback) { this._eventHandlers.playerJoined = callback; },
-      onPlayerLeft: function(callback) { this._eventHandlers.playerLeft = callback; },
-      onStateUpdate: function(callback) { this._eventHandlers.stateUpdate = callback; },
-      onSync: function(callback) { this._eventHandlers.sync = callback; },
-      onAction: function(callback) { this._eventHandlers.action = callback; },
-      onRealtime: function(callback) { this._eventHandlers.realtime = callback; },
-      onGameFinished: function(callback) { this._eventHandlers.finished = callback; },
-      onGameRestarted: function(callback) { this._eventHandlers.restarted = callback; },
-      onError: function(callback) { this._eventHandlers.error = callback; },
-      onRematchRequest: function(callback) { this._eventHandlers.rematchRequest = callback; },
-      onDisconnect: function(callback) { this._eventHandlers.disconnect = callback; },
-      onReconnect: function(callback) { this._eventHandlers.reconnect = callback; },
-      onConnectionError: function(callback) { this._eventHandlers.connectionError = callback; },
+      // Event handler registrations.
+      //
+      // Each onX(cb) keeps the long-standing "single handler, last one wins"
+      // behavior for back-compat, but now ALSO returns an unsubscribe
+      // function. For multiple listeners use game.on(event, cb), which
+      // supports any number of listeners, works before connect() in every
+      // transport, and returns an unsubscribe function.
+      onJoined: function(callback) { return this._setHandler('joined', callback); },
+      onPlayerJoined: function(callback) { return this._setHandler('playerJoined', callback); },
+      onPlayerLeft: function(callback) { return this._setHandler('playerLeft', callback); },
+      onStateUpdate: function(callback) { return this._setHandler('stateUpdate', callback); },
+      onSync: function(callback) { return this._setHandler('sync', callback); },
+      onAction: function(callback) { return this._setHandler('action', callback); },
+      onRealtime: function(callback) { return this._setHandler('realtime', callback); },
+      onGameFinished: function(callback) { return this._setHandler('finished', callback); },
+      onGameRestarted: function(callback) { return this._setHandler('restarted', callback); },
+      onError: function(callback) { return this._setHandler('error', callback); },
+      onRematchRequest: function(callback) { return this._setHandler('rematchRequest', callback); },
+      onDisconnect: function(callback) { return this._setHandler('disconnect', callback); },
+      onReconnect: function(callback) { return this._setHandler('reconnect', callback); },
+      onConnectionError: function(callback) { return this._setHandler('connectionError', callback); },
+      onPlayerConnection: function(callback) { return this._setHandler('playerConnection', callback); },
+
+      /** @private Set the single legacy handler; returns an unsubscribe fn. */
+      _setHandler: function(name, callback) {
+        const self = this;
+        self._eventHandlers[name] = callback;
+        return function() {
+          if (self._eventHandlers[name] === callback) {
+            self._eventHandlers[name] = null;
+          }
+        };
+      },
 
       /**
-       * Register a generic event handler
+       * @private Deliver an event to the legacy single handler and every
+       * game.on() listener. All game event delivery flows through here.
+       */
+      _dispatch: function(name) {
+        const args = Array.prototype.slice.call(arguments, 1);
+        const single = this._eventHandlers[name];
+        if (single) {
+          try { single.apply(null, args); } catch (e) { Usion.log('game handler error (' + name + '): ' + e.message); }
+        }
+        const list = this._listeners[name];
+        if (list && list.length) {
+          const copy = list.slice();
+          for (let i = 0; i < copy.length; i++) {
+            try { copy[i].apply(null, args); } catch (e) { Usion.log('game listener error (' + name + '): ' + e.message); }
+          }
+        }
+      },
+
+      /**
+       * Register an additional event listener. Unlike the onX methods this
+       * supports multiple listeners per event, can be called before
+       * connect(), and works in every transport (standalone, embedded
+       * proxy, direct). Accepts internal names ('action'), wire names
+       * ('game:action'), or snake_case ('player_joined').
        * @param {string} event - Event name
        * @param {function} callback - Handler function
+       * @returns {function} Unsubscribe function
        */
       on: function(event, callback) {
-        if (this.socket) {
-          this.socket.on(event, callback);
-        }
+        const self = this;
+        const name = _normalizeEventName(event);
+        if (!self._listeners[name]) self._listeners[name] = [];
+        self._listeners[name].push(callback);
+        return function() {
+          const list = self._listeners[name];
+          if (!list) return;
+          const i = list.indexOf(callback);
+          if (i >= 0) list.splice(i, 1);
+        };
       }
     };
 
+    game._listeners = {};
+
     // Apply sub-modules
     applyGameDirect(game, Usion);
     applyGameSocket(game, Usion);
@@ -4616,6 +4963,9 @@ var Usion = (function () {
   Usion.bot = createBotModule(Usion);
   Usion.fileStorage = createFileStorageModule(Usion);
   Usion.game = createGameModule(Usion);
+  // Stable error class + codes — developers branch on err.code, not message text.
+  Usion.UsionError = UsionError;
+  Usion.ERROR_CODES = ERROR_CODES;
   // Unified backend channel (used by lobby etc.; works standalone + embedded).
   applyBackendChannel(Usion);
   Usion.lobby = createLobbyModule(Usion);