@indiegems/gem-web-sdk 7.8.1 → 7.9.1

package/docs/changelog.md

@@ -16,6 +16,75 @@ 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.
 
+## 7.9.1
+
+Upgrading from 7.9.0. Impact: none.
+
+Nothing in this release asks anything of a game.
+
+## 7.9.0
+
+Upgrading from 7.8.1. Impact: required.
+
+### Must change
+
+- A link your game shares can no longer carry a parameter named build. The Arcade now reads that key for itself and removes it before your game starts, so the share request refuses it with a TypeError that names the key. Rename the parameter if your game shares one by that name.
+
+### Rebuild
+
+- GemCapability gained gameMenu, and the bridge's message lists and unions in both directions gained the two new menu messages. A switch that assumes it knows every GemCapability value must handle the new one. Other code that compiles today keeps compiling.
+
+### New capability
+
+- gem.setMenu adds to the Arcade's menu, the one control the Arcade keeps over a game in its top right corner. Give onSettings and the menu gains a settings entry that opens your own settings screen, and give items for up to four entries of your own, each with an id, a label you have already translated and an onSelect handler. Each call is the whole answer and replaces the last, so call it again when the entries change. It returns true when the Arcade was told. After awaitBridge has settled, draw a settings button of your own only when it returns false. The Arcade pauses your game while its menu is open and resumes it before your handler runs.
+
+## 7.8.1
+
+Upgrading from 7.8.0. Impact: none.
+
+Nothing in this release asks anything of a game.
+
+## 7.8.0
+
+Upgrading from 7.7.0. Impact: recommended.
+
+### May stop
+
+- The SDK now stops accidental text selection, the long-press copy menu and the tap highlight across your game's document, so a game can drop its own rules for that. Your own style rules always win, and inputs, text areas and editable content stay typeable and selectable. Text a player could select and copy before no longer is, unless your own styles make it selectable. Pass selectableText as true to createGem only if your game is mostly text a player should be able to copy.
+
+### New capability
+
+- A room says whether it is self-hosted in selfHosted: its dedicated server runs on the machine of the player who created it, as it does in the Gem editor. The SDK asks for such a room on your behalf where the embedder hosts locally, and there is no option for a game to set. It is false on every room a player in the Arcade is in.
+
+## 7.7.0
+
+Upgrading from 7.6.0. Impact: required.
+
+### Must change
+
+- In the server API types, occurred_at on a leaderboard row and on an entity leaderboard row is now optional and may be null. Code that assumes it is always a number must handle it missing. LeaderboardResponse and EntityLeaderboardResponse are now written as the shared LeaderboardPeriodFields joined with their own fields, so every field they had is still there.
+
+### Rebuild
+
+- Server API unions gained values. OrderSource has earning_reset, and InventoryChange has a new earning_limits_reset change. A switch that assumes it knows every OrderSource value or every InventoryChange type must handle the new one. Other code that compiles today keeps compiling.
+- The server API reads getLeaderboard and getEntityLeaderboard accept three more options, periods_back, period and player_id, and the option types GetLeaderboardOptions and EntityLeaderboardOptions now extend the new PeriodOptions. Code that compiles today keeps compiling.
+
+### New capability
+
+- gem.leaderboards can read a board scoped to one period of a challenge, such as today's board or this week's. Every read takes periodsBack, where 0 is the current period and 1 is the one before, or period, the id of a period from an earlier result. Name at most one of them. A result from such a board carries period, which says which period it is, when it opens and closes, and whether it is final. A serverless function or a dedicated server passes playerId so the board answers for that player's own day. On a board that is not scoped to periods, both selectors are refused rather than ignored.
+
+## 7.6.0
+
+Upgrading from 7.5.0. Impact: required.
+
+### Must change
+
+- createGem now throws GemUnframedError when the page is opened on its own instead of inside a frame. Before, such a game constructed and then waited for a bridge that never came, with no player, no saves and no config. Run your game where it is framed and handed an identity: the Arcade, the Gem editor or the Gem dev host. A game that is only ever played there changes nothing. When the framing page is not one the game allows, the refusal is now final: awaitBridge, awaitIdentity, awaitPlayer and awaitCohorts answer at once instead of timing out.
+
+### New capability
+
+- A serverless function written in JavaScript can use the SDK through a new function entry of the package. createGem there returns the same platform-backed calls a browser game makes, bound to the player who called the function. Nothing is retried, a conditional save is refused before it is sent, and gem.functions and gem.gameConfig throw because a function has neither. This entry is in the package only.
+
 ## 7.5.0
 
 Upgrading from 7.4.2. Impact: required.

