@smoregg/sdk 2.0.0 → 2.2.0

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

@@ -5,6 +5,7 @@
 })(this, (function (exports) { 'use strict';
 
   const BRIDGE_MSG_PREFIX = "_bridge:";
+  const PROTOCOL_VERSION = 1;
   function isBridgeMessage(data) {
     return data !== null && typeof data === "object" && "type" in data && typeof data.type === "string" && data.type.startsWith(BRIDGE_MSG_PREFIX);
   }
@@ -29,6 +30,8 @@
   }
 
   class PostMessageTransport {
+    static ACK_TIMEOUT = 3e4;
+    // 30 seconds
     handlers = /* @__PURE__ */ new Map();
     ackCallbacks = /* @__PURE__ */ new Map();
     ackCounter = 0;
@@ -47,11 +50,21 @@
         const callback = args[0];
         ackId = `ack_${++this.ackCounter}`;
         this.ackCallbacks.set(ackId, callback);
+        setTimeout(() => {
+          if (this.ackCallbacks.has(ackId)) {
+            this.ackCallbacks.delete(ackId);
+          }
+        }, PostMessageTransport.ACK_TIMEOUT);
       } else if (args.length >= 2 && typeof args[args.length - 1] === "function") {
         data = args[0];
         const callback = args[args.length - 1];
         ackId = `ack_${++this.ackCounter}`;
         this.ackCallbacks.set(ackId, callback);
+        setTimeout(() => {
+          if (this.ackCallbacks.has(ackId)) {
+            this.ackCallbacks.delete(ackId);
+          }
+        }, PostMessageTransport.ACK_TIMEOUT);
       }
       window.parent.postMessage(
         { type: "_bridge:emit", payload: { event, data, ackId } },
@@ -115,6 +128,7 @@
       super(message, options?.cause ? { cause: options.cause } : void 0);
       this.name = "SmoreSDKError";
       this.code = code;
+      this.cause = options?.cause;
       this.details = options?.details;
       const ErrorWithCapture = Error;
       if (typeof ErrorWithCapture.captureStackTrace === "function") {
@@ -134,8 +148,6 @@
   const SMORE_EVENTS = {
     // Game lifecycle
     GAME_OVER: "smore:game-over",
-    RETURN_TO_LOBBY: "smore:return-to-lobby",
-    // Used internally by platform, not handled by SDK
     // Player management
     PLAYER_JOINED: "smore:player-joined",
     PLAYER_LEFT: "smore:player-left",
@@ -148,9 +160,17 @@
     // Game ready sync
     GAME_READY: "smore:game-ready",
     ALL_READY: "smore:all-ready",
+    // Connection status (self)
+    SELF_DISCONNECTED: "smore:self-disconnected",
+    SELF_RECONNECTED: "smore:self-reconnected",
     // Send to specific player (internal use)
-    SEND_TO_PLAYER: "smore:send-to-player"
+    SEND_TO_PLAYER: "smore:send-to-player",
     // Used internally by platform, not handled by SDK
+    // Custom state management
+    STATE_SET: "smore:set-custom-state",
+    STATE_CHANGED: "smore:custom-state-changed",
+    STATE_GET_ALL: "smore:get-custom-states",
+    STATE_ALL: "smore:custom-states"
   };
   new Set(
     Object.values(SMORE_EVENTS)
@@ -176,6 +196,21 @@
       );
     }
   }
+  const SCREEN_LIFECYCLE_EVENTS = /* @__PURE__ */ new Set([
+    "$all-ready",
+    "$controller-join",
+    "$controller-leave",
+    "$controller-disconnect",
+    "$controller-reconnect",
+    "$character-updated",
+    "$error",
+    "$connection-change"
+  ]);
+  const CONTROLLER_LIFECYCLE_EVENTS = /* @__PURE__ */ new Set([
+    ...SCREEN_LIFECYCLE_EVENTS,
+    "$game-over",
+    "$state-recovery"
+  ]);
 
   class DebugLogger {
     enabled;
@@ -248,12 +283,30 @@
     }
   }
 
-  let globalConfig = {};
-  function configure(config) {
-    globalConfig = { ...globalConfig, ...config };
+  const MAX_PAYLOAD_SIZE = 65536;
+  function mapPlayerDTO(raw, fallbackIndex) {
+    return {
+      playerIndex: raw.playerIndex ?? fallbackIndex,
+      nickname: raw.nickname || raw.name || `Player ${(raw.playerIndex ?? fallbackIndex) + 1}`,
+      connected: raw.connected !== false,
+      appearance: raw.appearance ?? raw.character
+    };
   }
-  function getGlobalConfig() {
-    return globalConfig;
+  function validatePayloadSize(data) {
+    if (data === void 0 || data === null) return;
+    try {
+      const serialized = JSON.stringify(data);
+      const byteLength = new TextEncoder().encode(serialized).byteLength;
+      if (byteLength > MAX_PAYLOAD_SIZE) {
+        throw new SmoreSDKError(
+          "PAYLOAD_TOO_LARGE",
+          `Event payload exceeds maximum size of ${MAX_PAYLOAD_SIZE} bytes (got ${byteLength} bytes). The server will silently drop this event.`,
+          { details: { size: byteLength, limit: MAX_PAYLOAD_SIZE } }
+        );
+      }
+    } catch (err) {
+      if (err instanceof SmoreSDKError) throw err;
+    }
   }
 
   const DEFAULT_TIMEOUT$1 = 1e4;
@@ -285,17 +338,19 @@
     handlerToTransport = /* @__PURE__ */ new Map();
     // 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();
+    // 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;
+    // Custom state management
+    _customStates = /* @__PURE__ */ new Map();
+    _stateChangeListeners = /* @__PURE__ */ new Set();
+    // Protocol versioning
+    _protocolVersion = PROTOCOL_VERSION;
     // Ready promise
     _readyResolve;
     _readyReject;
@@ -357,8 +412,17 @@
             this._readyReject(error);
             return;
           }
-          this.transport = new PostMessageTransport(parentOrigin);
+          this.transport = this.config.transport ?? new PostMessageTransport(parentOrigin);
           this._roomCode = initData.roomCode;
+          const serverProtocolVersion = initData.protocolVersion;
+          if (serverProtocolVersion !== void 0) {
+            this._protocolVersion = serverProtocolVersion;
+            if (serverProtocolVersion !== PROTOCOL_VERSION) {
+              this.logger.warn(
+                `Protocol version mismatch: SDK v${PROTOCOL_VERSION}, server v${serverProtocolVersion}. Some features may not work correctly.`
+              );
+            }
+          }
           this._controllers = this.mapControllersFromInit(initData.players);
           if (this._controllers.length === 0) {
             this.logger.warn("Screen initialized with zero controllers");
@@ -368,13 +432,28 @@
             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 SmoreSDKError ? err : new SmoreSDKError("UNKNOWN", "Failed to flush buffered message"));
+            }
+          }
+          this._outboundBuffer = [];
           this.logger.lifecycle("Screen ready", {
             roomCode: this._roomCode,
             controllers: this._controllers.length
           });
