# PlayDrop client SDK declarations

Generated from the SDK's public declarations (`packages/sdk/src/types.ts`) and the types they reference; do not edit by hand. `const sdk = await playdrop.init()` returns `PlaydropSDK`. Guides: https://www.playdrop.ai/create/learn/sdk. Types from `@playdrop/types` that these declarations use are in the shared types (get_documentation topic `shared-types`, https://www.playdrop.ai/docs-markdown/en/shared-types.md).

## packages/sdk/src/types.ts

```ts
export type Deployment = "dev" | "live";

export type Platform = "web" | "native";

export type ConnectionStatus = "offline" | "connecting" | "online";

export type DeviceCategory = "desktop" | "tablet" | "phone";

export type DeviceOrientation = "portrait" | "landscape";

export type SessionMode = "dev" | "play";

export type HostPhase = "preview" | "play" | "editor";

export type HostPauseReason =
  | "tab_hidden"
  | "auth_prompt"
  | "purchase_flow"
  | "host_overlay"
  | "detail_hidden"
  | "route_change"
  | "native_background";

export type HostAudioPolicyReason = HostPauseReason | "user_preference";

export type ControllerAvailability = "ready" | "blocked" | "unsupported";

export type LoadingState =
  | { status: "loading"; progress?: number; message?: string }
  | { status: "ready"; editor?: true }
  | { status: "error"; message?: string };

/** `sdk.social.sendChallenge()` options: what the card shows besides the player's recorded best. */
export interface SendChallengeOptions {
  /** Identity of the recorded best, such as its score. Reuse it on Retry; change it for a different best. */
  operationKey?: string;
  /** The card's text, at most 80 characters, shown as written. Omitted: "Beat my <score> in <game>" in each reader's language. */
  text?: string;
  /** Opaque base64url launch payload, at most 256 characters: the game opens with it from the card. */
  payload?: string;
  /** A picture or short animation of the run: GIF, JPEG, PNG or WebP up to 8 MiB, at most 8 frames, as on turn cards. */
  image?: Blob;
}

export interface SendChallengeResult {
  /** The player shared a score link outside PlayDrop; recipients become known only on acceptance. */
  sharedLink?: true;
  /** The friends the challenge went to: [] when the player closed the picker (and in iMessage). */
  recipients: SocialFriend[];
  /** Recipients still missed; a retry of the same operation reaches only these friends. */
  failed: { userId: number; displayName: string; retryable: boolean }[];
  /** Fresh standings; when absent, only confirm that the score was posted. */
  standings?: import("@playdrop/types").ChallengeEntry[];
}

export interface AppMetadata {
  id: number | null;
  name: string | null;
  displayName: string | null;
  description: string | null;
  emoji: string | null;
  accentColor: string | null;
  type: AppType | null;
  surfaceTargets: AppSurface[];
  authMode: AppAuthMode;
  controllerMode: AppControllerMode;
  previewable: boolean;
  editorSupported: boolean;
  /** Semantic version string (e.g., "1.2.3") for multiplayer room isolation */
  version: string | null;
  assetSpecSupport: AppMetadataAssetSpecSupport[];
  routes?: {
    detailUrl: string;
    playUrl: string;
    previewUrl: string;
    devUrl: string;
    devPreviewUrl: string;
  } | null;
}

export interface DeviceInputs {
  keyboard: boolean;
  mouse: boolean;
  touch: boolean;
}

export interface DeviceGamepad {
  key: string;
  index: number;
  id: string;
  mapping: string;
}

export interface DeviceControllerState {
  availability: ControllerAvailability;
  gamepads: DeviceGamepad[];
}

/**
 * Read-only controller snapshot for one local player, in browser standard order and ranges.
 * `menu` and `home` belong to PlayDrop (pause) and always read released.
 */
export interface PlaydropGamepad {
  /** Verified public profile of the assigned phone player, or null for an anonymous or unidentified controller. */
  readonly player: Readonly<import("@playdrop/types").ControllerPlayer> | null;
  /** Identifies the device within this host session; never an account id. */
  key: string;
  playerIndex: number;
  connected: boolean;
  source: "physical" | "virtual";
  /** Display name, e.g. "Xbox Wireless Controller" or "Phone 1". */
  id: string;
  mapping: "standard";
  /** Controls this pad physically has; missing controls read neutral. */
  controls: readonly ControllerControlName[];
  /** Left x/y, right x/y in [-1, 1]. */
  axes: readonly number[];
  /** Seventeen buttons in standard order. */
  buttons: readonly { pressed: boolean; value: number }[];
  has(control: ControllerControlName): boolean;
  /** Prompt text for a positional button: "A", "Cross", "B" on Nintendo, or "South" when the layout is unknown. */
  label(button: ControllerButtonName): string;
}

export interface ControllerButtonEvent {
  playerIndex: number;
  button: ControllerButtonName;
  pressed: boolean;
}

export interface DeviceAPI {
  category: DeviceCategory;
  orientation: DeviceOrientation;
  inputs: DeviceInputs;
  controllerAvailability: ControllerAvailability;
  connectedGamepads: DeviceGamepad[];
  readonly localPlayers: readonly LocalPlayerSlot[];
  onLocalPlayersChange(cb: (players: readonly LocalPlayerSlot[]) => void): () => void;
  onControllerChange(cb: (state: DeviceControllerState) => void): () => void;
  /**
   * Opt in to PlayDrop controller input (physical controllers and phones). Call once after `init()`; repeated
   * calls return the same handshake. Rejects with `controller_input_unavailable` when the host refuses, or
   * `controller_input_timeout` after 5 seconds; the game keeps running without controller input.
   * Read controllers only through this API: never call `navigator.getGamepads()`.
   *
   * @example
   * ```ts
   * await playdrop.device.enableControllerInput();
   * const stop = playdrop.device.onButton(({ playerIndex, button, pressed }) => {
   *   if (button === "south" && pressed) jump(playerIndex);
   * });
   * // In the game loop, playerIndex 0 is P1:
   * const pad = playdrop.device.gamepad(0);
   * if (pad?.connected) move(pad.axes[0], pad.axes[1]);
   * ```
   */
  enableControllerInput(): Promise<void>;
  /** Latest snapshot for a local player (0 = P1); `null` when unassigned, or before opting in on hosts that bridge input. */
  gamepad(playerIndex: number): PlaydropGamepad | null;
  /** Ordered press/release transitions, after the snapshot updates. Subscribing never reports buttons already held. */
  onButton(cb: (event: ControllerButtonEvent) => void): () => void;
}

export interface AudioPolicyState {
  enabled: boolean;
  reason: HostAudioPolicyReason;
  /** Host WebAudio master volume; omitted by older hosts means full volume. */
  volume?: number;
}

export interface HostShareOptions {
  /** Optional text for the platform share sheet. */
  text?: string;
  /** Opaque base64url launch payload, at most 256 characters. Never put credentials here. */
  payload?: string;
  /**
   * GIF, JPEG, PNG or WebP Blob up to 8 MiB, attached to the platform share sheet. Hosts that cannot attach
   * images share the link only. Create the Blob before the player's tap so the share keeps that activation.
   */
  image?: Blob;
  /**
   * MP4 Blob, at most 15 seconds and 20 MB (20,000,000 bytes). Mutually exclusive with image.
   * Recommended: H.264/AAC, 1080p, 16:9 / 9:16 / 1:1. Prepare before the player's tap.
   * Invalid media and unsupported hosts reject; a video is never silently replaced with a link.
   */
  video?: Blob;
  /**
   * Share a one-use invite link instead of the game page: whoever accepts it first becomes this player's PlayDrop friend
   * and opens the game with `payload`, as from a Chat card (the `text`, at most 80 characters, is that card's title).
   * Requires `text` and `payload`. Hosts without invite links reject with `host_share_invite_unsupported`; share the
   * plain link then. The link opens a PlayDrop page, so the payload itself is never in it.
   */
  invite?: boolean;
}

export interface HostShowGamesOptions {
  /** 1 to 3 distinct public games as "@creator/name" (the public URL path without the leading slash). */
  games: string[];
}

export interface HostShowGamesResult {
  /** "played": the player chose a game; the host replaces this game right after resolving. */
  status: "played" | "dismissed";
  /** The chosen "@creator/name" when status is "played". */
  game?: string;
}

export interface HostAPI {
  /**
   * Player language selected by the host at launch, limited to the original ten languages ("en", "fr", "de", "ja",
   * "ko", "es", "pt-BR", "id", "zh-Hant", "zh-Hans"); any other language reads "en". Prefer `language`.
   * Throws host_locale_unavailable on older hosts.
   */
  readonly locale: string;
  /**
   * Player language selected by the host at launch, among every PlayDrop language (the ten of `locale` plus "it",
   * "pl", "nl", "sv", "nb", "fi", "tr", "th", "vi", "ar"). Hosts that predate it give `locale`.
   * Throws host_locale_unavailable when the host gives neither.
   */
  readonly language: string;
  /** Signal that the designed first screen is rendered and capture hooks, if any, are installed. */
  ready(): void;
  /** Signal that the optional game-owned Editor is usable in the editor phase. */
  editorReady(): void;
  /** @deprecated Use ready() instead. */
  firstFrameReady(): void;
  /** @deprecated Use ready() instead. */
  setLoadingState(state: LoadingState): void;
  error(message?: string): void;
  deployment: Deployment;
  platform: Platform;
  sdkVersion: string;
  sdkBuild: number;
  mode: SessionMode;
  phase: HostPhase;
  isPaused: boolean;
  audioEnabled: boolean;
  /** Host permits gameplay audio, also during a hidden-tab pause. Local preferences may further restrict playback. */
  readonly audioAllowed: boolean;
  /** Viewport-corner bounds in CSS pixels. Union with hardware safe areas; null preserves legacy layout. */
  readonly reservedCorners: HostReservedCorners | null;
  onReservedCornersChange(cb: (corners: HostReservedCorners | null) => void): () => void;
  /** Subscribe to changes; read audioAllowed once after init for the initial state. */
  onAudioAllowedChange(cb: (allowed: boolean) => void): () => void;
  /** Untrusted game-defined payload from a shared launch. Authorize room access on the server. */
  readonly launchPayload: string | null;
  /**
   * `"imessage"` when the game runs inside an iMessage conversation, else null. Show only that conversation's match:
   * `launchPayload` resumes it; without one, start its invite (the first move, then `host.share({ invite: true })`).
   * Never show the game's home or other matches; PlayDrop closes the game once the turn is sent.
   */
  readonly conversation: "imessage" | null;
  /**
   * The validated friend whose direct chat opened the game (a DM Play, a card, a turn notification), after init; null
   * otherwise and on older hosts. Non-null means a DM launch (ASYNC-TURNS.md). `launchPayload`, when set, still picks the
   * match; without one, route to creation, then confirm via social.selectFriends({max:1}); never auto-create.
   */
  readonly launchFriend: SocialFriend | null;
  /**
   * The score challenge this launch plays, read after init: from a challenge card, a direct chat's Challenge tab or an
   * iMessage chat (CHALLENGES.md). `entries` are best first, `me` is this player's entry, `payload` the card's payload.
   * Null when playing on your own (then offer "Challenge friends" after a new best) and on older hosts.
   */
  readonly challenge: HostChallenge | null;
  /**
   * Share the game's public link from a player click or tap, with optional text, launch payload and image or video.
   * Custom URLs and other files are unsupported. Hosts without image support share the link alone;
   * hosts without video support reject with host_share_video_unsupported.
   * Image errors: invalid_host_share_image, host_share_image_type, host_share_image_too_large.
   */
  share(options?: HostShareOptions): Promise<void>;
  /**
   * Hint: start downloading a game the player may open next. One slot; a later call replaces it.
   * Resolves immediately; hosts that cannot preload ignore it. Throws only invalid_game_ref.
   */
  preloadGame(game: string): Promise<void>;
  /**
   * Show host-rendered cards for 1-3 other PlayDrop games (icon, title, subtitle, Info, Play). Call from normal
   * play after a player action or a natural break (e.g. game over). Pauses the game while open. The host takes
   * every title, image and link from PlayDrop; when the player taps Play it resolves "played" and then replaces
   * this game. Errors: invalid_game_ref, host_games_unavailable, host_games_in_progress, host_games_not_playing,
   * host_games_not_found (no ref is another public playable game), host_games_failed.
   *
   * @example
   * ```ts
   * const result = await sdk.host.showGames({ games: ["@playdrop/hangingout"] });
   * if (result.status === "dismissed") restartRound();
   * ```
   */
  showGames(options: HostShowGamesOptions): Promise<HostShowGamesResult>;
  /**
   * Ask the player to review this game (thumbs up or down, optional comment) in a PlayDrop window over the paused
   * game. Call at a natural break, e.g. after a win. PlayDrop decides whether it shows: at most once per player and
   * game, never to a player who already reviewed it or is signed out. Resolves immediately and never says whether
   * the window showed or what the player chose, so never tie a reward to it. Hosts without reviews ignore it.
   */
  requestReview(): Promise<void>;
  /** Studio can switch Editor and Playtest in the same frame; remount and signal readiness as needed. */
  onPhaseChange(cb: (phase: HostPhase) => void): () => void;
  onPause(cb: (reason: HostPauseReason) => void): () => void;
  onResume(cb: (reason: HostPauseReason) => void): () => void;
  onAudioPolicyChange(cb: (policy: AudioPolicyState) => void): () => void;
}

export interface ConnectionQualityMetrics {
  pingMs: number;
  jitterMs: number;
  interpDelayMs: number;
}

/** Compatibility clocks for existing games; networking uses the Colyseus client/room. */
export interface ConnectionAPI {
  getStatus(): ConnectionStatus;
  getQuality(): ConnectionQualityMetrics;
  /** Local Unix time in milliseconds. This does not synchronize with the game server. */
  serverNow(): number;
  /** Local Unix time minus the historical 120 ms interpolation delay. */
  renderTime(): number;
  onStatusChange(cb: (status: ConnectionStatus) => void): () => void;
  onQualityChange(cb: (quality: ConnectionQualityMetrics) => void): () => void;
}

export interface SharedLibraryInfo {
  packageName: string;
  version: string;
  entryUrl: string;
  loaded: boolean;
}

export interface ThreeLibraryInfo extends SharedLibraryInfo {
  packageName: "three";
  availableAddons: ReadonlyArray<string>;
  loadedAddons: ReadonlyArray<string>;
}

export interface AvatarLibraryInfo extends SharedLibraryInfo {
  packageName: "@playdrop/avatar";
}

export interface RapierLibraryInfo extends SharedLibraryInfo {
  packageName: "@dimforge/rapier3d-compat";
}

export interface NipplejsLibraryInfo extends SharedLibraryInfo {
  packageName: "nipplejs";
}

export interface PhaserLibraryInfo extends SharedLibraryInfo {
  packageName: "phaser";
}

export interface ColyseusLibraryInfo extends SharedLibraryInfo {
  packageName: "@colyseus/sdk";
}

export interface ThreeLoadOptions {
  addons?: ReadonlyArray<string>;
}

export type ThreeRuntime = typeof ThreeModule & Record<string, unknown>;

export type AvatarRuntime = typeof import("@playdrop/avatar");

export type RapierRuntime = typeof RapierModule;

export type NipplejsRuntime = typeof nipplejsModule;

export type PhaserRuntime = typeof PhaserModule;

export type ColyseusRuntime = typeof ColyseusModule;

export interface ThreeLibraryAPI {
  info(): ThreeLibraryInfo;
  load(options?: ThreeLoadOptions): Promise<ThreeRuntime>;
}

export interface AvatarLibraryAPI {
  info(): AvatarLibraryInfo;
  load(): Promise<AvatarRuntime>;
}

export interface RapierLibraryAPI {
  info(): RapierLibraryInfo;
  load(): Promise<RapierRuntime>;
}

export interface NipplejsLibraryAPI {
  info(): NipplejsLibraryInfo;
  load(): Promise<NipplejsRuntime>;
}

export interface PhaserLibraryAPI {
  info(): PhaserLibraryInfo;
  load(): Promise<PhaserRuntime>;
}

export interface ColyseusLibraryAPI {
  info(): ColyseusLibraryInfo;
  /** Load the SDK-pinned official Colyseus client. See MultiplayerAPI.getConnection for connection setup. */
  load(): Promise<ColyseusRuntime>;
}

export interface LibrariesAPI {
  three: ThreeLibraryAPI;
  avatar: AvatarLibraryAPI;
  rapier: RapierLibraryAPI;
  nipplejs: NipplejsLibraryAPI;
  phaser: PhaserLibraryAPI;
  colyseus: ColyseusLibraryAPI;
}

export interface AssetListOptions {
  limit?: number;
  offset?: number;
  category?: AssetCategory;
  subcategory?: string;
  assetSpec?: string;
  assetSpecOwner?: string;
  assetSpecName?: string;
  sort?: AssetListSort;
  containsCategory?: AssetCategory;
  containsSubcategory?: string;
  tags?: string[];
}

export type AssetReference = string;

export interface UploadBuiltInAssetVersionRequest {
  category: AssetCategory;
  subcategory: string;
  format: AssetFormat;
  visibility?: AssetVisibility;
  sourceKind?: AssetSourceKind;
  sourceAppVersionId?: number;
  sourceGenerationId?: string;
  tags?: string[];
  clearTags?: boolean;
  shopListed?: boolean;
  shopPriceCredits?: number;
  displayName?: string;
  description?: string;
  files: Array<{
    file: File | Blob;
    fieldName?: string;
    filename?: string;
  }>;
}

export interface UploadCustomAssetVersionRequest {
  assetSpec: string;
  visibility?: AssetVisibility;
  sourceKind?: AssetSourceKind;
  sourceAppVersionId?: number;
  sourceGenerationId?: string;
  tags?: string[];
  clearTags?: boolean;
  shopListed?: boolean;
  shopPriceCredits?: number;
  displayName?: string;
  description?: string;
  files: Array<{
    file: File | Blob;
    fieldName?: string;
    filename?: string;
  }>;
}

export type UploadAssetVersionRequest = UploadBuiltInAssetVersionRequest | UploadCustomAssetVersionRequest;

export interface AssetsCatalogAPI {
  listCategories(): Promise<AssetSubcategoryDefinition[]>;
  listPublic(options?: AssetListOptions): Promise<AssetListResponse>;
  listForCreator(creatorUsername: string, options?: AssetListOptions): Promise<AssetListResponse>;
  get(creatorUsername: string, assetName: string): Promise<AssetResponse>;
  listVersions(
    creatorUsername: string,
    assetName: string,
    options?: AssetListOptions,
  ): Promise<AssetVersionsListResponse>;
  createVersion(
    creatorUsername: string,
    assetName: string,
    request: UploadAssetVersionRequest,
  ): Promise<CreateAssetVersionResponse>;
  update(creatorUsername: string, assetName: string, request: UpdateAssetRequest): Promise<UpdateAssetResponse>;
  updateVersion(
    creatorUsername: string,
    assetName: string,
    revision: string | number,
    request: UpdateAssetVersionRequest,
  ): Promise<UpdateAssetVersionResponse>;
  deleteVersion(
    creatorUsername: string,
    assetName: string,
    revision: string | number,
  ): Promise<DeleteAssetVersionResponse>;
  delete(creatorUsername: string, assetName: string): Promise<DeleteAssetResponse>;
  downloadFile(
    creatorUsername: string,
    assetName: string,
    revision: string | number,
    options?: { role?: string },
  ): Promise<Blob>;
  downloadSource(
    creatorUsername: string,
    assetName: string,
    revision: string | number,
  ): Promise<{ blob: Blob; metadata: AssetSourceBundleResponse }>;
}

export interface AssetPacksCatalogAPI {
  listPublic(options?: AssetListOptions): Promise<AssetPackListResponse>;
  listForCreator(creatorUsername: string, options?: AssetListOptions): Promise<AssetPackListResponse>;
  get(creatorUsername: string, packName: string): Promise<AssetPackResponse>;
  listVersions(
    creatorUsername: string,
    packName: string,
    options?: AssetListOptions,
  ): Promise<AssetPackVersionsListResponse>;
  createVersion(request: CreateOwnedAssetPackVersionRequest): Promise<FinalizeAssetPackUploadResponse>;
  update(creatorUsername: string, packName: string, request: UpdateAssetPackRequest): Promise<UpdateAssetPackResponse>;
  updateVersion(
    creatorUsername: string,
    packName: string,
    version: string,
    request: UpdateAssetPackVersionRequest,
  ): Promise<UpdateAssetPackVersionResponse>;
  deleteVersion(creatorUsername: string, packName: string, version: string): Promise<DeleteAssetPackVersionResponse>;
  delete(creatorUsername: string, packName: string): Promise<DeleteAssetPackResponse>;
}

export interface CreateOwnedAssetPackVersionAsset {
  assetName: string;
  displayName?: string;
  description?: string | null;
  category: AssetCategory;
  subcategory?: string | null;
  format?: AssetFormat;
  tags?: string[];
  files: Readonly<Record<string, Blob | File>>;
}

export interface CreateOwnedAssetPackVersionRequest {
  packName: string;
  displayName?: string;
  description?: string | null;
  version: string;
  tags?: string[];
  assets: CreateOwnedAssetPackVersionAsset[];
}

export interface TagsListOptions {
  targetKind?: SavedItemKind;
  groupSlug?: string;
  limit?: number;
  offset?: number;
}

export interface TagsAPI {
  list(options?: TagsListOptions): Promise<TagListResponse>;
  get(groupSlug: string, tagSlug: string): Promise<TagDetailResponse>;
}

export interface AssetSpecsAPI {
  listPublic(options?: { limit?: number; offset?: number; sort?: AssetSpecListSort }): Promise<AssetSpecListResponse>;
  get(assetSpecRef: string): Promise<AssetSpecResponse>;
  listVersions(assetSpecRef: string): Promise<AssetSpecVersionsListResponse>;
  listAssets(assetSpecRef: string, options?: AssetListOptions): Promise<AssetListResponse>;
  listApps(assetSpecRef: string, options?: { limit?: number; offset?: number }): Promise<AssetSpecAppsListResponse>;
}

export interface LoadedOwnedCustomAsset {
  asset: OwnedCustomAssetSummary;
  version: OwnedCustomAssetVersionSummary | null;
}

export interface MutatedOwnedCustomAsset {
  asset: OwnedCustomAssetSummary;
  version: OwnedCustomAssetVersionSummary | null;
}

export interface SaveOwnedCustomAssetRequest {
  assetName: string;
  displayName?: string | null;
  description?: string | null;
  /** Complete contract-role upload set. Required roles are enforced by the asset spec. */
  files: Readonly<Record<string, Blob | File>>;
}

export interface DeleteOwnedCustomAssetRequest {
  assetName: string;
  revision?: string | number;
  deleteAsset?: boolean;
}

export interface CustomAssetFamilyAPI<T = unknown> {
  readonly assetSpecRef: string;
  listPublic(options?: AssetListOptions): Promise<AssetListResponse>;
  listForCreator(creatorUsername: string, options?: AssetListOptions): Promise<AssetListResponse>;
  get(creatorUsername: string, assetName: string): Promise<AssetResponse>;
  getByRef(assetRef: string): Promise<AssetResponse>;
  supports(assetSpecVersionRef: string, capability: AssetSpecCapability): boolean;
  assertSupported(assetSpecVersionRef: string, capability: AssetSpecCapability): void;
  loadJson<U = T>(input: { assetRef: string; role?: string }): Promise<U>;
  loadText(input: { assetRef: string; role?: string }): Promise<string>;
  downloadFile(input: { assetRef: string; role?: string }): Promise<Blob>;
  listMine(): Promise<OwnedCustomAssetSummary[]>;
  loadOwned(input: { assetRef: string }): Promise<LoadedOwnedCustomAsset>;
  loadOwnedFile(input: { assetRef: string; role?: string }): Promise<Blob>;
  loadOwnedJson<U = T>(input: { assetRef: string; role?: string }): Promise<U>;
  saveDraft(input: SaveOwnedCustomAssetRequest): Promise<MutatedOwnedCustomAsset>;
  publish(input: SaveOwnedCustomAssetRequest): Promise<MutatedOwnedCustomAsset>;
  deleteOwned(input: DeleteOwnedCustomAssetRequest): Promise<{ success: boolean }>;
}

export interface CustomAssetsAPI {
  forSpec<T = unknown>(assetSpecRef: string): CustomAssetFamilyAPI<T>;
}

export interface AssetsGraphAPI {
  batchUpsertRelations(request: BatchUpsertNodeRelationsRequest): Promise<BatchUpsertNodeRelationsResponse>;
}

export interface ModelAssetListOptions {
  subcategory: Model3DAssetSubcategory;
  limit?: number;
  offset?: number;
}

export interface ModelAssetByIdRequest {
  id: number;
  subcategory?: Model3DAssetSubcategory;
}

export interface ModelAssetByRefRequest {
  assetRef: AssetReference;
  subcategory?: Model3DAssetSubcategory;
}

export interface ModelAssetBySlugRequest {
  subcategory: Model3DAssetSubcategory;
  slug: string;
  creatorSlug?: string;
}

export interface ModelsAPI {
  listPublic(options: ModelAssetListOptions): Promise<AssetListResponse>;
  getById(options: ModelAssetByIdRequest): Promise<AssetResponse>;
  getByRef(options: ModelAssetByRefRequest): Promise<AssetResponse>;
  getBySlug(options: ModelAssetBySlugRequest): Promise<AssetResponse>;
}

export interface AssetsAPI {
  catalog: AssetsCatalogAPI;
  specs: AssetSpecsAPI;
  custom: CustomAssetsAPI;
  models: ModelsAPI;
  packs: AssetPacksCatalogAPI;
  tags: TagsAPI;
  graph: AssetsGraphAPI;
  resolveAppAsset(runtimeKey: string): AppRuntimeAssetSummary;
  listAppAssets(): AppRuntimeAssetSummary[];
}

export interface SearchAPI {
  query(request: SearchRequest): Promise<SearchResponse>;
}

export interface DebugAPI {
  showUI(): void;
  hideUI(): void;
}

export interface AppData {
  data: Record<string, any>;
  seq: number;
  ts_event: number;
  ts_arrival: number;
}

/** Connection material for the current authenticated app and immutable version. Do not share its token. */
export interface MultiplayerConnection {
  endpoint: string;
  token: string;
  /** Token expiration as Unix time in milliseconds. */
  expiresAt: number;
  runtimeVersion: "colyseus-0.17-v1";
}

/** Connect to the game server declared in the app catalogue using standard Colyseus APIs. */
export interface MultiplayerAPI {
  /**
   * Join independently or consume this player’s host-reserved party seat. Never falls back from a failed party join.
   * Guests are refused with authentication_required and the host is asked to show sign-in; join again after onAuthChange.
   */
  join<State = unknown>(roomName: string, options?: Record<string, unknown>): Promise<import("@colyseus/sdk").Room<any, State>>;
  /**
   * Restore this player's reserved seat after a reload, keeping host party/voice tracking.
   * Requires host support. The token is a bearer credential; save it privately under
   * this app/version/user ID and clear it on logout or explicit leave. It cannot identify its owner.
   * Discard the saved token and call join for multiplayer_reconnect_expired,
   * multiplayer_reconnect_unavailable (this host cannot restore seats), or
   * party_reconnect_mismatch (join the host's current party launch instead).
   * Other errors must surface; never bypass host admission with a raw Colyseus join.
   */
  reconnect<State = unknown>(roomName: string, reconnectionToken: string): Promise<import("@colyseus/sdk").Room<any, State>>;
  voice: { updateSpatialState(state: VoiceSpatialState): void };
  /**
   * Read current host-provided connection material immediately before a new join.
   * Rejects when the game has no server, authentication is missing, or the player
   * token has expired. Does not create a room or refresh an expired host session.
   * A guest session rejects with authentication_required and requests the host sign-in prompt.
   * Prefer join/reconnect above for host party admission and room voice tracking.
   * Raw Colyseus clients are for independent low-level networking.
   *
   * @example
   * ```ts
   * const colyseus = await sdk.libs.colyseus.load();
   * const connection = await sdk.multiplayer.getConnection();
   * const client = new colyseus.Client(connection.endpoint);
   * client.auth.token = connection.token;
   * const room = await client.joinOrCreate("game");
   * ```
   */
  getConnection(): Promise<MultiplayerConnection>;
}

/** Why a game asks for sign-in; the host words its sign-up prompt after it. */
export type LoginPromptReason = "save" | "score" | "friends" | "party" | "challenge" | "multiplayer" | "purchase";

export interface MeAPI {
  login(): Promise<void>;
  /**
   * Ask the host to offer sign-in. Resolves once the request is sent, not when the player signs in: continue from
   * `onAuthChange`. `reason` lets the host say why ("save" progress, post a "score", play with "friends", …); hosts
   * that predate it show their plain prompt. Party, friends, challenges, purchases and rooms need no call here: call
   * the feature itself and the host asks a signed-out player.
   */
  promptLogin(options?: { reason?: LoginPromptReason }): Promise<void>;
  onAuthChange(
    cb: (state: Pick<MeAPI, "isLoggedIn" | "userId" | "username" | "selectedProfileAssetRef" | "avatarUrl">) => void,
  ): () => void;
  /** True only for a real PlayDrop account. Do not use this to gate game persistence. */
  isLoggedIn: boolean;
  userId: number | null;
  username: string | null;
  selectedProfileAssetRef: AssetReference;
  /**
   * The player's picture URL, the one PlayDrop shows for them everywhere and hands out as `SocialFriend.avatarUrl`
   * for friends: their sign-in provider photo first, their avatar's preview only without one. Null when signed out
   * or on a host that does not send it; then draw `selectedProfileAssetRef`.
   */
  readonly avatarUrl: string | null;
  getSelectedProfileAssetRef(): AssetReference;
  appData: AppData | null;
  /** Always callable. Persists for guests and real accounts, and remains in memory when fully logged out. */
  updateAppData(data: Record<string, any>): Promise<AppData>;
}

export type ShopPurchaseKind = "consumable" | "entitlement";

export type ShopReceiptStatus = "PENDING" | "AUTHORIZED" | "CONSUMED" | "GRANTED" | "CANCELLED";

export interface ShopPurchasePayload {
  /** Persist this UUID before confirmation and reuse it to recover the same intended purchase after a restart. */
  clientOperationId?: string;
  kind: ShopPurchaseKind;
  sku: string;
  displayName: string;
  priceCredits: number;
  /**
   * Item image URL for the host purchase confirmation. Use a square image at 256x256, 512x512, or 1024x1024 pixels.
   * Web confirmations crop non-square images. Missing, unloadable, or non-recommended images produce SDK warnings
   * without blocking the purchase; dimension checks run asynchronously where browser image loading is available.
   */
  previewImage?: string | null;
}

export interface ShopReceipt {
  id: number;
  kind: ShopPurchaseKind;
  status: ShopReceiptStatus;
  displayName: string;
  sku: string | null;
  amount: number;
  sourceId: number;
  sourceName: string;
  buyerId: number;
  buyer: string;
  sellerId: number;
  seller: string;
  createdAt: string;
  updatedAt: string;
}

export interface ShopReceiptList {
  receipts: ShopReceipt[];
  pagination: PaginationMeta;
}

export interface ShopReceiptFilters {
  kind?: ShopPurchaseKind;
  status?: ShopReceiptStatus | ShopReceiptStatus[];
  from?: string | Date;
  to?: string | Date;
  limit?: number;
  offset?: number;
}

export interface ShopAPI {
  /**
   * True when the host keeps purchases and receipts on the device (offline-first apps): purchases work for guests
   * and offline, and the host syncs them with PlayDrop. False everywhere else.
   */
  readonly onDevice: boolean;
  /**
   * Reserve credits for an item. Save the returned receipt with its fulfillment job, then consume after saving the
   * deliverable. Cancel failed work. Unconsumed online consumables are automatically cancelled after 24 hours.
   */
  purchase(payload: ShopPurchasePayload): Promise<ShopReceipt>;
  receipts(filters?: ShopReceiptFilters): Promise<ShopReceiptList>;
  consume(receiptId: number): Promise<ShopReceipt>;
  grant(receiptId: number): Promise<ShopReceipt>;
  cancel(receiptId: number): Promise<ShopReceipt>;
}

export interface InterstitialAdsAPI {
  load(): Promise<AdLoadResult>;
  /** Await the host's final result. Failure reason/message explain why an ad could not be shown. */
  show(): Promise<AdShowResult<AdInterstitialShowStatus>>;
}

export interface RewardedAdsAPI {
  load(): Promise<AdLoadResult>;
  /**
   * Await the host's final result and grant the reward exactly once, only when status is `completed`.
   * Do not put an arbitrary timeout around show(): an ad may remain open or the app may be backgrounded.
   * `dismissed` earns no reward. For `not_ready` or legacy `expired`, inspect reason/message for the cause;
   * older hosts may omit these optional fields. `message` is developer-facing, not localized player copy.
   */
  show(): Promise<AdShowResult<AdRewardedShowStatus>>;
}

export interface AdsAPI {
  interstitial: InterstitialAdsAPI;
  rewarded: RewardedAdsAPI;
}

export interface AchievementListOptions {
  includeHiddenDefinitions?: boolean;
  includeRetired?: boolean;
}

export interface AchievementsAPI {
  /** Always callable. Fully logged-out mutations resolve without persistence. */
  list(options?: AchievementListOptions): Promise<ListAchievementsResponse>;
  get(key: string, options?: AchievementListOptions): Promise<GetAchievementResponse>;
  unlock(key: string): Promise<UnlockAchievementResponse>;
  setProgressAtLeast(key: string, progress: number): Promise<SetAchievementProgressResponse>;
}

export interface LeaderboardListOptions {
  includeRetired?: boolean;
}

export interface LeaderboardGetOptions extends LeaderboardListOptions {
  top?: number;
  aroundMe?: number;
}

export interface LeaderboardsAPI {
  /** Always callable. Fully logged-out submissions resolve without persistence. */
  list(options?: LeaderboardListOptions): Promise<ListLeaderboardsResponse>;
  get(key: string, options?: LeaderboardGetOptions): Promise<GetLeaderboardResponse>;
  submitScore(key: string, score: number): Promise<SubmitLeaderboardScoreResponse>;
}

/** Host-owned social UI and app-scoped game cards in PlayDrop Chat, not matchmaking or game-state storage. */
export interface SocialAPI {
  /**
   * Opens host-owned party UI after player input. mode requests online setup or local controller pairing;
   * an existing party is reused. Omit options for the party menu, or use section for voice settings.
   * Resolves when the UI closes, including cancellation; observe party/local-player changes for the outcome.
   * Call it without checking `isLoggedIn`: for a signed-out player the host shows its sign-up state, then the party
   * window once they have an account. Closing either resolves the same way.
   */
  openParty(options?: { mode: "online" | "local"; section?: never } | { mode?: never; section?: "voice" }): Promise<void>;
  /**
   * The player's online party, or null. `participants` lists the leader first, then other members and invited
   * friends, each with a `state` for this game: `invited`, `inParty` (not coming to this game), `joining`, `inGame`
   * or `disconnected`. Older hosts omit `participants`; fall back to `members`. `launch` appears once PlayDrop seated
   * this player's party in this game: then call `sdk.multiplayer.join()`.
   *
   * @example
   * ```ts
   * sdk.social.onPartyChange((party) => {
   *   const people = party?.participants ?? [];
   *   lobby.render(people.map(({ displayName, state }) => ({ name: displayName, arriving: state === "joining" || state === "invited" })));
   * });
   * ```
   */
  getParty(): Promise<Party | null>;
  /**
   * Delivers an initial snapshot, then every change. Requires a host advertising social.getParty: a host without
   * parties throws `party_unavailable` (hide the Party button). A signed-out player on a host with parties gets a
   * null party, so the button stays: `openParty` then shows the host's sign-up state. Never check `isLoggedIn` first.
   */
  onPartyChange(callback: (party: Party | null) => void): () => void;
  /**
   * Friends with a fresh play session in this app (the last 45 s), not the friend list: never use it to decide whether
   * the player has friends (`hasFriends`) or whether someone is a friend (`watchPresence` gives `isFriend`).
   */
  listGameFriends(): Promise<SocialFriend[]>;
  /**
   * Whether the player has at least one PlayDrop friend, playing this game or not: makes Friends the primary button of
   * a new-game row. Resolves false for a signed-out player and in Messages; read it once per home screen. On a
   * rejection keep Friends primary (the host's friend picker explains an empty list). Keep the Friends, Invite and
   * Random buttons enabled for a signed-out player: their calls make the host offer an account.
   *
   * @example
   * ```ts
   * const friendsFirst = await sdk.social.hasFriends().catch(() => true);
   * newGameRow.render({ primary: friendsFirst ? "friends" : null });
   * ```
   */
  hasFriends(): Promise<boolean>;
  /**
   * Open the host friend picker. max defaults to 1 and accepts 1 through 10;
   * cancellation resolves to []. Only the selected identities enter game code.
   * Call it without checking `isLoggedIn`: the host offers a signed-out player an account, then shows the picker
   * (with an invite link when they have no friends yet); closing the offer resolves to [] like any cancellation.
   *
   * @example
   * ```ts
   * const [friend] = await sdk.social.selectFriends({ max: 1 });
   * if (friend) {
   *   // After this player's first move: the friend's move now.
   *   await sdk.social.sendMessage({
   *     recipientUserId: friend.id,
   *     type: "turn",
   *     title: "Played QUIZ for 32", // the move line: the recipient's notification text
   *     payload: matchId,
   *     clientMessageId: `${matchId}-1-${friend.id}`,
   *   });
   * }
   * ```
   */
  selectFriends(options?: { max?: number }): Promise<SocialFriend[]>;
  /** Open the canonical PlayDrop profile in host UI. */
  openProfile(userId: number): Promise<void>;
  /** Open Chat with an editable draft, without sending it. Nonfriends see the platform friendship requirement. */
  openChat(options: OpenSocialChatOptions): Promise<void>;
  /**
   * Send a typed game card to an authorized friend selected by the host, playing
   * this app, or in an existing game-message relationship. Ordinary stranger
   * matchmaking does not authorize social messages.
   * In async 1v1 games send `turn` when the recipient must move and `result` when the match ends; PlayDrop keeps
   * whose turn it is from them. Use `silent: true` while the recipient is watching the match: the card is still posted
   * and visible in Chat (attach the move picture as usual), it just sends no push and adds no unread count. Pass the
   * match's move count as `matchRevision`, so a delayed older card is refused (`social_turn_stale`) instead of moving
   * the turn backwards. The `title` is the text of the recipient's notification ("<you> played <game>. Your turn."):
   * write a short line about the move ("Knight to f6, check"), never just "Your move". Send one `result` when a real
   * match with that friend ends, saying who won, and none for practice, random strangers or matches without moves.
   * Reuse clientMessageId only when retrying the same logical notification.
   */
  sendMessage(input: SendSocialMessageInput): Promise<SendSocialMessageResponse>;
  /**
   * Upload a picture for a card (`mediaRef` on sendMessage, from a game client or its server): a GIF, JPEG, PNG or
   * WebP Blob up to 8 MiB. PlayDrop keeps it fitted inside 512 x 512 px with at most 8 frames, so a square, short
   * animation fits best. The reference works for this player in this game for 24 hours.
   *
   * @example
   * ```ts
   * const { mediaRef } = await sdk.social.uploadMedia(await boardSnapshotBlob());
   * room.send("move", { move, mediaRef }); // the game server sends the turn card with it
   * ```
   */
  uploadMedia(image: Blob): Promise<SocialMediaUploadResponse>;
  /**
   * Read unconsumed, unexpired messages for this app, oldest first. limit defaults
   * to 20 and accepts 1 through 50. Continue with nextCursor until it is null.
   * Incoming messages use `id` and `from.id`, not `messageId` or `senderUserId`.
   *
   * @example
   * ```ts
   * const page = await sdk.social.getMessages({ limit: 20 });
   * for (const message of page.messages) {
   *   await handleGameMessage(message.from.id, message.payload);
   *   await sdk.social.consumeMessage(message.id);
   * }
   * ```
   */
  getMessages(options?: { cursor?: string; limit?: number }): Promise<SocialMessagePage>;
  /** Mark a received message consumed after handling it. Pass the incoming message's `id`. */
  consumeMessage(messageId: string): Promise<void>;
  /**
   * Post the player's recorded best on the game's declared challenge leaderboard (`challenge` in catalogue.json),
   * never a number from the game. Inside a challenge (`sdk.host.challenge`) it posts to that conversation at once;
   * otherwise the host's friend picker opens (1 to 5 friends) and each picked friend gets a challenge card. Call it
   * from the result screen after `submitScore(...).improved`, or from a "Share your best" tap.
   * Offer the button whenever `canSendChallenge()` is true, signed in or not: the host offers a signed-out player an
   * account first, and closing that offer resolves like a cancelled picker (no recipients).
   * Rejects with `challenge_unsupported`, `challenge_no_score`, `challenge_recipients_invalid`,
   * `host_challenge_unsupported` (older host), `social_media_invalid`, or an option check:
   * `invalid_challenge_options`, `invalid_challenge_text`, `invalid_launch_payload`, `social_media_type`,
   * `social_media_too_large`.
   *
   * @example
   * ```ts
   * const result = await sdk.leaderboards.submitScore("high_score", score);
   * if (result.improved && sdk.host.challenge) await sdk.social.sendChallenge({ image: await replayGif() });
   * else if (result.improved) showChallengeFriendsButton(); // its tap calls sdk.social.sendChallenge()
   * ```
   */
  sendChallenge(options?: SendChallengeOptions): Promise<SendChallengeResult>;
  /**
   * Whether `sendChallenge()` can be offered to this player on this host, read synchronously before drawing the
   * button. True for a signed-out player where the host offers an account itself; false on hosts that cannot post
   * challenges for this player (hide the button there).
   */
  canSendChallenge(): boolean;
  /**
   * Watch whether up to 20 players are online: show a small green dot on the opponent while they are `online`, and a
   * full ring while your own room says they are in this very match now. The ring comes from your room's own events,
   * never from this callback alone (`inThisGame` only hints that they play this game now, in any match). `isFriend`
   * says they are a PlayDrop friend: offer the chat bubble (`sdk.social.openChat`) then, unless launched from a DM.
   * The callback receives every watched player's presence, in your order: a snapshot first, then again whenever one of
   * them changes (pushed by PlayDrop, no polling). Only friends are answered; everyone else, a past opponent who is no
   * longer a friend included, reads `unknown` (and `isFriend: false`), and so does everyone on a host without
   * `social.watchPresence` (older or native hosts) and for a guest until they sign in: then show no dot.
   * Call the returned function to stop watching (leaving the match screen). Repeated ids count once. Throws
   * `social_invalid_presence_ids` for an empty list, more than 20 players, an invalid id or a missing callback.
   *
   * @example
   * ```ts
   * let online = false;
   * let isFriend = false;
   * const render = () => opponentAvatar.render({
   *   dot: online,
   *   ring: online && room.state.players.get(String(opponent.id))?.connected === true, // realtime: the room says so
   *   chat: isFriend && !sdk.host.launchFriend,
   * });
   * const stop = sdk.social.watchPresence([opponent.id], ([presence]) => {
   *   online = presence.status === "online";
   *   isFriend = presence.isFriend;
   *   render();
   * });
   * room.onStateChange(render); // the ring follows the room at once, without waiting for a presence change
   * ```
   */
  watchPresence(userIds: number[], callback: (presence: SocialPresence[]) => void): () => void;
}

export interface SocialChatDraftMessage {
  text?: string;
  /** GIF, JPEG, PNG, or WebP Blob, up to 8 MiB, transferred without base64 expansion. */
  image?: Blob;
}

export interface OpenSocialChatOptions {
  recipientUserId: number;
  draftMessage?: SocialChatDraftMessage;
}

export type AiTaskRequest<K extends AgentTaskGenerationKind> = Omit<
  Extract<CreateAiGenerationTaskRequest, { kind: K }>,
  "kind"
>;

export interface AiModalityAPI<K extends AgentTaskGenerationKind> {
  createTask(request: AiTaskRequest<K>): Promise<Extract<GenerationAgentTaskResponse, { kind: K }>>;
  generations(): Promise<AiGenerationResponse[]>;
}

export interface AiTasksAPI {
  /** Share a completed user-paid MUSIC task for room playback after the player opts in. No new charge. */
  createRoomPlaybackGrant(id: number, options: import("@playdrop/types").AiRoomPlaybackGrantRequest): Promise<import("@playdrop/types").AiRoomPlaybackGrantResponse>;
  get(id: number): Promise<GenerationAgentTaskResponse>;
  downloadFile(id: number, options?: { role?: string }): Promise<Blob>;
  list(options?: { kind?: AgentTaskGenerationKind; status?: AgentTaskStatus; limit?: number; offset?: number }): Promise<GenerationAgentTaskResponse[]>;
  events(id: number): Promise<AgentTaskEventResponse[]>;
  cancel(id: number): Promise<GenerationAgentTaskResponse>;
  clear(id: number): Promise<void>;
}

export interface AiInputsAPI {
  upload(file: Blob, fileName?: string): Promise<{ type: "TASK_UPLOAD"; uploadId: string }>;
}

export type AiTextAPI = AiModalityAPI<"TEXT">;

export type AiJsonAPI = AiModalityAPI<"JSON">;

export type AiImageAPI = AiModalityAPI<"IMAGE">;

export type AiMusicAPI = AiModalityAPI<"MUSIC">;

export type AiSfxAPI = AiModalityAPI<"SFX">;

export type AiSpeechAPI = AiModalityAPI<"SPEECH">;

export type AiVideoAPI = AiModalityAPI<"VIDEO">;

export type AiModel3DAPI = AiModalityAPI<"MODEL_3D">;

export interface AiAPI {
  text: AiTextAPI;
  json: AiJsonAPI;
  image: AiImageAPI;
  music: AiMusicAPI;
  sfx: AiSfxAPI;
  speech: AiSpeechAPI;
  video: AiVideoAPI;
  model3d: AiModel3DAPI;
  inputs: AiInputsAPI;
  tasks: AiTasksAPI;
}

export type TweakValues = Record<string, string | number | boolean>;

export interface TweaksAPI {
  get<T extends TweakValues>(): Promise<T>;
}

export interface CreatorAPI {
  /**
   * False while this version is an update still in review: Notes work, but tweak saves open only once the
   * update completes, and replaceTweaks rejects with `creator_tweaks_unavailable:version_in_review`.
   */
  readonly canReplaceTweaks: boolean;
  replaceTweaks<T extends TweakValues>(values: T): Promise<T>;
  notes: CreatorNotesAPI;
}

export type CreatorNoteDraft =
  | { kind: "TEXT"; text: string }
  | { kind: "MARKDOWN"; text: string; fileName?: string }
  | { kind: "JSON"; value: unknown; fileName?: string }
  | { kind: "IMAGE"; image: Blob; fileName?: string }
  | { kind: "LOG"; format: "text"; text: string; fileName?: string }
  | { kind: "LOG"; format: "json"; value: unknown; fileName?: string }
  | { kind: "ASSET"; assetRef: string; comment: string };

export interface CreatorNotesAPI {
  list(): Promise<CreatorNote[]>;
  /**
   * Add a note using the discriminated CreatorNoteDraft payload; there is no title field.
   * Only available when sdk.creator is non-null.
   *
   * @example
   * ```ts
   * if (sdk.creator) {
   *   await sdk.creator.notes.add({ kind: "TEXT", text: "Jump feels weak" });
   *   await sdk.creator.notes.add({ kind: "JSON", value: { gravity: 900 } });
   * }
   * ```
   */
  add(note: CreatorNoteDraft): Promise<CreatorNote>;
  replace(id: number, note: CreatorNoteDraft): Promise<CreatorNote>;
  remove(id: number): Promise<void>;
}

export interface HapticsAPI {
  /** Native host can dispatch feedback; hardware and system settings may suppress it. */
  readonly supported: boolean;
  selection(): void;
  impact(style?: "light" | "medium" | "heavy"): void;
  notification(type: "success" | "warning" | "error"): void;
}

export interface PlaydropSDK {
  haptics: HapticsAPI;
  host: HostAPI;
  connection: ConnectionAPI;
  device: DeviceAPI;
  app: AppMetadata;
  libs: LibrariesAPI;
  assets: AssetsAPI;
  search: SearchAPI;
  me: MeAPI;
  multiplayer: MultiplayerAPI;
  debug: DebugAPI;
  shop: ShopAPI;
  ads: AdsAPI;
  achievements: AchievementsAPI;
  leaderboards: LeaderboardsAPI;
  social: SocialAPI;
  ai: AiAPI;
  tweaks: TweaksAPI;
  creator: CreatorAPI | null;
}
```

