@indiegems/gem-web-sdk 16.3.0 → 17.0.0

package/docs/arcade-economy.md

@@ -204,10 +204,10 @@ player got.
 Nothing sells Coins or achievement points, alone or in a bundle. The arcade's own store sells
 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:
+either itself. It may put the arcade store's own Gem packs, Boosts and passes in front of a player
+from a 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
@@ -246,8 +246,9 @@ animates every payout into the right total. Gems and Coins follow the same rules
 - **No top-up or payment screen of your own.** Never draw a "buy Coins" offer, a checkout, a
   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
+  own Buy button is yours, and so is a "Get Gems" button that calls `gem.store.purchase`, or a "Get
+  VIP" button that calls `gem.store.showOffer`, from the player's press: the checkout each one
+  leads to 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,39 @@ 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.
 
+## 17.0.0
+
+*Written from the API facts alone; no summary was generated for this release.*
+
+Upgrading from 16.3.1. Impact: required.
+
+### Must change
+
+- PARENT_CONFORMANCE_VERSION changed its signature.
+- FRAME_TO_PARENT changed its signature.
+- FrameMessage changed its signature.
+- GemCapability changed its signature.
+- PARENT_TO_FRAME changed its signature.
+- ParentMessage changed its signature.
+
+### New capability
+
+- StoreApi.showOffer was added.
+- StoreApi.showOfferAvailable was added.
+- GemHost.answerStoreOfferSheet was added.
+- GemRequestStoreOfferSheet was added.
+- GemStoreOfferSheetResult was added.
+- HostCallbacks.onRequestStoreOfferSheet was added.
+- HostOptions.onRequestStoreOfferSheet was added.
+- validateGemRequestStoreOfferSheet was added.
+- validateGemStoreOfferSheetResult was added.
+
+## 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": "17.0.0"
 }
 ```
 

package/docs/inventory-and-catalogs.md

@@ -827,8 +827,9 @@ inventory, never on a reason, and do not retry because of one.
 ⚠️ **Never draw a top-up or payment screen of your own** — no checkout, no wallet top-up, nothing
 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
+arcade's alone: a "Get Gems" button of yours calls `gem.store.purchase` from the player's press, a
+"Get VIP" button calls `gem.store.showOffer`, 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 +927,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": "7320826529435d290159c8b0707f69819124607d1b38160dbc85f63b385fdea9",
+      "updated": "2026-10-30T13:36:37Z"
     },
     {
       "file": "arcade-avatars.md",
@@ -28,8 +28,8 @@
     },
     {
       "file": "arcade-economy.md",
-      "sha256": "aca343bf98c0e111bca7d27f504bf71b43802b98e5cd649792dfd7c5f30b1b16",
-      "updated": "2026-10-28T18:37:42Z"
+      "sha256": "b72474b4694842a1fda030ab9df79987d2906f7a8c922e8630622d747a4b2c3c",
+      "updated": "2026-10-30T13:36:37Z"
     },
     {
       "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": "b795d5ed73558a4d355196971fb4bd9689ca15d38fd01d9a67b4cf6c0e8ff25d",
+      "updated": "2026-10-30T14:09:44Z"
     },
     {
       "file": "daily-challenges.md",
@@ -78,13 +78,13 @@
     },
     {
       "file": "getting-started.md",
-      "sha256": "50f47be4de5a38a04e49cf1e864f66f8eab4739d8658d6984bb85c61400a0893",
-      "updated": "2026-10-29T21:40:20Z"
+      "sha256": "a69a8be43e655a71717c1d15ff3e9136103c17eebd9074c2f3dab4fad07d2689",
+      "updated": "2026-10-30T14:09:44Z"
     },
     {
       "file": "inventory-and-catalogs.md",
-      "sha256": "e7bf9f38bf4ede778fdaca200186b782870f409949743e4e85f22f9c919cd19c",
-      "updated": "2026-10-28T18:37:42Z"
+      "sha256": "9c898355af92ab7e17035bad964dce57b26e64624b18e83149b88ae10b96fd9c",
+      "updated": "2026-10-30T13:36:37Z"
     },
     {
       "file": "leaderboards.md",
@@ -138,8 +138,8 @@
     },
     {
       "file": "server-bundles.md",
-      "sha256": "721aeb9ac64b9564477a5dffb3b5cc70d6d0c1b222d79ab7090413a0f9b4ef5a",
-      "updated": "2026-10-29T21:40:20Z"
+      "sha256": "d00bc2ea3896c2e262619bf87b2892dd954c9ef87d37dfb5881bb6ef7439401a",
+      "updated": "2026-10-30T14:09:44Z"
     },
     {
       "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/v17.0.0/gem-web-sdk.tgz
+curl -fsSL https://downloads.gemarcade.com/sdk/v17.0.0/gem-web-sdk.tgz.sri
 openssl dgst -sha384 -binary gem-web-sdk.tgz | openssl base64 -A
 ```
 

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

@@ -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": "17.0.0",
   "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",
@@ -5569,6 +5581,114 @@
         }
       },
       "rateLimit": { "perMinute": 30 }
