@indiegems/gem-web-sdk 9.1.4 → 10.1.0

package/docs/daily-challenges.md

@@ -78,9 +78,118 @@ Changing only these two is not a change of schedule, so the upload does not refu
 `completion_threshold` is the target. `client_writable` decides who may report it, and
 [section 4](#4-who-may-report-it) is where that choice actually matters.
 
+`display_name` and `description` are what a player reads. To translate them, or to have the
+platform write the target into them, see
+[section 2a](#2a-translate-the-copy-and-write-the-target-into-it).
+
 **Upload the config the way you upload any other.** A challenge is not promoted differently and
 does not need a new build to reach players.
 
+## 2a. Translate the copy, and write the target into it
+
+Both of these are optional, and a config that uses neither keeps working as it is. A progression
+may carry your own translations of its name and description, and a displayed challenge may have the
+platform write its target into the text:
+
+```yaml
+progressions:
+  - id: 9b1d6e40-52c7-4f0a-8e3d-1a7c4b9f2d65
+    slug: clear-lines
+    display_name: 'Clear {target, plural, one {# line} other {# lines}}'
+    description: 'Clear lines in a single run.'
+    localized:
+      de:
+        display_name: 'Räume {target, plural, one {# Reihe} other {# Reihen}} ab'
+        description: 'Räume Reihen in einem Durchgang ab.'
+      pl:
+        description: 'Usuń linie w jednej rozgrywce.'
+    config:
+      completion_threshold: 150
+      reset_schedule: { type: daily }
+      platform_display: challenge
+```
+
+Quote the text. YAML reads an unquoted value that starts with `{` as a mapping, so
+`display_name: {target} points` is not a string.
+
+### Translations
+
+Any progression may carry `localized`, whether or not it is a displayed challenge.
+
+- **The keys are the eleven locales:** `de`, `es`, `fr`, `it`, `ja`, `ko`, `pl`, `pt-BR`, `ru`,
+  `tr`, `zh-Hans`. `en` is refused as a key, and so is any other key.
+- **Each entry has two optional fields**, `display_name` and `description`. You may translate one
+  and not the other.
+- **The `display_name` and `description` you write outside `localized` are the default text**, and
+  the platform treats them as English. A missing locale, or a missing field in a locale, falls back
+  to the default text, one field at a time. In the example, a Polish reader gets the default name
+  and the Polish description, and a French reader gets the default text for both.
+- **An empty translation is refused.** To show the default text, remove the key.
+- **Translations are optional**, and promoting a config does not depend on them.
+
+### Write the target with {target}
+
+On a displayed challenge (`platform_display: challenge`), `{target}` in `display_name` or
+`description` is replaced by the challenge's `completion_threshold`. It works in the default text
+and in every translation. Copy that already contains the literal text `{target}` is now shown with
+the number in its place.
+
+| You write                                              | Target | A player reads        |
+| ------------------------------------------------------ | ------ | --------------------- |
+| `Score {target} points`                                | 12000  | Score 12,000 points   |
+| `Erziele {target} Punkte`, under `de`                  | 12000  | Erziele 12.000 Punkte |
+| `Clear {target, plural, one {# line} other {# lines}}` | 1      | Clear 1 line          |
+| the same                                               | 150    | Clear 150 lines       |
+
+- **`target` is the only name.** Any other `{name}` is refused, and so is `{target}` on a
+  progression with no `completion_threshold`.
+- **The number is grouped the way the reader's language groups it:** `12,000` in English, `12.000`
+  in German. Each text uses one language for its words, its plural rule and its number.
+- **A plural needs an `other` branch.** `Clear {target, plural, one {# line} other {# lines}}` is
+  "Clear 1 line" at 1 and "Clear 150 lines" at 150.
+- **Write category branches (`one`, `few`, `many`, `other`), not `=N`.** An exact branch is
+  accepted only when `N` equals the current threshold, so if you later change the threshold, copy
+  that used `=N` can fail its next upload. Each text uses the categories its own language has: a
+  category that no number takes in that language (`few` in English) is refused, and so is a branch
+  written twice.
+- **Each player reads the target they are working toward.** A player who started a period before
+  you changed the threshold keeps reading their own number, in the copy and on the meter alike.
+  Section 8 has what a change of threshold does to a period in progress.
+
+### The rules for a displayed challenge's copy
+
+- **On a displayed challenge the name and description are templates, and `{` and `}` are syntax.**
+  On any other progression they are plain text, and braces mean nothing.
+- **The name is at most 64 characters and the description at most 280, counted
+  on the line a player is shown**, in every language, never on the template. Nothing is truncated;
+  text that renders too long is refused. A long plural is therefore fine when each line it renders
+  is short. The text as written may be up to 256 characters for a name and 4096 for a description.
+- **A displayed challenge's name and description are each one line.**
+- **The copy is screened at upload, in every language.** It is refused for words that claim to
+  speak for the platform or name a platform role, for the name of a platform currency, for reward
+  or credential words, and for links.
+- **Some problems are refused today, and some only draw a warning.** A problem in a `localized`
+  entry, or in text that uses `{target}`, is refused. A problem in a displayed challenge's default
+  text that does not use `{target}` (a stray brace, a line break, a screened word) draws the
+  warning `progressions_copy_refusal_pending` with the same message, and the upload succeeds. That
+  warning will become a refusal, so fix the text when you see it. It follows the text, not its age:
+  default text without `{target}` on a challenge you add today draws the same warning.
+- **A translation on a progression that is not a displayed challenge is plain text**, held to 64 /
+  280 characters as written. It is still refused for a link or for words that claim to speak for
+  the platform, and its description may have line breaks.
+
+### What a player reads, and what your game reads
+
+- **Where the platform shows a progression's name and description, a reader gets your translation
+  when there is one for their language, and the default text otherwise.**
+- **Your game's own reads do not return this text.** `gem.challenges.list()` and the progression
+  read (`currentValue`, `isCompleted`) carry no name and no description.
+- **`gem.gameConfig.load()` returns the config as you wrote it:** `display_name` and `description`
+  with `{target}` still in them, not replaced, and not chosen for the player's language. It also
+  returns your `localized` entries as written.
+- **A game that shows its own challenge UI keeps rendering its own strings**, in
+  `gem.prefs.locale`.
+
 ## 3. Report progress from your game
 
 The write is the ordinary progression write. Your game already knows how to make it:
@@ -506,7 +615,9 @@ shows, just quietly meaningless.
 
 - **A new challenge gets a new id.** Always.
 - **To rename what the player sees, change `display_name`.** That is free and is not part of the
-  challenge's identity.
+  challenge's identity. Update that name's translations in `localized` too
+  ([section 2a](#2a-translate-the-copy-and-write-the-target-into-it)): a translation you leave
+  behind keeps showing the old name to readers of that language.
 - **Changing a progression's `reset_schedule` is refused at upload**, for the same reason: a daily
   that becomes a weekly would carry its old id into a history that then describes two different
   things. A different period means a new progression. (Rewriting `0 0 * * *` as `daily` is not a
@@ -590,6 +701,17 @@ own streak on your store page. Your game does not have to render any of it.
 | `cron expression never fires`                      | an expression naming a date that does not exist (`0 0 30 2 *`)  | fix the expression                                                   |
 | `reset_schedule changed from … to …`               | you changed a live progression's period                         | use a NEW progression; `display_name` is what renames one            |
 | warning `platform_grant_max_per_window_ignored` (or `platform_grant_cap_uses_retired_max_per_entity`) | a mapping declares `max_per_window` (or `max_per_entity`) | nothing is refused and the upload succeeds; remove the key, because the platform sets the caps |
+| a refusal at `localized.<key>`                     | the key is not one of the eleven locales, or it is `en`         | use a listed locale; the text outside `localized` is the English    |
+| a refusal at a `localized.<locale>` field that is empty | an empty translation                                       | remove the key to show the default text                             |
+| a refusal naming a `{name}` other than `target`    | a displayed challenge's copy referred to something else         | `target` is the only name; remove the braces from the copy          |
+| a refusal for `{target}` with no threshold         | the progression has no `completion_threshold`                   | set one, or remove `{target}`                                       |
+| a refusal on a plural branch                       | no `other` branch, an `=N` that is not the threshold, or a category the language does not have | write the category branches that language has, and always `other` |
+| a refusal for text that is too long                | the line a player is shown passes 64 (name) or 280 (description) | shorten the text; nothing is truncated for you                     |
+| warning `progressions_copy_refusal_pending`        | default text without `{target}` on a displayed challenge breaks a copy rule | the upload succeeds; fix the text now, because this will become a refusal |
+
+A refusal about a progression's copy reads `progressions[<i>] (<slug>): <path>: <reason>`, where
+`<path>` is `display_name`, `description`, `localized.<locale>.display_name`,
+`localized.<locale>.description`, or `localized.<key>` for a refused key.
 
 Every refusal names the field and the reason. **Read the error rather than a list written down
 here** — the platform is what decides these, and this table is only as current as the day it was

package/docs/getting-started.md

@@ -50,7 +50,7 @@ either way.
 ```jsonc
 // package.json
 "dependencies": {
-  "@indiegems/gem-web-sdk": "9.1.4"
+  "@indiegems/gem-web-sdk": "10.1.0"
 }
 ```
 
@@ -175,11 +175,11 @@ gem.frame.progress(loaded, total); // while assets load
 gem.frame.ready(); // once the player can actually play
 ```
 
-And tell the Arcade where your settings are — `gem.setMenu({ onSettings })` puts them in the
-Arcade's own menu, top-right, beside Return to the Arcade
-([what a game must do](what-a-game-must-do.md#the-arcades-menu-your-settings-live-in-it)). Outside
-the Arcade there is no such menu, so also give players a way out — a control that calls `gem.exit()`. A game a player
-cannot leave is one they leave by closing the tab.
+And draw a settings button of your own — top-right is the recommendation — whose values start from
+the player's Arcade-wide defaults, `gem.prefs.recommended`, until the player chooses their own
+([what a game must do](what-a-game-must-do.md#game-settings)). The Arcade's menu does not open
+your settings. Outside the Arcade there is no Arcade menu at all, so also give players a way out — a
+control that calls `gem.exit()`. A game a player cannot leave is one they leave by closing the tab.
 
 ## 6. Play it
 

package/docs/manifest.json

@@ -33,8 +33,8 @@
     },
     {
       "file": "changelog.md",
-      "sha256": "6333e652b2c3ffade4ced6759436b8ab3dcb95b25a43c1bd82fe9a6f23fd8a7d",
-      "updated": "2026-10-10T01:45:03Z"
+      "sha256": "a194ff0323a071b622349d0b7de0f189d723472f2e6584594d752b21daf5f668",
+      "updated": "2026-10-10T20:52:09Z"
     },
     {
       "file": "cross-promotion.md",
@@ -43,8 +43,8 @@
     },
     {
       "file": "daily-challenges.md",
-      "sha256": "c198868e2cb1f1b5d9164bb5b1d23bf3f502987e45e10163c8b048a8eba24667",
-      "updated": "2026-10-02T23:01:00Z"
+      "sha256": "f4842b2fe01c8780020326f4722ab69dc01c1f40e1e6455cf2fb27752094383d",
+      "updated": "2026-10-10T14:37:50Z"
     },
     {
       "file": "dedicated-server-flow.md",
@@ -68,8 +68,8 @@
     },
     {
       "file": "getting-started.md",
-      "sha256": "22fab7f0fd67966239c38541a8620ac7fe614f100b96df3e94570b573d4a9f61",
-      "updated": "2026-10-10T01:45:03Z"
+      "sha256": "f7a67995ffcbddafaf7ed5c6c1ae8bc2c25dabe60c588e5b70dfb73218445a36",
+      "updated": "2026-10-10T20:52:09Z"
     },
     {
       "file": "inventory-and-catalogs.md",
@@ -113,8 +113,8 @@
     },
     {
       "file": "rooms-and-matches.md",
-      "sha256": "0abf3717a42c94ec832dfa1310c2d93a9f58236fd75b0aacaab301976bffe286",
-      "updated": "2026-10-07T19:27:16Z"
+      "sha256": "23540a20bdd8c8d058eb06d8ef11085ffd8eaaeeaadc93a807608b7c279e240c",
+      "updated": "2026-10-10T18:05:31Z"
     },
     {
       "file": "saving-player-progress.md",
@@ -123,8 +123,8 @@
     },
     {
       "file": "server-bundles.md",
-      "sha256": "bc59062fefb7c17986671e2a8b6b86b714d1c7e9774956a3df98adcef38a7fd2",
-      "updated": "2026-10-10T01:45:03Z"
+      "sha256": "211384b7a68560979a43a57d25acc1e2897343958973b1c3f2a0d8fbeb0d7ffd",
+      "updated": "2026-10-10T20:52:09Z"
     },
     {
       "file": "serverless-functions-js.md",
@@ -143,13 +143,13 @@
     },
     {
       "file": "vibration.md",
-      "sha256": "3608da64abcef207cf0875f9d32f3aed88d4fb23512bc70d0a9684a570263a44",
-      "updated": "2026-10-06T17:36:25Z"
+      "sha256": "587031f88acb64d8da0933ead76e50a88190e24a17effd875de0828f8c436393",
+      "updated": "2026-10-10T20:30:31Z"
     },
     {
       "file": "what-a-game-must-do.md",
-      "sha256": "bc02d4a864943da446d9411b338b75908d9e0c2e0bc8378bbd28bf3f0ccf7f2a",
-      "updated": "2026-10-09T00:24:00Z"
+      "sha256": "a339443ece37e5a5311a05ff946a081ac6e8557d29e2ab59b90832e4ad40fc5d",
+      "updated": "2026-10-10T20:42:00Z"
     }
   ]
 }

package/docs/rooms-and-matches.md

@@ -746,16 +746,140 @@ for it would find it, and the room would still be briefly the wrong size — a v
 by a hidden one. The platform refuses the field outright, for this reason: a
 developer meets the rule locally rather than as a 400 in production.
 
+## 5c. Queueing for a match: tickets
+
+`quickJoin()` puts a player in a room at once and lets the room fill around them. That is right for a
+drop-in mode and wrong for one that must not start short — a duel, a team mode — because the first
+player in sits alone in a lobby, and a match is sized by who is there when it starts.
+
+`queueForMatch()` is the other way in. The player waits in a queue; when the platform has enough
+players for one of the templates the ticket named, it makes the room, seats every one of them and
+starts the match. Nobody hosts, and nobody calls `startMatch()`.
+
+```js
+const ticket = await gem.rooms.queueForMatch({ templateSlugs: ['duel', 'brawl'] });
+showSearching({ expiresAt: ticket.expiresAt, onCancel: () => ticket.cancel() });
+
+const outcome = await ticket.outcome;
+if (outcome.status === 'matched') enterMatch(outcome.room);
+else backToMenu(outcome.status);
+```
+
+**A template has to opt in.** A room template is queueable when its `matchmaking` block says
+`enabled: true`; a ticket naming one that does not is refused whole, **400
+`matchmaking_not_enabled`**. `fill_window_seconds` in that block is how long a queue holds out for
+`max_players` before it accepts `min_players`. The block cannot be combined with `auto_start_host`.
+
+**A ticket names every mode the player accepts**, one to eight templates, and is matched under
+whichever fills first. That is one ticket, not several: a player can be on one ticket at a time, across
+every game.
+
+### What the SDK does while the ticket waits
+
+- **It keeps the ticket alive.** A ticket nobody heartbeats is expired by the platform, so that a
+  player who closed the tab does not hold a place in a lobby. The interval is the platform's setting
+  and arrives on the ticket; the SDK reads it from there and a game never sends a heartbeat.
+- **The heartbeat is also how it learns the answer.** Each one returns the ticket as it stands, so a
+  match is noticed within one interval even when nothing crosses the bridge.
+- **A relayed push makes it ask at once.** The match's own start is relayed like any room event (§3),
+  and one that arrives about a room the manager is not in, while a ticket waits, is treated as a cue:
+  the ticket is read immediately, and once more a second later if it still says `queued` — the
+  platform sends the push a moment before it marks the ticket. So on a page that relays, a match is
+  noticed in about the time the push takes, not at the next heartbeat. A tab returning to the
+  foreground is the same cue. Like every relay it is a hint: nothing is entered on its strength.
+- **It refuses a second thing in flight.** While a ticket waits, `create`, `join`, `joinByCode`,
+  `quickJoin` and another `queueForMatch` are refused locally.
+- **It cancels the ticket when the tab closes.** See below.
+- **It raises no `seated` for the ticket's own room.** The owner is told by the outcome. Party
+  members, who hold no ticket, are told by `seated` as they are for any room their leader enters.
+
+### Queueing from inside a room
+
+A player sitting in a hub or a social lobby can queue without leaving it. The ticket takes no seat
+while it waits, and `gem.rooms.currentRoom` stays the room they are in.
+
+When the ticket is matched, **the manager moves and the seat stays**. `currentRoom` becomes the
+match's room and `joined` fires for it. The room the player queued from is not left: no leave is
+sent, no `left` is raised, and the platform still counts them as a member there. When the match is
+over, `gem.rooms.leave()` then `gem.rooms.join(hub.id)` puts them back — `join()` on a room a player
+already holds a seat in answers with the room.
+
+Keep the hub's id if you want that return trip: `currentRoom` is the match's room now, and the
+manager does not hand the old one back.
+
+**A tab closed before the player goes back leaves both rooms.** The SDK remembers the room a matched
+ticket moved it out of, and on `pagehide` sends a keepalive leave for it as well as for the room it
+is in. Otherwise the hub seat would outlive the page with nothing tracking it, and the player's next
+session would start already inside a room. Once the player is back in the hub, it is the tracked
+room again and the ordinary leave covers it.
+
+### When the tab closes
+
+**The ticket is cancelled as the page goes away.** On `pagehide` the SDK sends the cancel as a
+keepalive request, which the browser delivers after the document is gone, and settles the ticket
+`cancelled`. Without it a closed tab's ticket would stay matchable until the platform noticed nobody
+was keeping it alive, and a match formed in that window seats a player who is not there.
+
+This also happens when the page is put in the back/forward cache. A frozen page keeps nothing alive,
+so the player cannot come back to the same ticket; they come back to one that reads `cancelled` and
+queue again.
+
+The platform's own timeout is still there for a tab that crashed or lost its network, where no
+request can be sent. It is the fallback, not the mechanism.
+
+### How a ticket ends
+
+`ticket.outcome` settles once, and **resolves** for every ending the platform reports — these are
+outcomes to branch on, not errors to catch:
+
+| `status` | `reason` | What happened | Queue again? |
+| --- | --- | --- | --- |
+| `matched` | — | Seated, and the match is starting. `gem.rooms.currentRoom` is `outcome.room`, `joined` has fired, and the match events follow as for any room. | — |
+| `expired` | `timed_out` | Nobody to play with before the ticket's expiry. | on a fresh press |
+| `expired` | `heartbeat_lapsed` | The tab was throttled or offline too long to keep it alive. | on a fresh press |
+| `cancelled` | `requested` | `ticket.cancel()`. | — |
+| `cancelled` | `party_changed` | The party gained or lost a member while it waited. | once the party is settled |
+| `failed` | `handoff_failed` | A match formed and could not be started, several times over. | later; this is the platform's fault |
+| `lost` | — | The platform no longer has the ticket. Queues are held in memory and a restart loses them. | yes |
+| `unavailable` | — | Matchmaking is turned off, or stopped answering for longer than a ticket survives. | not in a loop |
+
+`lost` and `unavailable` are the SDK's own conclusions. A heartbeat answered "no such ticket" ends
+the wait as `lost` at once. Three heartbeats in a row that got no usable answer end it too — as
+`unavailable` when the platform said matchmaking is off, `lost` otherwise — and the SDK sends one
+cancel on its way out, in case the requests arrived and only the answers were lost.
+
+It **rejects** in one case: the ticket was matched and the room it was seated in could not be read. The
+seat stands, so `myRooms()` shows the room and `join(id)` enters it.
+
+**`cancel()` can lose the race.** A ticket the platform has already seated is never undone, so
+`cancel()` resolves the ticket's real outcome, and that may be `matched`. Backing out from there is
+`gem.rooms.leave()`.
+
+### The refusals when queueing
+
+`queueForMatch()` itself rejects with `GemApiError` when no ticket was made. Branch on `code`:
+
+| Code | Meaning |
+| --- | --- |
+| `already_queued` (409) | This player, or someone in their party, is already on a ticket — another tab, or another game. |
+| `matchmaking_not_enabled` (400) | A named template has no enabled `matchmaking` block. A config fault, not a player one. |
+| `matchmaking_unavailable` (503) | Matchmaking is turned off for the whole platform, or its store is not answering. |
+
+⚠️ **Nothing falls back to quick-join, and a game should not either.** Not on
+`matchmaking_unavailable`, not on `expired`. Quick-join puts the player in a different kind of room —
+alone, in a mode that was queued for precisely because it needs a lobby. Tell the player matchmaking is
+unavailable and leave the button where it is.
+
 ## 6. Scope
 
 **In:** rooms, membership, host, ready state, the match lifecycle, and the dedicated-server connect
 flow reshaped around them. P2P _allocation_ falls out of the same shape — `startMatch` is one route
 and a P2P match simply reports `ready` at once.
 
-**Out:** matchmaking beyond the engine's find-or-create. `quickJoin()` is exactly `quick_join`: join
-an open public room matching the template, in a cluster this player can play well in, or create one.
-There is no ranked
-system, no skill rating and no queue, and inventing one is not a small addition to this.
+**Out:** matching by anything but arrival order. `quickJoin()` is exactly `quick_join`: join an open
+public room matching the template, in a cluster this player can play well in, or create one.
+`queueForMatch()` (§5c) waits for a full lobby, oldest ticket first. There is no ranked system and no
+skill rating, and inventing one is not a small addition to this.
 
 **Elsewhere:** P2P _connection_ and parties. Both are
 [`p2p-and-parties.md`](p2p-and-parties.md). Three things surface here:

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

package/docs/vibration.md

@@ -23,7 +23,9 @@ Two rules come before everything else on this page. Both are easy to get wrong.
 
 ## The whole integration
 
-Your game owns its vibration toggle; the Arcade has none. Keep the toggle in
+Your game owns its vibration toggle. The Arcade keeps only the player's Arcade-wide default,
+`gem.prefs.recommended.vibration`, which your toggle starts from until the player flips it
+([game settings](what-a-game-must-do.md#game-settings)). Keep the player's choice in
 `gem.deviceSettings`, never in `localStorage`, which every publish of your game wipes.
 
 ```js
@@ -32,10 +34,13 @@ await gem.awaitBridge();
 // Your settings, kept by the Arcade so they survive your next publish.
 let settings = (await gem.deviceSettings.wait(1_500)) ?? {};
 
+// The player's own choice, else the Arcade's recommendation, else on.
+const vibrationOn = () => settings.vibration ?? gem.prefs?.recommended?.vibration ?? true;
+
 // Build the row when the settings screen OPENS, never once at boot.
 function openSettings() {
   vibrationRow.hidden = !gem.vibration.available;
-  vibrationToggle.checked = settings.vibration !== false;
+  vibrationToggle.checked = vibrationOn();
 }
 
 vibrationToggle.onchange = () => {
@@ -45,7 +50,7 @@ vibrationToggle.onchange = () => {
 
 // Check your own toggle before every call. Nothing else: no fallback.
 function onHit() {
-  if (settings.vibration !== false) gem.vibration.vibrate(30);
+  if (vibrationOn()) gem.vibration.vibrate(30);
 }
 ```
 

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

@@ -564,14 +564,15 @@ credit for it until you say so.
 Five messages arrive that a game cannot ask for — the parent pushes them on its own schedule, and
 there is no route by which the frame could request one. `createGem` forwards all five:
 
-- **`onPrefs`** — `reducedMotion`, `muted`, `locale`, `showFrameStats`, sent once after the
-  handshake and again on every change. Also **held**, as `gem.prefs`, because a component mounted
+- **`onPrefs`** — `reducedMotion`, `muted`, `locale`, `showFrameStats` and `recommended`, sent
+  once after the handshake and again on every change. Also **held**, as `gem.prefs`, because a component mounted
   after the push would otherwise have missed it and cannot ask again. Read it where you need it
   rather than caching it — the locale changes mid-session. `muted` is the Arcade's mute: the SDK
   silences your page itself, and your own mute control follows it — see
   [sound](#sound-your-own-mute-control-and-the-arcades) below. `showFrameStats` you need not act
   on: the SDK counts your frames itself — see [the Arcade's FPS overlay](#the-arcades-fps-overlay). See the language section for how to combine
-  `locale` with your own detection.
+  `locale` with your own detection. `recommended` is the player's Arcade-wide defaults, which your
+  own settings start from — see [game settings](#game-settings).
 - **`onPause`** — **pause gameplay and release the cursor.** Cooperative; nothing enforces it.
 
   ```js
@@ -586,7 +587,7 @@ there is no route by which the frame could request one. `createGem` forwards all
   the dialog sitting on top of your game.
 
   **Save on pause.** When a player on a phone chooses Return to the Arcade in
-  [the Arcade's menu](#the-arcades-menu-your-settings-live-in-it), or presses the device's Back, your
+  [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
   press Continue — `onPause(false)`, and play resumes where it stopped — or the parked game may be
@@ -704,8 +705,8 @@ the `var()` above, or read `gem.viewport`. The release checklist looks for the b
 On a phone your game is full-bleed, and the arcade keeps one row of its own over the top of it:
 
 - **The menu button**, in the **top-right corner**, always there. It opens
-  [the Arcade's menu](#the-arcades-menu-your-settings-live-in-it): Return to the Arcade, your
-  settings, mute and the rest.
+  [the Arcade's menu](#the-arcades-menu): Return to the Arcade, mute, the player's Arcade-wide
+  settings and the rest. Not your settings: those are [your own button](#game-settings).
 - **The player's wallets** (Gems, Tickets, their achievement score), in the **middle of the row**,
   [there unless your game hides them](#the-arcades-wallet-shown-unless-you-hide-it-never-drawn),
   during play as well as on your menus. They are translucent, so your game shows through them — but they are still the Arcade's,
@@ -723,8 +724,8 @@ Keep the left for Home / Back even on a screen that has neither today: a player
 is once, across every game, and information that sits there on one screen teaches them the wrong
 thing on the next.
 
-**Put no settings, pause-menu or burger button of your own top-right**: your settings open from the
-Arcade's menu, and a second button under the Arcade's would mean something else in every game.
+**Your settings button goes top-right, clear of the Arcade's controls**: never under one, and below
+any the Arcade keeps in that corner. [Game settings](#game-settings) shows how to place it.
 
 **How much room the top-left has.** The menu button is about 48px across — the size of a Home or
 Back button. With every wallet shown, the narrowest phones (360px wide) leave roughly 68px to the
@@ -903,22 +904,104 @@ and anything that must follow them, is a save or `gem.me.settings`:
 draws the line in full. Never block your first frame on it either: apply defaults, then apply what
 arrives.
 
-## The Arcade's menu: your settings live in it
+## Game settings
 
-The Arcade keeps one menu button over every game, top-right, on every device. Its menu is how a
-player leaves (**Return to the Arcade**), mutes, goes fullscreen and reports a problem — and how they
-open **your settings**, once you say you have some:
+**Your settings belong to your game: draw a settings button of your own, and the screen it opens.**
+The Arcade does not put your settings in its menu any more — its menu holds the player's
+_Arcade-wide_ settings instead — so a game with no button of its own has settings nobody can reach.
+
+**Put the button in the top-right corner.** That is a recommendation, not a rule the Arcade
+enforces, but a player who finds settings in the same corner in every game never has to look. Place
+it with the reserved-area properties so it never sits under an Arcade control, whatever the Arcade
+keeps in that corner on this device:
+
+```css
+#settings-button {
+  position: absolute;
+  top: max(
+    var(--gem-safe-top, env(safe-area-inset-top, 0px)),
+    var(--gem-reserved-tr-height, 0px)
+  );
+  right: var(--gem-safe-right, 0px);
+}
+```
+
+### Start from the player's Arcade-wide defaults: `gem.prefs.recommended`
+
+The player sets their defaults once, in the Arcade's Settings, separately for each device — a phone
+and a television can say different things. They reach your game as `gem.prefs.recommended`, in the
+same push as `muted` and `reducedMotion`, and again whenever the player changes one:
+
+| Field            | Values                | What it suggests                                                                                             |
+| ---------------- | --------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `volume`         | `0` to `100`          | Your master volume's starting level, as a percentage — divide by 100 for a gain. A level, never a mute.     |
+| `batterySaver`   | `true` / `false`      | Spend less power: a lower frame rate, fewer effects, a lower resolution.                                     |
+| `keyboardLayout` | `'wasd'` / `'arrows'` | Which keys move by default.                                                                                  |
+| `gamepadConfirm` | `'south'` / `'east'`  | Which face button confirms, by position: the bottom one (A on an Xbox controller) or the right one (B). The other one goes back. |
+| `vibration`      | `true` / `false`      | Your vibration toggle's starting state ([if your game vibrates](#if-your-game-vibrates)).                    |
+
+**They are recommendations, and the player's own choice in your game always wins:**
+
+- **Start from `recommended` only when the player has no saved choice** for that setting. Decide it
+  setting by setting: a player who chose a volume and nothing else still gets the recommended
+  keyboard layout.
+- **Never overwrite the player's own choice when the recommendation changes.** Keep what the player
+  chose apart from what you worked out, and save only what they chose: a recommended volume saved
+  as if it were theirs is one the next change to the recommendation can no longer reach. A "Reset
+  to defaults" in your settings clears what the player chose, so the recommendation applies again.
+- **`null` means no advice**: an older Arcade, or an embedder that keeps no such settings. Use your
+  own defaults. Never hold your first frame for it.
+- **You may ignore any of it.** A game with no keyboard support has nothing to do with
+  `keyboardLayout`.
+
+```js
+const DEFAULTS = { volume: 100, batterySaver: false, keyboardLayout: 'wasd', gamepadConfirm: 'south', vibration: true };
+let chosen = {}; // ONLY what the player picked in your settings screen
+
+// The player's choice, then the Arcade's recommendation, then your own default.
+const setting = (key) => chosen[key] ?? gem.prefs?.recommended?.[key] ?? DEFAULTS[key];
+
+const gem = createGem({
+  // The recommendation changed: apply it again. What the player chose does not move.
+  onPrefs: () => applySettings(setting),
+});
+
+chosen = (await gem.deviceSettings.wait(1_500)) ?? {};
+applySettings(setting);
+
+// The player moved YOUR slider: that one setting is now theirs.
+volumeSlider.oninput = () => {
+  chosen = { ...chosen, v: 1, volume: volumeSlider.valueAsNumber };
+  gem.deviceSettings.put(chosen); // debounce it
+  applySettings(setting);
+};
+```
+
+[Device settings](#device-settings-what-this-device-remembers-about-your-game) above is where the
+player's choices are kept between sessions.
+
+**Read `muted` and `reducedMotion` as before.** They are not recommendations and they did not move:
+`muted` is the Arcade's mute, which the SDK applies for you
+([sound](#sound-your-own-mute-control-and-the-arcades)), and `reducedMotion` is the player's
+accessibility setting, which your game honours.
+
+## The Arcade's menu
+
+The Arcade keeps one menu button over every game, on every device. Its menu is how a player leaves
+(**Return to the Arcade**), 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:
 
 ```js
-const inArcadeMenu = gem.setMenu({
-  onSettings: () => settingsScreen.open(),
+gem.setMenu({
   items: [{ id: 'how-to-play', label: t('How to play'), onSelect: () => help.open() }],
 });
 ```
 
-- **`onSettings` puts a Settings entry in the menu.** The Arcade closes its menu, resumes your game,
-  and calls it; you draw your own settings screen, as you always did. Leave it out and the menu has
-  no Settings entry.
+- **The Arcade no longer shows a "Game settings" row for `onSettings`.** Your settings open from
+  [your own button](#game-settings). `gem.setMenu({ onSettings })` is still accepted, so a game that
+  passes it keeps working, and another embedder may still show an entry for it — but in the Arcade
+  it adds nothing.
 - **`items` are up to four entries of your own**, shown in a group below the Arcade's. `id` is your
   name for the entry (1 to 32 characters); `label` is what the player reads, **already in their
   language** (`gem.prefs.locale`) — the Arcade does not translate it, cuts it at 40 characters, and
@@ -934,14 +1017,9 @@ const inArcadeMenu = gem.setMenu({
   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.
 
-**Do not draw a settings button of your own while `gem.setMenu` returns `true`.** One menu, in one
-place, in every game is the point. Draw your own **only when it returns `false` after the bridge has
-settled** — an embedder with no menu, or your game running outside any embedder:
-
-```js
-await gem.awaitBridge();
-ownSettingsButton.hidden = gem.setMenu({ onSettings: () => settingsScreen.open() });
-```
+`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
+that calls `gem.exit()`.
 
 Your own **back or home** button — the one that moves around inside your game — goes **top-left**,
 which the Arcade [leaves clear](#the-arcades-own-controls-reserved-areas). It never leaves the game:

package/package.json

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