# PlayDrop shared types used by the SDKs

Generated from `@playdrop/types`: every shared type the client and server SDK declarations reference; do not edit by hand.

## packages/types/src/social.ts

```ts
export const SOCIAL_MESSAGE_TYPES = ["invite", "request", "gift", "challenge", "turn", "result"] as const;

export type SocialMessageType = (typeof SOCIAL_MESSAGE_TYPES)[number];

/** Public identity returned by host friend selection or same-game friend discovery. */
export type SocialFriend = {
  /** PlayDrop user ID, also exposed as `message.from.id` on incoming messages. */
  id: number;
  username: string;
  displayName: string;
  /** The person's picture: their sign-in provider photo (X, then Google) first, their PlayDrop avatar only without one. */
  avatarUrl: string | null;
  /** `/parties/friends?username=` only: the friend is in a party now (anyone's). */
  inParty?: boolean;
};

/**
 * A game card in PlayDrop Chat, not storage for authoritative game state. In async 1v1 games, `turn` means "your move"
 * (PlayDrop then counts it as the recipient's turn) and `result` ends the match (no move pending).
 */
export type SendSocialMessageInput = {
  /** An authorized friend's user ID. A game-defined opponent ID alone is insufficient. */
  recipientUserId: number;
  type: SocialMessageType;
  /** Required Chat body, up to 80 characters. */
  title: string;
  /** Optional secondary text, up to 160 characters. */
  subtitle?: string;
  /** Exact reference to a declared public square image asset. Not with `mediaRef`. */
  thumbnailAssetRef?: string;
  /** A picture made at play time, from `social.uploadMedia` by the same player in this game (valid 24 hours). */
  mediaRef?: string;
  /**
   * `turn` and `result` only: a quiet card for a recipient already watching the match. The card is still posted and
   * visible in Chat (it arrives live in an open conversation) and still records whose turn it is, but it sends no push
   * notification and does not raise the recipient's unread count.
   */
  silent?: boolean;
  /**
   * The match's move count (a non-negative integer that grows with each committed move or result of this match).
   * PlayDrop keeps the highest one per game, friend pair and match (`payload`); a `turn` or `result` with a lower one is
   * refused with 409 `social_turn_stale` and posts nothing, so a delayed card never moves whose turn it is backwards.
   * Equal is accepted (retries).
   */
  matchRevision?: number;
  /** Opaque base64url launch payload, at most 256 characters; authorize its meaning in game code. */
  payload?: string;
  /** Integer lifetime from 60 seconds through 30 days; defaults to 30 days. */
  expiresInSeconds?: number;
  /**
   * Retry key, up to 120 characters, unique per sender and app. Reusing it returns
   * the original message even if other input changes; include the recipient when
   * sending one logical event to multiple friends. Omission generates a new key.
   */
  clientMessageId?: string;
};

export type SocialMessageApp = {
  id: number;
  name: string;
  displayName: string;
  creatorUsername: string;
  version: string;
  iconUrl: string | null;
  /** The version's portrait hero, on chat game cards sent after November 8, 2026 (blurred behind the card). */
  heroPortraitUrl?: string | null;
};

/** An incoming game message. Its identifier is `id`; only send results use `messageId`. */
export type SocialMessage = {
  /** Pass this value to consumeMessage after handling the message. */
  id: string;
  type: SocialMessageType;
  /** Sender identity; the sender's user ID is `from.id`. */
  from: SocialFriend;
  title: string;
  subtitle: string | null;
  thumbnailAssetRef: string | null;
  thumbnailUrl: string | null;
  /** The last frame of an animated picture, as a still (null for still pictures and older cards). */
  thumbnailStillUrl?: string | null;
  payload: string | null;
  app: SocialMessageApp;
  createdAt: string;
  expiresAt: string;
  consumedAt: string | null;
};

/** Unconsumed, unexpired incoming messages for this app, ordered oldest first. */
export type SocialMessagePage = {
  messages: SocialMessage[];
  /** Pass as cursor for the next page; null means pagination is complete. */
  nextCursor: string | null;
};

/**
 * Send acknowledgement. Read/list responses use SocialMessage.id instead. A quiet (`silent`) card has a message like
 * any other; only a silent send inside an iMessage match has none (`messageId` null).
 */
export type SendSocialMessageResponse = {
  messageId: string | null;
  createdAt: string;
  expiresAt: string | null;
};

/** A picture for a game card: at most 512 x 512 px and 8 frames once PlayDrop has normalized it. */
export type SocialMediaUploadResponse = {
  mediaRef: string;
  url: string;
  /** An animation's last frame as a still picture (`<key>.still.webp`); null for a still upload. */
  stillUrl?: string | null;
};

/** `unknown`: not a friend of this player, no game-message relationship with them in this game, or no answer yet. */
export type SocialPresenceStatus = "online" | "offline" | "unknown";

/** One player's presence as a game sees it (wiki/async-turns.md). */
export type SocialPresence = {
  userId: number;
  status: SocialPresenceStatus;
  /**
   * This player has a live play session of this game now (any match: the game's own room tells which). A hint for
   * "playing this game", never the same-match ring.
   */
  inThisGame: boolean;
  /** A PlayDrop friend of the viewer (mutual follows, no block): show the chat bubble (`sdk.social.openChat`). */
  isFriend: boolean;
};

/** One player's entry in a challenge: their posted best on its leaderboard, as that leaderboard formats it. */
export type ChallengeEntry = {
  user: SocialFriend;
  score: number;
  displayScore: string;
  /** 1 for the best entry; equal scores share a rank. */
  rank: number;
};

/** `sdk.host.challenge`: the challenge a game was opened from, as the host puts it in `host:init`. */
export type HostChallenge = {
  /** Null when started from a direct chat's Challenge tab before anyone posted, and in iMessage. */
  id: string | null;
  /** The declared challenge leaderboard key. */
  leaderboard: string;
  /** Best first. */
  entries: ChallengeEntry[];
  /** This player's entry, or null before their first post. */
  me: ChallengeEntry | null;
  /** The card's payload (also `sdk.host.launchPayload`). */
  payload: string | null;
};
```

## packages/types/src/app.ts

```ts
export const APP_TYPE_VALUES = ["GAME", "TEMPLATE", "TOOL", "DEMO"] as const;

export type AppType = (typeof APP_TYPE_VALUES)[number];

export const APP_SURFACE_VALUES = ["DESKTOP", "MOBILE_LANDSCAPE", "MOBILE_PORTRAIT"] as const;

export type AppSurface = (typeof APP_SURFACE_VALUES)[number];

export const APP_ORIGIN_VALUES = ["PLAYDROP_CLOUD", "USER"] as const;

export type AppOrigin = (typeof APP_ORIGIN_VALUES)[number];
```

## packages/types/src/version.ts

```ts
export const APP_HOSTING_MODE_VALUES = ["HOSTED", "EXTERNAL"] as const;

export type AppHostingMode = (typeof APP_HOSTING_MODE_VALUES)[number];

export const APP_VERSION_VISIBILITY_VALUES = ["PRIVATE", "PUBLIC"] as const;

export type AppVersionVisibility = (typeof APP_VERSION_VISIBILITY_VALUES)[number];

/** A game's audience: private to its creator, open by link, or listed on PlayDrop. */
export const GAME_VISIBILITY_VALUES = ["PRIVATE", "UNLISTED", "PUBLIC"] as const;

export type GameVisibility = (typeof GAME_VISIBILITY_VALUES)[number];

export const REVIEW_STATE_VALUES = [
  "NOT_REQUIRED",
  "QUEUED",
  "RUNNING",
  "SUPERSEDED",
  "LOW_QUALITY",
  "PASSED",
  "GOOD",
  "EXCELLENT",
  "FAILED",
  "ERROR",
] as const;

export type ReviewState = (typeof REVIEW_STATE_VALUES)[number];

export const APP_VERSION_DESIGN_GROUP_VALUES = [
  "genre",
  "coreGameplay",
  "perspective",
  "controls",
  "visualStyle",
  "progression",
  "feel",
] as const;

export type AppVersionDesignGroup = (typeof APP_VERSION_DESIGN_GROUP_VALUES)[number];

export type AppVersionDesign = Partial<Record<AppVersionDesignGroup, string>>;

export const APP_MULTIPLAYER_STYLE_VALUES = ["COOPERATIVE", "COMPETITIVE"] as const;

export type AppMultiplayerStyle = (typeof APP_MULTIPLAYER_STYLE_VALUES)[number];

export interface AppPlayerCountRange {
  min: number;
  max: number;
}

/** Online room capacity is optional: authoritative capacity lives in game-server configuration. */
export interface AppOnlinePlayersConfig extends Partial<AppPlayerCountRange> {
  /** Supported arriving party sizes, independent of total room capacity. */
  partySizes?: (2 | 3 | 4)[];
  /** Opt in to host-owned room voice. Omitted means disabled. */
  roomVoice?: boolean;
}

export interface AppMultiplayerConfig {
  local?: AppPlayerCountRange;
  online?: AppOnlinePlayersConfig;
  /** Optional classification; empty when undeclared (new-format declarations never set it). */
  styles: AppMultiplayerStyle[];
}

export interface AppPlayersConfig {
  solo: boolean;
  multiplayer?: AppMultiplayerConfig;
}

export interface AppCreationMetadata {
  harness?: string;
  model?: string;
}

/** How a game takes tips; null on a private game. */
export interface AppTipping {
  amounts: number[];
}

export const APP_AUTH_MODE_VALUES = ["REQUIRED", "OPTIONAL", "NONE"] as const;

export type AppAuthMode = (typeof APP_AUTH_MODE_VALUES)[number];

export const APP_CONTROLLER_MODE_VALUES = ["UNSUPPORTED", "SUPPORTED", "REQUIRED"] as const;

export type AppControllerMode = (typeof APP_CONTROLLER_MODE_VALUES)[number];

export const APP_LISTING_MEDIA_KIND_VALUES = ["IMAGE", "VIDEO"] as const;

export type AppListingMediaKind = (typeof APP_LISTING_MEDIA_KIND_VALUES)[number];

export const APP_LISTING_MEDIA_ORIENTATION_VALUES = ["PORTRAIT", "LANDSCAPE"] as const;

export type AppListingMediaOrientation = (typeof APP_LISTING_MEDIA_ORIENTATION_VALUES)[number];

export interface AppListingMediaMetadata {
  fileKey: string;
  slug?: string;
  title?: string;
  alt?: string;
  caption?: string;
  description?: string;
}

export interface AppListingMediaItem extends AppListingMediaMetadata {
  kind: AppListingMediaKind;
  orientation: AppListingMediaOrientation;
  position: number;
  url: string;
}
```

## packages/types/src/asset-spec.ts

