@smoregg/sdk 0.6.2 → 1.0.0

package/dist/esm/controller.js

@@ -1,103 +1,29 @@
 import { PostMessageTransport } from './transport/PostMessageTransport.js';
-import { isSmoreMessage } from './transport/protocol.js';
+import { isBridgeMessage, validateInitPayload } from './transport/protocol.js';
+import { SmoreSDKError } from './errors.js';
+import { validateEventName, SMORE_EVENTS } from './events.js';
+import { DebugLogger } from './logger.js';
 
-const SYSTEM_PREFIX = "smore:";
-const SYSTEM_EVENTS = {
-  PLAYER_JOIN: `${SYSTEM_PREFIX}player-join`,
-  PLAYER_LEAVE: `${SYSTEM_PREFIX}player-leave`
-};
 const DEFAULT_TIMEOUT = 1e4;
-class SmoreSDKError extends Error {
-  code;
-  cause;
-  details;
-  constructor(code, message, options) {
-    super(message);
-    this.name = "SmoreSDKError";
-    this.code = code;
-    this.cause = options?.cause;
-    this.details = options?.details;
-    const ErrorWithCapture = Error;
-    if (typeof ErrorWithCapture.captureStackTrace === "function") {
-      ErrorWithCapture.captureStackTrace(this, SmoreSDKError);
-    }
-  }
-  toSmoreError() {
-    return {
-      code: this.code,
-      message: this.message,
-      cause: this.cause,
-      details: this.details
-    };
-  }
-}
-const EVENT_NAME_REGEX = /^[a-zA-Z]([a-zA-Z0-9_-]*[a-zA-Z0-9])?$/;
-function validateEventName(event) {
-  if (!event || typeof event !== "string") {
-    throw new SmoreSDKError("INVALID_EVENT", "Event name must be a non-empty string");
-  }
-  if (!EVENT_NAME_REGEX.test(event)) {
-    throw new SmoreSDKError(
-      "INVALID_EVENT",
-      `Invalid event name "${event}". Event names must:
-  - Start with a letter (a-z, A-Z)
-  - Only contain letters, numbers, hyphens (-), and underscores (_)
-  - End with a letter or number`,
-      { details: { event } }
-    );
-  }
-}
-function createLogger(options) {
-  const enabled = typeof options === "boolean" ? options : options?.enabled ?? false;
-  const level = (typeof options === "object" ? options.level : void 0) ?? "debug";
-  const prefix = (typeof options === "object" ? options.prefix : void 0) ?? "[SmoreController]";
-  const customLogger = typeof options === "object" ? options.logger : void 0;
-  const levelPriority = {
-    debug: 0,
-    info: 1,
-    warn: 2,
-    error: 3
-  };
-  const shouldLog = (msgLevel) => {
-    if (!enabled) return false;
-    return levelPriority[msgLevel] >= levelPriority[level];
-  };
-  const log = (msgLevel, message, data) => {
-    if (!shouldLog(msgLevel)) return;
-    if (customLogger) {
-      customLogger(msgLevel, message, data);
-      return;
-    }
-    const fullMessage = `${prefix} ${message}`;
-    const consoleFn = console[msgLevel] ?? console.log;
-    if (data !== void 0) {
-      consoleFn(fullMessage, data);
-    } else {
-      consoleFn(fullMessage);
-    }
-  };
-  return {
-    debug: (msg, data) => log("debug", msg, data),
-    info: (msg, data) => log("info", msg, data),
-    warn: (msg, data) => log("warn", msg, data),
-    error: (msg, data) => log("error", msg, data)
-  };
-}
 class ControllerImpl {
   transport = null;
   config;
   logger;
   _roomCode = "";
   _myIndex = -1;
-  _isLeader = false;
   _isReady = false;
   _isDestroyed = false;
   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();
   constructor(config = {}) {
     this.config = config;
-    this.logger = createLogger(config.debug);
+    this.logger = new DebugLogger(config.debug, "[SmoreController]");
     if (config.listeners) {
       for (const event of Object.keys(config.listeners)) {
         validateEventName(event);
@@ -110,9 +36,6 @@ class ControllerImpl {
   get myIndex() {
     return this._myIndex;
   }
-  get isLeader() {
-    return this._isLeader;
-  }
   get roomCode() {
     return this._roomCode;
   }
@@ -122,19 +45,35 @@ class ControllerImpl {
   get isDestroyed() {
     return this._isDestroyed;
   }
+  /**
+   * Read-only list of all known controllers (players) in the room.
+   * Returns full ControllerInfo including playerIndex, nickname, connected status, and appearance.
+   *
+   * Returns a new shallow copy on every access. Cache the result if accessing
+   * repeatedly in the same frame/tick.
+   */
+  get controllers() {
+    return [...this._controllers];
+  }
+  /**
+   * Returns the number of currently connected players.
+   */
+  getControllerCount() {
+    return this._controllers.filter((c) => c.connected).length;
+  }
   // ---------------------------------------------------------------------------
   // Initialization
   // ---------------------------------------------------------------------------
   async initialize() {
     const parentOrigin = this.config.parentOrigin ?? "*";
     const timeout = this.config.timeout ?? DEFAULT_TIMEOUT;
-    this.logger.debug("Initializing controller...", { parentOrigin, 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 smore:init message.`,
+          `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);
@@ -143,22 +82,36 @@ class ControllerImpl {
       this.boundMessageHandler = (e) => {
         if (parentOrigin !== "*" && e.origin !== parentOrigin) return;
         const msg = e.data;
-        if (!isSmoreMessage(msg)) return;
-        if (msg.type === "smore:init") {
+        if (!isBridgeMessage(msg)) return;
+        if (msg.type === "_bridge:init") {
           clearTimeout(timeoutId);
           this.handleInit(msg, parentOrigin, resolve, reject);
-        } else if (msg.type === "smore:update") {
+        } else if (msg.type === "_bridge:update") {
           this.handleUpdate(msg);
         }
       };
       window.addEventListener("message", this.boundMessageHandler);
-      this.logger.debug("Sending smore:ready to parent");
-      window.parent.postMessage({ type: "smore:ready" }, parentOrigin);
+      this.logger.lifecycle("Sending _bridge:ready to parent");
+      window.parent.postMessage({ type: "_bridge:ready" }, parentOrigin);
     });
   }
   handleInit(msg, parentOrigin, resolve, reject) {
-    const initData = msg.payload;
-    this.logger.debug("Received smore:init", initData);
+    const initPayload = msg.payload;
+    this.logger.debug("Received _bridge:init", initPayload);
+    try {
+      validateInitPayload(initPayload);
+    } catch (err) {
+      const error = new SmoreSDKError(
+        "INIT_FAILED",
+        `Invalid _bridge:init payload: ${err instanceof Error ? err.message : String(err)}`,
+        { details: { payload: initPayload } }
+      );
+      this.logger.warn("_bridge:init validation failed", error);
+      this.handleError(error);
+      reject(error);
+      return;
+    }
+    const initData = initPayload;
     if (initData.side !== "player") {
       const error = new SmoreSDKError(
         "INIT_FAILED",
@@ -182,49 +135,171 @@ class ControllerImpl {
     this.transport = new PostMessageTransport(parentOrigin);
     this._roomCode = initData.roomCode;
     this._myIndex = initData.myIndex;
-    this._isLeader = initData.isLeader ?? false;
+    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.setupEventHandlers();
     this._isReady = true;
-    this.logger.info("Controller ready", {
+    this.logger.lifecycle("Controller ready", {
       roomCode: this._roomCode,
-      myIndex: this._myIndex,
-      isLeader: this._isLeader
+      myIndex: this._myIndex
     });
     this.config.onReady?.();
     resolve();
   }
   handleUpdate(msg) {
+    if (!this._isReady) {
+      this.logger.debug("Ignoring _bridge:update before init completes");
+      return;
+    }
     const updateData = msg.payload;
-    this.logger.debug("Received smore:update", updateData);
+    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 oldControllers = this._controllers;
+      for (const nc of newControllers) {
+        if (!oldControllers.some((oc) => oc.playerIndex === nc.playerIndex)) {
+          this.config.onControllerJoin?.(nc.playerIndex, nc);
+        }
+      }
+      for (const oc of oldControllers) {
+        if (!newControllers.some((nc) => nc.playerIndex === oc.playerIndex)) {
+          this.config.onControllerLeave?.(oc.playerIndex);
+        }
+      }
+      for (const nc of newControllers) {
+        const oc = oldControllers.find((c) => c.playerIndex === nc.playerIndex);
+        if (oc) {
+          if (oc.connected && !nc.connected) {
+            this.logger.debug("Player disconnected (via update)", { playerIndex: nc.playerIndex });
+            this.config.onControllerDisconnect?.(nc.playerIndex);
+          }
+          if (!oc.connected && nc.connected) {
+            this.logger.debug("Player reconnected (via update)", { playerIndex: nc.playerIndex });
+            this.config.onControllerReconnect?.(nc.playerIndex, nc);
+          }
+        }
+      }
+      this._controllers = newControllers;
+    }
   }
   setupEventHandlers() {
     if (!this.transport) return;
-    this.registerHandler(
-      SYSTEM_EVENTS.PLAYER_JOIN,
-      (data) => {
-        const playerIndex = data.player?.playerIndex ?? data.playerIndex;
-        if (playerIndex !== void 0) {
-          this.logger.debug("Player joined", { playerIndex });
-          this.config.onControllerJoin?.(playerIndex, data.player);
-        }
+    this.registerHandler(SMORE_EVENTS.PLAYER_JOINED, (raw) => {
+      const data = raw;
+      const playerInfo = data.player;
+      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
+        };
+        this._controllers = [...this._controllers, controllerInfo];
+        this.logger.debug("Player joined", { playerIndex });
+        this.config.onControllerJoin?.(playerIndex, controllerInfo);
       }
-    );
-    this.registerHandler(
-      SYSTEM_EVENTS.PLAYER_LEAVE,
-      (data) => {
-        const playerIndex = data.player?.playerIndex ?? data.playerIndex;
-        if (playerIndex !== void 0) {
-          this.logger.debug("Player left", { playerIndex });
-          this.config.onControllerLeave?.(playerIndex);
-        }
+    });
+    this.registerHandler(SMORE_EVENTS.PLAYER_LEFT, (raw) => {
+      const data = raw;
+      const playerIndex = data.player?.playerIndex ?? data.playerIndex;
+      if (playerIndex !== void 0) {
+        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.registerHandler(SMORE_EVENTS.PLAYER_DISCONNECTED, (raw) => {
+      const data = raw;
+      const playerData = data.player;
+      const playerIndex = playerData?.playerIndex ?? data.playerIndex;
+      if (playerIndex !== void 0) {
+        this._controllers = this._controllers.map(
+          (c) => c.playerIndex === playerIndex ? { ...c, connected: false } : c
+        );
+        this.logger.debug("Player disconnected", { playerIndex });
+        this.config.onControllerDisconnect?.(playerIndex);
       }
-    );
+    });
+    this.registerHandler(SMORE_EVENTS.PLAYER_RECONNECTED, (raw) => {
+      const data = raw;
+      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
+        };
+        this._controllers = this._controllers.map(
+          (c) => c.playerIndex === playerIndex ? controllerInfo : c
+        );
+        this.logger.debug("Player reconnected", { playerIndex });
+        this.config.onControllerReconnect?.(playerIndex, controllerInfo);
+      }
+    });
+    this.registerHandler(SMORE_EVENTS.PLAYER_CHARACTER_UPDATED, (raw) => {
+      const payload = raw;
+      const playerData = payload?.player;
+      if (playerData && typeof playerData.playerIndex === "number") {
+        const appearance = playerData.character ?? null;
+        this._controllers = this._controllers.map(
+          (c) => c.playerIndex === playerData.playerIndex ? { ...c, appearance } : c
+        );
+        this.logger.debug("Player character updated", { playerIndex: playerData.playerIndex });
+        this.config.onCharacterUpdated?.(playerData.playerIndex, 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);
+    });
+    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);
-          handler(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 }
+              })
+            );
+          }
         });
       }
     }
@@ -237,9 +312,24 @@ class ControllerImpl {
   // ---------------------------------------------------------------------------
   // 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,
+   * 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");
     validateEventName(event);
+    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).'
+      );
+    }
     this.logSend(event, data);
     this.transport.emit(event, data);
   }
@@ -252,6 +342,28 @@ class ControllerImpl {
   // ---------------------------------------------------------------------------
   // Event Subscription
   // ---------------------------------------------------------------------------
+  /**
+   * Register a handler for custom events.
+   *
+   * When receiving events from Screen's `broadcast()`:
+   *   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.
+   */
   on(event, handler) {
     validateEventName(event);
     let listeners = this.eventListeners.get(event);
@@ -262,11 +374,21 @@ class ControllerImpl {
     listeners.add(handler);
     const transportHandler = (data) => {
       this.logReceive(event, data);
-      handler(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 });
     }
     return () => {
       listeners?.delete(handler);
@@ -277,8 +399,25 @@ class ControllerImpl {
       this.registeredHandlers = this.registeredHandlers.filter(
         (h) => h.handler !== transportHandler
       );
+      this.handlerToTransport.delete(handler);
     };
   }
+  /**
+   * Add a one-time listener that auto-removes after first call.
+   *
+   * @note The handler is internally wrapped, so it cannot be removed via
+   * `off(event, originalHandler)`. Use the returned unsubscribe function instead.
+   *
+   * @example
+   * ```ts
+   * const unsubscribe = controller.once('game-start', (data) => {
+   *   console.log('Game started!', data);
+   * });
+   *
+   * // To cancel before it fires:
+   * unsubscribe();
+   * ```
+   */
   once(event, handler) {
     const unsubscribe = this.on(event, ((data) => {
       unsubscribe();
@@ -288,15 +427,38 @@ class ControllerImpl {
   }
   off(event, handler) {
     if (!handler) {
-      this.eventListeners.delete(event);
-      this.transport?.off(event);
-      this.registeredHandlers = this.registeredHandlers.filter((h) => h.event !== event);
+      if (this._configListenerEvents.has(event)) {
+        for (const [key, val] of this.handlerToTransport) {
+          if (val.event === event) {
+            this.transport?.off(event, val.transportHandler);
+            this.registeredHandlers = this.registeredHandlers.filter(
+              (h) => h.handler !== val.transportHandler
+            );
+            this.handlerToTransport.delete(key);
+          }
+        }
+      } else {
+        this.eventListeners.delete(event);
+        this.transport?.off(event);
+        this.registeredHandlers = this.registeredHandlers.filter((h) => h.event !== event);
+        for (const [key, val] of this.handlerToTransport) {
+          if (val.event === event) this.handlerToTransport.delete(key);
+        }
+      }
     } else {
       const listeners = this.eventListeners.get(event);
       listeners?.delete(handler);
       if (listeners?.size === 0) {
         this.eventListeners.delete(event);
       }
+      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);
+      }
     }
   }
   // ---------------------------------------------------------------------------
@@ -304,7 +466,7 @@ class ControllerImpl {
   // ---------------------------------------------------------------------------
   destroy() {
     if (this._isDestroyed) return;
-    this.logger.info("Destroying controller");
+    this.logger.lifecycle("Destroying controller");
     this.cleanup();
     this._isDestroyed = true;
   }
@@ -315,6 +477,7 @@ class ControllerImpl {
     }
     this.registeredHandlers = [];
     this.eventListeners.clear();
+    this.handlerToTransport.clear();
     if (this.transport) {
       this.transport.destroy();
       this.transport = null;
@@ -344,6 +507,7 @@ class ControllerImpl {
     }
   }
   handleError(error) {
+    this.logger.warn(`Error in handler: ${error.message}`);
     if (this.config.onError) {
       this.config.onError(error.toSmoreError());
     } else {
@@ -351,18 +515,10 @@ class ControllerImpl {
     }
   }
   logSend(event, data) {
-    const options = this.config.debug;
-    const shouldLog = typeof options === "object" ? options.logSend ?? true : Boolean(options);
-    if (shouldLog) {
-      this.logger.debug(`\u2192 SEND [${event}]`, data);
-    }
+    this.logger.send(event, data);
   }
   logReceive(event, data) {
-    const options = this.config.debug;
-    const shouldLog = typeof options === "object" ? options.logReceive ?? true : Boolean(options);
-    if (shouldLog) {
-      this.logger.debug(`\u2190 RECV [${event}]`, data);
-    }
+    this.logger.receive(event, data);
   }
 }
 function createController(config) {
@@ -372,5 +528,5 @@ function createController(config) {
   return promise;
 }
 
-export { SmoreSDKError, createController };
+export { createController };
 //# sourceMappingURL=controller.js.map