@indiegems/gem-web-sdk 20.0.0 → 21.0.0

package/docs/manifest.json

@@ -13,8 +13,8 @@
     },
     {
       "file": "analytics.md",
-      "sha256": "42f3d0d3360e1a6066c21015bd4925475b4336a53611bf04acb773a7c6084e62",
-      "updated": "2026-10-30T16:54:41Z"
+      "sha256": "0883e3c53f500f4d0554d7d62ef938bc53676800b11a285e0da508c6fcc4076d",
+      "updated": "2026-11-02T22:24:57Z"
     },
     {
       "file": "arcade-and-store.md",
@@ -38,8 +38,8 @@
     },
     {
       "file": "brand-art.md",
-      "sha256": "b7f8dda1afdb8d56cadee752e6b09fc62238372b68ebc8a746518e528f52e167",
-      "updated": "2026-10-29T21:40:17Z"
+      "sha256": "7d4d5c7226710742efdb958e10387d5e5a3de0622a686734c885720e16a5b128",
+      "updated": "2026-11-02T21:18:05Z"
     },
     {
       "file": "branding.md",
@@ -48,8 +48,8 @@
     },
     {
       "file": "changelog.md",
-      "sha256": "37f3bde69baa7c0280e7d8a58800c1509b3b61c76a684428832bf094f298478b",
-      "updated": "2026-11-02T19:11:02Z"
+      "sha256": "ed2476deed910a61badb23023267b5a8292467d3812c211adf3baf23c42ae914",
+      "updated": "2026-11-03T21:36:35Z"
     },
     {
       "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": "dd7328fd2462efd7373904f1c14085fd75b046d76670113cd0762825d0c0f107",
+      "updated": "2026-11-03T21:36:35Z"
     },
     {
       "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": "736e7b4ceb810944331274f940cb47e7d3d4a57f815340a9ade7ffc5f01cd0fa",
+      "updated": "2026-11-03T21:36:35Z"
     },
     {
       "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/v21.0.0/gem-web-sdk.tgz
+curl -fsSL https://downloads.gemarcade.com/sdk/v21.0.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": "21.0.0",
   "description": "postMessage bridge contract between gem-web and browser-playable games",
   "license": "UNLICENSED",
   "type": "module",

package/schema/bridge.v1.json

@@ -1790,8 +1790,11 @@
         "deliberately: a frame that took its JWKS endpoint from a relayed message",
         "would let the parent choose the keys it verifies peers against.",
         "",
-        "The nine events are the whole vocabulary; an unrecognised p2p_* type is",
-        "a drop at the parent, not a passthrough.",
+        "The nine events are the whole vocabulary of this message; an",
+        "unrecognised p2p_* type is a drop at the parent, not a passthrough. The",
+        "relay drain notice is the one further push the parent relays, and it",
+        "crosses as its own type, gem.relayDraining: this enum is closed, so a",
+        "tenth value would be refused by every frame already shipped.",
         "",
         "PARENT TO FRAME ONLY. gem.signal is the other direction."
       ],
@@ -1824,6 +1827,68 @@
       "rateLimit": { "perMinute": 1800 }
     },
 
+    {
+      "type": "gem.relayDraining",
+      "direction": "parentToFrame",
+      "transport": "port",
+      "$comment": [
+        "A TURN relay this player's P2P match may be using is going away, relayed",
+        "from gem-api's `p2p_relay_draining`. Gated by the `p2pRelayDrain`",
+        "capability; the mapping lives in schema/capabilities.json and nowhere",
+        "else.",
+        "",
+        "A HINT, AND ONE THE FRAME COULD SURVIVE WITHOUT. It tells the frame to",
+        "re-lease and, where its selected candidate pair runs through one of",
+        "these relays, to restart ICE on the connection it already has, so the",
+        "match moves before the relay stops rather than after. The control is",
+        "the relay's own: a draining relay refuses new allocations whatever",
+        "this message says, and a connection on it fails over by the ordinary",
+        "path when it stops. A parent that rewrites this can cost a frame a",
+        "renegotiation; it cannot move a connection anywhere.",
+        "",
+        "ITS OWN TYPE, NOT A TENTH VALUE IN gem.signalEvent'S ENUM: the",
+        "generated validator rejects an unknown enum value, and every frame",
+        "already shipped would answer `invalid_message`. A parent sends this",
+        "only to a frame that advertised the capability and drops it otherwise.",
+        "",
+        "SCOPED BY MATCH, NOT BY GAME. gem-api stamps the push with no game id,",
+        "as it does `p2p_error`, so the parent relays it only for a match this",
+        "player's socket or this frame has already named.",
+        "",
+        "PARENT TO FRAME ONLY. A frame-authored drain notice would let a game",
+        "tell the parent a relay is going away."
+      ],
+      "fields": {
+        "matchId": {
+          "kind": "string",
+          "maxLength": 64,
+          "$comment": "The match whose relays are draining. The frame acts only for the live session on this match."
+        },
+        "clusterTargetId": {
+          "kind": "string",
+          "maxLength": 64,
+          "$comment": "The cluster the draining relays belong to. It decides nothing on the frame: the re-lease asks the cluster the session already leases from."
+        },
+        "relayIps": {
+          "kind": "array",
+          "maxItems": 16,
+          "items": { "kind": "string", "maxLength": 64 },
+          "$comment": "The draining relays' public addresses — the hosts in the lease's `turn:` URLs, and what a selected candidate pair names. A lease names at most three relays."
+        },
+        "drainingSince": {
+          "kind": "string",
+          "maxLength": 40,
+          "$comment": "RFC 3339. When the relays began draining."
+        },
+        "deadline": {
+          "kind": "string",
+          "maxLength": 40,
+          "$comment": "RFC 3339. When the relays stop relaying. A link still on one by then is dropped and re-dialled; one this side cannot parse is read as the drain ceiling, thirty minutes."
+        }
+      },
+      "rateLimit": { "perMinute": 60 }
+    },
+
     {
       "type": "gem.dedicatedEvent",
       "direction": "parentToFrame",

package/schema/capabilities.public.json

@@ -308,6 +308,12 @@
       "gates": [
         "gem.menuStyle"
       ]
+    },
+    "p2pRelayDrain": {
+      "implemented": true,
+      "gates": [
+        "gem.relayDraining"
+      ]
     }
   }
 }