@indiegems/gem-web-sdk 15.0.0 → 15.1.1

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

@@ -1,6 +1,6 @@
 # The browser surface — API reference
 
-Generated from `@indiegems/gem-web-sdk/sdk` v15.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` v15.1.1, 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.
 
@@ -3553,6 +3553,72 @@ them, whatever you set here.
 | --- | --- |
 | `props` | `Readonly<Record<string, AnalyticsValue>>` |
 
+<a id="analyticsapi-experiment"></a>
+
+## AnalyticsApi.experiment
+
+```ts
+experiment(key: string, count: number): Promise<number>
+```
+
+Which arm of one of your experiments this player gets — the same answer on
+every call, every refresh and every device. Use it wherever you would have
+picked an arm with `Math.random()`, which deals a player a new arm on each
+visit and makes the test unreadable.
+
+Pass a COUNT and get an index, `0` to `count - 1`; pass a LIST of strings
+and get one of them. A string listed twice is twice as likely.
+
+```js
+const tutorial = await gem.analytics.experiment('tutorial_length', ['short', 'long']);
+const layout = await gem.analytics.experiment('shop_layout', 3); // 0, 1 or 2
+```
+
+The selection is a hash of the key and the signed-in player's id — FNV-1a
+32-bit over `"<key>:<playerId>"`, then MurmurHash3's 32-bit finalizer, mod
+the arm count; see
+[experimentSelection](#experimentselection), which computes the same answer for an id you
+hold. Hashing the key in is what keeps your experiments independent: the
+players in one experiment's first arm are not the same players in every
+other experiment's first arm.
+
+⚠️ **Keep the key and the arms fixed for the life of the experiment.** A new
+count or list re-deals every player. To start over on purpose, use a new
+key.
+
+⚠️ **NOTHING IS RECORDED FOR YOU.** The selection is not sent anywhere, and
+the SDK does not add it to your events. To analyse an experiment, declare a
+dimension for it on the events you want to break down, with the arms as its
+values, named after the experiment, and pass the selection there yourself:
+`gem.analytics.track('tutorial_finished', { tutorial_length: tutorial })`.
+Never the platform's `variant` field, which belongs to store-page
+experiments.
+
+WAITS FOR THE PLAYER. The id arrives with the first play token, so a call
+during boot waits for it, and rejects as [Gem.awaitIdentity](#gem-awaitidentity) does
+when none arrives — outside the Arcade, the Gem Editor or the dev host.
+There is no random fallback: catch the rejection and play your control arm.
+A guest is selected by their guest id, which is stable for as long as their
+guest account lasts; once they sign in to an account they are that
+account's player, and its selection applies.
+
+In a serverless function it selects for the player who invoked it, with
+no wait, and rejects when a game server invoked it.
+
+Works with analytics turned off: it reads no setting and sends nothing.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `key` | `string` | Names the experiment — any non-empty string. |
+| `count` | `number` | How many arms, an integer from 1 to 2048 — or, in the list
+  form, `options`: the arms themselves, 1 to 2048 strings. |
+
+**Returns.** The arm's index, or the chosen string.
+
+**Throws.** TypeError for an empty key or a list holding something other than
+  strings; RangeError for a count or list size outside 1 to 2048. Both
+  reject before waiting for the player.
+
 <a id="analyticsapi-environment"></a>
 
 ## AnalyticsApi.environment
@@ -3680,6 +3746,47 @@ The runtime companion to [PlatformEventName](#platformeventname), for a game tha
 show what it gets for free, or to check a funnel step it authored against
 what the platform actually emits.
 
+<a id="experimentselection"></a>
+
+## experimentSelection
+
+```ts
+function experimentSelection(key: string, playerId: string, count: number): number
+```
+
+Which arm of an experiment a player gets — the same answer for the same key
+and player, every time, anywhere.
+
+In a game, call [AnalyticsApi.experiment](#analyticsapi-experiment) instead: it is this, with
+the signed-in player's id filled in. This form takes the id, for code that
+has one in hand — a dedicated server reproducing what a member's client
+picked, or a test.
+
+Pass a COUNT and get an index, `0` to `count - 1`; pass a LIST of strings
+and get one of them. A string listed twice is twice as likely, which is how
+to weight an arm.
+
+The answer is `fmix32(fnv1a32("<key>:<playerId>")) % count`: FNV-1a 32-bit
+over the UTF-8 bytes of the key, a colon and the player id, then
+MurmurHash3's 32-bit finalizer, as an unsigned integer — with a list, the
+index into it. The hash is fixed, so any other language can reproduce a
+selection; docs/analytics.md has it written out.
+
+⚠️ **Keep the key and the arms fixed for the life of the experiment.** A new
+count or list re-deals every player. To start over on purpose, use a new
+key.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `key` | `string` | Names the experiment — any non-empty string, and the only thing
+  that makes one experiment's split independent of another's. |
+| `playerId` | `string` | The player to select for — [GemIdentity.playerId](#gemidentity-playerid). |
+| `count` | `number` | How many arms, an integer from 1 to 2048 — or, in the list
+  form, `options`: the arms themselves, 1 to 2048 strings. |
+
+**Throws.** TypeError for an empty key or player id, or a list holding something
+  other than strings; RangeError for a count or list size outside 1 to 2048.
+
 <a id="avatar3dprice"></a>
 
 ## Avatar3dPrice

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

@@ -1,6 +1,6 @@
 # The server surface — API reference
 
-Generated from `@indiegems/gem-web-sdk/sdk` v15.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` v15.1.1, 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": "15.0.0"
+    "version": "15.1.1"
   },
   "entries": [
     {
@@ -4393,6 +4393,35 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "AnalyticsApi.experiment",
+          "name": "experiment",
+          "anchor": "analyticsapi-experiment",
+          "group": "analytics",
+          "signature": "experiment(key: string, count: number): Promise<number>",
+          "documented": true,
+          "summary": "Which arm of one of your experiments this player gets — the same answer on\nevery call, every refresh and every device. Use it wherever you would have\npicked an arm with `Math.random()`, which deals a player a new arm on each\nvisit and makes the test unreadable.\n\nPass a COUNT and get an index, `0` to `count - 1`; pass a LIST of strings\nand get one of them. A string listed twice is twice as likely.\n\n```js\nconst tutorial = await gem.analytics.experiment('tutorial_length', ['short', 'long']);\nconst layout = await gem.analytics.experiment('shop_layout', 3); // 0, 1 or 2\n```\n\nThe selection is a hash of the key and the signed-in player's id — FNV-1a\n32-bit over `\"<key>:<playerId>\"`, then MurmurHash3's 32-bit finalizer, mod\nthe arm count; see\n[experimentSelection](api-reference-game.md#experimentselection), which computes the same answer for an id you\nhold. Hashing the key in is what keeps your experiments independent: the\nplayers in one experiment's first arm are not the same players in every\nother experiment's first arm.\n\n⚠️ **Keep the key and the arms fixed for the life of the experiment.** A new\ncount or list re-deals every player. To start over on purpose, use a new\nkey.\n\n⚠️ **NOTHING IS RECORDED FOR YOU.** The selection is not sent anywhere, and\nthe SDK does not add it to your events. To analyse an experiment, declare a\ndimension for it on the events you want to break down, with the arms as its\nvalues, named after the experiment, and pass the selection there yourself:\n`gem.analytics.track('tutorial_finished', { tutorial_length: tutorial })`.\nNever the platform's `variant` field, which belongs to store-page\nexperiments.\n\nWAITS FOR THE PLAYER. The id arrives with the first play token, so a call\nduring boot waits for it, and rejects as [Gem.awaitIdentity](api-reference-game.md#gem-awaitidentity) does\nwhen none arrives — outside the Arcade, the Gem Editor or the dev host.\nThere is no random fallback: catch the rejection and play your control arm.\nA guest is selected by their guest id, which is stable for as long as their\nguest account lasts; once they sign in to an account they are that\naccount's player, and its selection applies.\n\nIn a serverless function it selects for the player who invoked it, with\nno wait, and rejects when a game server invoked it.\n\nWorks with analytics turned off: it reads no setting and sends nothing.",
+          "deprecated": null,
+          "params": [
+            {
+              "name": "key",
+              "type": "string",
+              "optional": false,
+              "summary": "Names the experiment — any non-empty string."
+            },
+            {
+              "name": "count",
+              "type": "number",
+              "optional": false,
+              "summary": "How many arms, an integer from 1 to 2048 — or, in the list\n  form, `options`: the arms themselves, 1 to 2048 strings."
+            }
+          ],
+          "returns": "The arm's index, or the chosen string.",
+          "throws": "TypeError for an empty key or a list holding something other than\n  strings; RangeError for a count or list size outside 1 to 2048. Both\n  reject before waiting for the player.",
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "AnalyticsApi.environment",
           "name": "environment",
@@ -4496,6 +4525,41 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "experimentSelection",
+          "name": "experimentSelection",
+          "anchor": "experimentselection",
+          "group": "analytics",
+          "signature": "function experimentSelection(key: string, playerId: string, count: number): number",
+          "documented": true,
+          "summary": "Which arm of an experiment a player gets — the same answer for the same key\nand player, every time, anywhere.\n\nIn a game, call [AnalyticsApi.experiment](api-reference-game.md#analyticsapi-experiment) instead: it is this, with\nthe signed-in player's id filled in. This form takes the id, for code that\nhas one in hand — a dedicated server reproducing what a member's client\npicked, or a test.\n\nPass a COUNT and get an index, `0` to `count - 1`; pass a LIST of strings\nand get one of them. A string listed twice is twice as likely, which is how\nto weight an arm.\n\nThe answer is `fmix32(fnv1a32(\"<key>:<playerId>\")) % count`: FNV-1a 32-bit\nover the UTF-8 bytes of the key, a colon and the player id, then\nMurmurHash3's 32-bit finalizer, as an unsigned integer — with a list, the\nindex into it. The hash is fixed, so any other language can reproduce a\nselection; docs/analytics.md has it written out.\n\n⚠️ **Keep the key and the arms fixed for the life of the experiment.** A new\ncount or list re-deals every player. To start over on purpose, use a new\nkey.",
+          "deprecated": null,
+          "params": [
+            {
+              "name": "key",
+              "type": "string",
+              "optional": false,
+              "summary": "Names the experiment — any non-empty string, and the only thing\n  that makes one experiment's split independent of another's."
+            },
+            {
+              "name": "playerId",
+              "type": "string",
+              "optional": false,
+              "summary": "The player to select for — [GemIdentity.playerId](api-reference-game.md#gemidentity-playerid)."
+            },
+            {
+              "name": "count",
+              "type": "number",
+              "optional": false,
+              "summary": "How many arms, an integer from 1 to 2048 — or, in the list\n  form, `options`: the arms themselves, 1 to 2048 strings."
+            }
+          ],
+          "returns": null,
+          "throws": "TypeError for an empty key or player id, or a list holding something\n  other than strings; RangeError for a count or list size outside 1 to 2048.",
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "Avatar3dPrice",
           "name": "Avatar3dPrice",
@@ -28032,6 +28096,35 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "AnalyticsApi.experiment",
+          "name": "experiment",
+          "anchor": "analyticsapi-experiment",
+          "group": "analytics",
+          "signature": "experiment(key: string, count: number): Promise<number>",
+          "documented": true,
+          "summary": "Which arm of one of your experiments this player gets — the same answer on\nevery call, every refresh and every device. Use it wherever you would have\npicked an arm with `Math.random()`, which deals a player a new arm on each\nvisit and makes the test unreadable.\n\nPass a COUNT and get an index, `0` to `count - 1`; pass a LIST of strings\nand get one of them. A string listed twice is twice as likely.\n\n```js\nconst tutorial = await gem.analytics.experiment('tutorial_length', ['short', 'long']);\nconst layout = await gem.analytics.experiment('shop_layout', 3); // 0, 1 or 2\n```\n\nThe selection is a hash of the key and the signed-in player's id — FNV-1a\n32-bit over `\"<key>:<playerId>\"`, then MurmurHash3's 32-bit finalizer, mod\nthe arm count; see\n`experimentSelection`, which computes the same answer for an id you\nhold. Hashing the key in is what keeps your experiments independent: the\nplayers in one experiment's first arm are not the same players in every\nother experiment's first arm.\n\n⚠️ **Keep the key and the arms fixed for the life of the experiment.** A new\ncount or list re-deals every player. To start over on purpose, use a new\nkey.\n\n⚠️ **NOTHING IS RECORDED FOR YOU.** The selection is not sent anywhere, and\nthe SDK does not add it to your events. To analyse an experiment, declare a\ndimension for it on the events you want to break down, with the arms as its\nvalues, named after the experiment, and pass the selection there yourself:\n`gem.analytics.track('tutorial_finished', { tutorial_length: tutorial })`.\nNever the platform's `variant` field, which belongs to store-page\nexperiments.\n\nWAITS FOR THE PLAYER. The id arrives with the first play token, so a call\nduring boot waits for it, and rejects as `Gem.awaitIdentity` does\nwhen none arrives — outside the Arcade, the Gem Editor or the dev host.\nThere is no random fallback: catch the rejection and play your control arm.\nA guest is selected by their guest id, which is stable for as long as their\nguest account lasts; once they sign in to an account they are that\naccount's player, and its selection applies.\n\nIn a serverless function it selects for the player who invoked it, with\nno wait, and rejects when a game server invoked it.\n\nWorks with analytics turned off: it reads no setting and sends nothing.",
+          "deprecated": null,
+          "params": [
+            {
+              "name": "key",
+              "type": "string",
+              "optional": false,
+              "summary": "Names the experiment — any non-empty string."
+            },
+            {
+              "name": "count",
+              "type": "number",
+              "optional": false,
+              "summary": "How many arms, an integer from 1 to 2048 — or, in the list\n  form, `options`: the arms themselves, 1 to 2048 strings."
+            }
+          ],
+          "returns": "The arm's index, or the chosen string.",
+          "throws": "TypeError for an empty key or a list holding something other than\n  strings; RangeError for a count or list size outside 1 to 2048. Both\n  reject before waiting for the player.",
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "AnalyticsApi.environment",
           "name": "environment",

package/docs/changelog.md

@@ -16,6 +16,21 @@ 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.
 
+## 15.1.1
+
+Upgrading from 15.1.0. Impact: none.
+
+Nothing in this release asks anything of a game.
+
+## 15.1.0
+
+Upgrading from 15.0.0. Impact: none.
+
+### New capability
+
+- AnalyticsApi.experiment gives a player a stable experiment arm. Pass an experiment key and either an arm count or a list of options. It returns the same arm for that player on every call, refresh and device: an index from zero up to one less than the count, or one of the strings in the list. Games that picked an arm with a random number landed a player in a different arm on every refresh, so no test could be read. Switching to this call fixes that. Different experiment keys are independent of each other. Nothing is recorded for you. To analyse an experiment, declare a dimension on the events you choose and pass the selection yourself. The call rejects when there is no player.
+- experimentSelection computes the same arm as AnalyticsApi.experiment from an experiment key, a player id you hold, and an arm count or list of options. Use it where the SDK is not running, such as a dedicated game server or an analytics query, to reproduce which arm a player was given.
+
 ## 15.0.0
 
 *Written from the API facts alone; no summary was generated for this release.*

package/docs/getting-started.md

@@ -50,7 +50,7 @@ either way.
 ```jsonc
 // package.json
 "dependencies": {
-  "@indiegems/gem-web-sdk": "15.0.0"
+  "@indiegems/gem-web-sdk": "15.1.1"
 }
 ```
 

package/docs/manifest.json

@@ -13,8 +13,8 @@
     },
     {
       "file": "analytics.md",
-      "sha256": "94baa26268843ba926462633ddec8aaca56aabf79ee6639aaf77df68474debc7",
-      "updated": "2026-10-17T00:33:31Z"
+      "sha256": "afced8f94514818eca6de3e72bdd988b2cee10925086c3bfa47c0a8ec8967454",
+      "updated": "2026-10-23T00:13:14Z"
     },
     {
       "file": "arcade-avatars.md",
@@ -38,8 +38,8 @@
     },
     {
       "file": "changelog.md",
-      "sha256": "2405f222d6ba0120f9f58dd645a0b8e1659a55faac605935a38d00d50d529e97",
-      "updated": "2026-10-22T16:01:54Z"
+      "sha256": "0132ed26864b9c47309c3ab4df30329c5514eaa4dadabde25f2417f6a71a9a2c",
+      "updated": "2026-10-23T02:41:11Z"
     },
     {
       "file": "daily-challenges.md",
@@ -68,8 +68,8 @@
     },
     {
       "file": "getting-started.md",
-      "sha256": "3a6e8a015c5ae067364effd2c0c5432239096d0dc0b5d75ab369194d4f7c8346",
-      "updated": "2026-10-22T16:01:54Z"
+      "sha256": "f741da3ef391fd4641cd6a3c6ad99dc995f3a2895409965f6c01bc7d045db9e7",
+      "updated": "2026-10-23T02:41:11Z"
     },
     {
       "file": "inventory-and-catalogs.md",
@@ -83,8 +83,8 @@
     },
     {
       "file": "match-session.md",
-      "sha256": "33fdef4edc170cadd2284ff399fcf16455b7691d9aeac52bd09bade24b8b051a",
-      "updated": "2026-10-07T19:27:16Z"
+      "sha256": "cfc2f76e310f4a851ac0b9185687d284cced6533fe12fb359ce0cb2845c5e5ef",
+      "updated": "2026-10-23T01:58:45Z"
     },
     {
       "file": "p2p-and-parties.md",
@@ -128,8 +128,8 @@
     },
     {
       "file": "server-bundles.md",
-      "sha256": "5e07246cbfdb39d211fcee4f4610b9e6ca8ac8439c1a26751cf80ff68f383459",
-      "updated": "2026-10-22T16:01:54Z"
+      "sha256": "1ca3430270d7c180304bcb297484bf4c8a22689b7728fce753d9a2bf6b6248ad",
+      "updated": "2026-10-23T02:41:11Z"
     },
     {
       "file": "serverless-functions-js.md",
@@ -153,8 +153,8 @@
     },
     {
       "file": "what-a-game-must-do.md",
-      "sha256": "1dae31932542cf7d49e8b1c1bc456e62cfb72204e88ea776919cca12c690c859",
-      "updated": "2026-10-22T15:46:02Z"
+      "sha256": "645ed81d6d89996759880f9faf5a7ecb587953b9205bad2d32a30001d3238552",
+      "updated": "2026-10-23T01:58:45Z"
     }
   ]
 }

