@smoregg/sdk 1.3.0 → 2.1.0

package/dist/esm/controller.js

@@ -1,9 +1,9 @@
 import { PostMessageTransport } from './transport/PostMessageTransport.js';
-import { isBridgeMessage, validateInitPayload } from './transport/protocol.js';
+import { PROTOCOL_VERSION, isBridgeMessage, validateInitPayload } from './transport/protocol.js';
 import { SmoreSDKError } from './errors.js';
-import { validateEventName, SMORE_EVENTS } from './events.js';
+import { SMORE_EVENTS, validateEventName, CONTROLLER_LIFECYCLE_EVENTS } from './events.js';
 import { DebugLogger } from './logger.js';
-import { getGlobalConfig } from './config.js';
+import { mapPlayerDTO, validatePayloadSize } from './shared.js';
 
 const DEFAULT_TIMEOUT = 1e4;
 class ControllerImpl {
@@ -11,31 +11,46 @@ class ControllerImpl {
   config;
   logger;
   _roomCode = "";
-  _myIndex = -1;
+  _myPlayerIndex = -1;
   _isReady = false;
   _isDestroyed = false;
+  _initTimeoutId = null;
   boundMessageHandler = null;
   registeredHandlers = [];
   eventListeners = /* @__PURE__ */ new Map();
   // Maps user-facing handler -> transport wrappedHandler for proper cleanup in on()/off()
   handlerToTransport = /* @__PURE__ */ new Map();
   _controllers = [];
-  // Tracks event names registered via config.listeners so off(event) without handler won't remove them
-  _configListenerEvents = /* @__PURE__ */ new Set();
+  // Pending handlers registered via on() before transport is ready
+  _pendingHandlers = [];
+  // 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;
+  ready;
   constructor(config = {}) {
     this.config = config;
     this.logger = new DebugLogger(config.debug, "[SmoreController]");
-    if (config.listeners) {
-      for (const event of Object.keys(config.listeners)) {
-        validateEventName(event);
-      }
-    }
+    this.ready = new Promise((resolve, reject) => {
+      this._readyResolve = resolve;
+      this._readyReject = reject;
+    });
+    this.startInitialization();
   }
   // ---------------------------------------------------------------------------
   // Properties (readonly)
   // ---------------------------------------------------------------------------
-  get myIndex() {
-    return this._myIndex;
+  get myPlayerIndex() {
+    return this._myPlayerIndex;
   }
   get roomCode() {
     return this._roomCode;
@@ -46,6 +61,12 @@ class ControllerImpl {
   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.
@@ -62,41 +83,42 @@ class ControllerImpl {
   getControllerCount() {
     return this._controllers.filter((c) => c.connected).length;
   }
+  getController(playerIndex) {
+    return this._controllers.find((c) => c.playerIndex === playerIndex);
+  }
   // ---------------------------------------------------------------------------
   // Initialization
   // ---------------------------------------------------------------------------
-  async initialize() {
+  startInitialization() {
     const parentOrigin = this.config.parentOrigin ?? "*";
     const timeout = this.config.timeout ?? DEFAULT_TIMEOUT;
     this.logger.lifecycle("Initializing controller...", { parentOrigin, timeout });
-    return new Promise((resolve, reject) => {
-      const timeoutId = setTimeout(() => {
-        this.cleanup();
-        const error = new SmoreSDKError(
-          "TIMEOUT",
-          `Controller initialization timed out after ${timeout}ms. Make sure the parent window sends _bridge:init message. Check that the iframe has correct sandbox attributes (allow-scripts required) and same-origin/cross-origin settings. Create a new Controller instance to retry (this instance has been cleaned up).`,
-          { details: { timeout } }
-        );
-        this.handleError(error);
-        reject(error);
-      }, timeout);
-      this.boundMessageHandler = (e) => {
-        if (parentOrigin !== "*" && e.origin !== parentOrigin) return;
-        const msg = e.data;
-        if (!isBridgeMessage(msg)) return;
-        if (msg.type === "_bridge:init") {
-          clearTimeout(timeoutId);
-          this.handleInit(msg, parentOrigin, resolve, reject);
-        } else if (msg.type === "_bridge:update") {
-          this.handleUpdate(msg);
-        }
-      };
-      window.addEventListener("message", this.boundMessageHandler);
-      this.logger.lifecycle("Sending _bridge:ready to parent");
-      window.parent.postMessage({ type: "_bridge:ready" }, parentOrigin);
-    });
+    this._initTimeoutId = setTimeout(() => {
+      this.cleanup();
+      const error = new SmoreSDKError(
+        "TIMEOUT",
+        `Controller initialization timed out after ${timeout}ms. Make sure the parent window sends _bridge:init message. Check that the iframe has correct sandbox attributes (allow-scripts required) and same-origin/cross-origin settings. Create a new Controller instance to retry (this instance has been cleaned up).`,
+        { details: { timeout } }
+      );
+      this.handleError(error);
+      this._readyReject(error);
+    }, timeout);
+    this.boundMessageHandler = (e) => {
+      if (parentOrigin !== "*" && e.origin !== parentOrigin) return;
+      const msg = e.data;
+      if (!isBridgeMessage(msg)) return;
+      if (msg.type === "_bridge:init") {
+        clearTimeout(this._initTimeoutId);
+        this.handleInit(msg, parentOrigin);
+      } else if (msg.type === "_bridge:update") {
+        this.handleUpdate(msg);
+      }
+    };
+    window.addEventListener("message", this.boundMessageHandler);
+    this.logger.lifecycle("Sending _bridge:ready to parent");
+    window.parent.postMessage({ type: "_bridge:ready", protocolVersion: PROTOCOL_VERSION }, parentOrigin);
   }
-  handleInit(msg, parentOrigin, resolve, reject) {
+  handleInit(msg, parentOrigin) {
     const initPayload = msg.payload;
     this.logger.debug("Received _bridge:init", initPayload);
     try {
@@ -109,7 +131,7 @@ class ControllerImpl {
       );
       this.logger.warn("_bridge:init validation failed", error);
       this.handleError(error);
-      reject(error);
+      this._readyReject(error);
       return;
     }
     const initData = initPayload;
@@ -120,7 +142,7 @@ class ControllerImpl {
         { details: { side: initData.side } }
       );
       this.handleError(error);
-      reject(error);
+      this._readyReject(error);
       return;
     }
     if (initData.myIndex === void 0) {
@@ -130,31 +152,51 @@ class ControllerImpl {
         { details: initData }
       );
       this.handleError(error);
-      reject(error);
+      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;
+    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();
     }
-    resolve();
+    this._readyResolve();
   }
   handleUpdate(msg) {
     if (!this._isReady) {
@@ -165,21 +207,16 @@ class ControllerImpl {
     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.config.onControllerJoin?.(nc.playerIndex, nc);
+          this._emitLifecycle("$controller-join", nc.playerIndex, nc);
         }
       }
       for (const oc of oldControllers) {
         if (!newControllers.some((nc) => nc.playerIndex === oc.playerIndex)) {
-          this.config.onControllerLeave?.(oc.playerIndex);
+          this._emitLifecycle("$controller-leave", oc.playerIndex);
         }
       }
       for (const nc of newControllers) {
@@ -187,11 +224,11 @@ class ControllerImpl {
         if (oc) {
           if (oc.connected && !nc.connected) {
             this.logger.debug("Player disconnected (via update)", { playerIndex: nc.playerIndex });
-            this.config.onControllerDisconnect?.(nc.playerIndex);
+            this._emitLifecycle("$controller-disconnect", nc.playerIndex);
           }
           if (!oc.connected && nc.connected) {
             this.logger.debug("Player reconnected (via update)", { playerIndex: nc.playerIndex });
-            this.config.onControllerReconnect?.(nc.playerIndex, nc);
+            this._emitLifecycle("$controller-reconnect", nc.playerIndex, nc);
           }
         }
       }
@@ -206,19 +243,10 @@ class ControllerImpl {
       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.config.onControllerJoin?.(playerIndex, controllerInfo);
+        this._emitLifecycle("$controller-join", playerIndex, controllerInfo);
       }
     });
     this.registerHandler(SMORE_EVENTS.PLAYER_LEFT, (raw) => {
@@ -228,7 +256,7 @@ class ControllerImpl {
         if (!this._controllers.some((c) => c.playerIndex === playerIndex)) return;
         this._controllers = this._controllers.filter((c) => c.playerIndex !== playerIndex);
         this.logger.debug("Player left", { playerIndex });
-        this.config.onControllerLeave?.(playerIndex);
+        this._emitLifecycle("$controller-leave", playerIndex);
       }
     });
     this.registerHandler(SMORE_EVENTS.PLAYER_DISCONNECTED, (raw) => {
@@ -240,7 +268,7 @@ class ControllerImpl {
           (c) => c.playerIndex === playerIndex ? { ...c, connected: false } : c
         );
         this.logger.debug("Player disconnected", { playerIndex });
-        this.config.onControllerDisconnect?.(playerIndex);
+        this._emitLifecycle("$controller-disconnect", playerIndex);
       }
     });
     this.registerHandler(SMORE_EVENTS.PLAYER_RECONNECTED, (raw) => {
@@ -248,70 +276,86 @@ class ControllerImpl {
       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.config.onControllerReconnect?.(playerIndex, controllerInfo);
+        this._emitLifecycle("$controller-reconnect", playerIndex, controllerInfo);
       }
     });
     this.registerHandler(SMORE_EVENTS.PLAYER_CHARACTER_UPDATED, (raw) => {
       const payload = raw;
       const playerData = payload?.player;
       if (playerData && typeof playerData.playerIndex === "number") {
+        const pi = playerData.playerIndex;
         const appearance = playerData.character ?? null;
         this._controllers = this._controllers.map(
-          (c) => c.playerIndex === playerData.playerIndex ? { ...c, appearance } : c
+          (c) => c.playerIndex === pi ? { ...c, appearance } : c
         );
-        this.logger.debug("Player character updated", { playerIndex: playerData.playerIndex });
-        this.config.onCharacterUpdated?.(playerData.playerIndex, appearance ?? null);
+        this.logger.debug("Player character updated", { playerIndex: pi });
+        this._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.config.onRateLimited?.(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.config.onReady?.();
+      this._allReadyFired = true;
+      this._emitLifecycle("$all-ready");
     });
-    if (this.config.onHostDisconnect) {
-      this.logger.warn("onHostDisconnect is reserved for future use and currently non-functional");
-    }
-    if (this.config.onHostReconnect) {
-      this.logger.warn("onHostReconnect is reserved for future use and currently non-functional");
-    }
-    if (this.config.listeners) {
-      for (const [event, handler] of Object.entries(this.config.listeners)) {
-        if (!handler) continue;
-        this._configListenerEvents.add(event);
-        this.registerHandler(event, (data) => {
-          this.logReceive(event, data);
-          try {
-            handler(data);
-          } catch (err) {
-            this.handleError(
-              new SmoreSDKError("UNKNOWN", `Error in handler for event "${event}"`, {
-                cause: err instanceof Error ? err : void 0,
-                details: { event }
-              })
-            );
-          }
-        });
+    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);
+    });
+  }
+  /**
+   * Sets up a user event handler for controller events.
+   * Used for registering pending handlers after transport becomes available.
+   */
+  setupUserEventHandler(event, handler) {
+    const transportHandler = (data) => {
+      this.logReceive(event, data);
+      try {
+        handler(data);
+      } catch (err) {
+        this.handleError(
+          new SmoreSDKError("UNKNOWN", `Error in handler for event "${event}"`, {
+            cause: err instanceof Error ? err : void 0,
+            details: { event }
+          })
+        );
       }
+    };
+    if (this.transport) {
+      this.transport.on(event, transportHandler);
+      this.registeredHandlers.push({ event, handler: transportHandler });
+      this.handlerToTransport.set(handler, { event, transportHandler });
+    }
+    let listeners = this.eventListeners.get(event);
+    if (!listeners) {
+      listeners = /* @__PURE__ */ new Set();
+      this.eventListeners.set(event, listeners);
     }
+    listeners.add(handler);
   }
   registerHandler(event, handler) {
     if (!this.transport) return;
@@ -319,21 +363,95 @@ class ControllerImpl {
     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();
+    }
+    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);
+  }
+  onGameOver(callback) {
+    return this._addLifecycleListener("$game-over", callback);
+  }
+  // ---------------------------------------------------------------------------
   // Communication Methods
   // ---------------------------------------------------------------------------
   /**
    * Send an event to the Screen. Controller-to-Controller direct communication
    * is not supported; all messages must go through the Screen.
    *
-   * Data is sent to the Screen only (not to other controllers). For Screen→Controller communication,
+   * Data is sent to the Screen only (not to other controllers). For Screen->Controller communication,
    * Screen uses broadcast() or sendToController().
    *
    * @note Fire-and-forget sends (no callback) will silently fail if rate-limited.
    * 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).'
@@ -342,12 +460,6 @@ class ControllerImpl {
     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, {});
@@ -359,26 +471,26 @@ class ControllerImpl {
   /**
    * Register a handler for custom events.
    *
+   * Can be called before the Controller is ready. Handlers registered before ready
+   * are queued and activated when the transport becomes available.
+   *
    * When receiving events from Screen's `broadcast()`:
-   *   handler receives `(data)` — no playerIndex included.
+   *   handler receives `(data)` -- no playerIndex included.
    *
    * When receiving events from Screen's `sendToController()`:
-   *   handler receives `(data)` — targeted to this specific controller.
-   *
-   * @note Unlike Screen's `on()` which receives `(playerIndex, data)`,
-   * Controller's `on()` receives only `(data)` since there's only one player per controller.
-   *
-   * Controller's on() handler signature: (data) => void
-   * Unlike Screen's (playerIndex, data) => void, Controller doesn't receive playerIndex
-   * because Controller only receives events from Screen, not from other controllers.
-   * The sender is always the Screen, so playerIndex is not applicable.
-   *
-   * **Important:** If called before the Controller is ready (i.e., before `await createController()`
-   * resolves or before the `onReady` callback fires), the handler is stored locally but
-   * will NOT receive events until the transport is initialized. Always call `on()` after
-   * initialization completes, or use `config.listeners` for handlers needed from the start.
+   *   handler receives `(data)` -- targeted to this specific controller.
    */
   on(event, handler) {
+    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) {
@@ -386,34 +498,42 @@ class ControllerImpl {
       this.eventListeners.set(event, listeners);
     }
     listeners.add(handler);
-    const transportHandler = (data) => {
-      this.logReceive(event, data);
-      try {
-        handler(data);
-      } catch (err) {
-        this.handleError(
-          new SmoreSDKError("UNKNOWN", `Error in handler for event "${event}"`, {
-            cause: err instanceof Error ? err : void 0,
-            details: { event }
-          })
-        );
-      }
-    };
     if (this.transport) {
+      const transportHandler = (data) => {
+        this.logReceive(event, data);
+        try {
+          handler(data);
+        } catch (err) {
+          this.handleError(
+            new SmoreSDKError("UNKNOWN", `Error in handler for event "${event}"`, {
+              cause: err instanceof Error ? err : void 0,
+              details: { event }
+            })
+          );
+        }
+      };
       this.transport.on(event, transportHandler);
       this.registeredHandlers.push({ event, handler: transportHandler });
       this.handlerToTransport.set(handler, { event, transportHandler });
+    } else {
+      this._pendingHandlers.push({ event, handler });
     }
     return () => {
       listeners?.delete(handler);
       if (listeners?.size === 0) {
         this.eventListeners.delete(event);
       }
-      this.transport?.off(event, transportHandler);
-      this.registeredHandlers = this.registeredHandlers.filter(
-        (h) => h.handler !== transportHandler
+      this._pendingHandlers = this._pendingHandlers.filter(
+        (p) => !(p.event === event && p.handler === handler)
       );
-      this.handlerToTransport.delete(handler);
+      const entry = this.handlerToTransport.get(handler);
+      if (entry) {
+        this.transport?.off(event, entry.transportHandler);
+        this.registeredHandlers = this.registeredHandlers.filter(
+          (h) => h.handler !== entry.transportHandler
+        );
+        this.handlerToTransport.delete(handler);
+      }
     };
   }
   /**
@@ -421,18 +541,25 @@ class ControllerImpl {
    *
    * @note The handler is internally wrapped, so it cannot be removed via
    * `off(event, originalHandler)`. Use the returned unsubscribe function instead.
-   *
-   * @example
-   * ```ts
-   * const unsubscribe = controller.once('game-start', (data) => {
-   *   console.log('Game started!', data);
-   * });
-   *
-   * // To cancel before it fires:
-   * unsubscribe();
-   * ```
    */
   once(event, handler) {
+    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);
@@ -440,25 +567,22 @@ class ControllerImpl {
     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.registeredHandlers = this.registeredHandlers.filter(
-              (h) => h.handler !== val.transportHandler
-            );
-            this.handlerToTransport.delete(key);
-          }
-        }
+    if (typeof event === "string" && event.startsWith("$")) {
+      if (!handler) {
+        this._lifecycleListeners.delete(event);
       } else {
-        this.eventListeners.delete(event);
-        this.transport?.off(event);
-        this.registeredHandlers = this.registeredHandlers.filter((h) => h.event !== event);
-        for (const [key, val] of this.handlerToTransport) {
-          if (val.event === event) this.handlerToTransport.delete(key);
-        }
+        this._lifecycleListeners.get(event)?.delete(handler);
       }
+      return;
+    }
+    if (!handler) {
+      this.eventListeners.delete(event);
+      this.transport?.off(event);
+      this.registeredHandlers = this.registeredHandlers.filter((h) => h.event !== event);
+      for (const [key, val] of this.handlerToTransport) {
+        if (val.event === event) this.handlerToTransport.delete(key);
+      }
+      this._pendingHandlers = this._pendingHandlers.filter((p) => p.event !== event);
     } else {
       const listeners = this.eventListeners.get(event);
       listeners?.delete(handler);
@@ -473,6 +597,24 @@ class ControllerImpl {
         );
         this.handlerToTransport.delete(handler);
       }
+      this._pendingHandlers = this._pendingHandlers.filter(
+        (p) => !(p.event === event && p.handler === handler)
+      );
+    }
+  }
+  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);
+      }
     }
   }
   // ---------------------------------------------------------------------------
