@indiegems/gem-web-sdk 20.0.0 → 21.0.0

package/dist/sdk.d.ts

@@ -1511,7 +1511,7 @@ declare class FunctionsApi {
 }
 type SessionEndReason = "grant_expiring" | "session_ended" | "navigating" | "kill_switch" | "pagehide";
 type MatchTransport = "dedicated" | "p2p";
-type PlatformEventName = "gem_session_start" | "gem_session_end" | "gem_pause" | "gem_resume" | "gem_boot_ready" | "gem_match_started" | "gem_match_ended" | "gem_auth_lost";
+type PlatformEventName = "gem_session_start" | "gem_session_end" | "gem_pause" | "gem_resume" | "gem_boot_ready" | "gem_match_started" | "gem_match_ended" | "gem_auth_lost" | "gem_graphics_context_lost";
 declare const PLATFORM_EVENTS: readonly PlatformEventName[];
 type AnalyticsValue = string | number;
 interface AnalyticsRejection$1 {
@@ -2254,6 +2254,15 @@ interface GemSignalEvent {
     readonly matchId: string;
     readonly data: unknown;
 }
+interface GemRelayDraining {
+    readonly gem: typeof PROTOCOL;
+    readonly type: "gem.relayDraining";
+    readonly matchId: string;
+    readonly clusterTargetId: string;
+    readonly relayIps: string[];
+    readonly drainingSince: string;
+    readonly deadline: string;
+}
 interface GemDedicatedEvent {
     readonly gem: typeof PROTOCOL;
     readonly type: "gem.dedicatedEvent";
@@ -2570,6 +2579,7 @@ interface TelemetrySample {
     readonly type: string;
     readonly value?: number;
     readonly transport?: TransportLabel;
+    readonly labels?: Readonly<Record<string, string>>;
 }
 interface P2pApiOptions {
     readonly client: GemClient;
@@ -2686,9 +2696,12 @@ interface IceCandidateLike {
     readonly sdpMid?: string | null;
     readonly sdpMLineIndex?: number | null;
 }
+type EventListenerLike = {
+    bivarianceHack(event: unknown): void;
+}["bivarianceHack"];
 interface EventTargetLike {
-    addEventListener(type: string, listener: (event: never) => void): void;
-    removeEventListener(type: string, listener: (event: never) => void): void;
+    addEventListener(type: string, listener: EventListenerLike): void;
+    removeEventListener(type: string, listener: EventListenerLike): void;
 }
 interface DataChannelLike extends EventTargetLike {
     readonly readyState: string;
@@ -2703,6 +2716,16 @@ interface DataChannelInitLike {
     readonly negotiated?: boolean;
     readonly id?: number;
 }
+interface IceConfigurationLike {
+    iceServers?: {
+        urls: string | string[];
+        username?: string;
+        credential?: string;
+    }[];
+}
+interface StatsReportLike {
+    forEach(callback: (value: unknown, key: string) => void): void;
+}
 interface PeerConnectionLike extends EventTargetLike {
     readonly localDescription: SessionDescriptionLike | null;
     readonly remoteDescription: SessionDescriptionLike | null;
@@ -2715,6 +2738,10 @@ interface PeerConnectionLike extends EventTargetLike {
     setRemoteDescription(description: SessionDescriptionLike): Promise<void>;
     addIceCandidate(candidate: IceCandidateLike): Promise<void>;
     close(): void;
+    setConfiguration?(configuration: IceConfigurationLike): void;
+    getConfiguration?(): IceConfigurationLike;
+    restartIce?(): void;
+    getStats?(): Promise<StatsReportLike>;
 }
 interface PeerConnectionConfig {
     readonly iceServers: readonly {
@@ -2749,6 +2776,7 @@ interface P2pSessionOptions {
     readonly baseUrl: string;
     readonly signaling: SignalingClient;
     readonly clusterTargetId?: ClusterTargetLike;
+    readonly clusterTargetIds?: readonly string[];
     readonly peerConnectionFactory?: PeerConnectionFactory;
     readonly certificate?: unknown;
     readonly connectTimeoutMs?: number;
@@ -2765,7 +2793,11 @@ declare class P2pSession {
     private readonly keys;
     private localPlayerId;
     private migration;
-    private iceServers;
+    private lease;
+    private clusterTargetIds;
+    private leaseRenewal;
+    private leaseAskedAt;
+    private leaseRenewalWarned;
     private credential;
     private nextPeerId;
     private ended;
@@ -2779,6 +2811,7 @@ declare class P2pSession {
     private readonly answeredSessions;
     private credentialGeneration;
     private credentialDeadline;
+    private readonly drainTimers;
     constructor(options: P2pSessionOptions);
     get matchId(): string;
     get playerId(): string;
@@ -2804,6 +2837,7 @@ declare class P2pSession {
     private fetchCredential;
     private waitForCredential;
     private onOffer;
+    private answer;
     private onAnswer;
     private hostVerified;
     private maybeAuthenticate;
@@ -2814,6 +2848,17 @@ declare class P2pSession {
     private watchMigration;
     private onMatchEnded;
     private onSignalingError;
+    private onRelayDraining;
+    private onDrainDeadline;
+    private withoutDrainingRelays;
+    private restartIceToHost;
+    private offerIceRestart;
+    private progressRestart;
+    private reportRestart;
+    private takeLease;
+    private refreshLease;
+    private reconfigureLinks;
+    private iceServers;
     private openLink;
     private flushCandidates;
     private onReliableOpen;
@@ -2822,6 +2867,8 @@ declare class P2pSession {
     private refuseLink;
     private finishAdmission;
     private onIceState;
+    private recoverHostLink;
+    private voteHostUnreachable;
     private onConnectionState;
     private expose;
     private dropLink;
@@ -4726,6 +4773,7 @@ interface FrameCallbacks {
     onTicketEvent?(msg: GemTicketEvent): void;
     onSocketState?(msg: GemSocketState): void;
     onSignalEvent?(msg: GemSignalEvent): void;
+    onRelayDraining?(msg: GemRelayDraining): void;
     onDedicatedEvent?(msg: GemDedicatedEvent): void;
     onClusterTarget?(msg: GemClusterTarget): void;
     onPartyResult?(msg: GemPartyResult): void;

package/docs/analytics.md

@@ -131,10 +131,21 @@ and a game that declares no events at all still gets them:
 | `gem_boot_ready`                   | —                                | `boot_ms`     |
 | `gem_match_started` / `gem_match_ended` | `transport` (`dedicated`, `p2p`) | —        |
 | `gem_auth_lost`                    | —                                | —             |
+| `gem_graphics_context_lost`        | `gpu`, `host`, `route`           | `context_ms`, `hidden`, `nth_loss` |
 
 `reason` on a session end is one of `grant_expiring`, `session_ended`, `navigating`,
 `kill_switch` or `pagehide`.
 
+`gem_graphics_context_lost` is the browser taking one of your WebGL contexts away — on a phone
+usually a GPU driver fault rather than your code. `gpu` is the GPU family (`powervr_d_series`,
+`powervr_other`, `adreno`, `mali`, `xclipse`, `apple`, `nvidia`, `amd`, `intel`, `software`,
+`other`, `unknown`), `route` is how the browser drives it (`angle_gles`, `angle_vulkan`,
+`angle_d3d11`, `angle_d3d9`, `angle_metal`, `angle_opengl`, `angle_other`, `native_gl`, `webgpu`,
+`unknown`) and `host` is `android_webview` (the Arcade app) or `other`. `hidden` is 1 when the page
+was hidden at the time, which is a phone reclaiming a backgrounded game's memory rather than a
+crash in front of the player. It is sent whether or not your game recovers from the loss, at most
+five times a page.
+
 **The `gem_` prefix is reserved.** Your config cannot declare an id beginning with it and
 `gem.analytics.track` refuses one rather than sending it, so pick another name.
 

package/docs/api/api-reference-function.md

@@ -1,6 +1,6 @@
 # The function surface — API reference
 
-Generated from `@indiegems/gem-web-sdk/function` v20.0.0, the version of the package this file ships in. Every symbol below carries an explicit anchor, its `anchor` in `reference.json` beside this file.
+Generated from `@indiegems/gem-web-sdk/function` v21.0.0, the version of the package this file ships in. Every symbol below carries an explicit anchor, its `anchor` in `reference.json` beside this file.
 
 `@indiegems/gem-web-sdk/function` exports exactly the symbols on this page and nothing else.
 
@@ -470,7 +470,7 @@ the reading a funnel should treat as approximate.
 ## PlatformEventName
 
 ```ts
-type PlatformEventName = "gem_session_start" | "gem_session_end" | "gem_pause" | "gem_resume" | "gem_boot_ready" | "gem_match_started" | "gem_match_ended" | "gem_auth_lost"
+type PlatformEventName = "gem_session_start" | "gem_session_end" | "gem_pause" | "gem_resume" | "gem_boot_ready" | "gem_match_started" | "gem_match_ended" | "gem_auth_lost" | "gem_graphics_context_lost"
 ```
 
 Every event the SDK emits by itself.
@@ -488,6 +488,11 @@ config names them as steps.
 | `gem_boot_ready` | — | `boot_ms` |
 | `gem_match_started` / `gem_match_ended` | `transport` (`MatchTransport`) | — |
 | `gem_auth_lost` | — | — |
+| `gem_graphics_context_lost` | `gpu`, `host`, `route` | `context_ms`, `hidden`, `nth_loss` |
+
+`gem_graphics_context_lost` is the browser taking a WebGL context away —
+usually a GPU driver fault, sized per device across every game
+(`analytics/graphics.ts` lists the dimension values).
 
 <a id="gemerrorreason"></a>
 

package/docs/api/api-reference-game.md

@@ -1,6 +1,6 @@
 # The browser surface — API reference
 
-Generated from `@indiegems/gem-web-sdk/sdk` v20.0.0, the version of the package this file ships in. Every symbol below carries an explicit anchor, its `anchor` in `reference.json` beside this file.
+Generated from `@indiegems/gem-web-sdk/sdk` v21.0.0, the version of the package this file ships in. Every symbol below carries an explicit anchor, its `anchor` in `reference.json` beside this file.
 
 `@indiegems/gem-web-sdk/sdk` is the one import a game writes, wherever its code runs. `@indiegems/gem-web-sdk/game` exports exactly the symbols on this page and nothing else, for a build that wants only this half.
 
@@ -4012,7 +4012,7 @@ How a match was hosted — the closed set `gem_match_started` and
 ## PlatformEventName
 
 ```ts
-type PlatformEventName = "gem_session_start" | "gem_session_end" | "gem_pause" | "gem_resume" | "gem_boot_ready" | "gem_match_started" | "gem_match_ended" | "gem_auth_lost"
+type PlatformEventName = "gem_session_start" | "gem_session_end" | "gem_pause" | "gem_resume" | "gem_boot_ready" | "gem_match_started" | "gem_match_ended" | "gem_auth_lost" | "gem_graphics_context_lost"
 ```
 
 Every event the SDK emits by itself.
@@ -4030,6 +4030,11 @@ config names them as steps.
 | `gem_boot_ready` | — | `boot_ms` |
 | `gem_match_started` / `gem_match_ended` | `transport` ([MatchTransport](#matchtransport)) | — |
 | `gem_auth_lost` | — | — |
+| `gem_graphics_context_lost` | `gpu`, `host`, `route` | `context_ms`, `hidden`, `nth_loss` |
+
+`gem_graphics_context_lost` is the browser taking a WebGL context away —
+usually a GPU driver fault, sized per device across every game
+(`analytics/graphics.ts` lists the dimension values).
 
 <a id="platform_events"></a>
 
@@ -9504,8 +9509,9 @@ ARCADE_EMBEDDERS: readonly string[]
 ```
 
 The origins the Gem Arcade embeds a game from, which every game accepts
-without naming them: the website, the developer site, and the Gem Arcade
-app.
+without naming them: the website and the Gem Arcade app. The list also
+holds `https://developer.gemarcade.com`, which is reserved and not live —
+no page is served there, so nothing frames a game from it.
 
 You do not pass these. They are always allowed, and
 [GemOptions.allowedEmbedders](#gemoptions-allowedembedders) adds to them rather than replacing them.
@@ -9534,8 +9540,8 @@ readonly allowedEmbedders?: readonly string[]
 Extra origins allowed to embed your game, **added to** the ones the Gem
 Arcade uses. Most games leave this out.
 
-The website, the developer site and the Gem Arcade app are always
-allowed — see [ARCADE_EMBEDDERS](#arcade_embedders) — so do not list them. Set this only when a site
+The website and the Gem Arcade app are always allowed — see
+[ARCADE_EMBEDDERS](#arcade_embedders) — so do not list them. Set this only when a site
 of your own embeds your game.
 
 ```js
@@ -12593,9 +12599,9 @@ await gem.awaitBridge();      // before loading your main bundle
 const me = await gem.awaitIdentity();  // who is playing, once sign-in completes
 ```
 
-No options are needed. The Gem Arcade's website, developer site and app are
-always allowed to embed your game ([ARCADE_EMBEDDERS](#arcade_embedders)), and the arcade
-tells your game which build it is.
+No options are needed. The Gem Arcade's website and app are always allowed to
+embed your game ([ARCADE_EMBEDDERS](#arcade_embedders)), and the arcade tells your game
+which build it is.
 
 A dev host on your own machine (`gemctl serve`, the Gem Editor) needs no
 entry either: it frames a locally-served game from a loopback origin whose

package/docs/api/api-reference-server.md

@@ -1,6 +1,6 @@
 # The server surface — API reference
 
-Generated from `@indiegems/gem-web-sdk/sdk` v20.0.0, the version of the package this file ships in. Every symbol below carries an explicit anchor, its `anchor` in `reference.json` beside this file.
+Generated from `@indiegems/gem-web-sdk/sdk` v21.0.0, the version of the package this file ships in. Every symbol below carries an explicit anchor, its `anchor` in `reference.json` beside this file.
 
 `@indiegems/gem-web-sdk/sdk` is the one import a game writes, wherever its code runs. `@indiegems/gem-web-sdk/server` exports exactly the symbols on this page and nothing else, for a build that wants only this half.
 

package/docs/api/reference.json

@@ -2,7 +2,7 @@
   "schema_version": 2,
   "source": {
     "repo": "IndieGems/gem-web-sdk",
-    "version": "20.0.0"
+    "version": "21.0.0"
   },
   "entries": [
     {
@@ -4733,9 +4733,9 @@
           "name": "PlatformEventName",
           "anchor": "platformeventname",
           "group": "analytics",
-          "signature": "type PlatformEventName = \"gem_session_start\" | \"gem_session_end\" | \"gem_pause\" | \"gem_resume\" | \"gem_boot_ready\" | \"gem_match_started\" | \"gem_match_ended\" | \"gem_auth_lost\"",
+          "signature": "type PlatformEventName = \"gem_session_start\" | \"gem_session_end\" | \"gem_pause\" | \"gem_resume\" | \"gem_boot_ready\" | \"gem_match_started\" | \"gem_match_ended\" | \"gem_auth_lost\" | \"gem_graphics_context_lost\"",
           "documented": true,
-          "summary": "Every event the SDK emits by itself.\n\nA game never sends these — `gem.analytics.track` refuses the whole\n`gem_` namespace — but the names are published because a game reading its\nown funnel needs the vocabulary, and because a funnel declared in the game\nconfig names them as steps.\n\n| Event | Dimensions | Measures |\n|---|---|---|\n| `gem_session_start` | — | — |\n| `gem_session_end` | `reason` ([SessionEndReason](api-reference-game.md#sessionendreason)) | `duration_ms` |\n| `gem_pause` / `gem_resume` | — | — |\n| `gem_boot_ready` | — | `boot_ms` |\n| `gem_match_started` / `gem_match_ended` | `transport` ([MatchTransport](api-reference-game.md#matchtransport)) | — |\n| `gem_auth_lost` | — | — |",
+          "summary": "Every event the SDK emits by itself.\n\nA game never sends these — `gem.analytics.track` refuses the whole\n`gem_` namespace — but the names are published because a game reading its\nown funnel needs the vocabulary, and because a funnel declared in the game\nconfig names them as steps.\n\n| Event | Dimensions | Measures |\n|---|---|---|\n| `gem_session_start` | — | — |\n| `gem_session_end` | `reason` ([SessionEndReason](api-reference-game.md#sessionendreason)) | `duration_ms` |\n| `gem_pause` / `gem_resume` | — | — |\n| `gem_boot_ready` | — | `boot_ms` |\n| `gem_match_started` / `gem_match_ended` | `transport` ([MatchTransport](api-reference-game.md#matchtransport)) | — |\n| `gem_auth_lost` | — | — |\n| `gem_graphics_context_lost` | `gpu`, `host`, `route` | `context_ms`, `hidden`, `nth_loss` |\n\n`gem_graphics_context_lost` is the browser taking a WebGL context away —\nusually a GPU driver fault, sized per device across every game\n(`analytics/graphics.ts` lists the dimension values).",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -11139,7 +11139,7 @@
           "group": "start",
           "signature": "ARCADE_EMBEDDERS: readonly string[]",
           "documented": true,
-          "summary": "The origins the Gem Arcade embeds a game from, which every game accepts\nwithout naming them: the website, the developer site, and the Gem Arcade\napp.\n\nYou do not pass these. They are always allowed, and\n[GemOptions.allowedEmbedders](api-reference-game.md#gemoptions-allowedembedders) adds to them rather than replacing them.",
+          "summary": "The origins the Gem Arcade embeds a game from, which every game accepts\nwithout naming them: the website and the Gem Arcade app. The list also\nholds `https://developer.gemarcade.com`, which is reserved and not live —\nno page is served there, so nothing frames a game from it.\n\nYou do not pass these. They are always allowed, and\n[GemOptions.allowedEmbedders](api-reference-game.md#gemoptions-allowedembedders) adds to them rather than replacing them.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -11171,7 +11171,7 @@
           "group": "start",
           "signature": "readonly allowedEmbedders?: readonly string[]",
           "documented": true,
-          "summary": "Extra origins allowed to embed your game, **added to** the ones the Gem\nArcade uses. Most games leave this out.\n\nThe website, the developer site and the Gem Arcade app are always\nallowed — see [ARCADE_EMBEDDERS](api-reference-game.md#arcade_embedders) — so do not list them. Set this only when a site\nof your own embeds your game.\n\n```js\ncreateGem({ allowedEmbedders: ['https://my-own-site.example'] })\n```\n\nA page whose origin is not allowed gets no connection, and — deliberately —\nis told nothing about why. That means a typo here looks exactly like a\nhandshake that has not arrived: pass [GemOptions.onRefused](api-reference-game.md#gemoptions-onrefused) while you\nare integrating, because it is the only place the difference shows.\n\n⚠️ **Bake these in. Never build them from anything the page can\ninfluence** — not `location`, not a query parameter, not\n`document.referrer`. A value the embedder supplies is a check that can never\nfail. Do not add a `localhost:<port>` entry for your dev host either; the\nSDK admits one on your own machine by rule.",
+          "summary": "Extra origins allowed to embed your game, **added to** the ones the Gem\nArcade uses. Most games leave this out.\n\nThe website and the Gem Arcade app are always allowed — see\n[ARCADE_EMBEDDERS](api-reference-game.md#arcade_embedders) — so do not list them. Set this only when a site\nof your own embeds your game.\n\n```js\ncreateGem({ allowedEmbedders: ['https://my-own-site.example'] })\n```\n\nA page whose origin is not allowed gets no connection, and — deliberately —\nis told nothing about why. That means a typo here looks exactly like a\nhandshake that has not arrived: pass [GemOptions.onRefused](api-reference-game.md#gemoptions-onrefused) while you\nare integrating, because it is the only place the difference shows.\n\n⚠️ **Bake these in. Never build them from anything the page can\ninfluence** — not `location`, not a query parameter, not\n`document.referrer`. A value the embedder supplies is a check that can never\nfail. Do not add a `localhost:<port>` entry for your dev host either; the\nSDK admits one on your own machine by rule.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -13974,7 +13974,7 @@
           "group": "start",
           "signature": "function createGem(options?: GemOptions): Gem",
           "documented": true,
-          "summary": "Connect your game to the Gem Arcade. This is the one call every game makes.\n\nIt assembles everything and connects to the arcade that framed your game. The\nsame code runs on your machine and in production without a flag — but it needs\na frame either way. Opened at the top level it throws\n[GemUnframedError](api-reference-game.md#gemunframederror), which says how to run it: in the Arcade, the Editor,\nor the Gem dev host on your machine (`npm run dev`, signed in to `gemctl`).\n\nOne dependency, imported like anything else. The install is in\n[getting-started](../getting-started.md#3-add-the-sdk).\n\n```js\nimport { createGem } from '@indiegems/gem-web-sdk/sdk';\n\nconst gem = createGem();\n\nawait gem.awaitBridge();      // before loading your main bundle\nconst me = await gem.awaitIdentity();  // who is playing, once sign-in completes\n```\n\nNo options are needed. The Gem Arcade's website, developer site and app are\nalways allowed to embed your game ([ARCADE_EMBEDDERS](api-reference-game.md#arcade_embedders)), and the arcade\ntells your game which build it is.\n\nA dev host on your own machine (`gemctl serve`, the Gem Editor) needs no\nentry either: it frames a locally-served game from a loopback origin whose\nport changes every run, and the SDK admits it by rule — only while the game\nitself is served from loopback, so nothing changes once you publish.\n\nPass `allowedEmbedders` only when a site of your own frames your game. It\nadds to the arcade's origins; see [GemOptions.allowedEmbedders](api-reference-game.md#gemoptions-allowedembedders).",
+          "summary": "Connect your game to the Gem Arcade. This is the one call every game makes.\n\nIt assembles everything and connects to the arcade that framed your game. The\nsame code runs on your machine and in production without a flag — but it needs\na frame either way. Opened at the top level it throws\n[GemUnframedError](api-reference-game.md#gemunframederror), which says how to run it: in the Arcade, the Editor,\nor the Gem dev host on your machine (`npm run dev`, signed in to `gemctl`).\n\nOne dependency, imported like anything else. The install is in\n[getting-started](../getting-started.md#3-add-the-sdk).\n\n```js\nimport { createGem } from '@indiegems/gem-web-sdk/sdk';\n\nconst gem = createGem();\n\nawait gem.awaitBridge();      // before loading your main bundle\nconst me = await gem.awaitIdentity();  // who is playing, once sign-in completes\n```\n\nNo options are needed. The Gem Arcade's website and app are always allowed to\nembed your game ([ARCADE_EMBEDDERS](api-reference-game.md#arcade_embedders)), and the arcade tells your game\nwhich build it is.\n\nA dev host on your own machine (`gemctl serve`, the Gem Editor) needs no\nentry either: it frames a locally-served game from a loopback origin whose\nport changes every run, and the SDK admits it by rule — only while the game\nitself is served from loopback, so nothing changes once you publish.\n\nPass `allowedEmbedders` only when a site of your own frames your game. It\nadds to the arcade's origins; see [GemOptions.allowedEmbedders](api-reference-game.md#gemoptions-allowedembedders).",
           "deprecated": null,
           "params": [
             {
@@ -30371,9 +30371,9 @@
           "name": "PlatformEventName",
           "anchor": "platformeventname",
           "group": "analytics",
-          "signature": "type PlatformEventName = \"gem_session_start\" | \"gem_session_end\" | \"gem_pause\" | \"gem_resume\" | \"gem_boot_ready\" | \"gem_match_started\" | \"gem_match_ended\" | \"gem_auth_lost\"",
+          "signature": "type PlatformEventName = \"gem_session_start\" | \"gem_session_end\" | \"gem_pause\" | \"gem_resume\" | \"gem_boot_ready\" | \"gem_match_started\" | \"gem_match_ended\" | \"gem_auth_lost\" | \"gem_graphics_context_lost\"",
           "documented": true,
-          "summary": "Every event the SDK emits by itself.\n\nA game never sends these — `gem.analytics.track` refuses the whole\n`gem_` namespace — but the names are published because a game reading its\nown funnel needs the vocabulary, and because a funnel declared in the game\nconfig names them as steps.\n\n| Event | Dimensions | Measures |\n|---|---|---|\n| `gem_session_start` | — | — |\n| `gem_session_end` | `reason` ([SessionEndReason](api-reference-function.md#sessionendreason)) | `duration_ms` |\n| `gem_pause` / `gem_resume` | — | — |\n| `gem_boot_ready` | — | `boot_ms` |\n| `gem_match_started` / `gem_match_ended` | `transport` (`MatchTransport`) | — |\n| `gem_auth_lost` | — | — |",
+          "summary": "Every event the SDK emits by itself.\n\nA game never sends these — `gem.analytics.track` refuses the whole\n`gem_` namespace — but the names are published because a game reading its\nown funnel needs the vocabulary, and because a funnel declared in the game\nconfig names them as steps.\n\n| Event | Dimensions | Measures |\n|---|---|---|\n| `gem_session_start` | — | — |\n| `gem_session_end` | `reason` ([SessionEndReason](api-reference-function.md#sessionendreason)) | `duration_ms` |\n| `gem_pause` / `gem_resume` | — | — |\n| `gem_boot_ready` | — | `boot_ms` |\n| `gem_match_started` / `gem_match_ended` | `transport` (`MatchTransport`) | — |\n| `gem_auth_lost` | — | — |\n| `gem_graphics_context_lost` | `gpu`, `host`, `route` | `context_ms`, `hidden`, `nth_loss` |\n\n`gem_graphics_context_lost` is the browser taking a WebGL context away —\nusually a GPU driver fault, sized per device across every game\n(`analytics/graphics.ts` lists the dimension values).",
           "deprecated": null,
           "params": [],
           "returns": null,

package/docs/brand-art.md

@@ -2,8 +2,8 @@
 
 The SDK ships the platform's own art for its two currencies, **Gems** and **Coins**, and for
 **trophies**. You need it only if your game draws Gems, Coins or a trophy on its own screens. Read
-§1 before you pick a file: each currency has two kinds of art, and which one you use depends on what
-the screen is for.
+§1 before you pick a file: each currency has more than one kind of art, and which one you use
+depends on what the screen is for.
 
 > **Draw the platform's current marks with `gem.branding`, and keep these files as the fallback.**
 > `gem.branding.currencyMark('GEMS', { size: 20 })` and `gem.branding.trophy()` hand you the same
@@ -19,25 +19,35 @@ screen, and how much more your game can still pay (the earn allowance) — and n
 own. §5 is the creator's ruling and is not optional.
 
 > **The Coins art is a 3D render, open to a designer pass.** It is a gold coin with the platform's
-> gem in relief at its centre, a raised rim and a ridged edge, so a player reads it as the Arcade's
-> currency in every game rather than one game's gold. It replaced the tangerine coin of 2026-10-21,
-> which replaced the tangerine ticket of 2026-09-28. The files keep their `ticket-*` names, as the
-> currency keeps its slug `ARCADE_TICKETS`. If the art is redrawn again, the new art replaces these
-> files **under the same names** in a later SDK release, so a game that imports them picks it up on
-> its next SDK update. Lay your screens out from the sizes on this page, not from the drawing.
-
-## 1. Two kinds of currency art: pick by the ROLE of the screen
+> gem at its centre, so a player reads it as the Arcade's currency in every game rather than one
+> game's gold. The hero and the two piles (§3) are one coin — painted gold, a thick rounded edge, a
+> faceted gem standing on its face; the hero's also has a thin groove inside its rim and its gem
+> raised on a sloped base — and the icons keep the earlier gold coin, whose rings and gem channel
+> read better in a few pixels. Every coin is turned so its edge shows on the right. This
+> art replaced the gold coin of 2026-10-25, which replaced the tangerine coin of 2026-10-21. The
+> files keep their `ticket-*` names, as the currency keeps its slug `ARCADE_TICKETS`. If the art is
+> redrawn again, the new art replaces these files **under the same names** in a later SDK release,
+> so a game that imports them picks it up on its next SDK update. Lay your screens out from the
+> sizes on this page, not from the drawing.
+
+## 1. Pick the currency art by the role of the screen
 
 | You are drawing | Use | Drawn at |
 | --------------- | --- | -------- |
 | Gems **inline**, beside a number: a price, a "+15" reward label, a small chip | the **icon**, `gem-icon-20-*` or `gem-icon-32-*` | 16–40 CSS px |
 | Gems as **the subject of a reward presentation**: a victory or reward screen where the gem is what the player looks at, such as a victory overlay with a sunburst behind the reward | the **hero**, `gem-hero-*` | 64–256 CSS px |
-| Coins **inline**, beside a number | the **icon**, `ticket-icon-20-*` or `ticket-icon-32-*` | 16–40 CSS px |
+| Coins **inline** in your game's screens, beside a number | the **in-game icon**, `ticket-icon-ingame-20-*` or `ticket-icon-ingame-32-*` | 16–40 CSS px |
+| Coins as **a reward sized by how much it is**: a reward card, a results screen's payout | a **pile**, `ticket-pile-1-*` or `ticket-pile-2-*` (§3) | 64–256 CSS px |
 | Coins as **the subject of a reward presentation** | the **hero**, `ticket-hero-*` | 64–256 CSS px |
 
 The role decides first and the size follows from it. A price tag is inline even if you make it
 large; a reward screen is a presentation even on a small phone.
 
+`ticket-icon-20-*` and `ticket-icon-32-*` are the **arcade's wallet icon**: the same coin inside the
+violet rim the Gems icon wears, which the arcade draws in its own wallet. Inside your game that rim
+reads as the arcade's chrome, so draw the in-game icon there; a game that already draws the wallet
+icon keeps working, and moves to the in-game one when it next touches the screen.
+
 - **Never use the hero at icon sizes.** It is one render drawn to be seen large; shrunk to 20 px its
   outline goes under a pixel, its facet lines vanish and the gem smudges into the background.
 - **Never use the icon at hero sizes.** Each icon file is a separate render drawn for one small box,
@@ -114,12 +124,30 @@ outline weight — 1.5 px at 20, 2 px at 32.
 | | | `ticket-icon-32-2x.png` | 64 × 64 |
 | | | `ticket-icon-32-3x.png` | 96 × 96 |
 
-Like the Gems icon, each size is **its own render** of the hero's coin, not the hero scaled down.
-The coin is turned a little so its edge shows, and the lines that part its rim, field and gem — a
-groove inside the rim, a crease above the edge, a channel round the gem — are drawn wider and
+Like the Gems icon, each size is **its own render**, not the hero scaled down: the earlier gold
+coin, turned a little so its edge shows on the right, with the lines that part its rim, field and
+gem — a groove inside the rim, a crease above the edge, a channel round the gem — drawn wider and
 darker the smaller the size, so they still read in a few pixels. The 20 px coin has a slightly
 smaller gem and no ridges on its edge. Each is drawn on its own pixel grid inside the gem icon's
-violet outline. The arcade's wallet draws the same files.
+violet outline. These are the **wallet icon**: the arcade's wallet draws the same files.
+
+### The in-game Coins icon
+
+The same coin for **your game's own screens**, without the violet rim. A burnt-orange edge runs
+round its light right-hand side instead, so it stays distinct on a pale background, and its edge
+band is smooth. It comes in the same renditions and ratios, framed exactly as the wallet icon, so
+one swaps for the other in the same box.
+
+| Rendition | For a CSS box of | File | Pixels |
+| --------- | ---------------- | ---- | ------ |
+| 20 | up to about 24 px | `ticket-icon-ingame-20-1x.png` | 20 × 20 |
+| | | `ticket-icon-ingame-20-1.5x.png` | 30 × 30 |
+| | | `ticket-icon-ingame-20-2x.png` | 40 × 40 |
+| | | `ticket-icon-ingame-20-3x.png` | 60 × 60 |
+| 32 | above 24, up to about 40 px | `ticket-icon-ingame-32-1x.png` | 32 × 32 |
+| | | `ticket-icon-ingame-32-1.5x.png` | 48 × 48 |
+| | | `ticket-icon-ingame-32-2x.png` | 64 × 64 |
+| | | `ticket-icon-ingame-32-3x.png` | 96 × 96 |
 
 ## 3. The hero art
 
@@ -147,10 +175,31 @@ size you draw it multiplied by the screen's `devicePixelRatio`:
 **Do not draw it larger than 256 CSS pixels.** On a 3× screen that needs more than the largest file,
 and the art softens as it is stretched. Below 64 px, use the icon (§2).
 
+### The coin piles
+
+Two heaps of the hero's coin, for a Coins reward your game **offers or has just paid** where the
+size of the heap says how much: a reward card, or a results screen's payout. Pile 1 is a few short
+stacks; pile 2 holds about twice the coins.
+
+| Pile | Use it for | Files |
+| ---- | ---------- | ----- |
+| 1 | an everyday reward | `ticket-pile-1-128.png`, `ticket-pile-1-256.png`, `ticket-pile-1-384.png`, `ticket-pile-1-512.png`, `ticket-pile-1-768.png` |
+| 2 | a bigger reward | `ticket-pile-2-128.png`, `ticket-pile-2-256.png`, `ticket-pile-2-384.png`, `ticket-pile-2-512.png`, `ticket-pile-2-768.png` |
+
+**Pick the pile by where the reward sits among your game's own rewards, not by a number of Coins.**
+Where a reward's size doesn't matter, the hero does as well.
+
+Both piles share one frame: a square, transparent PNG with a margin all round, each heap centred
+across and standing on the same baseline. Pile 2 fills the frame and pile 1 is drawn smaller, so the
+two side by side climb from left to right with no scaling in your layout. Draw them at the hero's
+sizes, **64 to 256 CSS pixels**, and pick the file as for the hero above.
+
 ## 4. Loading and drawing the art
 
-The platform serves every one of these files through `gem.branding` ([branding.md](branding.md)),
+The platform serves the icons and the heroes through `gem.branding` ([branding.md](branding.md)),
 which is what to draw first. The copies below are the fallback for when it answers `unavailable`.
+The in-game Coins icon and the coin piles are not in the platform's manifest yet: draw them from
+here.
 
 All of it is in the package you already install, under `brand/`, and published beside it on the CDN —
 the same bytes either way, for the version you are on.

package/docs/changelog.md

@@ -16,6 +16,37 @@ Its entries are grouped under up to five headings:
 - **Rebuild**: a type changed. Recompile against the new version; code that compiles today keeps compiling unless the entry says otherwise.
 - **New capability**: something a game can now do. Nothing changes unless you use it.
 
+## 21.0.0
+
+Upgrading from 20.1.0. Impact: required.
+
+### May stop
+
+- You do not need to write your own code to count lost WebGL contexts for analytics. Every game now reports each loss automatically, with no code of its own. The SDK only observes the loss, so whether your game restores its context stays your decision, and your own handling keeps working unchanged.
+
+### Rebuild
+
+- The set of platform event names now includes a new member, gem_graphics_context_lost, which the SDK emits when the browser takes away one of the game's WebGL contexts. Recompiling is enough for most games. If your game switches over every platform event name exhaustively, or maps each name to a value, add a case for the new name so it still compiles.
+
+### New capability
+
+- A new in-game Coins icon is available in two sizes, 20 and 32, each at four pixel ratios: 1x, 1.5x, 2x and 3x. It is the Coins coin without the violet rim, so it does not look like the Arcade's own chrome inside a game. Use it wherever your game shows Coins. The wallet icon keeps its violet rim.
+- Two coin piles are now available for showing a Coins reward sized by how much it is: pile 1 for an everyday reward and pile 2 for a bigger one. Each comes in five widths: 128, 256, 384, 512 and 768. They share one frame and baseline, so a row of them climbs from the smaller to the larger. Larger piles are reserved for the Arcade's own shop. The Coins hero art remains the choice when the size of the reward does not matter.
+
+## 20.1.0
+
+Upgrading from 20.0.0. Impact: required.
+
+### Rebuild
+
+- The list of capability names a game can advertise gained one value, p2pRelayDrain. Recompile. If the game switches exhaustively over capability names, add a case for it. Otherwise nothing else changes.
+- The list of messages the Arcade page sends to the game frame gained one entry, gem.relayDraining, and the parent message type gained the matching member. Recompile. If the game handles every parent message in an exhaustive switch, add a case for the new one. Otherwise nothing else changes.
+
+### New capability
+
+- A game can now be told when a relay carrying its peer-to-peer match is draining and by when. Pass onRelayDraining in the frame options, or implement it on the frame callbacks, to receive the notice. The SDK already moves the connection off the draining relay by itself, so use this only to inform the player or log it. The notice is sent only by an Arcade page that supports it.
+- Telemetry samples can now carry labels, so a game that reads or forwards telemetry samples can see per-sample label values such as outcome and reason.
+
 ## 20.0.0
 
 Upgrading from 19.0.2. Impact: required.

package/docs/dedicated-server-flow.md

@@ -715,11 +715,39 @@ host does, and the SDK does it for you:
 
 | What gem-api answers | Where | What the SDK does |
 | --- | --- | --- |
-| `invalid_cluster_target` | `create()`, `quickJoin()` | Waits up to five seconds for the page to send a different list, and tries once more with it |
+| `invalid_cluster_target` | `create()` | Creates in the next cluster the page sent, at once, until every one has been refused; then waits up to five seconds for the page to send a different list, and tries once more with a cluster it has not yet tried |
+| `invalid_cluster_target` | `quickJoin()` | Waits up to five seconds for the page to send a different list, and tries once more with it |
 | `invalid_cluster_target` | `startMatch()` — the platform does not run the room's cluster | Starts once in this player's best other cluster, naming it, which moves the room |
 | `capacity_unavailable` twice in a row | `startMatch()` | Moves to the next acceptable cluster, once, and keeps waiting there |
 
-**Each of them happens once.** A second refusal is the answer, and it reaches you as the error.
+**Each wait and each move happens once.** `create()` trying each cluster the page sent counts as one
+step, and it tries three at most, because the page sends three at most. A refusal after that is the
+answer, and it reaches you as the error.
+
+### When the platform hides a cluster
+
+An operator can **hide** a cluster to take it out of service without stopping it: it leaves the list
+the page measures, it takes no new rooms, no new matches and no new TURN relay leases, and the
+matches already running on it carry on. A page that measured before the hide still lists it until
+it measures again, so the SDK is what moves that player on:
+
+- **`create()`** is refused with `invalid_cluster_target` for the hidden cluster and creates in the
+  next one the page sent, with no wait.
+- **`quickJoin()` and matchmaking** need nothing: the platform drops the hidden cluster from the list
+  they send and serves the rest.
+- **`startMatch()`** in a room on the hidden cluster is refused the same way and starts once in the
+  host's best other cluster, which moves the room — as for any cluster the platform stopped running.
+- **A P2P relay lease** is answered from another cluster in the same region when there is one, and
+  otherwise refused; the SDK then leases from the next cluster the page sent. See
+  `p2p-and-parties.md` §4.
+
+An earlier SDK version reaches the same place more slowly or not at all. Its `create()` names only the
+best cluster, waits up to five seconds for a list the page will not send, and then gives you the
+refusal, so a game that creates rooms shows an error until the page measures again. Its P2P lease asks
+the hidden cluster once and, with no other cluster in that region to answer for it, connects without
+a relay. Its `startMatch()` and matchmaking behave as above, and so does its `quickJoin()` from
+5.11.0 on, when the SDK began sending the page's whole list; before that a quick-join names one
+cluster, and one naming only the hidden cluster is refused.
 
 **An automatic start has nobody to answer, so the host's SDK answers it.** When a room's template
 starts the match as it fills to `min_players` and the platform refuses that start, no call is waiting

package/docs/getting-started.md

@@ -50,7 +50,7 @@ either way.
 ```jsonc
 // package.json
 "dependencies": {
-  "@indiegems/gem-web-sdk": "20.0.0"
+  "@indiegems/gem-web-sdk": "21.0.0"
 }
 ```
 
@@ -137,8 +137,8 @@ const me = await gem.awaitIdentity();
 
 Two things about that call are worth getting right the first time.
 
-**You do not list who may embed your game.** The Gem Arcade's website, developer site and app
-are always allowed, and so is a dev host on your own machine (`gemctl serve`, the Gem Editor) while your
+**You do not list who may embed your game.** The Gem Arcade's website and app are always
+allowed, and so is a dev host on your own machine (`gemctl serve`, the Gem Editor) while your
 game is served from loopback. `allowedEmbedders` exists only for a page beyond those — see
 [the embedder allowlist](what-a-game-must-do.md#1-the-embedder-allowlist) — and it adds to the
 arcade's origins rather than replacing them.