```ts
export const ASSET_SPEC_VISIBILITY_VALUES = ["PRIVATE", "PUBLIC"] as const;

export type AssetSpecVisibility = (typeof ASSET_SPEC_VISIBILITY_VALUES)[number];

export const ASSET_SPEC_VALIDATION_KIND_VALUES = ["NONE", "JSON_SCHEMA"] as const;

export type AssetSpecValidationKind = (typeof ASSET_SPEC_VALIDATION_KIND_VALUES)[number];

export const ASSET_SPEC_STATUS_VALUES = ["ACTIVE", "DEPRECATED", "RETRACTED"] as const;

export type AssetSpecStatus = (typeof ASSET_SPEC_STATUS_VALUES)[number];

export const ASSET_SPEC_CAPABILITY_VALUES = ["READ", "WRITE", "EDIT", "PREVIEW", "IMPORT"] as const;

export type AssetSpecCapability = (typeof ASSET_SPEC_CAPABILITY_VALUES)[number];

export const ASSET_SPEC_ROLE_MODE_VALUES = ["TEXT", "BINARY"] as const;

export type AssetSpecRoleMode = (typeof ASSET_SPEC_ROLE_MODE_VALUES)[number];

export const ASSET_SPEC_REFERENCE_TARGET_KIND_VALUES = ["ASSET"] as const;

export type AssetSpecReferenceTargetKind = (typeof ASSET_SPEC_REFERENCE_TARGET_KIND_VALUES)[number];

export const ASSET_SPEC_REFERENCE_CARDINALITY_VALUES = ["ONE", "MANY"] as const;

export type AssetSpecReferenceCardinality = (typeof ASSET_SPEC_REFERENCE_CARDINALITY_VALUES)[number];

export interface AssetSpecRoleContract {
  name: string;
  required: boolean;
  contentTypes: string[];
  extensions?: string[];
  mode: AssetSpecRoleMode;
  jsonSchema?: Record<string, unknown> | null;
}

export interface AssetSpecReferenceContract {
  name: string;
  required: boolean;
  targetKind: AssetSpecReferenceTargetKind;
  cardinality: AssetSpecReferenceCardinality;
  targetSpec?: string | null;
  versionRange?: string | null;
}

export interface AssetSpecContract {
  primaryRole: string;
  roles: AssetSpecRoleContract[];
  references?: AssetSpecReferenceContract[];
}

export interface AppMetadataAssetSpecSupport {
  assetSpecRef: string;
  versionRange: string;
  capabilities: AssetSpecCapability[];
}

export interface AssetSpecVersionResponse {
  id: number;
  version: string;
  major: number;
  minor: number;
  patch: number;
  visibility: AssetSpecVisibility;
  status: AssetSpecStatus;
  validationKind: AssetSpecValidationKind;
  contractJson: AssetSpecContract | Record<string, unknown>;
  documentationUrl?: string | null;
  validatorUrl?: string | null;
  releaseNotes?: string | null;
  successorVersionRef?: string | null;
  createdAt: string;
  updatedAt: string;
}

export interface AssetSpecResponse {
  id: number;
  name: string;
  displayName: string;
  description?: string | null;
  creatorId: number;
  creatorUsername: string;
  symbolUrl?: string | null;
  currentVersion?: AssetSpecVersionResponse | null;
  currentVersionRef?: string | null;
  status?: AssetSpecStatus | null;
  publicAssetCount: number;
  supportingAppCount: number;
  documentationAvailable: boolean;
  createdAt: string;
  updatedAt: string;
}

export const ASSET_SPEC_LIST_SORT_VALUES = ["recent", "assets", "apps", "alpha"] as const;

export type AssetSpecListSort = (typeof ASSET_SPEC_LIST_SORT_VALUES)[number];

export interface AssetSpecListResponse {
  assetSpecs: AssetSpecResponse[];
  pagination: {
    limit: number;
    offset: number;
    count: number;
    hasMore: boolean;
  };
}

export interface AssetSpecVersionsListResponse {
  versions: AssetSpecVersionResponse[];
  pagination?: {
    limit: number;
    offset: number;
    count: number;
    hasMore: boolean;
  };
}

export interface AssetSpecAppsListResponse {
  assetSpec: AssetSpecResponse;
  apps: AppResponse[];
  pagination: {
    limit: number;
    offset: number;
    count: number;
    hasMore: boolean;
  };
}

export interface AssetSpecSearchResult {
  kind: "asset-spec";
  targetPath: string;
  assetSpec: AssetSpecResponse;
}
```

## packages/types/src/asset.ts

```ts
export const ASSET_CATEGORY_VALUES = ["IMAGE", "VIDEO", "AUDIO", "SPRITESHEET", "MODEL_3D", "CUSTOM"] as const;

export type AssetCategory = (typeof ASSET_CATEGORY_VALUES)[number];

export const ASSET_FORMAT_VALUES = [
  "PNG",
  "JPEG",
  "WEBP",
  "GIF",
  "ASEPRITE",
  "MP4",
  "WEBM",
  "MP3",
  "WAV",
  "OGG",
  "GLTF",
  "GLB",
  "VOX",
  "CUSTOM",
] as const;

export type AssetFormat = (typeof ASSET_FORMAT_VALUES)[number];

export const ASSET_VISIBILITY_VALUES = ["PRIVATE", "PUBLIC"] as const;

export type AssetVisibility = (typeof ASSET_VISIBILITY_VALUES)[number];

export const ASSET_SOURCE_KIND_VALUES = ["UPLOAD", "AI", "APP_EMBEDDED", "IMPORT"] as const;

export type AssetSourceKind = (typeof ASSET_SOURCE_KIND_VALUES)[number];

export interface OwnedCustomAssetVersionSummary {
  assetRef: string;
  revision: number;
  revisionLabel: string;
  visibility: AssetVisibility;
  license: ContentLicense;
  assetSpecVersionRef: string | null;
  previewUrl: string | null;
  createdAt: string;
  updatedAt: string;
}

export interface OwnedCustomAssetSummary {
  creatorUsername: string;
  assetName: string;
  displayName: string | null;
  description: string | null;
  currentVersion: OwnedCustomAssetVersionSummary | null;
  latestVersion: OwnedCustomAssetVersionSummary | null;
  latestPublicVersion: OwnedCustomAssetVersionSummary | null;
}

export interface AssetSubcategoryDefinition {
  category: AssetCategory;
  subcategory: string;
  formats: AssetFormat[];
  label: string;
}

export const PLAYDROP_SPEECH_VOICE_IDS = [
  "default_narrator",
  "warm_storyteller_m",
  "neutral_guide",
  "confident_guide_f",
  "casual_companion_m",
  "atmospheric_storyteller_f",
  "energetic_host_m",
  "bright_creator_f",
] as const;

export type PlaydropSpeechVoiceId = (typeof PLAYDROP_SPEECH_VOICE_IDS)[number];

export const MODEL_3D_ASSET_SUBCATEGORY_VALUES = ["generic", "humanoid", "creature", "block", "procedural"] as const;

export type Model3DAssetSubcategory = (typeof MODEL_3D_ASSET_SUBCATEGORY_VALUES)[number];

export interface AssetFileManifestEntry {
  // Common roles include primary, preview, cover, mesh, and metadata.
  role: string;
  key: string;
  url?: string;
  contentType?: string | null;
  sizeBytes?: number | null;
  sha256?: string | null;
}

export interface AssetFileManifest {
  files: AssetFileManifestEntry[];
}

export interface AssetGenerationInputAttachmentResponse {
  key: string;
  label: string;
  url: string;
}

export interface AssetGenerationInputParamResponse {
  key: string;
  label: string;
  value: string | number | boolean | null;
}

export interface AssetGenerationInputSummaryResponse {
  modality: string | null;
  prompt: string | null;
  attachments: AssetGenerationInputAttachmentResponse[];
  params: AssetGenerationInputParamResponse[];
}

export interface AssetGenerationReplayAttachmentResponse {
  key: "image1" | "image2";
  label: string;
  url: string;
  mimeType?: string | null;
}

export interface AssetGenerationReplayResponse {
  modality: "IMAGE" | "MUSIC" | "SFX" | "SPEECH" | "VIDEO" | "MODEL_3D";
  prompt: string;
  image1?: AssetGenerationReplayAttachmentResponse | null;
  image2?: AssetGenerationReplayAttachmentResponse | null;
  durationMs?: number | null;
  forceInstrumental?: boolean | null;
  durationSeconds?: number | null;
  loop?: boolean | null;
  coverPrompt?: string | null;
  speechVoice?: PlaydropSpeechVoiceId | null;
  speechProviderVoiceId?: string | null;
  aspectRatio?: string | null;
  imageSize?: string | null;
  resolution?: string | null;
  sourceMode?: string | null;
  topology?: string | null;
  targetPolycount?: number | null;
  shouldRemesh?: boolean | null;
  shouldTexture?: boolean | null;
  assetSubcategory?: string | null;
}

export interface AssetVersionResponse {
  id: number;
  revision: number;
  revisionLabel: string;
  subcategory: string | null;
  visibility: AssetVisibility;
  format: AssetFormat;
  storageKey: string;
  fileManifest: AssetFileManifest | Record<string, unknown>;
  assetSpecVersionRef?: string | null;
  primaryRole?: string | null;
  primaryContentType?: string | null;
  primaryExtension?: string | null;
  sourceKind: AssetSourceKind;
  sourceAppVersionId?: number | null;
  sourceGenerationId?: string | null;
  sourcePrompt?: string | null;
  sourceGenerationInput?: AssetGenerationInputSummaryResponse | null;
  sourceGenerationReplay?: AssetGenerationReplayResponse | null;
  shopListed: boolean;
  shopPriceCredits: number;
  license: ContentLicense;
  permissions?: ContentPermissions;
  createdAt: string;
  updatedAt: string;
}

export interface AssetResponse {
  id: number;
  name: string;
  displayName: string;
  description?: string | null;
  category: AssetCategory;
  assetSpecRef?: string | null;
  assetSpecDisplayName?: string | null;
  assetSpecSymbolUrl?: string | null;
  creatorId: number;
  creatorUsername: string;
  createdAt: string;
  updatedAt: string;
  currentVersion?: AssetVersionResponse | null;
  viewerSaved?: boolean;
  viewerLiked?: boolean;
  viewerDisliked?: boolean;
  likeCount?: number;
  viewCount?: number;
  commentCount?: number;
  remixCount?: number;
  packMembershipSummary?: AssetPackMembershipSummary | null;
  tags: ContentTagSummary[];
}

export interface AssetPackMembershipSummaryItem {
  creatorUsername: string;
  name: string;
  displayName: string | null;
}

export interface AssetPackMembershipSummary {
  count: number;
  packs: AssetPackMembershipSummaryItem[];
}

export interface AssetRef {
  creatorUsername: string;
  name: string;
  revision: number;
}

export interface UpdateAssetRequest {
  name?: string;
  displayName?: string;
  description?: string | null;
}

export interface UpdateAssetVersionRequest {
  visibility?: AssetVisibility;
  license?: ContentLicense;
  setAsCurrent?: boolean;
}

export const ASSET_LIST_SORT_VALUES = ["recent", "views", "likes", "remixes", "comments"] as const;

export type AssetListSort = (typeof ASSET_LIST_SORT_VALUES)[number];

export interface AssetListResponse {
  assets: AssetResponse[];
  pagination: {
    limit: number;
    offset: number;
    count: number;
    hasMore: boolean;
  };
}

export interface AssetVersionsListResponse {
  versions: AssetVersionResponse[];
  pagination?: {
    limit: number;
    offset: number;
    count: number;
    hasMore: boolean;
  };
}

export interface CreateAssetVersionResponse {
  asset: AssetResponse;
  version: AssetVersionResponse;
  versionNodeId: string;
  warnings?: Array<{
    code: string;
    message: string;
    successorRef?: string | null;
  }>;
}

export interface UpdateAssetResponse {
  asset: AssetResponse;
}

export interface UpdateAssetVersionResponse {
  version: AssetVersionResponse;
}

export interface DeleteAssetVersionResponse {
  success: boolean;
}

export interface DeleteAssetResponse {
  success: boolean;
}

export interface AssetSourceBundleResponse {
  filename: string;
  sizeBytes: number;
  checksum?: string | null;
}
```

