@indiegems/gem-web-sdk 5.10.0 → 5.12.0

package/dist/sdk.d.ts

@@ -539,6 +539,16 @@ interface Progression {
     readonly currentValue: number;
     readonly completionCount: number;
     readonly isCompleted: boolean;
+    readonly achievements?: readonly ProgressionAchievement[];
+    readonly achievementsUnavailable?: boolean;
+}
+interface ProgressionAchievement {
+    readonly id: string;
+    readonly threshold: number;
+    readonly points: number;
+    readonly hidden: boolean;
+    readonly unlockedAt?: number;
+    readonly revoked?: boolean;
 }
 interface CurrencyBucket {
     readonly bucket: string;
@@ -1036,14 +1046,26 @@ declare class ChallengesApi {
     constructor(api: GameApi$1);
     list(options?: ListChallengesOptions): Promise<Challenge[]>;
 }
-interface LeaderboardEntry extends RankedRow {
+interface PlayerBadge {
+    readonly itemId: string;
+    readonly iconUrl: string;
+}
+interface PlayerIdentity {
+    readonly playerId?: string;
+    readonly displayName?: PlayerText;
+    readonly discriminator?: string;
+    readonly displayTag?: PlayerText;
+    readonly avatarIconId?: string;
+    readonly avatarIconUrl?: string;
+    readonly badges: readonly PlayerBadge[];
+}
+declare function mapIdentity(row: unknown): PlayerIdentity;
+declare function platformIconUrl(url: string | undefined): string | undefined;
+interface LeaderboardEntry extends RankedRow, PlayerIdentity {
     readonly rank: number;
     readonly occurredAt: number;
     readonly entityId?: string;
     readonly entityType?: EntityType$1;
-    readonly displayName?: string;
-    readonly discriminator?: string;
-    readonly displayTag?: string;
     readonly stats?: Readonly<Record<string, number>>;
     readonly properties?: Readonly<Record<string, unknown>>;
     readonly isViewer?: boolean;
@@ -1105,11 +1127,8 @@ interface ShowcaseValue {
     readonly value: unknown;
     readonly updatedAt: number;
 }
-interface ShowcaseFriendEntry {
+interface ShowcaseFriendEntry extends PlayerIdentity {
     readonly playerId: string;
-    readonly displayName?: string;
-    readonly discriminator?: string;
-    readonly displayTag?: string;
     readonly value: unknown;
     readonly isViewer: boolean;
     readonly updatedAt: number;
@@ -1131,13 +1150,8 @@ declare class ShowcaseApi {
     set(key: string, value: unknown, options?: ShowcaseCallOptions): Promise<ShowcaseValue>;
     clear(key: string, options?: ShowcaseCallOptions): Promise<void>;
 }
-interface Friend {
+interface Friend extends PlayerIdentity {
     readonly playerId: string;
-    readonly displayName?: string;
-    readonly discriminator?: string;
-    readonly displayTag?: string;
-    readonly avatarIconId?: string;
-    readonly avatarIconUrl?: string;
 }
 interface FriendsPage {
     readonly friends: readonly Friend[];
@@ -1178,13 +1192,8 @@ interface ProfileShowcaseEntry {
     readonly value: unknown;
     readonly updatedAt: number;
 }
-interface PlayerProfile {
+interface PlayerProfile extends PlayerIdentity {
     readonly playerId: string;
-    readonly displayName?: string;
-    readonly discriminator?: string;
-    readonly displayTag?: string;
-    readonly avatarIconId?: string;
-    readonly avatarIconUrl?: string;
     readonly showcase: readonly ProfileShowcaseEntry[];
     readonly generatedAt: number;
 }
@@ -1465,16 +1474,13 @@ interface AutoReconnectOptions {
     readonly attempts?: number;
     readonly maxDelayMs?: number;
 }
-interface RoomMember {
+interface RoomMember extends PlayerIdentity {
     readonly playerId: string;
     readonly isReady: boolean;
     readonly role: string;
     readonly joinedAt: number;
     readonly groupId?: string;
     readonly platform?: string;
-    readonly displayName?: PlayerText;
-    readonly displayTag?: PlayerText;
-    readonly discriminator?: string;
 }
 interface Room {
     readonly id: string;
@@ -1492,6 +1498,7 @@ interface Room {
     readonly roomArgsTemplate?: readonly RoomArgEntry[];
     readonly gameChannel: string;
     readonly region?: string;
+    readonly clusterTargetId?: string;
     readonly matchId?: string;
     readonly version: number;
     readonly templateId?: string;
@@ -1501,6 +1508,10 @@ interface Room {
     readonly updatedAt: number;
     readonly startedAt?: number;
 }
+interface MatchAutoStartFailed {
+    readonly roomId: string;
+    readonly code: string;
+}
 interface RoomSummary {
     readonly id: string;
     readonly gameId: string;
@@ -1603,6 +1614,9 @@ interface RoomEventMap {
     matchStartWaiting: [
         StartMatchWaiting
     ];
+    matchAutoStartFailed: [
+        MatchAutoStartFailed
+    ];
     matchAllocationStarted: [
         string
     ];
@@ -1700,6 +1714,7 @@ interface RoomManager {
     once<K extends RoomEventName>(event: K, listener: (...args: RoomEventMap[K]) => void): () => void;
     handleRoomEvent(event: RelayedRoomEvent): void;
     handleSeated(roomId: string): void;
+    handleAutoStartFailed(roomId: string, code: string): void;
     reconcileSeats(): Promise<void>;
     reconcile(hint?: MatchEndHint): Promise<void>;
     startPolling(intervalMs?: number): void;
@@ -1796,6 +1811,12 @@ interface GemSeatedEvent {
     readonly type: "gem.seatedEvent";
     readonly roomId: string;
 }
+interface GemAutoStartFailedEvent {
+    readonly gem: typeof PROTOCOL;
+    readonly type: "gem.autoStartFailedEvent";
+    readonly roomId: string;
+    readonly code: string;
+}
 interface GemSignalEvent {
     readonly gem: typeof PROTOCOL;
     readonly type: "gem.signalEvent";
@@ -1824,6 +1845,7 @@ interface GemClusterTarget {
     readonly gem: typeof PROTOCOL;
     readonly type: "gem.clusterTarget";
     readonly clusterTargetId: string;
+    readonly clusterTargetIds?: string[];
 }
 interface GemScreenshotDenied {
     readonly gem: typeof PROTOCOL;
@@ -3470,7 +3492,7 @@ interface GemServer {
 declare function createGemServer(host: ServerBundleHost, options?: GemServerOptions): GemServer;
 interface GemServerProfile {
     readonly displayName: PlayerText;
-    readonly displayTag: string;
+    readonly displayTag?: PlayerText;
     readonly discriminator?: string;
 }
 interface GemMatchServer extends GemServer {
@@ -3619,6 +3641,11 @@ interface RewardCue {
     };
 }
 type FrameState = "waiting" | "connected" | "refused" | "closed";
+interface FramePlayer extends PlayerIdentity {
+    readonly displayName: PlayerText;
+    readonly displayHandle: PlayerText;
+    readonly avatarUrl?: string;
+}
 interface FrameCallbacks {
     onToken?(msg: GemToken): void;
     onPause?(msg: GemPause): void;
@@ -3635,14 +3662,10 @@ interface FrameCallbacks {
     onTokenDenied?(msg: GemTokenDenied): void;
     onLocalServer?(msg: GemLocalServer): void;
     onLocalServerDenied?(msg: GemLocalServerDenied): void;
-    onPlayer?(player: {
-        displayName: PlayerText;
-        displayHandle: PlayerText;
-        displayTag: string;
-        avatarUrl?: string;
-    }): void;
+    onPlayer?(player: FramePlayer): void;
     onRoomEvent?(msg: GemRoomEvent): void;
     onSeatedEvent?(msg: GemSeatedEvent): void;
+    onAutoStartFailedEvent?(msg: GemAutoStartFailedEvent): void;
     onSocketState?(msg: GemSocketState): void;
     onSignalEvent?(msg: GemSignalEvent): void;
     onDedicatedEvent?(msg: GemDedicatedEvent): void;
@@ -3718,6 +3741,7 @@ declare class GemFrame {
     private screenshotDenied;
 }
 declare const DEVICE_SETTINGS_MAX_BYTES = 16384;
+declare const ARCADE_EMBEDDERS: readonly string[];
 interface GemOptions {
     readonly allowedEmbedders?: readonly string[];
     readonly baseUrl?: string;
@@ -3750,10 +3774,9 @@ interface GemOptions {
     }) => Promise<ImageBitmap | null>;
     readonly handshakeWarningMs?: number | null;
 }
-interface GemPlayer {
+interface GemPlayer extends PlayerIdentity {
     readonly displayName: PlayerText;
     readonly displayHandle: PlayerText;
-    readonly displayTag: string;
     readonly avatarUrl?: string;
 }
 interface GemPrefs {
@@ -3838,4 +3861,4 @@ interface ExitAnalytics {
 }
 declare function leaveAndExit(rooms: ExitRooms, bridge: ExitBridge | null, reason?: string, analytics?: ExitAnalytics): Promise<void>;
 declare function createGem(options?: GemOptions): Gem;
-export { type AccountApi, type AdFormat, type AdOutcome, type AdOutcomeKind, type AdRequest, type AdsApi, AnalyticsApi, type AnalyticsFlushOptions, type AnalyticsFlushResult, type AnalyticsOptions, type AnalyticsRejection, type AnalyticsValue, AuthError, type AuthFailure, type AuthState, type Base64String, type BootMark, type BootTimeline, type BroadcastOptions, CONDITIONAL_HEADERS, type Challenge, type ChallengeWindow, ChallengesApi, type ClientOptions, type Clock, type ConditionalRequestHeaders, type ConfiguredPurchasePayment, type ConfiguredPurchaseRequest, type ConfiguredPurchaseResult, DEVICE_SETTINGS_MAX_BYTES, DedicatedServerError, type DedicatedServerFailure, type DedicatedServerSession, type DevToolsOpener, type DeviceSettings, type DeviceSettingsApi, type DeviceSettingsPutOutcome, type DirectPurchaseRequest, type DirectPurchaseResult, type EntityLeaderboard, type EntityLeaderboardEntry, type EntityLeaderboardOptions, type EntityType$1 as EntityType, type ExitAnalytics, type ExitBridge, type ExitRooms, type FrameState, type Friend, FriendsApi, type FriendsPage, type GameApi, type GameConfig, type GameServerLink, type Gem, GemApiError, GemClient, type GemCohort, type GemCohorts, GemConfigError, type GemDevTools, type GemErrorReason, GemFrame, type GemIdentity, type GemInsets, type GemMatchApi, type GemMatchServer, type GemMatchServerModule, type GemOptions, type GemPlayer, type GemPrefs, GemSaveError, type GemServer, type GemServerBundle, type GemServerFactory, type GemServerHost, type GemServerHostProfile, type GemServerIdentity, type GemServerLifecycle, type GemServerOptions, type GemServerProfile, type GemTerminationNotice, type GemViewport, type GetLeaderboardOptions, type HostTokenSource, type HostTokenSourceOptions, type JoinWelcome, type Leaderboard, type LeaderboardEntry, LeaderboardsApi, type ListChallengesOptions, type ListFriendsOptions, MAX_PERIODS_BACK, type MatchConnectOptions, type MatchConnection, type MatchHosting, type MatchHostingMode, type MatchServeOptions, type MatchTransport, type MessageMeta, type MultiTransportSession, PLATFORM_EVENTS, PlatformApi, PlatformCurrenciesApi, type PlatformCurrency, type PlatformCurrencyAccess, type PlatformCurrencyPurchasePayment, type PlatformCurrencyPurchaseRequest, type PlatformCurrencyPurchaseResult, type PlatformCurrencyReadOptions, type PlatformEventName, type PlayerProfile, PlayerText, type ProfileCallOptions, type ProfileShowcaseEntry, ProfilesApi, type PurchaseApi, type PurchaseOptions, type PurchaseOutcome, type PurchaseRequest, type PutBytesOptions, type PutSaveOptions, type RankedRow, type RequestOptions, type RewardCue, type RoomArgValue, type SavePage, type SaveRecord, type SendOptions$1 as SendOptions, type ServerApi, type ServerBundleHost, type ServerTokenGrant, type SessionEndReason, ShowcaseApi, type ShowcaseCallOptions, type ShowcaseFriendEntry, type ShowcaseFriends, type ShowcaseValue, type SignInOutcome, type SignInOutcomeKind, type SnapshotCurrency, type SnapshotItem, type TokenGrant, type Transport, type TransportAdvert, type TransportKind, TransportRefusal, type TransportRequest, type TransportResponse, UNRELIABLE_CHANNEL_LABEL, type VersionedGetOptions, type VersionedResponse, asPlayerText, createBootTimeline, createGem, createGemServer, createHostTokenSource, createMatchServer, defineServer, leaveAndExit, markOnResolve, presentJoinCredential, readTemplateTransports, readTransportAdvert, reportOnResolve, systemClock, text, toBase64, webTransportAvailable };
+export { ARCADE_EMBEDDERS, type AccountApi, type AdFormat, type AdOutcome, type AdOutcomeKind, type AdRequest, type AdsApi, AnalyticsApi, type AnalyticsFlushOptions, type AnalyticsFlushResult, type AnalyticsOptions, type AnalyticsRejection, type AnalyticsValue, AuthError, type AuthFailure, type AuthState, type Base64String, type BootMark, type BootTimeline, type BroadcastOptions, CONDITIONAL_HEADERS, type Challenge, type ChallengeWindow, ChallengesApi, type ClientOptions, type Clock, type ConditionalRequestHeaders, type ConfiguredPurchasePayment, type ConfiguredPurchaseRequest, type ConfiguredPurchaseResult, DEVICE_SETTINGS_MAX_BYTES, DedicatedServerError, type DedicatedServerFailure, type DedicatedServerSession, type DevToolsOpener, type DeviceSettings, type DeviceSettingsApi, type DeviceSettingsPutOutcome, type DirectPurchaseRequest, type DirectPurchaseResult, type EntityLeaderboard, type EntityLeaderboardEntry, type EntityLeaderboardOptions, type EntityType$1 as EntityType, type ExitAnalytics, type ExitBridge, type ExitRooms, type FrameState, type Friend, FriendsApi, type FriendsPage, type GameApi, type GameConfig, type GameServerLink, type Gem, GemApiError, GemClient, type GemCohort, type GemCohorts, GemConfigError, type GemDevTools, type GemErrorReason, GemFrame, type GemIdentity, type GemInsets, type GemMatchApi, type GemMatchServer, type GemMatchServerModule, type GemOptions, type GemPlayer, type GemPrefs, GemSaveError, type GemServer, type GemServerBundle, type GemServerFactory, type GemServerHost, type GemServerHostProfile, type GemServerIdentity, type GemServerLifecycle, type GemServerOptions, type GemServerProfile, type GemTerminationNotice, type GemViewport, type GetLeaderboardOptions, type HostTokenSource, type HostTokenSourceOptions, type JoinWelcome, type Leaderboard, type LeaderboardEntry, LeaderboardsApi, type ListChallengesOptions, type ListFriendsOptions, MAX_PERIODS_BACK, type MatchConnectOptions, type MatchConnection, type MatchHosting, type MatchHostingMode, type MatchServeOptions, type MatchTransport, type MessageMeta, type MultiTransportSession, PLATFORM_EVENTS, PlatformApi, PlatformCurrenciesApi, type PlatformCurrency, type PlatformCurrencyAccess, type PlatformCurrencyPurchasePayment, type PlatformCurrencyPurchaseRequest, type PlatformCurrencyPurchaseResult, type PlatformCurrencyReadOptions, type PlatformEventName, type PlayerBadge, type PlayerIdentity, type PlayerProfile, PlayerText, type ProfileCallOptions, type ProfileShowcaseEntry, ProfilesApi, type PurchaseApi, type PurchaseOptions, type PurchaseOutcome, type PurchaseRequest, type PutBytesOptions, type PutSaveOptions, type RankedRow, type RequestOptions, type RewardCue, type RoomArgValue, type SavePage, type SaveRecord, type SendOptions$1 as SendOptions, type ServerApi, type ServerBundleHost, type ServerTokenGrant, type SessionEndReason, ShowcaseApi, type ShowcaseCallOptions, type ShowcaseFriendEntry, type ShowcaseFriends, type ShowcaseValue, type SignInOutcome, type SignInOutcomeKind, type SnapshotCurrency, type SnapshotItem, type TokenGrant, type Transport, type TransportAdvert, type TransportKind, TransportRefusal, type TransportRequest, type TransportResponse, UNRELIABLE_CHANNEL_LABEL, type VersionedGetOptions, type VersionedResponse, asPlayerText, createBootTimeline, createGem, createGemServer, createHostTokenSource, createMatchServer, defineServer, leaveAndExit, mapIdentity, markOnResolve, platformIconUrl, presentJoinCredential, readTemplateTransports, readTransportAdvert, reportOnResolve, systemClock, text, toBase64, webTransportAvailable };

package/dist/server.d.ts

@@ -1369,7 +1369,7 @@ declare const text: {
 };
 interface GemServerProfile {
     readonly displayName: PlayerText;
-    readonly displayTag: string;
+    readonly displayTag?: PlayerText;
     readonly discriminator?: string;
 }
 interface GemMatchServer extends GemServer {
@@ -1435,4 +1435,12 @@ interface RuntimeShutdownPayload {
 }
 type GemServerFactory = () => GemServerLifecycle;
 declare function defineServer(setup: (gem: GemMatchServer) => GemServerBundle, options?: GemServerOptions): GemServerFactory;
-export { type AnalyticsFlushResult, type AnalyticsRejection, type AnalyticsValue, AuthError, type AuthFailure, type AuthState, type Base64String, type BroadcastOptions, CONDITIONAL_HEADERS, type ClientOptions, type Clock, type ConditionalRequestHeaders, type GameApi, GemApiError, GemClient, type GemErrorReason, type GemMatchServer, type GemServer, type GemServerBundle, type GemServerFactory, type GemServerHost, type GemServerHostProfile, type GemServerIdentity, type GemServerLifecycle, type GemServerOptions, type GemServerProfile, type HostTokenSource, type HostTokenSourceOptions, PlayerText, type RequestOptions, type RoomArgValue, type RuntimeShutdownPayload, type SendOptions, type ServerAnalytics, type ServerApi, type ServerBundleHost, type ServerShutdownInfo, type ServerTokenGrant, type TokenGrant, type Transport, TransportRefusal, type TransportRequest, type TransportResponse, type VersionedGetOptions, type VersionedResponse, asPlayerText, createGemServer, createHostTokenSource, createMatchServer, defineServer, systemClock, text, toBase64 };
+interface AchievementReceipt {
+    readonly achievementId: string;
+    readonly progressionDefinitionId: string;
+    readonly points: number;
+    readonly outcome: "unlocked" | "already_unlocked" | "suppressed";
+    readonly reason?: string;
+}
+declare function achievementReceipts(order: unknown): AchievementReceipt[];
+export { type AchievementReceipt, type AnalyticsFlushResult, type AnalyticsRejection, type AnalyticsValue, AuthError, type AuthFailure, type AuthState, type Base64String, type BroadcastOptions, CONDITIONAL_HEADERS, type ClientOptions, type Clock, type ConditionalRequestHeaders, type GameApi, GemApiError, GemClient, type GemErrorReason, type GemMatchServer, type GemServer, type GemServerBundle, type GemServerFactory, type GemServerHost, type GemServerHostProfile, type GemServerIdentity, type GemServerLifecycle, type GemServerOptions, type GemServerProfile, type HostTokenSource, type HostTokenSourceOptions, PlayerText, type RequestOptions, type RoomArgValue, type RuntimeShutdownPayload, type SendOptions, type ServerAnalytics, type ServerApi, type ServerBundleHost, type ServerShutdownInfo, type ServerTokenGrant, type TokenGrant, type Transport, TransportRefusal, type TransportRequest, type TransportResponse, type VersionedGetOptions, type VersionedResponse, achievementReceipts, asPlayerText, createGemServer, createHostTokenSource, createMatchServer, defineServer, systemClock, text, toBase64 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indiegems/gem-web-sdk",
-  "version": "5.10.0",
+  "version": "5.12.0",
   "description": "postMessage bridge contract between gem-web and browser-playable games",
   "license": "UNLICENSED",
   "type": "module",

package/schema/bridge.v1.json

@@ -489,30 +489,100 @@
         "stripping it turns decomposed José into Jose and makes Thai unreadable —",
         "and inconsistently, since NFC é survives while NFD e+U+0301 does not.",
         "",
-        "`displayTag` and `avatarUrl` sit OUTSIDE `untrusted` because they are",
-        "platform-assigned, not player-authored. `displayHandle` is inside because",
-        "it embeds displayName — otherwise the precomposed 'safe' field is a",
-        "laundering path for the unsafe one."
+        "THE TRUST SPLIT. Outside",
+        "`untrusted` there are ONLY platform-assigned values: ids, the",
+        "discriminator digits, and platform image URLs. Every field that carries",
+        "the player's name sits inside it — `displayTag` because `Name#0001`",
+        "embeds displayName, which otherwise makes the precomposed 'safe' field a",
+        "laundering path for the unsafe one. This SDK's own schema test fails the",
+        "build if a name-bearing field appears anywhere else in this schema.",
+        "",
+        "The names follow gem-api's flat identity fields (`player_id`,",
+        "`display_name`, `discriminator`, `display_tag`, `avatar_icon_url`,",
+        "`badges`), which every REST surface carries and the SDK maps with one",
+        "`mapIdentity`. This message used to call the DISCRIMINATOR",
+        "`displayTag` — the same name gem-api gives the whole `Name#0001` — so",
+        "one name meant two things in two safety classes.",
+        "",
+        "LEGACY FIELDS, AND WHY THEY ARE STILL REQUIRED. `displayTag` (top level),",
+        "`untrusted.displayHandle` and `avatarUrl` are the earlier spellings of",
+        "`discriminator`, `untrusted.displayTag` and `avatarIconUrl`. A game",
+        "bundles the SDK it was built with, and every frame built before the new",
+        "names existed REQUIRES the first two — a parent that dropped them would",
+        "have its gem.player refused by every one of those games. Keeping them REQUIRED",
+        "makes that obligation mechanical on the sending side rather than a note:",
+        "a parent's own generated validator refuses a message without them. A",
+        "parent fills each from its successor and never from anything else —",
+        "`GemHost.sendPlayer` takes no input for them at all. A frame built from",
+        "this schema reads them only as the fallback for a parent older than the",
+        "new names, which sends nothing else. They are removed by the next `v`,",
+        "whose N-1 window is what lets them go.",
+        "",
+        "ADDITIVE, so no `v` bump: every new field is optional (an older parent",
+        "sends none of them and must still be accepted), and an older frame",
+        "ignores fields it does not know (rule 4)."
       ],
       "fields": {
         "untrusted": {
           "kind": "object",
           "fields": {
             "displayName": { "kind": "string", "maxLength": 64 },
+            "displayTag": {
+              "kind": "string",
+              "maxLength": 80,
+              "optional": true,
+              "$comment": "Precomposed `Name#0001` — gem-api's `display_tag` — so no game has to know the convention. Player-authored because it embeds the name. gem-web's AGENTS.md states the platform rule flatly: never display a username; always display_name + discriminator."
+            },
             "displayHandle": {
               "kind": "string",
               "maxLength": 80,
-              "$comment": "Precomposed `DisplayName#1234`, so no game has to know the convention. gem-web's AGENTS.md states the platform rule flatly: never display a username; always display_name + display_tag."
+              "$comment": "LEGACY — the earlier spelling of `untrusted.displayTag`, and the same value (`displayName` alone when the player has no tag). Required because older frames require it; see the message comment. A current frame reads it only when `untrusted.displayTag` is absent."
             }
           }
         },
-        "displayTag": { "kind": "string", "maxLength": 8 },
+        "playerId": {
+          "kind": "string",
+          "maxLength": 64,
+          "optional": true,
+          "$comment": "The same id the token carries, so a game can key its own row in a roster or a board without decoding anything. Optional only because an older parent does not send it."
+        },
+        "discriminator": {
+          "kind": "string",
+          "maxLength": 8,
+          "optional": true,
+          "$comment": "The platform-assigned digits after the `#` (`0001`), which tell two players with the same name apart. Not player-authored."
+        },
+        "avatarIconUrl": {
+          "kind": "string",
+          "maxLength": 2048,
+          "format": "url",
+          "optional": true,
+          "$comment": "The portrait's THUMBNAIL (gem-api `avatar_icon_url`). Absent means no portrait; a parent never sends an empty string. Structurally validated only — https (or loopback), no userinfo, parsed rather than regex-matched. It is NOT origin-pinned: the validator is a pure function with no configuration, so it cannot know the CDN origin. An earlier version of this comment claimed a pin that the generated code did not emit — a documented control that did not exist. THE CONSUMER MUST PIN THE ORIGIN before putting this in an <img src> — the SDK's `platformIconUrl` does — or a hostile parent supplies a request-time beacon carrying the Referer."
+        },
+        "badges": {
+          "kind": "array",
+          "maxItems": 2,
+          "optional": true,
+          "$comment": "Equipped badges in display order — empty until platform achievements equip any, and never more than two. Each is an item id and a thumbnail URL, the same pin caveat as `avatarIconUrl`.",
+          "items": {
+            "kind": "object",
+            "fields": {
+              "itemId": { "kind": "string", "maxLength": 64 },
+              "iconUrl": { "kind": "string", "maxLength": 2048, "format": "url" }
+            }
+          }
+        },
+        "displayTag": {
+          "kind": "string",
+          "maxLength": 8,
+          "$comment": "LEGACY — the earlier spelling of `discriminator`, and the same value (empty when the player has none). NOT the name-bearing `untrusted.displayTag`: this one has only ever carried the digits. Required because older frames require it; see the message comment. A current frame reads it only when `discriminator` is absent."
+        },
         "avatarUrl": {
           "kind": "string",
           "maxLength": 2048,
           "format": "url",
           "optional": true,
-          "$comment": "Structurally validated only — https (or loopback), no userinfo, parsed rather than regex-matched. It is NOT origin-pinned: the validator is a pure function with no configuration, so it cannot know the CDN origin. An earlier version of this comment claimed a pin that the generated code did not emit — a documented control that did not exist. THE CONSUMER MUST PIN THE ORIGIN before putting this in an <img src>, or a hostile parent supplies a request-time beacon carrying the Referer."
+          "$comment": "LEGACY — the earlier spelling of `avatarIconUrl`, and the same value. Same pin caveat. A current frame reads it only when `avatarIconUrl` is absent."
         }
       },
       "rateLimit": { "perMinute": 12 }
@@ -995,6 +1065,45 @@
       },
       "rateLimit": { "perMinute": 60 }
     },
+    {
+      "type": "gem.autoStartFailedEvent",
+      "direction": "parentToFrame",
+      "transport": "port",
+      "$comment": [
+        "The platform tried to start a match in this player's room on its own —",
+        "the room filled to its template's `min_players` — and was refused.",
+        "Gated by the `autoStartFailure` capability; the mapping lives in",
+        "schema/capabilities.json and nowhere else.",
+        "",
+        "gem-api's `game_room_auto_start_failed`, sent to the room's HOST only,",
+        "because the host is the one member who can act: start the match itself.",
+        "No match exists and the room stays open, so there is no",
+        "`game_room_match_failed` or `match_ended` to follow — which is why this",
+        "is not either of those.",
+        "",
+        "ITS OWN TYPE, NOT A VALUE IN gem.roomEvent'S ENUM, for the reason",
+        "gem.seatedEvent gives: the generated validator rejects an unknown enum",
+        "value, and the frame reports that rejection to the game and to the",
+        "embedder as a protocol error. Every already-published game would see",
+        "one each time an automatic start failed. An unknown TYPE is ignored,",
+        "and the capability keeps the parent from sending it at all.",
+        "",
+        "THE CODE IS WHAT CROSSES, and it is an open vocabulary. It is the error",
+        "code a manual start would have been answered with for the same refusal:",
+        "`invalid_cluster_target` (the room's cluster is no longer configured),",
+        "`capacity_unavailable`, or one of the start route's version, engine and",
+        "server-build codes. A string rather than an enum so a code gem-api adds",
+        "later reaches the game rather than breaking the message.",
+        "",
+        "PARENT TO FRAME ONLY. A frame-authored failure would let a game tell the",
+        "parent a room it is in cannot start."
+      ],
+      "fields": {
+        "roomId": { "kind": "string", "maxLength": 64 },
+        "code": { "kind": "string", "maxLength": 64 }
+      },
+      "rateLimit": { "perMinute": 30 }
+    },
 
     {
       "type": "gem.signalEvent",
@@ -1219,40 +1328,60 @@
       "direction": "parentToFrame",
       "transport": "port",
       "$comment": [
-        "Where this player should be allocated. Gated by the `clusterTarget`",
-        "capability.",
-        "",
-        "ONE RESOLVED ID, NEVER THE MEASUREMENT THAT PRODUCED IT. The parent",
-        "ranks regions by timing STUN Binding requests against the probe",
-        "endpoints `GET /v1/regions` publishes, once per player session. What",
-        "crosses is the winner. What must never cross is the vector: a",
-        "round-trip time to every region is coarse geolocation plus a network",
-        "fingerprint, and it would be readable by third-party game code that has",
-        "no use for it. There is no ranking, no runner-up, no per-region timing",
-        "and no `probe_targets_fresh` here, and adding any of them is not an",
-        "additive change however optional the field is.",
+        "Where this player's rooms and matches should be placed. Gated by the",
+        "`clusterTarget` capability.",
+        "",
+        "THE ACCEPTABLE CLUSTERS, BEST FIRST, NEVER THE MEASUREMENT THAT PRODUCED",
+        "THEM. The parent ranks regions by timing STUN Binding requests against",
+        "the probe endpoints `GET /v1/regions` publishes, and keeps the ones close",
+        "enough to the fastest that a player would not notice the difference —",
+        "at most three. What crosses is those ids, in order. What must never",
+        "cross is the vector: a round-trip time to every region is coarse",
+        "geolocation plus a network fingerprint, and it would be readable by",
+        "third-party game code that has no use for it. There is no per-region",
+        "timing, no list of the regions that were NOT acceptable, and no",
+        "`probe_targets_fresh` here, and adding any of them is not an additive",
+        "change however optional the field is. Three ids with no timings is",
+        "continent-level information, about what one id already said.",
+        "",
+        "TWO FIELDS FOR ONE ANSWER, because frames that predate the list are in",
+        "the wild. `clusterTargetId` is the best cluster, always the head of the",
+        "list, and it is all an older frame reads. `clusterTargetIds` is the",
+        "list; a frame that reads it prefers it, and a message without one is a",
+        "list of one.",
         "",
         "PUSHED, NOT ASKED, because the fact exists before the frame does — the",
         "Arcade page measures at startup and the same measurement survives a game",
         "swap. Sent once after the handshake; sent again only if the parent's",
-        "answer actually changes.",
+        "answer actually changes. A frame refused a cluster waits a few seconds",
+        "for exactly that, so a parent that re-measures should send the result.",
         "",
         "ABSENCE IS EXPRESSED BY NOT SENDING. There is no empty or sentinel",
-        "value, and the field is required for that reason: a parent with no",
-        "answer stays quiet, the frame omits the cluster target from its",
-        "allocation request, and the server is left to decide. That is what",
-        "`/v1/regions` asks a client with no `default_cluster_target_id` to do.",
-        "",
-        "NOT the room's `region`. That one is a free-form matchmaking label",
-        "gem-api stores on the room and filters quick-join by; it plays no part",
-        "in allocation. This is the cluster the match is placed in. Two nearby",
-        "words for two unrelated facts, so they are named apart — DESIGN.md §1."
+        "value, and the id is required for that reason: a parent with no answer",
+        "stays quiet, the frame names no cluster on its room and allocation",
+        "requests, and the server is left to decide.",
+        "",
+        "NOT the room's retired `region`, a free-form label gem-api no longer",
+        "stores or matches on. A room's cluster is where its matches start and",
+        "which quick-join requests can find it."
       ],
       "fields": {
         "clusterTargetId": {
           "kind": "string",
           "maxLength": 64,
-          "$comment": "`cluster_target_id` as `/v1/regions` reports it, e.g. `ct_azureeastus01`."
+          "$comment": "`cluster_target_id` as `/v1/regions` reports it, e.g. `ct_azureeastus01`. The best cluster: the head of `clusterTargetIds` when that is sent."
+        },
+        "clusterTargetIds": {
+          "kind": "array",
+          "maxItems": 3,
+          "items": { "kind": "string", "maxLength": 64 },
+          "optional": true,
+          "$comment": [
+            "Every acceptable cluster, best first, `clusterTargetId` included.",
+            "Bounded at three, which is also gem-api's own limit on a quick-join",
+            "list: a fourth entry would be refused there, and it would be one",
+            "more fact about where the player is than any game needs."
+          ]
         }
       },
       "rateLimit": { "perMinute": 12 }
@@ -1975,9 +2104,11 @@
         "player's one real wallet (gem-api's rule), so a cue confirms the same",
         "way everywhere; a grant the receipt reports suppressed confirms nothing.",
         "",
-        "Gated by `rewardCue`: sent only to a parent that advertised it, which is",
-        "how a game learns (`gem.cueReward` returns false) that it should play its",
-        "own celebration instead."
+        "Gated by `rewardCue`: sent only to a parent that advertised it; to any",
+        "other, `gem.cueReward` returns false and the game does NOTHING. There is",
+        "no fallback celebration: Gems display belongs to the arcade (the",
+        "creator's ruling, 2026-09-24), so a game draws no Gems flight, counter or",
+        "celebration of its own. `origin` is the centre of the game's Gems icon."
       ],
       "fields": {
         "currencySlug": { "kind": "string", "maxLength": 32 },