@indiegems/gem-web-sdk 19.0.2 → 20.1.0

package/docs/inventory-and-catalogs.md

@@ -591,7 +591,6 @@ everything under `platform_prices` may carry a price, and a currency under neith
 all. The grant rows also carry the platform's ceilings, and a game does not declare its own; a
 `max_per_window` on a mapping is ignored, with a warning.
 
-
 A browser-only game cannot award a platform currency without a server **or a serverless function**.
 That is the price of the platform never trusting a client. A game with no dedicated server writes
 the source progression from a function the player calls, on a progression that opts in with
@@ -657,10 +656,10 @@ subject. [brand-art.md](brand-art.md) has both, how to draw them, and the rest o
 
 Every game can choose between two purchase owners for the same published platform price:
 
-| Call | Who owns confirmation | Transport | Result |
-| --- | --- | --- | --- |
-| `gem.purchases.request(...)` | the platform | postMessage bridge; platform sheet always opens | `ok`, `declined`, or `unavailable` |
-| `gem.me.mutations.purchase(...)` | your game | direct authenticated SDK request; no bridge or platform sheet | an order-style result or a `GemApiError` |
+| Call                             | Who owns confirmation | Transport                                                     | Result                                   |
+| -------------------------------- | --------------------- | ------------------------------------------------------------- | ---------------------------------------- |
+| `gem.purchases.request(...)`     | the platform          | postMessage bridge; platform sheet always opens               | `ok`, `declined`, or `unavailable`       |
+| `gem.me.mutations.purchase(...)` | your game             | direct authenticated SDK request; no bridge or platform sheet | an order-style result or a `GemApiError` |
 
 There is no approval step. Both paths are available to every game.
 
