@smoregg/sdk 1.2.0 → 2.0.0

package/dist/umd/smore-sdk.umd.js

@@ -277,122 +277,139 @@
     _roomCode = "";
     _isReady = false;
     _isDestroyed = false;
+    _initTimeoutId = null;
     eventHandlers = /* @__PURE__ */ new Map();
     registeredTransportHandlers = [];
     boundMessageHandler = null;
-    // Maps user-facing handler → transport wrappedHandler for proper cleanup in on()/off()
+    // Maps user-facing handler -> transport wrappedHandler for proper cleanup in on()/off()
     handlerToTransport = /* @__PURE__ */ new Map();
-    // Tracks event names registered via config.listeners so off(event) without handler won't remove them
-    _configListenerEvents = /* @__PURE__ */ new Set();
+    // Pending handlers registered via on() before transport is ready
+    _pendingHandlers = [];
+    // Lifecycle callback arrays
+    _onAllReadyCallbacks = /* @__PURE__ */ new Set();
+    _onControllerJoinCallbacks = /* @__PURE__ */ new Set();
+    _onControllerLeaveCallbacks = /* @__PURE__ */ new Set();
+    _onControllerDisconnectCallbacks = /* @__PURE__ */ new Set();
+    _onControllerReconnectCallbacks = /* @__PURE__ */ new Set();
+    _onCharacterUpdatedCallbacks = /* @__PURE__ */ new Set();
+    _onRateLimitedCallbacks = /* @__PURE__ */ new Set();
+    _onErrorCallbacks = /* @__PURE__ */ new Set();
+    // Whether all-ready has fired
+    _allReadyFired = false;
+    // Ready promise
+    _readyResolve;
+    _readyReject;
+    ready;
     constructor(config = {}) {
       this.config = config;
       this.logger = new DebugLogger(config.debug, "[SmoreScreen]");
-      if (config.listeners) {
-        for (const event of Object.keys(config.listeners)) {
-          validateEventName(event);
-        }
-      }
+      this.ready = new Promise((resolve, reject) => {
+        this._readyResolve = resolve;
+        this._readyReject = reject;
+      });
+      this.startInitialization();
     }
     // ---------------------------------------------------------------------------
-    // Initialization (called by factory)
+    // Initialization (called in constructor)
     // ---------------------------------------------------------------------------
