@indiegems/gem-web-sdk 19.0.2 → 20.1.0

package/dist/sdk.d.ts

@@ -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/api/api-reference-function.md

@@ -1,6 +1,6 @@
 # The function surface — API reference
 
-Generated from `@indiegems/gem-web-sdk/function` v19.0.2, 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` v20.1.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.
 

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

@@ -1,6 +1,6 @@
 # The browser surface — API reference
 
-Generated from `@indiegems/gem-web-sdk/sdk` v19.0.2, 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` v20.1.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.
 
@@ -4779,16 +4779,17 @@ purchase(skuId: string): Promise<ArcadeOutcome>
 Ask the arcade to open checkout for one SKU from [StoreApi.offers](#storeapi-offers):
 the payment provider's page on the web, the app store's purchase sheet in
 the Arcade's apps, straight away, with no confirmation screen of the
-arcade's own first. **Call it from the player's press handler** — the
-arcade refuses an ask no person pressed for, `declined` / `busy`.
+arcade's own first. It needs no press: call it from your Buy button's
+handler, or after an `await` in it, and the checkout opens either way.
 
 - `ok` — the player paid. Re-read balances and inventory through `gem.me`;
   nothing here carries an amount. With `reason: 'pending'`, the provider
   has not settled yet: [StoreApi.onSettled](#storeapi-onsettled) hears when it does.
 - `declined` — nothing was bought: `cancelled` (the player closed the
-  checkout, or the offer cannot be bought again yet) or `busy` (after a
-  closed checkout the arcade refuses the next ask for a while). Return to
-  your screen silently, and do not ask again unprompted.
+  checkout, or the offer cannot be bought again yet) or `busy` (another
+  checkout or Arcade sheet was already open). Return to your screen
+  silently, and do not ask again unprompted: the player's next press opens
+  the checkout again, however many times they closed it.
 - `unavailable` with `store_off`, `sign_in_required`, `not_found`,
   `unsupported`, `invalid_argument` or a payment provider's failure code —
   nothing was bought.
@@ -4819,7 +4820,7 @@ Ask the arcade to show one SKU from [StoreApi.offers](#storeapi-offers) in its o
 sheet, over your paused and hidden game: its art, what the player gets, a
 sale if one is on, and, for a pass the player already holds, how long it
 has left. The sheet's Buy opens the same checkout as
-[StoreApi.purchase](#storeapi-purchase). **Call it from the player's press handler.**
+[StoreApi.purchase](#storeapi-purchase). Like `purchase`, it needs no press.
 
 Use it for an offer you would have to hardcode a pitch for: VIP and other
 passes, and bundles. Your button only needs to say what it opens. Draw a
@@ -4828,8 +4829,8 @@ Gem pack yourself and use `purchase` instead. Check
 
 It answers exactly as `purchase` does, with one addition: `declined` /
 `cancelled` also covers the player leaving the sheet without pressing Buy,
-and you are not told which of the two they closed. That starts the same
-back-off, so do not ask again unprompted. `unavailable` / `unsupported`
+and you are not told which of the two they closed. Do not ask again
+unprompted; the player's next press opens it again. `unavailable` / `unsupported`
 means this Arcade does not draw the sheet, and nothing was sent.
 `unavailable` / `error` means **the outcome is unknown**: re-read balances
 and inventory through `gem.me`, and keep listening with
@@ -9503,8 +9504,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.
@@ -9533,8 +9535,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
@@ -11581,7 +11583,7 @@ sheet. To spend Gems or Coins on your game's own items, use
 [Gem.purchases](#gem-purchases).
 
 List what the store sells here with `offers()`, show each `priceDisplay`
-exactly as given, and call `purchase(skuId)` from the player's press. For a
+exactly as given, and call `purchase(skuId)` when the player chooses to buy. For a
 pass, a bundle or anything else whose pitch you would have to hardcode, call
 `showOffer(skuId)` instead, and the arcade draws the offer. After `ok`,
 re-read balances through [Gem.me](#gem-me), and `gem.me.passes` for a pass.
@@ -12592,9 +12594,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` v19.0.2, 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` v20.1.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": "19.0.2"
+    "version": "20.1.0"
   },
   "entries": [
     {
@@ -5735,7 +5735,7 @@
           "group": "store",
           "signature": "purchase(skuId: string): Promise<ArcadeOutcome>",
           "documented": true,
-          "summary": "Ask the arcade to open checkout for one SKU from [StoreApi.offers](api-reference-game.md#storeapi-offers):\nthe payment provider's page on the web, the app store's purchase sheet in\nthe Arcade's apps, straight away, with no confirmation screen of the\narcade's own first. **Call it from the player's press handler** — the\narcade refuses an ask no person pressed for, `declined` / `busy`.\n\n- `ok` — the player paid. Re-read balances and inventory through `gem.me`;\n  nothing here carries an amount. With `reason: 'pending'`, the provider\n  has not settled yet: [StoreApi.onSettled](api-reference-game.md#storeapi-onsettled) hears when it does.\n- `declined` — nothing was bought: `cancelled` (the player closed the\n  checkout, or the offer cannot be bought again yet) or `busy` (after a\n  closed checkout the arcade refuses the next ask for a while). Return to\n  your screen silently, and do not ask again unprompted.\n- `unavailable` with `store_off`, `sign_in_required`, `not_found`,\n  `unsupported`, `invalid_argument` or a payment provider's failure code —\n  nothing was bought.\n- `unavailable` / `error` — **the outcome is unknown, and the player may\n  have paid.** It is what you get when the bridge closes while checkout\n  is open, or the arcade has no reliable answer. Never tell the player\n  nothing was bought: re-read balances and inventory through `gem.me`,\n  and keep listening with [StoreApi.onSettled](api-reference-game.md#storeapi-onsettled).\n\nNO TIMEOUT: it waits for as long as the arcade is connected, because a\npayment takes as long as it takes.",
+          "summary": "Ask the arcade to open checkout for one SKU from [StoreApi.offers](api-reference-game.md#storeapi-offers):\nthe payment provider's page on the web, the app store's purchase sheet in\nthe Arcade's apps, straight away, with no confirmation screen of the\narcade's own first. It needs no press: call it from your Buy button's\nhandler, or after an `await` in it, and the checkout opens either way.\n\n- `ok` — the player paid. Re-read balances and inventory through `gem.me`;\n  nothing here carries an amount. With `reason: 'pending'`, the provider\n  has not settled yet: [StoreApi.onSettled](api-reference-game.md#storeapi-onsettled) hears when it does.\n- `declined` — nothing was bought: `cancelled` (the player closed the\n  checkout, or the offer cannot be bought again yet) or `busy` (another\n  checkout or Arcade sheet was already open). Return to your screen\n  silently, and do not ask again unprompted: the player's next press opens\n  the checkout again, however many times they closed it.\n- `unavailable` with `store_off`, `sign_in_required`, `not_found`,\n  `unsupported`, `invalid_argument` or a payment provider's failure code —\n  nothing was bought.\n- `unavailable` / `error` — **the outcome is unknown, and the player may\n  have paid.** It is what you get when the bridge closes while checkout\n  is open, or the arcade has no reliable answer. Never tell the player\n  nothing was bought: re-read balances and inventory through `gem.me`,\n  and keep listening with [StoreApi.onSettled](api-reference-game.md#storeapi-onsettled).\n\nNO TIMEOUT: it waits for as long as the arcade is connected, because a\npayment takes as long as it takes.",
           "deprecated": null,
           "params": [
             {
@@ -5758,7 +5758,7 @@
           "group": "store",
           "signature": "showOffer(skuId: string): Promise<ArcadeOutcome>",
           "documented": true,
-          "summary": "Ask the arcade to show one SKU from [StoreApi.offers](api-reference-game.md#storeapi-offers) in its own\nsheet, over your paused and hidden game: its art, what the player gets, a\nsale if one is on, and, for a pass the player already holds, how long it\nhas left. The sheet's Buy opens the same checkout as\n[StoreApi.purchase](api-reference-game.md#storeapi-purchase). **Call it from the player's press handler.**\n\nUse it for an offer you would have to hardcode a pitch for: VIP and other\npasses, and bundles. Your button only needs to say what it opens. Draw a\nGem pack yourself and use `purchase` instead. Check\n[StoreApi.showOfferAvailable](api-reference-game.md#storeapi-showofferavailable) first, and that the SKU is in `offers`.\n\nIt answers exactly as `purchase` does, with one addition: `declined` /\n`cancelled` also covers the player leaving the sheet without pressing Buy,\nand you are not told which of the two they closed. That starts the same\nback-off, so do not ask again unprompted. `unavailable` / `unsupported`\nmeans this Arcade does not draw the sheet, and nothing was sent.\n`unavailable` / `error` means **the outcome is unknown**: re-read balances\nand inventory through `gem.me`, and keep listening with\n[StoreApi.onSettled](api-reference-game.md#storeapi-onsettled).\n\nNO TIMEOUT: it waits for as long as the arcade is connected, because a\nplayer may read a sheet and pay for as long as they like.",
+          "summary": "Ask the arcade to show one SKU from [StoreApi.offers](api-reference-game.md#storeapi-offers) in its own\nsheet, over your paused and hidden game: its art, what the player gets, a\nsale if one is on, and, for a pass the player already holds, how long it\nhas left. The sheet's Buy opens the same checkout as\n[StoreApi.purchase](api-reference-game.md#storeapi-purchase). Like `purchase`, it needs no press.\n\nUse it for an offer you would have to hardcode a pitch for: VIP and other\npasses, and bundles. Your button only needs to say what it opens. Draw a\nGem pack yourself and use `purchase` instead. Check\n[StoreApi.showOfferAvailable](api-reference-game.md#storeapi-showofferavailable) first, and that the SKU is in `offers`.\n\nIt answers exactly as `purchase` does, with one addition: `declined` /\n`cancelled` also covers the player leaving the sheet without pressing Buy,\nand you are not told which of the two they closed. Do not ask again\nunprompted; the player's next press opens it again. `unavailable` / `unsupported`\nmeans this Arcade does not draw the sheet, and nothing was sent.\n`unavailable` / `error` means **the outcome is unknown**: re-read balances\nand inventory through `gem.me`, and keep listening with\n[StoreApi.onSettled](api-reference-game.md#storeapi-onsettled).\n\nNO TIMEOUT: it waits for as long as the arcade is connected, because a\nplayer may read a sheet and pay for as long as they like.",
           "deprecated": null,
           "params": [
             {
@@ -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,
@@ -13228,7 +13228,7 @@
           "group": "start",
           "signature": "readonly store: StoreApi",
           "documented": true,
-          "summary": "**Real money.** The Arcade Store's own Gem packs, Boosts, passes and\nbundles, sold for the player's money through the arcade's own purchase\nsheet. To spend Gems or Coins on your game's own items, use\n[Gem.purchases](api-reference-game.md#gem-purchases).\n\nList what the store sells here with `offers()`, show each `priceDisplay`\nexactly as given, and call `purchase(skuId)` from the player's press. For a\npass, a bundle or anything else whose pitch you would have to hardcode, call\n`showOffer(skuId)` instead, and the arcade draws the offer. After `ok`,\nre-read balances through [Gem.me](api-reference-game.md#gem-me), and `gem.me.passes` for a pass.\nNothing rejects.",
+          "summary": "**Real money.** The Arcade Store's own Gem packs, Boosts, passes and\nbundles, sold for the player's money through the arcade's own purchase\nsheet. To spend Gems or Coins on your game's own items, use\n[Gem.purchases](api-reference-game.md#gem-purchases).\n\nList what the store sells here with `offers()`, show each `priceDisplay`\nexactly as given, and call `purchase(skuId)` when the player chooses to buy. For a\npass, a bundle or anything else whose pitch you would have to hardcode, call\n`showOffer(skuId)` instead, and the arcade draws the offer. After `ok`,\nre-read balances through [Gem.me](api-reference-game.md#gem-me), and `gem.me.passes` for a pass.\nNothing rejects.",
           "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": [
             {

package/docs/arcade-and-store.md

@@ -33,7 +33,7 @@ itself. You get an outcome.
 - [1. Two surfaces, and which one is real money](#1-two-surfaces-and-which-one-is-real-money)
 - [2. Nothing rejects](#2-nothing-rejects)
 - [3. What is available here](#3-what-is-available-here)
-- [4. Call the acting ones from a press](#4-call-the-acting-ones-from-a-press)
+- [4. Leaving takes a press; buying does not](#4-leaving-takes-a-press-buying-does-not)
 - [5. App links](#5-app-links)
 - [6. Opening another game](#6-opening-another-game)
 - [7. Similar games, as cards](#7-similar-games-as-cards)
@@ -88,20 +88,25 @@ the bridge is up. A feature can be off for reasons you
 cannot see from inside the frame: a TV, an in-app browser that cannot take payment, an app build
 where it is withheld. Do not guess; read it.
 
-## 4. Call the acting ones from a press
+## 4. Leaving takes a press; buying does not
 
 Four calls put something in front of the player: `gem.arcade.openApp`, `gem.arcade.openGame`,
-`gem.store.purchase` and `gem.store.showOffer`. **Call each one from the player's own press handler**, in the same turn as the
-press. The Arcade checks that a person pressed, and refuses an ask nobody pressed for with
-`declined` / `busy`, showing nothing.
-
+`gem.store.purchase` and `gem.store.showOffer`.
+
+- **Leaving the game takes a press.** Call `openApp` and `openGame` from the player's own press
+  handler, in the same turn as the press. The Arcade checks that a person pressed, and refuses an
+  ask nobody pressed for with `declined` / `busy`, showing nothing. Never on a timer, never on
+  load, never in a retry loop.
+- **Buying does not.** `gem.store.purchase` and `gem.store.showOffer` open their checkout or sheet
+  after an `await`, from a timer, or where the browser cannot report a press: the checkout is where
+  the player confirms, and your game cannot press it. Nothing backs off either, so the player's
+  next press after closing a checkout opens it again. Still ask only because the player chose to
+  buy.
 - **Controllers count.** A gamepad press the Arcade sees counts as a press. Do not add a keyboard or
   pointer workaround for pad players.
 - **One at a time.** Only one of these is open at once, across both surfaces and the Arcade's other
   sheets (a Gem purchase, a share, a friend challenge). A second ask while one is open is
   `declined` / `busy`. The SDK answers it for you without sending.
-- **Never on a timer, never on load, never in a retry loop.** None of them would have a press, so
-  all of them would be refused.
 
 The reads (`appLinks`, `similarGames`, `offers`) need no press. A second call while one is open
 shares the first one's answer.
@@ -250,9 +255,10 @@ first: the payment provider's page on the web, the app store's own purchase shee
 apps. That checkout is where the player confirms and pays. Your game is resumed before the answer
 arrives, so your own celebration is visible.
 
-- **Call it from the press** ([§4](#4-call-the-acting-ones-from-a-press)). The player's press on
-  your Buy button is what opens checkout, so make that button say plainly what it buys and for how
-  much (`priceDisplay`).
+- **Call it when the player chooses to buy** ([§4](#4-leaving-takes-a-press-buying-does-not)).
+  No press is needed — an `await` before it is fine — but the player's press on your Buy button is
+  what they expect to open checkout, so make that button say plainly what it buys and for how much
+  (`priceDisplay`).
 - **It has no timeout.** A payment takes as long as it takes, so the call waits for as long as the
   Arcade is connected.
 - `ok`: the player paid. **Read balances and inventory through `gem.me`**; the answer carries no
@@ -266,10 +272,11 @@ arrives, so your own celebration is visible.
   ```
 
 - `declined` / `cancelled`: the player closed the checkout without paying. Return to your screen
-  quietly and **do not ask again unprompted**: the Arcade backs off after the player closes one, and
-  the next ask is `declined` / `busy` for a while, longer each time. An offer the player cannot buy
-  again yet also answers `declined` / `cancelled`: the Arcade tells the player when it can be
-  bought, opens nothing, and does not back off.
+  quietly and **do not ask again unprompted**. Nothing backs off: the player's next press opens the
+  checkout again, however many times they closed it. An offer the player cannot buy again yet also
+  answers `declined` / `cancelled`: the Arcade tells the player when it can be bought, and opens
+  nothing.
+- `declined` / `busy`: another checkout or Arcade sheet was already open. Nothing was shown.
 - `unavailable` with `store_off`, `sign_in_required` or `not_found` (a SKU that is not in
   `offers()` right now), or with a payment provider's own failure code: nothing was bought. The
   first three show nothing.
@@ -304,13 +311,13 @@ pass the player already holds, how long it has left. The sheet's Buy opens the s
 
 Pick by who can say what the offer is:
 
-|                 | **You draw it: `offers()` + `purchase()`**                | **The Arcade draws it: `showOffer()`**                       |
-| --------------- | --------------------------------------------------------- | ------------------------------------------------------------ |
-| Use it for      | Gem packs: a name, an amount and a price say it all       | VIP and other passes, and bundles                            |
-| Your button     | says what it buys and shows `priceDisplay`                | says what it opens, such as "Get VIP"                        |
-| The press opens | the checkout, straight away                               | the Arcade's sheet, then the checkout if the player presses Buy |
-| Perks and sales | not available to you                                      | always current, in the player's language                     |
-| A holder sees   | the same Buy button                                       | what they already have                                       |
+|                 | **You draw it: `offers()` + `purchase()`**          | **The Arcade draws it: `showOffer()`**                          |
+| --------------- | --------------------------------------------------- | --------------------------------------------------------------- |
+| Use it for      | Gem packs: a name, an amount and a price say it all | VIP and other passes, and bundles                               |
+| Your button     | says what it buys and shows `priceDisplay`          | says what it opens, such as "Get VIP"                           |
+| The press opens | the checkout, straight away                         | the Arcade's sheet, then the checkout if the player presses Buy |
+| Perks and sales | not available to you                                | always current, in the player's language                        |
+| A holder sees   | the same Buy button                                 | what they already have                                          |
 
 - **Never write an offer's perks into your game.** They change without a new build of your game, and
   yours would go stale. Your button only needs the offer's name.
@@ -328,10 +335,8 @@ Pick by who can say what the offer is:
 
 Every rule of `purchase` holds ([§9](#9-buying-from-the-arcade-store)), and the answers are the
 same, with one addition. `declined` / `cancelled` also covers the player leaving the sheet without
-pressing Buy, and you are not told which of the two they closed. That starts the same back-off as a
-closed checkout, shared with `purchase`: the next ask of either kind is `declined` / `busy` for a
-while. The press shows nothing during a back-off, so give the player something else to do on that
-screen.
+pressing Buy, and you are not told which of the two they closed. Nothing backs off: the player's
+next press on either button opens it again.
 
 ## 11. What the player holds, and a VIP door
 
@@ -445,14 +450,14 @@ player, and the route refuses it with `403`. The body is `{ pass, held, ends_at
 While something listens to `on('changed')`, the SDK reads again at each of these, and calls you only
 if the answer differs:
 
-| Moment                                                    | Why you cannot rely on something else                                      |
-| --------------------------------------------------------- | -------------------------------------------------------------------------- |
-| `store.purchase` or `store.showOffer` answers `ok`        | `onSettled` does not fire after a plain `ok`                               |
-| Either answers `unavailable` / `error`                    | The outcome is unknown, and the player may have paid                       |
-| `gem.store.onSettled` fires                               | `ok` / `pending` still reads as not held                                   |
-| Your game resumes                                         | A purchase in the Arcade's own store, from the Gem menu, sends no event at all |
-| The player signs in                                       | A guest who signs in may hold VIP                                          |
-| A held pass reaches `endsAt`                              | VIP does not renew, so the door has to lock by itself                      |
+| Moment                                             | Why you cannot rely on something else                                          |
+| -------------------------------------------------- | ------------------------------------------------------------------------------ |
+| `store.purchase` or `store.showOffer` answers `ok` | `onSettled` does not fire after a plain `ok`                                   |
+| Either answers `unavailable` / `error`             | The outcome is unknown, and the player may have paid                           |
+| `gem.store.onSettled` fires                        | `ok` / `pending` still reads as not held                                       |
+| Your game resumes                                  | A purchase in the Arcade's own store, from the Gem menu, sends no event at all |
+| The player signs in                                | A guest who signs in may hold VIP                                              |
+| A held pass reaches `endsAt`                       | VIP does not renew, so the door has to lock by itself                          |
 
 A read that fails changes nothing, and is tried again later. A read that was already on its way when
 a purchase ended is never reused, so a stale answer cannot shut the door on the buyer. If you read
@@ -473,15 +478,15 @@ Until then, decide in a function, or leave a VIP door out of a dedicated-server
 
 ## 12. Outcomes and reasons
 
-| Call             | `ok`                      | `declined`          | `unavailable`                                                                                                 |
-| ---------------- | ------------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------- |
-| `appLinks`       | listings to draw          |                     | `unsupported`, `error`                                                                                        |
-| `openApp`        | opened, or `handed_off`   | `busy`              | `already_in_app`, `unsupported`, `error`                                                                      |
-| `openGame`       | the next game is starting | `busy`, `same_game` | `not_found`, `unsupported`, `error`                                                                           |
-| `similarGames`   | cards, possibly none      |                     | `unsupported`, `error`                                                                                        |
-| `store.offers`   | offers, possibly none     |                     | `sign_in_required`, `store_off`, `unsupported`, `error`                                                       |
-| `store.purchase` | paid, or `pending`        | `cancelled`, `busy` | `sign_in_required`, `store_off`, `not_found`, the provider's reason, `unsupported`, `error` (outcome unknown) |
-| `store.showOffer` | paid, or `pending`       | `cancelled`, `busy` | `sign_in_required`, `store_off`, `not_found`, the provider's reason, `unsupported`, `error` (outcome unknown) |
+| Call              | `ok`                      | `declined`          | `unavailable`                                                                                                 |
+| ----------------- | ------------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `appLinks`        | listings to draw          |                     | `unsupported`, `error`                                                                                        |
+| `openApp`         | opened, or `handed_off`   | `busy`              | `already_in_app`, `unsupported`, `error`                                                                      |
+| `openGame`        | the next game is starting | `busy`, `same_game` | `not_found`, `unsupported`, `error`                                                                           |
+| `similarGames`    | cards, possibly none      |                     | `unsupported`, `error`                                                                                        |
+| `store.offers`    | offers, possibly none     |                     | `sign_in_required`, `store_off`, `unsupported`, `error`                                                       |
+| `store.purchase`  | paid, or `pending`        | `cancelled`, `busy` | `sign_in_required`, `store_off`, `not_found`, the provider's reason, `unsupported`, `error` (outcome unknown) |
+| `store.showOffer` | paid, or `pending`        | `cancelled`, `busy` | `sign_in_required`, `store_off`, `not_found`, the provider's reason, `unsupported`, `error` (outcome unknown) |
 
 Every reason is a short code of lower-case letters and underscores. The Arcade turns a payment
 provider's own code into that shape before it reaches you.

package/docs/changelog.md

@@ -16,6 +16,32 @@ 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.
 
+## 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.
+
+### Must change
+
+- The parent conformance version moved from 3 to 4. If your game, test setup or tooling checks against the conformance version or runs the parent conformance checks, update it to expect version 4. Checks written for version 3 will now fail where they expect a purchase to be refused without a player press, or expect purchases to be refused after a player dismissed a checkout or sheet.
+
+### May stop
+
+- Purchases no longer need a player press. A purchase asked from a timer or after an await opens its checkout, and the checkout is the confirmation. Games can drop code that holds a purchase request back until a tap or click. Games can also drop code that waits out a pause after a player dismisses a checkout or sheet, because the next request opens it again. Two things are unchanged: leaving the game still needs a press, and a purchase asked while another surface is open is still declined as busy.
+
 ## 19.0.2
 
 Upgrading from 19.0.1. Impact: none.

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": "19.0.2"
+  "@indiegems/gem-web-sdk": "20.1.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.