+    },
+    {
+      "type": "gem.requestStoreOfferSheet",
+      "direction": "frameToParent",
+      "transport": "port",
+      "$comment": [
+        "Ask the parent to SHOW one SKU it listed in gem.storeOffersResult, in",
+        "the Arcade's own one-offer sheet over the paused game - real money, not",
+        "Gems. Gated by the `storeOfferSheet` capability. Answered by",
+        "`gem.storeOfferSheetResult`.",
+        "",
+        "THE ARCADE DRAWS THE OFFER; THE GAME ONLY POINTS AT IT. gem.requestStorePurchase",
+        "is for an offer the game drew itself from gem.storeOffersResult, and goes",
+        "straight to checkout. This is for an offer whose pitch the bridge cannot",
+        "carry: its perks, a sale, what a holder already has. All of that stays",
+        "with the parent, so none of it - least of all whether this player holds",
+        "a pass - crosses to the game. The sheet's Buy opens the same checkout",
+        "gem.requestStorePurchase opens.",
+        "",
+        "EVERY RULE OF gem.requestStorePurchase HOLDS, and it shares them rather",
+        "than having its own: an acting message (a press the parent can see, one",
+        "at a time across all of them, both checked before `skuId` is resolved,",
+        "the answer bound to this frame session); only a SKU the parent would",
+        "list now; an offer cooling down opens nothing and answers `declined` /",
+        "`cancelled`; the SAME back-off, so a game cannot escape one by switching",
+        "message; resume, then answer; evidence, not accounting.",
+        "",
+        "THE SHEET IS NOT A SECOND CONFIRMATION, and it does not change",
+        "gem.requestStorePurchase's straight-to-checkout rule. It is the pitch;",
+        "the checkout is still the confirmation, with its own pay control. The",
+        "player leaving the sheet without pressing Buy is a dismissal, exactly",
+        "as closing a checkout is, and starts the back-off.",
+        "",
+        "A PARENT THAT ADVERTISES `storeOfferSheet` ADVERTISES `store`: the",
+        "game's SKU comes from gem.storeOffersResult, and a purchase that answers",
+        "`ok` / `pending` here is followed by gem.storePurchaseSettled.",
+        "",
+        "Every field is untrusted text: match `skuId` against the offers you",
+        "read, never interpolate it into a path, a query or a log line."
+      ],
+      "fields": {
+        "requestId": {
+          "kind": "string",
+          "maxLength": 64,
+          "$comment": "Opaque and frame-chosen. Echo-only, and never a key on the money path: the parent derives its own request identity."
+        },
+        "skuId": {
+          "kind": "string",
+          "maxLength": 64,
+          "$comment": "One `skuId` from gem.storeOffersResult. Frame-chosen: matched by the parent against the listing it would show now."
+        }
+      },
+      "rateLimit": {
+        "perMinute": 12,
+        "$comment": "gem.requestStorePurchase's limit and its argument: it bounds a BUGGY game, not a hostile one. What bounds the player's experience is the activation check, the one-at-a-time rule and the back-off."
+      }
+    },
+    {
+      "type": "gem.storeOfferSheetResult",
+      "direction": "parentToFrame",
+      "transport": "port",
+      "$comment": [
+        "The answer to one gem.requestStoreOfferSheet, carrying exactly what",
+        "gem.storePurchaseResult carries and meaning the same. Gated by the",
+        "`storeOfferSheet` capability.",
+        "",
+        "  ok          - the player paid. With no reason, fulfilment has",
+        "                settled; with `reason: pending`,",
+        "                gem.storePurchaseSettled follows when it does.",
+        "  declined    - nothing was bought: the player left the sheet or 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`,",
+        "                `sign_in_required`, `not_found` or the provider's own",
+        "                failure code, nothing was bought. With `error`, the",
+        "                OUTCOME IS UNKNOWN and the player may have paid. The SDK",
+        "                resolves the same `unavailable` / `error` when the port",
+        "                closes under an open sheet.",
+        "",
+        "`cancelled` DOES NOT SAY WHICH. The game is not told whether the player",
+        "left the sheet or the checkout, and nothing here says what the sheet",
+        "showed.",
+        "",
+        "NO TIMEOUT ON THE GAME'S SIDE while the port is alive: the parent always",
+        "answers, and a player may read a sheet for as long as they like.",
+        "NEVER AUTO-RETRIED. Only a fresh press may ask again."
+      ],
+      "fields": {
+        "requestId": {
+          "kind": "string",
+          "maxLength": 64,
+          "$comment": "Echoes the gem.requestStoreOfferSheet that asked. Echo-only."
+        },
+        "outcome": {
+          "kind": "enum",
+          "values": ["ok", "declined", "unavailable"],
+          "$comment": "Closed at three, as gem.purchaseResult's."
+        },
+        "reason": {
+          "kind": "string",
+          "maxLength": 64,
+          "format": "code",
+          "optional": true,
+          "$comment": "An open code, on any outcome: `pending` with `ok`; `cancelled` or `busy` with `declined`; `store_off`, `sign_in_required`, `not_found`, `error` or the payment provider's own failure code with `unavailable`. Normalized to the code grammar before it is sent, as gem.storePurchaseResult's. A receiver must not fail on a code it does not know."
+        }
+      },
+      "rateLimit": { "perMinute": 30 }
     }
   ],
 

package/schema/capabilities.public.json

@@ -295,6 +295,13 @@
         "gem.storePurchaseResult",
         "gem.storePurchaseSettled"
       ]
+    },
+    "storeOfferSheet": {
+      "implemented": true,
+      "gates": [
+        "gem.requestStoreOfferSheet",
+        "gem.storeOfferSheetResult"
+      ]
     }
   }
 }