## packages/types/src/content-license.ts

```ts
export const CONTENT_LICENSE_VALUES = ["CLOSED", "PLAYDROP", "MIT", "CC0"] as const;

export type ContentLicense = (typeof CONTENT_LICENSE_VALUES)[number];

export interface ContentPermissions {
  canDownloadSource: boolean;
  canRemix: boolean;
  canReuseOnPlaydrop: boolean;
  canUseOffPlatform: boolean;
}
```

## packages/types/src/api.ts

```ts
export interface ContentTagSummary {
  ref: string;
  groupSlug: string;
  groupDisplayName: string;
  slug: string;
  displayName: string;
}

export const AGENT_TASK_STATUS_VALUES = [
  "BACKLOG", "WAITING", "QUEUED", "RUNNING", "DONE", "FAILED", "EXPIRED", "CANCELLED",
] as const;

export type AgentTaskStatus = (typeof AGENT_TASK_STATUS_VALUES)[number];

export type JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue };

export const AGENT_TASK_CREATOR_FEEDBACK_STATUS_VALUES = [
  "UNSEEN",
  "VIEWED",
  "PLAYED",
  "APPROVED",
  "DISAPPROVED",
] as const;

export type AgentTaskCreatorFeedbackStatus = (typeof AGENT_TASK_CREATOR_FEEDBACK_STATUS_VALUES)[number];

export const AGENT_TASK_KIND_VALUES = [
  "UGC",
  "UGC_PROCESSING",
  "CREATOR_SUPPORT",
  "NEW_GAME",
  "STATIC_GAME",
  "REMIX_GAME",
  "GAME_UPDATE",
  "AUTO_IMPROVE",
  "GAME_REVIEW",
  "GAME_EVAL",
  "RELEASE_SMOKE",
  "RETRO",
  "SCOUT",
  "KNOWLEDGE",
  "TEXT",
  "JSON",
  "IMAGE",
  "MODEL_3D",
  "VIDEO",
  "SFX",
  "SPEECH",
  "MUSIC",
] as const;

export type AgentTaskKind = (typeof AGENT_TASK_KIND_VALUES)[number];

export const AGENT_TASK_GENERATION_KIND_VALUES = [
  "TEXT",
  "JSON",
  "IMAGE",
  "MODEL_3D",
  "VIDEO",
  "SFX",
  "SPEECH",
  "MUSIC",
] as const;

export type AgentTaskGenerationKind = (typeof AGENT_TASK_GENERATION_KIND_VALUES)[number];

export const AGENT_TASK_PHASE_VALUES = ["SCREENING", "EXECUTION"] as const;

export type AgentTaskPhase = (typeof AGENT_TASK_PHASE_VALUES)[number];

export const AGENT_TASK_PROVIDER_VALUES = ["CODEX", "FAL", "GOOGLE", "GROK"] as const;

export type AgentTaskProvider = (typeof AGENT_TASK_PROVIDER_VALUES)[number];

export const AGENT_TASK_VISIBILITY_VALUES = ["CREATOR", "INTERNAL"] as const;

export type AgentTaskVisibility = (typeof AGENT_TASK_VISIBILITY_VALUES)[number];

export const AI_TEXT_SIZE_VALUES = ["small", "medium", "large"] as const;

export type AiTextSize = (typeof AI_TEXT_SIZE_VALUES)[number];

export type AiGenerationInputReference =
  | { type: "ASSET_VERSION"; ref: string }
  | { type: "TASK_UPLOAD"; uploadId: string };

export interface PrepareAiTaskInputUploadRequest {
  fileName: string;
  contentType: "image/png" | "image/jpeg" | "image/webp";
  sizeBytes: number;
  sha256: string;
  md5Base64: string;
}

export interface PrepareAiTaskInputUploadResponse {
  uploadId: string;
  uploadUrl: string;
  uploadMethod: "PUT";
  uploadHeaders: Record<string, string>;
  expiresAt: string;
}

export interface FinalizeAiTaskInputUploadResponse {
  uploadId: string;
  uploadedAt: string;
}

export interface AiGenerationAssetFields {
  assetName?: string;
  assetDisplayName?: string;
  assetDescription?: string;
  /** Defaults to PRIVATE. PUBLIC permits anyone to discover and download the generated asset. */
  assetVisibility?: "PRIVATE" | "PUBLIC";
  assetSubcategory?: string;
  attachAppVersionId?: number;
  remixAssetVersionRef?: string;
  suggestedTagRefs?: string[];
}

/**
 * The curated fal order behind a VIDEO, MODEL_3D, MUSIC, SFX or SPEECH task (see media-models.ts). The server writes
 * these fields from the creator's `quality` and settings; only a running 3D character job's helpers may name one of
 * `ASSET_JOB_FAL_HELPERS` themselves.
 */
export interface AiGenerationFalOrderFields {
  /** Standard (default) or high quality; each maps to one curated model. */
  quality?: MediaQuality;
  /** fal endpoint id. */
  falModel?: string;
  /** Provider input; "$image1"/"$image2" are replaced with the resolved reference URLs. */
  falInput?: Record<string, unknown>;
  /** Response field holding the primary output file, e.g. "rigged_character_glb". */
  falOutput?: string;
  /** fal's list price for this order in US dollars, counted against the monthly fal budget. */
  falUsd?: number;
}

export type CreateAiGenerationTaskRequest =
  | { kind: "TEXT"; input: string; system?: string; size?: AiTextSize }
  | { kind: "JSON"; input: string; system?: string; size?: AiTextSize; responseSchema: Record<string, unknown> }
  | (AiGenerationAssetFields & {
      kind: "IMAGE";
      input: string;
      image1?: AiGenerationInputReference;
      image2?: AiGenerationInputReference;
      aspectRatio?: "1:1" | "3:4" | "9:16" | "4:3" | "16:9";
      imageSize?: "1K" | "4K";
      /** Agentic asset job; the typed Hive definition owns the method and the price is per unit. */
      assetJob?: AssetJobRequest;
    })
  | (AiGenerationAssetFields & AiGenerationFalOrderFields & {
      kind: "MUSIC";
      input: string;
      /** High quality only: an exact length, 3,000 to 60,000 ms (60 s by default). */
      durationMs?: number;
      forceInstrumental?: boolean;
      /** A prompt for a generated cover. Without one, the song keeps the artwork its music AI made, or gets a waveform. */
      coverPrompt?: string;
    })
  | (AiGenerationAssetFields & AiGenerationFalOrderFields & {
      kind: "SFX";
      input: string;
      /** 0.5 to 30 seconds; leave it out to let the model choose. */
      durationSeconds?: number;
      loop?: boolean;
      coverPrompt?: string;
    })
  | (AiGenerationAssetFields & AiGenerationFalOrderFields & {
      kind: "SPEECH";
      input: string;
      speechVoice?: string;
      speechProviderVoiceId?: string;
    })
  | (AiGenerationAssetFields & AiGenerationFalOrderFields & {
      kind: "VIDEO";
      input: string;
      /** Start frame; image2 is the end frame. */
      image1?: AiGenerationInputReference;
      image2?: AiGenerationInputReference;
      durationSeconds?: 5 | 10;
      /** Text-to-video only; an image start keeps the image's shape. */
      aspectRatio?: "16:9" | "9:16" | "1:1";
    })
  | (AiGenerationAssetFields & AiGenerationFalOrderFields & {
      kind: "MODEL_3D";
      input: string;
      image1?: AiGenerationInputReference;
      /** A second view; needs high quality. */
      image2?: AiGenerationInputReference;
      targetPolycount?: number;
      shouldTexture?: boolean;
      outputFormat?: "GLB";
      /** Agentic asset job; the typed Hive definition owns the method and the price is per unit. */
      assetJob?: AssetJobRequest;
    });

export interface AiGenerationResponse {
  id: string;
  type: AgentTaskGenerationKind;
  status: "SUCCESS" | "FAILURE";
  provider: string;
  model: string;
  inputData: JsonValue | null;
  inputAssets: string[];
  outputData: JsonValue | null;
  outputAssets: string[];
  amount: number;
  paidBy: "USER" | "CREATOR";
  transactionId: number | null;
  agentTaskId: number | null;
  agentTaskAttempt: number | null;
  errorCode: string | null;
  errorMessage: string | null;
  createdAt: string;
  completedAt: string | null;
}

export const AGENT_EXECUTION_TARGET_VALUES = ["FIRST_PARTY", "PERSONAL"] as const;

export type AgentExecutionTarget = (typeof AGENT_EXECUTION_TARGET_VALUES)[number];

export const AGENT_RUNTIME_VALUES = ["CODEX", "CLAUDE_CODE", "GROK_BUILD", "ANTIGRAVITY", "CURSOR_COMPOSER"] as const;

export type AgentRuntime = (typeof AGENT_RUNTIME_VALUES)[number];

export const AGENT_TASK_EFFORT_VALUES = ["simple", "standard", "complex"] as const;

export type AgentTaskEffort = (typeof AGENT_TASK_EFFORT_VALUES)[number];

export const AGENT_TASK_EFFORT_KIND_VALUES = ["BUILD_COMPLEXITY", "CHANGE_MAGNITUDE", "REVIEW_DEPTH"] as const;

export type AgentTaskEffortKind = (typeof AGENT_TASK_EFFORT_KIND_VALUES)[number];

export const AGENT_TASK_AVAILABILITY_FAILURE_REASON_VALUES = [
  "agent_not_installed",
  "agent_not_authenticated",
  "agent_quota_exhausted",
  "agent_temporarily_unavailable",
  "unavailable_runtime",
  "agent_model_unsupported",
  "worker_capability_missing",
] as const;

export type AgentAvailabilityFailureReason = (typeof AGENT_TASK_AVAILABILITY_FAILURE_REASON_VALUES)[number];

export interface AgentAttemptOption {
  agent: AgentRuntime;
  model: string;
  reasoningEffort?: string | null;
  /** Host-local provider profile; omitted uses that host's configured default. */
  accountId?: string | null;
}

export interface AgentAttemptPlan {
  options: AgentAttemptOption[];
  roles?: { supervisor: AgentAttemptOption[]; work: AgentAttemptOption[]; review: AgentAttemptOption[] };
  supervisor?: AgentAttemptOption;
  maxWorkSessions?: number;
}

export interface AgentTaskSelectedAttempt extends AgentAttemptOption {
  /** Present only when the delivered assignment ran the supervisor and work session split. */
  supervised?: boolean;
}

export interface AgentAttemptResult {
  accountId?: string | null;
  attemptIndex: number;
  agent: AgentRuntime;
  model: string;
  reasoningEffort?: string | null;
  workerId?: number | null;
  retryOnAlternateWorker?: boolean;
  status: "selected" | "unavailable" | "started" | "completed" | "failed";
  reason?: AgentAvailabilityFailureReason | string | null;
  message?: string | null;
  source?: "server" | "worker";
  recordedAt: string;
}

export const AGENT_TASK_EVENT_KIND_VALUES = ["progress", "agent_message", "system", "catalogue_preview"] as const;

export type AgentTaskEventKind = (typeof AGENT_TASK_EVENT_KIND_VALUES)[number];

export interface AgentTaskEnrichmentResponse {
  title: string | null;
  summary: string | null;
  safetyFlags: string[];
}

export interface AgentTaskDurationEstimate {
  min: number;
  max: number;
}

export interface AgentTaskTerminalReason {
  kind: "failure" | "expiration" | "cancellation";
  category:
    | "provider_capacity"
    | "provider_connection"
    | "provider_timeout"
    | "provider_failure"
    | "instrument_error"
    | "upload_validation"
    | "agent_failure"
    | "screening_refused"
    | "queue_expired"
    | "cancelled";
  code: string;
  message: string;
  /** Whether automatic recovery may retry unchanged input; does not authorize or forbid an explicit creator retry. */
  retryable: boolean;
  source: "server" | "worker" | "agent" | "provider" | "instrument";
  /** Why an uploaded version was not marked done (agent_exited_after_upload_without_task_done, or a deadline after upload). */
  blocker?: AgentTaskUploadedWithoutCompletionBlocker;
  /** Semver of that uploaded version, when the worker knew it. */
  uploadedVersion?: string;
}

export const AGENT_TASK_UPLOADED_WITHOUT_COMPLETION_BLOCKERS = [
  "review_timeout",
  "review_incomplete",
  "review_changes",
  "deadline_after_upload",
  "usage_limit",
  "unconfirmed",
] as const;

export type AgentTaskUploadedWithoutCompletionBlocker = (typeof AGENT_TASK_UPLOADED_WITHOUT_COMPLETION_BLOCKERS)[number];

export interface AgentTaskRefundResponse {
  state: "refunded" | "withheld";
  credits: number;
  note: string;
}

export interface AgentTaskSubjectResponse {
  creatorUsername: string | null;
  appId: number | null;
  appSlug: string | null;
  appDisplayName: string | null;
  appVersionId: number | null;
  version: string | null;
}

export const AGENT_TASK_NEXT_STEP_CATEGORIES = [
  "POLISH",
  "CONTENT",
  "MECHANICS",
  "VISUALS",
  "AUDIO",
  "MONETIZATION",
  "PUBLISHING",
] as const;

export type AgentTaskNextStepCategory = (typeof AGENT_TASK_NEXT_STEP_CATEGORIES)[number];

export interface AgentTaskNextStepSuggestion {
  id: string;
  title: string;
  description: string;
  prompt: string;
  category: AgentTaskNextStepCategory;
}

/** Read-only observations of existing publication rules, never a per-task visibility override. */
export interface AgentTaskPublicationResponse {
  observedAt: string;
  /** Settings at observation time; they may change before completion, and publication may not succeed. */
  destination: {
    visibility: GameVisibility | null;
    source: "ACCOUNT_AUTO_PUBLISH" | "APP" | "UNKNOWN";
  };
  /** Where this task's version ends up when task done publishes it, with the reason, read before the builder writes
   * its summary (Scrum 203540: builders told creators "public" for versions that stayed private). Optional for older
   * servers. tellCreator is the plain sentence the summary must not contradict. */
  finalDestination?: {
    state: "PUBLISHED" | "PUBLISHES_AT_DONE" | "STAYS_UNPUBLISHED" | "UNKNOWN";
    visibility: GameVisibility | null;
    reason: "ACCOUNT_AUTO_PUBLISH" | "APP" | "KEEP_UNPUBLISHED" | "CREATOR_APPROVAL_IN_BRIEF" | "ULTRA_CREATOR_PUBLISHES" |
      "MODERATION_BLOCKED" | "UNKNOWN";
    tellCreator: string;
  };
  /** Current database state of this task's output. Completion publication can still be pending.
   * PRIVATE with isCurrent=true is a published private game, not a draft. */
  output: {
    appId: number;
    appVersionId: number;
    appVisibility: GameVisibility;
    versionVisibility: AppVersionVisibility;
    isCurrent: boolean;
  } | null;
}

export interface AgentTaskResponseBase {
  reviewRevision?: number;
  revision?: number;
  runtimeVersion?: number;
  taskDefinition?: import("./task-definitions.js").TaskDefinitionSnapshot | null;
  id: number;
  outputs?: AgentTaskOutputResponse[];
  progress?: import("./agent-task-progress").AgentTaskProgressReport | null;
  environment: AgentTaskExecutionEnvironment;
  workflow?: import("./workflows.js").AgentTaskWorkflow;
  stage?: import("./workflows.js").AgentTaskStage;
  round?: number;
  agentBundleSha?: string | null;
  workerCliVersion: string | null;
  platformReleaseSha: string | null;
  /** Optional domain operation for creator billing/output; identity comes from taskDefinition. */
  kind: AgentTaskKind | null;
  status: AgentTaskStatus;
  phase: AgentTaskPhase;
  provider: AgentTaskProvider | null;
  visibility: AgentTaskVisibility;
  /** Worker-only publication observation, separate from the task audience in visibility. */
  publication?: AgentTaskPublicationResponse | null;
  parentTaskId: number | null;
  parentTaskAttempt: number | null;
  authorizationId?: string | null;
  providerEndpoint: string | null;
  providerRequestId: string | null;
  outputFormat: string | null;
  executionTarget: AgentExecutionTarget;
  agent: AgentRuntime | null;
  model: string | null;
  estimatedDurationMinutes?: AgentTaskDurationEstimate | null;
  attemptPlan?: AgentAttemptPlan | null;
  selectedAttempt?: AgentTaskSelectedAttempt | null;
  attemptResults?: AgentAttemptResult[];
  effort: AgentTaskEffort | null;
  effortKind: AgentTaskEffortKind | null;
  appOrigin: AppOrigin | null;
  outputVersion: string | null;
  claimedAppName: string | null;
  claimedDisplayName: string | null;
  claimedSubtitle: string | null;
  claimedPrimarySurface: AppSurface | null;
  userInput: string | null;
  enrichment: AgentTaskEnrichmentResponse | null;
  subject: AgentTaskSubjectResponse;
  creatorId?: number;
  creatorUsername?: string | null;
  baseAppId: number | null;
  baseAppVersionId: number | null;
  appId: number | null;
  appVersionId: number | null;
  costCredits: number;
  fundingSource: CreatorTaskFundingSource;
  freeCloudGenerationTransactionId: number | null;
  usesFreeCloudGeneration: boolean;
  refund: AgentTaskRefundResponse | null;
  payload?: {
    classification?: import("./agent-task-classification.js").AgentTaskClassification;
    classificationPromptVersion?: number;
    safety?: Record<string, unknown>;
    model?: string;
    [key: string]: unknown;
  };
  result: Record<string, unknown> | null;
  completionSummary: string | null;
  nextSteps: AgentTaskNextStepSuggestion[];
  creatorFeedbackStatus: AgentTaskCreatorFeedbackStatus;
  error: string | null;
  terminalReason: AgentTaskTerminalReason | null;
  workerId?: number | null;
  workerName?: string | null;
  lastHeartbeatAt: string | null;
  cancelRequestedAt: string | null;
  attempts: number;
  queuePosition: number | null;
  tokensUsed: number | null;
  latestCataloguePreviewEvent?: AgentTaskEventResponse | null;
  createdAt: string;
  startedAt: string | null;
  completedAt: string | null;
  updatedAt: string;
}

export type AgentTaskGenerationResult =
  | { generationId: string; text: string }
  | { generationId: string; json: JsonValue }
  | {
      generationId: string;
      assetId: number;
      assetVersionId: number;
      assetRef: string;
    };

export type GenerationAgentTaskResponse = {
  [K in AgentTaskGenerationKind]: AgentTaskResponseBase & {
    kind: K;
    provider: AgentTaskProvider;
    request: Extract<CreateAiGenerationTaskRequest, { kind: K }>;
    result: AgentTaskGenerationResult | null;
  };
}[AgentTaskGenerationKind];

export interface AgentTaskEventResponse {
  id: number;
  taskId: number;
  attempt: number;
  kind: AgentTaskEventKind;
  phase: string | null;
  message: string;
  done?: string | null;
  current?: string | null;
  pct: number | null;
  payload?: Record<string, unknown> | null;
  createdAt: string;
}

export interface AgentTaskOutputResponse {
  id: number;
  taskId: number;
  attempt: number;
  clientKey: string;
  appVersionId: number | null;
  version: string | null;
  commitSha: string | null;
  isFinal: boolean;
  snapshot: import("./agent-task-output").AgentTaskOutputSnapshot;
  createdAt: string;
}

export type CreatorTaskFundingSource = "INCLUDED" | "CREDITS" | "MIXED" | "PERSONAL" | "PLATFORM";

export interface TagGroupSummary {
  slug: string;
  displayName: string;
  allowedTargetKinds: SavedItemKind[];
  createdAt: string;
  updatedAt: string;
}

export interface TagSummary extends ContentTagSummary {
  createdAt: string;
  updatedAt: string;
}

export interface TagGroupWithTagsSummary extends TagGroupSummary {
  tags: TagSummary[];
}

export const APP_PUBLICATION_KIND_VALUES = ["CLOUD", "UPLOAD", "EXTERNAL"] as const;

export type AppPublicationKind = (typeof APP_PUBLICATION_KIND_VALUES)[number];

/**
 * The owner's two buttons on their own game page (owner, October 30, 2026), on the app detail read for the owner and
 * admins only. Play is enabled for a Public or Unlisted game whose Live version can be played, else carries the reason;
 * Studio opens Playtest of the latest version.
 */
export interface AppOwnerActions {
  play: { enabled: boolean; reason?: string };
  studio: {
    href: string;
    /** The version newer than the Live one, when there is one: the "Newer draft in Studio" callout remembers it. */
    newerDraft?: string;
  };
  /** A game never published: the page is the owner's preview, labelled with this. */
  draft?: { label: string };
}

export interface AppResponse {
  nativeGameMode?: import("./experiments.js").NativeGameMode;
  /** Server capability advertised for registered templates. */
  templateReportSchemaVersion?: 2;
  listingImageBaseUrl?: string | null;
  sourceLocale?: string | null;
  displayedLocale?: string | null;
  listingSourceHash?: string | null;
  availableListingLocales?: string[];
  id?: number;
  name: string;
  displayName: string;
  /** Original listing name when the selected translation uses a different name. */
  sourceDisplayName?: string;
  subtitle?: string | null;
  description: string;
  /** Short localized prompt for creating a game inspired by this listing. */
  inspirationPrompt?: string | null;
  creatorId?: number;
  creatorUsername: string;
  createdAt: string;
  updatedAt: string;
  origin?: AppOrigin;
  publicationKind?: AppPublicationKind;
  type: AppType;
  emoji?: string | null;
  color?: string | null;
  lastPlayedAt?: string;

  // Version info (from currentVersion)
  /** Current version string (e.g., "1.2.3"), null if no versions exist */
  currentVersion?: string | null;
  /** Database id of the current version, null if no current version exists */
  currentVersionId?: number | null;
  /** Server-stamped publishing surface provenance of the current version. */
  publishSource?: string | null;
  /** Hosting mode of current version */
  hostingMode?: AppHostingMode;
  /** Auth mode of current version */
  authMode?: AppAuthMode;
  /** Controller mode of current version */
  controllerMode?: AppControllerMode;
  /** Whether the current hosted version can boot as a non-interactive detail-page preview */
  previewable?: boolean;
  /** Whether the current version is an instant game: small startup files, live in the Instant feed. */
  instant?: boolean;
  /** Whether the current hosted version exposes an owner-only creator Editor. */
  editorSupported?: boolean;
  /** Whether the current hosted version declares a PlayDrop-hosted game server. */
  hasServer?: boolean;
  /** Visibility of current version */
  visibility?: AppVersionVisibility;
  /** The game's audience: who can open and find it. */
  gameVisibility?: GameVisibility;
  /** Review state of current version */
  reviewState?: ReviewState;
  reviewStartedAt?: string | null;
  reviewCompletedAt?: string | null;
  /** License of the current version */
  license?: ContentLicense;
  /** Server-derived capability flags for the current version */
  permissions?: ContentPermissions;
  /** Base URL for loading the app (from current version) */
  assetUrl: string | null;
  /** Entry point file within assetUrl */
  entryPoint?: string | null;
  /** The current version's launch descriptor, as on Instant feed entries: hosted, public instant games only. */
  launch?: DiscoveryLaunch | null;
  /** Surface targets from current version (undefined for draft apps with no version) */
  surfaceTargets?: AppSurface[];
  primarySurface?: AppSurface | null;
  playtestTapes?: AppPlaytestTapes | null;
  design?: AppVersionDesign | null;
  players?: AppPlayersConfig | null;
  /**
   * The two listing facts (controller, player) from the version's play declaration or legacy fields. This API always
   * sends it; launch manifests published before controllers phase 1 and local dev servers omit it.
   */
  listingAttributes?: GameListingAttributes;
  /** Controller facts for native hosts (`controllerPlayFacts`); omitted when controller support is off. */
  controllerPlay?: ControllerPlayFacts;
  /** The exact new-format declaration, when the version was uploaded with one. */
  play?: AppPlayDeclaration;
  makingOf?: string | null;
  controls?: string | null;
  creation?: AppCreationMetadata | null;
  /** How players tip this game; null on a private game (and on a game nobody can play yet). */
  tips?: AppTipping | null;
  sourceRepository?: string | null;
  editorialNote?: string | null;
  /** Asset spec support declarations from the current version */
  assetSpecSupport?: AppMetadataAssetSpecSupport[];

  // HOSTED mode fields (from current version)
  bundleSize?: number | null;

  // Listing URLs (from current version)
  iconUrl?: string | null;
  heroPortraitUrl?: string | null;
  heroLandscapeUrl?: string | null;
  socialLandscapeUrl?: string | null;
  screenshotPortraitUrls?: string[];
  screenshotLandscapeUrls?: string[];
  videoPortraitUrls?: string[];
  videoLandscapeUrls?: string[];
  /** Structured listing media with stable slugs and descriptive metadata. */
  listingMedia?: AppListingMediaItem[];
  /** YouTube videos for the media gallery, after the game's own videos (pilot: internal accounts). */
  youtubeVideos?: AppListingYouTubeVideo[];
  friendsWhoPlayed?: HomeGameFriendsWhoPlayed;
  viewerSaved?: boolean;
  viewerLiked?: boolean;
  viewerDisliked?: boolean;
  likeCount?: number;
  dislikeCount?: number;
  /** Detail snapshot's persisted engagement threshold; never overrides publication or review eligibility. */
  seoEngagementEligible?: boolean;
  /** Game detail for its owner (and admins) only. */
  ownerActions?: AppOwnerActions;
  viewCount?: number;
  playCount?: number;
  commentCount?: number;
  /** Game detail only: how many achievements and leaderboards the game has. */
  achievementCount?: number;
  leaderboardCount?: number;
  remixCount?: number;
  remixedFrom?: RemixRelatedItemSummary[];
  boostedUntil?: string | null;
  promotionSource?: string | null;
  campaignSource?: "paid_boost" | "curated";
  promotionToken?: string | null;
  tags: ContentTagSummary[];
}

/**
 * Compact app payload used by home rails and collection pages.
 *
 * Keep this limited to fields required to render and route an app card, filter
 * by launch capability, show card media, and preserve engagement or promotion
 * context. Detail-page metadata belongs on AppResponse instead.
 */
export interface HomeGameFriendsWhoPlayed {
  total: number;
  /** Up to three friends, ordered by most recent qualified play. avatarUrl is the account's
   * profile photo, never a game avatar; null means clients display initials. */
  friends: Array<{ id: number; username: string; displayName: string; avatarUrl: string | null }>;
}

export interface AppRuntimeAssetFileSummary {
  role: string;
  url: string;
  contentType?: string | null;
  sizeBytes?: number | null;
  sha256?: string | null;
}

export interface AppRuntimeAssetSummary {
  assetRef: string;
  runtimeKey: string | null;
  sourceType: "OWNED" | "DIRECT" | "PACK";
  sourcePackRef?: string | null;
  files: AppRuntimeAssetFileSummary[];
}

type RemixRelatedItemSummaryBase = {
  creatorUsername: string;
  name: string;
  displayName: string | null;
  linkedVersionRef: string | null;
};

export type RemixRelatedItemSummary =
  | ({
      kind: "APP";
      appType: AppType;
    } & RemixRelatedItemSummaryBase)
  | ({
      kind: "ASSET";
    } & RemixRelatedItemSummaryBase)
  | ({
      kind: "PACK";
    } & RemixRelatedItemSummaryBase);

export interface PaginationMeta {
  limit: number;
  offset: number;
  count: number;
  hasMore: boolean;
}

export const SEARCH_KIND_VALUES = ["all", ...SEARCH_RESULT_KIND_VALUES] as const;

export type SearchKind = (typeof SEARCH_KIND_VALUES)[number];

export const SEARCH_MODE_VALUES = ["grouped", "flat"] as const;

export type SearchMode = (typeof SEARCH_MODE_VALUES)[number];

export const SEARCH_ASSET_TYPE_VALUES = ["image", "video", "audio", "song", "sfx", "3d"] as const;

export type SearchAssetType = (typeof SEARCH_ASSET_TYPE_VALUES)[number];

export const SEARCH_SORT_VALUES = [
  "relevance",
  "views",
  "recent",
  "updated",
  "used",
  "newest",
  "likes",
  "downloads",
  "remixes",
  "comments",
  "assets",
  "apps",
  "alpha",
] as const;

export type SearchSort = (typeof SEARCH_SORT_VALUES)[number];

export interface SearchRequest {
  q: string;
  mode?: SearchMode;
  kind?: SearchKind;
  sort?: SearchSort;
  creatorUsername?: string;
  page?: number;
  pageSize?: number;
  appType?: AppType;
  auth?: AppAuthFilter;
  surface?: AppSurfaceFilter;
  controller?: AppControllerFilter;
  assetType?: SearchAssetType;
  assetCategory?: AssetCategory;
  assetSubcategory?: string;
  assetSpec?: string;
  assetSpecOwner?: string;
  assetSpecName?: string;
  packContainsCategory?: AssetCategory;
  packContainsSubcategory?: string;
  tags?: string[];
  includeCounts?: boolean;
}

export interface SearchCountsByKind {
  creator: number;
  app: number;
  asset: number;
  assetSpec: number;
  pack: number;
  total: number;
}

export interface SearchTabCounts {
  topResults: number;
  creators: number;
  apps: number;
  demos: number;
  tools: number;
  templates: number;
  images: number;
  videos: number;
  audio: number;
  songs: number;
  sfx: number;
  models3d: number;
  assetSpecs: number;
  packs: number;
}

export interface HomeCreatorResponse {
  id: number;
  username: string;
  displayName: string;
  profileAssetPreviewUrl: string | null;
  xProfileImageUrl: string | null;
  googleProfileImageUrl: string | null;
  createdAt?: string;
  viewerFollowing?: boolean;
  followsViewer?: boolean;
  /** Count for the collection's selected ranking metric and period. */
  rankingCount?: number;
}

export const SAVED_ITEM_KIND_VALUES = ["APP", "ASSET", "PACK"] as const;

export type SavedItemKind = (typeof SAVED_ITEM_KIND_VALUES)[number];

export interface TagListResponse {
  groups: TagGroupWithTagsSummary[];
  pagination: PaginationMeta;
}

export interface TagDetailResponse {
  tag: TagSummary & {
    group: TagGroupSummary;
  };
}

export interface CreatorSearchResult {
  kind: "creator";
  targetPath: string;
  creator: HomeCreatorResponse;
}

export interface AppSearchResult {
  kind: "app";
  targetPath: string;
  app: AppResponse;
}

export interface AssetSearchResult {
  kind: "asset";
  targetPath: string;
  asset: AssetResponse;
}

export interface AssetPackSearchResult {
  kind: "pack";
  targetPath: string;
  pack: AssetPackResponse;
}

export type SearchResult =
  CreatorSearchResult | AppSearchResult | AssetSearchResult | AssetSpecSearchResult | AssetPackSearchResult;

export interface SearchGroupedResults {
  creators: CreatorSearchResult[];
  apps: AppSearchResult[];
  assets: AssetSearchResult[];
  assetSpecs: AssetSpecSearchResult[];
  packs: AssetPackSearchResult[];
}

export interface SearchResponse {
  q: string;
  mode: SearchMode;
  kind: SearchKind;
  countsByKind: SearchCountsByKind;
  tabCounts: SearchTabCounts;
  groups?: SearchGroupedResults;
  results?: SearchResult[];
  pagination?: PaginationMeta;
}

export type CreditTransactionKind = "CONSUMABLE" | "ENTITLEMENT";

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

/** `expired` is a legacy invalid-reservation status; inspect reason/message for the cause. */
export type AdInterstitialShowStatus = "dismissed" | "not_ready" | "expired";

export type AdRewardedShowStatus = "completed" | "dismissed" | "not_ready" | "expired";

/** Machine-readable cause of a failed ad show. Older hosts may omit failure details. */
export type AdShowFailureReason =
  | "ad_campaign_inactive"
  | "ad_campaign_completed"
  | "ad_target_unavailable"
  | "ad_cancelled"
  | "ad_already_consumed"
  | "ad_not_ready"
  | "host_error"
  | "ad_expired";

export interface AdShowFailureDetails {
  /** Why no impression/reward was accepted; absent on success or older hosts. */
  reason?: AdShowFailureReason;
  /** Developer-readable explanation, not localized player-facing copy. */
  message?: string;
}

export interface AdShowResult<
  Status extends AdInterstitialShowStatus | AdRewardedShowStatus = AdInterstitialShowStatus | AdRewardedShowStatus,
> extends AdShowFailureDetails {
  /** Grant a reward exactly once, and only for `completed`. */
  status: Status;
}

export type AdLoadResult =
  | { status: "ready" }
  | { status: "no_fill" }
  | { status: "rate_limited"; retryAfterSeconds: number }
  | { status: "blocked"; reason: string };

export interface IapReceipt {
  id: number;
  type: string;
  kind: CreditTransactionKind;
  status: CreditTransactionStatus;
  displayName: string;
  sku: string | null;
  amount: number;
  creatorPayoutAmount: number | null;
  platformFeeAmount: number | null;
  sourceId: number;
  sourceName: string;
  buyerId: number;
  buyer: string;
  sellerId: number;
  seller: string;
  createdAt: string;
  updatedAt: string;
  /** Present on an offline purchase whose price the buyer's balance could not fully cover. */
  writtenOffCredits?: number;
}

export type ShopReceiptKindInput = CreditTransactionKind | "consumable" | "entitlement";

export type ShopReceiptStatus = CreditTransactionStatus;

export type ShopReceipt = IapReceipt;

export interface VerifyShopReceiptOptions {
  sku?: string;
  amount?: number;
  priceCredits?: number;
  kind?: ShopReceiptKindInput;
  status?: ShopReceiptStatus | readonly ShopReceiptStatus[];
}

export interface SettleShopReceiptOptions {
  sku?: string;
  amount?: number;
  priceCredits?: number;
  kind?: ShopReceiptKindInput;
}
```

