@wvdsh/sdk-js 1.2.2 → 1.2.3

package/dist/index.d.ts

@@ -2,7 +2,7 @@ import { ConvexClient } from 'convex/browser';
 import { GenericId } from 'convex/values';
 export { GenericId as Id } from 'convex/values';
 import { FunctionReturnType } from 'convex/server';
-import { PublicApiType, api, GAME_ENGINE, SDKUser, IFRAME_MESSAGE_TYPE, IFrameEventPayloadMap, SDKConfig, GameLaunchParams } from '@wvdsh/api';
+import { PublicApiType, api, GAME_ENGINE, SDKUser, IFrameEventPayloadMap, IFRAME_MESSAGE_TYPE, SDKConfig, GameLaunchParams } from '@wvdsh/api';
 export { GameLaunchParams } from '@wvdsh/api';
 
 /**
@@ -30,6 +30,7 @@ declare const WavedashEvents: {
     readonly BACKEND_CONNECTED: "BackendConnected";
     readonly BACKEND_DISCONNECTED: "BackendDisconnected";
     readonly BACKEND_RECONNECTING: "BackendReconnecting";
+    readonly FULLSCREEN_CHANGED: "FullscreenChanged";
 };
 
 type LobbyVisibility = PublicApiType["sdk"]["gameLobby"]["createAndJoinLobby"]["_args"]["visibility"];
@@ -590,6 +591,63 @@ declare class GameEventManager {
     flushEventQueue(): void;
 }
 
+/**
+ * FullscreenManager
+ *
+ * Wavedash owns the fullscreen target (a wrapper DIV on the host page that
+ * contains both the game iframe and our overlay UI). The SDK inside the iframe
+ * therefore can't call `requestFullscreen` directly — it asks the parent to
+ * do it via postMessage, and the parent broadcasts state changes back through
+ * FULLSCREEN_CHANGED so we can keep a local mirror of `isFullscreen`.
+ *
+ * User activation: browsers require a fresh user gesture to enter fullscreen.
+ * The click happens in the iframe, User Activation v2 propagates transient
+ * activation to ancestor frames, and the parent's message handler runs within
+ * the ~5s window — so the parent's requestFullscreen call stays activated.
+ *
+ * Legacy compat: games that call `element.requestFullscreen()` or listen for
+ * `fullscreenchange` directly are monkey-patched in the constructor so those
+ * calls route through us. The iframe isn't granted the fullscreen feature
+ * policy anymore, so without these shims those calls would silently reject.
+ */
+declare class FullscreenManager {
+    private _isFullscreen;
+    private listeners;
+    private sdk;
+    constructor(sdk: WavedashSDK);
+    isFullscreen(): boolean;
+    /**
+     * Ask the host to enter (true) or exit (false) fullscreen. Resolves to
+     * `true` if the host reports the operation succeeded, `false` otherwise
+     * (e.g. browser rejected for lack of user activation).
+     */
+    requestFullscreen(fullscreen: boolean): Promise<boolean>;
+    toggleFullscreen(): Promise<boolean>;
+    /** Subscribe to state flips. Returns an unsubscribe fn. */
+    subscribe(listener: (isFullscreen: boolean) => void): () => void;
+    private setState;
+    private installCompatShims;
+}
+
+/**
+ * OverlayManager
+ *
+ * Owns the iframe ↔ parent interactions for the Wavedash overlay UI:
+ * - Shift+Tab inside the iframe toggles the overlay on the host page
+ *   (the host owns the overlay, so we postMessage up).
+ * - When the parent closes the overlay it sends TAKE_FOCUS so keyboard
+ *   input goes back to the game; we walk the DOM for a focusable target.
+ * - `takeFocus()` is also called after load completes so the game starts
+ *   with keyboard focus without the player clicking first.
+ */
+declare class OverlayManager {
+    private sdk;
+    constructor(sdk: WavedashSDK);
+    toggleOverlay(): void;
+    takeFocus(): void;
+    private handleKeyDown;
+}
+
 /**
  * Friends service
  *
@@ -659,18 +717,22 @@ declare class WavedashLogger implements Logger {
  * TODO: Look into Vercel's BIDC for this https://github.com/vercel/bidc
  */
 
