@indiegems/gem-web-sdk 20.0.0 → 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` 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` 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` 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` 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.
 
@@ -9504,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.
@@ -9534,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
@@ -12593,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` 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` 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": "20.0.0"
+    "version": "20.1.0"
   },
   "entries": [
     {
@@ -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": [
             {

package/docs/changelog.md

@@ -16,6 +16,20 @@ 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.

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": "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.

package/docs/manifest.json

@@ -48,8 +48,8 @@
     },
     {
       "file": "changelog.md",
-      "sha256": "37f3bde69baa7c0280e7d8a58800c1509b3b61c76a684428832bf094f298478b",
-      "updated": "2026-11-02T19:11:02Z"
+      "sha256": "8a292ee18fe7f910be0af049d96df66ccebf5c810fe5495c11d5352f7ee121f4",
+      "updated": "2026-11-03T00:39:38Z"
     },
     {
       "file": "daily-challenges.md",
@@ -58,8 +58,8 @@
     },
     {
       "file": "dedicated-server-flow.md",
-      "sha256": "6da1bfc820ab2cf79180f69f9fec4d9f377ddde690f53923e749a88ec6307e22",
-      "updated": "2026-10-02T19:04:21Z"
+      "sha256": "4a51622df43be68b5b9a88ae89907972090e64fd9b793ba74e5daa576489281c",
+      "updated": "2026-10-27T02:41:17Z"
     },
     {
       "file": "deprecation-policy.md",
@@ -78,8 +78,8 @@
     },
     {
       "file": "getting-started.md",
-      "sha256": "896f7d29d2017e5c42fec20386bce31eacf3f5143b7134c7607574b452c039bf",
-      "updated": "2026-11-02T19:11:02Z"
+      "sha256": "0c4cee83ffc77711f43ccdaafb394283a5a412b78395db1434ebbc2ab6943667",
+      "updated": "2026-11-03T00:39:38Z"
     },
     {
       "file": "inventory-and-catalogs.md",
@@ -93,13 +93,13 @@
     },
     {
       "file": "match-session.md",
-      "sha256": "cfc2f76e310f4a851ac0b9185687d284cced6533fe12fb359ce0cb2845c5e5ef",
-      "updated": "2026-10-23T01:58:45Z"
+      "sha256": "121eb2bd92da9daf3922097699e0ab450da6a087eec8de552fe573094cf7e2c4",
+      "updated": "2026-11-02T16:12:53Z"
     },
     {
       "file": "p2p-and-parties.md",
-      "sha256": "4cfe2a47def51eb617f154eaac39faf176d8aa7ca2c36907084b6349048ab1b9",
-      "updated": "2026-10-17T22:11:15Z"
+      "sha256": "1de834a88746a4c7b6de555b3e6e3500fce0b7e75fc3cb87d46795efc7e27940",
+      "updated": "2026-11-02T23:33:48Z"
     },
     {
       "file": "platform-moments.md",
@@ -138,8 +138,8 @@
     },
     {
       "file": "server-bundles.md",
-      "sha256": "655a5835bf9d1c13997784de57aaf54566d72641bfe220da8a37903d5fad044c",
-      "updated": "2026-11-02T19:11:02Z"
+      "sha256": "f54aeb88c268e5b657be9d0ea323d44cc61bfbb76fc84670f8a607d4514b005d",
+      "updated": "2026-11-03T00:39:38Z"
     },
     {
       "file": "serverless-functions-js.md",
@@ -163,8 +163,8 @@
     },
     {
       "file": "what-a-game-must-do.md",
-      "sha256": "17df2ebdafe56ac5eafdf4eba783c97025ddd9e0ee88b7b43d25718908496b2a",
-      "updated": "2026-11-02T14:57:41Z"
+      "sha256": "059f3c8a31c0f6098d2c8e4836b79e866d0c5486443dc89039e160648946bd68",
+      "updated": "2026-11-02T23:27:22Z"
     }
   ]
 }

package/docs/match-session.md

@@ -155,6 +155,15 @@ own. When a host migration is already in flight the attempt waits it out instead
 the way back, and it re-attaches this connection without a dial (§5.1 of
 [p2p-and-parties.md](p2p-and-parties.md)).
 
+**A relay that moves is not a drop.** When the platform takes a TURN relay out of service, or one
+dies under a match, the SDK moves the peer-to-peer connection to another relay with an ICE restart
+on the connection it already has (§4.1 and §5 of [p2p-and-parties.md](p2p-and-parties.md)). The
+data channels stay open, so there is no `matchSuspended`, no `matchReconnected` and nothing to
+resync — at most a pause of a few seconds while the route changes. Only a move that misses the
+platform's deadline, or a restart that never comes back, leaves that path: the first is a drop with
+`cause: 'link_closed'` and the re-dial above; the second is treated as the host being gone, as §5
+there describes.
+
 The loop never runs while the page is hidden. It parks, and the next visible edge — the phone
 unlocked, the tab foregrounded — is itself a read, so a match that ended while the player was away
 resolves to `matchEnded` and one that is still running resumes reconnecting. Nothing in your game