package/docs/daily-challenges.md

@@ -246,14 +246,13 @@ you almost certainly do not want to:
 | Storefront marker, My Games  | yes                                           | yes                                      |
 | Rewards, platform grants     | yes                                           | yes                                      |
 | The platform-wide **streak** | yes                                           | **no** — a streak of its own, on your store page |
-| The player's history calendar| yes                                           | no                                       |
 | Label in the arcade          | localised in every language the arcade speaks | generic                                  |
 | Period length                | a day, a week, a month                        | must be between **1 and 31 days**        |
 
 A streak spans games, which only works when every game agrees on what the player's "today" is. A
 custom cron period is yours alone and cannot be compared with anything, so a cron challenge is
 **game-local**: it shows progress, pays and keeps its own streak, and it never joins the
-platform-wide streak or a history.
+platform-wide streak.
 
 **If you wrote `0 0 * * *`, write `daily`.** The upload stores it as `daily` either way — which puts
 it on each player's own calendar, not on UTC midnight. Reach for a custom cron only when the period
@@ -542,10 +541,11 @@ Three things to know before you build a mechanic on it:
 - **One completion is a day.** A player who finishes three of your challenges advances their streak
   once, the same as a player who finishes one. A streak measures days the player showed up, not how
   much a game offered.
-- **A streak is the platform's, and it is shown on platform surfaces.** Your game reports progress
-  and does not read the streak back — see below.
-- **Whether a player's streak is shown at all can depend on who they are.** Some players do not see
-  streak surfaces. Do not design a mechanic whose fairness depends on every player seeing one.
+- **A streak is the platform's.** Your game reports progress and does not read the streak back —
+  see below.
+- **The arcade does not display the platform-wide streak.** The platform counts it, but no arcade
+  surface shows it to the player today. Do not tell players about it, and do not design a mechanic
+  that depends on a player seeing it.
 
 Challenges on a custom cron are game-local: each keeps a streak of its own, shown on your game's
 store page, and none advances the platform-wide one ([section 5a](#5a-use-daily-weekly-or-monthly-avoid-cron-for-a-challenge)).
@@ -576,8 +576,9 @@ counts for the day it was played. [A board for each day](leaderboards.md#a-board
 is the page.
 
 **Their per-period history and their streak — no.** There is no history read and no streak read in
-the SDK. The arcade is what displays those — the marker on your game's card, and the player's own
-progress, history and streak on platform surfaces. Your game does not have to render any of it.
+the SDK, and the arcade has no history calendar either. What the arcade displays is the marker on
+your game's card and the player's progress in the current period — plus, for a cron challenge, its
+own streak on your store page. Your game does not have to render any of it.
 
 ## 11. When an upload is refused
 

package/docs/game-economy-tutorial.md

@@ -209,8 +209,9 @@ the one you attempted, rather than resending the purchase.
 
 Your shop can also sell for the arcade's own currencies, and the platform draws one line through
 them: **Tickets buy cosmetics, Gems buy anything.** Each platform currency has a spend scope — Tickets'
-is `cosmetic_only`, Gems' is `any`. Mark a cosmetic in the
-config, and price it in `ARCADE_TICKETS`:
+is `cosmetic_only`, Gems' is `any`. Which currencies your game may price in, and what each may buy,
+is `gemctl platform config`'s answer. Mark a cosmetic in the config, and price it in
+`ARCADE_TICKETS`:
 
 ```yaml
 items:

package/docs/getting-started.md

@@ -50,7 +50,7 @@ either way.
 ```jsonc
 // package.json
 "dependencies": {
-  "@indiegems/gem-web-sdk": "7.8.1"
+  "@indiegems/gem-web-sdk": "7.9.1"
 }
 ```
 
@@ -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": "3398bf6f55c503520167dc9cfbee06da7f0552125a4b2050d7e508096c8e256f",
-      "updated": "2026-10-02T21:36:48Z"
+      "sha256": "8a2e021addc2980433e722ba6ca2c7f5fa81cb8eac921e0bda28e44e3484d09d",
+      "updated": "2026-10-05T17:22:40Z"
     },
     {
       "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": "3281ee225785781d234a7d0dab275ef6f2af499846c5376737d87aa3f3234fe5",
-      "updated": "2026-10-02T21:43:45Z"
+      "sha256": "3c38e5b14c78b70b107d5e5b5499fa9340975d602642a8eb91f2dd969d1b605b",
+      "updated": "2026-10-05T17:22:40Z"
     },
     {
       "file": "inventory-and-catalogs.md",
@@ -118,8 +118,8 @@
     },
     {
       "file": "server-bundles.md",
-      "sha256": "e85e1d041b12870fac5bb3fa20fab33737749e177e55b831b38fb6c3b6a930ad",
-      "updated": "2026-10-02T21:43:45Z"
+      "sha256": "13f5846ad8ee3d27e83916b8d95b4d3fdfcbeb85f94e095cc0c04e14dc2577b2",
+      "updated": "2026-10-05T17:22:40Z"
     },
     {
       "file": "serverless-functions-js.md",
@@ -138,8 +138,8 @@
     },
     {
       "file": "what-a-game-must-do.md",
-      "sha256": "4bd46c937788cb11aa188c7bb120399ddc7dd89c23fa5ea2955db9dd4e9ea08e",
-      "updated": "2026-10-02T21:36:48Z"
+      "sha256": "f44c1fd73678b1b569c59bc94bb55cfa2bdb957d798f5985ea5b3024865ed4a6",
+      "updated": "2026-10-04T19:51:47Z"
     }
   ]
 }

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

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

@@ -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,66 +571,117 @@ 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 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 player's wallets** (Gems, Tickets, their achievement score), in the **middle of the row**,
+  [always there](#the-arcades-wallet-always-shown-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,
+  and still taps the Arcade takes.
 
-- **Top-left: the Back tab** — the Gem Arcade wordmark, always there.
-- **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 of the screen has one layout, in every game:**
+
+| Where                                        | Whose        | What goes there                                                                                                                                                                                              |
+| -------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **Top-left**                                 | yours        | Your **Home / Back** buttons, drawn when a screen needs them, in the space to the left of the wallets. They move around _inside_ your game — back to your level select or title screen — and never leave it. |
+| **Middle and top-right**                     | the Arcade's | Its wallets and its menu button. Nothing of yours.                                                                                                                                                           |
+| **Centre and right, below the Arcade's row** | yours        | Your **information**: score, moves, a timer, a level name. It starts under the bottom of the Arcade's row, never beside it or under it.                                                                      |
+
+Keep the left for Home / Back even on a screen that has neither today: a player learns where "back"
+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.
+
+**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
+left of the wallets: room for **one** button. Two buttons, or a wide one, go on their own row below
+the Arcade's. Do not copy those numbers — read the space, as below.
 
 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
 whole row may rise into the camera band — read them, as below.
 
-An inset cannot say that — as a top inset, a tab a few dozen pixels wide would take your whole top
+An inset cannot say that — as a top inset, a button a few dozen pixels wide would take your whole top
 strip. So `gem.viewport` also carries the rectangles, in the same CSS pixels of your frame, measured
-from its top-left corner:
+from its top-left corner — one per wallet shown, and one for the menu button:
 
 ```json
 {
   "insets": { "top": 47, "right": 0, "bottom": 34, "left": 0 },
-  "reserved": [{ "x": 8, "y": 51, "width": 104, "height": 34 }]
+  "reserved": [
+    { "x": 68, "y": 51, "width": 72, "height": 28 },
+    { "x": 144, "y": 51, "width": 72, "height": 28 },
+    { "x": 220, "y": 51, "width": 72, "height": 28 },
+    { "x": 304, "y": 51, "width": 48, "height": 48 }
+  ]
 }
 ```
 
 **The SDK turns them into one pair of custom properties per corner**, written beside
 `--gem-safe-*` before anything else hears the push: `--gem-reserved-tl-width` and
 `--gem-reserved-tl-height`, and the same pair for `tr`, `bl` and `br` — how far that corner's
-reserved rectangles reach in from its two edges. Push the corner's UI clear of it:
+reserved rectangles reach in from its two edges. A rectangle belongs to the corner its centre lies
+nearest to.
+
+⚠️ **The wallets sit in the middle, so they count toward BOTH top corners.** A wallet left of
+centre is a top-left rectangle, one right of centre a top-right one. While wallets are shown,
+`--gem-reserved-tl-height` is the bottom of the wallets and `--gem-reserved-tl-width` reaches to the
+middle of the screen — even though the corner itself, left of the first wallet, is clear. So:
 
 ```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));
+/* your information — score, moves, a timer — below the WHOLE of the arcade's row: the taller of
+   the two top corners. It moves up by itself when gameplay hides the wallets. */
+#info {
+  top: max(
+    var(--gem-safe-top, env(safe-area-inset-top, 0px)),
+    var(--gem-reserved-tl-height, 0px),
+    var(--gem-reserved-tr-height, 0px)
+  );
   right: var(--gem-safe-right, 0px);
 }