+type PushType = keyof IFrameEventPayloadMap;
+type PushListener<T extends PushType> = (data: IFrameEventPayloadMap[T]) => void;
 declare class IFrameMessenger {
     private pendingRequests;
     private requestIdCounter;
+    private listeners;
     constructor();
-    private handleMessage;
-    postToParent(requestType: (typeof IFRAME_MESSAGE_TYPE)[keyof typeof IFRAME_MESSAGE_TYPE], data: Record<string, string | number | boolean>): boolean;
     /**
-     * Register global keyboard/mouse handlers for iframe communication.
-     * Handles F3 prevention, initial interaction signaling, and Tab+Shift overlay toggle.
-     * Called once during SDK setup.
+     * Register a handler for a one-way (no requestId) push from the parent —
+     * e.g. FULLSCREEN_CHANGED or TAKE_FOCUS. Multiple handlers per type are
+     * supported; `data` is typed from IFramePushMap.
      */
-    registerEventHandlers(): void;
+    addEventListener<T extends PushType>(type: T, listener: PushListener<T>): void;
+    removeEventListener<T extends PushType>(type: T, listener: PushListener<T>): void;
+    private handleMessage;
+    postToParent(requestType: (typeof IFRAME_MESSAGE_TYPE)[keyof typeof IFRAME_MESSAGE_TYPE], data: Record<string, string | number | boolean>): boolean;
     requestFromParent<T extends keyof IFrameEventPayloadMap>(requestType: T, data?: Record<string, unknown>): Promise<IFrameEventPayloadMap[T]>;
 }
 
@@ -700,6 +762,7 @@ declare class WavedashSDK extends EventTarget {
         readonly BACKEND_CONNECTED: "BackendConnected";
         readonly BACKEND_DISCONNECTED: "BackendDisconnected";
         readonly BACKEND_RECONNECTING: "BackendReconnecting";
+        readonly FULLSCREEN_CHANGED: "FullscreenChanged";
     };
     protected lobbyManager: LobbyManager;
     protected statsManager: StatsManager;
