@indiegems/gem-web-sdk 7.8.0 → 7.9.0

package/docs/getting-started.md

@@ -50,7 +50,7 @@ either way.
 ```jsonc
 // package.json
 "dependencies": {
-  "@indiegems/gem-web-sdk": "7.8.0"
+  "@indiegems/gem-web-sdk": "7.9.0"
 }
 ```
 
@@ -175,7 +175,10 @@ gem.frame.progress(loaded, total); // while assets load
 gem.frame.ready(); // once the player can actually play
 ```
 
-And give players a way out — a visible control that calls `gem.exit()`. A game a player
+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.
 
 ## 6. Play it
@@ -347,8 +350,9 @@ What reaches the frame:
 - **The query only.** A fragment (`#…`) is never forwarded.
 - **Not the arcade's own keys.** These are stripped and never reach the game, and they are the
   only keys the arcade keeps for itself; it never interprets yours:
-  - Store and play-page switches: `play`, `channel`, `purchase`.
-  - Platform switches: `devtools`, `devLocale`, `playOverlay`.
+  - Store and play-page switches: `play`, `channel`, `purchase`, and `build`, which pins one
+    of your own builds when you play it from your Builds page.
+  - Platform switches: `devtools`, `devLocale`.
   - The arcade's own sign-in return marker: `social`.
   - Attribution and campaign keys, which the arcade keeps out of every game: `_s`, `utm_*`
     (every key with that prefix, matched case-sensitively, so UTM_X and utmost are yours),

package/docs/manifest.json

@@ -8,8 +8,8 @@
   "documents": [
     {
       "file": "achievements.md",
-      "sha256": "2bb4790db96a48171826a9cb3ea8e517d9128f07e55b1fd71b072a491021a15b",
-      "updated": "2026-09-28T01:10:05Z"
+      "sha256": "e67bc5d0e6abd9ff842be46fa82bf5117fce74b2eb9d28a3954919ddc8a11c73",
+      "updated": "2026-10-02T23:09:37Z"
     },
     {
       "file": "analytics.md",
@@ -33,8 +33,8 @@
     },
     {
       "file": "changelog.md",
-      "sha256": "02083c9ed1d62baed5a297ca71b602608afa90320afb73a21ff03187da11346f",
-      "updated": "2026-10-02T04:41:46Z"
+      "sha256": "3398bf6f55c503520167dc9cfbee06da7f0552125a4b2050d7e508096c8e256f",
+      "updated": "2026-10-02T21:36:48Z"
     },
     {
       "file": "cross-promotion.md",
@@ -43,8 +43,8 @@
     },
     {
       "file": "daily-challenges.md",
-      "sha256": "7ba296ba3056407ca3c8c9757a3351f3a8062a943335ee52b4ee92e1b2721d3b",
-      "updated": "2026-10-02T18:52:17Z"
+      "sha256": "c198868e2cb1f1b5d9164bb5b1d23bf3f502987e45e10163c8b048a8eba24667",
+      "updated": "2026-10-02T23:01:00Z"
     },
     {
       "file": "dedicated-server-flow.md",
@@ -63,13 +63,13 @@
     },
     {
       "file": "game-economy-tutorial.md",
-      "sha256": "7c94ec70c9e2490bdef23b92743b48409a3c6e22d9f26aff8c09fd86af84eae1",
-      "updated": "2026-10-01T19:42:50Z"
+      "sha256": "08588571cd6529d81bd064f65bc3158997418aeb88ce00ae281735c8b44bff1f",
+      "updated": "2026-10-02T19:05:02Z"
     },
     {
       "file": "getting-started.md",
-      "sha256": "d2179480be49085d828c9afbd89d1d72c00914c5607105831503f0652e521285",
-      "updated": "2026-10-02T21:18:29Z"
+      "sha256": "63a367fdcf79abee6a7978057cb1b7065f0365cd6fa5a895cbd2b18f76d29701",
+      "updated": "2026-10-03T22:38:04Z"
     },
     {
       "file": "inventory-and-catalogs.md",
@@ -118,8 +118,8 @@
     },
     {
       "file": "server-bundles.md",
-      "sha256": "fed144c0d7b9f8be10fc3896a7325ab19aa660441c24038f39bc02b5fdf60cb3",
-      "updated": "2026-10-02T21:18:29Z"
+      "sha256": "419a1587827f494f638f331571a6385f4de080efb062e83656a9d2c50ee3473b",
+      "updated": "2026-10-03T22:38:04Z"
     },
     {
       "file": "serverless-functions-js.md",
@@ -138,8 +138,8 @@
     },
     {
       "file": "what-a-game-must-do.md",
-      "sha256": "d7b66e2c04f5cea169ae4cecd3926e350e272232af32752e60a7a388dfd8c461",
-      "updated": "2026-10-02T21:01:44Z"
+      "sha256": "e5d0e2622077d4e41d1f1786c834e6280356f525146193285d062c4209ac33bd",
+      "updated": "2026-10-03T22:11:20Z"
     }
   ]
 }

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

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

