@wvdsh/sdk-js 1.3.15 → 1.3.17

package/dist/index.d.ts

@@ -5,6 +5,76 @@ import { FunctionReturnType, FunctionArgs } from 'convex/server';
 import { LOBBY_VISIBILITY, api, UGC_TYPE, UGC_VISIBILITY, LEADERBOARD_SORT_ORDER, LEADERBOARD_DISPLAY_TYPE, GAME_ENGINE, SDKUser, IFrameEventPayloadMap, IFRAME_MESSAGE_TYPE, SDKConfig, GameLaunchParams } from '@wvdsh/api';
 export { GameLaunchParams } from '@wvdsh/api';
 
+/**
+ * Base class for SDK managers. Provides the shared `sdk` reference and a
+ * default no-op `destroy()` so the SDK can safely iterate every manager
+ * during teardown without each one having to define an empty stub.
+ *
+ * Override `destroy()` in any manager that owns ongoing state — Convex
+ * subscriptions, intervals, peer connections, monkey-patched globals, etc.
+ * — to make sure that state is released when the SDK is torn down.
+ */
+declare abstract class WavedashManager {
+    protected sdk: WavedashSDK;
+    constructor(sdk: WavedashSDK);
+    destroy(): void;
+}
+
+/**
+ * AudioManager
+ *
+ * Mutes & unmutes the game in response to MUTE_CHANGED iframe messages, without
+ * the game needing to know anything about it.
+ *
+ * Web Audio: subclass `AudioContext` so `ctx.destination` resolves to a master
+ * GainNode that we control. The master gain wires to the real native destination,
+ * so `node.connect(ctx.destination)` and any other game code is unaffected.
+ *
+ * HTML Media (`<audio>`/`<video>`): override `HTMLMediaElement.prototype.muted`
+ * to record the game's intended state, but write `true` to the underlying element
+ * whenever the SDK is muted. Tracked elements come from three sources:
+ *  1. Pre-existing DOM media (`querySelectorAll`)
+ *  2. `new Audio()` constructor shim (covers detached SFX)
+ *  3. MutationObserver for any media added to the DOM later (covers innerHTML,
+ *     framework rendering, createElement + append, etc.)
+ */
+declare class AudioManager extends WavedashManager {
+    private _isMuted;
+    private contexts;
+    private elements;
+    private intendedMuted;
+    private originalAudioContext;
+    private originalWebKitAudioContext;
+    private originalAudio;
+    private originalMutedDescriptor;
+    private mutationObserver;
+    constructor(sdk: WavedashSDK);
+    isMuted(): boolean;
+    /**
+     * Ask the host to mute (true) or unmute (false). Resolves to `true` if the
+     * host applied the change, `false` otherwise — notably, the host rejects an
+     * unmute when the user muted the game from the Wavedash UI, so games can't
+     * override an explicit user mute. The resulting state arrives via the usual
+     * MUTE_CHANGED broadcast, so `isMuted()` updates independently of this result.
+     */
+    requestMute(muted: boolean): Promise<boolean>;
+    /**
+     * Toggle mute. Like `requestMute`, the host may reject the unmute half of a
+     * toggle if the user muted from the Wavedash UI. Resolves to `true` if the
+     * host applied the change.
+     */
+    toggleMute(): Promise<boolean>;
+    private handleMute;
+    /**
+     * Track a media element and (if SDK is currently muted) silence it.
+     * Idempotent — safe to call multiple times for the same element.
+     */
+    private trackElement;
+    private installShims;
+    private shimAudioContextClass;
+    destroy(): void;
+}
+
 /**
  * SDK-to-Engine Events
  *
@@ -91,6 +161,8 @@ type UpsertedLeaderboardEntry = FunctionReturnType<typeof api.sdk.leaderboards.u
     userId: GenericId<"users">;
     username: string;
     userAvatarUrl?: string;
+    submittedScore: number;
+    submittedRank: number;
 };
 type WavedashEvent = (typeof WavedashEvents)[keyof typeof WavedashEvents];
 interface WavedashConfig {
@@ -260,18 +332,234 @@ interface P2PConfig {
 }
 
 /**
- * Base class for SDK managers. Provides the shared `sdk` reference and a
- * default no-op `destroy()` so the SDK can safely iterate every manager
- * during teardown without each one having to define an empty stub.
+ * File system service
+ * Utilities for syncing local IndexedDB files with remote storage.
  *
- * Override `destroy()` in any manager that owns ongoing state — Convex
- * subscriptions, intervals, peer connections, monkey-patched globals, etc.
- * — to make sure that state is released when the SDK is torn down.
+ * Exposes a specific remote folder for the game to save user-specific files to.
+ * TODO: Extend this to game-level assets as well.
  */