@@ -718,6 +781,8 @@ declare class WavedashSDK extends EventTarget {
     logger: WavedashLogger;
     iframeMessenger: IFrameMessenger;
     p2pManager: P2PManager;
+    fullscreenManager: FullscreenManager;
+    overlayManager: OverlayManager;
     private gameplayJwt;
     private gameplayJwtPromise;
     ugcHost: string;
@@ -735,6 +800,23 @@ declare class WavedashSDK extends EventTarget {
     loadComplete(): void;
     get gameLoaded(): boolean;
     toggleOverlay(): void;
+    /**
+     * Whether the game is currently presented in fullscreen. Mirrored from the
+     * Wavedash host page, which owns the real fullscreen target so our overlay
+     * UI stays on top of the game.
+     */
+    isFullscreen(): boolean;
+    /**
+     * Ask the host page to enter (true) or exit (false) fullscreen. Entering
+     * must happen inside a user gesture handler (click / keydown / pointerdown)
+     * for the browser to permit it.
+     */
+    requestFullscreen(fullscreen: boolean): Promise<boolean>;
+    /**
+     * Toggle fullscreen. Like `requestFullscreen(true)`, this must run inside
+     * a user gesture handler when entering fullscreen.
+     */
+    toggleFullscreen(): Promise<boolean>;
     getUser(): SDKUser;
     /**
      * Get a username. Returns the logged in user's username if no ID is passed.

package/dist/index.js

@@ -4218,8 +4218,11 @@ var WavedashEvents = {
   // connected to Convex backend
   BACKEND_DISCONNECTED: "BackendDisconnected",
   // disconnected from Convex backend
-  BACKEND_RECONNECTING: "BackendReconnecting"
+  BACKEND_RECONNECTING: "BackendReconnecting",
   // attempting to reconnect to backend
+  // Fullscreen events
+  FULLSCREEN_CHANGED: "FullscreenChanged"
+  // fullscreen state changed
   // TODO: Future events to implement
   // P2P_CONNECTION_REQUESTED: 'P2PConnectionRequested', // for now we always connect all lobby members
 };
@@ -6294,16 +6297,13 @@ var _P2PManager = class _P2PManager {
     }
   }
   emitPacketDropped(tracker, droppedCount) {
-    this.sdk.gameEventManager.notifyGame(
-      WavedashEvents.P2P_PACKET_DROPPED,
-      {
-        channel: tracker.channel,
-        direction: tracker.direction,
-        reason: tracker.reason,
-        droppedCount,
-        droppedTotal: tracker.droppedTotal
-      }
-    );
+    this.sdk.gameEventManager.notifyGame(WavedashEvents.P2P_PACKET_DROPPED, {
+      channel: tracker.channel,
+      direction: tracker.direction,
+      reason: tracker.reason,
+      droppedCount,
+      droppedTotal: tracker.droppedTotal
+    });
   }
   clearPacketDropTrackers() {
     for (const tracker of this.packetDropTrackers.values()) {
@@ -6585,11 +6585,10 @@ var StatsManager = class {
     // Debounced persist — used by storeNow in setters to batch rapid calls.
     // Leading+trailing: first call fires immediately, subsequent calls within
     // the window are batched into one trailing call.
-    this.debouncedPersist = (0, import_lodash2.default)(
-      () => this.persist(),
-      STORE_DEBOUNCE_MS,
-      { leading: true, trailing: true }
-    );
+    this.debouncedPersist = (0, import_lodash2.default)(() => this.persist(), STORE_DEBOUNCE_MS, {
+      leading: true,
+      trailing: true
+    });
     this.sdk = sdk;
     this.subscribe();
     this.requestStats().catch((error) => {
@@ -6956,6 +6955,135 @@ var GameEventManager = class {
   }
 };
 
+// src/services/fullscreen.ts
+import { IFRAME_MESSAGE_TYPE as IFRAME_MESSAGE_TYPE3 } from "@wvdsh/api";
+var FullscreenManager = class {
+  constructor(sdk) {
+    this._isFullscreen = false;
+    this.listeners = /* @__PURE__ */ new Set();
+    this.sdk = sdk;
+    this.sdk.iframeMessenger.addEventListener(
+      IFRAME_MESSAGE_TYPE3.FULLSCREEN_CHANGED,
+      (data) => {
+        this.sdk.gameEventManager.notifyGame(
+          WavedashEvents.FULLSCREEN_CHANGED,
+          data.isFullscreen
+        );
+        this.setState(data.isFullscreen);
+      }
+    );
+    this.installCompatShims();
+  }
+  isFullscreen() {
+    return this._isFullscreen;
+  }
+  /**
+   * Ask the host to enter (true) or exit (false) fullscreen. Resolves to
+   * `true` if the host reports the operation succeeded, `false` otherwise
+   * (e.g. browser rejected for lack of user activation).
+   */
+  async requestFullscreen(fullscreen) {
+    const response = await this.sdk.iframeMessenger.requestFromParent(
+      IFRAME_MESSAGE_TYPE3.SET_FULLSCREEN,
+      { fullscreen }
+    );
+    return response.success;
+  }
+  async toggleFullscreen() {
+    const response = await this.sdk.iframeMessenger.requestFromParent(
+      IFRAME_MESSAGE_TYPE3.TOGGLE_FULLSCREEN
+    );
+    return response.success;
+  }
+  /** Subscribe to state flips. Returns an unsubscribe fn. */
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+  setState(isFullscreen) {
+    if (this._isFullscreen === isFullscreen) return;
+    this._isFullscreen = isFullscreen;
+    for (const listener of this.listeners) listener(isFullscreen);
+  }
+  installCompatShims() {
+    if (typeof document === "undefined") return;
+    const fullscreenElementGetter = () => this._isFullscreen ? document.body : null;
+    Object.defineProperty(document, "fullscreenElement", {
+      configurable: true,
+      get: fullscreenElementGetter
+    });
+    Object.defineProperty(document, "webkitFullscreenElement", {
+      configurable: true,
+      get: fullscreenElementGetter
+    });
+    const enter = async () => {
+      if (this._isFullscreen) return;
+      const ok = await this.requestFullscreen(true);
+      if (!ok) throw new Error("Fullscreen request was denied");
+    };
+    const exit = async () => {
+      if (!this._isFullscreen) return;
+      const ok = await this.requestFullscreen(false);
+      if (!ok) throw new Error("Exit fullscreen request was denied");
+    };
+    Element.prototype.requestFullscreen = function() {
+      return enter();
+    };
+    Element.prototype.webkitRequestFullscreen = function() {
+      return enter();
+    };
+    Document.prototype.exitFullscreen = function() {
+      return exit();
+    };
+    Document.prototype.webkitExitFullscreen = function() {
+      return exit();
+    };
+    this.subscribe(() => {
+      document.dispatchEvent(new Event("fullscreenchange", { bubbles: true }));
+    });
+  }
+};
+
+// src/services/overlay.ts
+import { IFRAME_MESSAGE_TYPE as IFRAME_MESSAGE_TYPE4 } from "@wvdsh/api";
+var OverlayManager = class {
+  constructor(sdk) {
+    this.handleKeyDown = (event) => {
+      if (event.defaultPrevented) return;
+      if (event.key === "Tab" && event.shiftKey) {
+        event.preventDefault();
+        this.toggleOverlay();
+      }
+    };
+    this.sdk = sdk;
+    this.sdk.iframeMessenger.addEventListener(
+      IFRAME_MESSAGE_TYPE4.TAKE_FOCUS,
+      () => this.takeFocus()
+    );
+    if (typeof window !== "undefined") {
+      window.addEventListener("keydown", this.handleKeyDown);
+    }
+  }
+  toggleOverlay() {
+    this.sdk.iframeMessenger.postToParent(
+      IFRAME_MESSAGE_TYPE4.TOGGLE_OVERLAY,
+      {}
+    );
+  }
+  takeFocus() {
+    if (typeof document === "undefined") return;
+    const gameFocusTargets = document.getElementsByClassName("game-focus-target");
+    if (gameFocusTargets.length > 0) {
+      gameFocusTargets[0].focus();
+      return;
+    }
+    const focusableElement = document.querySelector(
+      "canvas, input, button, [tabindex]:not([tabindex='-1'])"
+    );
+    focusableElement?.focus();
+  }
+};
+
 // src/services/friends.ts
 import { api as api8 } from "@wvdsh/api";
 