@@ -353,6 +353,33 @@ one refused orientation, in fullscreen, once they are already the right way roun
 That is best effort (iOS does not implement it, and the native app's webview declines
 it), which is why the panel exists and why it always offers a way past.
 
+## An achievement unlock — celebrate it yourself, or declare the Arcade's
+
+By default the Arcade draws no card when a player unlocks one of your game's
+achievements: **the celebration is your game's**, in its own art and sound. If your
+game has no celebration of its own, declare the Arcade's card on your store page
+instead:
+
+```yaml
+unlock_celebration: arcade
+```
+
+`game` is the default, and it is what an absent line means.
+
+- **Opt in when** your game has no unlock celebration of its own, so its players
+  still see their unlocks.
+- **Do not opt in when** your game draws its own. The Arcade's card then lands on top
+  of yours, and the player sees two.
+- **Platform milestones** — the Achievement Score tiers, which belong to no game —
+  always get the Arcade's card, whatever you declare.
+- **Only the store page on `release` is read**, and it takes effect when that page is
+  promoted. It is display-only, and it needs no `schema_version` change.
+- **Gems or Tickets paid in the same moment** still go through `gem.cueReward`, with
+  no flight of your own.
+
+How your game learns an unlock happened, and the field's full rules, are in
+[achievements.md §5](achievements.md#5-celebrating-an-unlock-is-your-games-job).
+
 ## A television, if a player puts you on one
 
 The Arcade runs in TV browsers and on TV hardware, so a game can find itself ten feet from its
@@ -435,7 +462,9 @@ 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 the player taps the Arcade's Back tab, your game is **parked**, not closed:
+  **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
+  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
   ended up to five minutes later. That end usually comes with `onWillTerminate` first, **but not
@@ -542,17 +571,20 @@ the `var()` above, or read `gem.viewport`. The release checklist looks for the b
 
 ### The arcade's own controls: reserved areas
 
-On a phone your game is full-bleed, and the arcade keeps one row of its own across the top of it,
-with the middle left open for a centred camera:
+On a phone your game is full-bleed, and the arcade keeps one cluster of its own over it, in the
+**top-right corner**:
+
+- **The menu button**, in the corner itself, 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 player's wallets** (Gems, Tickets, their achievement score), to the left of it, while your
+  screen [shows them](#the-arcades-wallet-show-it-never-draw-it). When gameplay hides them with
+  `gem.setWalletVisible(false)`, the cluster shrinks to the menu button alone.
 
-- **Top-left: the Back tab** — the Gem Arcade wordmark, always there. **Do not put a back arrow of
-  your own top-left**: it would sit under the arcade's tab, which leaves the game, while yours would
-  mean something else.
-- **Top-right: the player's wallets** (Gems, Tickets, their achievement score) while your screen
-  [shows them](#the-arcades-wallet-show-it-never-draw-it). Put your own settings, pause or menu
-  button top-right **below** them, at `top: var(--gem-reserved-tr-height, …)` — and when gameplay
-  hides the wallets with `gem.setWalletVisible(false)`, that rectangle shrinks to nothing and your
-  button moves up into the corner on its own.
+**The top-left corner is yours.** Put your own back or home button there — the one that moves around
+_inside_ your game, back to your level select or your title screen. **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.
 
 Those rectangles of your frame are **reserved**: keep essential UI and every touch target out of
 them. **Never hard-code their size or height.** They differ by phone, and in native fullscreen the
@@ -575,17 +607,17 @@ from its top-left corner:
 reserved rectangles reach in from its two edges. Push the corner's UI clear of it:
 
 ```css
-/* settings in the top-right corner, below the wallets — and up in the corner when they are hidden */
-#settings {
-  top: max(var(--gem-safe-top, env(safe-area-inset-top, 0px)), var(--gem-reserved-tr-height, 0px));
-  right: var(--gem-safe-right, 0px);
+/* your back button in the top-left corner, which the arcade leaves clear */
+#back {
+  top: var(--gem-safe-top, env(safe-area-inset-top, 0px));
+  left: var(--gem-safe-left, 0px);
 }
-/* a score in the top-left corner, below the tab */
+/* a score in the top-right corner, below the arcade's cluster */
 #score {
-  top: max(var(--gem-safe-top, env(safe-area-inset-top, 0px)), var(--gem-reserved-tl-height, 0px));
-  left: var(--gem-safe-left, 0px);
+  top: max(var(--gem-safe-top, env(safe-area-inset-top, 0px)), var(--gem-reserved-tr-height, 0px));
+  right: var(--gem-safe-right, 0px);
 }
-/* or a row along the top, between the two */
+/* or a row along the top, stopping short of it */
 #top-bar {
   padding-left: var(--gem-reserved-tl-width, 0px);
   padding-right: var(--gem-reserved-tr-width, 0px);
@@ -597,13 +629,15 @@ value; they are never set under an embedder that sends no viewport, which is wha
 fallback is for. A rectangle belongs to the corner its centre lies nearest to. For a HUD laid out
 from script, read `gem.viewport.reserved` — `[]` when nothing is covered.
 
-**Lay out against it whenever it changes.** Shown wallets reserve the top-right corner; hiding them
-shrinks it to nothing, and only the tab's top-left rectangle is left. A wallet the arcade pops up for
-a moment while they are hidden never reserves anything — it floats over your game and moves nothing.
+**Lay out against it whenever it changes.** Shown wallets widen the top-right rectangle; hiding them
+shrinks it to the menu button alone. A wallet the arcade pops up for a moment while they are hidden
+never reserves anything — it floats over your game and moves nothing. Read every corner, not only the
+one this page names today: `--gem-reserved-tl-*` is `0px` now, and a layout that honours it anyway
+is right under any embedder.
 
 **Older SDKs get it folded into the top inset.** A game on an SDK from before reserved areas cannot
 read the rectangles, so the arcade sends it none and instead raises `insets.top` — and so
-`--gem-safe-top` — past the bottom of the tab. That game keeps working, at the cost of a full-width
+`--gem-safe-top` — past the bottom of the cluster. That game keeps working, at the cost of a full-width
 band; upgrading gives the band back.
 
 ## Which store-page experiment brought this player in: cohorts
@@ -695,18 +729,62 @@ 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
+
+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:
+
+```js
+const inArcadeMenu = gem.setMenu({
+  onSettings: () => settingsScreen.open(),
+  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.
+- **`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
+  may shorten it further. A fifth entry is left out.
+- **It is screen state, not a toggle**, like the wallets: each call is the whole answer and replaces
+  the last. Call it again when the language changes or a screen has different options;
+  `gem.setMenu({})` takes everything of yours back out. Before the Arcade connects the menu is held
+  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.
+  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.
+
+**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() });
+```
+
+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:
+leaving is the Arcade's menu, so a player always knows which control does which.
+
 ## Sound: your own mute control, and the Arcade's
 
-**Every game needs its own mute control**, in its settings or its pause menu, because on a phone
-the Arcade shows **no** mute button: your game fills the screen and the Arcade's only control over
-it is the Back tab. A player on a phone who wants silence has your control and nothing else.
+**Every game needs its own mute control**, in its settings screen. The Arcade's menu has a mute
+entry on every device, but a player who opens your settings expects sound to be there too — and
+under an embedder with no menu, yours is the only one there is.
 
 Wire it both ways, so the player has one mute rather than two that disagree:
 
 ```js
 const gem = createGem({
   // ...
-  // The Arcade's mute changed (desktop, tablet, TV): follow it.
+  // The Arcade's mute changed: follow it.
   onPrefs: (prefs) => sound.setMuted(prefs.muted),
 });
 
@@ -726,14 +804,14 @@ sent when the Arcade connects; an embedder with no mute button is simply not tol
 button saying one thing while the game does the other; a game that follows `prefs.muted` but never
 reports leaves the Arcade's button stale after the player uses yours.
 
-### The Arcade's mute button, where there is one
+### The Arcade's mute entry
 
-On a desktop, a tablet and a television the Arcade does keep a mute button beside your game, for
-games whose SDK can honour it — an SDK that silences your game says so when it connects, and a game
-built on an older one gets no button rather than one that does nothing. When the player presses it,
+The Arcade's menu carries a mute entry on every device, for games whose SDK can honour it — an SDK
+that silences your game says so when it connects, and a game built on an older one gets no entry
+rather than one that does nothing. When the player presses it,
 `gem.prefs.muted` arrives as `true` and the SDK silences your page itself — every Web Audio graph and
 every `<audio>`/`<video>` element — then gives the sound back when they press it again. With the two
-calls above, the Arcade's button and yours stay in step whichever the player uses.
+calls above, the Arcade's entry and yours stay in step whichever the player uses.
 
 - **It turns the volume down; it does not stop your clock.** Your `AudioContext` keeps running, so
   anything scheduled against `currentTime` stays in time. Do not answer a mute with `ctx.suspend()` in
@@ -780,8 +858,8 @@ and the release checklist checks that it does.
 
 The player's platform balances — Gems, Tickets (`ARCADE_TICKETS`) and their achievement score —
 belong to the Arcade. **Your game never draws one**, and never shows a pending state for one: the
-Arcade takes every figure from the platform and draws the wallets itself, in the top-right corner
-of your frame on a phone.
+Arcade takes every figure from the platform and draws the wallets itself, beside its menu button in
+the top-right corner of your frame on a phone.
 
 **They are shown unless your game hides them.** A game that does nothing has every wallet on show
 the whole time. The one rule: **hide them during gameplay, show them on your menus.**
@@ -797,10 +875,10 @@ pauseMenu.onOpen = () => gem.setWalletVisible(true);
 - **It is screen state, not a toggle.** Each call is the whole answer and replaces the last. Call it
   as often as you like: before the Arcade connects the state is held and sent when it does, and
   again after any reconnect; a repeat of the current state is not re-sent.
-- **Shown wallets take space; a pop does not.** Shown, they reserve the top-right
-  [corner](#the-arcades-own-controls-reserved-areas), so lay your menu out against
-  `--gem-reserved-tr-*` — your settings button sits below them; hidden, the corner is yours again and
-  the same `var()` moves the button up. A pop floats over your game and never moves its layout.
+- **Shown wallets take space; a pop does not.** Shown, they widen the top-right
+  [reserved area](#the-arcades-own-controls-reserved-areas) beside the menu button, so lay your
+  screen out against `--gem-reserved-tr-*`; hidden, it shrinks back to the button alone. A pop floats
+  over your game and never moves its layout.
 - **Narrowing is optional.** On a screen that sells in one currency — a ticket store — you may show
   only that one: `gem.setWalletVisible(true, { only: ['ARCADE_TICKETS'] })`, with `'score'` for the
   achievement score. Use it only there; leaving it out shows every wallet, which is always safe.

package/package.json

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

package/schema/bridge.v1.json

@@ -893,7 +893,7 @@
         "",
         "AMENDED, DELIBERATELY: this message once carried insets only. It now also",
         "carries `reserved`, rectangles of the frame covered by the parent's own",
-        "controls floating over the game (a Back tab in a corner, the wallet chips",
+        "controls floating over the game (a menu button in a corner, the wallet chips",
         "shown in another). An inset can only describe a full-width or full-height band,",
         "and a corner tab expressed as a top inset would take the whole top strip",
         "from a full-bleed game to clear a control a few dozen pixels wide. A",
@@ -2387,7 +2387,7 @@
         "to it: a reward cue, a pending grant, a landing, a spend, a daily-maximum",
         "note, a score change. The game's state never cancels those. Only wallets",
         "shown BECAUSE OF THIS STATE reserve space: they extend `gem.viewport`'s",
-        "`reserved`, and hiding them shrinks it back to the parent's own Back tab. An",
+        "`reserved`, and hiding them shrinks it back to the parent's own menu button. An",
         "event pop floats over the game and never moves its layout. Where the parent",
         "docks its wallets beside the frame rather than over it, this changes",
         "nothing.",
@@ -2416,6 +2416,108 @@
       "rateLimit": { "perMinute": 60 }
     },
 
+    {
+      "type": "gem.menu",
+      "direction": "frameToParent",
+      "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.",
+        "",
+        "  settings: true   the game has a settings screen and will open it when",
+        "                   told to; the menu gains a Settings entry",
+        "  items            up to four entries of the game's own, in this order,",
+        "                   below the arcade's entries and visibly apart from them",
+        "",
+        "With no message at all, the menu holds the arcade's own entries and",
+        "nothing of the game's. The arcade's entries are the arcade's: a game can",
+        "neither remove nor reorder them, and Return to the Arcade is always there.",
+        "",
+        "SCREEN STATE, NOT A TOGGLE, like `gem.walletDisplay`. Each message is the",
+        "whole answer and the latest one wins; nothing accumulates. The SDK re-sends",
+        "the latest state after every handshake, so a parent that reconnects never",
+        "shows a menu missing what the game had declared.",
+        "",
+        "`id` is the game's own name for an entry and is what comes back in",
+        "`gem.menuSelect`; unique within one message, and the parent keeps the first",
+        "of a repeated id. `label` is what the player reads, ALREADY IN THE PLAYER'S",
+        "LANGUAGE (`gem.prefs.locale`): the parent does not translate it.",
+        "",
+        "A LABEL IS UNTRUSTED TEXT IN THE PARENT'S CHROME. A parent renders it as",
+        "text and never as markup, in the game's group and never among its own",
+        "entries, truncated to fit, and may decline to show an entry at all. A game",
+        "cannot make the menu say something the arcade says: that is what the",
+        "separate group is for.",
+        "",
+        "A PRESENTATION REQUEST ONLY. Not an authorization control; choosing an",
+        "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."
+      ],
+      "fields": {
+        "settings": { "kind": "boolean" },
+        "items": {
+          "kind": "array",
+          "maxItems": 4,
+          "optional": true,
+          "items": {
+            "kind": "object",
+            "fields": {
+              "id": {
+                "kind": "string",
+                "maxLength": 32,
+                "$comment": "The game's own name for the entry, 1..32 characters, echoed in `gem.menuSelect`. The SDK drops an entry whose id is empty or over-long rather than cutting it into a different id."
+              },
+              "label": {
+                "kind": "string",
+                "maxLength": 40,
+                "$comment": "What the player reads, 1..40 characters, already translated. The SDK drops an entry with an empty label and cuts an over-long one."
+              }
+            }
+          }
+        }
+      },
+      "rateLimit": { "perMinute": 60 }
+    },
+
+    {
+      "type": "gem.menuSelect",
+      "direction": "parentToFrame",
+      "transport": "port",
+      "$comment": [
+        "The player chose one of the game's entries in the arcade's menu: its",
+        "Settings entry, or one of the items `gem.menu` declared.",
+        "",
+        "  entry: settings        open your settings screen",
+        "  entry: item, id        the item with this id",
+        "",
+        "Sent only for what the frame's LATEST `gem.menu` declared, and only to a",
+        "frame that advertised `gameMenu`. The parent closes its menu first, so the",
+        "`gem.pause` it sent when the menu opened is lifted before this arrives:",
+        "the game is running, in front, and the next thing on screen is the game's",
+        "own. A frame that hears an id it no longer declares ignores it — the menu",
+        "may have been open across a change.",
+        "",
+        "The arcade's own entries never come through here. Leaving, the mute and",
+        "fullscreen reach the game as they always did (`gem.pause`,",
+        "`gem.willTerminate`, `gem.prefs`), and a problem report reaches it not at",
+        "all."
+      ],
+      "fields": {
+        "entry": { "kind": "enum", "values": ["settings", "item"] },
+        "id": {
+          "kind": "string",
+          "maxLength": 32,
+          "optional": true,
+          "$comment": "Present when `entry` is `item`: the id from `gem.menu`."
+        }
+      },
+      "rateLimit": { "perMinute": 60 }
+    },
+
     {
       "type": "gem.requestShare",
       "direction": "frameToParent",

package/schema/capabilities.public.json

@@ -190,6 +190,13 @@
       "gates": [
         "gem.requestShare"
       ]
+    },
+    "gameMenu": {
+      "implemented": true,
+      "gates": [
+        "gem.menu",
+        "gem.menuSelect"
+      ]
     }
   }
 }