## packages/types/src/experiments.ts

```ts
export type NativeGameMode = "web-native" | "nudge-native" | "force-native";
```

## packages/types/src/discovery.ts

```ts
/** An immutable, digest-addressed public runtime manifest. */
export type DiscoveryLaunchManifest = { url: string; sha256: string; sizeBytes: number; appVersionId: number; appVersion: string };

/**
 * Everything a host needs to create a game's frame with no further read: the public, versioned frame URL (the asset
 * folder plus the entry point; the host adds its channel and origin parameters) and the runtime manifest. Sent for
 * hosted, public instant games only.
 */
export type DiscoveryLaunch = { runtimeUrl: string; manifest: DiscoveryLaunchManifest };
```

## packages/types/src/app-playtest-tape.ts

```ts
export const APP_PLAYTEST_TAPE_VERSION = 1 as const;

export const APP_PLAYTEST_PRIMARY_VERB_VALUES = ["tap", "swipe", "drag", "key"] as const;

export type AppPlaytestPrimaryVerb = (typeof APP_PLAYTEST_PRIMARY_VERB_VALUES)[number];

export const APP_PLAYTEST_SUCCESS_SIGNAL_KIND_VALUES = [
  "SURVIVE_LONGER",
  "SCORE_ABOVE_IDLE",
  "VISIBLE_PROGRESS",
  "STATE_REACHED",
] as const;

export type AppPlaytestSuccessSignalKind = (typeof APP_PLAYTEST_SUCCESS_SIGNAL_KIND_VALUES)[number];

export type AppPlaytestSuccessSignal = {
  kind: AppPlaytestSuccessSignalKind;
  description: string;
};

type AppPlaytestTimedEvent = {
  atMs: number;
};

export type AppPlaytestPointerEvent = AppPlaytestTimedEvent & {
  type: "pointerDown" | "pointerMove" | "pointerUp";
  x: number;
  y: number;
  pointerId?: number;
};

export type AppPlaytestTapEvent = AppPlaytestTimedEvent & {
  type: "tap";
  x: number;
  y: number;
  durationMs?: number;
};

export type AppPlaytestKeyboardEvent = AppPlaytestTimedEvent & {
  type: "keyDown" | "keyUp";
  key: string;
};

export type AppPlaytestTapeEvent = AppPlaytestPointerEvent | AppPlaytestTapEvent | AppPlaytestKeyboardEvent;

export type AppPlaytestTape = {
  version: typeof APP_PLAYTEST_TAPE_VERSION;
  primaryVerb: AppPlaytestPrimaryVerb;
  durationMs: number;
  startOnlyEventCount: number;
  successSignals: AppPlaytestSuccessSignal[];
  events: AppPlaytestTapeEvent[];
};

export type AppPlaytestTapes = Partial<Record<AppSurface, AppPlaytestTape>>;
```