@@ -7069,26 +7197,6 @@ var WavedashLogger = class {
   }
 };
 
-// src/utils/iframeMessenger.ts
-import { IFRAME_MESSAGE_TYPE as IFRAME_MESSAGE_TYPE3 } from "@wvdsh/api";
-
-// src/utils/focusManager.ts
-function takeFocus() {
-  if (typeof document !== "undefined") {
-    const gameFocusTargets = document.getElementsByClassName("game-focus-target");
-    if (gameFocusTargets.length > 0) {
-      gameFocusTargets[0].focus();
-    } else {
-      const focusableElement = document.querySelector(
-        "canvas, input, button, [tabindex]:not([tabindex='-1'])"
-      );
-      if (focusableElement) {
-        focusableElement.focus();
-      }
-    }
-  }
-}
-
 // src/utils/parentOrigin.ts
 function deriveParentOrigin() {
   if (typeof window === "undefined") return "";
@@ -7122,46 +7230,42 @@ var IFrameMessenger = class {
           this.pendingRequests.delete(event.data.requestId);
           pending.resolve(event.data.data);
         }
-      } else if (event.data?.type === IFRAME_MESSAGE_TYPE3.TAKE_FOCUS) {
-        takeFocus();
+        return;
       }
+      const messageType = event.data?.type;
+      if (!messageType) return;
+      const set = this.listeners.get(messageType);
+      if (!set) return;
+      for (const listener of set) listener(event.data);
     };
     this.pendingRequests = /* @__PURE__ */ new Map();
     this.requestIdCounter = 0;
