@indiegems/gem-web-sdk 16.2.0 → 16.3.1

package/docs/arcade-and-store.md

@@ -21,8 +21,8 @@ async function onBuyPressed(offer) {
 ```
 
 **Your game asks; the Arcade decides.** Nothing your game sends carries a URL, a price or a card
-field. The Arcade builds every link, reads every price, draws every purchase sheet and takes the
-payment itself. You get an outcome.
+field. The Arcade builds every link, reads every price, opens every checkout and takes the payment
+itself. You get an outcome.
 
 - [1. Two surfaces, and which one is real money](#1-two-surfaces-and-which-one-is-real-money)
 - [2. Nothing rejects](#2-nothing-rejects)
@@ -37,11 +37,11 @@ payment itself. You get an outcome.
 
 ## 1. Two surfaces, and which one is real money
 
-|              | **`gem.arcade`**                                 | **`gem.store`**                                 |
-| ------------ | ------------------------------------------------ | ----------------------------------------------- |
-| What it does | app-store listings, another game, similar games  | the Arcade Store's own SKUs                     |
-| Money        | none                                             | **real money**, through the Arcade's own sheet  |
-| Who draws it | the Arcade (a new tab, a QR code, the next game) | the Arcade Store's sheet, over your paused game |
+|              | **`gem.arcade`**                                 | **`gem.store`**                                     |
+| ------------ | ------------------------------------------------ | --------------------------------------------------- |
+| What it does | app-store listings, another game, similar games  | the Arcade Store's own SKUs                         |
+| Money        | none                                             | **real money**, through the Arcade Store's checkout |
+| Who draws it | the Arcade (a new tab, a QR code, the next game) | the checkout, over your paused and hidden game      |
 
 `gem.store` is not `gem.purchases`. **`gem.purchases` spends Gems or Coins on your game's own
 items** ([`inventory-and-catalogs.md`](inventory-and-catalogs.md)). **`gem.store` sells the Arcade
@@ -194,6 +194,12 @@ talks to the Arcade: `gemctl serve` and the Project Editor too, when they are si
 **Name each host exactly. Never allow `https://*.blob.core.windows.net`**: that wildcard is every
 Azure customer's storage, not the Arcade's.
 
+**The platform's branding** (the logo, the wordmark and the currency marks `gem.branding` hands
+you) is served from `https://gemarcade.com`, in every environment. Allow it in `connect-src`, for
+the branding manifest, and in each kind's own directive for the files you draw: `img-src` for
+images, `media-src` for audio, `font-src` for fonts
+([branding.md](branding.md#5-your-pages-content-security-policy)).
+
 A non-production backend serves its art from hosts of its own. These hosts are infrastructure, and
 they can change: art that will not load is the sign, and the browser's console names the host your
 policy refused. Allow that host rather than a wildcard.
@@ -215,7 +221,7 @@ Gem pack, a `grant` naming the currency and amount.
   currency, already formatted. Never parse it, compare two of them, or compute a discount from it.
   There is no numeric price.
 - **Re-read offers when your game resumes.** What is on sale can change while the player is away.
-- **Do not imitate the Arcade's chrome.** Your offer list is yours to style; the sheet that takes
+- **Do not imitate the Arcade's chrome.** Your offer list is yours to style; the checkout that takes
   the money is the Arcade's, and a game that draws something that looks like it confuses players
   about which one is real.
 - `unavailable` / `store_off` means the store is not offered here (a TV, an in-app browser that
@@ -228,12 +234,15 @@ Gem pack, a `grant` naming the currency and amount.
 const { outcome, reason } = await gem.store.purchase(offer.skuId);
 ```
 
-`purchase(skuId)` asks the Arcade to open its store's sheet for one SKU from `offers()`. The Arcade
-pauses your game, shows the offer with its own price, and takes the payment on the provider's page
-or the operating system's purchase sheet. Your game is resumed before the answer arrives, so your
-own celebration is visible.
+`purchase(skuId)` asks the Arcade to open checkout for one SKU from `offers()`. The Arcade pauses
+and hides your game and opens checkout **straight away**, with no confirmation screen of its own
+first: the payment provider's page on the web, the app store's own purchase sheet in the Arcade's
+apps. That checkout is where the player confirms and pays. Your game is resumed before the answer
+arrives, so your own celebration is visible.
 
-- **Call it from the press** ([§4](#4-call-the-acting-ones-from-a-press)).
+- **Call it from the press** ([§4](#4-call-the-acting-ones-from-a-press)). The player's press on
+  your Buy button is what opens checkout, so make that button say plainly what it buys and for how
+  much (`priceDisplay`).
 - **It has no timeout.** A payment takes as long as it takes, so the call waits for as long as the
   Arcade is connected.
 - `ok`: the player paid. **Read balances and inventory through `gem.me`**; the answer carries no
@@ -246,14 +255,16 @@ own celebration is visible.
   const stop = gem.store.onSettled(({ skuId }) => refreshBalances());
   ```
 
-- `declined` / `cancelled`: the player closed the sheet. Return to your screen quietly and **do not
-  ask again unprompted**: the Arcade backs off after a dismissal, and the next ask is
-  `declined` / `busy` for a while.
+- `declined` / `cancelled`: the player closed the checkout without paying. Return to your screen
+  quietly and **do not ask again unprompted**: the Arcade backs off after the player closes one, and
+  the next ask is `declined` / `busy` for a while, longer each time. An offer the player cannot buy
+  again yet also answers `declined` / `cancelled`: the Arcade tells the player when it can be
+  bought, opens nothing, and does not back off.
 - `unavailable` with `store_off`, `sign_in_required` or `not_found` (a SKU that is not in
   `offers()` right now), or with a payment provider's own failure code: nothing was bought. The
   first three show nothing.
 - `unavailable` / `error`: **the outcome is unknown, and the player may have paid.** You get it
-  when the bridge to the Arcade closes while the sheet is open, which can happen after the payment
+  when the bridge to the Arcade closes while checkout is open, which can happen after the payment
   went through, and when the Arcade has no reliable answer. Never tell the player nothing was
   bought. Re-read balances and inventory through `gem.me`, keep your `gem.store.onSettled`
   listener, and re-read again when your game resumes:

package/docs/arcade-economy.md

@@ -205,9 +205,9 @@ Nothing sells Coins or achievement points, alone or in a bundle. The arcade's ow
 Gems, and the Gems a player bought there spend in your game exactly as the ones they earned do: your
 game cannot tell the two apart and prices nothing differently for either. Your game never sells
 either itself. It may put the arcade store's own Gem packs and Boosts in front of a player from a
-button of its own, through `gem.store`, and the arcade prices them, shows its own sheet and takes
-the money ([arcade-and-store.md](arcade-and-store.md)). The real-money product that changes what
-your game pays is a **Boost**, which a player always buys on the arcade's own sheet:
+button of its own, through `gem.store`, and the arcade prices them, opens its own checkout and
+takes the money ([arcade-and-store.md](arcade-and-store.md)). The real-money product that changes
+what your game pays is a **Boost**, which a player always buys in the arcade's own checkout:
 
 - **It multiplies what Gems and Coins grants pay, and the ceilings with them.** A player on a 2×
   Boost earns twice as much per grant, may earn twice as much per window and per day, and may hold
@@ -247,7 +247,7 @@ animates every payout into the right total. Gems and Coins follow the same rules
   wallet top-up, or anything shaped like the arcade's purchase sheet: a game screen that looks like
   platform payment chrome is an imitation of it, and players cannot tell the two apart. Your shop's
   own Buy button is yours, and so is a "Get Gems" button that calls `gem.store.purchase` from the
-  player's press: the sheet it opens is the arcade store's own
+  player's press: the checkout it opens is the arcade store's own
   ([arcade-and-store.md](arcade-and-store.md)). When a purchase is refused for
   `insufficient_funds`, say so in your shop's own words ("Not enough Coins") and stop there: a
   refusal never opens the store by itself.

package/docs/brand-art.md

@@ -5,6 +5,13 @@ The SDK ships the platform's own art for its two currencies, **Gems** and **Coin
 §1 before you pick a file: each currency has two kinds of art, and which one you use depends on what
 the screen is for.
 
+> **Draw the platform's current marks with `gem.branding`, and keep these files as the fallback.**
+> `gem.branding.currencyMark('GEMS', { size: 20 })` and `gem.branding.trophy()` hand you the same
+> renders, served by the platform, so a changed mark reaches your game with no SDK update and no
+> republish ([branding.md](branding.md)). The files in this package are the marks as they were when
+> this SDK version was released: draw them only when a lookup answers `unavailable`. Every size,
+> role and rule on this page applies to both.
+
 **Currency display belongs to the arcade.** The arcade draws the player's Gems and Coins totals in
 its own chrome while your game runs, and it animates every payout of either into its total. Your game
 draws Gems or Coins only in the three places §5 allows — an amount on offer or just paid, a reward
@@ -142,6 +149,9 @@ and the art softens as it is stretched. Below 64 px, use the icon (§2).
 
 ## 4. Loading and drawing the art
 
+The platform serves every one of these files through `gem.branding` ([branding.md](branding.md)),
+which is what to draw first. The copies below are the fallback for when it answers `unavailable`.
+
 All of it is in the package you already install, under `brand/`, and published beside it on the CDN —
 the same bytes either way, for the version you are on.
 
@@ -264,9 +274,10 @@ The CDN lets any origin read these files, so a canvas or a WebGL texture can use
 path never changes once published, so a URL you ship keeps working, and `artifact-manifest.json` in
 the same version folder lists each file's `sha384` hash under `brand`.
 
-**Prefer copying the file into your build over loading it by URL at play time.** A load at play time
-is one more request that can be slow or fail, and your screen then shows a gap where the art should
-be. If you do load it live, lay the screen out so it reads correctly without the image.
+**Prefer `gem.branding` over a fixed URL here.** A URL in this folder is the art of the version you
+pinned, forever; the platform's is the art as it is now. Either way, a load at play time can be slow
+or fail, so lay the screen out so it reads correctly without the image, and keep a bundled copy for
+`unavailable`.
 
 ### The platform currency's `icon_url`
 
@@ -285,7 +296,9 @@ decision of that date); the ruling's other rules are unchanged. In rules:
 
 - **Keep no Gems counter.** Your game shows no Gems balance, running total or wallet of its own, on
   any screen. The arcade's wallet is the only place Gems accrue, and the only place a total is shown
-  — in the Gem Arcade, the Gem menu, which the player opens from the Gem button.
+  — in the Gem Arcade, the Gem menu, which the player opens from the Gem button, and beside the Gem
+  for a game that asks the arcade to draw it there (`gem.setWalletVisible(true)`,
+  [the Arcade's wallet](what-a-game-must-do.md#the-arcades-wallet-in-the-gem-menu-and-beside-the-gem-when-you-ask)).
 - **Draw no Gems flight or celebration of your own.** No particles flying to a corner, no counting-up
   number, no burst of gems. `gem.cueReward` is the animation, and the arcade draws it.
 - **Show no Gems amount at all when you are not connected to the arcade.** Without the arcade there is

package/docs/branding.md

@@ -0,0 +1,160 @@
+# The platform's branding: the logo, the wordmark and the platform marks
+
+Show the Indie Gems logo on your main menu, the Gem Arcade wordmark on a credits screen, or the Gems
+mark beside a price, with the files **the platform serves now**. `gem.branding` reads them from the
+platform's branding manifest, so when a mark changes, your game draws the new one on its next
+session. You do not update the SDK or republish.
+
+```js
+const logo = await gem.branding.logo();
+if (logo.outcome === 'ok') {
+  menuLogo.src = logo.url;
+} else {
+  menuLogo.hidden = true; // the platform's branding could not be read: draw no logo
+}
+```
+
+- [1. What you can ask for](#1-what-you-can-ask-for)
+- [2. What a lookup answers](#2-what-a-lookup-answers)
+- [3. Picking a file](#3-picking-a-file)
+- [4. When the manifest cannot be read: the bundled copy](#4-when-the-manifest-cannot-be-read-the-bundled-copy)
+- [5. Your page's Content-Security-Policy](#5-your-pages-content-security-policy)
+- [6. Using the logo and the wordmark](#6-using-the-logo-and-the-wordmark)
+
+## 1. What you can ask for
+
+| Call                                          | Asset id       | What it is                                                                                          |
+| --------------------------------------------- | -------------- | --------------------------------------------------------------------------------------------------- |
+| `gem.branding.logo()`                         | `gem-logo`     | The Indie Gems logo, the brand gem. Scalable (SVG).                                                 |
+| `gem.branding.wordmark()`                     | `gem-wordmark` | The Gem Arcade wordmark, 336 and 672 px wide.                                                       |
+| `gem.branding.currencyMark('GEMS')`           | `gems-mark`    | The Gems mark: the 20 and 32 CSS px icons at 1, 1.5, 2 and 3x, and hero renders 128 to 768 px wide. |
+| `gem.branding.currencyMark('ARCADE_TICKETS')` | `ticket-mark`  | The Coins mark, in the same sizes.                                                                  |
+| `gem.branding.trophy()`                       | `trophy-mark`  | The trophy: 20, 28, 56 and 72 CSS px renders and hero renders 128 to 768 px wide.                   |
+
+**Any asset, by id and kind:** `gem.branding.get(id, { kind })`. The named calls are `get` with the
+id filled in. When the platform adds an asset (another image, a sound, a font), you reach it with
+`get` from the SDK you already have:
+
+```js
+// 'arcade-sting' is an example of an id the platform could add; today it answers not_found.
+const sting = await gem.branding.get('arcade-sting', { kind: 'audio' });
+if (sting.outcome === 'ok') new Audio(sting.url).play();
+```
+
+`gem.branding.list()` resolves every asset the platform serves today, each with its `id`, `kind`
+and every file (`variants`). Compare `kind` rather than switching on every value: kinds other than
+`image`, `audio` and `font` may appear.
+
+The currency marks follow the rules in [brand-art.md](brand-art.md): **the icon** (`size: 20` or
+`32`) beside an amount, **the hero** (no size, or a size of 64 CSS px or more) on a reward screen,
+and never a balance of your own.
+
+## 2. What a lookup answers
+
+Every call resolves. None rejects, except for an argument that is not one: an empty id, a `size`
+or `density` that is not a positive number, a `theme` other than `'light'` or `'dark'`, or a
+currency other than `'GEMS'` or `'ARCADE_TICKETS'`.
+
+| `outcome`     | Means                                                                                                             | Do                                       |
+| ------------- | ----------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
+| `ok`          | The platform has it. `url` is the file picked for you, `variant` describes it, and `asset` holds every file.      | Draw `url`.                              |
+| `not_found`   | The manifest was read, and has no asset with that id and kind, or none in the theme you asked for.                | Draw nothing for it.                     |
+| `unavailable` | The manifest could not be read: the player is offline, the request failed, or your page's policy refused it (§5). | Draw your bundled copy (§4), or nothing. |
+
+An id or a kind the SDK does not know is `not_found`, never an error, so a newer platform cannot
+break an older game.
+
+**Every URL is on the platform's own host**, absolute, and content-hashed: a changed mark is a new
+URL. Use it as it is in an `<img src>`, a CSS `background-image` or a texture loader. Look it up
+each session; do not store one in a save or your build.
+
+The SDK reads the manifest once, on your first `gem.branding` call, and every later call shares
+that read. A game that never calls it makes no request. If the read fails, calls answer
+`unavailable` for a minute, then the next call tries again. Call `gem.branding.list()` during
+start-up to have it ready before your menu draws.
+
+## 3. Picking a file
+
+Pass the box you draw in, in CSS px, as `size`. The SDK picks:
+
+1. the file **made for that box**, at the nearest density at or above the screen's
+   `devicePixelRatio` (else the densest there is);
+2. else a **scalable** file (the logo's SVG);
+3. else the **narrowest** file at least `size × density` pixels wide, else the widest.
+
+With no `size`, you get the scalable file, or else the widest. Pass `density` to override the
+screen's ratio, for example `density: 3` for a canvas or a texture you scale down yourself. Pass
+`theme: 'light'` or `'dark'` to prefer a file drawn for that theme; files for the other theme are
+never picked, and a file rendered for your exact `size` still beats one drawn for your theme at
+another size. Every file today serves both.
+
+```js
+// A 20 CSS px Gems icon in an <img>, with every density for the browser to choose from.
+const gems = await gem.branding.currencyMark('GEMS', { size: 20 });
+if (gems.outcome === 'ok') {
+  const files = gems.asset.variants.filter((v) => v.size === 20);
+  icon.src = gems.url;
+  icon.srcset = files.map((v) => `${v.url} ${v.width}w`).join(', ');
+  icon.sizes = '20px';
+}
+```
+
+```js
+// The wordmark on a canvas or a WebGL texture: the platform's host allows any origin to read it.
+const wordmark = await gem.branding.wordmark({ size: 168, density: 3 });
+if (wordmark.outcome === 'ok') {
+  const img = new Image();
+  img.crossOrigin = 'anonymous'; // before src, or the canvas is tainted
+  img.src = wordmark.url;
+  await img.decode();
+  ctx.drawImage(img, x, y, 168, 88);
+}
+```
+
+## 4. When the manifest cannot be read: the bundled copy
+
+The SDK package still ships the Gems, Coins and trophy marks under `brand/`
+([brand-art.md](brand-art.md) §4). **They are the fallback for `unavailable`**, not the art to draw
+first: a file bundled in your build is the mark as it was when you built, and the platform's is the
+mark as it is now.
+
+```js
+import gemsIcon from '@indiegems/gem-web-sdk/brand/gem-icon-20-2x.png';
+
+const gems = await gem.branding.currencyMark('GEMS', { size: 20 });
+if (gems.outcome === 'ok') icon.src = gems.url;
+else if (gems.outcome === 'unavailable') icon.src = gemsIcon; // the platform could not be reached
+```
+
+There is no bundled logo or wordmark. When `logo()` or `wordmark()` is `unavailable`, lay the screen
+out so it reads correctly without it.
+
+## 5. Your page's Content-Security-Policy
+
+The platform does not restrict what your game fetches. If your own page sets a
+Content-Security-Policy (a `<meta>` tag in your `index.html`), allow `https://gemarcade.com`,
+where the manifest and every file it lists are served:
+
+- in **`connect-src`**, for the manifest. Without it every lookup is `unavailable`, and the SDK says
+  so once on the console;
+- in each kind's own directive for the files you draw: **`img-src`** for images, **`media-src`**
+  for audio, **`font-src`** for fonts.
+
+[arcade-and-store.md](arcade-and-store.md#the-media-hosts) lists the hosts the Arcade's card art comes
+from, beside this one.
+
+## 6. Using the logo and the wordmark
+
+- **Draw them as served:** never recoloured, stretched, rotated, cropped, outlined or given effects,
+  and never rebuilt from another font or file.
+- **Keep clear space** around each, at least a quarter of its height, free of text, buttons and
+  other art.
+- **Not smaller than the Arcade draws them:** the wordmark 60 CSS px wide, the gem logo 32 CSS px.
+  Below that the gem's facets blur together.
+- **On a busy background,** put them on a plain panel rather than over art.
+- **The wordmark is the product's name written as a logo.** Never set "Gem Arcade" in a text face
+  beside the gem in its place.
+- **The currency marks stand for the platform's currencies only:** the Gems mark beside a Gems
+  amount, never for your own currency ([brand-art.md](brand-art.md) §5).
+- **Never inside a panel dressed as the Arcade's own screens.** A player must always be able to tell
+  your game from the platform.

package/docs/changelog.md

@@ -16,6 +16,20 @@ 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.
 
+## 16.3.1
+
+Upgrading from 16.3.0. Impact: none.
+
+Nothing in this release asks anything of a game.
+
+## 16.3.0
+
+Upgrading from 16.2.0. Impact: none.
+
+### New capability
+
+- Games can now read the platform's branding manifest at run time through Gem.branding. A game can show the platform logo, the Arcade wordmark, the currency marks and the trophy, and a branding change on the platform reaches the game with no SDK update or republish. The manifest is read once on the first call and all callers share that read. A lookup by id and kind resolves to one of three outcomes: ok, with the URL, the chosen variant and the whole asset; not_found, when the manifest does not list that id or kind; or unavailable, when the manifest could not be read. In the unavailable case, draw your bundled brand copy instead. Only a bad argument rejects. A list call resolves every asset. You can pass the size you will draw and an optional theme, and the SDK picks the best-matching variant. Nothing is required of existing games.
+
 ## 16.2.0
 
 Upgrading from 16.1.0. Impact: required.

package/docs/getting-started.md

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

package/docs/inventory-and-catalogs.md

@@ -828,7 +828,7 @@ inventory, never on a reason, and do not retry because of one.
 that looks like the arcade's purchase sheet or wallet. A game screen shaped like platform payment
 chrome is an imitation of it. Your Buy button is yours, and taking a player's money is the
 arcade's alone: a "Get Gems" button of yours calls `gem.store.purchase` from the player's press,
-and the arcade store's own sheet does the rest ([arcade-and-store.md](arcade-and-store.md)). An
+and the arcade store's own checkout does the rest ([arcade-and-store.md](arcade-and-store.md)). An
 `insufficient_funds` refusal never opens it by itself.
 
 ### What Coins and Gems may buy: the spend scope
@@ -926,8 +926,9 @@ buyButton.disabled = !gems || gems.balance < price; // can the player afford it?
 ```
 
 **Read it to decide, never to display.** Platform-currency display belongs to the arcade: its
-wallet — the Gem menu, in the Gem Arcade — shows the player's Gems and Coins totals while your
-game runs, and your game keeps no
+wallet — the Gem menu, in the Gem Arcade, and beside the Gem for a game that asks with
+`gem.setWalletVisible(true)` ([the Arcade's wallet](what-a-game-must-do.md#the-arcades-wallet-in-the-gem-menu-and-beside-the-gem-when-you-ask))
+— shows the player's Gems and Coins totals while your game runs, and your game keeps no
 counter, balance or wallet total of either of its own ([brand-art.md](brand-art.md) §5). Use the
 balance to enable a purchase or to say "not enough Gems" — not to draw a number.
 

package/docs/manifest.json

@@ -18,8 +18,8 @@
     },
     {
       "file": "arcade-and-store.md",
-      "sha256": "35d71f81775c0e7b05c84626bbe8365b624a60fb751abe2a2b3126ba554f33ab",
-      "updated": "2026-10-28T21:07:26Z"
+      "sha256": "e055b2b1ec540da9fae8f41c025de99b0faec29cef8fca35285ee34e23120941",
+      "updated": "2026-10-29T23:35:13Z"
     },
     {
       "file": "arcade-avatars.md",
@@ -28,8 +28,8 @@
     },
     {
       "file": "arcade-economy.md",
-      "sha256": "aca343bf98c0e111bca7d27f504bf71b43802b98e5cd649792dfd7c5f30b1b16",
-      "updated": "2026-10-28T18:37:42Z"
+      "sha256": "f0bdc98d765fa4794090fc035d2c32d9c125cbdae58ba89fb5e76fcf1fb9da94",
+      "updated": "2026-10-29T23:35:13Z"
     },
     {
       "file": "async-opponents.md",
@@ -38,13 +38,18 @@
     },
     {
       "file": "brand-art.md",
-      "sha256": "6d51ae596f6b43fb79058412ab8b10922829dd4e37631ca42f9063d5f43b5029",
-      "updated": "2026-10-25T16:18:07Z"
+      "sha256": "b7f8dda1afdb8d56cadee752e6b09fc62238372b68ebc8a746518e528f52e167",
+      "updated": "2026-10-29T21:40:17Z"
+    },
+    {
+      "file": "branding.md",
+      "sha256": "f22bd82245e6c4a74025884bfda54e35405e990661c84e5857d5e424e182e61d",
+      "updated": "2026-10-29T20:56:53Z"
     },
     {
       "file": "changelog.md",
-      "sha256": "b2791239b695b7830c97ccb7ef1370c317b92070a9a3f17d8488d02d78965094",
-      "updated": "2026-10-29T20:57:56Z"
+      "sha256": "e66efedcc9662bea610d3d4edc4e0125f3078e2b49059770f4553d57f37368b3",
+      "updated": "2026-10-29T23:50:25Z"
     },
     {
       "file": "daily-challenges.md",
@@ -73,13 +78,13 @@
     },
     {
       "file": "getting-started.md",
-      "sha256": "0699d1d9283ec251416a8068a6d1dfa050d795c58c55656cc5ce83f98e5bf132",
-      "updated": "2026-10-29T20:57:56Z"
+      "sha256": "5f6b7c1e3763cb647379ccc96fc8eb4e5f22551f60cfe56bc6a957312f431fe3",
+      "updated": "2026-10-29T23:50:25Z"
     },
     {
       "file": "inventory-and-catalogs.md",
-      "sha256": "e7bf9f38bf4ede778fdaca200186b782870f409949743e4e85f22f9c919cd19c",
-      "updated": "2026-10-28T18:37:42Z"
+      "sha256": "032b911f515a7c81b0bcee6065300049651fef8b2108e7930e1d1354eada7a87",
+      "updated": "2026-10-29T23:35:13Z"
     },
     {
       "file": "leaderboards.md",
@@ -133,8 +138,8 @@
     },
     {
       "file": "server-bundles.md",
-      "sha256": "3d628942136f6dbf2dc0dd25a825f4520fe9b54ffc88a62e2d9fed11039a5151",
-      "updated": "2026-10-29T20:57:56Z"
+      "sha256": "387d213d3770f21dccb32c94aac57b5af32bcac8bbe5ca9a6c3c2d8d51e5a2a2",
+      "updated": "2026-10-29T23:50:25Z"
     },
     {
       "file": "serverless-functions-js.md",
@@ -158,8 +163,8 @@
     },
     {
       "file": "what-a-game-must-do.md",
-      "sha256": "e020dca72e597dae0bfa1a71e3263dbb3234f9515d464944e66d7f89612f8db1",
-      "updated": "2026-10-28T00:47:43Z"
+      "sha256": "9d6f2121306bfee8b886d9555a644faa843d16f0c5200e257698336d747136b1",
+      "updated": "2026-10-29T21:40:17Z"
     }
   ]
 }

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/v16.2.0/gem-web-sdk.tgz
-curl -fsSL https://downloads.gemarcade.com/sdk/v16.2.0/gem-web-sdk.tgz.sri
+curl -fsSL -O https://downloads.gemarcade.com/sdk/v16.3.1/gem-web-sdk.tgz
+curl -fsSL https://downloads.gemarcade.com/sdk/v16.3.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

@@ -783,11 +783,13 @@ game, a framed or full-window game on a desktop, a tablet or a TV in native full
   opens [the Arcade's menu](#the-arcades-menu): Leave game, the player's Gems, Coins and
   achievement score, mute, the player's Arcade-wide settings and the rest. Not your settings: those
   are [your own button](#game-settings).
-- **Nothing else.** The player's wallets (Gems, Coins, their achievement score) are **not** drawn
-  over your game: the player opens the Gem menu to see them, and every platform-currency payout
-  flies into the Gem button ([the Arcade's wallet](#the-arcades-wallet-in-the-gem-menu-never-drawn-by-you)).
-  When the player switches the frame-rate readout on, it sits beside the gem and is reserved the
-  same way.
+- **Nothing else, unless you ask.** The player's wallets (Gems, Coins, their achievement score) are
+  **not** drawn over a game that says nothing: the player opens the Gem menu to see them, and every
+  platform-currency payout flies into the Gem button. A game that wants them on screen asks with
+  `gem.setWalletVisible(true)`, and the Arcade draws them beside the Gem
+  ([the Arcade's wallet](#the-arcades-wallet-in-the-gem-menu-and-beside-the-gem-when-you-ask)).
+  When the player switches the frame-rate readout on, it sits beside the gem; the readout and any
+  wallets you asked for are reserved the same way as the Gem.
 
 ### The top of the screen
 
@@ -809,7 +811,10 @@ where "back" and "settings" are once, across every game:
   SDK gives you as `--gem-reserved-tl-center-y` (below), never on the middle of its reserved area.
 - **Your settings button is there on every screen.** It goes top-right even where no Arcade control
   is: another embedder may keep one in that corner, so place it from the reserved areas below and it
-  moves aside for whatever is there.
+  moves aside for whatever is there. Inside the Gem Arcade you may leave it out, on every screen
+  at once, when the Arcade's menu reaches everything it did
+  ([a game whose menu rows replace its button](#leaving-your-settings-button-out-inside-the-arcade));
+  Back then takes the end of the row.
 
 The parts of your frame under the Gem and any other Arcade control are **reserved**: keep
 essential UI and every touch target out of them. **Never hard-code their size or position.** They
@@ -1071,11 +1076,16 @@ This is the whole model, and every other page that mentions settings links here:
   them ([the Arcade's Music and Sound switches](#the-arcades-music-and-sound-switches-onaudiochannels)).
 - **Every game draws its own settings button, top-right ([the top of the
   screen](#the-top-of-the-screen)), and its own settings screen.** The Arcade's menu never opens it.
+  Inside the Gem Arcade the button may go when the Arcade's menu holds every setting and action of
+  your screen ([below](#leaving-your-settings-button-out-inside-the-arcade)); the screen stays,
+  for every other embedder.
 - **A game should also declare its settings — all of them, up to eight — to the Arcade's menu**,
   with `gem.settings.declare`: the Arcade's Settings screen lists every one, and the first
   colour-help toggle fills the Color slot of its fixed quick row (the first music toggle fills Music
   for a game that does not pass `onAudioChannels`). It is a second way
-  to reach them, never the only one, and never a second mute or vibration switch ([mirror your
+  to reach them — the only one only where a game
+  [leaves its button out inside the Arcade](#leaving-your-settings-button-out-inside-the-arcade) —
+  and never a second mute or vibration switch ([mirror your
   settings into the Arcade's menu](#mirror-your-settings-into-the-arcades-menu-gemsettings)).
 - **A setting starts from `recommended` until the player changes it in your game, and then the
   player's choice in your game wins.** Save only what the player chose, never a recommended value.
@@ -1222,11 +1232,41 @@ player's Arcade-wide ones, in two places:
   slot that nothing fills stays in its place, greyed and inert. Nothing else of yours reaches the
   quick row.
 
-**It is a mirror, never a replacement: keep your own settings button and screen**, with every
-setting you declare on it too. An embedder that draws no game settings shows none of this, and the
-Arcade may leave an entry out when it is short of room — your own screen is what remains. A game
-that dropped its button because the Arcade's menu had its settings would have settings nobody can
-reach.
+**It is a mirror of your own screen: keep that screen**, with every setting you declare on it too.
+An embedder that draws no game settings shows none of this — your own screen is what remains there.
+Your own button stays too, except inside the Gem Arcade under the conditions in the next section:
+a game that dropped its button anywhere else, or while a setting was missing from the menu, would
+have settings nobody can reach.
+
+#### Leaving your settings button out inside the Arcade
+
+A game may leave its own settings button out inside the Gem Arcade (the owner, 2026-10-29), when
+the Arcade's menu reaches everything the button did:
+
+- **Every toggle, slider and choice on your settings screen is declared** with
+  `gem.settings.declare`, so the screen has eight of them at most.
+- **Your mute and vibration are the quick row's**, wired both ways as
+  [Sound](#sound-your-own-mute-control-and-the-arcades) says.
+- **Every action on the screen is one of your own menu rows** — Replay the tutorial, How to play,
+  Credits — with [`gem.setMenu({ items })`](#the-arcades-menu), so four at most.
+
+Anything more (a ninth setting, a text field, a key-binding screen) keeps the button. **Hide it only
+while `gem.setMenu` returns `true`**: that is an Arcade that has connected and draws a menu. It
+returns `false` before the bridge is up, under an embedder with no menu and in a plain tab, and
+there the button stays, with a way out of your own where there is no menu. Ask again when the frame
+connects (`onStateChange` in `createGem`) and when the language changes, since your rows carry
+your words. Hide it on every screen alike, never on some, and let Back take the end of the top row.
+
+```js
+let arcadeMenu = false;
+function offerMenu() {
+  arcadeMenu = gem.setMenu({
+    items: [{ id: 'replay-tutorial', label: t('Replay the tutorial'), onSelect: replayTutorial }],
+  });
+  document.documentElement.classList.toggle('arcade-menu', arcadeMenu); // CSS hides the button
+}
+offerMenu(); // and again from onStateChange, and on every language change
+```
 
 ```js
 // Built from the same state your own settings screen shows: every setting on it.
@@ -1498,8 +1538,9 @@ gem.setMenu({
   ([p2p-and-parties.md](p2p-and-parties.md) §7.4) needs nothing more for this.
 
 `gem.setMenu` returns `false` under an embedder with no menu, and outside any embedder. Your
-settings button is there either way; what such a game also needs is a way out of its own, a control
-that calls `gem.exit()`.
+settings button is there then, even in a game that
+[leaves it out inside the Arcade](#leaving-your-settings-button-out-inside-the-arcade); 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-right,
 just left of your settings button** ([the top of the screen](#the-top-of-the-screen)). It never
@@ -1650,24 +1691,35 @@ 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: in the Gem menu, never drawn by you
+## The Arcade's wallet: in the Gem menu, and beside the Gem when you ask
 
 The player's platform balances — Gems, Coins (`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 shows them itself.
 
-**The Gem Arcade draws no wallet over your game** (since 2026-10-11). Nothing of it sits in your top
-row, at rest or when a balance moves. The player opens the Gem menu — the Gem button, in whichever
-corner it sits — to see their Gems, Coins and achievement score, and every payout
+**The Gem Arcade draws no wallet over a game that says nothing** (since 2026-10-11). The player
+opens the Gem menu — the Gem button, in whichever corner it sits — to see their Gems, Coins and
+achievement score, and every payout
 [`gem.cueReward`](inventory-and-catalogs.md#showing-the-reward-land-in-the-arcades-wallet) announces
 flies into the Gem button. A payout you do not cue flies too, from the middle of your frame, so cue
 the ones the player earns on screen and the flight starts where they are looking.
 
-**`gem.setWalletVisible` changes nothing on the Gem Arcade.** It is still part of the contract, so a
-game that calls it keeps working, and it is the call to make for an embedder that draws wallets over
-games: hide them while you play, show them on your menus. Under the Gem Arcade there is no wallet to
-show or hide and no wallet rectangle in `gem.viewport.reserved`. The `only` option is ignored there
-as well.
+**A game that wants them on screen asks** (the owner, 2026-10-29):
+
+```js
+gem.setWalletVisible(true, { only: ['GEMS', 'ARCADE_TICKETS'] }); // add 'score' for the achievement score
+```
+
+- **The Arcade draws them beside the Gem**, from the platform's own figures, and reserves them like
+  the Gem: they arrive in `gem.viewport.reserved` and widen the Gem's corner in the
+  `--gem-reserved-*` variables, so a top row laid out from those moves over by itself.
+- **`only` names the wallets.** Without it every wallet shows, the achievement score's chip
+  included; a slug the platform does not serve names nothing.
+- **It is screen state, not a toggle**, held across a reconnect: ask once for every screen, or per
+  screen, and `gem.setWalletVisible(false)` puts them away (during play, say). Nothing tells the
+  game a balance changed, and nothing needs to: the figures are the Arcade's.
+- **An Arcade from before this change ignores the call**: nothing breaks, and the wallets stay in
+  the Gem menu. Another embedder that draws wallets over games honours it the same way.
 
 ## No accidental text selection