@@ -818,21 +817,21 @@ local lookup. The purchase catalog is keyed by ids. Recipes also require `catalo
 One vocabulary covers both paths: the sheet's `res.reason` and the direct path's `err.code` are
 the same strings.
 
-| Code                                                                                                                 | What happened                                                                                           | What to do                                                                         |
-| -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
-| `unknown_currency`                                                                                                   | the slug is not an active platform currency                           | write `ARCADE_TICKETS` or `GEMS`; the direct path's message lists what is active    |
-| `currency_not_in_game_payable`                                                                                               | the currency exists but cannot pay for game items                                                       | price in a currency `gemctl platform config` lists under `platform_prices`          |
-| `not_purchasable`                                                                                                    | the target is not in the purchase catalog on this channel, or cannot be bought                          | send the id (not the slug); promote the config version that prices it              |
-| `no_price_in_currency`                                                                                               | the target has no price in that currency                                                                | ask in the currency it is priced in, or add the price                              |
-| `busy`                                                                                                               | a purchase is already in flight, a sheet is open, the arcade is backing off after a cancel, or no click | ask again only from a fresh player action                                          |
-| `cancelled`                                                                                                          | the player dismissed the sheet                                                                          | nothing — return to the shop                                                       |
-| `insufficient_funds`                                                                                                 | the player cannot afford it                                                                             | say so in your shop's words; never draw a top-up screen                            |
-| `price_mismatch`, `config_version_stale`                                                                             | the price or config changed since your catalog read; nothing was charged                                | re-read the catalog and re-render                                                  |
-| `platform_currency_unavailable`                                                                                      | the currency is not available to this purchase right now                                                | show the store as unavailable                                                      |
-| `not_available`                                                                                                      | the recipe is outside its availability window, or inactive; nothing was charged                         | hide or disable the row until its window opens                                     |
-| `recipe_locked`                                                                                                      | the recipe's prerequisites are not met; nothing was charged                                             | show the lock from `recipeAvailability().lockReasons`                              |
-| `recipe_on_cooldown`, `recipe_max_uses_exceeded`, `item_max_stack_exceeded`, `recipe_costs_unmet`, `quantity_invalid` | the recipe or item refused this purchase before any charge                                              | reflect it on the row; `recipeAvailability` has the detail                         |
-| `error`                                                                                                              | anything else, or no reliable answer                                                                    | one neutral "store unavailable"; after `unavailable`, re-read inventory            |
+| Code                                                                                                                  | What happened                                                                   | What to do                                                                       |
+| --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| `unknown_currency`                                                                                                    | the slug is not an active platform currency                                     | write `ARCADE_TICKETS` or `GEMS`; the direct path's message lists what is active |
+| `currency_not_in_game_payable`                                                                                        | the currency exists but cannot pay for game items                               | price in a currency `gemctl platform config` lists under `platform_prices`       |
+| `not_purchasable`                                                                                                     | the target is not in the purchase catalog on this channel, or cannot be bought  | send the id (not the slug); promote the config version that prices it            |
+| `no_price_in_currency`                                                                                                | the target has no price in that currency                                        | ask in the currency it is priced in, or add the price                            |
+| `busy`                                                                                                                | a purchase is already in flight, or a sheet is open                             | ask again only from a fresh player action                                        |
+| `cancelled`                                                                                                           | the player dismissed the sheet                                                  | nothing — return to the shop                                                     |
+| `insufficient_funds`                                                                                                  | the player cannot afford it                                                     | say so in your shop's words; never draw a top-up screen                          |
+| `price_mismatch`, `config_version_stale`                                                                              | the price or config changed since your catalog read; nothing was charged        | re-read the catalog and re-render                                                |
+| `platform_currency_unavailable`                                                                                       | the currency is not available to this purchase right now                        | show the store as unavailable                                                    |
+| `not_available`                                                                                                       | the recipe is outside its availability window, or inactive; nothing was charged | hide or disable the row until its window opens                                   |
+| `recipe_locked`                                                                                                       | the recipe's prerequisites are not met; nothing was charged                     | show the lock from `recipeAvailability().lockReasons`                            |
+| `recipe_on_cooldown`, `recipe_max_uses_exceeded`, `item_max_stack_exceeded`, `recipe_costs_unmet`, `quantity_invalid` | the recipe or item refused this purchase before any charge                      | reflect it on the row; `recipeAvailability` has the detail                       |
+| `error`                                                                                                               | anything else, or no reliable answer                                            | one neutral "store unavailable"; after `unavailable`, re-read inventory          |
 
 Reasons are for your shop's state and your logs. Branch money on `outcome` and on a re-read of
 inventory, never on a reason, and do not retry because of one.
@@ -964,7 +963,9 @@ const gems = allowances.find((a) => a.currencySlug === 'GEMS');
 // 0 or less once `resetsAt` has passed: the read is stale, so say nothing about when.
 const hours = gems?.resetsAt ? Math.ceil((gems.resetsAt - Date.now()) / 3_600_000) : 0;
 if (gems && gems.remaining > 0) {
-  hud.setText(`You can still earn ${gems.remaining} Gems` + (hours > 0 ? `, more in ${hours}h` : ''));
+  hud.setText(
+    `You can still earn ${gems.remaining} Gems` + (hours > 0 ? `, more in ${hours}h` : ''),
+  );
 } else if (gems?.resetsAt) {
   // Spent for now: say when more arrives, never "0 left".
   hud.setText(hours > 0 ? `More Gems in ${hours}h` : 'More Gems soon');
@@ -1001,7 +1002,7 @@ end of the reported period when both of the platform's ceilings are spent.
 
 **Display only. Never gate gameplay or a grant on it.**
 
-- ✅ `` hud.setText(`${gems.remaining} Gems left to earn today`) ``
+- ✅ ``hud.setText(`${gems.remaining} Gems left to earn today`)``
 - ❌ `if (gems.remaining > 0) awardDailyBonus()`
 
 Grant anyway: the platform trims every grant to what is left, and the receipt is the authority on

package/docs/manifest.json

@@ -18,8 +18,8 @@
     },
     {
       "file": "arcade-and-store.md",
-      "sha256": "aee6e00fa7e0f463cb09174a9afdffe10d66ed1036546e584b341e4c11bb1e27",
-      "updated": "2026-10-31T19:43:30Z"
+      "sha256": "79bd7829d5a6577d3619d7fd831b74065df883e11eadd1b8153754d97a88474a",
+      "updated": "2026-11-02T18:42:37Z"
     },
     {
       "file": "arcade-avatars.md",
@@ -48,8 +48,8 @@
     },
     {
       "file": "changelog.md",
-      "sha256": "f2139ca3d6d368b6ae42da9f8550f69036ba56dcb5e7076b16421728809ac111",
-      "updated": "2026-11-02T18:36:05Z"
+      "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,13 +78,13 @@
     },
     {
       "file": "getting-started.md",
-      "sha256": "6d1d9969076b1f44b900a9923d8e3a82ca0b93278c000a0dc3699d836f57a09c",
-      "updated": "2026-11-02T18:36:05Z"
+      "sha256": "0c4cee83ffc77711f43ccdaafb394283a5a412b78395db1434ebbc2ab6943667",
+      "updated": "2026-11-03T00:39:38Z"
     },
     {
       "file": "inventory-and-catalogs.md",
-      "sha256": "a4763fe2418c0e24639ca58c27f30ffc416f07528857402a6f9ab3fee147f4f6",
-      "updated": "2026-11-01T21:49:36Z"
+      "sha256": "dab6e42f4ad5cc2a63c2adb11e85053f963cd3166d1c447394cd6f532bb6c006",
+      "updated": "2026-11-02T18:42:37Z"
     },
     {
       "file": "leaderboards.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": "46bb5ff4bea22129482f314aad4ba6e89b81c853140fdb72dedb7a3bc7853a1b",
-      "updated": "2026-11-02T18:36:05Z"
+      "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/v19.0.2/gem-web-sdk.tgz
-curl -fsSL https://downloads.gemarcade.com/sdk/v19.0.2/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": "19.0.2",
+  "version": "20.1.0",
   "description": "postMessage bridge contract between gem-web and browser-playable games",
   "license": "UNLICENSED",
   "type": "module",