+    this.listeners = /* @__PURE__ */ new Map();
     if (typeof window !== "undefined") {
       window.addEventListener("message", this.handleMessage);
     }
   }
+  /**
+   * Register a handler for a one-way (no requestId) push from the parent —
+   * e.g. FULLSCREEN_CHANGED or TAKE_FOCUS. Multiple handlers per type are
+   * supported; `data` is typed from IFramePushMap.
+   */
+  addEventListener(type, listener) {
+    let set = this.listeners.get(type);
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      this.listeners.set(type, set);
+    }
+    set.add(listener);
+  }
+  removeEventListener(type, listener) {
+    this.listeners.get(type)?.delete(listener);
+  }
   postToParent(requestType, data) {
     if (typeof window === "undefined" || !parentOrigin) return false;
     window.parent.postMessage({ type: requestType, ...data }, parentOrigin);
     return true;
   }
-  /**
-   * Register global keyboard/mouse handlers for iframe communication.
-   * Handles F3 prevention, initial interaction signaling, and Tab+Shift overlay toggle.
-   * Called once during SDK setup.
-   */
-  registerEventHandlers() {
-    let sentInitialInteraction = false;
-    const handleInteraction = () => {
-      if (!sentInitialInteraction) {
-        sentInitialInteraction = true;
-        this.postToParent(IFRAME_MESSAGE_TYPE3.INITIAL_INTERACTION, {});
-      }
-    };
-    window.addEventListener("keydown", (event) => {
-      if (event.key === "F3") {
-        event.preventDefault();
-      }
-      handleInteraction();
-      if (event.key === "Tab" && event.shiftKey) {
-        event.preventDefault();
-        this.postToParent(IFRAME_MESSAGE_TYPE3.TOGGLE_OVERLAY, {});
-      }
-    });
-    window.addEventListener("mousedown", handleInteraction);
-  }
   async requestFromParent(requestType, data) {
     return new Promise((resolve, reject) => {
       if (typeof window === "undefined" || !parentOrigin) {
@@ -7193,7 +7297,7 @@ var IFrameMessenger = class {
 // src/index.ts
 import {
   GAME_ENGINE,
-  IFRAME_MESSAGE_TYPE as IFRAME_MESSAGE_TYPE4,
+  IFRAME_MESSAGE_TYPE as IFRAME_MESSAGE_TYPE5,
   LEADERBOARD_DISPLAY_TYPE,
   LEADERBOARD_SORT_ORDER,
   LOBBY_VISIBILITY,
@@ -7206,9 +7310,7 @@ import {
 var CONVEX_ID_REGEX = /^[0-9a-z]{31,37}$/;
 var vString = (value, path) => {
   if (typeof value !== "string") {
-    throw new Error(
-      `${path}: expected string, got ${describeValue(value)}`
-    );
+    throw new Error(`${path}: expected string, got ${describeValue(value)}`);
   }
   return value;
 };
@@ -7222,9 +7324,7 @@ var vNumber = (value, path) => {
 };
 var vBoolean = (value, path) => {
   if (typeof value !== "boolean") {
-    throw new Error(
-      `${path}: expected boolean, got ${describeValue(value)}`
-    );
+    throw new Error(`${path}: expected boolean, got ${describeValue(value)}`);
   }
   return value;
 };
@@ -7287,9 +7387,7 @@ function vUnion(...variants) {
       } catch {
       }
     }
-    throw new Error(
-      `${path}: no variant matched, got ${describeValue(value)}`
-    );
+    throw new Error(`${path}: no variant matched, got ${describeValue(value)}`);
   };
 }
 function validateArgs(methodName, specs, values) {
@@ -7349,6 +7447,8 @@ var WavedashSDK = class extends EventTarget {
     this.leaderboardManager = new LeaderboardManager(this);
     this.friendsManager = new FriendsManager(this);
     this.gameEventManager = new GameEventManager(this);
+    this.fullscreenManager = new FullscreenManager(this);
+    this.overlayManager = new OverlayManager(this);
     this.friendsManager.cacheUsers([
       {
         userId: this.wavedashUser.id,
@@ -7426,7 +7526,7 @@ var WavedashSDK = class extends EventTarget {
       [["progress", vNumber]],
       [progress]
     );
-    iframeMessenger.postToParent(IFRAME_MESSAGE_TYPE4.PROGRESS_UPDATE, {
+    iframeMessenger.postToParent(IFRAME_MESSAGE_TYPE5.PROGRESS_UPDATE, {
       progress
     });
   }
@@ -7434,14 +7534,40 @@ var WavedashSDK = class extends EventTarget {
     if (this.gameFinishedLoading) return;
     this.gameFinishedLoading = true;
     this.heartbeatManager.start();
-    iframeMessenger.postToParent(IFRAME_MESSAGE_TYPE4.LOADING_COMPLETE, {});
-    takeFocus();
+    iframeMessenger.postToParent(IFRAME_MESSAGE_TYPE5.LOADING_COMPLETE, {});
+    this.overlayManager.takeFocus();
   }
   get gameLoaded() {
     return this.gameFinishedLoading;
   }
   toggleOverlay() {
-    iframeMessenger.postToParent(IFRAME_MESSAGE_TYPE4.TOGGLE_OVERLAY, {});
+    this.overlayManager.toggleOverlay();
+  }
+  // ==========
+  // Fullscreen
+  // ==========
+  /**
+   * Whether the game is currently presented in fullscreen. Mirrored from the
+   * Wavedash host page, which owns the real fullscreen target so our overlay
+   * UI stays on top of the game.
+   */
+  isFullscreen() {
+    return this.fullscreenManager.isFullscreen();
+  }
+  /**
+   * Ask the host page to enter (true) or exit (false) fullscreen. Entering
+   * must happen inside a user gesture handler (click / keydown / pointerdown)
+   * for the browser to permit it.
+   */
+  async requestFullscreen(fullscreen) {
+    return this.fullscreenManager.requestFullscreen(fullscreen);
+  }
+  /**
+   * Toggle fullscreen. Like `requestFullscreen(true)`, this must run inside
+   * a user gesture handler when entering fullscreen.
+   */
+  async toggleFullscreen() {
+    return this.fullscreenManager.toggleFullscreen();
   }
   // ============
   // User methods
@@ -8237,7 +8363,6 @@ var WavedashSDK = class extends EventTarget {
 function setupWavedashSDK() {
   const existing = window.WavedashJS;
   if (existing) return existing;
-  iframeMessenger.registerEventHandlers();
   const raw = new URLSearchParams(window.location.search).get(
     UrlParams.SdkConfig
   );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wvdsh/sdk-js",
-  "version": "1.2.2",
+  "version": "1.2.3",
   "type": "module",
   "description": "Wavedash JavaScript SDK",
   "main": "./dist/index.js",
@@ -40,7 +40,7 @@
     "typescript-eslint": "^8.52.0"
   },
   "dependencies": {
-    "@wvdsh/api": "^0.1.0",
+    "@wvdsh/api": "^0.1.1",
     "convex": "^1.28.0",
     "lodash.debounce": "^4.0.8"
   }