package/docs/match-session.md

@@ -272,7 +272,22 @@ wiki keeps a live match live. Only the transport says a link dropped.
 The two messages the arcade pushes about the page — `onPause` on both edges, and `onWillTerminate`
 with its grace budget — are the game's to honour and are on
 [what-a-game-must-do.md](what-a-game-must-do.md#what-the-parent-says-about-the-session-prefs-pause-and-terminate).
-Neither ends a match.
+Neither ends a match, and a game must not leave its room on `onPause`: the same pause fires when
+the phone locks.
+
+**Leave game is the exception, and the platform handles it.** A player who chooses Leave game in
+the Arcade's menu is taken out of every room of the game, on every device, by the platform when
+they choose it — not by a request from the game's page as it unloads, so a game needs no
+`pagehide` leave for this. Each room is left the way `gem.rooms.leave()` leaves it, so a server
+holding the seat for a reconnect hears the player left and frees it. On a phone the game is still
+parked; a player who comes back and presses Continue resumes without a seat, and the room's next
+read says so — `kicked` while the room plays on without them, `matchEnded` and then `closed` when
+they were the last one in it. Go back to your menu on either.
+
+A room the player's party leader seated them in stays: only the leader can take the party out,
+Leave game keeps that room without an error, and reopening the game puts the player back in their
+party's match. [what-a-game-must-do.md](what-a-game-must-do.md#the-arcades-menu) has the whole
+rule.
 
 ## 8. When it goes wrong
 

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/v15.0.0/gem-web-sdk.tgz
-curl -fsSL https://downloads.gemarcade.com/sdk/v15.0.0/gem-web-sdk.tgz.sri
+curl -fsSL -O https://downloads.gemarcade.com/sdk/v15.1.1/gem-web-sdk.tgz
+curl -fsSL https://downloads.gemarcade.com/sdk/v15.1.1/gem-web-sdk.tgz.sri
 openssl dgst -sha384 -binary gem-web-sdk.tgz | openssl base64 -A
 ```
 

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

@@ -610,7 +610,7 @@ there is no route by which the frame could request one. `createGem` forwards all
   arcade cannot release yours from outside the frame. Keep it captured and the player cannot click
   the dialog sitting on top of your game.
 
-  **Save on pause.** When a player on a phone chooses Return to the Arcade in
+  **Save on pause.** When a player on a phone chooses Leave game in
   [the Arcade's menu](#the-arcades-menu), or presses the device's Back, your
   game is **parked**, not closed:
   it receives `onPause(true)` and stays loaded while the player browses. They may come back and
@@ -620,6 +620,14 @@ there is no route by which the frame could request one. `createGem` forwards all
   nothing after the pause. So the pause edge is your last guaranteed moment. Write anything the
   player would mind losing there, and never hold it back for a terminate warning that may not come.
 
+  **Leave game has already left the rooms.** A parked game is still loaded, but a player who chose
+  Leave game is no longer in its rooms: the platform took them out when they chose it
+  ([the Arcade's menu](#the-arcades-menu) says which rooms). If they come back and press Continue,
+  your game resumes without a seat, and the room's next read says so: `kicked` while the room plays
+  on without them, `matchEnded` and then `closed` when they were the last one in it. Go back to your
+  own menu on either, as you already do for a match that ended while your game was away. The
+  device's Back parks the game without leaving anything.
+
   **Re-read on resume.** Your game is told that it was paused and resumed, never why, and never
   what the player did in the meantime. Their Gems and Coins can change while you are paused, so
   if your game keeps anything worked out from a balance, such as a Buy button it greyed out or a
@@ -642,7 +650,10 @@ there is no route by which the frame could request one. `createGem` forwards all
 Neither `onPause` nor `onWillTerminate` touches a match. A match whose link dropped while the phone was locked
 comes back through the SDK's own reconnect on the next visible edge, and one that ended meanwhile
 raises `matchEnded` on the same edge — [match-session.md](match-session.md) §7. Pause the loop
-on `onPause`; do not leave the room.
+on `onPause`; do not leave the room. The same pause fires when the phone locks, and a player who
+locked their phone mid-match expects to be in it when they unlock. The one pause that does take the
+player out of their rooms is Leave game, and the platform does that itself
+([the Arcade's menu](#the-arcades-menu)), not your game.
 
 🔴 **The assembly used to drop all three.** `GemFrame` parsed them and `createGem` wired none, so a
 game built the one-call way could not hear them — and could not add a handler afterwards either,
@@ -734,7 +745,7 @@ game, a framed or full-window game on a desktop, a tablet or a TV in native full
 
 - **The Gem button**, the Gem Arcade's gem, always there (a 44px square touch target), in
   the **top-left corner** unless your game [asks for another](#moving-the-gem-gemsetgemcorner). It
-  opens [the Arcade's menu](#the-arcades-menu): Return to the Arcade, the player's Gems, Coins and
+  opens [the Arcade's menu](#the-arcades-menu): Leave game, the player's Gems, Coins and
   achievement score, mute, the player's Arcade-wide settings and the rest. Not your settings: those
   are [your own button](#game-settings).
 - **Nothing else.** The player's wallets (Gems, Coins, their achievement score) are **not** drawn
@@ -1397,7 +1408,7 @@ What it does, so you know what to expect:
 
 The Arcade keeps one button over every game, on every device: the Gem, top-left unless your game
 [asks for another corner](#moving-the-gem-gemsetgemcorner). Its menu is
-how a player leaves (**Return to the Arcade**), sees their Gems, Coins and achievement score, mutes,
+how a player leaves (**Leave game**), sees their Gems, Coins and achievement score, mutes,
 goes fullscreen, reports a problem and changes their Arcade-wide settings — the ones that reach you as [`gem.prefs.recommended`](#game-settings). You can add up to
 four entries of your own:
 
@@ -1421,10 +1432,25 @@ gem.setMenu({
   and sent when it does, and again after any reconnect.
 - **The Arcade pauses your game while its menu is open** — `onPause(true)`, then `onPause(false)`
   before a handler of yours runs. Nothing else is needed from you.
-- **You cannot remove or reorder the Arcade's entries**, and Return to the Arcade is always there.
+- **You cannot remove or reorder the Arcade's entries**, and Leave game is always there.
   On a phone it **parks** your game, as above; on a desktop, a tablet and a television it ends the
   session, with `onWillTerminate` first. Either way your game heard `onPause(true)` when the menu
   opened: save there — it is the edge you are sure to get.
+- **Leave game takes the player out of every room of your game**, on every device, and the
+  platform does it, not your page. It leaves each room the way `gem.rooms.leave()` does, so a
+  match server holding the seat hears the player left and frees it rather than waiting out its
+  reconnect budget. It leaves open rooms, matches in progress and custom lobbies alike; rooms of
+  other games, and the player's Arcade party, are untouched. So your game needs no leave of its own
+  for Leave game: not on `onPause`, not on `onWillTerminate` and not from a `pagehide` handler,
+  which a parked game never gets. The SDK's own `pagehide` leave stays, for the tab closed or
+  reloaded out from under you
+  ([rooms-and-matches.md](rooms-and-matches.md) §4.3a).
+- **A room the player's party leader seated them in stays.** A party member cannot leave the
+  room their leader took the party into; only the leader can take the party out. Leave game leaves
+  every other room and keeps that one, and that is not an error. When the player opens your game
+  again, they are back in their party's match — by design: they left the game, not their friends.
+  A game that follows its party into the leader's match
+  ([p2p-and-parties.md](p2p-and-parties.md) §7.4) needs nothing more for this.
 
 `gem.setMenu` returns `false` under an embedder with no menu, and outside any embedder. Your
 settings button is there either way; what such a game also needs is a way out of its own, a control

package/package.json

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