package/docs/p2p-and-parties.md

@@ -327,6 +327,14 @@ peer connection's configuration when it is constructed. Leasing afterwards
 produces a connection that works whenever both peers are directly reachable —
 which passes every test on a LAN and fails for a large minority of real players.
 
+**A lease has a lifetime, and a match can outlast it.** The SDK keeps the
+lease's expiry and renews it whenever it is about to build a connection on a
+lease within two minutes of running out — a host answering a player's offer,
+or a player rebuilding after a migration — so a host
+deep into a long match never answers with credentials that have already
+lapsed. A renewal also reaches every connection already up, ready for its next
+change of route. Renewals are paced at one per event, never one per candidate.
+
 **Which cluster to lease from is normally nobody's decision to make here.** The
 parent measures the regions and hands the close ones across the bridge, and each
 peer leases from its own best one — a relay near that peer, whichever cluster
@@ -343,6 +351,23 @@ alike — which is a decision to move the room. When nothing resolves one the
 connection proceeds without a relay and says so loudly, because the failure it
 causes is the one that looks like success.
 
+**A lease refused for its cluster moves to the next one the page sent.** The page
+sends up to three clusters, best first. When the platform refuses a lease because
+of the cluster it named — `cluster_hidden`, an operator took it out of service and
+no other cluster in its region can relay for it, or `invalid_cluster_target`, it
+is not one the platform runs — the SDK leases from the next, before any connection
+is built. Only when every one is refused does the connection proceed without a
+relay, with the same warning. Any other refusal is not walked, because another
+cluster would answer it the same. A cluster you named yourself is the only one
+tried. A renewal walks the same way, starting from the cluster that granted the
+lease it replaces, and a re-dial after a dropped connection leases afresh over the
+whole list, so a cluster hidden mid-match is passed over either way.
+
+An earlier SDK version asks only the best cluster. Where the platform can answer
+from another cluster in the same region it does, and that SDK gets its relay
+anyway; where it cannot, that SDK connects without one. `dedicated-server-flow.md`
+§5 says what hiding a cluster does to rooms and matches.
+
 **`null` names no cluster, exactly as omitting the option does.** A game picking
 its target out of a list writes `targets[0]?.id ?? null`, so that is the spelling
 ordinary code arrives with — and it defers to the parent's answer the same way an
@@ -351,6 +376,41 @@ request for a cluster with no id: that costs the caller the no-relay warning and
 reports "the relay was refused" for a player whose actual problem is that nobody
 ever resolved a region for them.
 
+### 4.1 A relay going away does not end the match
+
+Relays are taken out of service for deploys, credential rotation and scaling.
+The platform does it in three ordered steps:
+
+1. **Delist.** No new lease names the relay, so no new connection is built on it.
+2. **Move.** Every player in a match that may be using it is told, and the
+   connections on it move elsewhere while it still forwards traffic.
+3. **Stop.** The relay stops once nobody is on it, or when the platform's
+   deadline for the move passes.
+
+**Your game sees none of it.** On the notice every player renews its lease and
+drops the draining relay from the list it holds. A player whose connection to
+the host runs through that relay moves with an **ICE restart on the connection
+it already has**: new candidates on the remaining relays, the same DTLS
+session, the same three data channels. The host answers on its existing
+connection. Nothing closes, `gem.match` raises no `matchSuspended`, and nobody
+reports the host unreachable. A player whose route does not touch the draining
+relay renews and does nothing else, and the host renews and answers but never
+offers a restart of its own.
+
+**If the move has not completed by the platform's deadline**, the player drops
+that connection and the ordinary reconnect takes over (§5.1, and §4 of
+[match-session.md](match-session.md)): a fresh session at the same host, over
+the renewed lease, reported as this player's own link closing — `link_closed` —
+because the host is fine. The same happens at once if the host has already let
+go of that player's connection when the restart reaches it: the host can only
+answer from a new connection, which the player's existing one cannot use.
+
+**The announced move needs the Arcade page to pass the notice on.** The page is
+what relays it into the game frame, and a page whose side of the bridge
+predates the SDK release that brought this drops it. Until the page is at that
+release or later, a relay stopping under a match is recovered the way an
+unannounced loss is (§5): a few seconds of quiet, then the same restart.
+
 ---
 
 ## 5. Host migration is where a split match can happen
@@ -388,18 +448,31 @@ trying to fix, and the old host is already gone. A host that settled on its own
 send could not tell that apart from a healthy match. The active phase is bounded
 at 30 seconds and a stall is reported as `migration_failed`.
 