-    async initialize() {
+    startInitialization() {
       this.logger.lifecycle("Initializing screen...");
       const parentOrigin = this.config.parentOrigin ?? "*";
       const timeout = this.config.timeout ?? DEFAULT_TIMEOUT$1;
-      return new Promise((resolve, reject) => {
-        const timeoutId = setTimeout(() => {
-          this.cleanup();
-          const error = new SmoreSDKError(
-            "TIMEOUT",
-            `Screen initialization timed out after ${timeout}ms. Make sure the parent frame sends _bridge:init. Check that the iframe has correct sandbox attributes (allow-scripts required) and same-origin/cross-origin settings. Create a new Screen instance to retry (this instance has been cleaned up).`,
-            { details: { timeout } }
-          );
-          this.handleError(error);
-          reject(error);
-        }, timeout);
-        this.boundMessageHandler = (e) => {
-          if (parentOrigin !== "*" && e.origin !== parentOrigin) return;
-          const msg = e.data;
-          if (!isBridgeMessage(msg)) return;
-          if (msg.type === "_bridge:init") {
-            clearTimeout(timeoutId);
-            const initPayload = msg.payload;
-            try {
-              validateInitPayload(initPayload);
-            } catch (err) {
-              const error = new SmoreSDKError(
-                "INIT_FAILED",
-                `Invalid _bridge:init payload: ${err instanceof Error ? err.message : String(err)}`,
-                { details: { payload: initPayload } }
-              );
-              this.logger.warn("_bridge:init validation failed", error);
-              this.handleError(error);
-              reject(error);
-              return;
-            }
-            const initData = initPayload;
-            if (initData.side !== "host") {
-              const error = new SmoreSDKError(
-                "INIT_FAILED",
-                `Received init for wrong side: ${initData.side}. Expected "host".`,
-                { details: { side: initData.side } }
-              );
-              this.handleError(error);
-              reject(error);
-              return;
-            }
-            this.transport = new PostMessageTransport(parentOrigin);
-            this._roomCode = initData.roomCode;
-            this._controllers = this.mapControllersFromInit(initData.players);
-            if (this._controllers.length === 0) {
-              this.logger.warn("Screen initialized with zero controllers");
-            }
-            this.setupEventHandlers();
-            this._isReady = true;
-            this.logger.lifecycle("Screen ready", {
-              roomCode: this._roomCode,
-              controllers: this._controllers.length
-            });
-            this.config.onReady?.();
-            const autoReady = this.config.autoReady ?? getGlobalConfig().autoReady ?? true;
-            if (autoReady) {
-              this.logger.lifecycle("Auto-signaling ready (autoReady enabled)");
-              this.signalReady();
-            }
-            resolve();
-          } else if (msg.type === "_bridge:update") {
-            if (!this._isReady) {
-              this.logger.debug("Ignoring _bridge:update before init completes");
-              return;
-            }
-            const updateData = msg.payload;
-            if (updateData.players && Array.isArray(updateData.players)) {
-              const oldControllers = this._controllers;
-              const newControllers = this.mapControllersFromInit(updateData.players);
-              this._controllers = newControllers;
-              for (const nc of newControllers) {
-                if (!oldControllers.some((oc) => oc.playerIndex === nc.playerIndex)) {
-                  this.logger.lifecycle("Controller joined (via update)", { playerIndex: nc.playerIndex });
-                  this.config.onControllerJoin?.(nc.playerIndex, nc);
-                }
+      this._initTimeoutId = setTimeout(() => {
+        this.cleanup();
+        const error = new SmoreSDKError(
+          "TIMEOUT",
+          `Screen initialization timed out after ${timeout}ms. Make sure the parent frame sends _bridge:init. Check that the iframe has correct sandbox attributes (allow-scripts required) and same-origin/cross-origin settings. Create a new Screen instance to retry (this instance has been cleaned up).`,
+          { details: { timeout } }
+        );
+        this.handleError(error);
+        this._readyReject(error);
+      }, timeout);
+      this.boundMessageHandler = (e) => {
+        if (parentOrigin !== "*" && e.origin !== parentOrigin) return;
+        const msg = e.data;
+        if (!isBridgeMessage(msg)) return;
+        if (msg.type === "_bridge:init") {
+          clearTimeout(this._initTimeoutId);
+          const initPayload = msg.payload;
+          try {
+            validateInitPayload(initPayload);
+          } catch (err) {
+            const error = new SmoreSDKError(
+              "INIT_FAILED",
+              `Invalid _bridge:init payload: ${err instanceof Error ? err.message : String(err)}`,
+              { details: { payload: initPayload } }
+            );
+            this.logger.warn("_bridge:init validation failed", error);
+            this.handleError(error);
+            this._readyReject(error);
+            return;
+          }
+          const initData = initPayload;
+          if (initData.side !== "host") {
+            const error = new SmoreSDKError(
+              "INIT_FAILED",
+              `Received init for wrong side: ${initData.side}. Expected "host".`,
+              { details: { side: initData.side } }
+            );
+            this.handleError(error);
+            this._readyReject(error);
+            return;
+          }
+          this.transport = new PostMessageTransport(parentOrigin);
+          this._roomCode = initData.roomCode;
+          this._controllers = this.mapControllersFromInit(initData.players);
+          if (this._controllers.length === 0) {
+            this.logger.warn("Screen initialized with zero controllers");
+          }
+          this.setupEventHandlers();
+          for (const { event, handler } of this._pendingHandlers) {
+            this.setupUserEventHandler(event, handler);
+          }
+          this._pendingHandlers = [];
+          this._isReady = true;
+          this.logger.lifecycle("Screen ready", {
+            roomCode: this._roomCode,
+            controllers: this._controllers.length
+          });
+          const autoReady = getGlobalConfig().autoReady ?? true;
+          if (autoReady) {
+            this.logger.lifecycle("Auto-signaling ready (autoReady enabled)");
+            this.signalReady();
+          }
+          this._readyResolve();
+        } else if (msg.type === "_bridge:update") {
+          if (!this._isReady) {
+            this.logger.debug("Ignoring _bridge:update before init completes");
+            return;
+          }
+          const updateData = msg.payload;
+          if (updateData.players && Array.isArray(updateData.players)) {
+            const oldControllers = this._controllers;
+            const newControllers = this.mapControllersFromInit(updateData.players);
+            this._controllers = newControllers;
+            for (const nc of newControllers) {
+              if (!oldControllers.some((oc) => oc.playerIndex === nc.playerIndex)) {
+                this.logger.lifecycle("Controller joined (via update)", { playerIndex: nc.playerIndex });
+                this._onControllerJoinCallbacks.forEach((cb) => cb(nc.playerIndex, nc));
               }
-              for (const oc of oldControllers) {
-                if (!newControllers.some((nc) => nc.playerIndex === oc.playerIndex)) {
-                  this.logger.lifecycle("Controller left (via update)", { playerIndex: oc.playerIndex });
-                  this.config.onControllerLeave?.(oc.playerIndex);
-                }
+            }
+            for (const oc of oldControllers) {
+              if (!newControllers.some((nc) => nc.playerIndex === oc.playerIndex)) {
+                this.logger.lifecycle("Controller left (via update)", { playerIndex: oc.playerIndex });
+                this._onControllerLeaveCallbacks.forEach((cb) => cb(oc.playerIndex));
               }
             }
-            this.logger.lifecycle("Room updated", {
-              controllers: this._controllers.length
-            });
           }
-        };
-        window.addEventListener("message", this.boundMessageHandler);
-        window.parent.postMessage({ type: "_bridge:ready" }, parentOrigin);
-        this.logger.lifecycle("Sent _bridge:ready to parent");
-      });
+          this.logger.lifecycle("Room updated", {
+            controllers: this._controllers.length
+          });
+        }
+      };
+      window.addEventListener("message", this.boundMessageHandler);
+      window.parent.postMessage({ type: "_bridge:ready" }, parentOrigin);
+      this.logger.lifecycle("Sent _bridge:ready to parent");
     }
     mapControllersFromInit(players) {
       return players.map((p, index) => ({
@@ -419,7 +436,7 @@
           if (this._controllers.some((c) => c.playerIndex === controllerInfo.playerIndex)) return;
           this._controllers = [...this._controllers, controllerInfo];
           this.logger.lifecycle("Controller joined", { playerIndex: controllerInfo.playerIndex });
-          this.config.onControllerJoin?.(controllerInfo.playerIndex, controllerInfo);
+          this._onControllerJoinCallbacks.forEach((cb) => cb(controllerInfo.playerIndex, controllerInfo));
         }
       });
       this.registerTransportHandler(SMORE_EVENTS.PLAYER_LEFT, (data) => {
@@ -429,7 +446,7 @@
           if (!this._controllers.some((c) => c.playerIndex === playerIndex)) return;
           this._controllers = this._controllers.filter((c) => c.playerIndex !== playerIndex);
           this.logger.lifecycle("Controller left", { playerIndex });
-          this.config.onControllerLeave?.(playerIndex);
+          this._onControllerLeaveCallbacks.forEach((cb) => cb(playerIndex));
         }
       });
       this.registerTransportHandler(SMORE_EVENTS.PLAYER_DISCONNECTED, (data) => {
@@ -440,7 +457,7 @@
             (c) => c.playerIndex === playerIndex ? { ...c, connected: false } : c
           );
           this.logger.lifecycle("Controller disconnected", { playerIndex });
-          this.config.onControllerDisconnect?.(playerIndex);
+          this._onControllerDisconnectCallbacks.forEach((cb) => cb(playerIndex));
         }
       });
       this.registerTransportHandler(SMORE_EVENTS.PLAYER_RECONNECTED, (data) => {
@@ -457,38 +474,33 @@
             (c) => c.playerIndex === controllerInfo.playerIndex ? controllerInfo : c
           );
           this.logger.lifecycle("Controller reconnected", { playerIndex: controllerInfo.playerIndex });
-          this.config.onControllerReconnect?.(controllerInfo.playerIndex, controllerInfo);
+          this._onControllerReconnectCallbacks.forEach((cb) => cb(controllerInfo.playerIndex, controllerInfo));
         }
       });
       this.registerTransportHandler(SMORE_EVENTS.PLAYER_CHARACTER_UPDATED, (data) => {
         const payload = data;
         const playerData = payload?.player;
         if (playerData && typeof playerData.playerIndex === "number") {
+          const pi = playerData.playerIndex;
           const appearance = playerData.character ?? null;
           this._controllers = this._controllers.map(
-            (c) => c.playerIndex === playerData.playerIndex ? { ...c, appearance } : c
+            (c) => c.playerIndex === pi ? { ...c, appearance } : c
           );
-          this.logger.lifecycle("Player character updated", { playerIndex: playerData.playerIndex });
-          this.config.onCharacterUpdated?.(playerData.playerIndex, appearance ?? null);
+          this.logger.lifecycle("Player character updated", { playerIndex: pi });
+          this._onCharacterUpdatedCallbacks.forEach((cb) => cb(pi, appearance ?? null));
         }
       });
       this.registerTransportHandler(SMORE_EVENTS.RATE_LIMITED, (data) => {
         const payload = data;
         const event = payload?.event ?? "unknown";
         this.logger.warn(`Rate limited: ${event}`);
-        this.config.onRateLimited?.(event);
+        this._onRateLimitedCallbacks.forEach((cb) => cb(event));
       });
       this.registerTransportHandler(SMORE_EVENTS.ALL_READY, () => {
         this.logger.lifecycle("All participants ready");
-        this.config.onAllReady?.();
+        this._allReadyFired = true;
+        this._onAllReadyCallbacks.forEach((cb) => cb());
       });
-      if (this.config.listeners) {
-        for (const [event, handler] of Object.entries(this.config.listeners)) {
-          if (!handler) continue;
-          this._configListenerEvents.add(event);
-          this.setupUserEventHandler(event, handler);
-        }
-      }
     }
     /**
      * Sets up a user event handler with playerIndex extraction.
@@ -530,6 +542,7 @@
         this.eventHandlers.set(event, handlers);
       }
       handlers.add(handler);
+      this.handlerToTransport.set(handler, { event, transportHandler: wrappedHandler });
     }
     registerTransportHandler(event, handler) {
       if (!this.transport) return;
@@ -556,6 +569,60 @@
       return this._isDestroyed;
     }
     // ---------------------------------------------------------------------------
+    // Lifecycle Methods
+    // ---------------------------------------------------------------------------
+    onAllReady(callback) {
+      if (this._allReadyFired) {
+        callback();
+      }
+      this._onAllReadyCallbacks.add(callback);
+      return () => {
+        this._onAllReadyCallbacks.delete(callback);
+      };
+    }
+    onControllerJoin(callback) {
+      this._onControllerJoinCallbacks.add(callback);
+      return () => {
+        this._onControllerJoinCallbacks.delete(callback);
+      };
+    }
+    onControllerLeave(callback) {
+      this._onControllerLeaveCallbacks.add(callback);
+      return () => {
+        this._onControllerLeaveCallbacks.delete(callback);
+      };
+    }
+    onControllerDisconnect(callback) {
+      this._onControllerDisconnectCallbacks.add(callback);
+      return () => {
+        this._onControllerDisconnectCallbacks.delete(callback);
+      };
+    }
+    onControllerReconnect(callback) {
+      this._onControllerReconnectCallbacks.add(callback);
+      return () => {
+        this._onControllerReconnectCallbacks.delete(callback);
+      };
+    }
+    onCharacterUpdated(callback) {
+      this._onCharacterUpdatedCallbacks.add(callback);
+      return () => {
+        this._onCharacterUpdatedCallbacks.delete(callback);
+      };
+    }
+    onRateLimited(callback) {
+      this._onRateLimitedCallbacks.add(callback);
+      return () => {
+        this._onRateLimitedCallbacks.delete(callback);
+      };
+    }
+    onError(callback) {
+      this._onErrorCallbacks.add(callback);
+      return () => {
+        this._onErrorCallbacks.delete(callback);
+      };
+    }
+    // ---------------------------------------------------------------------------
     // Communication Methods
     // ---------------------------------------------------------------------------
     /**
@@ -662,11 +729,8 @@
     /**
      * Register an event handler for messages from controllers.
      *
-     * **Important:** If called before the Screen is ready (i.e., before `await createScreen()`
-     * resolves or before the `onReady` callback fires), the handler is stored locally but
-     * will NOT be registered with the transport layer. This means the handler will never
-     * fire for events received during the pre-ready window. Always call `on()` after
-     * initialization completes, or use `config.listeners` for handlers needed from the start.
+     * Can be called before the Screen is ready. Handlers registered before ready
+     * are queued and activated when the transport becomes available.
      */
     on(event, handler) {
       validateEventName(event);
@@ -676,9 +740,8 @@
         this.eventHandlers.set(event, handlers);
       }
       handlers.add(handler);
