@indiegems/gem-web-sdk 16.3.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
@@ -221,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
@@ -234,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
@@ -252,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

@@ -296,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/changelog.md

@@ -16,6 +16,12 @@ 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.

package/docs/getting-started.md

@@ -50,7 +50,7 @@ either way.
 ```jsonc
 // package.json
 "dependencies": {
-  "@indiegems/gem-web-sdk": "16.3.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": "d792225c078f9488e3c67f2fe4af1128f7f742ee829173dcd014b03e11eb32f0",
-      "updated": "2026-10-29T20:35:07Z"
+      "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,8 +38,8 @@
     },
     {
       "file": "brand-art.md",
-      "sha256": "99ef1d5703bca12128b38db8352a102e11444de82903a73973942f074da4fc74",
-      "updated": "2026-10-29T20:35:07Z"
+      "sha256": "b7f8dda1afdb8d56cadee752e6b09fc62238372b68ebc8a746518e528f52e167",
+      "updated": "2026-10-29T21:40:17Z"
     },
     {
       "file": "branding.md",
@@ -48,8 +48,8 @@
     },
     {
       "file": "changelog.md",
-      "sha256": "600e6a0c79c48d4fa82e0993eac822df6629ab737ec6053eafab19c743ea19b8",
-      "updated": "2026-10-29T21:40:20Z"
+      "sha256": "e66efedcc9662bea610d3d4edc4e0125f3078e2b49059770f4553d57f37368b3",
+      "updated": "2026-10-29T23:50:25Z"
     },
     {
       "file": "daily-challenges.md",
@@ -78,13 +78,13 @@
     },
     {
       "file": "getting-started.md",
-      "sha256": "50f47be4de5a38a04e49cf1e864f66f8eab4739d8658d6984bb85c61400a0893",
-      "updated": "2026-10-29T21:40:20Z"
+      "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",
@@ -138,8 +138,8 @@
     },
     {
       "file": "server-bundles.md",
-      "sha256": "721aeb9ac64b9564477a5dffb3b5cc70d6d0c1b222d79ab7090413a0f9b4ef5a",
-      "updated": "2026-10-29T21:40:20Z"
+      "sha256": "387d213d3770f21dccb32c94aac57b5af32bcac8bbe5ca9a6c3c2d8d51e5a2a2",
+      "updated": "2026-10-29T23:50:25Z"
     },
     {
       "file": "serverless-functions-js.md",
@@ -163,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.3.0/gem-web-sdk.tgz
-curl -fsSL https://downloads.gemarcade.com/sdk/v16.3.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
 

package/package.json

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

package/schema/bridge.v1.json

@@ -3771,8 +3771,8 @@
         "      arcade's store for one of the store's own SKUs -",
         "      gem.requestStorePurchase, gated on `store` -",
         "      but only from the player's press on a button of the game's; that",
-        "      sheet is the Arcade Store's, under its own rules, and nothing opens",
-        "      it by itself on a refusal here.",
+        "      checkout is the Arcade Store's, under its own rules, and nothing",
+        "      opens it by itself on a refusal here.",
         "    - MONEY IS TAKEN ONLY ON THE PAYMENT PROVIDER'S PAGE OR THE OPERATING",
         "      SYSTEM'S PURCHASE SHEET, which a player reaches through the parent's",
         "      own chrome. Nothing a frame sends carries a price or a card field,",
@@ -5342,7 +5342,9 @@
         "rail's own formatted string, and a game shows it exactly as given,",
         "never parsing it or computing a discount from it. No balance. And no",
         "per-offer availability flag: one would reveal a recent purchase through",
-        "its cooldown, so the parent's sheet explains a cooldown instead.",
+        "its cooldown, so the parent explains a cooldown in its own chrome",
+        "instead, and a purchase of that offer is answered `declined` /",
+        "`cancelled`.",
         "",
         "THE NAMES ARE THE PLATFORM'S, not a game developer's: the Arcade",
         "Store's own catalog copy, which is why `name` and `description` sit",
@@ -5438,14 +5440,14 @@
       "direction": "frameToParent",
       "transport": "port",
       "$comment": [
-        "Ask the parent to open the Arcade Store's purchase sheet for ONE SKU it",
+        "Ask the parent to open the Arcade Store's checkout for ONE SKU it",
         "listed in gem.storeOffersResult - real money, not Gems. Gated by the",
         "`store` capability. Answered by `gem.storePurchaseResult`.",
         "",
         "THE GAME ASKS; THE PLATFORM SELLS. Nothing in this message is a price,",
-        "a card field, a URL or a token. The parent renders its own sheet from",
-        "platform records, takes money only on the payment provider's page or",
-        "the operating system's purchase sheet, and tells the game the outcome.",
+        "a card field, a URL or a token. The parent looks the SKU up in its own",
+        "listing, takes money only on the payment provider's page or the",
+        "operating system's purchase sheet, and tells the game the outcome.",
         "",
         "AN ACTING MESSAGE, under every rule gem.requestOpenApp states: a press",
         "the parent can see (a missing `userActivation` API fails closed), one",
@@ -5456,17 +5458,26 @@
         "  would list to this player right now; anything else is `unavailable`",
         "  with nothing shown.",
         "",
-        "  THE STORE'S OWN SHEET. Over the paused game, hidden not dimmed, with",
-        "  the parent's bar saying the Arcade Store is open, game chrome frozen,",
-        "  and focus never landing on a money control. \"Not now\" has the",
-        "  default focus. Buy arms visibly for a moment and then takes a FRESH",
-        "  press; input during arming restarts it.",
+        "  STRAIGHT TO CHECKOUT, with no confirmation of the parent's own first,",
+        "  by owner decision: games are developed in-house and trusted, as for",
+        "  gem.requestOpenGame. The press in the game opens the",
+        "  payment provider's page on the web, or the operating system's",
+        "  purchase sheet in an app, over the paused game: hidden, not dimmed.",
+        "  That checkout is the confirmation - it has its own pay control, and",
+        "  no money moves without the player's press there.",
+        "",
+        "  AN OFFER COOLING DOWN OPENS NOTHING. When the listed SKU cannot be",
+        "  bought again yet, the parent says when, in its own chrome, and",
+        "  answers `declined` / `cancelled` - the answer a closed checkout gets,",
+        "  so the cooldown, which would reveal a recent purchase, never crosses",
+        "  the bridge. It starts no back-off: the player turned nothing down.",
         "",
         "  BACK OFF AFTER A DISMISSAL. `cancelled` is disclosed, so after the",
-        "  player dismisses a sheet a game started, further asks from that game",
+        "  player closes a checkout a game started, further asks from that game",
         "  are `declined` / `busy`, unrendered, for an interval that grows with",
         "  each dismissal (the Arcade: 30 s, 2 min, 10 min, then the rest of the",
-        "  session).",
+        "  session). Only the player closing it starts the back-off: a failed",
+        "  payment, `error` and `ok` / `pending` do not.",
         "",
         "  RESUME, THEN ANSWER. The result is sent after the game has been told",
         "  it is resumed, so the game's own celebration is visible.",
@@ -5508,9 +5519,10 @@
         "                `reason: pending`, the provider has not settled yet (or",
         "                the player left before it did): `gem.storePurchaseSettled`",
         "                follows when it does, and a game re-reads on resume too.",
-        "  declined    - nothing was bought: the player dismissed the sheet",
-        "                (`cancelled`), or no press, another acting message open",
-        "                or a back-off running (`busy`).",
+        "  declined    - nothing was bought: the player closed the checkout,",
+        "                or the offer is cooling down (`cancelled`); or no",
+        "                press, another acting message open or a back-off",
+        "                running (`busy`).",
         "  unavailable - no sale the parent can vouch for. With `store_off`",
         "                (the store withheld), `sign_in_required` (a guest),",
         "                `not_found` (an unknown SKU) or the provider's own",