-A non-host that sees ICE fail reports the host unreachable **once per epoch**.
-That is a vote, not a verdict: gem-api migrates on a quorum of independent
-reporters and never on one, so it cannot unseat a host who is fine for everyone
-else.
+A non-host whose connection to the host goes quiet **tries to bring it back
+before it reports anything**. ICE `disconnected` is what a lost relay looks like
+as much as a lost host, so the player first renews its lease and restarts ICE on
+the existing connection — the move §4.1 describes, without the notice — and
+gives it about eight seconds to come back. Only if it does not, or the
+connection fails or closes outright meanwhile, does the player report the host
+unreachable, **once per epoch**. A relay that dies without warning therefore no
+longer ends a two-player match or migrates a larger one away from a healthy
+host; the cost is that a host who really has gone is reported a few seconds
+later.
+
+The report is a vote, not a verdict. In a match of three or more, gem-api
+migrates on a quorum of at least two independent reporters, so one player
+cannot unseat a host who is fine for everyone else. In a two-player match there
+is nobody to elect, and the lone peer's report ends the match with `host_left`
+— which is why the report waits for the restart to fail.
 
 ### 5.1 What `gem.match` does with a migration
 
 A `MatchConnection` to a hosting peer survives a migration as a **pause**: its
 channels re-resolve on `hostChanged`, so the game sees a gap rather than a new
 connection to build. What the room reports meanwhile is the ordinary session
-vocabulary — `matchSuspended` with cause `host_unreachable` when the host's
-link fails, `matchReconnected` with `attempt: 0` when the migration seated a
+vocabulary — `matchSuspended` with cause `link_closed` when this side sees the
+host's link fail or `host_unreachable` when the platform reports the host gone,
+`matchReconnected` with `attempt: 0` when the migration seated a
 new host and the link came back without a re-dial, and `matchEnded` with
 `host_left` or `migration_failed` when it did not. The screens for each are
 [match-session.md](match-session.md) §3 and §4; the listen host's own

package/docs/server-bundles.md

@@ -80,8 +80,8 @@ To check the download yourself: the package npm serves is, byte for byte, the fi
 also publishes on its download host, with the hash beside it:
 
 ```bash
-curl -fsSL -O https://downloads.gemarcade.com/sdk/v20.0.0/gem-web-sdk.tgz
-curl -fsSL https://downloads.gemarcade.com/sdk/v20.0.0/gem-web-sdk.tgz.sri
+curl -fsSL -O https://downloads.gemarcade.com/sdk/v20.1.0/gem-web-sdk.tgz
+curl -fsSL https://downloads.gemarcade.com/sdk/v20.1.0/gem-web-sdk.tgz.sri
 openssl dgst -sha384 -binary gem-web-sdk.tgz | openssl base64 -A
 ```
 

package/docs/what-a-game-must-do.md

@@ -53,10 +53,10 @@ No `baseUrl`. The Arcade names the backend on every token and the SDK routes the
 tokens only if its origin is allowed, and the pages that matter are always allowed without a word
 from you:
 
-- **the Gem Arcade website, developer site and app** — the SDK carries their origins as
-  `ARCADE_EMBEDDERS`, on every platform the app runs on. The developer site,
-  `https://developer.gemarcade.com`, is where you play your own dev and test builds; a build accepts
-  it once it is built with an SDK that lists it;
+- **the Gem Arcade website and app** — the SDK carries their origins as `ARCADE_EMBEDDERS`, on every
+  platform the app runs on. The list also holds `https://developer.gemarcade.com`, which is
+  reserved and not live: no page is served there. You play your own dev and test builds with
+  `gemctl serve` or the Gem Editor, or on your game's dev or test channel in the Arcade;
 - **a dev host on your own machine** — `gemctl serve` and the Gem Editor frame a locally-served game
   from a loopback origin whose port changes every run, and the SDK admits that shape by rule, only
   while your game itself is served from loopback. Once published, nothing about the rule applies.
@@ -1710,7 +1710,10 @@ stops your media elements, and restarts neither. The snippet above has stopped l
 the SDK does this part for you. After the page was hidden, or a context left `running` without your
 asking, it listens again for the player's next lift in your frame, resumes the contexts that were
 running and replays the elements that were playing when the sound was cut off, then stops
-listening. You write nothing for it. It stays out of your way:
+listening. A context that reads `running` after the page comes back can still be silent, as when
+your own `resume()` ran outside a tap, so on that first lift the SDK also suspends and resumes each
+context that had run, once per return: your clock pauses for a moment, and the sound comes back.
+You write nothing for it. It stays out of your way:
 
 - **A context you `suspend()` yourself is left alone** until you call `resume()`. If you pause your
   audio when the page is hidden and resume it when it comes back, keep doing that: the SDK steps in

package/package.json

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