-      let wrappedHandler = null;
       if (this.transport) {
-        wrappedHandler = (data) => {
+        const wrappedHandler = (data) => {
           this.logger.receive(event, data);
           const payload = data;
           const { playerIndex, ...rest } = payload;
@@ -698,16 +761,22 @@
         };
         this.registerTransportHandler(event, wrappedHandler);
         this.handlerToTransport.set(handler, { event, transportHandler: wrappedHandler });
+      } else {
+        this._pendingHandlers.push({ event, handler });
       }
       return () => {
         handlers?.delete(handler);
         if (handlers?.size === 0) {
           this.eventHandlers.delete(event);
         }
-        if (wrappedHandler) {
-          this.transport?.off(event, wrappedHandler);
+        this._pendingHandlers = this._pendingHandlers.filter(
+          (p) => !(p.event === event && p.handler === handler)
+        );
+        const entry = this.handlerToTransport.get(handler);
+        if (entry) {
+          this.transport?.off(event, entry.transportHandler);
           this.registeredTransportHandlers = this.registeredTransportHandlers.filter(
-            (h) => h.handler !== wrappedHandler
+            (h) => h.handler !== entry.transportHandler
           );
           this.handlerToTransport.delete(handler);
         }
@@ -724,16 +793,6 @@
      * @param event - Event name to listen for
      * @param handler - Handler function to call once
      * @returns Unsubscribe function to remove the handler before it fires
-     *
-     * @example
-     * ```ts
-     * const unsubscribe = screen.once('ready', (playerIndex, data) => {
-     *   console.log('Ready event received');
-     * });
-     *
-     * // To remove before the event fires:
-     * unsubscribe();
-     * ```
      */
     once(event, handler) {
       const wrappedHandler = (playerIndex, data) => {
@@ -745,24 +804,13 @@
     }
     off(event, handler) {
       if (!handler) {
-        if (this._configListenerEvents.has(event)) {
-          for (const [key, val] of this.handlerToTransport) {
-            if (val.event === event) {
-              this.transport?.off(event, val.transportHandler);
-              this.registeredTransportHandlers = this.registeredTransportHandlers.filter(
-                (h) => h.handler !== val.transportHandler
-              );
-              this.handlerToTransport.delete(key);
-            }
-          }
-        } else {
-          this.eventHandlers.delete(event);
-          this.transport?.off(event);
-          this.registeredTransportHandlers = this.registeredTransportHandlers.filter((h) => h.event !== event);
-          for (const [key, val] of this.handlerToTransport) {
-            if (val.event === event) this.handlerToTransport.delete(key);
-          }
+        this.eventHandlers.delete(event);
+        this.transport?.off(event);
+        this.registeredTransportHandlers = this.registeredTransportHandlers.filter((h) => h.event !== event);
+        for (const [key, val] of this.handlerToTransport) {
+          if (val.event === event) this.handlerToTransport.delete(key);
         }
+        this._pendingHandlers = this._pendingHandlers.filter((p) => p.event !== event);
       } else {
         const handlers = this.eventHandlers.get(event);
         handlers?.delete(handler);
@@ -777,6 +825,9 @@
           );
           this.handlerToTransport.delete(handler);
         }
+        this._pendingHandlers = this._pendingHandlers.filter(
+          (p) => !(p.event === event && p.handler === handler)
+        );
       }
     }
     // ---------------------------------------------------------------------------
@@ -788,25 +839,6 @@
     getControllerCount() {
       return this._controllers.filter((c) => c.connected).length;
     }
-    /**
-     * Check if there is at least one connected controller.
-     * Useful for detecting when all players have disconnected
-     * (e.g., to pause the game or show a waiting screen).
-     *
-     * Use this in onControllerDisconnect callback to detect when all controllers have disconnected.
-     *
-     * @example
-     * ```ts
-     * const screen = await createScreen<MyEvents>({
-     *   onControllerDisconnect: (playerIndex) => {
-     *     if (!screen.hasAnyConnectedControllers()) {
-     *       console.log('All controllers disconnected!');
-     *       screen.broadcast('waiting-for-players', {});
-     *     }
-     *   },
-     * });
-     * ```
-     */
     hasAnyConnectedControllers() {
       return this._controllers.some((c) => c.connected);
     }
@@ -822,12 +854,25 @@
       this.logger.lifecycle("Screen destroyed");
     }
     cleanup() {
+      if (this._initTimeoutId) {
+        clearTimeout(this._initTimeoutId);
+        this._initTimeoutId = null;
+      }
       for (const { event, handler } of this.registeredTransportHandlers) {
         this.transport?.off(event, handler);
       }
       this.registeredTransportHandlers = [];
       this.eventHandlers.clear();
       this.handlerToTransport.clear();
+      this._pendingHandlers = [];
+      this._onAllReadyCallbacks.clear();
+      this._onControllerJoinCallbacks.clear();
+      this._onControllerLeaveCallbacks.clear();
+      this._onControllerDisconnectCallbacks.clear();
+      this._onControllerReconnectCallbacks.clear();
+      this._onCharacterUpdatedCallbacks.clear();
+      this._onRateLimitedCallbacks.clear();
+      this._onErrorCallbacks.clear();
       if (this.transport instanceof PostMessageTransport) {
         this.transport.destroy();
       }
@@ -843,8 +888,8 @@
     handleError(error) {
       this.logger.warn(`Error in handler: ${error.message}`);
       const smoreError = error.toSmoreError();
-      if (this.config.onError) {
-        this.config.onError(smoreError);
+      if (this._onErrorCallbacks.size > 0) {
+        this._onErrorCallbacks.forEach((cb) => cb(smoreError));
       } else {
         this.logger.error(error.message, error.details);
       }
@@ -860,17 +905,14 @@
       if (!this._isReady || !this.transport) {
         throw new SmoreSDKError(
           "NOT_READY",
-          `Cannot call ${method}() before screen is ready. Use await createScreen() or onReady callback.`,
+          `Cannot call ${method}() before screen is ready. Use await screen.ready.`,
           { details: { method } }
         );
       }
     }
   }
   function createScreen(config) {
-    const screen = new ScreenImpl(config);
-    const promise = screen.initialize().then(() => screen);
-    promise.instance = screen;
-    return promise;
+    return new ScreenImpl(config);
   }
 
   const DEFAULT_TIMEOUT = 1e4;
@@ -882,22 +924,38 @@
     _myIndex = -1;
     _isReady = false;
     _isDestroyed = false;
+    _initTimeoutId = null;
     boundMessageHandler = null;
     registeredHandlers = [];
     eventListeners = /* @__PURE__ */ new Map();
     // Maps user-facing handler -> transport wrappedHandler for proper cleanup in on()/off()
     handlerToTransport = /* @__PURE__ */ new Map();
     _controllers = [];
-    // Tracks event names registered via config.listeners so off(event) without handler won't remove them
-    _configListenerEvents = /* @__PURE__ */ new Set();
+    // Pending handlers registered via on() before transport is ready
+    _pendingHandlers = [];
+    // Lifecycle callback arrays
+    _onAllReadyCallbacks = /* @__PURE__ */ new Set();
+    _onControllerJoinCallbacks = /* @__PURE__ */ new Set();
+    _onControllerLeaveCallbacks = /* @__PURE__ */ new Set();
+    _onControllerDisconnectCallbacks = /* @__PURE__ */ new Set();
+    _onControllerReconnectCallbacks = /* @__PURE__ */ new Set();
+    _onCharacterUpdatedCallbacks = /* @__PURE__ */ new Set();
+    _onRateLimitedCallbacks = /* @__PURE__ */ new Set();
+    _onErrorCallbacks = /* @__PURE__ */ new Set();
+    // Whether all-ready has fired
+    _allReadyFired = false;
+    // Ready promise
+    _readyResolve;
+    _readyReject;
+    ready;
     constructor(config = {}) {
       this.config = config;
       this.logger = new DebugLogger(config.debug, "[SmoreController]");
-      if (config.listeners) {
-        for (const event of Object.keys(config.listeners)) {
-          validateEventName(event);
-        }
-      }
+      this.ready = new Promise((resolve, reject) => {
+        this._readyResolve = resolve;
+        this._readyReject = reject;
+      });
+      this.startInitialization();
     }
     // ---------------------------------------------------------------------------
     // Properties (readonly)
@@ -933,38 +991,36 @@
     // ---------------------------------------------------------------------------
     // Initialization
     // ---------------------------------------------------------------------------
-    async initialize() {
+    startInitialization() {
       const parentOrigin = this.config.parentOrigin ?? "*";
       const timeout = this.config.timeout ?? DEFAULT_TIMEOUT;
       this.logger.lifecycle("Initializing controller...", { parentOrigin, timeout });
-      return new Promise((resolve, reject) => {
-        const timeoutId = setTimeout(() => {
-          this.cleanup();
-          const error = new SmoreSDKError(
-            "TIMEOUT",
-            `Controller initialization timed out after ${timeout}ms. Make sure the parent window sends _bridge:init message. Check that the iframe has correct sandbox attributes (allow-scripts required) and same-origin/cross-origin settings. Create a new Controller instance to retry (this instance has been cleaned up).`,
-            { details: { timeout } }
-          );
-          this.handleError(error);
-          reject(error);
-        }, timeout);
-        this.boundMessageHandler = (e) => {
-          if (parentOrigin !== "*" && e.origin !== parentOrigin) return;
-          const msg = e.data;
-          if (!isBridgeMessage(msg)) return;
-          if (msg.type === "_bridge:init") {
-            clearTimeout(timeoutId);
-            this.handleInit(msg, parentOrigin, resolve, reject);
-          } else if (msg.type === "_bridge:update") {
-            this.handleUpdate(msg);
-          }
-        };
-        window.addEventListener("message", this.boundMessageHandler);
-        this.logger.lifecycle("Sending _bridge:ready to parent");
-        window.parent.postMessage({ type: "_bridge:ready" }, parentOrigin);
-      });
+      this._initTimeoutId = setTimeout(() => {
+        this.cleanup();
+        const error = new SmoreSDKError(
+          "TIMEOUT",
+          `Controller initialization timed out after ${timeout}ms. Make sure the parent window sends _bridge:init message. Check that the iframe has correct sandbox attributes (allow-scripts required) and same-origin/cross-origin settings. Create a new Controller instance to retry (this instance has been cleaned up).`,
+          { details: { timeout } }
+        );
+        this.handleError(error);
+        this._readyReject(error);
+      }, timeout);
+      this.boundMessageHandler = (e) => {
+        if (parentOrigin !== "*" && e.origin !== parentOrigin) return;
+        const msg = e.data;
+        if (!isBridgeMessage(msg)) return;
+        if (msg.type === "_bridge:init") {
+          clearTimeout(this._initTimeoutId);
+          this.handleInit(msg, parentOrigin);
+        } else if (msg.type === "_bridge:update") {
+          this.handleUpdate(msg);
+        }
+      };
+      window.addEventListener("message", this.boundMessageHandler);
+      this.logger.lifecycle("Sending _bridge:ready to parent");
+      window.parent.postMessage({ type: "_bridge:ready" }, parentOrigin);
     }
-    handleInit(msg, parentOrigin, resolve, reject) {
+    handleInit(msg, parentOrigin) {
       const initPayload = msg.payload;
       this.logger.debug("Received _bridge:init", initPayload);
       try {
@@ -977,7 +1033,7 @@
         );
         this.logger.warn("_bridge:init validation failed", error);
         this.handleError(error);
-        reject(error);
+        this._readyReject(error);
         return;
       }
       const initData = initPayload;
@@ -988,7 +1044,7 @@
           { details: { side: initData.side } }
         );
         this.handleError(error);
-        reject(error);
+        this._readyReject(error);
         return;
       }
       if (initData.myIndex === void 0) {
@@ -998,7 +1054,7 @@
           { details: initData }
         );
         this.handleError(error);
-        reject(error);
+        this._readyReject(error);
         return;
       }
       this.transport = new PostMessageTransport(parentOrigin);
@@ -1012,18 +1068,21 @@
         appearance: p.appearance ?? p.character
       }));
       this.setupEventHandlers();