-declare abstract class WavedashManager {
-    protected sdk: WavedashSDK;
+
+declare class FileSystemManager extends WavedashManager {
+    private remoteStorageOrigin;
+    constructor(sdk: WavedashSDK);
+    /**
+     * Converts a local filesystem path into a full R2 object key.
+     * Normalizes the Unity persistentDataPath and prepends the R2 prefix.
+     */
+    private toRemoteKey;
+    /**
+     * Converts a full R2 object key back into the local filesystem path
+     * the engine expects. Inverse of toRemoteKey.
+     */
+    private toLocalPath;
+    /**
+     * Uploads a local file to remote storage
+     * @param filePath - The path of the local file to upload
+     * @returns The path of the remote file that the local file was uploaded to
+     */
+    uploadRemoteFile(filePath: string): Promise<string>;
+    /**
+     * Deletes a remote file from storage
+     * @param filePath - The path of the remote file to delete
+     * @returns The path of the remote file that was deleted
+     */
+    deleteRemoteFile(filePath: string): Promise<string>;
+    /**
+     * Downloads a remote file to a local location.
+     * Throws on failure; the error message is the server's HTTP status (e.g. "404 (Not Found)")
+     * or a network-level description if the server didn't respond. See also: {@link remoteFileExists}
+     * @param filePath - The path of the remote file to download
+     * @returns The path of the local file that the remote file was downloaded to
+     */
+    downloadRemoteFile(filePath: string): Promise<string>;
+    /**
+     * Checks whether a remote file exists by issuing a HEAD request.
+     * Does NOT throw for the "file does not exist" case — returns false.
+     * Throws only for real errors (network failure, auth failure, server error).
+     * @param filePath - The path of the remote file to check
+     * @returns true if the remote file exists, false otherwise
+     */
+    remoteFileExists(filePath: string): Promise<boolean>;
+    /**
+     * Lists each file in a remote directory, including its subdirectories.
+     * Returns only file paths, no directory paths.
+     * An empty or non-existent directory returns an empty array — not an error.
+     * @param path - The path of the remote directory to list
+     * @returns A list of metadata for each file in the remote directory
+     */
+    listRemoteDirectory(path: string): Promise<RemoteFileMetadata[]>;
+    downloadRemoteDirectory(path: string): Promise<string>;
+    writeLocalFile(filePath: string, data: Uint8Array): Promise<boolean>;
+    readLocalFile(filePath: string): Promise<Uint8Array | null>;
+    upload(presignedUploadUrl: string, filePath: string): Promise<boolean>;
+    download(url: string, filePath: string): Promise<void>;
+    private getRemoteStorageOrigin;
+    private getRemoteStorageUrl;
+    private uploadFromIndexedDb;
+    private uploadFromFS;
+    private readLocalFileBlob;
+}
+
+/**
+ * Friends service
+ *
+ * Implements friend-related methods for the Wavedash SDK
+ */
+
+declare class FriendsManager extends WavedashManager {
+    private userCache;
+    private leaderboardPageUserCache;
+    constructor(sdk: WavedashSDK);
+    /**
+     * Returns CDN URL with size transformation for a cached user's avatar.
+     * @param userId - The user ID to get the avatar URL for
+     * @param size - Pixel size for width and height. Use a value from
+     *   `AvatarSize` (SMALL=64, MEDIUM=128, LARGE=256) or any custom pixel size.
+     * @returns CDN URL with size transformation, or null if user not cached or has no avatar
+     */
+    getUserAvatarUrl(userId: GenericId<"users">, size?: number): string | null;
+    /**
+     * Returns the cached username for a given user ID
+     * @param userId - The user ID to get the username for
+     * @returns The username, or null if user not cached
+     */
+    getUsername(userId: GenericId<"users">): string | null;
+    /**
+     * List all friends for the logged in user
+     * @returns Array<{
+     *   avatarUrl?: string;
+     *   isOnline: boolean;
+     *   userId: Id<"users">;
+     *   username: string;
+     * }>
+     */
+    listFriends(): Promise<Friend[]>;
+}
+
+/**
+ * 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 extends WavedashManager {
+    private _isFullscreen;
+    private listeners;
+    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;
+}
+
+declare class GameEventManager extends WavedashManager {
+    private eventQueue;
     constructor(sdk: WavedashSDK);
+    notifyGame(event: WavedashEvent, payload: string | number | object): void;
+    private sendGameEvent;
+    flushEventQueue(): void;
+}
+
+/**
+ * Heartbeat service
+ *
+ * Polls connection state and allows the game to update rich user presence
+ * Lets the game know if backend connection ever changes.
+ * Lets the game update userPresence in the backend
+ */
+
+declare class HeartbeatManager extends WavedashManager {
+    private deviceFingerprint;
+    private deviceFingerprintReady;
+    private testConnectionInterval;
+    private heartbeatInterval;
+    private gamepadPollInterval;
+    private inactivityTimeout;
+    private isConnected;
+    private sentDisconnectedEvent;
+    private disconnectedAt;
+    private lastHeartbeatTime;
+    private lastInputResetAt;
+    private heartbeatInFlight;
+    private isFirstTick;
+    private readonly TEST_CONNECTION_INTERVAL_MS;
+    private readonly DISCONNECTED_TIMEOUT_MS;
+    private readonly INACTIVITY_TIMEOUT_MS;
+    private readonly INPUT_THROTTLE_MS;
+    private readonly GAMEPAD_POLL_INTERVAL_MS;
+    private readonly GAMEPAD_AXIS_DEADZONE;
+    private cachedPresenceData;
+    constructor(sdk: WavedashSDK);
+    /**
+     * Start (or refresh) the heartbeat. Idempotent: if intervals are already
+     * running this just reschedules the inactivity timer. No-op if the game
+     * hasn't loaded yet or the tab is hidden.
+     */
+    start(): void;
+    /** Stop the heartbeat and clear the inactivity timer. Idempotent. */
+    stop(): void;
+    /**
+     * Updates user presence in the backend.
+     * @param data - Data to send to the backend
+     * @returns true if the presence was updated successfully
+     */
+    updateUserPresence(data: Record<string, string | number | boolean | null>): Promise<boolean>;
+    isCurrentlyConnected(): boolean;
+    /** Full teardown — stops intervals and removes all listeners */
     destroy(): void;
+    private tickHeartbeat;
+    private sendHeartbeat;
+    private handleVisibilityChange;
+    private handleUserInput;
+    /**
+     * Polls connected gamepads; any pressed button or out-of-deadzone axis
+     * counts as user activity and (re)starts the heartbeat.
+     */
+    private pollGamepads;
+    /**
+     * Tests the connection to the backend
+     */
+    private testConnection;
+}
+
+/**
+ * Leaderboard service
+ *
+ * Implements each of the leaderboard methods of the Wavedash SDK
+ */
+
+declare class LeaderboardManager extends WavedashManager {
+    private leaderboardCache;
+    constructor(sdk: WavedashSDK);
+    getLeaderboard(name: string): Promise<Leaderboard>;
+    getOrCreateLeaderboard(name: string, sortOrder: LeaderboardSortOrder, displayType: LeaderboardDisplayType): Promise<Leaderboard>;
+    getLeaderboardEntryCount(leaderboardId: GenericId<"leaderboards">): number;
+    getMyLeaderboardEntries(leaderboardId: GenericId<"leaderboards">): Promise<LeaderboardEntries>;
+    listLeaderboardEntriesAroundUser(leaderboardId: GenericId<"leaderboards">, countAhead: number, countBehind: number, friendsOnly?: boolean): Promise<LeaderboardEntries>;
+    listLeaderboardEntries(leaderboardId: GenericId<"leaderboards">, offset: number, limit: number, friendsOnly?: boolean): Promise<LeaderboardEntries>;
+    uploadLeaderboardScore(leaderboardId: GenericId<"leaderboards">, score: number, keepBest: boolean, ugcId?: GenericId<"userGeneratedContent">): Promise<UpsertedLeaderboardEntry>;
+    private updateCachedTotalEntries;
 }
 
 /**
@@ -350,121 +638,36 @@ declare class LobbyManager extends WavedashManager {
     destroy(): void;
     private throttledSetMetadata;
     private setMetadata;
-    /**
-     * Process user updates and emit individual user events
-     * @param newUsers - The updated list of lobby users
-     */
-    private processUserUpdates;
-    private processMessageUpdates;
-    private processInviteUpdates;
-    /**
-     * Update P2P connections when lobby membership changes
-     * @param newUsers - The updated list of lobby users
-     */
-    private updateP2PConnections;
-}
-
-/**
- * File system service
- * Utilities for syncing local IndexedDB files with remote storage.
- *
- * Exposes a specific remote folder for the game to save user-specific files to.
- * TODO: Extend this to game-level assets as well.
- */
-
-declare class FileSystemManager extends WavedashManager {
-    private remoteStorageOrigin;
-    constructor(sdk: WavedashSDK);
-    /**
-     * Converts a local filesystem path into a full R2 object key.
-     * Normalizes the Unity persistentDataPath and prepends the R2 prefix.
-     */
-    private toRemoteKey;
-    /**
-     * Converts a full R2 object key back into the local filesystem path
-     * the engine expects. Inverse of toRemoteKey.
-     */
-    private toLocalPath;
-    /**
-     * Uploads a local file to remote storage
-     * @param filePath - The path of the local file to upload
-     * @returns The path of the remote file that the local file was uploaded to
-     */
-    uploadRemoteFile(filePath: string): Promise<string>;
-    /**
-     * Deletes a remote file from storage
-     * @param filePath - The path of the remote file to delete
-     * @returns The path of the remote file that was deleted
-     */
-    deleteRemoteFile(filePath: string): Promise<string>;
-    /**
-     * Downloads a remote file to a local location.
-     * Throws on failure; the error message is the server's HTTP status (e.g. "404 (Not Found)")
-     * or a network-level description if the server didn't respond. See also: {@link remoteFileExists}
-     * @param filePath - The path of the remote file to download
-     * @returns The path of the local file that the remote file was downloaded to
-     */
-    downloadRemoteFile(filePath: string): Promise<string>;
-    /**
-     * Checks whether a remote file exists by issuing a HEAD request.
-     * Does NOT throw for the "file does not exist" case — returns false.
-     * Throws only for real errors (network failure, auth failure, server error).
-     * @param filePath - The path of the remote file to check
-     * @returns true if the remote file exists, false otherwise
-     */
-    remoteFileExists(filePath: string): Promise<boolean>;
-    /**
-     * Lists each file in a remote directory, including its subdirectories.
-     * Returns only file paths, no directory paths.
-     * An empty or non-existent directory returns an empty array — not an error.
-     * @param path - The path of the remote directory to list
-     * @returns A list of metadata for each file in the remote directory
-     */
-    listRemoteDirectory(path: string): Promise<RemoteFileMetadata[]>;
-    downloadRemoteDirectory(path: string): Promise<string>;
-    writeLocalFile(filePath: string, data: Uint8Array): Promise<boolean>;
-    readLocalFile(filePath: string): Promise<Uint8Array | null>;
-    upload(presignedUploadUrl: string, filePath: string): Promise<boolean>;
-    download(url: string, filePath: string): Promise<void>;
-    private getRemoteStorageOrigin;
-    private getRemoteStorageUrl;
-    private uploadFromIndexedDb;
-    private uploadFromFS;
-    private readLocalFileBlob;
-}
-
-/**
- * UGC service
- *
- * Implements each of the user generated content methods of the Wavedash SDK
- */
-
-declare class UGCManager extends WavedashManager {
-    constructor(sdk: WavedashSDK);
-    createUGCItem(ugcType: UGCType, title?: string, description?: string, visibility?: UGCVisibility, filePath?: string): Promise<GenericId<"userGeneratedContent">>;
-    updateUGCItem(ugcId: GenericId<"userGeneratedContent">, updates?: UpdateUGCItemArgs): Promise<GenericId<"userGeneratedContent">>;
-    deleteUGCItem(ugcId: GenericId<"userGeneratedContent">): Promise<GenericId<"userGeneratedContent">>;
-    downloadUGCItem(ugcId: GenericId<"userGeneratedContent">, filePath: string): Promise<GenericId<"userGeneratedContent">>;
-    listUGCItems(args?: ListUGCItemsArgs): Promise<PaginatedUGCItems>;
+    /**
+     * Process user updates and emit individual user events
+     * @param newUsers - The updated list of lobby users
+     */
+    private processUserUpdates;
+    private processMessageUpdates;
+    private processInviteUpdates;
+    /**
+     * Update P2P connections when lobby membership changes
+     * @param newUsers - The updated list of lobby users
+     */
+    private updateP2PConnections;
 }
 
 /**
- * Leaderboard service
+ * OverlayManager
  *
- * Implements each of the leaderboard methods of the Wavedash SDK
+ * 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 LeaderboardManager extends WavedashManager {
-    private leaderboardCache;
+declare class OverlayManager extends WavedashManager {
     constructor(sdk: WavedashSDK);
-    getLeaderboard(name: string): Promise<Leaderboard>;
-    getOrCreateLeaderboard(name: string, sortOrder: LeaderboardSortOrder, displayType: LeaderboardDisplayType): Promise<Leaderboard>;
-    getLeaderboardEntryCount(leaderboardId: GenericId<"leaderboards">): number;
-    getMyLeaderboardEntries(leaderboardId: GenericId<"leaderboards">): Promise<LeaderboardEntries>;
-    listLeaderboardEntriesAroundUser(leaderboardId: GenericId<"leaderboards">, countAhead: number, countBehind: number, friendsOnly?: boolean): Promise<LeaderboardEntries>;
-    listLeaderboardEntries(leaderboardId: GenericId<"leaderboards">, offset: number, limit: number, friendsOnly?: boolean): Promise<LeaderboardEntries>;
-    uploadLeaderboardScore(leaderboardId: GenericId<"leaderboards">, score: number, keepBest: boolean, ugcId?: GenericId<"userGeneratedContent">): Promise<UpsertedLeaderboardEntry>;
-    private updateCachedTotalEntries;
+    toggleOverlay(): void;
+    takeFocus(): void;
+    private handleKeyDown;
 }
 
 /**
@@ -584,6 +787,12 @@ declare class P2PManager extends WavedashManager {
     private decodeBinaryMessage;
 }
 
+declare class PaidContentManager extends WavedashManager {
+    isEntitled(contentId: string): Promise<boolean>;
+    getEntitlements(): Promise<string[]>;
+    triggerPaywall(contentIdentifier: string): Promise<boolean>;
+}
+
 declare class StatsManager extends WavedashManager {
     private stats;
     private unlockedAchievements;
@@ -613,205 +822,18 @@ declare class StatsManager extends WavedashManager {
 }
 
 /**
- * Heartbeat service
- *
- * Polls connection state and allows the game to update rich user presence
- * Lets the game know if backend connection ever changes.
- * Lets the game update userPresence in the backend
- */
-
-declare class HeartbeatManager extends WavedashManager {
-    private deviceFingerprint;
-    private deviceFingerprintReady;
-    private testConnectionInterval;
-    private heartbeatInterval;
-    private gamepadPollInterval;
-    private inactivityTimeout;
-    private isConnected;
-    private sentDisconnectedEvent;
-    private disconnectedAt;
-    private lastHeartbeatTime;
-    private lastInputResetAt;
-    private heartbeatInFlight;
-    private isFirstTick;
-    private readonly TEST_CONNECTION_INTERVAL_MS;
-    private readonly DISCONNECTED_TIMEOUT_MS;
-    private readonly INACTIVITY_TIMEOUT_MS;
-    private readonly INPUT_THROTTLE_MS;
-    private readonly GAMEPAD_POLL_INTERVAL_MS;
-    private readonly GAMEPAD_AXIS_DEADZONE;
-    private cachedPresenceData;
-    constructor(sdk: WavedashSDK);
-    /**
-     * Start (or refresh) the heartbeat. Idempotent: if intervals are already
-     * running this just reschedules the inactivity timer. No-op if the game
-     * hasn't loaded yet or the tab is hidden.
-     */
-    start(): void;
-    /** Stop the heartbeat and clear the inactivity timer. Idempotent. */
-    stop(): void;
-    /**
-     * Updates user presence in the backend.
-     * @param data - Data to send to the backend
-     * @returns true if the presence was updated successfully
-     */
-    updateUserPresence(data: Record<string, string | number | boolean | null>): Promise<boolean>;
-    isCurrentlyConnected(): boolean;
-    /** Full teardown — stops intervals and removes all listeners */
-    destroy(): void;
-    private tickHeartbeat;
-    private sendHeartbeat;
-    private handleVisibilityChange;
-    private handleUserInput;
-    /**
-     * Polls connected gamepads; any pressed button or out-of-deadzone axis
-     * counts as user activity and (re)starts the heartbeat.
-     */
-    private pollGamepads;
-    /**
-     * Tests the connection to the backend
-     */
-    private testConnection;
-}
-
-declare class GameEventManager extends WavedashManager {
-    private eventQueue;
-    constructor(sdk: WavedashSDK);
-    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 extends WavedashManager {
-    private _isFullscreen;
-    private listeners;
-    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 extends WavedashManager {
-    constructor(sdk: WavedashSDK);
-    toggleOverlay(): void;
-    takeFocus(): void;
-    private handleKeyDown;
-}
-
-/**
- * AudioManager
- *
- * Mutes & unmutes the game in response to MUTE_CHANGED iframe messages, without
- * the game needing to know anything about it.
- *
- * Web Audio: subclass `AudioContext` so `ctx.destination` resolves to a master
- * GainNode that we control. The master gain wires to the real native destination,
- * so `node.connect(ctx.destination)` and any other game code is unaffected.
- *
- * HTML Media (`<audio>`/`<video>`): override `HTMLMediaElement.prototype.muted`
- * to record the game's intended state, but write `true` to the underlying element
- * whenever the SDK is muted. Tracked elements come from three sources:
- *  1. Pre-existing DOM media (`querySelectorAll`)
- *  2. `new Audio()` constructor shim (covers detached SFX)
- *  3. MutationObserver for any media added to the DOM later (covers innerHTML,
- *     framework rendering, createElement + append, etc.)
- */
-declare class AudioManager extends WavedashManager {
-    private _isMuted;
-    private contexts;
-    private elements;
-    private intendedMuted;
-    private originalAudioContext;
-    private originalWebKitAudioContext;
-    private originalAudio;
-    private originalMutedDescriptor;
-    private mutationObserver;
-    constructor(sdk: WavedashSDK);
-    isMuted(): boolean;
-    private handleMute;
-    /**
-     * Track a media element and (if SDK is currently muted) silence it.
-     * Idempotent — safe to call multiple times for the same element.
-     */
-    private trackElement;
-    private installShims;
-    private shimAudioContextClass;
-    destroy(): void;
-}
-
-/**
- * Friends service
+ * UGC service
  *
- * Implements friend-related methods for the Wavedash SDK
+ * Implements each of the user generated content methods of the Wavedash SDK
  */
 
-declare class FriendsManager extends WavedashManager {
-    private userCache;
-    private leaderboardPageUserCache;
+declare class UGCManager extends WavedashManager {
     constructor(sdk: WavedashSDK);
-    /**
-     * Returns CDN URL with size transformation for a cached user's avatar.
-     * @param userId - The user ID to get the avatar URL for
-     * @param size - Pixel size for width and height. Use a value from
-     *   `AvatarSize` (SMALL=64, MEDIUM=128, LARGE=256) or any custom pixel size.
-     * @returns CDN URL with size transformation, or null if user not cached or has no avatar
-     */
-    getUserAvatarUrl(userId: GenericId<"users">, size?: number): string | null;
-    /**
-     * Returns the cached username for a given user ID
-     * @param userId - The user ID to get the username for
-     * @returns The username, or null if user not cached
-     */
-    getUsername(userId: GenericId<"users">): string | null;
-    /**
-     * List all friends for the logged in user
-     * @returns Array<{
-     *   avatarUrl?: string;
-     *   isOnline: boolean;
-     *   userId: Id<"users">;
-     *   username: string;
-     * }>
-     */
-    listFriends(): Promise<Friend[]>;
+    createUGCItem(ugcType: UGCType, title?: string, description?: string, visibility?: UGCVisibility, filePath?: string): Promise<GenericId<"userGeneratedContent">>;
+    updateUGCItem(ugcId: GenericId<"userGeneratedContent">, updates?: UpdateUGCItemArgs): Promise<GenericId<"userGeneratedContent">>;
+    deleteUGCItem(ugcId: GenericId<"userGeneratedContent">): Promise<GenericId<"userGeneratedContent">>;
+    downloadUGCItem(ugcId: GenericId<"userGeneratedContent">, filePath: string): Promise<GenericId<"userGeneratedContent">>;
+    listUGCItems(args?: ListUGCItemsArgs): Promise<PaginatedUGCItems>;
 }
 
 /**
@@ -837,7 +859,7 @@ declare class IFrameMessenger {
     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]>;
+    requestFromParent<T extends keyof IFrameEventPayloadMap>(requestType: T, data?: Record<string, unknown>, timeoutMs?: number): Promise<IFrameEventPayloadMap[T]>;
 }
 
 /**
@@ -965,6 +987,7 @@ declare class WavedashSDK extends EventTarget {
     fullscreenManager: FullscreenManager;
     overlayManager: OverlayManager;
     audioManager: AudioManager;
+    paidContentManager: PaidContentManager;
     private managers;
     private gameplayJwt;
     private gameplayJwtPromise;
@@ -1021,6 +1044,22 @@ declare class WavedashSDK extends EventTarget {
      * a user gesture handler when entering fullscreen.
      */
     toggleFullscreen(): Promise<boolean>;
+    /**
+     * Whether the game is currently muted. Mirrored from the Wavedash host page,
+     * which owns the mute control so its UI button and the game stay in sync.
+     */
+    isMuted(): boolean;
+    /**
+     * Ask the host to mute (true) or unmute (false). Resolves to `true` if the
+     * change was applied, `false` if it was rejected — the host won't let the
+     * game unmute when the user has muted from the Wavedash UI.
+     */
+    requestMute(muted: boolean): Promise<boolean>;
+    /**
+     * Toggle mute. Resolves to `true` if the change was applied, `false` if it
+     * was rejected (e.g. trying to unmute over an explicit user mute).
+     */
+    toggleMute(): Promise<boolean>;
     getUser(): SDKUser;
     /**
      * Get a username. Returns the logged in user's username if no ID is passed.
@@ -1228,6 +1267,31 @@ declare class WavedashSDK extends EventTarget {
     sendLobbyMessage(lobbyId: GenericId<"lobbies">, message: string): boolean;
     inviteUserToLobby(lobbyId: GenericId<"lobbies">, userId: GenericId<"users">): Promise<WavedashResponse<boolean>>;
     getLobbyInviteLink(copyToClipboard?: boolean): Promise<WavedashResponse<string>>;
+    /**
+     * Returns true if the player owns the given paid content for this game.
+     * Reads the `entitlements` claim from the gameplay JWT — this is a UX hint, not a
+     * security check. The builds server re-verifies the JWT signature and gates
+     * paid asset bytes on every request, so a tampered client return value
+     * doesn't actually unlock anything. Pair with triggerPaywall() to drive
+     * in-game UI.
+     */
+    isEntitled_EXPERIMENTAL(contentId: string): Promise<WavedashResponse<boolean>>;
+    /**
+     * Returns the full list of paid-content IDs the player owns for this game.
+     * Reads the `entitlements` claim from the gameplay JWT — this is a UX hint,
+     * not a security check (see {@link isEntitled_EXPERIMENTAL}). Useful
+     * for access gating multiple items at once without a call per content ID.
+     */
+    getEntitlements_EXPERIMENTAL(): Promise<WavedashResponse<string[]>>;
+    /**
+     * Trigger the Wavedash-rendered paywall flow for the given content. Resolves
+     * immediately with data `true` if the player already owns it; otherwise
+     * opens the modal and resolves with whether the user completed the purchase.
+     * After a successful purchase the JWT is refreshed automatically so a
+     * subsequent resource fetch is authenticated with the new purchase, and isEntitled
+     * will return true if the purchase was successful.
+     */
+    triggerPaywall_EXPERIMENTAL(contentIdentifier: string): Promise<WavedashResponse<boolean>>;
     /**
      * Updates rich user presence so friends can see what the player is doing in game.
      * Supported keys:
@@ -1245,17 +1309,15 @@ declare class WavedashSDK extends EventTarget {
     private apiCall;
     private apiCallSync;
     /**
-     * Fetches (or returns cached) gameplay JWT. Callers outside of Convex's
-     * setAuth should use {@link ensureGameplayJwt} instead; this method is the
-     * fetcher wired into `ConvexClient.setAuth` and honors `forceRefresh` so the
-     * server can invalidate a stale token.
-     *
-     * Same-origin POST to /auth/refresh on the play domain — the
-     * gameplaySession cookie set by the play server during playKey exchange
-     * authenticates the request, so no cross-origin credentials handling needed.
+     * Fetcher wired into `ConvexClient.setAuth`; other callers use
+     * {@link ensureGameplayJwt}. Same-origin POST to /auth/refresh, authenticated
+     * by the gameplaySession cookie.
      *
-     * Concurrent callers share a single in-flight fetch to avoid duplicate
-     * refresh round-trips.
+     * Concurrent callers share one in-flight fetch. A forced refresh instead
+     * serializes behind any in-flight fetch (it may predate the event that
+     * required it, e.g. a purchase) and becomes the current promise; only the
+     * current promise notifies the parent, so a superseded refresh can't
+     * broadcast a stale token
      */
     private getAuthToken;
     /**
@@ -1263,7 +1325,7 @@ declare class WavedashSDK extends EventTarget {
      * already running (e.g. from Convex's initial setAuth). Use this anywhere
      * you need to authenticate a request outside of the Convex client.
      */
-    ensureGameplayJwt(): Promise<string>;
+    ensureGameplayJwt(forceRefresh?: boolean): Promise<string>;
     /**
      * Tear down every manager. Called on the parent's `END_SESSION` signal
      */