@smoregg/sdk 1.3.0 → 2.1.0

package/dist/cjs/screen.cjs

@@ -5,7 +5,7 @@ var protocol = require('./transport/protocol.cjs');
 var errors = require('./errors.cjs');
 var events = require('./events.cjs');
 var logger = require('./logger.cjs');
-var config = require('./config.cjs');
+var shared = require('./shared.cjs');
 
 const DEFAULT_TIMEOUT = 1e4;
 function validatePlayerIndex(playerIndex, controllers) {
@@ -28,131 +28,165 @@ class ScreenImpl {
   _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 = [];
+  // Unified lifecycle listener map (supports both onXxx() and on('$xxx') patterns)
+  _lifecycleListeners = /* @__PURE__ */ new Map();
+  // Outbound message buffer (messages sent before ready)
+  _outboundBuffer = [];
+  // Whether all-ready has fired
+  _allReadyFired = false;
+  // Self-connection awareness
+  _isConnected = false;
+  // Protocol versioning
+  _protocolVersion = protocol.PROTOCOL_VERSION;
+  // Ready promise
+  _readyResolve;
+  _readyReject;
+  ready;
   constructor(config = {}) {
     this.config = config;
     this.logger = new logger.DebugLogger(config.debug, "[SmoreScreen]");
-    if (config.listeners) {
-      for (const event of Object.keys(config.listeners)) {
-        events.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;
-    return new Promise((resolve, reject) => {
-      const timeoutId = setTimeout(() => {
-        this.cleanup();
-        const error = new errors.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 (!protocol.isBridgeMessage(msg)) return;
-        if (msg.type === "_bridge:init") {
-          clearTimeout(timeoutId);
-          const initPayload = msg.payload;
-          try {
-            protocol.validateInitPayload(initPayload);
-          } catch (err) {
-            const error = new errors.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 errors.SmoreSDKError(
-              "INIT_FAILED",
-              `Received init for wrong side: ${initData.side}. Expected "host".`,
-              { details: { side: initData.side } }
+    this._initTimeoutId = setTimeout(() => {
+      this.cleanup();
+      const error = new errors.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 (!protocol.isBridgeMessage(msg)) return;
+      if (msg.type === "_bridge:init") {
+        clearTimeout(this._initTimeoutId);
+        const initPayload = msg.payload;
+        try {
+          protocol.validateInitPayload(initPayload);
+        } catch (err) {
+          const error = new errors.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 errors.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 = this.config.transport ?? new PostMessageTransport.PostMessageTransport(parentOrigin);
+        this._roomCode = initData.roomCode;
+        const serverProtocolVersion = initData.protocolVersion;
+        if (serverProtocolVersion !== void 0) {
+          this._protocolVersion = serverProtocolVersion;
+          if (serverProtocolVersion !== protocol.PROTOCOL_VERSION) {
+            this.logger.warn(
+              `Protocol version mismatch: SDK v${protocol.PROTOCOL_VERSION}, server v${serverProtocolVersion}. Some features may not work correctly.`
             );
-            this.handleError(error);
-            reject(error);
-            return;
-          }
-          this.transport = new PostMessageTransport.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
-          });
-          const autoReady = config.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;
+        }
+        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._isConnected = true;
+        this._isReady = true;
+        for (const buffered of this._outboundBuffer) {
+          try {
+            switch (buffered.method) {
+              case "broadcast":
+                this.broadcast(buffered.args[0], buffered.args[1]);
+                break;
+              case "sendToController":
+                this.sendToController(buffered.args[0], buffered.args[1], buffered.args[2]);
+                break;
+            }
+          } catch (err) {
+            this.handleError(err instanceof errors.SmoreSDKError ? err : new errors.SmoreSDKError("UNKNOWN", "Failed to flush buffered message"));
           }
-          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._outboundBuffer = [];
+        this.logger.lifecycle("Screen ready", {
+          roomCode: this._roomCode,
+          controllers: this._controllers.length
+        });
+        if (this.config.autoReady !== false) {
+          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._emitLifecycle("$controller-join", 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._emitLifecycle("$controller-leave", 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", protocolVersion: protocol.PROTOCOL_VERSION }, parentOrigin);
+    this.logger.lifecycle("Sent _bridge:ready to parent");
   }
   mapControllersFromInit(players) {
-    return players.map((p, index) => ({
-      playerIndex: p.playerIndex ?? index,
-      // Fallback to `nickname` for defensive compatibility (server currently always sends `name`)
-      nickname: p.nickname || p.name || `Player ${index + 1}`,
-      connected: p.connected !== false,
-      // Fallback to `appearance` for defensive compatibility (server currently always sends `character`)
-      appearance: p.appearance ?? p.character
-    }));
+    return players.map((p, index) => shared.mapPlayerDTO(p, index));
   }
   setupEventHandlers() {
     if (!this.transport) return;
@@ -160,16 +194,11 @@ class ScreenImpl {
       const payload = data;
       const playerData = payload?.player;
       if (playerData && typeof playerData.playerIndex === "number") {
-        const controllerInfo = {
-          playerIndex: playerData.playerIndex,
-          nickname: playerData.nickname || playerData.name || `Player ${playerData.playerIndex + 1}`,
-          connected: playerData.connected !== false,
-          appearance: playerData.appearance ?? playerData.character
-        };
+        const controllerInfo = shared.mapPlayerDTO(playerData, playerData.playerIndex);
         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._emitLifecycle("$controller-join", controllerInfo.playerIndex, controllerInfo);
       }
     });
     this.registerTransportHandler(events.SMORE_EVENTS.PLAYER_LEFT, (data) => {
@@ -179,7 +208,7 @@ class ScreenImpl {
         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._emitLifecycle("$controller-leave", playerIndex);
       }
     });
     this.registerTransportHandler(events.SMORE_EVENTS.PLAYER_DISCONNECTED, (data) => {
@@ -190,55 +219,58 @@ class ScreenImpl {
           (c) => c.playerIndex === playerIndex ? { ...c, connected: false } : c
         );
         this.logger.lifecycle("Controller disconnected", { playerIndex });
-        this.config.onControllerDisconnect?.(playerIndex);
+        this._emitLifecycle("$controller-disconnect", playerIndex);
       }
     });
     this.registerTransportHandler(events.SMORE_EVENTS.PLAYER_RECONNECTED, (data) => {
       const payload = data;
       const playerData = payload?.player;
       if (playerData && typeof playerData.playerIndex === "number") {
-        const controllerInfo = {
-          playerIndex: playerData.playerIndex,
-          nickname: playerData.nickname || playerData.name || `Player ${playerData.playerIndex + 1}`,
-          connected: true,
-          appearance: playerData.appearance ?? playerData.character
-        };
+        const controllerInfo = shared.mapPlayerDTO(playerData, playerData.playerIndex);
         this._controllers = this._controllers.map(
           (c) => c.playerIndex === controllerInfo.playerIndex ? controllerInfo : c
         );
         this.logger.lifecycle("Controller reconnected", { playerIndex: controllerInfo.playerIndex });
-        this.config.onControllerReconnect?.(controllerInfo.playerIndex, controllerInfo);
+        this._emitLifecycle("$controller-reconnect", controllerInfo.playerIndex, controllerInfo);
       }
     });
     this.registerTransportHandler(events.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._emitLifecycle("$character-updated", pi, appearance ?? null);
       }
     });
     this.registerTransportHandler(events.SMORE_EVENTS.RATE_LIMITED, (data) => {
       const payload = data;
-      const event = payload?.event ?? "unknown";
-      this.logger.warn(`Rate limited: ${event}`);
-      this.config.onRateLimited?.(event);
+      const eventName = payload?.event ?? "unknown";
+      this.handleError(
+        new errors.SmoreSDKError("RATE_LIMITED", `Server rate-limited event: ${eventName}`, {
+          details: { event: eventName }
+        })
+      );
     });
     this.registerTransportHandler(events.SMORE_EVENTS.ALL_READY, () => {
       this.logger.lifecycle("All participants ready");
-      this.config.onReady?.();
+      this._allReadyFired = true;
+      this._emitLifecycle("$all-ready");
+    });
+    this.registerTransportHandler(events.SMORE_EVENTS.SELF_DISCONNECTED, () => {
+      this._isConnected = false;
+      this.logger.lifecycle("Connection lost");
+      this._emitLifecycle("$connection-change", false);
+    });
+    this.registerTransportHandler(events.SMORE_EVENTS.SELF_RECONNECTED, () => {
+      this._isConnected = true;
+      this.logger.lifecycle("Connection restored");
+      this._emitLifecycle("$connection-change", true);
     });
-    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.
@@ -280,6 +312,7 @@ class ScreenImpl {
       this.eventHandlers.set(event, handlers);
     }
     handlers.add(handler);
+    this.handlerToTransport.set(handler, { event, transportHandler: wrappedHandler });
   }
   registerTransportHandler(event, handler) {
     if (!this.transport) return;
@@ -305,6 +338,75 @@ class ScreenImpl {
   get isDestroyed() {
     return this._isDestroyed;
   }
+  get isConnected() {
+    return this._isConnected;
+  }
+  get protocolVersion() {
+    return this._protocolVersion;
+  }
+  // ---------------------------------------------------------------------------
+  // Lifecycle Listener Helpers
+  // ---------------------------------------------------------------------------
+  _addLifecycleListener(event, listener) {
+    let set = this._lifecycleListeners.get(event);
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      this._lifecycleListeners.set(event, set);
+    }
+    set.add(listener);
+    return () => {
+      set.delete(listener);
+      if (set.size === 0) this._lifecycleListeners.delete(event);
+    };
+  }
+  _emitLifecycle(event, ...args) {
+    this._lifecycleListeners.get(event)?.forEach((cb) => {
+      try {
+        cb(...args);
+      } catch (err) {
+        this.handleError(
+          new errors.SmoreSDKError("UNKNOWN", `Error in lifecycle handler for "${event}"`, {
+            cause: err instanceof Error ? err : void 0,
+            details: { event }
+          })
+        );
+      }
+    });
+  }
+  _hasLifecycleListeners(event) {
+    const set = this._lifecycleListeners.get(event);
+    return set !== void 0 && set.size > 0;
+  }
+  // ---------------------------------------------------------------------------
+  // Lifecycle Methods
+  // ---------------------------------------------------------------------------
+  onAllReady(callback) {
+    if (this._allReadyFired) {
+      callback();
+    }
+    return this._addLifecycleListener("$all-ready", callback);
+  }
+  onControllerJoin(callback) {
+    return this._addLifecycleListener("$controller-join", callback);
+  }
+  onControllerLeave(callback) {
+    return this._addLifecycleListener("$controller-leave", callback);
+  }
+  onControllerDisconnect(callback) {
+    return this._addLifecycleListener("$controller-disconnect", callback);
+  }
+  onControllerReconnect(callback) {
+    return this._addLifecycleListener("$controller-reconnect", callback);
+  }
+  onCharacterUpdated(callback) {
+    return this._addLifecycleListener("$character-updated", callback);
+  }
+  onError(callback) {
+    return this._addLifecycleListener("$error", callback);
+  }
+  onConnectionChange(callback) {
+    return this._addLifecycleListener("$connection-change", callback);
+  }
   // ---------------------------------------------------------------------------
   // Communication Methods
   // ---------------------------------------------------------------------------
@@ -312,7 +414,6 @@ class ScreenImpl {
    * Send type-safe events to all controllers.
    *
    * Uses EventMap generic for compile-time type checking of event names and data payloads.
-   * Runtime behavior is identical to broadcastRaw - both call validateEventName at runtime.
    *
    * @note Data should be an object. Primitive values will be wrapped as `{ data: value }` by the relay server.
    * @note Maximum payload size is 64KB. Data exceeding this limit will be silently dropped by the server.
@@ -321,31 +422,18 @@ class ScreenImpl {
    *
    * Warning: Avoid sending primitive values directly (string, number, boolean).
    * Wrap in an object: broadcast('event', { value: 42 }) instead of broadcast('event', 42)
-   *
-   * @see broadcastRaw for bypassing TypeScript type checking (runtime behavior identical)
    */
   broadcast(event, data) {
-    this.ensureReady("broadcast");
-    events.validateEventName(event);
-    this.logger.send(event, data);
-    this.transport.emit(event, data);
-  }
-  /**
-   * Send events to all controllers without TypeScript type checking.
-   *
-   * Bypasses EventMap generic type checks at compile time.
-   * Runtime behavior is identical to broadcast - both call validateEventName at runtime.
-   *
-   * Use this when you need dynamic event names or when working without a predefined EventMap.
-   *
-   * @note Data should be an object. Primitive values will be wrapped as `{ data: value }` by the relay server.
-   * @note Maximum payload size is 64KB. Data exceeding this limit will be silently dropped by the server.
-   *
-   * @see broadcast for type-safe version using EventMap generic
-   */
-  broadcastRaw(event, data) {
-    this.ensureReady("broadcastRaw");
+    if (this._isDestroyed) {
+      throw new errors.SmoreSDKError("DESTROYED", "Cannot call broadcast() after destroy()");
+    }
+    if (!this._isReady || !this.transport) {
+      this._outboundBuffer.push({ method: "broadcast", args: [event, data] });
+      this.logger.debug(`Buffered broadcast "${event}" (screen not ready yet)`);
+      return;
+    }
     events.validateEventName(event);
+    shared.validatePayloadSize(data);
     this.logger.send(event, data);
     this.transport.emit(event, data);
   }
@@ -364,24 +452,17 @@ class ScreenImpl {
    * @param data - Event data payload
    */
   sendToController(playerIndex, event, data) {
-    this.ensureReady("sendToController");
-    events.validateEventName(event);
-    validatePlayerIndex(playerIndex, this._controllers);
-    if (data && typeof data === "object" && "targetPlayerIndex" in data) {
-      this.logger.warn(
-        `Event "${event}" data contains reserved field "targetPlayerIndex" which will be overwritten for routing.`
-      );
+    if (this._isDestroyed) {
+      throw new errors.SmoreSDKError("DESTROYED", "Cannot call sendToController() after destroy()");
+    }
+    if (!this._isReady || !this.transport) {
+      this._outboundBuffer.push({ method: "sendToController", args: [playerIndex, event, data] });
+      this.logger.debug(`Buffered sendToController "${event}" -> Player ${playerIndex} (screen not ready yet)`);
+      return;
     }
-    this.logger.send(`${event} -> Player ${playerIndex}`, data);
-    this.transport.emit(event, {
-      targetPlayerIndex: playerIndex,
-      ...data && typeof data === "object" ? data : { data }
-    });
-  }
-  sendToControllerRaw(playerIndex, event, data) {
-    this.ensureReady("sendToControllerRaw");
     events.validateEventName(event);
     validatePlayerIndex(playerIndex, this._controllers);
+    shared.validatePayloadSize(data);
     if (data && typeof data === "object" && "targetPlayerIndex" in data) {
       this.logger.warn(
         `Event "${event}" data contains reserved field "targetPlayerIndex" which will be overwritten for routing.`
@@ -412,13 +493,20 @@ class ScreenImpl {
   /**
    * 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) {
+    if (typeof event === "string" && event.startsWith("$")) {
+      const validEvents = events.SCREEN_LIFECYCLE_EVENTS;
+      if (!validEvents.has(event)) {
+        throw new errors.SmoreSDKError("INVALID_EVENT", `Unknown lifecycle event: "${event}". Valid lifecycle events: ${Array.from(validEvents).join(", ")}`);
+      }
+      if (event === "$all-ready" && this._allReadyFired) {
+        handler();
+      }
+      return this._addLifecycleListener(event, handler);
+    }
     events.validateEventName(event);
     let handlers = this.eventHandlers.get(event);
     if (!handlers) {
@@ -426,9 +514,8 @@ class ScreenImpl {
       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;
@@ -448,16 +535,22 @@ class ScreenImpl {
       };
       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);
       }
@@ -474,18 +567,25 @@ class ScreenImpl {
    * @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) {
+    if (typeof event === "string" && event.startsWith("$")) {
+      const validEvents = events.SCREEN_LIFECYCLE_EVENTS;
+      if (!validEvents.has(event)) {
+        throw new errors.SmoreSDKError("INVALID_EVENT", `Unknown lifecycle event: "${event}"`);
+      }
+      if (event === "$all-ready" && this._allReadyFired) {
+        handler();
+        return () => {
+        };
+      }
+      const wrapper = (...args) => {
+        unsub();
+        handler(...args);
+      };
+      const unsub = this._addLifecycleListener(event, wrapper);
+      return unsub;
+    }
     const wrappedHandler = (playerIndex, data) => {
       unsubscribe();
       handler(playerIndex, data);
@@ -494,25 +594,22 @@ class ScreenImpl {
     return unsubscribe;
   }
   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);
-          }
-        }
+    if (typeof event === "string" && event.startsWith("$")) {
+      if (!handler) {
+        this._lifecycleListeners.delete(event);
       } 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._lifecycleListeners.get(event)?.delete(handler);
+      }
+      return;
+    }
+    if (!handler) {
+      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);
@@ -527,6 +624,24 @@ class ScreenImpl {
         );
         this.handlerToTransport.delete(handler);
       }
+      this._pendingHandlers = this._pendingHandlers.filter(
+        (p) => !(p.event === event && p.handler === handler)
+      );
+    }
+  }
+  removeAllListeners(event) {
+    if (event) {
+      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 {
+      for (const evt of [...this.eventHandlers.keys()]) {
+        this.removeAllListeners(evt);
+      }
     }
   }
   // ---------------------------------------------------------------------------
@@ -538,28 +653,6 @@ class ScreenImpl {
   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);
-  }
   // ---------------------------------------------------------------------------
   // Cleanup
   // ---------------------------------------------------------------------------
@@ -572,12 +665,20 @@ class ScreenImpl {
     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._lifecycleListeners.clear();
+    this._isConnected = false;
+    this._outboundBuffer = [];
     if (this.transport instanceof PostMessageTransport.PostMessageTransport) {
       this.transport.destroy();
     }
@@ -593,8 +694,8 @@ class ScreenImpl {
   handleError(error) {
     this.logger.warn(`Error in handler: ${error.message}`);
     const smoreError = error.toSmoreError();
-    if (this.config.onError) {
-      this.config.onError(smoreError);
+    if (this._hasLifecycleListeners("$error")) {
+      this._emitLifecycle("$error", smoreError);
     } else {
       this.logger.error(error.message, error.details);
     }
@@ -610,17 +711,14 @@ class ScreenImpl {
     if (!this._isReady || !this.transport) {
       throw new errors.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);
 }
 
 exports.createScreen = createScreen;