+      for (const { event, handler } of this._pendingHandlers) {
+        this.setupUserEventHandler(event, handler);
+      }
+      this._pendingHandlers = [];
       this._isReady = true;
       this.logger.lifecycle("Controller ready", {
         roomCode: this._roomCode,
         myIndex: this._myIndex
       });
-      this.config.onReady?.();
-      const autoReady = this.config.autoReady ?? getGlobalConfig().autoReady ?? true;
+      const autoReady = getGlobalConfig().autoReady ?? true;
       if (autoReady) {
         this.logger.lifecycle("Auto-signaling ready (autoReady enabled)");
         this.signalReady();
       }
-      resolve();
+      this._readyResolve();
     }
     handleUpdate(msg) {
       if (!this._isReady) {
@@ -1043,12 +1102,12 @@
         const oldControllers = this._controllers;
         for (const nc of newControllers) {
           if (!oldControllers.some((oc) => oc.playerIndex === nc.playerIndex)) {
-            this.config.onControllerJoin?.(nc.playerIndex, nc);
+            this._onControllerJoinCallbacks.forEach((cb) => cb(nc.playerIndex, nc));
           }
         }
         for (const oc of oldControllers) {
           if (!newControllers.some((nc) => nc.playerIndex === oc.playerIndex)) {
-            this.config.onControllerLeave?.(oc.playerIndex);
+            this._onControllerLeaveCallbacks.forEach((cb) => cb(oc.playerIndex));
           }
         }
         for (const nc of newControllers) {
@@ -1056,11 +1115,11 @@
           if (oc) {
             if (oc.connected && !nc.connected) {
               this.logger.debug("Player disconnected (via update)", { playerIndex: nc.playerIndex });
-              this.config.onControllerDisconnect?.(nc.playerIndex);
+              this._onControllerDisconnectCallbacks.forEach((cb) => cb(nc.playerIndex));
             }
             if (!oc.connected && nc.connected) {
               this.logger.debug("Player reconnected (via update)", { playerIndex: nc.playerIndex });
-              this.config.onControllerReconnect?.(nc.playerIndex, nc);
+              this._onControllerReconnectCallbacks.forEach((cb) => cb(nc.playerIndex, nc));
             }
           }
         }
@@ -1087,7 +1146,7 @@
           };
           this._controllers = [...this._controllers, controllerInfo];
           this.logger.debug("Player joined", { playerIndex });
-          this.config.onControllerJoin?.(playerIndex, controllerInfo);
+          this._onControllerJoinCallbacks.forEach((cb) => cb(playerIndex, controllerInfo));
         }
       });
       this.registerHandler(SMORE_EVENTS.PLAYER_LEFT, (raw) => {
@@ -1097,7 +1156,7 @@
           if (!this._controllers.some((c) => c.playerIndex === playerIndex)) return;
           this._controllers = this._controllers.filter((c) => c.playerIndex !== playerIndex);
           this.logger.debug("Player left", { playerIndex });
-          this.config.onControllerLeave?.(playerIndex);
+          this._onControllerLeaveCallbacks.forEach((cb) => cb(playerIndex));
         }
       });
       this.registerHandler(SMORE_EVENTS.PLAYER_DISCONNECTED, (raw) => {
@@ -1109,7 +1168,7 @@
             (c) => c.playerIndex === playerIndex ? { ...c, connected: false } : c
           );
           this.logger.debug("Player disconnected", { playerIndex });
-          this.config.onControllerDisconnect?.(playerIndex);
+          this._onControllerDisconnectCallbacks.forEach((cb) => cb(playerIndex));
         }
       });
       this.registerHandler(SMORE_EVENTS.PLAYER_RECONNECTED, (raw) => {
@@ -1131,56 +1190,63 @@
             (c) => c.playerIndex === playerIndex ? controllerInfo : c
           );
           this.logger.debug("Player reconnected", { playerIndex });
-          this.config.onControllerReconnect?.(playerIndex, controllerInfo);
+          this._onControllerReconnectCallbacks.forEach((cb) => cb(playerIndex, controllerInfo));
         }
       });
       this.registerHandler(SMORE_EVENTS.PLAYER_CHARACTER_UPDATED, (raw) => {
         const payload = raw;
         const playerData = payload?.player;
         if (playerData && typeof playerData.playerIndex === "number") {
+          const pi = playerData.playerIndex;
           const appearance = playerData.character ?? null;
           this._controllers = this._controllers.map(
-            (c) => c.playerIndex === playerData.playerIndex ? { ...c, appearance } : c
+            (c) => c.playerIndex === pi ? { ...c, appearance } : c
           );
-          this.logger.debug("Player character updated", { playerIndex: playerData.playerIndex });
-          this.config.onCharacterUpdated?.(playerData.playerIndex, appearance ?? null);
+          this.logger.debug("Player character updated", { playerIndex: pi });
+          this._onCharacterUpdatedCallbacks.forEach((cb) => cb(pi, appearance ?? null));
         }
       });
       this.registerHandler(SMORE_EVENTS.RATE_LIMITED, (raw) => {
         const data = raw;
         const event = data?.event ?? "unknown";
         this.logger.warn(`Rate limited: ${event}`);
-        this.config.onRateLimited?.(event);
+        this._onRateLimitedCallbacks.forEach((cb) => cb(event));
       });
       this.registerHandler(SMORE_EVENTS.ALL_READY, () => {
         this.logger.lifecycle("All participants ready");
-        this.config.onAllReady?.();
+        this._allReadyFired = true;
+        this._onAllReadyCallbacks.forEach((cb) => cb());
       });
