@wvdsh/sdk-js 1.2.2 → 1.2.4

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"];
@@ -72,7 +73,7 @@ interface RemoteFileMetadata {
 }
 interface EngineInstance {
     type: (typeof GAME_ENGINE)[keyof typeof GAME_ENGINE];
-    SendMessage(objectName: string, methodName: WavedashEvent, value?: string | number | boolean): void;
+    SendMessage(objectName: string, methodName: WavedashEvent, value?: string | number): void;
     FS: {
         readFile(path: string, opts?: Record<string, unknown>): string | Uint8Array;
         writeFile(path: string, data: string | ArrayBufferView, opts?: Record<string, unknown>): void;
@@ -184,6 +185,10 @@ interface BackendConnectionPayload {
     connectionCount: number;
     connectionRetries: number;
 }
+/** Payload for FullscreenChanged event - emitted when fullscreen state flips */
+interface FullscreenChangedPayload {
+    isFullscreen: boolean;
+}
 interface P2PPeer {
     userId: GenericId<"users">;
     username: string;
@@ -585,11 +590,68 @@ declare class GameEventManager {
     private sdk;
     private eventQueue;
     constructor(sdk: WavedashSDK);
-    notifyGame(event: WavedashEvent, payload: string | number | boolean | object): void;
+    notifyGame(event: WavedashEvent, payload: string | number | object): void;
     private sendGameEvent;
     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 +721,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 +766,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 +785,8 @@ declare class WavedashSDK extends EventTarget {
     logger: WavedashLogger;
     iframeMessenger: IFrameMessenger;
     p2pManager: P2PManager;
+    fullscreenManager: FullscreenManager;
+    overlayManager: OverlayManager;
     private gameplayJwt;
     private gameplayJwtPromise;
     ugcHost: string;
@@ -735,6 +804,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.
@@ -969,4 +1055,4 @@ declare class WavedashSDK extends EventTarget {
 
 declare function setupWavedashSDK(): WavedashSDK;
 
-export { AVATAR_SIZE_LARGE, AVATAR_SIZE_MEDIUM, AVATAR_SIZE_SMALL, type BackendConnectionPayload, type EngineInstance, type Friend, type Leaderboard, type LeaderboardDisplayType, type LeaderboardEntries, type LeaderboardSortOrder, type Lobby, type LobbyDataUpdatedPayload, type LobbyInvite, type LobbyInvitePayload, type LobbyJoinResponse, type LobbyJoinedPayload, type LobbyKickedPayload, LobbyKickedReason, type LobbyMessage, type LobbyMessagePayload, type LobbyUser, LobbyUserChangeType, type LobbyUsersUpdatedPayload, type LobbyVisibility, type P2PConfig, type P2PConnection, type P2PConnectionEstablishedPayload, type P2PConnectionFailedPayload, type P2PMessage, type P2PPacketDropReason, type P2PPacketDroppedPayload, type P2PPeer, type P2PPeerDisconnectedPayload, type P2PPeerReconnectedPayload, type P2PPeerReconnectingPayload, type P2PSignalingMessage, type P2PTurnCredentials, type RemoteFileMetadata, type StatsStoredPayload, type UGCType, type UGCVisibility, type UpsertedLeaderboardEntry, type WavedashConfig, type WavedashEvent, WavedashEvents, type WavedashResponse, WavedashSDK, setupWavedashSDK };
+export { AVATAR_SIZE_LARGE, AVATAR_SIZE_MEDIUM, AVATAR_SIZE_SMALL, type BackendConnectionPayload, type EngineInstance, type Friend, type FullscreenChangedPayload, type Leaderboard, type LeaderboardDisplayType, type LeaderboardEntries, type LeaderboardSortOrder, type Lobby, type LobbyDataUpdatedPayload, type LobbyInvite, type LobbyInvitePayload, type LobbyJoinResponse, type LobbyJoinedPayload, type LobbyKickedPayload, LobbyKickedReason, type LobbyMessage, type LobbyMessagePayload, type LobbyUser, LobbyUserChangeType, type LobbyUsersUpdatedPayload, type LobbyVisibility, type P2PConfig, type P2PConnection, type P2PConnectionEstablishedPayload, type P2PConnectionFailedPayload, type P2PMessage, type P2PPacketDropReason, type P2PPacketDroppedPayload, type P2PPeer, type P2PPeerDisconnectedPayload, type P2PPeerReconnectedPayload, type P2PPeerReconnectingPayload, type P2PSignalingMessage, type P2PTurnCredentials, type RemoteFileMetadata, type StatsStoredPayload, type UGCType, type UGCVisibility, type UpsertedLeaderboardEntry, type WavedashConfig, type WavedashEvent, WavedashEvents, type WavedashResponse, WavedashSDK, setupWavedashSDK };

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,
+          { isFullscreen: 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.4",
   "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"
   }