-          const autoReady = getGlobalConfig().autoReady ?? true;
-          if (autoReady) {
+          if (this.config.autoReady !== false) {
             this.logger.lifecycle("Auto-signaling ready (autoReady enabled)");
             this.signalReady();
           }
@@ -392,13 +471,13 @@
             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));
+                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._onControllerLeaveCallbacks.forEach((cb) => cb(oc.playerIndex));
+                this._emitLifecycle("$controller-leave", oc.playerIndex);
               }
             }
           }
@@ -408,18 +487,11 @@
         }
       };
       window.addEventListener("message", this.boundMessageHandler);
-      window.parent.postMessage({ type: "_bridge:ready" }, parentOrigin);
+      window.parent.postMessage({ type: "_bridge:ready", protocolVersion: 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) => mapPlayerDTO(p, index));
     }
     setupEventHandlers() {
       if (!this.transport) return;
@@ -427,16 +499,11 @@
         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 = 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._onControllerJoinCallbacks.forEach((cb) => cb(controllerInfo.playerIndex, controllerInfo));
+          this._emitLifecycle("$controller-join", controllerInfo.playerIndex, controllerInfo);
         }
       });
       this.registerTransportHandler(SMORE_EVENTS.PLAYER_LEFT, (data) => {
@@ -446,7 +513,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._onControllerLeaveCallbacks.forEach((cb) => cb(playerIndex));
+          this._emitLifecycle("$controller-leave", playerIndex);
         }
       });
       this.registerTransportHandler(SMORE_EVENTS.PLAYER_DISCONNECTED, (data) => {
@@ -457,24 +524,19 @@
             (c) => c.playerIndex === playerIndex ? { ...c, connected: false } : c
           );
           this.logger.lifecycle("Controller disconnected", { playerIndex });
-          this._onControllerDisconnectCallbacks.forEach((cb) => cb(playerIndex));
+          this._emitLifecycle("$controller-disconnect", playerIndex);
         }
       });
       this.registerTransportHandler(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 = 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._onControllerReconnectCallbacks.forEach((cb) => cb(controllerInfo.playerIndex, controllerInfo));
+          this._emitLifecycle("$controller-reconnect", controllerInfo.playerIndex, controllerInfo);
         }
       });
       this.registerTransportHandler(SMORE_EVENTS.PLAYER_CHARACTER_UPDATED, (data) => {
@@ -487,19 +549,69 @@
             (c) => c.playerIndex === pi ? { ...c, appearance } : c
           );
           this.logger.lifecycle("Player character updated", { playerIndex: pi });
-          this._onCharacterUpdatedCallbacks.forEach((cb) => cb(pi, appearance ?? null));
+          this._emitLifecycle("$character-updated", 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._onRateLimitedCallbacks.forEach((cb) => cb(event));
+        const eventName = payload?.event ?? "unknown";
+        this.handleError(
+          new SmoreSDKError("RATE_LIMITED", `Server rate-limited event: ${eventName}`, {
+            details: { event: eventName }
+          })
+        );
       });
       this.registerTransportHandler(SMORE_EVENTS.ALL_READY, () => {
         this.logger.lifecycle("All participants ready");
         this._allReadyFired = true;
-        this._onAllReadyCallbacks.forEach((cb) => cb());
+        this._emitLifecycle("$all-ready");
+      });
+      this.registerTransportHandler(SMORE_EVENTS.SELF_DISCONNECTED, () => {
+        this._isConnected = false;
+        this.logger.lifecycle("Connection lost");
+        this._emitLifecycle("$connection-change", false);
+      });
+      this.registerTransportHandler(SMORE_EVENTS.SELF_RECONNECTED, () => {
+        this._isConnected = true;
+        this.logger.lifecycle("Connection restored");
+        this._emitLifecycle("$connection-change", true);
+      });
+      this.registerTransportHandler(SMORE_EVENTS.STATE_CHANGED, (raw) => {
+        const data = raw;
+        if (typeof data?.playerIndex === "number" && data.state) {
+          this._customStates.set(data.playerIndex, data.state);
+          this._stateChangeListeners.forEach((cb) => {
+            try {
+              cb(data.playerIndex, data.state);
+            } catch (err) {
+              this.handleError(
+                new SmoreSDKError("UNKNOWN", "Error in custom state change listener", {
+                  cause: err instanceof Error ? err : void 0
+                })
+              );
+            }
+          });
+        }
+      });
+      this.registerTransportHandler(SMORE_EVENTS.STATE_ALL, (raw) => {
+        const data = raw;
+        if (data?.states) {
+          for (const [key, value] of Object.entries(data.states)) {
+            const pi = Number(key);
+            this._customStates.set(pi, value);
+            this._stateChangeListeners.forEach((cb) => {
+              try {
+                cb(pi, value);
+              } catch (err) {
+                this.handleError(
+                  new SmoreSDKError("UNKNOWN", "Error in custom state change listener", {
+                    cause: err instanceof Error ? err : void 0
+                  })
+                );
+              }
+            });
+          }
+        }
       });
     }
     /**
@@ -568,6 +680,45 @@
     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 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
     // ---------------------------------------------------------------------------
@@ -575,51 +726,46 @@
       if (this._allReadyFired) {
         callback();
       }
-      this._onAllReadyCallbacks.add(callback);
-      return () => {
-        this._onAllReadyCallbacks.delete(callback);
-      };
+      return this._addLifecycleListener("$all-ready", callback);
     }
     onControllerJoin(callback) {
-      this._onControllerJoinCallbacks.add(callback);
-      return () => {
-        this._onControllerJoinCallbacks.delete(callback);
-      };
+      return this._addLifecycleListener("$controller-join", callback);
     }
     onControllerLeave(callback) {
-      this._onControllerLeaveCallbacks.add(callback);
-      return () => {
-        this._onControllerLeaveCallbacks.delete(callback);
-      };
+      return this._addLifecycleListener("$controller-leave", callback);
     }
     onControllerDisconnect(callback) {
-      this._onControllerDisconnectCallbacks.add(callback);
-      return () => {
-        this._onControllerDisconnectCallbacks.delete(callback);
-      };
+      return this._addLifecycleListener("$controller-disconnect", callback);
     }
     onControllerReconnect(callback) {
-      this._onControllerReconnectCallbacks.add(callback);
-      return () => {
-        this._onControllerReconnectCallbacks.delete(callback);
-      };
+      return this._addLifecycleListener("$controller-reconnect", callback);
     }
     onCharacterUpdated(callback) {
-      this._onCharacterUpdatedCallbacks.add(callback);
-      return () => {
-        this._onCharacterUpdatedCallbacks.delete(callback);
-      };
-    }
-    onRateLimited(callback) {
-      this._onRateLimitedCallbacks.add(callback);
-      return () => {
-        this._onRateLimitedCallbacks.delete(callback);
-      };
+      return this._addLifecycleListener("$character-updated", callback);
     }
     onError(callback) {
-      this._onErrorCallbacks.add(callback);
+      return this._addLifecycleListener("$error", callback);
+    }
+    onConnectionChange(callback) {
+      return this._addLifecycleListener("$connection-change", callback);
+    }
+    // ---------------------------------------------------------------------------
+    // Custom State Methods
+    // ---------------------------------------------------------------------------
+    getControllerState(playerIndex) {
+      return this._customStates.get(playerIndex);
+    }
+    getAllControllerStates() {
+      const result = {};
+      for (const [key, value] of this._customStates) {
+        result[key] = value;
+      }
+      return result;
+    }
+    onCustomStateChange(listener) {
+      this._stateChangeListeners.add(listener);
       return () => {
-        this._onErrorCallbacks.delete(callback);
+        this._stateChangeListeners.delete(listener);
       };
     }
     // ---------------------------------------------------------------------------
@@ -629,7 +775,6 @@
      * 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.
@@ -638,31 +783,18 @@
      *
      * 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");
-      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 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;
+      }
       validateEventName(event);
+      validatePayloadSize(data);
       this.logger.send(event, data);
       this.transport.emit(event, data);
     }
@@ -681,24 +813,17 @@
      * @param data - Event data payload
      */
     sendToController(playerIndex, event, data) {
-      this.ensureReady("sendToController");
-      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 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");
       validateEventName(event);
       validatePlayerIndex(playerIndex, this._controllers);
+      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.`
@@ -733,6 +858,16 @@
      * are queued and activated when the transport becomes available.
      */
     on(event, handler) {
+      if (typeof event === "string" && event.startsWith("$")) {
+        const validEvents = SCREEN_LIFECYCLE_EVENTS;
+        if (!validEvents.has(event)) {
+          throw new 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);
+      }
       validateEventName(event);
       let handlers = this.eventHandlers.get(event);
       if (!handlers) {
@@ -795,6 +930,23 @@
      * @returns Unsubscribe function to remove the handler before it fires
      */
     once(event, handler) {
+      if (typeof event === "string" && event.startsWith("$")) {
+        const validEvents = SCREEN_LIFECYCLE_EVENTS;
+        if (!validEvents.has(event)) {
+          throw new 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);
@@ -803,6 +955,14 @@
       return unsubscribe;
     }
     off(event, handler) {
+      if (typeof event === "string" && event.startsWith("$")) {
+        if (!handler) {
+          this._lifecycleListeners.delete(event);
+        } else {
+          this._lifecycleListeners.get(event)?.delete(handler);
+        }
+        return;
+      }
       if (!handler) {
         this.eventHandlers.delete(event);
         this.transport?.off(event);
@@ -830,6 +990,21 @@
         );
       }
     }
+    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);
+        }
+      }
+    }
     // ---------------------------------------------------------------------------
     // Utilities
     // ---------------------------------------------------------------------------
@@ -839,9 +1014,6 @@
     getControllerCount() {
       return this._controllers.filter((c) => c.connected).length;
     }
-    hasAnyConnectedControllers() {
-      return this._controllers.some((c) => c.connected);
-    }
     // ---------------------------------------------------------------------------
     // Cleanup
     // ---------------------------------------------------------------------------
@@ -865,14 +1037,11 @@
       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();
+      this._lifecycleListeners.clear();
+      this._customStates.clear();
+      this._stateChangeListeners.clear();
+      this._isConnected = false;
+      this._outboundBuffer = [];
       if (this.transport instanceof PostMessageTransport) {
         this.transport.destroy();
       }
@@ -888,8 +1057,8 @@
     handleError(error) {
       this.logger.warn(`Error in handler: ${error.message}`);
       const smoreError = error.toSmoreError();
-      if (this._onErrorCallbacks.size > 0) {
-        this._onErrorCallbacks.forEach((cb) => cb(smoreError));
+      if (this._hasLifecycleListeners("$error")) {
+        this._emitLifecycle("$error", smoreError);
       } else {
         this.logger.error(error.message, error.details);
       }
@@ -921,7 +1090,7 @@
     config;
     logger;
     _roomCode = "";
-    _myIndex = -1;
+    _myPlayerIndex = -1;
     _isReady = false;
     _isDestroyed = false;
     _initTimeoutId = null;
@@ -931,19 +1100,20 @@
     // Maps user-facing handler -> transport wrappedHandler for proper cleanup in on()/off()
     handlerToTransport = /* @__PURE__ */ new Map();
     _controllers = [];
+    _customStates = /* @__PURE__ */ new Map();
+    _stateChangeListeners = /* @__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();
+    // 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_VERSION;
     // Ready promise
     _readyResolve;
     _readyReject;
@@ -960,8 +1130,8 @@
     // ---------------------------------------------------------------------------
     // Properties (readonly)
     // ---------------------------------------------------------------------------
-    get myIndex() {
-      return this._myIndex;
+    get myPlayerIndex() {
+      return this._myPlayerIndex;
     }
     get roomCode() {
       return this._roomCode;
@@ -972,6 +1142,12 @@
     get isDestroyed() {
       return this._isDestroyed;
     }
+    get isConnected() {
+      return this._isConnected;
+    }
+    get protocolVersion() {
+      return this._protocolVersion;
+    }
     /**
      * Read-only list of all known controllers (players) in the room.
      * Returns full ControllerInfo including playerIndex, nickname, connected status, and appearance.
@@ -982,12 +1158,18 @@
     get controllers() {
       return [...this._controllers];
     }
+    get me() {
+      return this._controllers.find((c) => c.playerIndex === this._myPlayerIndex);
+    }
     /**
      * Returns the number of currently connected players.
      */
     getControllerCount() {
       return this._controllers.filter((c) => c.connected).length;
     }
+    getController(playerIndex) {
+      return this._controllers.find((c) => c.playerIndex === playerIndex);
+    }
     // ---------------------------------------------------------------------------
     // Initialization
     // ---------------------------------------------------------------------------
@@ -1018,7 +1200,7 @@
       };
       window.addEventListener("message", this.boundMessageHandler);
       this.logger.lifecycle("Sending _bridge:ready to parent");
-      window.parent.postMessage({ type: "_bridge:ready" }, parentOrigin);
+      window.parent.postMessage({ type: "_bridge:ready", protocolVersion: PROTOCOL_VERSION }, parentOrigin);
     }
     handleInit(msg, parentOrigin) {
       const initPayload = msg.payload;
@@ -1057,28 +1239,48 @@
         this._readyReject(error);
         return;
       }
-      this.transport = new PostMessageTransport(parentOrigin);
+      this.transport = this.config.transport ?? new PostMessageTransport(parentOrigin);
       this._roomCode = initData.roomCode;
-      this._myIndex = initData.myIndex;
+      const serverProtocolVersion = initData.protocolVersion;
+      if (serverProtocolVersion !== void 0) {
+        this._protocolVersion = serverProtocolVersion;
+        if (serverProtocolVersion !== PROTOCOL_VERSION) {
+          this.logger.warn(
+            `Protocol version mismatch: SDK v${PROTOCOL_VERSION}, server v${serverProtocolVersion}. Some features may not work correctly.`
+          );
+        }
+      }
+      this._myPlayerIndex = initData.myIndex;
       const initPlayers = initData.players;
-      this._controllers = initPlayers.filter((p) => typeof p.playerIndex === "number").map((p) => ({
-        playerIndex: p.playerIndex,
-        nickname: p.nickname || p.name || `Player ${p.playerIndex + 1}`,
-        connected: p.connected !== false,
-        appearance: p.appearance ?? p.character
-      }));
+      this._controllers = initPlayers.filter((p) => typeof p.playerIndex === "number").map((p, index) => mapPlayerDTO(p, index));
       this.setupEventHandlers();
       for (const { event, handler } of this._pendingHandlers) {
         this.setupUserEventHandler(event, handler);
       }
       this._pendingHandlers = [];
+      this._isConnected = true;
       this._isReady = true;
+      if (initData.gameInProgress && this.transport) {
+        this.logger.lifecycle("Game in progress detected, requesting state recovery");
+        this.transport.emit(SMORE_EVENTS.STATE_GET_ALL, {});
+      }
+      for (const buffered of this._outboundBuffer) {
+        try {
+          switch (buffered.method) {
+            case "send":
+              this.send(buffered.args[0], buffered.args[1]);
+              break;
+          }
+        } catch (err) {
+          this.handleError(err instanceof SmoreSDKError ? err : new SmoreSDKError("UNKNOWN", "Failed to flush buffered message"));
+        }
+      }
+      this._outboundBuffer = [];
       this.logger.lifecycle("Controller ready", {
         roomCode: this._roomCode,
-        myIndex: this._myIndex
+        myIndex: this._myPlayerIndex
       });
-      const autoReady = getGlobalConfig().autoReady ?? true;
-      if (autoReady) {
+      if (this.config.autoReady !== false) {
         this.logger.lifecycle("Auto-signaling ready (autoReady enabled)");
         this.signalReady();
       }
@@ -1093,21 +1295,16 @@
       this.logger.debug("Received _bridge:update", updateData);
       if (updateData.players && Array.isArray(updateData.players)) {
         const players = updateData.players;
-        const newControllers = players.filter((p) => typeof p.playerIndex === "number").map((p) => ({
-          playerIndex: p.playerIndex,
-          nickname: p.nickname || p.name || `Player ${p.playerIndex + 1}`,
-          connected: p.connected !== false,
-          appearance: p.appearance ?? p.character
-        }));
+        const newControllers = players.filter((p) => typeof p.playerIndex === "number").map((p, index) => mapPlayerDTO(p, index));
         const oldControllers = this._controllers;
         for (const nc of newControllers) {
           if (!oldControllers.some((oc) => oc.playerIndex === nc.playerIndex)) {
-            this._onControllerJoinCallbacks.forEach((cb) => cb(nc.playerIndex, nc));
+            this._emitLifecycle("$controller-join", nc.playerIndex, nc);
           }
         }
         for (const oc of oldControllers) {
           if (!newControllers.some((nc) => nc.playerIndex === oc.playerIndex)) {
-            this._onControllerLeaveCallbacks.forEach((cb) => cb(oc.playerIndex));
+            this._emitLifecycle("$controller-leave", oc.playerIndex);
           }
         }
         for (const nc of newControllers) {
@@ -1115,11 +1312,11 @@
           if (oc) {
             if (oc.connected && !nc.connected) {
               this.logger.debug("Player disconnected (via update)", { playerIndex: nc.playerIndex });
-              this._onControllerDisconnectCallbacks.forEach((cb) => cb(nc.playerIndex));
+              this._emitLifecycle("$controller-disconnect", nc.playerIndex);
             }
             if (!oc.connected && nc.connected) {
               this.logger.debug("Player reconnected (via update)", { playerIndex: nc.playerIndex });
-              this._onControllerReconnectCallbacks.forEach((cb) => cb(nc.playerIndex, nc));
+              this._emitLifecycle("$controller-reconnect", nc.playerIndex, nc);
             }
           }
         }
@@ -1134,19 +1331,10 @@
         const playerIndex = playerInfo?.playerIndex ?? data.playerIndex;
         if (playerIndex !== void 0) {
           if (this._controllers.some((c) => c.playerIndex === playerIndex)) return;
-          const controllerInfo = playerInfo ? {
-            playerIndex,
-            nickname: playerInfo.nickname || playerInfo.name || `Player ${playerIndex + 1}`,
-            connected: playerInfo.connected !== false,
-            appearance: playerInfo.appearance ?? playerInfo.character
-          } : {
-            playerIndex,
-            nickname: `Player ${playerIndex + 1}`,
-            connected: true
-          };
+          const controllerInfo = playerInfo ? mapPlayerDTO(playerInfo, playerIndex) : mapPlayerDTO({ playerIndex, connected: true }, playerIndex);
           this._controllers = [...this._controllers, controllerInfo];
           this.logger.debug("Player joined", { playerIndex });
-          this._onControllerJoinCallbacks.forEach((cb) => cb(playerIndex, controllerInfo));
+          this._emitLifecycle("$controller-join", playerIndex, controllerInfo);
         }
       });
       this.registerHandler(SMORE_EVENTS.PLAYER_LEFT, (raw) => {
@@ -1156,7 +1344,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._onControllerLeaveCallbacks.forEach((cb) => cb(playerIndex));
+          this._emitLifecycle("$controller-leave", playerIndex);
         }
       });
       this.registerHandler(SMORE_EVENTS.PLAYER_DISCONNECTED, (raw) => {
@@ -1168,7 +1356,7 @@
             (c) => c.playerIndex === playerIndex ? { ...c, connected: false } : c
           );
           this.logger.debug("Player disconnected", { playerIndex });
-          this._onControllerDisconnectCallbacks.forEach((cb) => cb(playerIndex));
+          this._emitLifecycle("$controller-disconnect", playerIndex);
         }
       });
       this.registerHandler(SMORE_EVENTS.PLAYER_RECONNECTED, (raw) => {
@@ -1176,21 +1364,12 @@
         const playerData = data.player;
         const playerIndex = playerData?.playerIndex ?? data.playerIndex;
         if (playerIndex !== void 0) {
-          const controllerInfo = playerData ? {
-            playerIndex,
-            nickname: playerData.nickname || playerData.name || `Player ${playerIndex + 1}`,
-            connected: true,
-            appearance: playerData.appearance ?? playerData.character
-          } : {
-            playerIndex,
-            nickname: `Player ${playerIndex + 1}`,
-            connected: true
-          };
+          const controllerInfo = playerData ? mapPlayerDTO(playerData, playerIndex) : mapPlayerDTO({ playerIndex, connected: true }, playerIndex);
           this._controllers = this._controllers.map(
             (c) => c.playerIndex === playerIndex ? controllerInfo : c
           );
           this.logger.debug("Player reconnected", { playerIndex });
-          this._onControllerReconnectCallbacks.forEach((cb) => cb(playerIndex, controllerInfo));
+          this._emitLifecycle("$controller-reconnect", playerIndex, controllerInfo);
         }
       });
       this.registerHandler(SMORE_EVENTS.PLAYER_CHARACTER_UPDATED, (raw) => {
@@ -1203,19 +1382,75 @@
             (c) => c.playerIndex === pi ? { ...c, appearance } : c
           );
           this.logger.debug("Player character updated", { playerIndex: pi });
-          this._onCharacterUpdatedCallbacks.forEach((cb) => cb(pi, appearance ?? null));
+          this._emitLifecycle("$character-updated", 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._onRateLimitedCallbacks.forEach((cb) => cb(event));
+        const eventName = data?.event ?? "unknown";
+        this.handleError(
+          new SmoreSDKError("RATE_LIMITED", `Server rate-limited event: ${eventName}`, {
+            details: { event: eventName }
+          })
+        );
+      });
+      this.registerHandler(SMORE_EVENTS.GAME_OVER, (raw) => {
+        const data = raw;
+        this.logger.lifecycle("Game over", data?.results);
+        this._emitLifecycle("$game-over", data?.results);
       });
       this.registerHandler(SMORE_EVENTS.ALL_READY, () => {
         this.logger.lifecycle("All participants ready");
         this._allReadyFired = true;
-        this._onAllReadyCallbacks.forEach((cb) => cb());
+        this._emitLifecycle("$all-ready");
+      });
+      this.registerHandler(SMORE_EVENTS.SELF_DISCONNECTED, () => {
+        this._isConnected = false;
+        this.logger.lifecycle("Connection lost");
+        this._emitLifecycle("$connection-change", false);
+      });
+      this.registerHandler(SMORE_EVENTS.SELF_RECONNECTED, () => {
+        this._isConnected = true;
+        this.logger.lifecycle("Connection restored");
+        this._emitLifecycle("$connection-change", true);
+      });
+      this.registerHandler(SMORE_EVENTS.STATE_CHANGED, (raw) => {
+        const data = raw;
+        if (typeof data?.playerIndex === "number" && data.state) {
+          this._customStates.set(data.playerIndex, data.state);
+          this._stateChangeListeners.forEach((cb) => {
+            try {
+              cb(data.playerIndex, data.state);
+            } catch (err) {
+              this.handleError(
+                new SmoreSDKError("UNKNOWN", "Error in custom state change listener", {
+                  cause: err instanceof Error ? err : void 0
+                })
+              );
+            }
+          });
+        }
+      });
+      this.registerHandler(SMORE_EVENTS.STATE_ALL, (raw) => {
+        const data = raw;
+        if (data?.states) {
+          for (const [key, value] of Object.entries(data.states)) {
+            const pi = Number(key);
+            this._customStates.set(pi, value);
+            this._stateChangeListeners.forEach((cb) => {
+              try {
+                cb(pi, value);
+              } catch (err) {
+                this.handleError(
+                  new SmoreSDKError("UNKNOWN", "Error in custom state change listener", {
+                    cause: err instanceof Error ? err : void 0
+                  })
+                );
+              }
+            });
+          }
+          this._emitLifecycle("$state-recovery", data.states);
+        }
       });
     }
     /**
@@ -1254,57 +1489,89 @@
       this.registeredHandlers.push({ event, handler });
     }
     // ---------------------------------------------------------------------------
+    // 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 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();
       }
-      this._onAllReadyCallbacks.add(callback);
-      return () => {
-        this._onAllReadyCallbacks.delete(callback);
-      };
+      return this._addLifecycleListener("$all-ready", callback);
     }
     onControllerJoin(callback) {
-      this._onControllerJoinCallbacks.add(callback);
-      return () => {
-        this._onControllerJoinCallbacks.delete(callback);
-      };
+      return this._addLifecycleListener("$controller-join", callback);
     }
     onControllerLeave(callback) {
-      this._onControllerLeaveCallbacks.add(callback);
-      return () => {
-        this._onControllerLeaveCallbacks.delete(callback);
-      };
+      return this._addLifecycleListener("$controller-leave", callback);
     }
     onControllerDisconnect(callback) {
-      this._onControllerDisconnectCallbacks.add(callback);
-      return () => {
-        this._onControllerDisconnectCallbacks.delete(callback);
-      };
+      return this._addLifecycleListener("$controller-disconnect", callback);
     }
     onControllerReconnect(callback) {
-      this._onControllerReconnectCallbacks.add(callback);
-      return () => {
-        this._onControllerReconnectCallbacks.delete(callback);
-      };
+      return this._addLifecycleListener("$controller-reconnect", callback);
     }
     onCharacterUpdated(callback) {
-      this._onCharacterUpdatedCallbacks.add(callback);
-      return () => {
-        this._onCharacterUpdatedCallbacks.delete(callback);
-      };
-    }
-    onRateLimited(callback) {
-      this._onRateLimitedCallbacks.add(callback);
-      return () => {
-        this._onRateLimitedCallbacks.delete(callback);
-      };
+      return this._addLifecycleListener("$character-updated", callback);
     }
     onError(callback) {
-      this._onErrorCallbacks.add(callback);
+      return this._addLifecycleListener("$error", callback);
+    }
+    onConnectionChange(callback) {
+      return this._addLifecycleListener("$connection-change", callback);
+    }
+    onGameOver(callback) {
+      return this._addLifecycleListener("$game-over", callback);
+    }
+    // ---------------------------------------------------------------------------
+    // Custom State Methods
+    // ---------------------------------------------------------------------------
+    setState(state) {
+      const current = this._customStates.get(this._myPlayerIndex) ?? {};
+      const merged = { ...current, ...state };
+      this._customStates.set(this._myPlayerIndex, merged);
+      if (this.transport) {
+        this.transport.emit(SMORE_EVENTS.STATE_SET, { state });
+      }
+    }
+    getMyState() {
+      return this._customStates.get(this._myPlayerIndex);
+    }
+    onCustomStateChange(listener) {
+      this._stateChangeListeners.add(listener);
       return () => {
-        this._onErrorCallbacks.delete(callback);
+        this._stateChangeListeners.delete(listener);
       };
     }
     // ---------------------------------------------------------------------------
@@ -1321,8 +1588,16 @@
      * Use the onError callback or smore:rate-limited event to detect rate limiting.
      */
     send(event, data) {
-      this.ensureReady("send");
+      if (this._isDestroyed) {
+        throw new SmoreSDKError("DESTROYED", "Cannot call send() after destroy()");
+      }
+      if (!this._isReady || !this.transport) {
+        this._outboundBuffer.push({ method: "send", args: [event, data] });
+        this.logger.debug(`Buffered send "${event}" (controller not ready yet)`);
+        return;
+      }
       validateEventName(event);
+      validatePayloadSize(data);
       if (typeof data !== "object" || data === null) {
         this.logger.warn(
           'Event data should be an object. Primitive values will be wrapped as { data: value } by the relay server. To avoid confusion, wrap explicitly: send("event", { value: 42 }) instead of send("event", 42).'
@@ -1331,12 +1606,6 @@
       this.logSend(event, data);
       this.transport.emit(event, data);
     }
-    sendRaw(event, data) {
-      this.ensureReady("sendRaw");
-      validateEventName(event);
-      this.logSend(event, data);
-      this.transport.emit(event, data);
-    }
     signalReady() {
       this.ensureReady("signalReady");
       this.logSend(SMORE_EVENTS.GAME_READY, {});
@@ -1358,6 +1627,16 @@
      *   handler receives `(data)` -- targeted to this specific controller.
      */
     on(event, handler) {
+      if (typeof event === "string" && event.startsWith("$")) {
+        const validEvents = CONTROLLER_LIFECYCLE_EVENTS;
+        if (!validEvents.has(event)) {
+          throw new 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);
+      }
       validateEventName(event);
       let listeners = this.eventListeners.get(event);
       if (!listeners) {
@@ -1410,6 +1689,23 @@
      * `off(event, originalHandler)`. Use the returned unsubscribe function instead.
      */
     once(event, handler) {
+      if (typeof event === "string" && event.startsWith("$")) {
+        const validEvents = CONTROLLER_LIFECYCLE_EVENTS;
+        if (!validEvents.has(event)) {
+          throw new 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 unsubscribe = this.on(event, ((data) => {
         unsubscribe();
         handler(data);
@@ -1417,6 +1713,14 @@
       return unsubscribe;
     }
     off(event, handler) {
+      if (typeof event === "string" && event.startsWith("$")) {
+        if (!handler) {
+          this._lifecycleListeners.delete(event);
+        } else {
+          this._lifecycleListeners.get(event)?.delete(handler);
+        }
+        return;
+      }
       if (!handler) {
         this.eventListeners.delete(event);
         this.transport?.off(event);
@@ -1444,6 +1748,21 @@
         );
       }
     }
+    removeAllListeners(event) {
+      if (event) {
+        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 {
+        for (const evt of [...this.eventListeners.keys()]) {
+          this.removeAllListeners(evt);
+        }
+      }
+    }
     // ---------------------------------------------------------------------------
     // Cleanup
     // ---------------------------------------------------------------------------
@@ -1467,14 +1786,11 @@
       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();
+      this._lifecycleListeners.clear();
+      this._customStates.clear();
+      this._stateChangeListeners.clear();
+      this._isConnected = false;
+      this._outboundBuffer = [];
       if (this.transport) {
         this.transport.destroy();
         this.transport = null;
@@ -1506,8 +1822,8 @@
     handleError(error) {
       this.logger.warn(`Error in handler: ${error.message}`);
       const smoreError = error.toSmoreError();
-      if (this._onErrorCallbacks.size > 0) {
-        this._onErrorCallbacks.forEach((cb) => cb(smoreError));
+      if (this._hasLifecycleListeners("$error")) {
+        this._emitLifecycle("$error", smoreError);
       } else {
         this.logger.error(error.message, error.details);
       }
@@ -1523,547 +1839,22 @@
     return new ControllerImpl(config ?? {});
   }
 
-  function createMockScreen(options = {}) {
-    const {
-      roomCode = "TEST",
-      controllers: initialControllers = [],
-      autoReady = true
-    } = options;
-    let _controllers = [...initialControllers];
-    let _isReady = false;
-    let _isDestroyed = false;
-    const listeners = /* @__PURE__ */ new Map();
-    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 = {
-      // === Properties ===
-      get controllers() {
-        return [..._controllers];
-      },
-      get roomCode() {
-        return roomCode;
-      },
-      get isReady() {
-        return _isReady;
-      },
-      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) {
-          throw new Error("Cannot broadcast: screen is destroyed");
-        }
-        if (!_isReady) {
-          throw new Error("Cannot broadcast: screen is not ready");
-        }
-        validateEventName(event);
-        broadcasts.push({ event, data });
-      },
-      broadcastRaw(event, data) {
-        if (_isDestroyed) {
-          throw new Error("Cannot broadcast: screen is destroyed");
-        }
-        if (!_isReady) {
-          throw new Error("Cannot broadcast: screen is not ready");
-        }
-        validateEventName(event);
-        broadcasts.push({ event, data });
-      },
-      sendToController(playerIndex, event, data) {
-        if (_isDestroyed) {
-          throw new Error("Cannot send: screen is destroyed");
-        }
-        if (!_isReady) {
-          throw new Error("Cannot send: screen is not ready");
-        }
-        validateEventName(event);
-        if (!_controllers.some((c) => c.playerIndex === playerIndex)) {
-          throw new Error(`Invalid player index: ${playerIndex}`);
-        }
-        sends.push({ playerIndex, event, data });
-      },
-      sendToControllerRaw(playerIndex, event, data) {
-        if (_isDestroyed) {
-          throw new Error("Cannot send: screen is destroyed");
-        }
-        if (!_isReady) {
-          throw new Error("Cannot send: screen is not ready");
-        }
-        validateEventName(event);
-        if (!_controllers.some((c) => c.playerIndex === playerIndex)) {
-          throw new Error(`Invalid player index: ${playerIndex}`);
-        }
-        sends.push({ playerIndex, event, data });
-      },
-      // === Game Lifecycle ===
-      gameOver(results) {
-        if (_isDestroyed) {
-          throw new Error("Cannot call gameOver: screen is destroyed");
-        }
-        if (!_isReady) {
-          throw new Error("Cannot call gameOver: screen is not ready");
-        }
-        broadcasts.push({ event: "smore:game-over", data: { results } });
-      },
-      signalReady() {
-        if (_isDestroyed) {
-          throw new Error("Cannot call signalReady: screen is destroyed");
-        }
-        if (!_isReady) {
-          throw new Error("Cannot call signalReady: screen is not ready");
-        }
-      },
-      // === Event Subscription ===
-      on(event, handler) {
-        validateEventName(event);
-        const eventStr = event;
-        if (!listeners.has(eventStr)) {
-          listeners.set(eventStr, /* @__PURE__ */ new Set());
-        }
-        listeners.get(eventStr).add(handler);
-        return () => {
-          listeners.get(eventStr)?.delete(handler);
-        };
-      },
-      once(event, handler) {
-        validateEventName(event);
-        const wrapper = (playerIndex, data) => {
-          handler(playerIndex, data);
-          screen.off(event, wrapper);
-        };
-        return screen.on(event, wrapper);
-      },
-      off(event, handler) {
-        validateEventName(event);
-        const eventStr = event;
-        if (!handler) {
-          listeners.delete(eventStr);
-        } else {
-          listeners.get(eventStr)?.delete(handler);
-        }
-      },
-      // === Utilities ===
-      getController(playerIndex) {
-        return _controllers.find((c) => c.playerIndex === playerIndex);
-      },
-      getControllerCount() {
-        return _controllers.filter((c) => c.connected).length;
-      },
-      hasAnyConnectedControllers() {
-        return _controllers.some((c) => c.connected);
-      },
-      // === Cleanup ===
-      /**
-       * Note: destroy() clears recorded broadcast/event arrays. Call getBroadcasts() before destroy() if assertions are needed.
-       */
-      destroy() {
-        _isDestroyed = true;
-        listeners.clear();
-        broadcasts.length = 0;
-        sends.length = 0;
-      },
-      // === Mock-specific methods ===
-      simulateEvent(playerIndex, event, data) {
-        validateEventName(event);
-        const eventStr = event;
-        const handlers = listeners.get(eventStr);
-        if (handlers) {
-          handlers.forEach((handler) => {
-            handler(playerIndex, data);
-          });
-        }
-      },
-      simulateControllerJoin(info) {
-        _controllers.push(info);
-        _onControllerJoinCallbacks.forEach((cb) => cb(info.playerIndex, info));
-      },
-      simulateControllerLeave(playerIndex) {
-        _controllers = _controllers.filter((c) => c.playerIndex !== playerIndex);
-        _onControllerLeaveCallbacks.forEach((cb) => cb(playerIndex));
-      },
-      /**
-       * Simulate a controller network disconnect (player still in room but unreachable).
-       */
-      simulateControllerDisconnect(playerIndex) {
-        const controller = _controllers.find((c) => c.playerIndex === playerIndex);
-        if (!controller) {
-          throw new Error(`Controller ${playerIndex} not found`);
-        }
-        _controllers = _controllers.map(
-          (c) => c.playerIndex === playerIndex ? { ...c, connected: false } : c
-        );
-        _onControllerDisconnectCallbacks.forEach((cb) => cb(playerIndex));
-      },
-      /**
-       * Simulate a controller network reconnect after disconnect.
-       */
-      simulateControllerReconnect(playerIndex) {
-        const controller = _controllers.find((c) => c.playerIndex === playerIndex);
-        if (!controller) {
-          throw new Error(`Controller ${playerIndex} not found`);
-        }
-        const reconnectedController = { ...controller, connected: true };
-        _controllers = _controllers.map(
-          (c) => c.playerIndex === playerIndex ? reconnectedController : c
-        );
-        _onControllerReconnectCallbacks.forEach((cb) => cb(playerIndex, reconnectedController));
-      },
-      simulateCharacterUpdate(playerIndex, appearance) {
-        const controller = _controllers.find((c) => c.playerIndex === playerIndex);
-        if (!controller) {
-          throw new Error(`Controller ${playerIndex} not found`);
-        }
-        _controllers = _controllers.map(
-          (c) => c.playerIndex === playerIndex ? { ...c, appearance } : c
-        );
-        _onCharacterUpdatedCallbacks.forEach((cb) => cb(playerIndex, appearance));
-      },
-      simulateRateLimited(event) {
-        _onRateLimitedCallbacks.forEach((cb) => cb(event));
-      },
-      simulateAllReady() {
-        _allReadyFired = true;
-        _onAllReadyCallbacks.forEach((cb) => cb());
-      },
-      simulateError(error) {
-        _onErrorCallbacks.forEach((cb) => cb(error));
-      },
-      getBroadcasts() {
-        return [...broadcasts];
-      },
-      getSentToController(playerIndex) {
-        return sends.filter((s) => s.playerIndex === playerIndex).map((s) => ({ event: s.event, data: s.data }));
-      },
-      clearRecordedEvents() {
-        broadcasts.length = 0;
-        sends.length = 0;
-      },
-      triggerReady() {
-        _isReady = true;
-        _readyResolve();
-      }
-    };
-    if (autoReady) {
-      setTimeout(() => screen.triggerReady(), 0);
-    }
-    return screen;
-  }
-  function createMockController(options = {}) {
-    const {
-      roomCode = "TEST",
-      myIndex = 0,
-      autoReady = true
-    } = options;
-    let _isReady = false;
-    let _isDestroyed = false;
-    let _controllers = options.controllers ?? [];
-    const listeners = /* @__PURE__ */ new Map();
-    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 ===
-      get myIndex() {
-        return myIndex;
-      },
-      get roomCode() {
-        return roomCode;
-      },
-      get isReady() {
-        return _isReady;
-      },
-      get isDestroyed() {
-        return _isDestroyed;
-      },
-      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;
-      },
-      // === Communication Methods ===
-      send(event, data) {
-        if (_isDestroyed) {
-          throw new Error("Cannot send: controller is destroyed");
-        }
-        validateEventName(event);
-        sentEvents.push({ event, data });
-      },
-      sendRaw(event, data) {
-        if (_isDestroyed) {
-          throw new Error("Cannot send: controller is destroyed");
-        }
-        validateEventName(event);
-        sentEvents.push({ event, data });
-      },
-      signalReady() {
-        if (_isDestroyed) {
-          throw new Error("Cannot call signalReady: controller is destroyed");
-        }
-        if (!_isReady) {
-          throw new Error("Cannot call signalReady: controller is not ready");
-        }
-      },
-      // === Event Subscription ===
-      on(event, handler) {
-        validateEventName(event);
-        const eventStr = event;
-        if (!listeners.has(eventStr)) {
-          listeners.set(eventStr, /* @__PURE__ */ new Set());
-        }
-        listeners.get(eventStr).add(handler);
-        return () => {
-          listeners.get(eventStr)?.delete(handler);
-        };
-      },
-      once(event, handler) {
-        validateEventName(event);
-        const wrapper = (data) => {
-          handler(data);
-          controller.off(event, wrapper);
-        };
-        return controller.on(event, wrapper);
-      },
-      off(event, handler) {
-        validateEventName(event);
-        const eventStr = event;
-        if (!handler) {
-          listeners.delete(eventStr);
-        } else {
-          listeners.get(eventStr)?.delete(handler);
-        }
-      },
-      // === Cleanup ===
-      destroy() {
-        _isDestroyed = true;
-        listeners.clear();
-        sentEvents.length = 0;
-      },
-      // === Mock-specific methods ===
-      simulateEvent(event, data) {
-        validateEventName(event);
-        const eventStr = event;
-        const handlers = listeners.get(eventStr);
-        if (handlers) {
-          handlers.forEach((handler) => {
-            handler(data);
-          });
-        }
-      },
-      getSentEvents() {
-        return [...sentEvents];
-      },
-      clearRecordedEvents() {
-        sentEvents.length = 0;
-      },
-      triggerReady() {
-        _isReady = true;
-        _readyResolve();
-      },
-      /**
-       * Simulate a new player joining the room.
-       * Stores full ControllerInfo (nickname, appearance, etc.) for later retrieval.
-       */
-      simulatePlayerJoin(playerIndex, info) {
-        if (!_controllers.some((c) => c.playerIndex === playerIndex)) {
-          _controllers = [..._controllers, { ...info, connected: info.connected ?? true }];
-        }
-        _onControllerJoinCallbacks.forEach((cb) => cb(playerIndex, info));
-      },
-      /**
-       * Simulate a player leaving the room (fully removed).
-       */
-      simulatePlayerLeave(playerIndex) {
-        _controllers = _controllers.filter((c) => c.playerIndex !== playerIndex);
-        _onControllerLeaveCallbacks.forEach((cb) => cb(playerIndex));
-      },
-      /**
-       * Simulate a player network disconnect (player still in room but unreachable).
-       */
-      simulatePlayerDisconnect(playerIndex) {
-        _controllers = _controllers.map(
-          (c) => c.playerIndex === playerIndex ? { ...c, connected: false } : c
-        );
-        _onControllerDisconnectCallbacks.forEach((cb) => cb(playerIndex));
-      },
-      /**
-       * Simulate a player network reconnect after disconnect.
-       */
-      simulatePlayerReconnect(playerIndex, info) {
-        _controllers = _controllers.map(
-          (c) => c.playerIndex === playerIndex ? { ...info, connected: true } : c
-        );
-        _onControllerReconnectCallbacks.forEach((cb) => cb(playerIndex, info));
-      },
-      simulateCharacterUpdate(playerIndex, appearance) {
-        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
-        );
-        _onCharacterUpdatedCallbacks.forEach((cb) => cb(playerIndex, appearance));
-      },
-      simulateRateLimited(event) {
-        _onRateLimitedCallbacks.forEach((cb) => cb(event));
-      },
-      simulateAllReady() {
-        _allReadyFired = true;
-        _onAllReadyCallbacks.forEach((cb) => cb());
-      },
-      simulateError(error) {
-        _onErrorCallbacks.forEach((cb) => cb(error));
-      }
-    };
-    if (autoReady) {
-      setTimeout(() => controller.triggerReady(), 0);
-    }
-    return controller;
-  }
+  const LifecycleEvent = {
+    ALL_READY: "$all-ready",
+    CONTROLLER_JOIN: "$controller-join",
+    CONTROLLER_LEAVE: "$controller-leave",
+    CONTROLLER_DISCONNECT: "$controller-disconnect",
+    CONTROLLER_RECONNECT: "$controller-reconnect",
+    CHARACTER_UPDATED: "$character-updated",
+    ERROR: "$error",
+    GAME_OVER: "$game-over",
+    CONNECTION_CHANGE: "$connection-change"
+  };
 
+  exports.LifecycleEvent = LifecycleEvent;
   exports.SmoreSDKError = SmoreSDKError;
-  exports.configure = configure;
   exports.createController = createController;
-  exports.createMockController = createMockController;
-  exports.createMockScreen = createMockScreen;
   exports.createScreen = createScreen;
-  exports.validateEventName = validateEventName;
 
 }));
 //# sourceMappingURL=smore-sdk.umd.js.map