## packages/web-bridge/src/types.ts

```ts
export interface LocalPlayerSlot {
  playerIndex: number;
  gamepadKey: string;
}

/**
 * Positional controller buttons in W3C standard-mapping order: the index is the browser `buttons[]` index.
 * `menu` and `home` are host-reserved: hosts consume them (pause) and always report them released.
 */
export const CONTROLLER_BUTTON_NAMES = [
  "south",
  "east",
  "west",
  "north",
  "leftShoulder",
  "rightShoulder",
  "leftTrigger",
  "rightTrigger",
  "select",
  "menu",
  "leftStickPress",
  "rightStickPress",
  "dpadUp",
  "dpadDown",
  "dpadLeft",
  "dpadRight",
  "home",
] as const;

export type ControllerButtonName = (typeof CONTROLLER_BUTTON_NAMES)[number];

/** Controls a pad physically has. Sticks are axes 0-1 (left) and 2-3 (right); `dpad` covers its four buttons. */
export type ControllerControlName =
  | Exclude<ControllerButtonName, "menu" | "home" | "dpadUp" | "dpadDown" | "dpadLeft" | "dpadRight">
  | "leftStick"
  | "rightStick"
  | "dpad";

export interface VoiceVector { x: number; y: number; z: number }

export interface VoiceSpatialState {
  listener: { position: VoiceVector; forward: VoiceVector; up: VoiceVector };
  speakers: { userId: number; position: VoiceVector }[];
}

export type HostReservedCorners = Readonly<Record<"topLeft" | "topRight", Readonly<{ width: number; height: number }>>>;
```