## packages/types/src/play.ts

```ts
/**
 * Author-facing play declaration (catalogue `types`, `party`, `async`, `challenge`, `controller`, `roomVoice`), its legacy projection,
 * the two listing attributes and the controller eligibility used by listings, launch and discovery.
 * One calculation for every platform: clients render the result, they never re-derive it.
 */

export const APP_PLAY_TYPE_VALUES = ["solo", "online", "party"] as const;

export type AppPlayType = (typeof APP_PLAY_TYPE_VALUES)[number];

/** Minimum controls a game needs. `custom` is reserved until the controller-page runtime ships. */
export const APP_CONTROLLER_PROFILE_VALUES = ["any", "simpler", "standard", "custom"] as const;

export type AppControllerProfile = (typeof APP_CONTROLLER_PROFILE_VALUES)[number];

export type PublishableControllerProfile = Exclude<AppControllerProfile, "custom">;

export type AppPlayController =
  | { support: "off" }
  | { support: "optional" | "required"; type: PublishableControllerProfile };

/** Normalized new-format declaration, stored as-is on the app version. */
export interface AppPlayDeclaration {
  types: AppPlayType[];
  party?: { local?: number[]; online?: number[] };
  /** Friend-chat async play, currently one player and one friend. */
  async?: { friend: [2] };
  /**
   * Score challenges in conversations (wiki/game-challenges.md): the key of one of the app's declared leaderboards.
   * Only its shape is checked here; catalogues and publishing check that the leaderboard exists and is not retired.
   */
  challenge?: { leaderboard: string };
  controller: AppPlayController;
  roomVoice?: true;
}

export type GameListingControllerAttribute =
  | { kind: "unsupported" }
  | { kind: "supported" }
  | { kind: "counts"; counts: string; source?: "virtual" | "physical" };

export interface GameListingPlayerAttribute {
  solo: boolean;
  online: boolean;
  /** Party sizes ("1-4", "2, 4"): online sizes when declared, otherwise local sizes. */
  party?: string;
}

/** The two owner-specified listing attributes. `player` is null when a legacy version declared no players. */
export interface GameListingAttributes {
  controller: GameListingControllerAttribute;
  player: GameListingPlayerAttribute | null;
}

/**
 * Controller facts for hosts that cannot run these rules themselves (native apps). Omitted (null) when support is off.
 * `counts`: exact local participants Local Players offers. `profile`: the declared minimum controls (null for legacy
 * versions: any physical controller). `phone`: the declared profile accepts the phone pad; a phone still takes a
 * gameplay slot only after the running game enables bridged input.
 */
export interface ControllerPlayFacts {
  counts: number[];
  profile: PublishableControllerProfile | null;
  phone: boolean;
}
```