-/* a score in the top-left corner, below the tab */
-#score {
-  top: max(var(--gem-safe-top, env(safe-area-inset-top, 0px)), var(--gem-reserved-tl-height, 0px));
+/* ONE Home or Back button, level with the arcade's row, in the clear corner to the wallets' left */
+#back {
+  top: var(--gem-safe-top, env(safe-area-inset-top, 0px));
   left: var(--gem-safe-left, 0px);
 }
-/* or a row along the top, between the two */
-#top-bar {
-  padding-left: var(--gem-reserved-tl-width, 0px);
-  padding-right: var(--gem-reserved-tr-width, 0px);
+/* a ROW of your own buttons does not fit beside the wallets: start it below the arcade's row,
+   like your information */
+#nav {
+  top: max(
+    var(--gem-safe-top, env(safe-area-inset-top, 0px)),
+    var(--gem-reserved-tl-height, 0px),
+    var(--gem-reserved-tr-height, 0px)
+  );
 }
 ```
 
-All eight are written on every push, `0px` for a clear corner, so a rotation never leaves a stale
-value; they are never set under an embedder that sends no viewport, which is what the `0px`
-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.
+The per-corner properties cannot say how wide the clear corner is — only that the corner's
+rectangles reach in to the middle. To know whether your button fits beside the wallets, read the
+rectangles from script: the clear width at the top-left is the smallest `x` among
+`gem.viewport.reserved` (the whole width when the list is empty).
+
+```js
+const reserved = gem.viewport?.reserved ?? [];
+const clearLeft = reserved.length ? Math.min(...reserved.map((r) => r.x)) : window.innerWidth;
+nav.classList.toggle('below-arcade-row', clearLeft < nav.offsetWidth + 8);
+```
 
-**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.
+All eight properties are written on every push, `0px` for a clear corner, so a rotation never leaves
+a stale value; they are never set under an embedder that sends no viewport, which is what the `0px`
+fallback is for. `gem.viewport.reserved` is `[]` when nothing is covered.
+
+**Lay out against it whenever it changes.** The wallets' rectangles are there for the whole
+session on the Arcade's phone layout, and their number and width can change as the player's
+balances and currencies do. Read every corner, not only the ones this page names today: a layout that honours
+all four 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 row. 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
@@ -693,18 +773,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),
 });
 
@@ -724,14 +848,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
@@ -774,38 +898,25 @@ its music out than cut it, say. The Arcade still shows its button for your game
 so this is a promise: your `onPrefs` handler must go quiet on `muted: true` and come back on `false`,
 and the release checklist checks that it does.
 
-## The Arcade's wallet: show it, never draw it
+## The Arcade's wallet: always shown, never drawn
 
 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.
-
-**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.**
-
-```js
-level.onStart = () => gem.setWalletVisible(false);
-pauseMenu.onOpen = () => gem.setWalletVisible(true);
-```
-
-- **While hidden, the Arcade still pops a wallet up** for a moment when something happens to it —
-  a reward you cued with `gem.cueReward`, a spend, a landing, a daily-maximum note, a score change
-  — then hides it again. Your state never cancels that, so a reward mid-level still shows.
-- **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.
-- **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.
-- **Where the Arcade docks its wallets beside your frame** — a desktop page — they are always on
-  show, and this changes nothing. Call it anyway; the same code is right everywhere.
-- **`false` means nobody is listening** — no connection yet, or an embedder that draws no wallet.
-  Do nothing in its place.
+Arcade takes every figure from the platform and draws the wallets itself, in the middle of the row
+across the top of your frame on a phone, with its menu button at the right end.
+
+**The Arcade shows every wallet the whole time, during play too** (since 2026-10-04). They are
+small, translucent chips in the middle of the top row, and they are
+[reserved rectangles](#the-arcades-own-controls-reserved-areas): lay every screen out below both
+`--gem-reserved-tl-height` and `--gem-reserved-tr-height`, gameplay included. There is nothing for
+your game to call.
+
+⚠️ **`gem.setWalletVisible` no longer hides anything in the Arcade.** It was how a game hid the
+wallets for gameplay and showed them on its menus, and narrowed them to one currency on a store
+screen. The Arcade still accepts the call — it returns `true`, and existing games need no change —
+but the wallets stay up whatever it is told. **Do not design a screen around the top row being
+clear during play**: it is not. Another embedder may still honour the call, so leaving it in is
+harmless; new code does not need it.
 
 ## No accidental text selection
 

package/package.json

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