@usions/sdk 2.0.1 → 2.1.0

package/src/browser.js

@@ -1,30 +1,29 @@
-/**
- * Usion Mini App SDK v2.0
- * 
- * JavaScript utilities for Mini Apps (Iframe Games & Services)
- * Import via: <script src="https://usions.com/usion-sdk.js"></script>
- * 
- * Features:
- * - User info and authentication
- * - Persistent storage (per-user, per-service)
- * - Wallet/payment integration
- * - Session management
- * - Real-time game support via Socket.IO
- */
-
-(function(global) {
+var Usion = (function () {
   'use strict';
 
+  /**
+   * Usion SDK Core — init, _post, _request, message handling
+   */
+
   // Request ID counter for tracking async responses
   let _requestId = 0;
   const _pendingRequests = {};
 
-  const Usion = {
-    version: '2.0.1',
+  function getNextRequestId() {
+    return ++_requestId;
+  }
+
+  /**
+   * Core Usion object with init, _post, _request
+   */
+  const core = {
+    version: '2.1.0',
     config: {},
     _initialized: false,
     _initCallback: null,
     _messageHandlerRegistered: false,
+    _results: [],
+    _backButtonCallback: null,
 
     /**
      * Initialize the SDK with config from parent app
@@ -32,22 +31,22 @@
      */
     init: function(callback) {
       const self = this;
-      
+
       // Prevent double initialization - just update callback
       if (self._initialized) {
         if (callback) callback(self.config);
         return;
       }
-      
+
       // Store callback for when config arrives
       self._initCallback = callback;
-      
+
       // Only register message handler once
       if (self._messageHandlerRegistered) {
         return;
       }
       self._messageHandlerRegistered = true;
-      
+
       // Setup global message handler
       window.addEventListener('message', function(event) {
         let data;
@@ -63,12 +62,12 @@
           if (self._initialized) {
             return;
           }
-          
+
           self.config = data.config;
           self._initialized = true;
-          // We received INIT from a parent → we are embedded (iframe or WebView)
+          // We received INIT from a parent -> we are embedded (iframe or WebView)
           self._isEmbedded = true;
-          
+
           // Initialize user module with config data
           if (data.config.userId) {
             self.user._id = data.config.userId;
@@ -76,36 +75,41 @@
             self.user._avatar = data.config.userAvatar;
             self.user._token = data.config.authToken;
           }
-          
+
           // Initialize session module
           if (data.config.sessionId) {
             self.session._id = data.config.sessionId;
             self.session._data = data.config.sessionData || {};
           }
-          
+
           // Initialize wallet with balance if provided
           if (data.config.balance !== undefined) {
             self.wallet._balance = data.config.balance;
           }
-          
+
+          // Initialize results from server
+          if (data.config.results) {
+            self._results = data.config.results;
+          }
+
           // Call the stored init callback
           if (self._initCallback) {
             self._initCallback(data.config);
           }
         }
-        
+
         // Handle response messages for async requests
         if (data._requestId && _pendingRequests[data._requestId]) {
           const { resolve, reject } = _pendingRequests[data._requestId];
           delete _pendingRequests[data._requestId];
-          
+
           if (data.error) {
             reject(new Error(data.error));
           } else {
             resolve(data);
           }
         }
-        
+
         // Handle balance updates
         if (data.type === 'BALANCE_UPDATE') {
           self.wallet._balance = data.balance;
@@ -113,25 +117,53 @@
             self.wallet._balanceChangeHandler(data.balance);
           }
         }
+
+        // Handle back button pressed (one-time claim)
+        if (data.type === 'BACK_BUTTON_PRESSED' && self._backButtonCallback) {
+          var cb = self._backButtonCallback;
+          self._backButtonCallback = null; // one-time use
+          cb();
+        }
+
+        // Handle bot messages forwarded from host app
+        if (data.type === 'BOT_MESSAGE' && self.bot && self.bot._messageHandler) {
+          self.bot._messageHandler(data.message);
+        }
       });
 
       // Signal ready to parent
       this._post({ type: 'READY' });
     },
 
+    /**
+     * Get the current theme ('light' or 'dark')
+     * @returns {string}
+     */
+    getTheme: function() {
+      return this.config.theme || 'light';
+    },
+
+    /**
+     * Get the current language/locale (e.g. 'en', 'mn')
+     * @returns {string}
+     */
+    getLanguage: function() {
+      return this.config.language || 'en';
+    },
+
     /**
      * Send message to parent app
      * @private
      */
     _post: function(message) {
       const msg = JSON.stringify(message);
-      
+
       // React Native WebView
       if (window.ReactNativeWebView) {
         window.ReactNativeWebView.postMessage(msg);
         return;
       }
-      
+
       // Web iframe
       if (window.parent !== window) {
         window.parent.postMessage(message, '*');
@@ -145,16 +177,16 @@
     _request: function(type, data, timeout) {
       const self = this;
       timeout = timeout || 5000;
-      
+
       return new Promise(function(resolve, reject) {
-        const requestId = ++_requestId;
-        
+        const requestId = getNextRequestId();
+
         // Setup timeout
         const timer = setTimeout(function() {
           delete _pendingRequests[requestId];
           reject(new Error('Request timeout'));
         }, timeout);
-        
+
         // Store pending request
         _pendingRequests[requestId] = {
           resolve: function(result) {
@@ -166,7 +198,7 @@
             reject(error);
           }
         };
-        
+
         // Send request
         self._post({
           type: type,
@@ -174,16 +206,18 @@
           ...data
         });
       });
-    },
+    }
+  };
 
-    // ============================================
-    // User Module
-    // ============================================
+  /**
+   * Usion SDK User Module — user info and authentication
+   */
 
-    /**
-     * User information and authentication
-     */
-    user: {
+  /**
+   * @param {object} Usion - Reference to the main Usion object
+   */
+  function createUserModule(Usion) {
+    return {
       _id: null,
       _name: null,
       _avatar: null,
@@ -234,16 +268,18 @@
           };
         });
       }
-    },
-
-    // ============================================
-    // Storage Module
-    // ============================================
-
-    /**
-     * Persistent storage (per-user, per-service)
-     */
-    storage: {
+    };
+  }
+
+  /**
+   * Usion SDK Storage Module — persistent storage (per-user, per-service)
+   */
+
+  /**
+   * @param {object} Usion - Reference to the main Usion object
+   */
+  function createStorageModule(Usion) {
+    return {
       /**
        * Get a stored value
        * @param {string} key - Storage key
@@ -297,16 +333,19 @@
           return response.keys || [];
         });
       }
-    },
+    };
+  }
 
-    // ============================================
-    // Wallet Module
-    // ============================================
+  /**
+   * Usion SDK Wallet Module — wallet and payment operations
+   */
 
-    /**
-     * Wallet and payment operations
-     */
-    wallet: {
+
+  /**
+   * @param {object} Usion - Reference to the main Usion object
+   */
+  function createWalletModule(Usion) {
+    return {
       _balance: null,
       _balanceChangeHandler: null,
 
@@ -316,12 +355,12 @@
        */
       getBalance: function() {
         const self = this;
-        
+
         // If we have cached balance, return it
         if (self._balance !== null) {
           return Promise.resolve(self._balance);
         }
-        
+
         return Usion._request('GET_BALANCE', {}).then(function(response) {
           self._balance = response.balance;
           return response.balance;
@@ -348,9 +387,9 @@
        */
       requestPayment: function(amount, reason, data) {
         const self = this;
-        
+
         return new Promise(function(resolve, reject) {
-          const requestId = ++_requestId;
+          const requestId = getNextRequestId();
           const timeoutMs = 60000;
 
           // Listen for response
@@ -408,16 +447,18 @@
       onBalanceChange: function(callback) {
         this._balanceChangeHandler = callback;
       }
-    },
-
-    // ============================================
-    // Session Module
-    // ============================================
-
-    /**
-     * Session management (ephemeral data for current session)
-     */
-    session: {
+    };
+  }
+
+  /**
+   * Usion SDK Session Module — ephemeral session data management
+   */
+
+  /**
+   * @param {object} Usion - Reference to the main Usion object
+   */
+  function createSessionModule(Usion) {
+    return {
       _id: null,
       _data: {},
 
@@ -452,7 +493,7 @@
         } else {
           this._data[keyOrData] = value;
         }
-        
+
         // Notify parent of session data change
         Usion._post({
           type: 'SESSION_DATA_UPDATE',
@@ -469,132 +510,24 @@
           type: 'SESSION_DATA_CLEAR'
         });
       }
-    },
-
-    // ============================================
-    // Legacy Payment Method (for backwards compatibility)
-    // ============================================
-
-    /**
-     * Request payment from user (legacy method)
-     * @deprecated Use Usion.wallet.requestPayment instead
-     */
-    requestPayment: function(amount, reason, data) {
-      return this.wallet.requestPayment(amount, reason, data);
-    },
-
-    /**
-     * Submit result and signal completion
-     * @param {object} data - Result data to send to parent
-     */
-    submit: function(data) {
-      this._post({
-        type: 'SUBMIT',
-        data: data
-      });
-    },
-
-    /**
-     * Report an error to parent app
-     * @param {string} message - Error message
-     */
-    error: function(message) {
-      this._post({
-        type: 'ERROR',
-        message: message
-      });
-    },
-
-    /**
-     * Request to close the mini app
-     */
-    exit: function() {
-      this._post({ type: 'EXIT' });
-    },
-
-    /**
-     * Share content through the app's native share and optionally post to Usions feed
-     * 
-     * @param {string} contentType - Type of content: 'audio' | 'image' | 'video' | 'text' | 'mixed'
-     * @param {object} data - Content data to share:
-     *   - text: Optional text/caption for the post
-     *   - audioUrl: URL for audio content (when contentType is 'audio')
-     *   - imageUrl: URL for image content (when contentType is 'image')
-     *   - videoUrl: URL for video content (when contentType is 'video')
-     *   - thumbnailUrl: Optional thumbnail URL for video/audio
-     *   - width: Optional width for image/video
-     *   - height: Optional height for image/video
-     *   - duration: Optional duration in seconds for audio/video
-     *   - media: Array of media items for 'mixed' content type
-     *     - Each item: { type: 'image'|'video'|'audio', url: string, thumbnailUrl?, width?, height?, duration? }
-     * 
-     * @example
-     * // Share audio
-     * Usion.share('audio', { 
-     *   text: 'Check out this AI voice!', 
-     *   audioUrl: 'https://cdn.example.com/audio.mp3',
-     *   duration: 5.2
-     * });
-     * 
-     * @example
-     * // Share image
-     * Usion.share('image', { 
-     *   text: 'AI-generated art', 
-     *   imageUrl: 'https://cdn.example.com/image.webp',
-     *   thumbnailUrl: 'https://cdn.example.com/thumb.webp',
-     *   width: 1024,
-     *   height: 1024
-     * });
-     * 
-     * @example
-     * // Share video
-     * Usion.share('video', {
-     *   text: 'My AI video creation',
-     *   videoUrl: 'https://cdn.example.com/video.mp4',
-     *   thumbnailUrl: 'https://cdn.example.com/poster.jpg',
-     *   duration: 30
-     * });
-     * 
-     * @example
-     * // Share mixed content (multiple media)
-     * Usion.share('mixed', {
-     *   text: 'Gallery of AI creations',
-     *   media: [
-     *     { type: 'image', url: 'https://cdn.example.com/1.webp' },
-     *     { type: 'image', url: 'https://cdn.example.com/2.webp' },
-     *     { type: 'video', url: 'https://cdn.example.com/video.mp4', thumbnailUrl: '...' }
-     *   ]
-     * });
-     */
-    share: function(contentType, data) {
-      var shareData = Object.assign({}, data, {
-        contentType: contentType,
-        serviceId: this.config.serviceId,
-        serviceName: this.config.serviceName
-      });
-      
-      this._post({
-        type: 'SHARE',
-        contentType: contentType,
-        data: shareData
-      });
-    },
-
-    // ============================================
-    // Chat
-    // ============================================
-
-    chat: {
+    };
+  }
+
+  /**
+   * Usion SDK Chat Module — messaging between users
+   */
+
+  /**
+   * @param {object} Usion - Reference to the main Usion object
+   */
+  function createChatModule(Usion) {
+    return {
       /**
        * Request to send a message to another user.
        * The parent app will show a confirmation prompt to the user.
        * @param {string} recipientId - Usion user ID of the recipient
        * @param {string} message - Message content to send
        * @returns {Promise<{success: boolean, reason?: string}>}
-       *
-       * @example
-       * const result = await Usion.chat.sendMessage('user_abc', '👋');
-       * if (result.success) console.log('Message sent!');
        */
       sendMessage: function(recipientId, message) {
         return Usion._request('SEND_MESSAGE_REQUEST', {
@@ -613,44 +546,129 @@
           peerUserId: peerUserId
         });
       }
-    },
+    };
+  }
 
-    /**
-     * Log message to native console (for debugging)
-     * @param {string} msg - Message to log
-     */
-    log: function(msg) {
-      this._post({
-        type: 'LOG',
-        msg: msg
-      });
-      console.log('[Usion]', msg);
-    },
+  /**
+   * Usion SDK Bot Bridge — for inline bot iframes
+   */
 
-    /**
-     * Listen for messages from parent app
-     * @param {string} type - Message type to listen for
-     * @param {function} callback - Handler function
-     */
-    on: function(type, callback) {
-      window.addEventListener('message', function(event) {
-        let data;
-        try {
-          data = typeof event.data === 'string' ? JSON.parse(event.data) : event.data;
-        } catch (e) {
-          return;
-        }
+  function createBotModule(Usion) {
+    return {
+      _messageHandler: null,
 
-        if (data.type === type) {
-          callback(data);
-        }
-      });
-    },
+      /**
+       * Call a bot action. Delivered as an "iframe_action" webhook to the bot's server.
+       * @param {string} action - Action name (e.g., "submit_form", "select_item")
+       * @param {object} [data] - Action payload
+       * @returns {Promise} Resolves when the host app confirms delivery
+       */
+      callAction: function(action, data) {
+        return Usion._request('CALL_BOT', { action: action, data: data || {} }, 30000);
+      },
+
+      /**
+       * Send a message as if the user typed it. Triggers the normal bot webhook flow.
+       * @param {string} text - Message text
+       */
+      sendMessage: function(text) {
+        Usion._post({ type: 'SEND_USER_MESSAGE', text: text });
+      },
+
+      /**
+       * Update context metadata visible to the bot on the next webhook delivery.
+       * @param {object} ctx - Context key/value pairs
+       */
+      updateContext: function(ctx) {
+        Usion._post({ type: 'UPDATE_CONTEXT', context: ctx });
+      },
+
+      /**
+       * Close the iframe, optionally returning a result to the bot.
+       * @param {object} [result] - Optional result data
+       */
+      close: function(result) {
+        Usion._post({ type: 'CLOSE', result: result });
+      },
+
+      /**
+       * Listen for new bot messages in the conversation.
+       * Called whenever the bot sends a message (text, components, etc.).
+       * @param {function} callback - Called with { id, content, content_type, components, sender_id }
+       */
+      onMessage: function(callback) {
+        this._messageHandler = callback;
+      }
+    };
+  }
+
+  /**
+   * Usion SDK Results — server-side result persistence across devices
+   */
+
+  function createResultsMethods(Usion) {
+    return {
+      /**
+       * Save a result to server-side storage (persists across devices).
+       * @param {string} data - Result string (URL, JSON, etc.)
+       * @param {object} [metadata] - Optional metadata (thumbnail_url, title, type)
+       * @returns {Promise<object>} The saved result document
+       */
+      saveResult: function(data, metadata) {
+        return Usion._request('SAVE_RESULT', { data: data, metadata: metadata || {} }, 15000);
+      },
+
+      /**
+       * Delete a saved result by ID.
+       * @param {string} resultId - The result ID to delete
+       * @returns {Promise<void>}
+       */
+      deleteResult: function(resultId) {
+        return Usion._request('DELETE_RESULT', { resultId: resultId });
+      },
+
+      /**
+       * Get all saved results for this service (populated from INIT config).
+       * @returns {Array} Array of result objects
+       */
+      getResults: function() {
+        return Usion._results || [];
+      }
+    };
+  }
+
+  /**
+   * Usion SDK Back Button — claim/release host back button for in-app navigation
+   */
+
+  function createBackButtonMethods(Usion) {
+    return {
+      /**
+       * Claim the host app's back button for one-time in-app navigation.
+       * When claimed, pressing back sends BACK_BUTTON_PRESSED to the mini app
+       * instead of closing it. Automatically resets after one press.
+       * @param {function} callback - Called when the user presses the claimed back button
+       */
+      claimBackButton: function(callback) {
+        Usion._backButtonCallback = callback;
+        Usion._post({ type: 'CLAIM_BACK_BUTTON' });
+      },
 
-    // ============================================
-    // UI Utilities
-    // ============================================
+      /**
+       * Release a previously claimed back button, restoring default close behavior.
+       */
+      releaseBackButton: function() {
+        Usion._backButtonCallback = null;
+        Usion._post({ type: 'RELEASE_BACK_BUTTON' });
+      }
+    };
+  }
+
+  /**
+   * Usion SDK UI Utilities — DOM helpers for mini apps
+   */
 
+  const uiMethods = {
     /**
      * Set button to loading state
      * @param {HTMLElement|string} btn - Button element or selector
@@ -700,13 +718,13 @@
     charCount: function(input, counter, max) {
       const inputEl = typeof input === 'string' ? document.querySelector(input) : input;
       const counterEl = typeof counter === 'string' ? document.querySelector(counter) : counter;
-      
+
       if (!inputEl || !counterEl) return;
 
       function update() {
         const count = inputEl.value.length;
         counterEl.textContent = count + ' / ' + max;
-        
+
         counterEl.classList.remove('warning', 'error');
         if (count > max * 0.9) {
           counterEl.classList.add('error');
@@ -737,11 +755,11 @@
           container.querySelectorAll(itemSelector).forEach(function(i) {
             i.classList.remove('selected');
           });
-          
+
           // Select this one
           item.classList.add('selected');
           selected = item.dataset.value || item.dataset.id;
-          
+
           if (onChange) onChange(selected, item);
         });
       });
@@ -755,1025 +773,1206 @@
           selected = null;
         }
       };
+    }
+  };
+
+  /**
+   * Usion SDK Misc — submit, error, exit, share, log, on, requestPayment (legacy)
+   */
+
+  const miscMethods = {
+    /**
+     * Request payment from user (legacy method)
+     * @deprecated Use Usion.wallet.requestPayment instead
+     */
+    requestPayment: function(amount, reason, data) {
+      return this.wallet.requestPayment(amount, reason, data);
     },
 
-    // ============================================
-    // Game/Multiplayer Utilities
-    // ============================================
+    /**
+     * Submit result and signal completion
+     * @param {object} data - Result data to send to parent
+     */
+    submit: function(data) {
+      this._post({
+        type: 'SUBMIT',
+        data: data
+      });
+    },
 
     /**
-     * Game module for multiplayer real-time games
+     * Report an error to parent app
+     * @param {string} message - Error message
      */
-    game: {
-      socket: null,
-      directSocket: null,
-      roomId: null,
-      playerId: null,
-      connected: false,
-      directMode: false,
-      directConfig: null,
-      _directSeq: 0,
-      _eventHandlers: {},
-      _lastSequence: 0,
-      _connecting: false,
-      _connectPromise: null,
-      _joined: false,
-      _joinPromise: null,
-      _useProxy: false,
-      _proxyListenerSetup: false,
-      _heartbeatInterval: null,
+    error: function(message) {
+      this._post({
+        type: 'ERROR',
+        message: message
+      });
+    },
 
-      /**
-       * Connect to the game socket server
-       * @param {string} socketUrl - Socket.IO server URL (optional, uses config)
-       * @param {string} token - JWT auth token (optional, uses user.getToken())
-       * @returns {Promise} Resolves when connected
-       */
-      connect: function(socketUrl, token) {
-        const self = this;
-        var connectionMode = (Usion.config && Usion.config.connectionMode) || 'platform';
-        if (connectionMode === 'direct') {
-          return self.connectDirect();
-        }
-        
-        // Use config values as defaults
-        socketUrl = socketUrl || Usion.config.socketUrl;
-        token = token || Usion.user.getToken();
-        
-        if (!socketUrl) {
-          return Promise.reject(new Error('No socket URL provided'));
-        }
-        if (!token) {
-          return Promise.reject(new Error('No auth token available'));
-        }
-        
-        // If already connected (direct or proxy), return immediately
-        if (self._useProxy && self.connected) {
-          return Promise.resolve();
-        }
-        if (self.socket && self.connected) {
-          return Promise.resolve();
-        }
-        
-        // If currently connecting, return the existing promise
-        if (self._connecting && self._connectPromise) {
-          return self._connectPromise;
+    /**
+     * Request to close the mini app
+     * @param {object} [options] - Optional exit options
+     * @param {number} [options.backCount] - Number of screens to go back (default 1)
+     */
+    exit: function(options) {
+      var msg = { type: 'EXIT' };
+      if (options && typeof options.backCount === 'number' && options.backCount > 1) {
+        msg.backCount = options.backCount;
+      }
+      this._post(msg);
+    },
+
+    /**
+     * Share content through the app's native share and optionally post to Usions feed
+     *
+     * @param {string} contentType - Type of content: 'audio' | 'image' | 'video' | 'text' | 'mixed'
+     * @param {object} data - Content data to share:
+     *   - text: Optional text/caption for the post
+     *   - audioUrl: URL for audio content (when contentType is 'audio')
+     *   - imageUrl: URL for image content (when contentType is 'image')
+     *   - videoUrl: URL for video content (when contentType is 'video')
+     *   - thumbnailUrl: Optional thumbnail URL for video/audio
+     *   - width: Optional width for image/video
+     *   - height: Optional height for image/video
+     *   - duration: Optional duration in seconds for audio/video
+     *   - media: Array of media items for 'mixed' content type
+     *     - Each item: { type: 'image'|'video'|'audio', url: string, thumbnailUrl?, width?, height?, duration? }
+     */
+    share: function(contentType, data) {
+      var shareData = Object.assign({}, data, {
+        contentType: contentType,
+        serviceId: this.config.serviceId,
+        serviceName: this.config.serviceName
+      });
+
+      this._post({
+        type: 'SHARE',
+        contentType: contentType,
+        data: shareData
+      });
+    },
+
+    /**
+     * Download a file to the device's storage / gallery.
+     * @param {string} url - URL of the file to download
+     * @param {string} [filename] - Optional filename (default: 'download.mp4')
+     * @returns {Promise<{success: boolean, error?: string}>}
+     */
+    download: function(url, filename) {
+      return this._request('DOWNLOAD_FILE', {
+        url: url,
+        filename: filename || 'download.mp4'
+      });
+    },
+
+    /**
+     * Log message to native console (for debugging)
+     * @param {string} msg - Message to log
+     */
+    log: function(msg) {
+      this._post({
+        type: 'LOG',
+        msg: msg
+      });
+      console.log('[Usion]', msg);
+    },
+
+    /**
+     * Listen for messages from parent app
+     * @param {string} type - Message type to listen for
+     * @param {function} callback - Handler function
+     */
+    on: function(type, callback) {
+      window.addEventListener('message', function(event) {
+        let data;
+        try {
+          data = typeof event.data === 'string' ? JSON.parse(event.data) : event.data;
+        } catch (e) {
+          return;
         }
-        
-        // When running inside an iframe or WebView, always use the parent app
-        // as a socket proxy. The parent already has an authenticated socket
-        // connection, avoids CORS issues, and avoids mixed-content blocks.
-        // Detection order (first truthy wins):
-        //   (1) __USION_PROXY__ injected by parent before page load (most reliable)
-        //   (2) iframe check (window.parent !== window)
-        //   (3) ReactNativeWebView global
-        //   (4) _isEmbedded flag set when INIT message was received
-        var isInFrame = !!window.__USION_PROXY__
-                     || window.parent !== window
-                     || !!window.ReactNativeWebView
-                     || !!Usion._isEmbedded;
-        
-        if (isInFrame) {
-          Usion.log('Running in iframe – using parent app as socket proxy');
-          return self._connectViaProxy();
+
+        if (data.type === type) {
+          callback(data);
         }
-        
-        self._connecting = true;
-        self._connectPromise = new Promise(function(resolve, reject) {
-          // Check if socket.io-client is available
-          if (typeof io === 'undefined') {
-            // Load socket.io client – try local copy first, fallback to CDN
-            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() {
-                self._connecting = false;
-                reject(new Error('Failed to load Socket.IO client'));
-              };
-              document.head.appendChild(cdnScript);
-            };
-            document.head.appendChild(script);
-          } else {
-            self._initSocket(socketUrl, token, resolve, reject);
-          }
-        });
-        
-        return self._connectPromise;
+      });
+    }
+  };
+
+  /**
+   * Usion SDK File Storage — large binary data (IndexedDB / filesystem)
+   *
+   * Scoped per-user, per-service like regular storage.
+   * Uses IndexedDB (web) or filesystem (mobile) — no localStorage size limits.
+   */
+
+  function createFileStorageModule(sdk) {
+    return {
+      /**
+       * Store a file (base64 encoded)
+       * @param {string} key - Storage key
+       * @param {string} base64Data - Base64-encoded file content (no data: prefix)
+       * @param {string} mimeType - MIME type (e.g. 'image/png')
+       * @returns {Promise<void>}
+       */
+      set: function(key, base64Data, mimeType) {
+        return sdk._request('FILE_STORAGE_SET', {
+          key: key,
+          base64Data: base64Data,
+          mimeType: mimeType || 'application/octet-stream'
+        }, 30000).then(function() { return; });
       },
 
       /**
-       * Connect directly to creator-controlled WebSocket server.
-       * Uses backend-issued short-lived room token.
-       * @returns {Promise}
+       * Get a stored file
+       * @param {string} key - Storage key
+       * @returns {Promise<{base64Data: string, mimeType: string} | null>}
        */
-      connectDirect: function(config) {
-        var self = this;
-        config = config || {};
+      get: function(key) {
+        return sdk._request('FILE_STORAGE_GET', { key: key }, 30000).then(function(response) {
+          if (!response || !response.base64Data) return null;
+          return { base64Data: response.base64Data, mimeType: response.mimeType };
+        });
+      },
 
-        if (self.directMode && self.directSocket && self.connected) {
-          return Promise.resolve();
-        }
-        if (self._connecting && self._connectPromise) {
-          return self._connectPromise;
-        }
+      /**
+       * Remove a stored file
+       * @param {string} key - Storage key
+       * @returns {Promise<void>}
+       */
+      remove: function(key) {
+        return sdk._request('FILE_STORAGE_REMOVE', { key: key }).then(function() { return; });
+      }
+    };
+  }
+
+  /**
+   * Usion SDK Game Direct — WebSocket direct connection to game server
+   */
+
+  /**
+   * Add direct WebSocket connection methods to game module
+   * @param {object} game - The game module object
+   * @param {object} Usion - Reference to the main Usion object
+   */
+  function applyGameDirect(game, Usion) {
+    /**
+     * Connect directly to creator-controlled WebSocket server.
+     * Uses backend-issued short-lived room token.
+     * @returns {Promise}
+     */
+    game.connectDirect = function(config) {
+      var self = this;
+      config = config || {};
 
-        self._connecting = true;
-        self.directMode = true;
-        self._connectPromise = self._fetchDirectAccess(config)
-          .then(function(access) {
-            self.directConfig = access;
-            return self._initDirectSocket(access);
-          })
-          .then(function() {
-            self.connected = true;
-            self._connecting = false;
-            Usion.log('Direct game socket connected');
-          })
-          .catch(function(err) {
-            self._connecting = false;
-            self.connected = false;
-            self.directMode = false;
-            if (self._eventHandlers.connectionError) {
-              self._eventHandlers.connectionError(err);
-            }
-            throw err;
-          });
+      if (self.directMode && self.directSocket && self.connected) {
+        return Promise.resolve();
+      }
+      if (self._connecting && self._connectPromise) {
         return self._connectPromise;
-      },
+      }
 
-      _fetchDirectAccess: function(config) {
-        var roomId = config.roomId || this.roomId || Usion.config.roomId;
-        var serviceId = config.serviceId || Usion.config.serviceId;
-        var apiUrl = config.apiUrl || Usion.config.apiUrl || '';
-        var token = config.token || Usion.user.getToken();
-
-        if (!roomId) return Promise.reject(new Error('No room ID provided'));
-        if (!serviceId) return Promise.reject(new Error('No service ID provided'));
-        if (!apiUrl) return Promise.reject(new Error('No API URL provided'));
-        if (!token) return Promise.reject(new Error('No auth token available'));
-
-        this.roomId = roomId;
-        this.playerId = Usion.user.getId();
-
-        var cleanApiUrl = String(apiUrl).replace(/\/$/, '');
-        var endpoint = cleanApiUrl + '/games/rooms/' + encodeURIComponent(roomId) + '/access';
-        return fetch(endpoint, {
-          method: 'POST',
-          headers: {
-            'Content-Type': 'application/json',
-            'Authorization': 'Bearer ' + token
-          },
-          body: JSON.stringify({
-            service_id: serviceId,
-            client_type: 'iframe',
-            protocol_version: (config.protocolVersion || Usion.config.protocolVersion || Usion.config.protocol_version || '2')
-          })
-        }).then(function(res) {
-          if (!res.ok) {
-            return res.text().then(function(text) {
-              throw new Error(text || ('Direct access failed: HTTP ' + res.status));
-            });
+      self._connecting = true;
+      self.directMode = true;
+      self._connectPromise = self._fetchDirectAccess(config)
+        .then(function(access) {
+          self.directConfig = access;
+          return self._initDirectSocket(access);
+        })
+        .then(function() {
+          self.connected = true;
+          self._connecting = false;
+          Usion.log('Direct game socket connected');
+        })
+        .catch(function(err) {
+          self._connecting = false;
+          self.connected = false;
+          self.directMode = false;
+          if (self._eventHandlers.connectionError) {
+            self._eventHandlers.connectionError(err);
           }
-          return res.json();
+          throw err;
         });
-      },
+      return self._connectPromise;
+    };
+
+    game._fetchDirectAccess = function(config) {
+      var roomId = config.roomId || this.roomId || Usion.config.roomId;
+      var serviceId = config.serviceId || Usion.config.serviceId;
+      var apiUrl = config.apiUrl || Usion.config.apiUrl || '';
+      var token = config.token || Usion.user.getToken();
+
+      if (!roomId) return Promise.reject(new Error('No room ID provided'));
+      if (!serviceId) return Promise.reject(new Error('No service ID provided'));
+
+      this.roomId = roomId;
+      this.playerId = Usion.user.getId();
+
+      // When embedded (iframe/WebView), proxy through parent app to avoid
+      // CORS / Private Network Access issues
+      if (Usion._isEmbedded) {
+        return Usion._request('GAME_ACCESS_REQUEST', {
+          room_id: roomId,
+          service_id: serviceId,
+          protocol_version: (config.protocolVersion || Usion.config.protocolVersion || Usion.config.protocol_version || '2')
+        }, 10000);
+      }
 
-      _initDirectSocket: function(access) {
-        var self = this;
-        return new Promise(function(resolve, reject) {
-          if (!access || !access.ws_url || !access.access_token) {
-            reject(new Error('Invalid direct access payload'));
-            return;
-          }
+      if (!apiUrl) return Promise.reject(new Error('No API URL provided'));
+      if (!token) return Promise.reject(new Error('No auth token available'));
+
+      var cleanApiUrl = String(apiUrl).replace(/\/$/, '');
+      var endpoint = cleanApiUrl + '/games/rooms/' + encodeURIComponent(roomId) + '/access';
+      return fetch(endpoint, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'Authorization': 'Bearer ' + token
+        },
+        body: JSON.stringify({
+          service_id: serviceId,
+          client_type: 'iframe',
+          protocol_version: (config.protocolVersion || Usion.config.protocolVersion || Usion.config.protocol_version || '2')
+        })
+      }).then(function(res) {
+        if (!res.ok) {
+          return res.text().then(function(text) {
+            throw new Error(text || ('Direct access failed: HTTP ' + res.status));
+          });
+        }
+        return res.json();
+      });
+    };
 
-          var wsUrl = access.ws_url;
-          var separator = wsUrl.indexOf('?') === -1 ? '?' : '&';
-          var urlWithToken = wsUrl + separator + 'token=' + encodeURIComponent(access.access_token);
-          var ws = new WebSocket(urlWithToken);
-          self.directSocket = ws;
-
-          var opened = false;
-          var joinSent = false;
-          var timeout = setTimeout(function() {
-            if (!opened) {
-              try { ws.close(); } catch (e) {}
-              reject(new Error('Direct WebSocket connection timeout'));
+    game._initDirectSocket = function(access) {
+      var self = this;
+      return new Promise(function(resolve, reject) {
+        if (!access || !access.ws_url || !access.access_token) {
+          reject(new Error('Invalid direct access payload'));
+          return;
+        }
+
+        var wsUrl = access.ws_url;
+        var separator = wsUrl.indexOf('?') === -1 ? '?' : '&';
+        var urlWithToken = wsUrl + separator + 'token=' + encodeURIComponent(access.access_token);
+        var ws = new WebSocket(urlWithToken);
+        self.directSocket = ws;
+
+        var opened = false;
+        var joinSent = false;
+        var timeout = setTimeout(function() {
+          if (!opened) {
+            try { ws.close(); } catch (e) {}
+            reject(new Error('Direct WebSocket connection timeout'));
+          }
+        }, 10000);
+
+        ws.onopen = function() {
+          opened = true;
+          clearTimeout(timeout);
+          if (!joinSent) {
+            joinSent = true;
+            self._sendDirect('join', {});
+          }
+          // Start heartbeat for direct mode
+          if (self._heartbeatInterval) clearInterval(self._heartbeatInterval);
+          self._heartbeatInterval = setInterval(function() {
+            if (self.directSocket && self.directSocket.readyState === WebSocket.OPEN) {
+              self._sendDirect('heartbeat', {});
             }
-          }, 10000);
+          }, 25000);
+          resolve();
+        };
 
-          ws.onopen = function() {
-            opened = true;
+        ws.onerror = function() {
+          if (!opened) {
             clearTimeout(timeout);
-            if (!joinSent) {
-              joinSent = true;
-              self._sendDirect('join', {});
-            }
-            // Start heartbeat for direct mode
-            if (self._heartbeatInterval) clearInterval(self._heartbeatInterval);
-            self._heartbeatInterval = setInterval(function() {
-              if (self.directSocket && self.directSocket.readyState === WebSocket.OPEN) {
-                self._sendDirect('heartbeat', {});
-              }
-            }, 25000);
-            resolve();
-          };
+            reject(new Error('Direct WebSocket connection error'));
+          }
+        };
 
-          ws.onerror = function() {
-            if (!opened) {
-              clearTimeout(timeout);
-              reject(new Error('Direct WebSocket connection error'));
-            }
-          };
+        ws.onclose = function(evt) {
+          self.connected = false;
+          self._joined = false;
+          self._joinPromise = null;
+          if (self._heartbeatInterval) {
+            clearInterval(self._heartbeatInterval);
+            self._heartbeatInterval = null;
+          }
+          if (self._eventHandlers.disconnect) {
+            self._eventHandlers.disconnect(evt && evt.reason ? evt.reason : 'direct socket closed');
+          }
+        };
 
-          ws.onclose = function(evt) {
-            self.connected = false;
-            self._joined = false;
-            self._joinPromise = null;
-            if (self._heartbeatInterval) {
-              clearInterval(self._heartbeatInterval);
-              self._heartbeatInterval = null;
-            }
-            if (self._eventHandlers.disconnect) {
-              self._eventHandlers.disconnect(evt && evt.reason ? evt.reason : 'direct socket closed');
-            }
-          };
+        ws.onmessage = function(evt) {
+          self._handleDirectMessage(evt && evt.data);
+        };
+      });
+    };
+
+    game._sendDirect = function(type, payload) {
+      if (!this.directSocket || this.directSocket.readyState !== WebSocket.OPEN) return;
+      this._directSeq = this._directSeq + 1;
+      this.directSocket.send(JSON.stringify({
+        type: type,
+        room_id: this.roomId,
+        ts: Date.now(),
+        seq: this._directSeq,
+        session_id: (this.directConfig && this.directConfig.session_id) ? this.directConfig.session_id : null,
+        protocol_version: (this.directConfig && this.directConfig.protocol_version) ? this.directConfig.protocol_version : '2',
+        payload: payload || {}
+      }));
+    };
+
+    game._handleDirectMessage = function(raw) {
+      var data;
+      try {
+        data = typeof raw === 'string' ? JSON.parse(raw) : raw;
+      } catch (e) {
+        return;
+      }
+      if (!data || !data.type) return;
+      var payload = data.payload || {};
 
-          ws.onmessage = function(evt) {
-            self._handleDirectMessage(evt && evt.data);
-          };
-        });
-      },
+      if (data.type === 'joined') {
+        this._joined = true;
+        if (this._eventHandlers.joined) this._eventHandlers.joined(payload);
+        return;
+      }
+      if (data.type === 'player_joined') {
+        if (this._eventHandlers.playerJoined) this._eventHandlers.playerJoined(payload);
+        return;
+      }
+      if (data.type === 'player_left') {
+        if (this._eventHandlers.playerLeft) this._eventHandlers.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);
+        return;
+      }
+      if (data.type === 'pong') {
+        if (this._eventHandlers.sync) this._eventHandlers.sync(payload);
+        return;
+      }
+      if (data.type === 'match_end') {
+        if (this._eventHandlers.finished) this._eventHandlers.finished(payload);
+        return;
+      }
+      if (data.type === 'error' && this._eventHandlers.error) {
+        this._eventHandlers.error(payload);
+      }
+    };
+  }
+
+  /**
+   * Usion SDK Game Socket — Socket.IO connection management
+   */
+
+  /**
+   * Add Socket.IO connection methods to game module
+   * @param {object} game - The game module object
+   * @param {object} Usion - Reference to the main Usion object
+   */
+  function applyGameSocket(game, Usion) {
+    /**
+     * Initialize socket connection
+     * @private
+     */
+    game._initSocket = function(socketUrl, token, resolve, reject) {
+      const self = this;
 
-      _sendDirect: function(type, payload) {
-        if (!this.directSocket || this.directSocket.readyState !== WebSocket.OPEN) return;
-        this._directSeq = this._directSeq + 1;
-        this.directSocket.send(JSON.stringify({
-          type: type,
-          room_id: this.roomId,
-          ts: Date.now(),
-          seq: this._directSeq,
-          session_id: (this.directConfig && this.directConfig.session_id) ? this.directConfig.session_id : null,
-          protocol_version: (this.directConfig && this.directConfig.protocol_version) ? this.directConfig.protocol_version : '2',
-          payload: payload || {}
-        }));
-      },
+      // Prevent creating duplicate sockets
+      if (self.socket && self.socket.connected) {
+        self._connecting = false;
+        resolve();
+        return;
+      }
 
-      _handleDirectMessage: function(raw) {
-        var data;
-        try {
-          data = typeof raw === 'string' ? JSON.parse(raw) : raw;
-        } catch (e) {
-          return;
-        }
-        if (!data || !data.type) return;
-        var payload = data.payload || {};
+      // Clean up any existing disconnected socket
+      if (self.socket) {
+        self.socket.disconnect();
+        self.socket = null;
+      }
 
-        if (data.type === 'joined') {
-          this._joined = true;
-          if (this._eventHandlers.joined) this._eventHandlers.joined(payload);
-          return;
-        }
-        if (data.type === 'player_joined') {
-          if (this._eventHandlers.playerJoined) this._eventHandlers.playerJoined(payload);
-          return;
-        }
-        if (data.type === 'player_left') {
-          if (this._eventHandlers.playerLeft) this._eventHandlers.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);
-          return;
-        }
-        if (data.type === 'pong') {
-          if (this._eventHandlers.sync) this._eventHandlers.sync(payload);
-          return;
-        }
-        if (data.type === 'match_end') {
-          if (this._eventHandlers.finished) this._eventHandlers.finished(payload);
-          return;
-        }
-        if (data.type === 'error' && this._eventHandlers.error) {
-          this._eventHandlers.error(payload);
-        }
-      },
+      try {
+        self.socket = io(socketUrl, {
+          path: '/socket.io',
+          transports: ['websocket', 'polling'],
+          auth: { token: token },
+          autoConnect: true,
+          reconnection: true,
+          reconnectionAttempts: 50,
+          reconnectionDelay: 1000,
+          reconnectionDelayMax: 10000
+        });
 
-      /**
-       * Initialize socket connection
-       * @private
-       */
-      _initSocket: function(socketUrl, token, resolve, reject) {
-        const self = this;
-        
-        // Prevent creating duplicate sockets
-        if (self.socket && self.socket.connected) {
+        self.socket.on('connect', function() {
+          self.connected = true;
           self._connecting = false;
-          resolve();
-          return;
-        }
-        
-        // Clean up any existing disconnected socket
-        if (self.socket) {
-          self.socket.disconnect();
-          self.socket = null;
-        }
-        
-        try {
-          self.socket = io(socketUrl, {
-            path: '/socket.io',
-            transports: ['websocket', 'polling'],
-            auth: { token: token },
-            autoConnect: true,
-            reconnection: true,
-            reconnectionAttempts: 50,
-            reconnectionDelay: 1000,
-            reconnectionDelayMax: 10000
-          });
-
-          self.socket.on('connect', function() {
-            self.connected = true;
-            self._connecting = false;
-            Usion.log('Game socket connected');
-
-            // Start heartbeat to keep game session alive
-            if (self._heartbeatInterval) clearInterval(self._heartbeatInterval);
-            self._heartbeatInterval = setInterval(function() {
-              if (self.socket && self.connected && self.roomId) {
-                self.socket.emit('game:heartbeat', { room_id: self.roomId });
-              }
-            }, 25000);
-
-            // Re-join room after reconnect so this socket gets room broadcasts again
-            if (self.roomId) {
-              self._joined = false;
-              self._joinPromise = null;
-              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)));
-                });
-            }
-            
-            resolve();
-          });
+          Usion.log('Game socket connected');
 
-          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);
+          // Start heartbeat to keep game session alive
+          if (self._heartbeatInterval) clearInterval(self._heartbeatInterval);
+          self._heartbeatInterval = setInterval(function() {
+            if (self.socket && self.connected && self.roomId) {
+              self.socket.emit('game:heartbeat', { room_id: self.roomId });
             }
-            reject(err);
-          });
+          }, 25000);
 
-          self.socket.on('disconnect', function(reason) {
-            self.connected = false;
+          // Re-join room after reconnect
+          if (self.roomId) {
             self._joined = false;
             self._joinPromise = null;
-            if (self._heartbeatInterval) {
-              clearInterval(self._heartbeatInterval);
-              self._heartbeatInterval = null;
-            }
-            Usion.log('Game socket disconnected: ' + reason);
-            if (self._eventHandlers.disconnect) {
-              self._eventHandlers.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.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)));
+              });
+          }
 
-          // Game event handlers
-          self.socket.on('game:joined', function(data) {
-            if (data.sequence !== undefined) {
-              self._lastSequence = data.sequence;
-            }
-            if (self._eventHandlers.joined) {
-              self._eventHandlers.joined(data);
-            }
-          });
+          resolve();
+        });
 
-          self.socket.on('game:player_joined', function(data) {
-            if (self._eventHandlers.playerJoined) {
-              self._eventHandlers.playerJoined(data);
-            }
-          });
+        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);
+          }
+          reject(err);
+        });
 
-          self.socket.on('game:player_left', function(data) {
-            if (self._eventHandlers.playerLeft) {
-              self._eventHandlers.playerLeft(data);
-            }
-          });
+        self.socket.on('disconnect', function(reason) {
+          self.connected = false;
+          self._joined = false;
+          self._joinPromise = null;
+          if (self._heartbeatInterval) {
+            clearInterval(self._heartbeatInterval);
+            self._heartbeatInterval = null;
+          }
+          Usion.log('Game socket disconnected: ' + reason);
+          if (self._eventHandlers.disconnect) {
+            self._eventHandlers.disconnect(reason);
+          }
+        });
 
-          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.socket.on('reconnect', function(attemptNumber) {
+          Usion.log('Game socket reconnected after ' + attemptNumber + ' attempts');
+          if (self._eventHandlers.reconnect) {
+            self._eventHandlers.reconnect(attemptNumber);
+          }
+        });
 
-          self.socket.on('game:sync', function(data) {
-            if (data.sequence !== undefined) {
-              self._lastSequence = data.sequence;
-            }
-            if (self._eventHandlers.sync) {
-              self._eventHandlers.sync(data);
-            }
-            // Also trigger stateUpdate for backwards compat
-            if (self._eventHandlers.stateUpdate) {
-              self._eventHandlers.stateUpdate(data);
-            }
-          });
+        // Game event handlers
+        self.socket.on('game:joined', function(data) {
+          if (data.sequence !== undefined) {
+            self._lastSequence = data.sequence;
+          }
+          if (self._eventHandlers.joined) {
+            self._eventHandlers.joined(data);
+          }
+        });
 
-          self.socket.on('game:action', function(data) {
-            if (data.sequence !== undefined) {
-              self._lastSequence = Math.max(self._lastSequence, data.sequence);
-            }
-            if (self._eventHandlers.action) {
-              self._eventHandlers.action(data);
-            }
-          });
+        self.socket.on('game:player_joined', function(data) {
+          if (self._eventHandlers.playerJoined) {
+            self._eventHandlers.playerJoined(data);
+          }
+        });
 
-          self.socket.on('game:realtime', function(data) {
-            if (self._eventHandlers.realtime) {
-              self._eventHandlers.realtime(data);
-            }
-          });
+        self.socket.on('game:player_left', function(data) {
+          if (self._eventHandlers.playerLeft) {
+            self._eventHandlers.playerLeft(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.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.socket.on('game:error', function(data) {
-            Usion.log('Game error: ' + (data.message || data.code));
-            if (self._eventHandlers.error) {
-              self._eventHandlers.error(data);
-            }
-          });
+        self.socket.on('game:sync', function(data) {
+          if (data.sequence !== undefined) {
+            self._lastSequence = data.sequence;
+          }
+          if (self._eventHandlers.sync) {
+            self._eventHandlers.sync(data);
+          }
+          // Also trigger stateUpdate for backwards compat
+          if (self._eventHandlers.stateUpdate) {
+            self._eventHandlers.stateUpdate(data);
+          }
+        });
 
-          self.socket.on('game:rematch_request', function(data) {
-            if (self._eventHandlers.rematchRequest) {
-              self._eventHandlers.rematchRequest(data);
-            }
-          });
+        self.socket.on('game:action', function(data) {
+          if (data.sequence !== undefined) {
+            self._lastSequence = Math.max(self._lastSequence, data.sequence);
+          }
+          if (self._eventHandlers.action) {
+            self._eventHandlers.action(data);
+          }
+        });
 
-          self.socket.on('game:restarted', function(data) {
-            self._lastSequence = 0; // Reset sequence on rematch
-            if (self._eventHandlers.restarted) {
-              self._eventHandlers.restarted(data);
-            }
-          });
+        self.socket.on('game:realtime', function(data) {
+          if (self._eventHandlers.realtime) {
+            self._eventHandlers.realtime(data);
+          }
+        });
 
-        } catch (err) {
-          reject(err);
-        }
-      },
+        self.socket.on('game:finished', function(data) {
+          if (data.sequence !== undefined) {
+            self._lastSequence = data.sequence;
+          }
+          if (self._eventHandlers.finished) {
+            self._eventHandlers.finished(data);
+          }
+        });
 
-      /**
-       * Connect via parent app proxy (postMessage relay).
-       * Used when mixed content prevents direct socket connection.
-       * @private
-       */
-      _connectViaProxy: function() {
-        var self = this;
-        
-        if (self._useProxy && self.connected) {
-          return Promise.resolve();
-        }
-        
-        self._useProxy = true;
-        self._connecting = true;
-        self._setupProxyListener();
-        
-        self._connectPromise = new Promise(function(resolve, reject) {
-          // Listen for GAME_CONNECTED from parent
-          self._proxyConnectResolve = function() {
-            self.connected = true;
-            self._connecting = false;
-            Usion.log('Game socket connected via parent proxy');
-            resolve();
-          };
-          
-          // Send connect request to parent
-          Usion._post({ type: 'GAME_CONNECT' });
-          
-          // Timeout after 10s
-          setTimeout(function() {
-            if (!self.connected) {
-              self._connecting = false;
-              reject(new Error('Proxy connection timeout'));
-            }
-          }, 10000);
+        self.socket.on('game:error', function(data) {
+          Usion.log('Game error: ' + (data.message || data.code));
+          if (self._eventHandlers.error) {
+            self._eventHandlers.error(data);
+          }
         });
-        
-        return self._connectPromise;
-      },
 
-      /**
-       * Set up message listener for proxy game events from parent.
-       * @private
-       */
-      _setupProxyListener: function() {
-        var self = this;
-        if (self._proxyListenerSetup) return;
-        self._proxyListenerSetup = true;
-        
-        window.addEventListener('message', function(event) {
-          var data;
-          try {
-            data = typeof event.data === 'string' ? JSON.parse(event.data) : event.data;
-          } catch (e) {
-            return;
+        self.socket.on('game:rematch_request', function(data) {
+          if (self._eventHandlers.rematchRequest) {
+            self._eventHandlers.rematchRequest(data);
           }
-          if (!data || typeof data !== 'object' || !self._useProxy) return;
-          
-          switch (data.type) {
-            case 'GAME_CONNECTED':
-              if (self._proxyConnectResolve) {
-                self._proxyConnectResolve();
-                self._proxyConnectResolve = null;
-              }
-              break;
-              
-            case 'GAME_CONNECT_ERROR':
-              self.connected = false;
-              self._connecting = false;
-              break;
-              
-            case 'GAME_JOINED':
-              self._joined = true;
-              if (data.sequence !== undefined) self._lastSequence = data.sequence;
-              if (self._proxyJoinResolve) {
-                self._proxyJoinResolve(data);
-                self._proxyJoinResolve = null;
-              }
-              if (self._eventHandlers.joined) self._eventHandlers.joined(data);
-              break;
-              
-            case 'GAME_JOIN_ERROR':
-              self._joined = false;
-              if (self._proxyJoinReject) {
-                self._proxyJoinReject(new Error(data.message || 'Join failed'));
-                self._proxyJoinReject = null;
-              }
-              break;
-              
-            case 'GAME_PLAYER_JOINED':
-              if (self._eventHandlers.playerJoined) self._eventHandlers.playerJoined(data);
-              break;
-              
-            case 'GAME_PLAYER_LEFT':
-              if (self._eventHandlers.playerLeft) self._eventHandlers.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);
-              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);
-              break;
-              
-            case 'GAME_REALTIME_DATA':
-              if (self._eventHandlers.realtime) self._eventHandlers.realtime(data);
-              break;
-              
-            case 'GAME_FINISHED':
-              if (data.sequence !== undefined) self._lastSequence = data.sequence;
-              if (self._eventHandlers.finished) self._eventHandlers.finished(data);
-              break;
-              
-            case 'GAME_ERROR':
-              Usion.log('Game error via proxy: ' + (data.message || data.code));
-              if (self._eventHandlers.error) self._eventHandlers.error(data);
-              break;
-              
-            case 'GAME_RESTARTED':
-              self._lastSequence = 0;
-              if (self._eventHandlers.restarted) self._eventHandlers.restarted(data);
-              break;
-              
-            case 'GAME_REMATCH_REQUEST':
-              if (self._eventHandlers.rematchRequest) self._eventHandlers.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);
-              break;
+        });
+
+        self.socket.on('game:restarted', function(data) {
+          self._lastSequence = 0; // Reset sequence on rematch
+          if (self._eventHandlers.restarted) {
+            self._eventHandlers.restarted(data);
           }
         });
-      },
 
-      /**
-       * Join a game room
-       * @param {string} roomId - Game room ID (optional, uses config)
-       * @returns {Promise} Resolves with join data
-       */
-      join: function(roomId) {
-        const self = this;
-        roomId = roomId || Usion.config.roomId;
-        
-        // If already joined this room, return cached promise/data
-        if (self._joined && self.roomId === roomId && self._joinPromise) {
-          return self._joinPromise;
-        }
-        
-        self.roomId = roomId;
-        self.playerId = Usion.user.getId();
-
-        if (self.directMode) {
-          self._joined = true;
-          self._joinPromise = Promise.resolve({
-            room_id: roomId,
-            player_id: self.playerId
-          });
-          return self._joinPromise;
-        }
+      } catch (err) {
+        reject(err);
+      }
+    };
+  }
+
+  /**
+   * Usion SDK Game Proxy — postMessage relay through parent app
+   */
+
+  /**
+   * Add proxy connection methods to game module
+   * @param {object} game - The game module object
+   * @param {object} Usion - Reference to the main Usion object
+   */
+  function applyGameProxy(game, Usion) {
+    /**
+     * Connect via parent app proxy (postMessage relay).
+     * Used when mixed content prevents direct socket connection.
+     * @private
+     */
+    game._connectViaProxy = function() {
+      var self = this;
 
-        // Proxy mode: send join request to parent
-        if (self._useProxy) {
-          self._joinPromise = new Promise(function(resolve, reject) {
-            self._proxyJoinResolve = resolve;
-            self._proxyJoinReject = reject;
-            Usion._post({ type: 'GAME_JOIN', room_id: roomId });
-            setTimeout(function() {
-              if (!self._joined && self._proxyJoinReject) {
-                self._proxyJoinReject = null;
-                reject(new Error('Join timeout'));
-              }
-            }, 15000);
-          });
-          return self._joinPromise;
-        }
+      if (self._useProxy && self.connected) {
+        return Promise.resolve();
+      }
 
-        self._joinPromise = new Promise(function(resolve, reject) {
-          if (!self.socket || !self.connected) {
-            reject(new Error('Not connected'));
-            return;
-          }
+      self._useProxy = true;
+      self._connecting = true;
+      self._setupProxyListener();
 
-          if (!roomId) {
-            reject(new Error('No room ID provided'));
-            return;
+      self._connectPromise = new Promise(function(resolve, reject) {
+        // Listen for GAME_CONNECTED from parent
+        self._proxyConnectResolve = function() {
+          self.connected = true;
+          self._connecting = false;
+          Usion.log('Game socket connected via parent proxy');
+          resolve();
+        };
+
+        // Send connect request to parent
+        Usion._post({ type: 'GAME_CONNECT' });
+
+        // Timeout after 10s
+        setTimeout(function() {
+          if (!self.connected) {
+            self._connecting = false;
+            reject(new Error('Proxy connection timeout'));
           }
+        }, 10000);
+      });
 
-          self.socket.emit('game:join', { room_id: roomId }, function(response) {
-            if (response.error) {
-              self._joined = false;
-              reject(new Error(response.message || response.error));
-            } else {
-              self._joined = true;
-              if (response.sequence !== undefined) {
-                self._lastSequence = response.sequence;
-              }
-              resolve(response);
-            }
-          });
-        });
-        
-        return self._joinPromise;
-      },
+      return self._connectPromise;
+    };
 
-      /**
-       * Leave the current game room
-       */
-      leave: function() {
-        const self = this;
+    /**
+     * Set up message listener for proxy game events from parent.
+     * @private
+     */
+    game._setupProxyListener = function() {
+      var self = this;
+      if (self._proxyListenerSetup) return;
+      self._proxyListenerSetup = true;
 
-        if (self.directMode) {
-          if (self.roomId) self._sendDirect('leave', {});
-          self.roomId = null;
-          self._lastSequence = 0;
-          self._joined = false;
-          self._joinPromise = null;
-          return;
-        }
-        
-        if (self._useProxy) {
-          if (self.roomId) Usion._post({ type: 'GAME_LEAVE', room_id: self.roomId });
-          self.roomId = null;
-          self._lastSequence = 0;
-          self._joined = false;
-          self._joinPromise = null;
+      window.addEventListener('message', function(event) {
+        var data;
+        try {
+          data = typeof event.data === 'string' ? JSON.parse(event.data) : event.data;
+        } catch (e) {
           return;
         }
-        
-        if (self.socket && self.connected && self.roomId) {
-          self.socket.emit('game:leave', { room_id: self.roomId });
-          self.roomId = null;
-          self._lastSequence = 0;
-          self._joined = false;
-          self._joinPromise = null;
-        }
-      },
+        if (!data || typeof data !== 'object' || !self._useProxy) return;
 
-      /**
-       * Send a game action
-       * @param {string} actionType - Type of action (e.g., 'move')
-       * @param {object} actionData - Action data
-       * @returns {Promise} Resolves when action is processed
-       */
-      action: function(actionType, actionData) {
-        const self = this;
+        switch (data.type) {
+          case 'GAME_CONNECTED':
+            if (self._proxyConnectResolve) {
+              self._proxyConnectResolve();
+              self._proxyConnectResolve = null;
+            }
+            break;
 
-        if (self.directMode) {
-          self._sendDirect(actionType || 'action', actionData || {});
-          return Promise.resolve({ success: true });
-        }
+          case 'GAME_CONNECT_ERROR':
+            self.connected = false;
+            self._connecting = false;
+            break;
+
+          case 'GAME_JOINED':
+            self._joined = true;
+            if (data.sequence !== undefined) self._lastSequence = data.sequence;
+            if (self._proxyJoinResolve) {
+              self._proxyJoinResolve(data);
+              self._proxyJoinResolve = null;
+            }
+            if (self._eventHandlers.joined) self._eventHandlers.joined(data);
+            break;
 
-        if (self._useProxy) {
-          Usion._post({ type: 'GAME_ACTION', room_id: self.roomId, action_type: actionType, action_data: actionData });
-          return Promise.resolve({ success: true });
+          case 'GAME_JOIN_ERROR':
+            self._joined = false;
+            if (self._proxyJoinReject) {
+              self._proxyJoinReject(new Error(data.message || 'Join failed'));
+              self._proxyJoinReject = null;
+            }
+            break;
+
+          case 'GAME_PLAYER_JOINED':
+            if (self._eventHandlers.playerJoined) self._eventHandlers.playerJoined(data);
+            break;
+
+          case 'GAME_PLAYER_LEFT':
+            if (self._eventHandlers.playerLeft) self._eventHandlers.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);
+            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);
+            break;
+
+          case 'GAME_REALTIME_DATA':
+            if (self._eventHandlers.realtime) self._eventHandlers.realtime(data);
+            break;
+
+          case 'GAME_FINISHED':
+            if (data.sequence !== undefined) self._lastSequence = data.sequence;
+            if (self._eventHandlers.finished) self._eventHandlers.finished(data);
+            break;
+
+          case 'GAME_ERROR':
+            Usion.log('Game error via proxy: ' + (data.message || data.code));
+            if (self._eventHandlers.error) self._eventHandlers.error(data);
+            break;
+
+          case 'GAME_RESTARTED':
+            self._lastSequence = 0;
+            if (self._eventHandlers.restarted) self._eventHandlers.restarted(data);
+            break;
+
+          case 'GAME_REMATCH_REQUEST':
+            if (self._eventHandlers.rematchRequest) self._eventHandlers.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);
+            break;
         }
+      });
+    };
+  }
+
+  /**
+   * Usion SDK Game Methods — join, leave, action, realtime, sync, etc.
+   */
+
+  /**
+   * Add game action methods to game module
+   * @param {object} game - The game module object
+   * @param {object} Usion - Reference to the main Usion object
+   */
+  function applyGameMethods(game, Usion) {
+    /**
+     * Join a game room
+     * @param {string} roomId - Game room ID (optional, uses config)
+     * @returns {Promise} Resolves with join data
+     */
+    game.join = function(roomId) {
+      const self = this;
+      roomId = roomId || Usion.config.roomId;
 
-        return new Promise(function(resolve, reject) {
-          if (!self.socket || !self.connected) {
-            reject(new Error('Not connected'));
-            return;
-          }
+      // If already joined this room, return cached promise/data
+      if (self._joined && self.roomId === roomId && self._joinPromise) {
+        return self._joinPromise;
+      }
 
-          self.socket.emit('game:action', {
-            room_id: self.roomId,
-            action_type: actionType,
-            action_data: actionData
-          }, function(response) {
-            if (response.error) {
-              reject(new Error(response.message || response.error));
-            } else {
-              if (response.sequence !== undefined) {
-                self._lastSequence = response.sequence;
-              }
-              resolve(response);
-            }
-          });
+      self.roomId = roomId;
+      self.playerId = Usion.user.getId();
+
+      if (self.directMode) {
+        self._joined = true;
+        self._joinPromise = Promise.resolve({
+          room_id: roomId,
+          player_id: self.playerId
         });
-      },
+        return self._joinPromise;
+      }
 
-      /**
-       * Send a real-time game update (no locking, no rate limiting, fire-and-forget).
-       * Use this for high-frequency updates like position, input, state broadcasts.
-       * @param {string} actionType - Type of action (e.g., 'snake_input', 'position')
-       * @param {object} actionData - Action data
-       */
-      realtime: function(actionType, actionData) {
-        const self = this;
+      // Proxy mode: send join request to parent
+      if (self._useProxy) {
+        self._joinPromise = new Promise(function(resolve, reject) {
+          self._proxyJoinResolve = resolve;
+          self._proxyJoinReject = reject;
+          Usion._post({ type: 'GAME_JOIN', room_id: roomId });
+          setTimeout(function() {
+            if (!self._joined && self._proxyJoinReject) {
+              self._proxyJoinReject = null;
+              reject(new Error('Join timeout'));
+            }
+          }, 15000);
+        });
+        return self._joinPromise;
+      }
 
-        if (self.directMode) {
-          self._sendDirect('input', {
-            action_type: actionType,
-            action_data: actionData || {}
-          });
+      self._joinPromise = new Promise(function(resolve, reject) {
+        if (!self.socket || !self.connected) {
+          reject(new Error('Not connected'));
           return;
         }
 
-        if (self._useProxy) {
-          Usion._post({ type: 'GAME_REALTIME', room_id: self.roomId, action_type: actionType, action_data: actionData });
+        if (!roomId) {
+          reject(new Error('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));
+          } else {
+            self._joined = true;
+            if (response.sequence !== undefined) {
+              self._lastSequence = response.sequence;
+            }
+            resolve(response);
+          }
+        });
+      });
+
+      return self._joinPromise;
+    };
+
+    /**
+     * Leave the current game room
+     */
+    game.leave = function() {
+      const self = this;
+
+      if (self.directMode) {
+        if (self.roomId) self._sendDirect('leave', {});
+        self.roomId = null;
+        self._lastSequence = 0;
+        self._joined = false;
+        self._joinPromise = null;
+        return;
+      }
+
+      if (self._useProxy) {
+        if (self.roomId) Usion._post({ type: 'GAME_LEAVE', room_id: self.roomId });
+        self.roomId = null;
+        self._lastSequence = 0;
+        self._joined = false;
+        self._joinPromise = null;
+        return;
+      }
+
+      if (self.socket && self.connected && self.roomId) {
+        self.socket.emit('game:leave', { room_id: self.roomId });
+        self.roomId = null;
+        self._lastSequence = 0;
+        self._joined = false;
+        self._joinPromise = null;
+      }
+    };
+
+    /**
+     * Send a game action
+     * @param {string} actionType - Type of action (e.g., 'move')
+     * @param {object} actionData - Action data
+     * @returns {Promise} Resolves when action is processed
+     */
+    game.action = function(actionType, actionData) {
+      const self = this;
+
+      if (self.directMode) {
+        self._sendDirect(actionType || 'action', actionData || {});
+        return Promise.resolve({ success: true });
+      }
+
+      if (self._useProxy) {
+        Usion._post({ type: 'GAME_ACTION', room_id: self.roomId, action_type: actionType, action_data: actionData });
+        return Promise.resolve({ success: true });
+      }
+
+      return new Promise(function(resolve, reject) {
         if (!self.socket || !self.connected) {
+          reject(new Error('Not connected'));
           return;
         }
 
-        self.socket.emit('game:realtime', {
+        self.socket.emit('game:action', {
           room_id: self.roomId,
           action_type: actionType,
           action_data: actionData
+        }, function(response) {
+          if (response.error) {
+            reject(new Error(response.message || response.error));
+          } else {
+            if (response.sequence !== undefined) {
+              self._lastSequence = response.sequence;
+            }
+            resolve(response);
+          }
         });
-      },
+      });
+    };
 
-      /**
-       * Request game state sync (for reconnection)
-       * @param {number} lastSequence - Last known sequence number
-       */
-      requestSync: function(lastSequence) {
-        const self = this;
-        lastSequence = lastSequence !== undefined ? lastSequence : self._lastSequence;
+    /**
+     * Send a real-time game update (fire-and-forget).
+     * @param {string} actionType - Type of action
+     * @param {object} actionData - Action data
+     */
+    game.realtime = function(actionType, actionData) {
+      const self = this;
 
-        if (self.directMode) {
-          self._sendDirect('ping', { last_sequence: lastSequence || 0 });
-          return;
-        }
-        
-        if (self._useProxy && self.roomId) {
-          Usion._post({ type: 'GAME_SYNC_REQUEST', room_id: self.roomId, last_sequence: lastSequence || 0 });
-          return;
-        }
-        
-        if (self.socket && self.connected && self.roomId) {
-          self.socket.emit('game:sync_request', {
-            room_id: self.roomId,
-            last_sequence: lastSequence || 0
-          });
-        }
-      },
+      if (self.directMode) {
+        self._sendDirect('input', {
+          action_type: actionType,
+          action_data: actionData || {}
+        });
+        return;
+      }
 
-      /**
-       * Request a rematch
-       */
-      requestRematch: function() {
-        const self = this;
+      if (self._useProxy) {
+        Usion._post({ type: 'GAME_REALTIME', room_id: self.roomId, action_type: actionType, action_data: actionData });
+        return;
+      }
 
-        if (self.directMode) {
-          self._sendDirect('rematch', {});
-          return;
-        }
-        
-        if (self._useProxy && self.roomId) {
-          Usion._post({ type: 'GAME_REMATCH', room_id: self.roomId });
-          return;
-        }
-        
-        if (self.socket && self.connected && self.roomId) {
-          self.socket.emit('game:rematch', { room_id: self.roomId });
-        }
-      },
+      if (!self.socket || !self.connected) {
+        return;
+      }
 
-      /**
-       * Forfeit the current game
-       * @returns {Promise}
-       */
-      forfeit: function() {
-        const self = this;
+      self.socket.emit('game:realtime', {
+        room_id: self.roomId,
+        action_type: actionType,
+        action_data: actionData
+      });
+    };
 
-        if (self.directMode) {
-          self._sendDirect('forfeit', {});
-          return Promise.resolve({ success: true });
-        }
+    /**
+     * Request game state sync (for reconnection)
+     * @param {number} lastSequence - Last known sequence number
+     */
+    game.requestSync = function(lastSequence) {
+      const self = this;
+      lastSequence = lastSequence !== undefined ? lastSequence : self._lastSequence;
 
-        if (self._useProxy) {
-          Usion._post({ type: 'GAME_FORFEIT', room_id: self.roomId });
-          return Promise.resolve({ success: true });
-        }
+      if (self.directMode) {
+        self._sendDirect('ping', { last_sequence: lastSequence || 0 });
+        return;
+      }
 
-        return new Promise(function(resolve, reject) {
-          if (!self.socket || !self.connected) {
-            reject(new Error('Not connected'));
-            return;
-          }
+      if (self._useProxy && self.roomId) {
+        Usion._post({ type: 'GAME_SYNC_REQUEST', room_id: self.roomId, last_sequence: lastSequence || 0 });
+        return;
+      }
 
-          self.socket.emit('game:forfeit', { room_id: self.roomId }, function(response) {
-            if (response.error) {
-              reject(new Error(response.message || response.error));
-            } else {
-              resolve(response);
-            }
-          });
+      if (self.socket && self.connected && self.roomId) {
+        self.socket.emit('game:sync_request', {
+          room_id: self.roomId,
+          last_sequence: lastSequence || 0
         });
-      },
+      }
+    };
 
-      /**
-       * Disconnect from the game socket
-       */
-      disconnect: function() {
-        const self = this;
+    /**
+     * Request a rematch
+     */
+    game.requestRematch = function() {
+      const self = this;
 
-        // Always clear heartbeat
-        if (self._heartbeatInterval) {
-          clearInterval(self._heartbeatInterval);
-          self._heartbeatInterval = null;
-        }
+      if (self.directMode) {
+        self._sendDirect('rematch', {});
+        return;
+      }
 
-        if (self.directMode) {
-          if (self.directSocket) {
-            try { self.directSocket.close(); } catch (e) {}
-          }
-          self.directSocket = null;
-          self.connected = false;
-          self.roomId = null;
-          self._lastSequence = 0;
-          self._connecting = false;
-          self._connectPromise = null;
-          self._joined = false;
-          self._joinPromise = null;
-          self.directMode = false;
-          self.directConfig = null;
-          self._directSeq = 0;
-          return;
-        }
+      if (self._useProxy && self.roomId) {
+        Usion._post({ type: 'GAME_REMATCH', room_id: self.roomId });
+        return;
+      }
 
-        if (self._useProxy) {
-          Usion._post({ type: 'GAME_DISCONNECT' });
-          self.connected = false;
-          self.roomId = null;
-          self._lastSequence = 0;
-          self._connecting = false;
-          self._connectPromise = null;
-          self._joined = false;
-          self._joinPromise = null;
-          self._useProxy = false;
+      if (self.socket && self.connected && self.roomId) {
+        self.socket.emit('game:rematch', { room_id: self.roomId });
+      }
+    };
+
+    /**
+     * Forfeit the current game
+     * @returns {Promise}
+     */
+    game.forfeit = function() {
+      const self = this;
+
+      if (self.directMode) {
+        self._sendDirect('forfeit', {});
+        return Promise.resolve({ success: true });
+      }
+
+      if (self._useProxy) {
+        Usion._post({ type: 'GAME_FORFEIT', room_id: self.roomId });
+        return Promise.resolve({ success: true });
+      }
+
+      return new Promise(function(resolve, reject) {
+        if (!self.socket || !self.connected) {
+          reject(new Error('Not connected'));
           return;
         }
 
-        if (self.socket) {
-          self.socket.disconnect();
-          self.socket = null;
-          self.connected = false;
-          self.roomId = null;
-          self._lastSequence = 0;
-          self._connecting = false;
-          self._connectPromise = null;
-          self._joined = false;
-          self._joinPromise = null;
-        }
-      },
+        self.socket.emit('game:forfeit', { room_id: self.roomId }, function(response) {
+          if (response.error) {
+            reject(new Error(response.message || response.error));
+          } else {
+            resolve(response);
+          }
+        });
+      });
+    };
 
-      /**
-       * Get connection status
-       * @returns {boolean}
-       */
-      isConnected: function() {
-        if (this.directMode) {
-          return this.connected && this.directSocket && this.directSocket.readyState === WebSocket.OPEN;
+    /**
+     * Disconnect from the game socket
+     */
+    game.disconnect = function() {
+      const self = this;
+
+      // Always clear heartbeat
+      if (self._heartbeatInterval) {
+        clearInterval(self._heartbeatInterval);
+        self._heartbeatInterval = null;
+      }
+
+      if (self.directMode) {
+        if (self.directSocket) {
+          try { self.directSocket.close(); } catch (e) {}
         }
-        return this.connected && this.socket && this.socket.connected;
-      },
+        self.directSocket = null;
+        self.connected = false;
+        self.roomId = null;
+        self._lastSequence = 0;
+        self._connecting = false;
+        self._connectPromise = null;
+        self._joined = false;
+        self._joinPromise = null;
+        self.directMode = false;
+        self.directConfig = null;
+        self._directSeq = 0;
+        return;
+      }
 
-      // Event handler registrations
-      onJoined: function(callback) {
-        this._eventHandlers.joined = callback;
-      },
+      if (self._useProxy) {
+        Usion._post({ type: 'GAME_DISCONNECT' });
+        self.connected = false;
+        self.roomId = null;
+        self._lastSequence = 0;
+        self._connecting = false;
+        self._connectPromise = null;
+        self._joined = false;
+        self._joinPromise = null;
+        self._useProxy = false;
+        return;
+      }
 
-      onPlayerJoined: function(callback) {
-        this._eventHandlers.playerJoined = callback;
-      },
+      if (self.socket) {
+        self.socket.disconnect();
+        self.socket = null;
+        self.connected = false;
+        self.roomId = null;
+        self._lastSequence = 0;
+        self._connecting = false;
+        self._connectPromise = null;
+        self._joined = false;
+        self._joinPromise = null;
+      }
+    };
 
-      onPlayerLeft: function(callback) {
-        this._eventHandlers.playerLeft = callback;
-      },
+    /**
+     * Get connection status
+     * @returns {boolean}
+     */
+    game.isConnected = function() {
+      if (this.directMode) {
+        return this.connected && this.directSocket && this.directSocket.readyState === WebSocket.OPEN;
+      }
+      return this.connected && this.socket && this.socket.connected;
+    };
+  }
 
-      onStateUpdate: function(callback) {
-        this._eventHandlers.stateUpdate = callback;
-      },
+  /**
+   * Usion SDK Game Core — game module base, connect routing, event registrations
+   */
 
-      onSync: function(callback) {
-        this._eventHandlers.sync = callback;
-      },
 
-      onAction: function(callback) {
-        this._eventHandlers.action = callback;
-      },
+  /**
+   * Create the game module with all sub-modules applied
+   * @param {object} Usion - Reference to the main Usion object
+   */
+  function createGameModule(Usion) {
+    const game = {
+      socket: null,
+      directSocket: null,
+      roomId: null,
+      playerId: null,
+      connected: false,
+      directMode: false,
+      directConfig: null,
+      _directSeq: 0,
+      _eventHandlers: {},
+      _lastSequence: 0,
+      _connecting: false,
+      _connectPromise: null,
+      _joined: false,
+      _joinPromise: null,
+      _useProxy: false,
+      _proxyListenerSetup: false,
+      _heartbeatInterval: null,
 
-      onRealtime: function(callback) {
-        this._eventHandlers.realtime = callback;
-      },
+      /**
+       * Connect to the game socket server
+       * @param {string} socketUrl - Socket.IO server URL (optional, uses config)
+       * @param {string} token - JWT auth token (optional, uses user.getToken())
+       * @returns {Promise} Resolves when connected
+       */
+      connect: function(socketUrl, token) {
+        const self = this;
+        var connectionMode = (Usion.config && Usion.config.connectionMode) || 'platform';
+        if (connectionMode === 'direct') {
+          return self.connectDirect();
+        }
 
-      onGameFinished: function(callback) {
-        this._eventHandlers.finished = callback;
-      },
+        // Use config values as defaults
+        socketUrl = socketUrl || Usion.config.socketUrl;
+        token = token || Usion.user.getToken();
 
-      onGameRestarted: function(callback) {
-        this._eventHandlers.restarted = callback;
-      },
+        if (!socketUrl) {
+          return Promise.reject(new Error('No socket URL provided'));
+        }
+        if (!token) {
+          return Promise.reject(new Error('No auth token available'));
+        }
 
-      onError: function(callback) {
-        this._eventHandlers.error = callback;
-      },
+        // If already connected (direct or proxy), return immediately
+        if (self._useProxy && self.connected) {
+          return Promise.resolve();
+        }
+        if (self.socket && self.connected) {
+          return Promise.resolve();
+        }
 
-      onRematchRequest: function(callback) {
-        this._eventHandlers.rematchRequest = callback;
-      },
+        // If currently connecting, return the existing promise
+        if (self._connecting && self._connectPromise) {
+          return self._connectPromise;
+        }
 
-      onDisconnect: function(callback) {
-        this._eventHandlers.disconnect = callback;
-      },
+        // When running inside an iframe or WebView, use parent as socket proxy
+        var isInFrame = !!window.__USION_PROXY__
+                     || window.parent !== window
+                     || !!window.ReactNativeWebView
+                     || !!Usion._isEmbedded;
 
-      onReconnect: function(callback) {
-        this._eventHandlers.reconnect = callback;
-      },
+        if (isInFrame) {
+          Usion.log('Running in iframe \u2013 using parent app as socket proxy');
+          return self._connectViaProxy();
+        }
+
+        self._connecting = true;
+        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() {
+                self._connecting = false;
+                reject(new Error('Failed to load Socket.IO client'));
+              };
+              document.head.appendChild(cdnScript);
+            };
+            document.head.appendChild(script);
+          } else {
+            self._initSocket(socketUrl, token, resolve, reject);
+          }
+        });
 
-      onConnectionError: function(callback) {
-        this._eventHandlers.connectionError = callback;
+        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; },
+
       /**
        * Register a generic event handler
        * @param {string} event - Event name
@@ -1784,10 +1983,64 @@
           this.socket.on(event, callback);
         }
       }
-    }
-  };
-
-  // Expose to global
-  global.Usion = Usion;
-
-})(typeof window !== 'undefined' ? window : this);
+    };
+
+    // Apply sub-modules
+    applyGameDirect(game, Usion);
+    applyGameSocket(game, Usion);
+    applyGameProxy(game, Usion);
+    applyGameMethods(game, Usion);
+
+    return game;
+  }
+
+  /**
+   * Usion Mini App SDK v2.1
+   *
+   * JavaScript utilities for Mini Apps (Iframe Games & Services)
+   * Import via: <script src="https://usions.com/usion-sdk.js"></script>
+   *
+   * Features:
+   * - User info and authentication
+   * - Persistent storage (per-user, per-service)
+   * - Wallet/payment integration
+   * - Session management
+   * - Real-time game support via Socket.IO
+   */
+
+
+  // Build the Usion object from core
+  const Usion = Object.assign({}, core);
+
+  // Attach sub-modules (these reference Usion internally)
+  Usion.user = createUserModule(Usion);
+  Usion.storage = createStorageModule(Usion);
+  Usion.wallet = createWalletModule(Usion);
+  Usion.session = createSessionModule(Usion);
+  Usion.chat = createChatModule(Usion);
+  Usion.bot = createBotModule(Usion);
+  Usion.fileStorage = createFileStorageModule(Usion);
+  Usion.game = createGameModule(Usion);
+
+  // Attach results methods directly on Usion
+  Object.assign(Usion, createResultsMethods(Usion));
+
+  // Attach back button methods directly on Usion
+  Object.assign(Usion, createBackButtonMethods(Usion));
+
+  // Attach UI utilities directly on Usion
+  Object.assign(Usion, uiMethods);
+
+  // Attach misc methods (submit, error, exit, share, log, on, requestPayment)
+  Object.assign(Usion, miscMethods);
+
+  return Usion;
+
+})();
+
+// Expose to global
+if (typeof window !== 'undefined') {
+  window.Usion = Usion;
+} else if (typeof globalThis !== 'undefined') {
+  globalThis.Usion = Usion;
+}