## packages/types/src/app-listing-youtube.ts

```ts
/**
 * A YouTube video in a game's media gallery, shown after the game's own videos and played only after a tap.
 * Pilot: only internal accounts may publish these (see wiki/listing-youtube-videos.md).
 */
export interface AppListingYouTubeVideo {
  videoId: string;
  /** A Shorts link is upright; every other link is wide. */
  orientation: "PORTRAIT" | "LANDSCAPE";
  startSeconds?: number;
  title?: string;
  caption?: string;
}
```

## packages/types/src/asset-pack.ts

```ts
export const VERSION_VISIBILITY_VALUES = ["PRIVATE", "PUBLIC"] as const;

export type VersionVisibility = (typeof VERSION_VISIBILITY_VALUES)[number];

export type AssetCategoryBreakdown = Partial<Record<AssetCategory, number>>;

export type AssetSubcategoryBreakdown = Partial<Record<string, number>>;

export const ASSET_PACK_UPLOAD_SESSION_STATUS_VALUES = ["OPEN", "FINALIZED", "ABORTED", "EXPIRED"] as const;

export type AssetPackUploadSessionStatus = (typeof ASSET_PACK_UPLOAD_SESSION_STATUS_VALUES)[number];

export interface AssetPackVersionResponse {
  id: number;
  version: string;
  major: number;
  minor: number;
  patch: number;
  visibility: VersionVisibility;
  license: ContentLicense;
  permissions?: ContentPermissions;
  hostingMode: AppHostingMode;
  externalUrl?: string | null;
  downloadUrl?: string | null;
  releaseNotes?: string | null;
  assets: AssetRef[];
  assetCategoryBreakdown?: AssetCategoryBreakdown;
  assetSubcategoryBreakdown?: AssetSubcategoryBreakdown;
  iconUrl?: string | null;
  heroPortraitUrl?: string | null;
  heroLandscapeUrl?: string | null;
  screenshotPortraitUrls?: string[];
  screenshotLandscapeUrls?: string[];
  videoPortraitUrls?: string[];
  videoLandscapeUrls?: string[];
  createdAt: string;
  updatedAt: string;
}

export interface AssetPackResponse {
  id: number;
  name: string;
  displayName: string;
  description?: string | null;
  creatorId: number;
  creatorUsername: string;
  previewAppVersionId?: number | null;
  createdAt: string;
  updatedAt: string;
  currentVersion?: AssetPackVersionResponse | null;
  viewerSaved?: boolean;
  viewerLiked?: boolean;
  viewerDisliked?: boolean;
  likeCount?: number;
  viewCount?: number;
  downloadCount?: number;
  commentCount?: number;
  remixCount?: number;
  tags: ContentTagSummary[];
}

export interface AssetPackUploadSessionState {
  id: string;
  creatorUsername: string;
  packName: string;
  version: string;
  manifestHash: string;
  status: AssetPackUploadSessionStatus;
  expiresAt?: string | null;
  uploadedAssetKeys: string[];
  uploadedMediaKeys: string[];
}

export interface AssetPackUploadedLocalAsset {
  uploadKey: string;
  creatorUsername: string;
  name: string;
  revision: number;
  versionNodeId: string;
}

export interface FinalizeAssetPackUploadResponse {
  status: "finalized";
  packRef: string;
  session: AssetPackUploadSessionState;
  pack: AssetPackResponse;
  version: AssetPackVersionResponse;
  versionNodeId: string;
  uploadedLocalAssets: AssetPackUploadedLocalAsset[];
}

export interface UpdateAssetPackRequest {
  name?: string;
  displayName?: string;
  description?: string | null;
  previewAppVersionId?: number | null;
}

export interface UpdateAssetPackVersionRequest {
  visibility?: VersionVisibility;
  license?: ContentLicense;
  releaseNotes?: string | null;
  setAsCurrent?: boolean;
}

export interface AssetPackListResponse {
  packs: AssetPackResponse[];
  pagination: {
    limit: number;
    offset: number;
    count: number;
    hasMore: boolean;
  };
}

export interface AssetPackVersionsListResponse {
  versions: AssetPackVersionResponse[];
  pagination?: {
    limit: number;
    offset: number;
    count: number;
    hasMore: boolean;
  };
}

export interface UpdateAssetPackResponse {
  pack: AssetPackResponse;
}

export interface UpdateAssetPackVersionResponse {
  version: AssetPackVersionResponse;
}

export interface DeleteAssetPackVersionResponse {
  success: boolean;
}

export interface DeleteAssetPackResponse {
  success: boolean;
}
```

