@indiegems/gem-web-sdk 10.0.0 → 10.1.0

package/docs/api/reference.json

@@ -2,7 +2,7 @@
   "schema_version": 2,
   "source": {
     "repo": "IndieGems/gem-web-sdk",
-    "version": "10.0.0"
+    "version": "10.1.0"
   },
   "entries": [
     {
@@ -7630,7 +7630,7 @@
           "group": "start",
           "signature": "readonly onPrefs?: (prefs: GemPrefs) => void",
           "documented": true,
-          "summary": "The player's accessibility and locale preferences arrived, or changed.\n\n**A game that animates owes this a handler.** Reduced motion is the\nplayer's own account setting, and honouring it is on the platform's release\nchecklist.\n\n**`muted` is honoured for you** — the SDK silences your audio itself (see\n`manageAudio`). If your game has its own mute control, set it from `muted`\nhere so the two agree, and see [Gem.reportMuted](api-reference-game.md#gem-reportmuted) for the other\ndirection.",
+          "summary": "The player's accessibility and locale preferences arrived, or changed.\n\n**A game that animates owes this a handler.** Reduced motion is the\nplayer's own account setting, and honouring it is on the platform's release\nchecklist.\n\n**`muted` is honoured for you** — the SDK silences your audio itself (see\n`manageAudio`). If your game has its own mute control, set it from `muted`\nhere so the two agree, and see [Gem.reportMuted](api-reference-game.md#gem-reportmuted) for the other\ndirection.\n\n**`recommended` changing is advice changing.** Apply it only to a setting\nthe player has not chosen in your game; never overwrite their own choice\nwith it.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -8008,7 +8008,7 @@
           "group": "player",
           "signature": "interface GemPrefs",
           "documented": true,
-          "summary": "The player's arcade-level preferences, which your game is expected to honour.\n\nReached as `gem.prefs`. These are the player's settings for the whole arcade,\nnot for your game — respecting them is part of what a game must do.\n\nThey can change mid-session, so read them when you need them rather than\ncaching at boot.",
+          "summary": "The player's arcade-level preferences, which your game is expected to honour.\n\nReached as `gem.prefs`. These are the player's settings for the whole arcade,\nnot for your game — respecting them is part of what a game must do.\n\nThey can change mid-session, so read them when you need them rather than\ncaching at boot.\n\n`recommended` is the exception: the player's Arcade-wide defaults, which\nyour game may start its own settings from or ignore — never a reason to\noverwrite a choice the player made in your game.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -8086,6 +8086,123 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "GemPrefs.recommended",
+          "name": "recommended",
+          "anchor": "gemprefs-recommended",
+          "group": "player",
+          "signature": "readonly recommended: GemRecommendedSettings | null",
+          "documented": true,
+          "summary": "The player's Arcade-wide defaults for this device — a volume, battery\nsaver, a keyboard layout, the gamepad's confirm button and vibration — or\n`null` when the Arcade did not send them.\n\n**Recommendations only; the player's own choice in your game wins.** Start\na setting from here while the player has made no choice of their own for\nit, and never overwrite one they made because this changed:\n\n```js\nconst saved = gem.deviceSettings.current ?? {};\nconst volume = saved.volume ?? gem.prefs?.recommended?.volume ?? 100;\n```\n\nUnlike `muted` and `reducedMotion`, nothing here is applied for you, and\nnothing obliges you to use it. See the guide's \"Game settings\" section.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemRecommendedSettings",
+          "name": "GemRecommendedSettings",
+          "anchor": "gemrecommendedsettings",
+          "group": "player",
+          "signature": "interface GemRecommendedSettings",
+          "documented": true,
+          "summary": "The player's Arcade-wide defaults for this device, as `gem.prefs.recommended`.\n\nThe player sets these once in the Arcade's Settings, and every game that\nreads them starts in the right place. They are advice: a game may ignore\nthem, and a choice the player made in your game always beats them.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": [
+            {
+              "slug": "what-a-game-must-do",
+              "anchor": null
+            }
+          ]
+        },
+        {
+          "id": "GemRecommendedSettings.volume",
+          "name": "volume",
+          "anchor": "gemrecommendedsettings-volume",
+          "group": "player",
+          "signature": "readonly volume: number",
+          "documented": true,
+          "summary": "The volume the player wants, as a percentage from 0 to 100. A level, not a\nmute — `gem.prefs.muted` is the mute.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemRecommendedSettings.batterySaver",
+          "name": "batterySaver",
+          "anchor": "gemrecommendedsettings-batterysaver",
+          "group": "player",
+          "signature": "readonly batterySaver: boolean",
+          "documented": true,
+          "summary": "The player asked games to save power on this device: a lower frame rate,\nfewer effects, a lower resolution.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemRecommendedSettings.keyboardLayout",
+          "name": "keyboardLayout",
+          "anchor": "gemrecommendedsettings-keyboardlayout",
+          "group": "player",
+          "signature": "readonly keyboardLayout: \"wasd\" | \"arrows\"",
+          "documented": true,
+          "summary": "Which keys the player expects to move with: `'wasd'` or `'arrows'`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemRecommendedSettings.gamepadConfirm",
+          "name": "gamepadConfirm",
+          "anchor": "gemrecommendedsettings-gamepadconfirm",
+          "group": "player",
+          "signature": "readonly gamepadConfirm: \"south\" | \"east\"",
+          "documented": true,
+          "summary": "Which gamepad face button the player expects to confirm with, by position:\n`'south'` (the bottom button, A on an Xbox controller) or `'east'` (the\nright one, B on an Xbox controller). The other one goes back.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemRecommendedSettings.vibration",
+          "name": "vibration",
+          "anchor": "gemrecommendedsettings-vibration",
+          "group": "player",
+          "signature": "readonly vibration: boolean",
+          "documented": true,
+          "summary": "Whether the player wants vibration and controller rumble.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "GemCohort",
           "name": "GemCohort",
@@ -8487,7 +8604,7 @@
           "group": "frame",
           "signature": "readonly onSettings?: () => void",
           "documented": true,
-          "summary": "Open your settings screen. Give this and the arcade's menu gains a\nSettings entry that calls it; leave it out and there is no such entry.",
+          "summary": "Open your settings screen. Another embedder may show a Settings entry that\ncalls it, but **the Gem Arcade no longer does**: draw a settings button of\nyour own, always (top-right is the recommendation). Passing this is still\naccepted and harmless.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -9271,7 +9388,7 @@
           "group": "start",
           "signature": "setMenu(menu: GameMenu): boolean",
           "documented": true,
-          "summary": "Put your settings, and up to four entries of your own, in the arcade's\nmenu. The arcade keeps one menu button over your game, in the top-right\ncorner: it is how a player leaves, mutes, goes fullscreen and reports a\nproblem — and, once you call this, how they open **your** settings.\n\n```js\nconst inArcadeMenu = gem.setMenu({\n  onSettings: () => settingsScreen.open(),\n  items: [{ id: 'how-to-play', label: t('How to play'), onSelect: () => help.open() }],\n});\nownSettingsButton.hidden = inArcadeMenu;\n```\n\n**Do not draw a settings button of your own while this returns `true`** —\nthe arcade's menu is the one place a player looks, in every game. Draw\nyour own only when it returns `false` once the bridge has settled\n(`await gem.awaitBridge()`): an embedder with no menu, or no embedder at\nall. The top-left corner is yours, for a back or home button that moves\naround inside your game.\n\n**It is screen state, not a toggle.** Each call is the whole answer and\nreplaces the last, so call it again when the entries change — a new\nlanguage, a screen with different options. `gem.setMenu({})` takes\neverything of yours back out. The arcade's own entries are not yours to\nchange, and Return to the Arcade is always among them.\n\n**The arcade pauses your game while its menu is open** (`onPause`), and\nresumes it before a handler of yours runs. A handler opens a screen; it\nshould not assume the game was paused by you.",
+          "summary": "Put up to four entries of your own in the arcade's menu. The arcade keeps\none menu button over your game: it is how a player leaves, mutes, goes\nfullscreen, reports a problem and changes their Arcade-wide settings.\n\n```js\ngem.setMenu({\n  items: [{ id: 'how-to-play', label: t('How to play'), onSelect: () => help.open() }],\n});\n```\n\n**Your settings are not in it: draw your own settings button, always** —\ntop-right is the recommendation. `onSettings` is still accepted, and\nanother embedder may show an entry for it, but the Gem Arcade no longer\nshows a Settings entry, so a game whose settings open only from there has\nnone a player can reach.\n\n**It is screen state, not a toggle.** Each call is the whole answer and\nreplaces the last, so call it again when the entries change — a new\nlanguage, a screen with different options. `gem.setMenu({})` takes\neverything of yours back out. The arcade's own entries are not yours to\nchange, and Return to the Arcade is always among them.\n\n**The arcade pauses your game while its menu is open** (`onPause`), and\nresumes it before a handler of yours runs. A handler opens a screen; it\nshould not assume the game was paused by you.",
           "deprecated": null,
           "params": [
             {

package/docs/changelog.md

@@ -16,6 +16,19 @@ 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.
 
+## 10.1.0
+
+Upgrading from 10.0.0. Impact: required.
+
+### Rebuild
+
+- The host-side method for sending preferences now accepts an optional recommended object with the five default settings. Existing calls remain valid, so recompiling is enough. Pass the new field only if your test host should simulate the Arcade's recommended defaults.
+
+### New capability
+
+- GemPrefs now carries an optional recommended field holding the player's Arcade-wide defaults as advice: volume from 0 to 100, battery saver, keyboard layout (wasd or arrows), gamepad confirm button (south or east) and vibration. It is null when the Arcade does not send it. Changes arrive through the existing preferences callback, and the latest value is always available on the current preferences. Use these values as starting points when the player has no saved choice in your game, and never overwrite a choice the player made in your own settings. Muted, reduced motion and frame stats stay where they were.
+- A new GemRecommendedSettings type describes the recommended defaults object. You can use it to type your own code that reads or stores the recommended values. The object is frozen, so copy values into your own settings rather than modifying it.
+
 ## 10.0.0
 
 Upgrading from 9.1.4. Impact: required.

package/docs/getting-started.md

@@ -50,7 +50,7 @@ either way.
 ```jsonc
 // package.json
 "dependencies": {
-  "@indiegems/gem-web-sdk": "10.0.0"
+  "@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": "cdaa2661a18afd096def083e5a44b2e125275d2aaa210b5d1e496631bf18f457",
-      "updated": "2026-10-10T18:47:07Z"
+      "sha256": "a194ff0323a071b622349d0b7de0f189d723472f2e6584594d752b21daf5f668",
+      "updated": "2026-10-10T20:52:09Z"
     },
     {
       "file": "cross-promotion.md",
@@ -68,8 +68,8 @@
     },
     {
       "file": "getting-started.md",
-      "sha256": "39812f4b84097fd29f4038324a9070eeddf526ca294f7cb5b7b3913335ac34bf",
-      "updated": "2026-10-10T18:47:07Z"
+      "sha256": "f7a67995ffcbddafaf7ed5c6c1ae8bc2c25dabe60c588e5b70dfb73218445a36",
+      "updated": "2026-10-10T20:52:09Z"
     },
     {
       "file": "inventory-and-catalogs.md",
@@ -123,8 +123,8 @@
     },
     {
       "file": "server-bundles.md",
-      "sha256": "43a7674a6da40e2091538d6a24664a66c4cf607cc16b6027f2ddf6fd7421861c",
-      "updated": "2026-10-10T18:47:07Z"
+      "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/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/v10.0.0/gem-web-sdk.tgz
-curl -fsSL https://downloads.gemarcade.com/sdk/v10.0.0/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": "10.0.0",
+  "version": "10.1.0",
   "description": "postMessage bridge contract between gem-web and browser-playable games",
   "license": "UNLICENSED",
   "type": "module",

package/schema/bridge.v1.json

@@ -763,6 +763,67 @@
             "because removing it is a `v` bump and an embedder may legitimately send",
             "one."
           ]
+        },
+        "recommended": {
+          "kind": "object",
+          "optional": true,
+          "$comment": [
+            "The player's ARCADE-WIDE DEFAULTS for this device, which the Arcade",
+            "keeps in its own Settings: a starting volume, battery saver, a keyboard",
+            "layout, the gamepad's confirm button, and vibration. RECOMMENDATIONS",
+            "ONLY. The game's own saved settings win: a game starts a setting from",
+            "here only while the player has made no choice of their own in that",
+            "game, and never overwrites one the player made because this changed.",
+            "A game may ignore it entirely.",
+            "",
+            "OPTIONAL because it is additive: a parent that predates it sends the",
+            "fields above without it, and the SDK reports `null`. All five fields",
+            "come together or the object is absent -- a parent that keeps only some",
+            "of them fills the rest from the defaults below rather than sending a",
+            "partial object.",
+            "",
+            "`muted`, `reducedMotion` and `showFrameStats` stay where they are, at",
+            "the top of this message, and keep their meaning: they are the Arcade's",
+            "own state the frame acts on, not a recommendation. The Arcade starts",
+            "them from the same per-device defaults.",
+            "",
+            "A DISPLAY PREFERENCE OF THE DEVICE, like `showFrameStats`: the Arcade",
+            "keeps one copy per device in the player's account (a guest's on the",
+            "device only), so a phone and a television recommend different things.",
+            "Sent in the first push after connecting and again on change.",
+            "",
+            "WIDENING AN ENUM HERE IS NOT FREE. The generated validator refuses the",
+            "WHOLE message on any field it rejects, so a value an older frame does",
+            "not know would cost it `muted` and `reducedMotion` as well. A new",
+            "keyboard layout or confirm button needs a capability the frame",
+            "advertises before a parent may send it."
+          ],
+          "fields": {
+            "volume": {
+              "kind": "int",
+              "min": 0,
+              "max": 100,
+              "$comment": "Master volume as a percentage, 0..100. Default 100. A level, not a mute: `muted` above is the mute."
+            },
+            "batterySaver": {
+              "kind": "boolean",
+              "$comment": "The player asked games to spend less power: a lower frame rate, fewer effects, a lower resolution. Default false."
+            },
+            "keyboardLayout": {
+              "kind": "enum",
+              "values": ["wasd", "arrows"],
+              "$comment": "Which keys move by default: WASD or the arrow keys. Default `wasd`."
+            },
+            "gamepadConfirm": {
+              "kind": "enum",
+              "values": ["south", "east"],
+              "$comment": "Which face button confirms, by position: `south` (the bottom button, A on an Xbox pad) or `east` (the right button, B on an Xbox pad); the other one goes back. Default `south`."
+            },
+            "vibration": {
+              "kind": "boolean",
+              "$comment": "Whether the player wants vibration and controller rumble. Default true."
+            }
+          }
         }
       },
       "rateLimit": { "perMinute": 60 }
@@ -2422,11 +2483,12 @@
       "transport": "port",
       "$comment": [
         "What the game adds to the arcade's own menu — the one control the arcade",
-        "keeps over a game, in the frame's top-right corner, which is how a player",
-        "leaves, mutes, reports a problem, and reaches the game's settings.",
+        "keeps over a game, in a corner `gem.viewport.reserved` names, which is how",
+        "a player leaves, mutes and reports a problem.",
         "",
         "  settings: true   the game has a settings screen and will open it when",
-        "                   told to; the menu gains a Settings entry",
+        "                   told to; a parent MAY show a Settings entry for it",
+        "                   (the Gem Arcade no longer does: see below)",
         "  items            up to four entries of the game's own, in this order,",
         "                   below the arcade's entries and visibly apart from them",
         "",
@@ -2454,8 +2516,15 @@
         "entry does nothing but send `gem.menuSelect`.",
         "",
         "Gated by `gameMenu`: sent only to a parent that advertised it. To any",
-        "other, `gem.setMenu` returns false and the game shows a settings control",
-        "of its own instead."
+        "other, `gem.setMenu` returns false.",
+        "",
+        "THE GEM ARCADE NO LONGER SHOWS A SETTINGS ENTRY FOR `settings: true`.",
+        "A game draws its own settings button (top-right is the recommendation)",
+        "and the Arcade's menu holds the player's Arcade-wide settings instead,",
+        "which reach the game as `gem.prefs.recommended`. The field STAYS: removing",
+        "it is a `v` bump, every game that sends it keeps working, and another",
+        "embedder may still show the entry. A parent that ignores it sends no",
+        "`gem.menuSelect` for it."
       ],
       "fields": {
         "settings": { "kind": "boolean" },