-      if (this.config.onHostDisconnect) {
-        this.logger.warn("onHostDisconnect is reserved for future use and currently non-functional");
-      }
-      if (this.config.onHostReconnect) {
-        this.logger.warn("onHostReconnect is reserved for future use and currently non-functional");
-      }
-      if (this.config.listeners) {
-        for (const [event, handler] of Object.entries(this.config.listeners)) {
-          if (!handler) continue;
-          this._configListenerEvents.add(event);
-          this.registerHandler(event, (data) => {
-            this.logReceive(event, data);
-            try {
-              handler(data);
-            } catch (err) {
-              this.handleError(
-                new SmoreSDKError("UNKNOWN", `Error in handler for event "${event}"`, {
-                  cause: err instanceof Error ? err : void 0,
-                  details: { event }
-                })
-              );
-            }
-          });
+    }
+    /**
+     * Sets up a user event handler for controller events.
+     * Used for registering pending handlers after transport becomes available.
+     */
+    setupUserEventHandler(event, handler) {
+      const transportHandler = (data) => {
+        this.logReceive(event, data);
+        try {
+          handler(data);
+        } catch (err) {
+          this.handleError(
+            new SmoreSDKError("UNKNOWN", `Error in handler for event "${event}"`, {
+              cause: err instanceof Error ? err : void 0,
+              details: { event }
+            })
+          );
         }
+      };
+      if (this.transport) {
+        this.transport.on(event, transportHandler);
+        this.registeredHandlers.push({ event, handler: transportHandler });
+        this.handlerToTransport.set(handler, { event, transportHandler });
+      }
+      let listeners = this.eventListeners.get(event);
+      if (!listeners) {
+        listeners = /* @__PURE__ */ new Set();
+        this.eventListeners.set(event, listeners);
       }
+      listeners.add(handler);
     }
     registerHandler(event, handler) {
       if (!this.transport) return;
@@ -1188,13 +1254,67 @@
       this.registeredHandlers.push({ event, handler });
     }
     // ---------------------------------------------------------------------------
+    // Lifecycle Methods
+    // ---------------------------------------------------------------------------
+    onAllReady(callback) {
+      if (this._allReadyFired) {
+        callback();
+      }
+      this._onAllReadyCallbacks.add(callback);
+      return () => {
+        this._onAllReadyCallbacks.delete(callback);
+      };
+    }
+    onControllerJoin(callback) {
+      this._onControllerJoinCallbacks.add(callback);
+      return () => {
+        this._onControllerJoinCallbacks.delete(callback);
+      };
+    }
+    onControllerLeave(callback) {
+      this._onControllerLeaveCallbacks.add(callback);
+      return () => {
+        this._onControllerLeaveCallbacks.delete(callback);
+      };
+    }
+    onControllerDisconnect(callback) {
+      this._onControllerDisconnectCallbacks.add(callback);
+      return () => {
+        this._onControllerDisconnectCallbacks.delete(callback);
+      };
+    }
+    onControllerReconnect(callback) {
+      this._onControllerReconnectCallbacks.add(callback);
+      return () => {
+        this._onControllerReconnectCallbacks.delete(callback);
+      };
+    }
+    onCharacterUpdated(callback) {
+      this._onCharacterUpdatedCallbacks.add(callback);
+      return () => {
+        this._onCharacterUpdatedCallbacks.delete(callback);
+      };
+    }
+    onRateLimited(callback) {
+      this._onRateLimitedCallbacks.add(callback);
+      return () => {
+        this._onRateLimitedCallbacks.delete(callback);
+      };
+    }
+    onError(callback) {
+      this._onErrorCallbacks.add(callback);
+      return () => {
+        this._onErrorCallbacks.delete(callback);
+      };
+    }
+    // ---------------------------------------------------------------------------
     // Communication Methods
     // ---------------------------------------------------------------------------
     /**
      * Send an event to the Screen. Controller-to-Controller direct communication
      * is not supported; all messages must go through the Screen.
      *
-     * Data is sent to the Screen only (not to other controllers). For Screen→Controller communication,
+     * Data is sent to the Screen only (not to other controllers). For Screen->Controller communication,
      * Screen uses broadcast() or sendToController().
      *
      * @note Fire-and-forget sends (no callback) will silently fail if rate-limited.
@@ -1228,24 +1348,14 @@
     /**
      * Register a handler for custom events.
      *
+     * Can be called before the Controller is ready. Handlers registered before ready
+     * are queued and activated when the transport becomes available.
+     *
      * When receiving events from Screen's `broadcast()`:
-     *   handler receives `(data)` — no playerIndex included.
+     *   handler receives `(data)` -- no playerIndex included.
      *
      * When receiving events from Screen's `sendToController()`:
-     *   handler receives `(data)` — targeted to this specific controller.
-     *
-     * @note Unlike Screen's `on()` which receives `(playerIndex, data)`,
-     * Controller's `on()` receives only `(data)` since there's only one player per controller.
-     *
-     * Controller's on() handler signature: (data) => void
-     * Unlike Screen's (playerIndex, data) => void, Controller doesn't receive playerIndex
-     * because Controller only receives events from Screen, not from other controllers.
-     * The sender is always the Screen, so playerIndex is not applicable.
-     *
-     * **Important:** If called before the Controller is ready (i.e., before `await createController()`
-     * resolves or before the `onReady` callback fires), the handler is stored locally but
-     * will NOT receive events until the transport is initialized. Always call `on()` after
-     * initialization completes, or use `config.listeners` for handlers needed from the start.
+     *   handler receives `(data)` -- targeted to this specific controller.
      */
     on(event, handler) {
       validateEventName(event);
@@ -1255,34 +1365,42 @@
         this.eventListeners.set(event, listeners);
       }
       listeners.add(handler);
-      const transportHandler = (data) => {
-        this.logReceive(event, data);
-        try {
-          handler(data);
-        } catch (err) {
-          this.handleError(
-            new SmoreSDKError("UNKNOWN", `Error in handler for event "${event}"`, {
-              cause: err instanceof Error ? err : void 0,
-              details: { event }
-            })
-          );
-        }
-      };
       if (this.transport) {
+        const transportHandler = (data) => {
+          this.logReceive(event, data);
+          try {
+            handler(data);
+          } catch (err) {
+            this.handleError(
+              new SmoreSDKError("UNKNOWN", `Error in handler for event "${event}"`, {
+                cause: err instanceof Error ? err : void 0,
+                details: { event }
+              })
+            );
+          }
+        };
         this.transport.on(event, transportHandler);
         this.registeredHandlers.push({ event, handler: transportHandler });
         this.handlerToTransport.set(handler, { event, transportHandler });
+      } else {
+        this._pendingHandlers.push({ event, handler });
       }
       return () => {
         listeners?.delete(handler);
         if (listeners?.size === 0) {
           this.eventListeners.delete(event);
         }
-        this.transport?.off(event, transportHandler);
-        this.registeredHandlers = this.registeredHandlers.filter(
-          (h) => h.handler !== transportHandler
+        this._pendingHandlers = this._pendingHandlers.filter(
+          (p) => !(p.event === event && p.handler === handler)
         );
-        this.handlerToTransport.delete(handler);
+        const entry = this.handlerToTransport.get(handler);
+        if (entry) {
+          this.transport?.off(event, entry.transportHandler);
+          this.registeredHandlers = this.registeredHandlers.filter(
+            (h) => h.handler !== entry.transportHandler
+          );
+          this.handlerToTransport.delete(handler);
+        }
       };
     }
     /**
@@ -1290,16 +1408,6 @@
      *
      * @note The handler is internally wrapped, so it cannot be removed via
      * `off(event, originalHandler)`. Use the returned unsubscribe function instead.
-     *
-     * @example
-     * ```ts
-     * const unsubscribe = controller.once('game-start', (data) => {
-     *   console.log('Game started!', data);
-     * });
-     *
-     * // To cancel before it fires:
-     * unsubscribe();
-     * ```
      */
     once(event, handler) {
       const unsubscribe = this.on(event, ((data) => {
@@ -1310,24 +1418,13 @@
     }
     off(event, handler) {
       if (!handler) {
-        if (this._configListenerEvents.has(event)) {
-          for (const [key, val] of this.handlerToTransport) {
-            if (val.event === event) {
-              this.transport?.off(event, val.transportHandler);
-              this.registeredHandlers = this.registeredHandlers.filter(
-                (h) => h.handler !== val.transportHandler
-              );
-              this.handlerToTransport.delete(key);
-            }
-          }
-        } else {
-          this.eventListeners.delete(event);
-          this.transport?.off(event);
-          this.registeredHandlers = this.registeredHandlers.filter((h) => h.event !== event);
-          for (const [key, val] of this.handlerToTransport) {
-            if (val.event === event) this.handlerToTransport.delete(key);
-          }
+        this.eventListeners.delete(event);
+        this.transport?.off(event);
+        this.registeredHandlers = this.registeredHandlers.filter((h) => h.event !== event);
+        for (const [key, val] of this.handlerToTransport) {
+          if (val.event === event) this.handlerToTransport.delete(key);
         }
+        this._pendingHandlers = this._pendingHandlers.filter((p) => p.event !== event);
       } else {
         const listeners = this.eventListeners.get(event);
         listeners?.delete(handler);
@@ -1342,6 +1439,9 @@
           );
           this.handlerToTransport.delete(handler);
         }
+        this._pendingHandlers = this._pendingHandlers.filter(
+          (p) => !(p.event === event && p.handler === handler)
+        );
       }
     }
     // ---------------------------------------------------------------------------
@@ -1350,10 +1450,15 @@
     destroy() {
       if (this._isDestroyed) return;
       this.logger.lifecycle("Destroying controller");
-      this.cleanup();
       this._isDestroyed = true;
+      this._isReady = false;
+      this.cleanup();
     }
     cleanup() {
+      if (this._initTimeoutId) {
+        clearTimeout(this._initTimeoutId);
+        this._initTimeoutId = null;
+      }
       this._isReady = false;
       for (const { event, handler } of this.registeredHandlers) {
         this.transport?.off(event, handler);
@@ -1361,6 +1466,15 @@
       this.registeredHandlers = [];
       this.eventListeners.clear();
       this.handlerToTransport.clear();
+      this._pendingHandlers = [];
+      this._onAllReadyCallbacks.clear();
+      this._onControllerJoinCallbacks.clear();
+      this._onControllerLeaveCallbacks.clear();
+      this._onControllerDisconnectCallbacks.clear();
+      this._onControllerReconnectCallbacks.clear();
+      this._onCharacterUpdatedCallbacks.clear();
+      this._onRateLimitedCallbacks.clear();
+      this._onErrorCallbacks.clear();
       if (this.transport) {
         this.transport.destroy();
         this.transport = null;
@@ -1384,15 +1498,16 @@
       if (!this._isReady || !this.transport) {
         throw new SmoreSDKError(
           "NOT_READY",
-          `Cannot call ${method}() before controller is ready. Use await createController() or wait for onReady callback.`,
+          `Cannot call ${method}() before controller is ready. Use await controller.ready.`,
           { details: { method, isReady: this._isReady } }
         );
       }
     }
     handleError(error) {
       this.logger.warn(`Error in handler: ${error.message}`);
-      if (this.config.onError) {
-        this.config.onError(error.toSmoreError());
+      const smoreError = error.toSmoreError();
+      if (this._onErrorCallbacks.size > 0) {
+        this._onErrorCallbacks.forEach((cb) => cb(smoreError));
       } else {
         this.logger.error(error.message, error.details);
       }
@@ -1405,49 +1520,32 @@
     }
   }
   function createController(config) {
-    const controller = new ControllerImpl(config ?? {});
-    const promise = controller.initialize().then(() => controller);
-    promise.instance = controller;
-    return promise;
+    return new ControllerImpl(config ?? {});
   }
 
   function createMockScreen(options = {}) {
     const {
       roomCode = "TEST",
       controllers: initialControllers = [],
-      autoReady = true,
-      onReady: onReadyCb,
-      onControllerJoin: onJoinCb,
-      onControllerLeave: onLeaveCb,
-      onControllerDisconnect: onDisconnectCb,
-      onControllerReconnect: onReconnectCb,
-      onCharacterUpdated: onCharacterUpdatedCb,
-      onRateLimited: onRateLimitedCb,
-      onAllReady: onAllReadyCb,
-      onError: onErrorCb
+      autoReady = true
     } = options;
     let _controllers = [...initialControllers];
     let _isReady = false;
     let _isDestroyed = false;
     const listeners = /* @__PURE__ */ new Map();
-    let onReadyCallback;
-    let onControllerJoinCallback;
-    let onControllerLeaveCallback;
-    let onControllerDisconnectCallback;
-    let onControllerReconnectCallback;
-    let onCharacterUpdatedCallback;
-    let onRateLimitedCallback;
-    let onAllReadyCallback;
-    let onErrorCallback;
-    onReadyCallback = onReadyCb;
-    onControllerJoinCallback = onJoinCb;
-    onControllerLeaveCallback = onLeaveCb;
-    onControllerDisconnectCallback = onDisconnectCb;
-    onControllerReconnectCallback = onReconnectCb;
-    onCharacterUpdatedCallback = onCharacterUpdatedCb;
-    onRateLimitedCallback = onRateLimitedCb;
-    onAllReadyCallback = onAllReadyCb;
-    onErrorCallback = onErrorCb;
+    const _onAllReadyCallbacks = /* @__PURE__ */ new Set();
+    const _onControllerJoinCallbacks = /* @__PURE__ */ new Set();
+    const _onControllerLeaveCallbacks = /* @__PURE__ */ new Set();
+    const _onControllerDisconnectCallbacks = /* @__PURE__ */ new Set();
+    const _onControllerReconnectCallbacks = /* @__PURE__ */ new Set();
+    const _onCharacterUpdatedCallbacks = /* @__PURE__ */ new Set();
+    const _onRateLimitedCallbacks = /* @__PURE__ */ new Set();
+    const _onErrorCallbacks = /* @__PURE__ */ new Set();
+    let _allReadyFired = false;
+    let _readyResolve;
+    const _readyPromise = new Promise((resolve) => {
+      _readyResolve = resolve;
+    });
     const broadcasts = [];
     const sends = [];
     const screen = {
@@ -1464,6 +1562,61 @@
       get isDestroyed() {
         return _isDestroyed;
       },
+      get ready() {
+        return _readyPromise;
+      },
+      // === Lifecycle Methods ===
+      onAllReady(callback) {
+        if (_allReadyFired) {
+          callback();
+        }
+        _onAllReadyCallbacks.add(callback);
+        return () => {
+          _onAllReadyCallbacks.delete(callback);
+        };
+      },
+      onControllerJoin(callback) {
+        _onControllerJoinCallbacks.add(callback);
+        return () => {
+          _onControllerJoinCallbacks.delete(callback);
+        };
+      },
+      onControllerLeave(callback) {
+        _onControllerLeaveCallbacks.add(callback);
+        return () => {
+          _onControllerLeaveCallbacks.delete(callback);
+        };
+      },
+      onControllerDisconnect(callback) {
+        _onControllerDisconnectCallbacks.add(callback);
+        return () => {
+          _onControllerDisconnectCallbacks.delete(callback);
+        };
+      },
+      onControllerReconnect(callback) {
+        _onControllerReconnectCallbacks.add(callback);
+        return () => {
+          _onControllerReconnectCallbacks.delete(callback);
+        };
+      },
+      onCharacterUpdated(callback) {
+        _onCharacterUpdatedCallbacks.add(callback);
+        return () => {
+          _onCharacterUpdatedCallbacks.delete(callback);
+        };
+      },
+      onRateLimited(callback) {
+        _onRateLimitedCallbacks.add(callback);
+        return () => {
+          _onRateLimitedCallbacks.delete(callback);
+        };
+      },
+      onError(callback) {
+        _onErrorCallbacks.add(callback);
+        return () => {
+          _onErrorCallbacks.delete(callback);
+        };
+      },
       // === Communication Methods ===
       broadcast(event, data) {
         if (_isDestroyed) {
@@ -1591,24 +1744,14 @@
       },
       simulateControllerJoin(info) {
         _controllers.push(info);
-        if (onControllerJoinCallback) {
-          onControllerJoinCallback(info.playerIndex, info);
-        }
+        _onControllerJoinCallbacks.forEach((cb) => cb(info.playerIndex, info));
       },
       simulateControllerLeave(playerIndex) {
         _controllers = _controllers.filter((c) => c.playerIndex !== playerIndex);
-        if (onControllerLeaveCallback) {
-          onControllerLeaveCallback(playerIndex);
-        }
+        _onControllerLeaveCallbacks.forEach((cb) => cb(playerIndex));
       },
       /**
        * Simulate a controller network disconnect (player still in room but unreachable).
-       *
-       * @example
-       * ```ts
-       * screen.simulateControllerDisconnect(0);
-       * expect(screen.getController(0)?.connected).toBe(false);
-       * ```
        */
       simulateControllerDisconnect(playerIndex) {
         const controller = _controllers.find((c) => c.playerIndex === playerIndex);
@@ -1618,19 +1761,10 @@
         _controllers = _controllers.map(
           (c) => c.playerIndex === playerIndex ? { ...c, connected: false } : c
         );
-        if (onControllerDisconnectCallback) {
-          onControllerDisconnectCallback(playerIndex);
-        }
+        _onControllerDisconnectCallbacks.forEach((cb) => cb(playerIndex));
       },
       /**
        * Simulate a controller network reconnect after disconnect.
-       *
-       * @example
-       * ```ts
-       * screen.simulateControllerDisconnect(0);
-       * screen.simulateControllerReconnect(0);
-       * expect(screen.getController(0)?.connected).toBe(true);
-       * ```
        */
       simulateControllerReconnect(playerIndex) {
         const controller = _controllers.find((c) => c.playerIndex === playerIndex);
@@ -1641,9 +1775,7 @@
         _controllers = _controllers.map(
           (c) => c.playerIndex === playerIndex ? reconnectedController : c
         );
-        if (onControllerReconnectCallback) {
-          onControllerReconnectCallback(playerIndex, reconnectedController);
-        }
+        _onControllerReconnectCallbacks.forEach((cb) => cb(playerIndex, reconnectedController));
       },
       simulateCharacterUpdate(playerIndex, appearance) {
         const controller = _controllers.find((c) => c.playerIndex === playerIndex);
@@ -1653,24 +1785,17 @@
         _controllers = _controllers.map(
           (c) => c.playerIndex === playerIndex ? { ...c, appearance } : c
         );
-        if (onCharacterUpdatedCallback) {
-          onCharacterUpdatedCallback(playerIndex, appearance);
-        }
+        _onCharacterUpdatedCallbacks.forEach((cb) => cb(playerIndex, appearance));
       },
       simulateRateLimited(event) {
-        if (onRateLimitedCallback) {
-          onRateLimitedCallback(event);
-        }
+        _onRateLimitedCallbacks.forEach((cb) => cb(event));
       },
       simulateAllReady() {
-        if (onAllReadyCallback) {
-          onAllReadyCallback();
-        }
+        _allReadyFired = true;
+        _onAllReadyCallbacks.forEach((cb) => cb());
       },
       simulateError(error) {
-        if (onErrorCallback) {
-          onErrorCallback(error);
-        }
+        _onErrorCallbacks.forEach((cb) => cb(error));
       },
       getBroadcasts() {
         return [...broadcasts];
@@ -1684,9 +1809,7 @@
       },
       triggerReady() {
         _isReady = true;
-        if (onReadyCallback) {
-          onReadyCallback();
-        }
+        _readyResolve();
       }
     };
     if (autoReady) {
@@ -1698,39 +1821,25 @@
     const {
       roomCode = "TEST",
       myIndex = 0,
-      autoReady = true,
-      onReady: onReadyCb,
-      onControllerJoin: onJoinCb,
-      onControllerLeave: onLeaveCb,
-      onControllerDisconnect: onDisconnectCb,
-      onControllerReconnect: onReconnectCb,
-      onCharacterUpdated: onCharacterUpdatedCb,
-      onRateLimited: onRateLimitedCb,
-      onAllReady: onAllReadyCb,
-      onError: onErrorCb
+      autoReady = true
     } = options;
     let _isReady = false;
     let _isDestroyed = false;
     let _controllers = options.controllers ?? [];
     const listeners = /* @__PURE__ */ new Map();
-    let onReadyCallback;
-    let onControllerJoinCallback;
-    let onControllerLeaveCallback;
-    let onControllerDisconnectCallback;
-    let onControllerReconnectCallback;
-    let onCharacterUpdatedCallback;
-    let onRateLimitedCallback;
-    let onAllReadyCallback;
-    let onErrorCallback;
-    onReadyCallback = onReadyCb;
-    onControllerJoinCallback = onJoinCb;
-    onControllerLeaveCallback = onLeaveCb;
-    onControllerDisconnectCallback = onDisconnectCb;
-    onControllerReconnectCallback = onReconnectCb;
-    onCharacterUpdatedCallback = onCharacterUpdatedCb;
-    onRateLimitedCallback = onRateLimitedCb;
-    onAllReadyCallback = onAllReadyCb;
-    onErrorCallback = onErrorCb;
+    const _onAllReadyCallbacks = /* @__PURE__ */ new Set();
+    const _onControllerJoinCallbacks = /* @__PURE__ */ new Set();
+    const _onControllerLeaveCallbacks = /* @__PURE__ */ new Set();
+    const _onControllerDisconnectCallbacks = /* @__PURE__ */ new Set();
+    const _onControllerReconnectCallbacks = /* @__PURE__ */ new Set();
+    const _onCharacterUpdatedCallbacks = /* @__PURE__ */ new Set();
+    const _onRateLimitedCallbacks = /* @__PURE__ */ new Set();
+    const _onErrorCallbacks = /* @__PURE__ */ new Set();
+    let _allReadyFired = false;
+    let _readyResolve;
+    const _readyPromise = new Promise((resolve) => {
+      _readyResolve = resolve;
+    });
     const sentEvents = [];
     const controller = {
       // === Properties ===
@@ -1749,6 +1858,61 @@
       get controllers() {
         return [..._controllers];
       },
+      get ready() {
+        return _readyPromise;
+      },
+      // === Lifecycle Methods ===
+      onAllReady(callback) {
+        if (_allReadyFired) {
+          callback();
+        }
+        _onAllReadyCallbacks.add(callback);
+        return () => {
+          _onAllReadyCallbacks.delete(callback);
+        };
+      },
+      onControllerJoin(callback) {
+        _onControllerJoinCallbacks.add(callback);
+        return () => {
+          _onControllerJoinCallbacks.delete(callback);
+        };
+      },
+      onControllerLeave(callback) {
+        _onControllerLeaveCallbacks.add(callback);
+        return () => {
+          _onControllerLeaveCallbacks.delete(callback);
+        };
+      },
+      onControllerDisconnect(callback) {
+        _onControllerDisconnectCallbacks.add(callback);
+        return () => {
+          _onControllerDisconnectCallbacks.delete(callback);
+        };
+      },
+      onControllerReconnect(callback) {
+        _onControllerReconnectCallbacks.add(callback);
+        return () => {
+          _onControllerReconnectCallbacks.delete(callback);
+        };
+      },
+      onCharacterUpdated(callback) {
+        _onCharacterUpdatedCallbacks.add(callback);
+        return () => {
+          _onCharacterUpdatedCallbacks.delete(callback);
+        };
+      },
+      onRateLimited(callback) {
+        _onRateLimitedCallbacks.add(callback);
+        return () => {
+          _onRateLimitedCallbacks.delete(callback);
+        };
+      },
+      onError(callback) {
+        _onErrorCallbacks.add(callback);
+        return () => {
+          _onErrorCallbacks.delete(callback);
+        };
+      },
       getControllerCount() {
         return _controllers.filter((c) => c.connected).length;
       },
@@ -1829,105 +1993,62 @@
       },
       triggerReady() {
         _isReady = true;
-        if (onReadyCallback) {
-          onReadyCallback();
-        }
+        _readyResolve();
       },
       /**
        * Simulate a new player joining the room.
        * Stores full ControllerInfo (nickname, appearance, etc.) for later retrieval.
-       *
-       * @example
-       * ```ts
-       * controller.simulatePlayerJoin(2, { playerIndex: 2, nickname: 'Alice', connected: true });
-       * expect(controller.getControllerCount()).toBe(3);
-       * expect(controller.controllers.find(c => c.playerIndex === 2)?.nickname).toBe('Alice');
-       * ```
        */
       simulatePlayerJoin(playerIndex, info) {
         if (!_controllers.some((c) => c.playerIndex === playerIndex)) {
           _controllers = [..._controllers, { ...info, connected: info.connected ?? true }];
         }
-        if (onControllerJoinCallback) {
-          onControllerJoinCallback(playerIndex, info);
-        }
+        _onControllerJoinCallbacks.forEach((cb) => cb(playerIndex, info));
       },
       /**
        * Simulate a player leaving the room (fully removed).
-       *
-       * @example
-       * ```ts
-       * controller.simulatePlayerLeave(1);
-       * expect(controller.controllers.some(c => c.playerIndex === 1)).toBe(false);
-       * ```
        */
       simulatePlayerLeave(playerIndex) {
         _controllers = _controllers.filter((c) => c.playerIndex !== playerIndex);
-        if (onControllerLeaveCallback) {
-          onControllerLeaveCallback(playerIndex);
-        }
+        _onControllerLeaveCallbacks.forEach((cb) => cb(playerIndex));
       },
       /**
        * Simulate a player network disconnect (player still in room but unreachable).
-       *
-       * @example
-       * ```ts
-       * controller.simulatePlayerDisconnect(1);
-       * expect(controller.controllers.find(c => c.playerIndex === 1)?.connected).toBe(false);
-       * ```
        */
       simulatePlayerDisconnect(playerIndex) {
         _controllers = _controllers.map(
           (c) => c.playerIndex === playerIndex ? { ...c, connected: false } : c
         );
-        if (onControllerDisconnectCallback) {
-          onControllerDisconnectCallback(playerIndex);
-        }
+        _onControllerDisconnectCallbacks.forEach((cb) => cb(playerIndex));
       },
       /**
        * Simulate a player network reconnect after disconnect.
-       *
-       * @example
-       * ```ts
-       * controller.simulatePlayerDisconnect(1);
-       * controller.simulatePlayerReconnect(1, { playerIndex: 1, nickname: 'Bob', connected: true });
-       * expect(controller.controllers.find(c => c.playerIndex === 1)?.connected).toBe(true);
-       * ```
        */
       simulatePlayerReconnect(playerIndex, info) {
         _controllers = _controllers.map(
           (c) => c.playerIndex === playerIndex ? { ...info, connected: true } : c
         );
-        if (onControllerReconnectCallback) {
-          onControllerReconnectCallback(playerIndex, info);
-        }
+        _onControllerReconnectCallbacks.forEach((cb) => cb(playerIndex, info));
       },
       simulateCharacterUpdate(playerIndex, appearance) {
-        const controller2 = _controllers.find((c) => c.playerIndex === playerIndex);
-        if (!controller2) {
+        const ctrl = _controllers.find((c) => c.playerIndex === playerIndex);
+        if (!ctrl) {
           throw new Error(`Controller ${playerIndex} not found`);
         }
         _controllers = _controllers.map(
           (c) => c.playerIndex === playerIndex ? { ...c, appearance } : c
         );
-        if (onCharacterUpdatedCallback) {
-          onCharacterUpdatedCallback(playerIndex, appearance);
-        }
+        _onCharacterUpdatedCallbacks.forEach((cb) => cb(playerIndex, appearance));
       },
       simulateRateLimited(event) {
-        if (onRateLimitedCallback) {
-          onRateLimitedCallback(event);
-        }
+        _onRateLimitedCallbacks.forEach((cb) => cb(event));
       },
       simulateAllReady() {
-        if (onAllReadyCallback) {
-          onAllReadyCallback();
-        }
+        _allReadyFired = true;
+        _onAllReadyCallbacks.forEach((cb) => cb());
       },
       simulateError(error) {
-        if (onErrorCallback) {
-          onErrorCallback(error);
-        }
+        _onErrorCallbacks.forEach((cb) => cb(error));
       }
     };
     if (autoReady) {