## packages/types/src/graph.ts

```ts
export const RELATION_TYPE_VALUES = ["USES", "CONTAINS", "REMIXES"] as const;

export type RelationType = (typeof RELATION_TYPE_VALUES)[number];

export interface NodeRelationRecord {
  id: number;
  fromNodeId: string;
  toNodeId: string;
  type: RelationType;
  createdAt: string;
  updatedAt: string;
}

export interface BatchUpsertNodeRelationsRequest {
  relations: Array<{
    fromNodeId: string;
    toNodeId: string;
    type: RelationType;
  }>;
}

export interface BatchUpsertNodeRelationsResponse {
  relations: NodeRelationRecord[];
}
```

## packages/types/src/app-capability-filters.ts

```ts
export const APP_AUTH_FILTER_VALUES = ["required", "optional", "none"] as const;

export type AppAuthFilter = (typeof APP_AUTH_FILTER_VALUES)[number];

export const APP_CONTROLLER_FILTER_VALUES = ["required", "optional", "none"] as const;

export type AppControllerFilter = (typeof APP_CONTROLLER_FILTER_VALUES)[number];

export const APP_SURFACE_FILTER_VALUES = ["desktop", "mobile-portrait", "mobile-landscape"] as const;

export type AppSurfaceFilter = (typeof APP_SURFACE_FILTER_VALUES)[number];
```

## packages/types/src/player-meta.ts

```ts
export const PLAYER_META_DEFINITION_STATUS_VALUES = ["ACTIVE", "RETIRED"] as const;

export type PlayerMetaDefinitionStatus = (typeof PLAYER_META_DEFINITION_STATUS_VALUES)[number];

export const APP_ACHIEVEMENT_KIND_VALUES = ["STANDARD", "INCREMENTAL"] as const;

export type AppAchievementKind = (typeof APP_ACHIEVEMENT_KIND_VALUES)[number];

export const APP_LEADERBOARD_SCORE_TYPE_VALUES = ["INTEGER", "TIME_MS"] as const;

export type AppLeaderboardScoreType = (typeof APP_LEADERBOARD_SCORE_TYPE_VALUES)[number];

export const APP_LEADERBOARD_SORT_VALUES = ["DESC", "ASC"] as const;

export type AppLeaderboardSort = (typeof APP_LEADERBOARD_SORT_VALUES)[number];

export interface AppAchievementDefinition {
  key: string;
  displayName: string;
  description: string;
  kind: AppAchievementKind;
  hidden: boolean;
  maxProgress: number | null;
  iconUrl: string;
  status: PlayerMetaDefinitionStatus;
}

export interface AppLeaderboardDefinition {
  key: string;
  displayName: string;
  description: string;
  scoreType: AppLeaderboardScoreType;
  sort: AppLeaderboardSort;
  unitLabel?: string;
  status: PlayerMetaDefinitionStatus;
}

export interface AppAchievementPlayerState {
  progress: number;
  unlocked: boolean;
  unlockedAt: string | null;
}

export interface AppLeaderboardPlayerSummary {
  hasScore: boolean;
  bestScore: number | null;
  rank: number | null;
  bestScoreAt: string | null;
}

export interface AchievementView {
  definition: AppAchievementDefinition;
  player: AppAchievementPlayerState | null;
}

export interface LeaderboardSummary {
  definition: AppLeaderboardDefinition;
  player: AppLeaderboardPlayerSummary | null;
}

export interface LeaderboardEntryUser {
  publicPlayerId: string;
  username?: string;
  displayName: string;
  /**
   * For a game (`sdk.leaderboards`, runtime auth): the one picture, the provider photo first, else the avatar. For
   * PlayDrop's clients: the avatar, else a provider photo; they show the provider photos first and fall back to it.
   */
  avatarUrl?: string;
  /** Provider photos. */
  xProfileImageUrl?: string;
  googleProfileImageUrl?: string;
  profilePath?: string;
}

export interface LeaderboardEntry {
  rank: number;
  score: number;
  bestScoreAt: string;
  isCurrentPlayer?: boolean;
  user: LeaderboardEntryUser;
}

export interface LeaderboardView {
  definition: AppLeaderboardDefinition;
  top: LeaderboardEntry[];
  player: AppLeaderboardPlayerSummary | null;
  playerEntry: LeaderboardEntry | null;
  aroundPlayer: LeaderboardEntry[];
}

export interface ListAchievementsResponse {
  achievements: AchievementView[];
}

export interface GetAchievementResponse {
  achievement: AchievementView;
}

export interface AppAchievementMutationSummary {
  key: string;
  displayName: string;
  iconUrl: string;
}

export interface UnlockAchievementResponse {
  accepted: true;
  changed: boolean;
  unlocked: boolean;
  progress: number;
  unlockedAt: string | null;
  achievement: AppAchievementMutationSummary;
}

export interface SetAchievementProgressResponse {
  accepted: true;
  changed: boolean;
  unlocked: boolean;
  progress: number;
  unlockedAt: string | null;
  achievement: AppAchievementMutationSummary;
}

export interface ListLeaderboardsResponse {
  leaderboards: LeaderboardSummary[];
}

export interface GetLeaderboardResponse {
  leaderboard: LeaderboardView;
}

export interface AppLeaderboardMutationSummary {
  key: string;
  displayName: string;
  scoreType: AppLeaderboardScoreType;
  unitLabel?: string;
}

export interface SubmitLeaderboardScoreResponse {
  accepted: true;
  improved: boolean;
  previousBestScore: number | null;
  bestScore: number;
  rank: number | null;
  previousRank: number | null;
  bestScoreAt: string;
  leaderboard: AppLeaderboardMutationSummary;
}
```

## packages/types/src/play-together.ts

```ts
/** Host-owned online social state. Games receive only this read-only snapshot. */
export interface PartyMember {
  userId: number;
  username: string;
  displayName: string;
  joinedAt: string;
  connectionState?: "connected" | "reconnecting" | "disconnected";
  /** Host-only public image, resolved with the shared provider-first image policy. */
  avatarUrl?: string | null;
  /** Unknown means a connected legacy host has not reported microphone state. */
  voiceState?: "muted" | "unmuted" | "disconnected" | "unknown";
  /** The game this member's host reports open right now (host UI only, never sent to games). */
  playing?: PartyMemberPlaying | null;
}

/** A party member's current game, as `POST /parties/activity` reported it. */
export interface PartyMemberPlaying {
  appId: number;
  appVersionId: number;
  creatorUsername: string;
  name: string;
  displayName: string;
  iconUrl: string | null;
}

/** A host-selected public game page. Navigation never grants room admission or starts playback. */
export interface PartyBrowseTarget {
  partyId: string;
  leaderUserId: number;
  /** Party revision at the moment this page was selected. */
  revision: number;
  appId: number;
  appVersionId: number;
  creatorUsername: string;
  name: string;
  displayName: string;
}

export interface Party {
  /** Host-controlled availability; omitted by older servers means enabled. */
  voiceEnabled?: boolean;
  partyId: string;
  leaderUserId: number;
  revision: number;
  conversationId: string;
  members: PartyMember[];
  playTarget?: PartyPlayTarget | null;
  browseTarget?: PartyBrowseTarget | null;
  /** Revision when the host entered Find games or selected a game. Null after leaving or launching. */
  choosingGameRevision?: number | null;
  invitations?: Array<Pick<PartyMember, "userId" | "username" | "displayName" | "avatarUrl"> & { expiresAt: string }>;
}

export type RoomVoiceAudience = "all" | "team" | "proximity" | "off";

export interface PartyPlayTarget {
  /** Absolute server deadline for automatic readiness acknowledgements (Unix milliseconds). */
  ackDeadline?: number;
  /** Host-owned playback; separate from room admission state. */
  playback?: "playing" | "paused" | "stopped";
  controlRevision?: number;
  pendingUserIds?: number[];
  joinedUserIds?: number[];
  partyId: string;
  revision: number;
  appId: number;
  appVersionId: number;
  creatorUsername: string;
  name: string;
  /** Human-readable destination title; name remains the stable routing slug. */
  displayName?: string;
  version: string;
  participantUserIds: number[];
  status: "proposed" | "joining" | "ready" | "failed";
  roomId?: string;
  error?: string;
}

/**
 * Where one person stands relative to this game: `invited` (invitation not answered yet), `inParty` (in the party but
 * not coming to this game), `joining` (on the way into this game's party room), `inGame` (in that room, or with this
 * game open when no party launch is running) and `disconnected` (lost connection; PlayDrop keeps the place briefly).
 */
export type GamePartyParticipantState = "invited" | "inParty" | "joining" | "inGame" | "disconnected";

export interface GamePartyParticipant {
  userId: number;
  username: string;
  displayName: string;
  state: GamePartyParticipantState;
}

/** A launch is visible only to an accepted participant inside its destination game. */
export type GameParty = Pick<Party, "partyId" | "leaderUserId" | "revision"> & {
  members: Pick<PartyMember, "userId" | "username" | "displayName" | "joinedAt">[];
  /** Members (leader first) followed by people with an outstanding invitation. Absent from older hosts. */
  participants?: GamePartyParticipant[];
  launch?: { revision: number; status: "joining" | "ready"; roomId?: string };
};
```

