@usions/sdk 2.20.2 → 2.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usions/sdk",
-  "version": "2.20.2",
+  "version": "2.21.0",
   "description": "Usion Mini App SDK for iframe games and services",
   "type": "module",
   "main": "src/modules/index.js",

package/src/browser.js

@@ -69,7 +69,7 @@ var Usion = (function () {
    * Core Usion object with init, _post, _request
    */
   const core = {
-    version: '2.20.2', // injected from package.json at build
+    version: '2.21.0', // injected from package.json at build
     config: {},
     _initialized: false,
     _initCallback: null,
@@ -1564,7 +1564,20 @@ var Usion = (function () {
         // backend channel — robust to listener registration order.
         if (Usion._bindBackendSocket) Usion._bindBackendSocket(self.socket);
 
+        // Socket.IO v4 emits 'reconnect' on the Manager, not the Socket — a
+        // Socket-level 'reconnect' listener never fires. Track attempts on the
+        // Manager and treat any connect after the first (per socket) as the
+        // reconnect signal, dispatched below AFTER rejoin gating is in place.
+        var hadConnect = false;
+        if (self.socket.io && typeof self.socket.io.on === 'function') {
+          self.socket.io.on('reconnect_attempt', function(n) {
+            self._reconnAttempts = n;
+          });
+        }
+
         self.socket.on('connect', function() {
+          var isReconnect = hadConnect;
+          hadConnect = true;
           self.connected = true;
           self._connecting = false;
           Usion.log('Game socket connected');
@@ -1595,12 +1608,21 @@ var Usion = (function () {
               .then(function() {
                 self._rejoinPromise = null;
                 // Send any moves queued while offline, now that membership
-                // and sync are restored. (Socket.IO v4 emits 'reconnect' on
-                // the Manager, not the Socket, so this is the reliable hook.)
+                // and sync are restored. (This connect handler is the reliable
+                // hook — see the Manager-vs-Socket note above.)
                 if (self._flushOfflineQueue) self._flushOfflineQueue();
               });
           }
 
+          // Dispatched after _rejoinPromise is set, so anything reacting to
+          // 'reconnect' (offline-queue flush, connection-state machine) sees
+          // sends gated behind the rejoin+resync.
+          if (isReconnect) {
+            Usion.log('Game socket reconnected');
+            self._dispatch('reconnect', self._reconnAttempts || 1);
+            self._reconnAttempts = 0;
+          }
+
           resolve();
         });
 
@@ -1623,11 +1645,6 @@ var Usion = (function () {
           self._dispatch('disconnect', reason);
         });
 
-        self.socket.on('reconnect', function(attemptNumber) {
-          Usion.log('Game socket reconnected after ' + attemptNumber + ' attempts');
-          self._dispatch('reconnect', attemptNumber);
-        });
-
         // Game event handlers
         self.socket.on('game:joined', function(data) {
           if (data.sequence !== undefined) {
@@ -2043,7 +2060,15 @@ var Usion = (function () {
             self._joined = true;
             if (response.sequence !== undefined) {
               self._lastSequence = response.sequence;
+              // The joined state reflects everything up to this sequence —
+              // actions at or below it must not be re-delivered (same
+              // baseline the proxy transport sets from GAME_JOINED).
+              self._lastActionApplied = Math.max(self._lastActionApplied, response.sequence);
             }
+            // Transport parity: proxy and direct modes dispatch 'joined';
+            // the socket transport now does too, so onJoined / recovery
+            // logic behaves the same everywhere.
+            self._dispatch('joined', response);
             resolve(response);
           }
         });
@@ -4615,6 +4640,285 @@ var Usion = (function () {
     game.getRtt = function () { return this._pingMeter ? this._pingMeter.rtt : null; };
   }
 
+  /**
+   * Usion SDK Game Reliability — the reconnection-lifecycle surface promised in
+   * v2.16: sequence getters, the unified connection-state machine, and
+   * syncedState (reconnect-safe authoritative shared state).
+   *
+   * Everything here rides the events the game module already dispatches
+   * ('disconnect' / 'reconnect' / 'joined' / 'sync' / 'action'), so it behaves
+   * identically across the socket, embedded-proxy, and direct transports.
+   */
+
+  function applyGameReliability(game, Usion) {
+    // ── Sequence getters ──────────────────────────────────────────────────────
+
+    /** Highest action sequence seen (from joins, syncs, and live actions). */
+    game.getLastSequence = function () { return this._lastSequence || 0; };
+
+    /** Highest action sequence applied locally; trails while catching up. */
+    game.getLastAppliedSequence = function () { return this._lastActionApplied || 0; };
+
+    // ── Connection-state machine ──────────────────────────────────────────────
+    // connected → disconnected → rejoining → reconnected → connected.
+    // 'reconnected' is a transient notification state: observers see it, then
+    // the machine settles back to 'connected' in the same tick.
+
+    game._connState = 'disconnected';
+    game._awaitResync = false;
+
+    game._setConnState = function (state) {
+      if (this._connState === state) return;
+      this._connState = state;
+      this._dispatch('connectionState', state);
+    };
+
+    /** Current connection state, synchronously. */
+    game.getConnectionState = function () { return this._connState; };
+
+    /**
+     * Observe connection-state transitions — one hook to drive a
+     * "Reconnecting…" overlay and gate input, identical on every transport.
+     * Single handler (last wins); returns an unsubscribe fn. For multiple
+     * listeners use game.on('connectionState', cb).
+     */
+    game.onConnectionState = function (callback) { return this._setHandler('connectionState', callback); };
+
+    /**
+     * Fires once per reconnect, after the resync completes, with
+     * { state, lastSequence, viaSync }. Restore local state here — it does NOT
+     * fire for a manually-requested sync.
+     */
+    game.onReconnected = function (callback) { return this._setHandler('reconnected', callback); };
+
+    game.on('disconnect', function () {
+      game._awaitResync = false;
+      game._setConnState('disconnected');
+    });
+
+    game.on('reconnect', function () {
+      if (game.roomId) {
+        game._awaitResync = true;
+        game._setConnState('rejoining');
+      } else {
+        game._setConnState('connected');
+      }
+    });
+
+    game.on('sync', function (data) {
+      if (!game._awaitResync) return;
+      game._awaitResync = false;
+      game._dispatch('reconnected', {
+        state: (data && data.game_state) || null,
+        lastSequence: game._lastSequence || 0,
+        viaSync: true,
+      });
+      game._setConnState('reconnected');
+      game._setConnState('connected');
+    });
+
+    // Transport-level connects (initial connect in every mode) resolve through
+    // connect()/connectDirect() — reflect them in the state machine.
+    function wrapConnect(name) {
+      var orig = game[name];
+      if (typeof orig !== 'function') return;
+      game[name] = function () {
+        var self = this;
+        return orig.apply(self, arguments).then(function (result) {
+          if (!self._awaitResync) self._setConnState('connected');
+          return result;
+        });
+      };
+    }
+    wrapConnect('connect');
+    wrapConnect('connectDirect');
+
+    // ── Host tracking ─────────────────────────────────────────────────────────
+    // Kept on the game module (registered at module creation, so it never
+    // misses an event) — a syncedState created AFTER the join still knows who
+    // the authority is.
+
+    game._hostId = null;
+    function trackHost(d) {
+      if (!d) return;
+      if (d.host_id) game._hostId = d.host_id;
+      else if (d.player_ids && d.player_ids.length) game._hostId = d.player_ids[0];
+    }
+    game.on('joined', trackHost);
+    game.on('playerJoined', trackHost);
+
+    // ── syncedState ───────────────────────────────────────────────────────────
+
+    /**
+     * Reconnect-safe authoritative shared state. Commits are sequenced actions
+     * applied through `reduce` on every client in the same order (deduped by
+     * sequence); the authority (player_ids[0] by default) auto-checkpoints via
+     * setState, and (re)joining clients recover automatically (checkpoint +
+     * un-checkpointed tail). Degrades to local-apply in direct mode.
+     * Full contract: SyncedStateOptions / SyncedState in types/index.d.ts.
+     */
+    game.syncedState = function (initial, opts) {
+      opts = opts || {};
+      var self = this;
+      var reduce = typeof opts.reduce === 'function'
+        ? opts.reduce
+        : function (state, action) { return Object.assign({}, state, action.data); };
+      var checkpointEvery = opts.checkpointEvery != null ? opts.checkpointEvery : 1;
+      var authorityMode = opts.authority === 'all' ? 'all' : 'host';
+      var defaultType = opts.type || 'update';
+
+      var state = initial === undefined ? {} : initial;
+      var appliedSeq = 0;
+      var sinceCheckpoint = 0;
+      var lastGapRequest = -1;
+      var changeCbs = [];
+      var offs = [];
+
+      function notify(reason) {
+        var copy = changeCbs.slice();
+        for (var i = 0; i < copy.length; i++) {
+          try { copy[i](state, reason); } catch (e) { Usion.log('syncedState onChange error: ' + e.message); }
+        }
+      }
+
+      function isAuthority() {
+        if (authorityMode === 'all') return true;
+        var me = self.playerId || (Usion.user && Usion.user.getId && Usion.user.getId());
+        return !!(me && self._hostId && me === self._hostId);
+      }
+
+      function doCheckpoint() {
+        if (self.directMode) {
+          return Promise.resolve({ success: false, error: 'not_supported_in_direct_mode' });
+        }
+        // The wrapper carries the sequence the checkpoint reflects, so recovery
+        // knows exactly where the un-checkpointed tail starts.
+        return self.setState({ __usionSyncedState: 1, seq: appliedSeq, state: state });
+      }
+
+      function maybeAutoCheckpoint() {
+        if (!(checkpointEvery > 0) || !isAuthority()) return;
+        sinceCheckpoint += 1;
+        if (sinceCheckpoint >= checkpointEvery) {
+          sinceCheckpoint = 0;
+          doCheckpoint();
+        }
+      }
+
+      function applyOne(playerId, type, data, sequence) {
+        if (sequence !== undefined && sequence <= appliedSeq) return false; // dedupe
+        var next;
+        try {
+          next = reduce(state, { playerId: playerId, type: type, data: data, sequence: sequence });
+        } catch (e) {
+          Usion.log('syncedState reduce error: ' + e.message);
+          return false;
+        }
+        if (next !== undefined) state = next;
+        if (sequence !== undefined) appliedSeq = sequence;
+        return true;
+      }
+
+      function onAction(d) {
+        if (!d) return;
+        if (applyOne(d.player_id, d.action_type, d.action_data, d.sequence)) {
+          notify('action');
+          maybeAutoCheckpoint();
+        }
+      }
+
+      // Recover from a join ack or sync payload: load the checkpoint (if it is
+      // ours and newer), replay the action tail in order, and if the server's
+      // sequence is still ahead of us, ask once for the missing range.
+      function recover(d) {
+        if (!d) return;
+        var changed = false;
+
+        var gs = d.game_state;
+        if (gs && gs.__usionSyncedState && typeof gs.seq === 'number'
+            && gs.seq >= appliedSeq && gs.state !== undefined) {
+          state = gs.state;
+          appliedSeq = gs.seq;
+          changed = true;
+        }
+
+        var actions = d.actions;
+        if (actions && actions.length) {
+          var sorted = actions.slice().sort(function (a, b) {
+            return (a.sequence || 0) - (b.sequence || 0);
+          });
+          for (var i = 0; i < sorted.length; i++) {
+            var item = sorted[i];
+            if (item && applyOne(item.player_id, item.action_type, item.action_data, item.sequence)) {
+              changed = true;
+            }
+          }
+        }
+
+        if (changed) notify('recover');
+
+        // Gap fill: the checkpoint may lag the room sequence (checkpointEvery>1).
+        // Request the tail from OUR applied sequence — once per position, so a
+        // trimmed history can't loop us.
+        if (d.sequence !== undefined && d.sequence > appliedSeq && lastGapRequest !== appliedSeq) {
+          lastGapRequest = appliedSeq;
+          try { self.requestSync(appliedSeq); } catch (e) { /* non-fatal */ }
+        }
+      }
+
+      offs.push(self.on('action', onAction));
+      offs.push(self.on('sync', recover));
+      offs.push(self.on('joined', recover));
+
+      return {
+        /** Current state value. */
+        get: function () { return state; },
+
+        /**
+         * Commit a change: commit(data) with the default action type, or
+         * commit(type, data, opts) to name it (opts forwarded to game.action,
+         * e.g. nextTurn / queueOffline). Applied exactly once via the echo.
+         */
+        commit: function (typeOrData, data, actionOpts) {
+          var t, payload, o;
+          if (typeof typeOrData === 'string') { t = typeOrData; payload = data; o = actionOpts; }
+          else { t = defaultType; payload = typeOrData; o = data; }
+          if (self.directMode) {
+            // No platform echo in direct mode — apply locally, then send.
+            if (applyOne(self.playerId, t, payload, undefined)) notify('action');
+            return self.action(t, payload, o);
+          }
+          return self.action(t, payload, o);
+        },
+
+        /** Subscribe to changes: cb(state, reason). Returns an unsubscribe fn. */
+        onChange: function (cb) {
+          changeCbs.push(cb);
+          return function () {
+            var i = changeCbs.indexOf(cb);
+            if (i >= 0) changeCbs.splice(i, 1);
+          };
+        },
+
+        /** Whether this client is the checkpointing authority. */
+        isAuthority: isAuthority,
+
+        /** Force a server checkpoint now (no-op result in direct mode). */
+        checkpoint: function () { return doCheckpoint(); },
+
+        /** Sequence of the last action applied into this state. */
+        getSequence: function () { return appliedSeq; },
+
+        /** Detach all listeners; the instance stops receiving updates. */
+        destroy: function () {
+          for (var i = 0; i < offs.length; i++) { try { offs[i](); } catch (e) { /* noop */ } }
+          offs.length = 0;
+          changeCbs.length = 0;
+        },
+      };
+    };
+  }
+
   /**
    * Usion SDK Game Core — game module base, connect routing, event registrations
    */
@@ -4640,6 +4944,8 @@ var Usion = (function () {
     reconnect: 'reconnect',
     connection_error: 'connectionError',
     room_assigned: 'roomAssigned',
+    connection_state: 'connectionState',
+    reconnected: 'reconnected',
   };
 
   function _normalizeEventName(event) {
@@ -4853,6 +5159,8 @@ var Usion = (function () {
     applyGameProxy(game, Usion);
     applyGameMethods(game, Usion);
     applyGameNetcode(game, Usion);
+    // Applied last: wraps connect/connectDirect and rides dispatched events.
+    applyGameReliability(game, Usion);
 
     // Foreground catch-up safety net (generic across every transport).
     //

package/src/modules/game-core.js

@@ -7,6 +7,7 @@ import { applyGameSocket } from './game-socket.js';
 import { applyGameProxy } from './game-proxy.js';
 import { applyGameMethods } from './game-methods.js';
 import { applyGameNetcode } from './game-netcode.js';
+import { applyGameReliability } from './game-reliability.js';
 
 // Map any reasonable spelling of a game event onto the internal handler
 // name: 'game:player_joined' / 'player_joined' / 'playerJoined' → 'playerJoined'.
@@ -28,6 +29,8 @@ const _EVENT_ALIASES = {
   reconnect: 'reconnect',
   connection_error: 'connectionError',
   room_assigned: 'roomAssigned',
+  connection_state: 'connectionState',
+  reconnected: 'reconnected',
 };
 
 function _normalizeEventName(event) {
@@ -241,6 +244,8 @@ export function createGameModule(Usion) {
   applyGameProxy(game, Usion);
   applyGameMethods(game, Usion);
   applyGameNetcode(game, Usion);
+  // Applied last: wraps connect/connectDirect and rides dispatched events.
+  applyGameReliability(game, Usion);
 
   // Foreground catch-up safety net (generic across every transport).
   //

package/src/modules/game-methods.js

@@ -71,7 +71,15 @@ export function applyGameMethods(game, Usion) {
           self._joined = true;
           if (response.sequence !== undefined) {
             self._lastSequence = response.sequence;
+            // The joined state reflects everything up to this sequence —
+            // actions at or below it must not be re-delivered (same
+            // baseline the proxy transport sets from GAME_JOINED).
+            self._lastActionApplied = Math.max(self._lastActionApplied, response.sequence);
           }
+          // Transport parity: proxy and direct modes dispatch 'joined';
+          // the socket transport now does too, so onJoined / recovery
+          // logic behaves the same everywhere.
+          self._dispatch('joined', response);
           resolve(response);
         }
       });

package/src/modules/game-reliability.js

@@ -0,0 +1,278 @@
+/**
+ * Usion SDK Game Reliability — the reconnection-lifecycle surface promised in
+ * v2.16: sequence getters, the unified connection-state machine, and
+ * syncedState (reconnect-safe authoritative shared state).
+ *
+ * Everything here rides the events the game module already dispatches
+ * ('disconnect' / 'reconnect' / 'joined' / 'sync' / 'action'), so it behaves
+ * identically across the socket, embedded-proxy, and direct transports.
+ */
+
+export function applyGameReliability(game, Usion) {
+  // ── Sequence getters ──────────────────────────────────────────────────────
+
+  /** Highest action sequence seen (from joins, syncs, and live actions). */
+  game.getLastSequence = function () { return this._lastSequence || 0; };
+
+  /** Highest action sequence applied locally; trails while catching up. */
+  game.getLastAppliedSequence = function () { return this._lastActionApplied || 0; };
+
+  // ── Connection-state machine ──────────────────────────────────────────────
+  // connected → disconnected → rejoining → reconnected → connected.
+  // 'reconnected' is a transient notification state: observers see it, then
+  // the machine settles back to 'connected' in the same tick.
+
+  game._connState = 'disconnected';
+  game._awaitResync = false;
+
+  game._setConnState = function (state) {
+    if (this._connState === state) return;
+    this._connState = state;
+    this._dispatch('connectionState', state);
+  };
+
+  /** Current connection state, synchronously. */
+  game.getConnectionState = function () { return this._connState; };
+
+  /**
+   * Observe connection-state transitions — one hook to drive a
+   * "Reconnecting…" overlay and gate input, identical on every transport.
+   * Single handler (last wins); returns an unsubscribe fn. For multiple
+   * listeners use game.on('connectionState', cb).
+   */
+  game.onConnectionState = function (callback) { return this._setHandler('connectionState', callback); };
+
+  /**
+   * Fires once per reconnect, after the resync completes, with
+   * { state, lastSequence, viaSync }. Restore local state here — it does NOT
+   * fire for a manually-requested sync.
+   */
+  game.onReconnected = function (callback) { return this._setHandler('reconnected', callback); };
+
+  game.on('disconnect', function () {
+    game._awaitResync = false;
+    game._setConnState('disconnected');
+  });
+
+  game.on('reconnect', function () {
+    if (game.roomId) {
+      game._awaitResync = true;
+      game._setConnState('rejoining');
+    } else {
+      game._setConnState('connected');
+    }
+  });
+
+  game.on('sync', function (data) {
+    if (!game._awaitResync) return;
+    game._awaitResync = false;
+    game._dispatch('reconnected', {
+      state: (data && data.game_state) || null,
+      lastSequence: game._lastSequence || 0,
+      viaSync: true,
+    });
+    game._setConnState('reconnected');
+    game._setConnState('connected');
+  });
+
+  // Transport-level connects (initial connect in every mode) resolve through
+  // connect()/connectDirect() — reflect them in the state machine.
+  function wrapConnect(name) {
+    var orig = game[name];
+    if (typeof orig !== 'function') return;
+    game[name] = function () {
+      var self = this;
+      return orig.apply(self, arguments).then(function (result) {
+        if (!self._awaitResync) self._setConnState('connected');
+        return result;
+      });
+    };
+  }
+  wrapConnect('connect');
+  wrapConnect('connectDirect');
+
+  // ── Host tracking ─────────────────────────────────────────────────────────
+  // Kept on the game module (registered at module creation, so it never
+  // misses an event) — a syncedState created AFTER the join still knows who
+  // the authority is.
+
+  game._hostId = null;
+  function trackHost(d) {
+    if (!d) return;
+    if (d.host_id) game._hostId = d.host_id;
+    else if (d.player_ids && d.player_ids.length) game._hostId = d.player_ids[0];
+  }
+  game.on('joined', trackHost);
+  game.on('playerJoined', trackHost);
+
+  // ── syncedState ───────────────────────────────────────────────────────────
+
+  /**
+   * Reconnect-safe authoritative shared state. Commits are sequenced actions
+   * applied through `reduce` on every client in the same order (deduped by
+   * sequence); the authority (player_ids[0] by default) auto-checkpoints via
+   * setState, and (re)joining clients recover automatically (checkpoint +
+   * un-checkpointed tail). Degrades to local-apply in direct mode.
+   * Full contract: SyncedStateOptions / SyncedState in types/index.d.ts.
+   */
+  game.syncedState = function (initial, opts) {
+    opts = opts || {};
+    var self = this;
+    var reduce = typeof opts.reduce === 'function'
+      ? opts.reduce
+      : function (state, action) { return Object.assign({}, state, action.data); };
+    var checkpointEvery = opts.checkpointEvery != null ? opts.checkpointEvery : 1;
+    var authorityMode = opts.authority === 'all' ? 'all' : 'host';
+    var defaultType = opts.type || 'update';
+
+    var state = initial === undefined ? {} : initial;
+    var appliedSeq = 0;
+    var sinceCheckpoint = 0;
+    var lastGapRequest = -1;
+    var changeCbs = [];
+    var offs = [];
+
+    function notify(reason) {
+      var copy = changeCbs.slice();
+      for (var i = 0; i < copy.length; i++) {
+        try { copy[i](state, reason); } catch (e) { Usion.log('syncedState onChange error: ' + e.message); }
+      }
+    }
+
+    function isAuthority() {
+      if (authorityMode === 'all') return true;
+      var me = self.playerId || (Usion.user && Usion.user.getId && Usion.user.getId());
+      return !!(me && self._hostId && me === self._hostId);
+    }
+
+    function doCheckpoint() {
+      if (self.directMode) {
+        return Promise.resolve({ success: false, error: 'not_supported_in_direct_mode' });
+      }
+      // The wrapper carries the sequence the checkpoint reflects, so recovery
+      // knows exactly where the un-checkpointed tail starts.
+      return self.setState({ __usionSyncedState: 1, seq: appliedSeq, state: state });
+    }
+
+    function maybeAutoCheckpoint() {
+      if (!(checkpointEvery > 0) || !isAuthority()) return;
+      sinceCheckpoint += 1;
+      if (sinceCheckpoint >= checkpointEvery) {
+        sinceCheckpoint = 0;
+        doCheckpoint();
+      }
+    }
+
+    function applyOne(playerId, type, data, sequence) {
+      if (sequence !== undefined && sequence <= appliedSeq) return false; // dedupe
+      var next;
+      try {
+        next = reduce(state, { playerId: playerId, type: type, data: data, sequence: sequence });
+      } catch (e) {
+        Usion.log('syncedState reduce error: ' + e.message);
+        return false;
+      }
+      if (next !== undefined) state = next;
+      if (sequence !== undefined) appliedSeq = sequence;
+      return true;
+    }
+
+    function onAction(d) {
+      if (!d) return;
+      if (applyOne(d.player_id, d.action_type, d.action_data, d.sequence)) {
+        notify('action');
+        maybeAutoCheckpoint();
+      }
+    }
+
+    // Recover from a join ack or sync payload: load the checkpoint (if it is
+    // ours and newer), replay the action tail in order, and if the server's
+    // sequence is still ahead of us, ask once for the missing range.
+    function recover(d) {
+      if (!d) return;
+      var changed = false;
+
+      var gs = d.game_state;
+      if (gs && gs.__usionSyncedState && typeof gs.seq === 'number'
+          && gs.seq >= appliedSeq && gs.state !== undefined) {
+        state = gs.state;
+        appliedSeq = gs.seq;
+        changed = true;
+      }
+
+      var actions = d.actions;
+      if (actions && actions.length) {
+        var sorted = actions.slice().sort(function (a, b) {
+          return (a.sequence || 0) - (b.sequence || 0);
+        });
+        for (var i = 0; i < sorted.length; i++) {
+          var item = sorted[i];
+          if (item && applyOne(item.player_id, item.action_type, item.action_data, item.sequence)) {
+            changed = true;
+          }
+        }
+      }
+
+      if (changed) notify('recover');
+
+      // Gap fill: the checkpoint may lag the room sequence (checkpointEvery>1).
+      // Request the tail from OUR applied sequence — once per position, so a
+      // trimmed history can't loop us.
+      if (d.sequence !== undefined && d.sequence > appliedSeq && lastGapRequest !== appliedSeq) {
+        lastGapRequest = appliedSeq;
+        try { self.requestSync(appliedSeq); } catch (e) { /* non-fatal */ }
+      }
+    }
+
+    offs.push(self.on('action', onAction));
+    offs.push(self.on('sync', recover));
+    offs.push(self.on('joined', recover));
+
+    return {
+      /** Current state value. */
+      get: function () { return state; },
+
+      /**
+       * Commit a change: commit(data) with the default action type, or
+       * commit(type, data, opts) to name it (opts forwarded to game.action,
+       * e.g. nextTurn / queueOffline). Applied exactly once via the echo.
+       */
+      commit: function (typeOrData, data, actionOpts) {
+        var t, payload, o;
+        if (typeof typeOrData === 'string') { t = typeOrData; payload = data; o = actionOpts; }
+        else { t = defaultType; payload = typeOrData; o = data; }
+        if (self.directMode) {
+          // No platform echo in direct mode — apply locally, then send.
+          if (applyOne(self.playerId, t, payload, undefined)) notify('action');
+          return self.action(t, payload, o);
+        }
+        return self.action(t, payload, o);
+      },
+
+      /** Subscribe to changes: cb(state, reason). Returns an unsubscribe fn. */
+      onChange: function (cb) {
+        changeCbs.push(cb);
+        return function () {
+          var i = changeCbs.indexOf(cb);
+          if (i >= 0) changeCbs.splice(i, 1);
+        };
+      },
+
+      /** Whether this client is the checkpointing authority. */
+      isAuthority: isAuthority,
+
+      /** Force a server checkpoint now (no-op result in direct mode). */
+      checkpoint: function () { return doCheckpoint(); },
+
+      /** Sequence of the last action applied into this state. */
+      getSequence: function () { return appliedSeq; },
+
+      /** Detach all listeners; the instance stops receiving updates. */
+      destroy: function () {
+        for (var i = 0; i < offs.length; i++) { try { offs[i](); } catch (e) { /* noop */ } }
+        offs.length = 0;
+        changeCbs.length = 0;
+      },
+    };
+  };
+}

package/src/modules/game-socket.js

@@ -44,7 +44,20 @@ export function applyGameSocket(game, Usion) {
       // backend channel — robust to listener registration order.
       if (Usion._bindBackendSocket) Usion._bindBackendSocket(self.socket);
 
+      // Socket.IO v4 emits 'reconnect' on the Manager, not the Socket — a
+      // Socket-level 'reconnect' listener never fires. Track attempts on the
+      // Manager and treat any connect after the first (per socket) as the
+      // reconnect signal, dispatched below AFTER rejoin gating is in place.
+      var hadConnect = false;
+      if (self.socket.io && typeof self.socket.io.on === 'function') {
+        self.socket.io.on('reconnect_attempt', function(n) {
+          self._reconnAttempts = n;
+        });
+      }
+
       self.socket.on('connect', function() {
+        var isReconnect = hadConnect;
+        hadConnect = true;
         self.connected = true;
         self._connecting = false;
         Usion.log('Game socket connected');
@@ -75,12 +88,21 @@ export function applyGameSocket(game, Usion) {
             .then(function() {
               self._rejoinPromise = null;
               // Send any moves queued while offline, now that membership
-              // and sync are restored. (Socket.IO v4 emits 'reconnect' on
-              // the Manager, not the Socket, so this is the reliable hook.)
+              // and sync are restored. (This connect handler is the reliable
+              // hook — see the Manager-vs-Socket note above.)
               if (self._flushOfflineQueue) self._flushOfflineQueue();
             });
         }
 
+        // Dispatched after _rejoinPromise is set, so anything reacting to
+        // 'reconnect' (offline-queue flush, connection-state machine) sees
+        // sends gated behind the rejoin+resync.
+        if (isReconnect) {
+          Usion.log('Game socket reconnected');
+          self._dispatch('reconnect', self._reconnAttempts || 1);
+          self._reconnAttempts = 0;
+        }
+
         resolve();
       });
 
@@ -103,11 +125,6 @@ export function applyGameSocket(game, Usion) {
         self._dispatch('disconnect', reason);
       });
 
-      self.socket.on('reconnect', function(attemptNumber) {
-        Usion.log('Game socket reconnected after ' + attemptNumber + ' attempts');
-        self._dispatch('reconnect', attemptNumber);
-      });
-
       // Game event handlers
       self.socket.on('game:joined', function(data) {
         if (data.sequence !== undefined) {

package/types/index.d.ts

@@ -274,6 +274,60 @@ export interface GameInviteResult {
   invited: string[];
 }
 
+/** Unified connection-state machine, identical across all transports. */
+export type GameConnectionState = 'connected' | 'disconnected' | 'rejoining' | 'reconnected';
+
+/** Payload of game.onReconnected — fires once after a reconnect's resync. */
+export interface ReconnectedInfo {
+  /** The server checkpoint from the resync (may be empty). */
+  state: Record<string, any> | null;
+  /** Highest action sequence after the resync. */
+  lastSequence: number;
+  /** True when recovery came through a game:sync payload. */
+  viaSync: boolean;
+}
+
+/** An action as seen by a syncedState reducer. */
+export interface SyncedStateAction {
+  playerId: string;
+  type: string;
+  data: any;
+  /** Authoritative sequence; undefined only for direct-mode local applies. */
+  sequence: number | undefined;
+}
+
+/** Options for game.syncedState(). */
+export interface SyncedStateOptions<S = Record<string, any>> {
+  /** Pure reducer applied to every action; default shallow-merges action.data. */
+  reduce?: (state: S, action: SyncedStateAction) => S;
+  /** Authority checkpoint cadence in actions (1 = every action; 0 disables). */
+  checkpointEvery?: number;
+  /** Who checkpoints: 'host' (player_ids[0], default) or 'all' participants. */
+  authority?: 'host' | 'all';
+  /** Default action type used by commit(data) (default 'update'). */
+  type?: string;
+}
+
+/** Reconnect-safe authoritative shared state (see game.syncedState). */
+export interface SyncedState<S = Record<string, any>> {
+  /** Current state value. */
+  get(): S;
+  /** Commit with the default action type. Applied exactly once via the echo. */
+  commit(data: Record<string, any>): Promise<ActionResult>;
+  /** Commit a named action; opts forwarded to game.action (nextTurn, …). */
+  commit(type: string, data?: Record<string, any>, opts?: GameActionOptions): Promise<ActionResult>;
+  /** Subscribe to changes: cb(state, reason). Returns an unsubscribe fn. */
+  onChange(callback: (state: S, reason: 'action' | 'recover') => void): UnsubscribeFn;
+  /** Whether this client is the checkpointing authority. */
+  isAuthority(): boolean;
+  /** Force a server checkpoint now (no-op result in direct mode). */
+  checkpoint(): Promise<{ success: boolean; error?: string; code?: UsionErrorCode }>;
+  /** Sequence of the last action applied into this state. */
+  getSequence(): number;
+  /** Detach all listeners; the instance stops receiving updates. */
+  destroy(): void;
+}
+
 export interface GameModule {
   // Connection
   connect(socketUrl?: string, token?: string): Promise<void>;
@@ -368,6 +422,36 @@ export interface GameModule {
    */
   onRoomAssigned(callback: (data: { roomId: string }) => void): UnsubscribeFn;
 
+  // ─── Reconnection lifecycle (SDK ≥ 2.21; documented since 2.16) ──────────
+  /** Highest action sequence seen (joins, syncs, live actions). */
+  getLastSequence(): number;
+  /** Highest action sequence applied locally; trails while catching up. */
+  getLastAppliedSequence(): number;
+  /** Current connection state, synchronously. */
+  getConnectionState(): GameConnectionState;
+  /**
+   * Observe connection-state transitions ('connected' → 'disconnected' →
+   * 'rejoining' → 'reconnected' → 'connected') — identical across the socket,
+   * embedded-proxy, and direct transports. One hook to drive a
+   * "Reconnecting…" overlay and gate input.
+   */
+  onConnectionState(callback: (state: GameConnectionState) => void): UnsubscribeFn;
+  /**
+   * Fires once per reconnect, after the resync completes. Restore local
+   * state here — it does NOT fire for a manually-requested sync.
+   */
+  onReconnected(callback: (info: ReconnectedInfo) => void): UnsubscribeFn;
+  /**
+   * Reconnect-safe authoritative shared state. Commits are sequenced actions
+   * applied through `reduce` on every client in the same order (deduped by
+   * sequence); the authority (player_ids[0] by default) auto-checkpoints via
+   * setState, and (re)joining clients recover automatically (load checkpoint,
+   * replay the un-checkpointed tail). Use for state that must survive a
+   * disconnect — unlike replicate() (realtime, lossy). Degrades to
+   * local-apply in direct mode (no platform checkpoint there).
+   */
+  syncedState<S = Record<string, any>>(initial: S, opts?: SyncedStateOptions<S>): SyncedState<S>;
+
   /**
    * Register an ADDITIONAL event listener. Unlike the onX methods this
    * supports multiple listeners per event, can be called before connect(),