@@ -481,10 +623,15 @@ class ControllerImpl {
   destroy() {
     if (this._isDestroyed) return;
     this.logger.lifecycle("Destroying controller");
-    this.cleanup();
     this._isDestroyed = true;
+    this._isReady = false;
+    this.cleanup();
   }
   cleanup() {
+    if (this._initTimeoutId) {
+      clearTimeout(this._initTimeoutId);
+      this._initTimeoutId = null;
+    }
     this._isReady = false;
     for (const { event, handler } of this.registeredHandlers) {
       this.transport?.off(event, handler);
@@ -492,6 +639,10 @@ class ControllerImpl {
     this.registeredHandlers = [];
     this.eventListeners.clear();
     this.handlerToTransport.clear();
+    this._pendingHandlers = [];
+    this._lifecycleListeners.clear();
+    this._isConnected = false;
+    this._outboundBuffer = [];
     if (this.transport) {
       this.transport.destroy();
       this.transport = null;
@@ -515,15 +666,16 @@ class ControllerImpl {
     if (!this._isReady || !this.transport) {
       throw new SmoreSDKError(
         "NOT_READY",
-        `Cannot call ${method}() before controller is ready. Use await createController() or wait for onReady callback.`,
+        `Cannot call ${method}() before controller is ready. Use await controller.ready.`,
         { details: { method, isReady: this._isReady } }
       );
     }
   }
   handleError(error) {
     this.logger.warn(`Error in handler: ${error.message}`);
-    if (this.config.onError) {
-      this.config.onError(error.toSmoreError());
+    const smoreError = error.toSmoreError();
+    if (this._hasLifecycleListeners("$error")) {
+      this._emitLifecycle("$error", smoreError);
     } else {
       this.logger.error(error.message, error.details);
     }
@@ -536,10 +688,7 @@ class ControllerImpl {
   }
 }
 function createController(config) {
-  const controller = new ControllerImpl(config ?? {});
-  const promise = controller.initialize().then(() => controller);
-  promise.instance = controller;
-  return promise;
+  return new ControllerImpl(config ?? {});
 }
 
 export { createController };