## packages/types/src/asset-jobs.ts

```ts
export const ASSET_JOB_TYPE_VALUES = [
  "procedural-2d",
  "character-2d",
  "voxel-3d",
  "procedural-3d",
  "character-3d",
  "avatar-skin",
  "vfx-3d",
  "pack-image-2d",
  "pack-procedural-2d",
  "pack-procedural-3d",
] as const;

export type AssetJobType = (typeof ASSET_JOB_TYPE_VALUES)[number];

export const ASSET_JOB_2D_STYLES = ["pixel", "vector"] as const;

export type AssetJob2DStyle = (typeof ASSET_JOB_2D_STYLES)[number];

export const ASSET_JOB_CHARACTER_2D_VIEWS = ["side", "top-down-4", "top-down-8"] as const;

export type AssetJobCharacter2DView = (typeof ASSET_JOB_CHARACTER_2D_VIEWS)[number];

export interface AssetJobPackItem {
  name: string;
  prompt: string;
}

export interface AssetJobRequest {
  type: AssetJobType;
  style?: AssetJob2DStyle;
  view?: AssetJobCharacter2DView;
  /** Animations beyond the standard set; each is billed as one extra unit (one more rigging clip for 3D). */
  extraAnimations?: string[];
  /** 3D characters only; both use Meshy and cost the same (kept for older clients). */
  quality?: MediaQuality;
  /** Pack item list; each item is billed as one unit. */
  items?: AssetJobPackItem[];
  /** Optional pack display name; items share its style. */
  packName?: string;
}
```

## packages/types/src/media-models.ts

```ts
export const MEDIA_QUALITY_VALUES = ["standard", "high"] as const;

export type MediaQuality = (typeof MEDIA_QUALITY_VALUES)[number];
```

## packages/types/src/task-definitions.ts

```ts
/** Markdown is the job description; this metadata is admission and execution policy, not a stage graph. */
export interface TaskDefinition {
  id: string;
  name: string;
  description: string;
  role: "QUEEN" | "WORKER";
  managerProfile: string;
  defaultWorkspace: { kind: "REPO" | "APP" | "PACK" | "CREATOR"; ref?: string };
  admission: ("CREATOR" | "OWNER" | "SCHEDULE" | "QUEEN" | "MANUAL" | "EVENT")[];
  review: "none" | "requester";
  execution: { mode: "single" | "auto-loop"; maxDurationSeconds?: number; targetBudgetUsd?: number };
  safety: "none" | "screening";
  /** Defaults apply to production; persisted per-environment enabled overrides always win. */
  schedule?: { key: string; cron: string; timezone: string; enabledByDefault: boolean };
  /** Names of existing domain admission events; a document cannot create new server capabilities. */
  events?: string[];
  /** Queen machine capability every admitted task of this job needs, such as the Windows client toolchain. */
  requires?: QueenExecutionRequirements;
  /**
   * Branch-and-pull-request publication this internal repository job may perform through `task publish-branch`
   * (Core 231107). The repository is always the task's own execution repository; `head` is a branch name with at most
   * one `*`, `base` the only pull request base. Neither may be the repository's default branch; nothing merges.
   */
  publishBranch?: TaskDefinitionBranchPublication;
}

export interface TaskDefinitionBranchPublication { head: string; base: string }

export interface PinnedTaskDefinitionSource {
  repository: string;
  path: string;
  commit: string;
  /** SHA-256 of the exact UTF-8 Markdown bytes, computed and checked by the catalogue boundary. */
  sha256: string;
}

export interface ParsedTaskDefinition {
  definition: TaskDefinition;
  instructions: string;
}

export interface TaskDefinitionSnapshot extends ParsedTaskDefinition {
  source: PinnedTaskDefinitionSource;
  markdown: string;
}
```

## packages/types/src/queen-execution.ts

```ts
export type QueenWorkCapability = "windows-client" | "xcode";

export interface QueenExecutionRequirements {
  os: "win32" | "darwin" | "linux";
  capability?: QueenWorkCapability;
}
```

## packages/types/src/agent-task-output.ts

```ts
/** Durable references, resolved to access URLs only when an output is read. */
export interface AgentTaskOutputMedia {
  id: string;
  kind: "image" | "video" | "asset";
  label?: string | null;
  storageKey: string;
  posterStorageKey?: string | null;
}

/** An immutable delivery; task progress and execution status remain independent. */
export interface AgentTaskOutputSnapshot {
  version: 1;
  title: string;
  subtitle?: string | null;
  message: string;
  items: AgentTaskProgressItem[];
  media: AgentTaskOutputMedia[];
  /** Server-frozen display selection; raw media remain immutable evidence. */
  displayMediaIds?: string[];
}
```

## packages/types/src/agent-task-progress.ts

```ts
/**
 * Structured task progress shared by the studio, admin and workers.
 * Workers post a full report; the server keeps builds and media cumulative so agents never resend them.
 */
export const AGENT_TASK_PROGRESS_ITEM_STATUS_VALUES = ["done", "working", "later"] as const;

export type AgentTaskProgressItemStatus = (typeof AGENT_TASK_PROGRESS_ITEM_STATUS_VALUES)[number];

export interface AgentTaskProgressItem {
  id: string;
  title: string;
  subtitle?: string | null;
  status: AgentTaskProgressItemStatus;
}

export interface AgentTaskProgressBuild {
  id: string;
  label: string;
  /** Exact app version reference when the build was uploaded through PlayDrop. */
  versionRef?: string | null;
  url?: string | null;
  uploadedAt: string;
}

export const AGENT_TASK_PROGRESS_MEDIA_KIND_VALUES = ["image", "video", "asset"] as const;

export type AgentTaskProgressMediaKind = (typeof AGENT_TASK_PROGRESS_MEDIA_KIND_VALUES)[number];

export interface AgentTaskProgressMedia {
  id: string;
  kind: AgentTaskProgressMediaKind;
  label?: string | null;
  url: string;
  posterUrl?: string | null;
}

export interface AgentTaskProgressReport {
  version: 1;
  /** Headline, such as the current milestone. */
  title: string;
  /** Second line, such as the current sprint. */
  subtitle?: string | null;
  /** High-level status text; the final message replaces it at the end. */
  status?: string | null;
  items: AgentTaskProgressItem[];
  builds?: AgentTaskProgressBuild[];
  media?: AgentTaskProgressMedia[];
  /** Server-stamped when stored; worker-supplied values are replaced. */
  updatedAt: string;
  /** Server-assigned, increases with every stored report; ordering never depends on worker clocks. */
  revision?: number;
}
```

## packages/types/src/agent-task-environment.ts

```ts
export const AGENT_TASK_EXECUTION_ENVIRONMENTS = ["prod", "preview", "dev", "test"] as const;

export type AgentTaskExecutionEnvironment = typeof AGENT_TASK_EXECUTION_ENVIRONMENTS[number];
```

## packages/types/src/workflows.ts

```ts
export const AGENT_TASK_WORKFLOW_VALUES = [
  "creator-game",
  "mcp-game-review",
  "generation",
  "ugc-processing",
  "creator-support",
  "release-smoke",
  "worker-repo",
  "queen-repo",
  "queen-ops",
  "swarm-wiki-ingest",
  "swarm-wiki-lint",
  "queen-wiki-ingest",
  "queen-wiki-lint",
] as const;

export type AgentTaskWorkflow = (typeof AGENT_TASK_WORKFLOW_VALUES)[number];

export const AGENT_TASK_STAGE_VALUES = [
  "SCREENING",
  "WORK",
  "REVIEW",
  "BLOCKED",
  "OWNER",
  "MERGE",
  "DEPLOY",
  "DONE",
  "DENIED",
  "FAILED",
  "CANCELLED",
] as const;

export type AgentTaskStage = (typeof AGENT_TASK_STAGE_VALUES)[number];
```

## packages/types/src/agent-task-classification.ts

```ts
/** Shared request taxonomy and time-based effort values for screening. */
export const AGENT_TASK_CLASSIFICATION_CATEGORIES = {
  question: ["game_explanation", "capabilities"],
  game_work: ["validation", "technical_fix", "visual_fix", "visual_polish", "gameplay_polish", "new_game", "feature", "refactor", "listing_marketing"],
  reject: ["private_information", "content_policy", "unrelated", "unclear"],
} as const;

export const AGENT_TASK_CLASSIFICATION_EFFORTS = ["simple", "standard", "complex", "extra_ambitious"] as const;

export const AGENT_TASK_GAME_DIMENSIONS = ["2d", "iso", "3d", "unknown"] as const;

export const AGENT_TASK_WORK_FOCUSES = ["systems", "visuals", "balanced"] as const;

export interface AgentTaskClassification {
  type: keyof typeof AGENT_TASK_CLASSIFICATION_CATEGORIES;
  category: (typeof AGENT_TASK_CLASSIFICATION_CATEGORIES)[keyof typeof AGENT_TASK_CLASSIFICATION_CATEGORIES][number];
  effort: (typeof AGENT_TASK_CLASSIFICATION_EFFORTS)[number] | null;
  gameDimension?: (typeof AGENT_TASK_GAME_DIMENSIONS)[number] | null;
  workFocus?: (typeof AGENT_TASK_WORK_FOCUSES)[number] | null;
  flags: string[];
  reason: string;
  promptLanguage: string;
  promptEnglishTranslation: string;
}
```

## packages/types/src/playtest-notes.ts

```ts
export const PLAYTEST_NOTE_KINDS = ["TEXT", "MARKDOWN", "JSON", "IMAGE", "LOG", "ASSET"] as const;

export type PlaytestNoteKind = (typeof PLAYTEST_NOTE_KINDS)[number];

export interface PlaytestNoteAttachment {
  id: string;
  fileName: string;
  contentType: string;
  sizeBytes: number;
  url?: string;
}

export interface CreatorNote {
  id: number;
  appId: number;
  authoredVersionId: number;
  authoredVersion: string;
  kind: PlaytestNoteKind;
  text?: string;
  assetRef?: string;
  comment?: string;
  attachment?: PlaytestNoteAttachment;
  createdAt: string;
  updatedAt: string;
}
```
