@indiegems/gem-web-sdk 16.3.0 → 17.0.0

package/docs/api/api-reference-game.md

@@ -1,6 +1,6 @@
 # The browser surface — API reference
 
-Generated from `@indiegems/gem-web-sdk/sdk` v16.3.0, the version of the package this file ships in. Every symbol below carries an explicit anchor, its `anchor` in `reference.json` beside this file.
+Generated from `@indiegems/gem-web-sdk/sdk` v17.0.0, the version of the package this file ships in. Every symbol below carries an explicit anchor, its `anchor` in `reference.json` beside this file.
 
 `@indiegems/gem-web-sdk/sdk` is the one import a game writes, wherever its code runs. `@indiegems/gem-web-sdk/game` exports exactly the symbols on this page and nothing else, for a build that wants only this half.
 
@@ -4590,7 +4590,7 @@ interface StoreApi
 ```
 
 **Real money.** The Arcade Store's own Gem packs, Boosts, passes and bundles,
-bought with the player's money through the arcade's own purchase sheet.
+bought with the player's money through the Arcade Store's own checkout.
 `gem.store` is one of these. To spend Gems or Coins on your game's own items,
 use `gem.purchases`.
 
@@ -4605,6 +4605,19 @@ readonly available: boolean
 Whether the Arcade Store answers here, synchronously. Draw your own "Get
 Gems" button only when it is true.
 
+<a id="storeapi-showofferavailable"></a>
+
+## StoreApi.showOfferAvailable
+
+```ts
+readonly showOfferAvailable: boolean
+```
+
+Whether [StoreApi.showOffer](#storeapi-showoffer) answers here, synchronously. An older
+Arcade can sell through `purchase` and still not draw this sheet, so read
+this, not [StoreApi.available](#storeapi-available), before you draw a button that calls
+`showOffer`. `false` until the bridge is up.
+
 <a id="storeapi-offers"></a>
 
 ## StoreApi.offers
@@ -4628,20 +4641,24 @@ is withheld. Re-read on resume: what is on sale can change.
 purchase(skuId: string): Promise<ArcadeOutcome>
 ```
 
-Ask the arcade to open its store's purchase sheet for one SKU from
-[StoreApi.offers](#storeapi-offers). **Call it from the player's press handler** — the
+Ask the arcade to open checkout for one SKU from [StoreApi.offers](#storeapi-offers):
+the payment provider's page on the web, the app store's purchase sheet in
+the Arcade's apps, straight away, with no confirmation screen of the
+arcade's own first. **Call it from the player's press handler** — the
 arcade refuses an ask no person pressed for, `declined` / `busy`.
 
 - `ok` — the player paid. Re-read balances and inventory through `gem.me`;
   nothing here carries an amount. With `reason: 'pending'`, the provider
   has not settled yet: [StoreApi.onSettled](#storeapi-onsettled) hears when it does.
-- `declined` — nothing was bought: `cancelled` (the player said no) or
-  `busy`. Return to your screen silently, and do not ask again unprompted.
+- `declined` — nothing was bought: `cancelled` (the player closed the
+  checkout, or the offer cannot be bought again yet) or `busy` (after a
+  closed checkout the arcade refuses the next ask for a while). Return to
+  your screen silently, and do not ask again unprompted.
 - `unavailable` with `store_off`, `sign_in_required`, `not_found`,
   `unsupported`, `invalid_argument` or a payment provider's failure code —
   nothing was bought.
 - `unavailable` / `error` — **the outcome is unknown, and the player may
-  have paid.** It is what you get when the bridge closes while the sheet
+  have paid.** It is what you get when the bridge closes while checkout
   is open, or the arcade has no reliable answer. Never tell the player
   nothing was bought: re-read balances and inventory through `gem.me`,
   and keep listening with [StoreApi.onSettled](#storeapi-onsettled).
@@ -4655,6 +4672,43 @@ payment takes as long as it takes.
 
 **Returns.** Always resolves; never rejects.
 
+<a id="storeapi-showoffer"></a>
+
+## StoreApi.showOffer
+
+```ts
+showOffer(skuId: string): Promise<ArcadeOutcome>
+```
+
+Ask the arcade to show one SKU from [StoreApi.offers](#storeapi-offers) in its own
+sheet, over your paused and hidden game: its art, what the player gets, a
+sale if one is on, and, for a pass the player already holds, how long it
+has left. The sheet's Buy opens the same checkout as
+[StoreApi.purchase](#storeapi-purchase). **Call it from the player's press handler.**
+
+Use it for an offer you would have to hardcode a pitch for: VIP and other
+passes, and bundles. Your button only needs to say what it opens. Draw a
+Gem pack yourself and use `purchase` instead. Check
+[StoreApi.showOfferAvailable](#storeapi-showofferavailable) first, and that the SKU is in `offers`.
+
+It answers exactly as `purchase` does, with one addition: `declined` /
+`cancelled` also covers the player leaving the sheet without pressing Buy,
+and you are not told which of the two they closed. That starts the same
+back-off, so do not ask again unprompted. `unavailable` / `unsupported`
+means this Arcade does not draw the sheet, and nothing was sent.
+`unavailable` / `error` means **the outcome is unknown**: re-read balances
+and inventory through `gem.me`, and keep listening with
+[StoreApi.onSettled](#storeapi-onsettled).
+
+NO TIMEOUT: it waits for as long as the arcade is connected, because a
+player may read a sheet and pay for as long as they like.
+
+| Parameter | Type |
+| --- | --- |
+| `skuId` | `string` |
+
+**Returns.** Always resolves; never rejects.
+
 <a id="storeapi-onsettled"></a>
 
 ## StoreApi.onSettled
@@ -10478,9 +10532,9 @@ readonly reserved: readonly GemReservedArea[]
 ```
 
 Rectangles of your frame the arcade's own controls cover — in the Gem
-Arcade, its Gem button in whichever corner it sits, and the frame-rate readout
-beside it while the player shows it; an embedder that draws wallets over
-your game adds theirs (see `setWalletVisible`). Keep essential UI and touch
+Arcade, its Gem button in whichever corner it sits, the frame-rate readout
+beside it while the player shows it, and the wallets beside it while your
+game asks for them (see `setWalletVisible`). Keep essential UI and touch
 targets out of them. Empty when the arcade covers nothing.
 
 Each is a keep-out area, grown out to the frame edges it sits nearest — not
@@ -10629,10 +10683,10 @@ readonly only?: readonly string[]
 
 While shown, show ONLY these: platform currency slugs as
 `gem.platform.currencies.get()` lists them (`GEMS`, `ARCADE_TICKETS`),
-matched exactly, and the literal `'score'` for the achievement score. Only
-for a screen about one currency, such as a Coins store; leave it out and
-every wallet shows, which is always safe. The Gem Arcade draws no wallet
-over a game, so it has nothing to narrow and ignores it.
+matched exactly, and the literal `'score'` for the achievement score. Leave
+it out and every wallet shows, the achievement score's included. The Gem
+Arcade honours it: `{ only: ['GEMS', 'ARCADE_TICKETS'] }` shows those two
+and no achievement score; a slug the platform does not serve names nothing.
 
 <a id="gamemenuitem"></a>
 
@@ -10688,7 +10742,8 @@ interface GameMenu
 ```
 
 What your game adds to the arcade's menu — see `gem.setMenu`. Your settings
-are not part of it: they open from your own settings button.
+screen is not part of it: it opens from your own settings button. An action
+on that screen (Replay the tutorial, How to play) may also be an entry here.
 
 <a id="gamemenu-items"></a>
 
@@ -11211,8 +11266,10 @@ sheet. To spend Gems or Coins on your game's own items, use
 [Gem.purchases](#gem-purchases).
 
 List what the store sells here with `offers()`, show each `priceDisplay`
-exactly as given, and call `purchase(skuId)` from the player's press. After
-`ok`, re-read balances through [Gem.me](#gem-me). Nothing rejects.
+exactly as given, and call `purchase(skuId)` from the player's press. For a
+pass, a bundle or anything else whose pitch you would have to hardcode, call
+`showOffer(skuId)` instead, and the arcade draws the offer. After `ok`,
+re-read balances through [Gem.me](#gem-me). Nothing rejects.
 
 **Guides.** [arcade-and-store](../arcade-and-store.md)
 
@@ -11796,9 +11853,10 @@ Tell the arcade a platform-currency reward is on its way, so it **shows it
 landing**: in the Gem Arcade the currency flies from `origin` into the Gem
 button, wherever on your frame it sits, which pops as each mark lands, and
 the player's total moves once the platform confirms the grant. The Gem
-Arcade draws no wallet over your game: the player sees their Gems and
-Coins in the Gem menu. A payout you do not cue still flies, from the
-middle of your frame, so cue the ones the player earns on screen.
+Arcade draws no wallet over your game unless you ask (`setWalletVisible`):
+the player sees their Gems and Coins in the Gem menu. A payout you do not
+cue still flies, from the middle of your frame, so cue the ones the player
+earns on screen.
 
 Call it the moment your game decides to award — when your server has moved
 (or is about to move) the progression mapped onto a platform currency —
@@ -11843,26 +11901,25 @@ landed — which it does on every channel, dev and test included.
 setWalletVisible(visible: boolean, options?: WalletVisibleOptions): boolean
 ```
 
-Show or hide the player's wallets — Gems, Coins, the achievement score —
-that an embedder draws over your game.
+Ask the arcade to show, or stop showing, the player's wallets — Gems,
+Coins, the achievement score — over your game.
 
-**The Gem Arcade draws no wallet over a game** (since 2026-10-11): the
-player sees their balances in the Gem menu, and payouts fly into the Gem
-button. So under the Gem Arcade this changes nothing on screen — it is
-accepted and harmless, and a game that already calls it keeps working.
-Call it for an embedder that does draw wallets over your game: hide them
-while you play, show them on your menus.
+**The Gem Arcade draws them on request** (the owner, 2026-10-29): a game
+that says nothing gets no wallet over it, as since 2026-10-11, and the
+player sees their balances in the Gem menu; a game that asks gets them
+drawn beside the Gem, from the platform's own figures. An Arcade from
+before that ignores the call, harmlessly.
 
 ```js
-level.onStart = () => gem.setWalletVisible(false);
-menu.onOpen = () => gem.setWalletVisible(true);
+gem.setWalletVisible(true, { only: ['GEMS', 'ARCADE_TICKETS'] }); // every screen
+level.onStart = () => gem.setWalletVisible(false); // or put them away during play
 ```
 
 **It is screen state, not a toggle.** Each call is the whole answer and
-replaces the last. Where an embedder draws wallets, shown ones arrive as
-rectangles in `gem.viewport.reserved` and hiding them gives that space
-back; the Gem Arcade sends none for wallets. `only` narrows what shows,
-where an embedder honours it; the Gem Arcade does not.
+replaces the last. Shown wallets arrive as rectangles in
+`gem.viewport.reserved` (and widen the Gem's corner in the
+`--gem-reserved-*` variables), and hiding them gives that space back.
+`only` narrows what shows.
 
 **Never draw a platform balance yourself**, and never show a pending state
 for one: the arcade takes every figure from the platform. If this returns
@@ -11895,10 +11952,14 @@ gem.setMenu({
 });
 ```
 
-**Your settings are not in it: draw your own settings button, always** —
+**Your settings screen is not in it: draw your own settings button** —
 top-right, with your Back button just to its left, clear of
 `gem.viewport.reserved`. The Arcade's menu never opens your settings
-screen.
+screen. Inside the Gem Arcade you may leave the button out while this
+returns `true`, when every setting on your screen is declared with
+`gem.settings` and every action on it is one of these entries; it returns
+`false` before the bridge is up and under an embedder with no menu, and the
+button stays there.
 
 **It is screen state, not a toggle.** Each call is the whole answer and
 replaces the last, so call it again when the entries change — a new

package/docs/api/api-reference-server.md

@@ -1,6 +1,6 @@
 # The server surface — API reference
 
-Generated from `@indiegems/gem-web-sdk/sdk` v16.3.0, the version of the package this file ships in. Every symbol below carries an explicit anchor, its `anchor` in `reference.json` beside this file.
+Generated from `@indiegems/gem-web-sdk/sdk` v17.0.0, the version of the package this file ships in. Every symbol below carries an explicit anchor, its `anchor` in `reference.json` beside this file.
 
 `@indiegems/gem-web-sdk/sdk` is the one import a game writes, wherever its code runs. `@indiegems/gem-web-sdk/server` exports exactly the symbols on this page and nothing else, for a build that wants only this half.
 

package/docs/api/reference.json

@@ -2,7 +2,7 @@
   "schema_version": 2,
   "source": {
     "repo": "IndieGems/gem-web-sdk",
-    "version": "16.3.0"
+    "version": "17.0.0"
   },
   "entries": [
     {
@@ -5512,7 +5512,7 @@
           "group": "store",
           "signature": "interface StoreApi",
           "documented": true,
-          "summary": "**Real money.** The Arcade Store's own Gem packs, Boosts, passes and bundles,\nbought with the player's money through the arcade's own purchase sheet.\n`gem.store` is one of these. To spend Gems or Coins on your game's own items,\nuse `gem.purchases`.",
+          "summary": "**Real money.** The Arcade Store's own Gem packs, Boosts, passes and bundles,\nbought with the player's money through the Arcade Store's own checkout.\n`gem.store` is one of these. To spend Gems or Coins on your game's own items,\nuse `gem.purchases`.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -5537,6 +5537,22 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "StoreApi.showOfferAvailable",
+          "name": "showOfferAvailable",
+          "anchor": "storeapi-showofferavailable",
+          "group": "store",
+          "signature": "readonly showOfferAvailable: boolean",
+          "documented": true,
+          "summary": "Whether [StoreApi.showOffer](api-reference-game.md#storeapi-showoffer) answers here, synchronously. An older\nArcade can sell through `purchase` and still not draw this sheet, so read\nthis, not [StoreApi.available](api-reference-game.md#storeapi-available), before you draw a button that calls\n`showOffer`. `false` until the bridge is up.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "StoreApi.offers",
           "name": "offers",
@@ -5560,7 +5576,30 @@
           "group": "store",
           "signature": "purchase(skuId: string): Promise<ArcadeOutcome>",
           "documented": true,
-          "summary": "Ask the arcade to open its store's purchase sheet for one SKU from\n[StoreApi.offers](api-reference-game.md#storeapi-offers). **Call it from the player's press handler** — the\narcade refuses an ask no person pressed for, `declined` / `busy`.\n\n- `ok` — the player paid. Re-read balances and inventory through `gem.me`;\n  nothing here carries an amount. With `reason: 'pending'`, the provider\n  has not settled yet: [StoreApi.onSettled](api-reference-game.md#storeapi-onsettled) hears when it does.\n- `declined` — nothing was bought: `cancelled` (the player said no) or\n  `busy`. Return to your screen silently, and do not ask again unprompted.\n- `unavailable` with `store_off`, `sign_in_required`, `not_found`,\n  `unsupported`, `invalid_argument` or a payment provider's failure code —\n  nothing was bought.\n- `unavailable` / `error` — **the outcome is unknown, and the player may\n  have paid.** It is what you get when the bridge closes while the sheet\n  is open, or the arcade has no reliable answer. Never tell the player\n  nothing was bought: re-read balances and inventory through `gem.me`,\n  and keep listening with [StoreApi.onSettled](api-reference-game.md#storeapi-onsettled).\n\nNO TIMEOUT: it waits for as long as the arcade is connected, because a\npayment takes as long as it takes.",
+          "summary": "Ask the arcade to open checkout for one SKU from [StoreApi.offers](api-reference-game.md#storeapi-offers):\nthe payment provider's page on the web, the app store's purchase sheet in\nthe Arcade's apps, straight away, with no confirmation screen of the\narcade's own first. **Call it from the player's press handler** — the\narcade refuses an ask no person pressed for, `declined` / `busy`.\n\n- `ok` — the player paid. Re-read balances and inventory through `gem.me`;\n  nothing here carries an amount. With `reason: 'pending'`, the provider\n  has not settled yet: [StoreApi.onSettled](api-reference-game.md#storeapi-onsettled) hears when it does.\n- `declined` — nothing was bought: `cancelled` (the player closed the\n  checkout, or the offer cannot be bought again yet) or `busy` (after a\n  closed checkout the arcade refuses the next ask for a while). Return to\n  your screen silently, and do not ask again unprompted.\n- `unavailable` with `store_off`, `sign_in_required`, `not_found`,\n  `unsupported`, `invalid_argument` or a payment provider's failure code —\n  nothing was bought.\n- `unavailable` / `error` — **the outcome is unknown, and the player may\n  have paid.** It is what you get when the bridge closes while checkout\n  is open, or the arcade has no reliable answer. Never tell the player\n  nothing was bought: re-read balances and inventory through `gem.me`,\n  and keep listening with [StoreApi.onSettled](api-reference-game.md#storeapi-onsettled).\n\nNO TIMEOUT: it waits for as long as the arcade is connected, because a\npayment takes as long as it takes.",
+          "deprecated": null,
+          "params": [
+            {
+              "name": "skuId",
+              "type": "string",
+              "optional": false,
+              "summary": null
+            }
+          ],
+          "returns": "Always resolves; never rejects.",
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "StoreApi.showOffer",
+          "name": "showOffer",
+          "anchor": "storeapi-showoffer",
+          "group": "store",
+          "signature": "showOffer(skuId: string): Promise<ArcadeOutcome>",
+          "documented": true,
+          "summary": "Ask the arcade to show one SKU from [StoreApi.offers](api-reference-game.md#storeapi-offers) in its own\nsheet, over your paused and hidden game: its art, what the player gets, a\nsale if one is on, and, for a pass the player already holds, how long it\nhas left. The sheet's Buy opens the same checkout as\n[StoreApi.purchase](api-reference-game.md#storeapi-purchase). **Call it from the player's press handler.**\n\nUse it for an offer you would have to hardcode a pitch for: VIP and other\npasses, and bundles. Your button only needs to say what it opens. Draw a\nGem pack yourself and use `purchase` instead. Check\n[StoreApi.showOfferAvailable](api-reference-game.md#storeapi-showofferavailable) first, and that the SKU is in `offers`.\n\nIt answers exactly as `purchase` does, with one addition: `declined` /\n`cancelled` also covers the player leaving the sheet without pressing Buy,\nand you are not told which of the two they closed. That starts the same\nback-off, so do not ask again unprompted. `unavailable` / `unsupported`\nmeans this Arcade does not draw the sheet, and nothing was sent.\n`unavailable` / `error` means **the outcome is unknown**: re-read balances\nand inventory through `gem.me`, and keep listening with\n[StoreApi.onSettled](api-reference-game.md#storeapi-onsettled).\n\nNO TIMEOUT: it waits for as long as the arcade is connected, because a\nplayer may read a sheet and pay for as long as they like.",
           "deprecated": null,
           "params": [
             {
@@ -12027,7 +12066,7 @@
           "group": "player",
           "signature": "readonly reserved: readonly GemReservedArea[]",
           "documented": true,
-          "summary": "Rectangles of your frame the arcade's own controls cover — in the Gem\nArcade, its Gem button in whichever corner it sits, and the frame-rate readout\nbeside it while the player shows it; an embedder that draws wallets over\nyour game adds theirs (see `setWalletVisible`). Keep essential UI and touch\ntargets out of them. Empty when the arcade covers nothing.\n\nEach is a keep-out area, grown out to the frame edges it sits nearest — not\nthe control's own box, and not something to line anything up with. Where\nthe arcade says, `control` on each is the control itself.\n\nA stylesheet reads the per-corner custom properties the SDK stamps from\nthese instead — `--gem-reserved-tl-height` and friends, and\n`--gem-reserved-tl-center-y` to line a top bar up with the Gem.",
+          "summary": "Rectangles of your frame the arcade's own controls cover — in the Gem\nArcade, its Gem button in whichever corner it sits, the frame-rate readout\nbeside it while the player shows it, and the wallets beside it while your\ngame asks for them (see `setWalletVisible`). Keep essential UI and touch\ntargets out of them. Empty when the arcade covers nothing.\n\nEach is a keep-out area, grown out to the frame edges it sits nearest — not\nthe control's own box, and not something to line anything up with. Where\nthe arcade says, `control` on each is the control itself.\n\nA stylesheet reads the per-corner custom properties the SDK stamps from\nthese instead — `--gem-reserved-tl-height` and friends, and\n`--gem-reserved-tl-center-y` to line a top bar up with the Gem.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -12235,7 +12274,7 @@
           "group": "platform",
           "signature": "readonly only?: readonly string[]",
           "documented": true,
-          "summary": "While shown, show ONLY these: platform currency slugs as\n`gem.platform.currencies.get()` lists them (`GEMS`, `ARCADE_TICKETS`),\nmatched exactly, and the literal `'score'` for the achievement score. Only\nfor a screen about one currency, such as a Coins store; leave it out and\nevery wallet shows, which is always safe. The Gem Arcade draws no wallet\nover a game, so it has nothing to narrow and ignores it.",
+          "summary": "While shown, show ONLY these: platform currency slugs as\n`gem.platform.currencies.get()` lists them (`GEMS`, `ARCADE_TICKETS`),\nmatched exactly, and the literal `'score'` for the achievement score. Leave\nit out and every wallet shows, the achievement score's included. The Gem\nArcade honours it: `{ only: ['GEMS', 'ARCADE_TICKETS'] }` shows those two\nand no achievement score; a slug the platform does not serve names nothing.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -12315,7 +12354,7 @@
           "group": "frame",
           "signature": "interface GameMenu",
           "documented": true,
-          "summary": "What your game adds to the arcade's menu — see `gem.setMenu`. Your settings\nare not part of it: they open from your own settings button.",
+          "summary": "What your game adds to the arcade's menu — see `gem.setMenu`. Your settings\nscreen is not part of it: it opens from your own settings button. An action\non that screen (Replay the tutorial, How to play) may also be an entry here.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -12790,7 +12829,7 @@
           "group": "start",
           "signature": "readonly store: StoreApi",
           "documented": true,
-          "summary": "**Real money.** The Arcade Store's own Gem packs, Boosts, passes and\nbundles, sold for the player's money through the arcade's own purchase\nsheet. To spend Gems or Coins on your game's own items, use\n[Gem.purchases](api-reference-game.md#gem-purchases).\n\nList what the store sells here with `offers()`, show each `priceDisplay`\nexactly as given, and call `purchase(skuId)` from the player's press. After\n`ok`, re-read balances through [Gem.me](api-reference-game.md#gem-me). Nothing rejects.",
+          "summary": "**Real money.** The Arcade Store's own Gem packs, Boosts, passes and\nbundles, sold for the player's money through the arcade's own purchase\nsheet. To spend Gems or Coins on your game's own items, use\n[Gem.purchases](api-reference-game.md#gem-purchases).\n\nList what the store sells here with `offers()`, show each `priceDisplay`\nexactly as given, and call `purchase(skuId)` from the player's press. For a\npass, a bundle or anything else whose pitch you would have to hardcode, call\n`showOffer(skuId)` instead, and the arcade draws the offer. After `ok`,\nre-read balances through [Gem.me](api-reference-game.md#gem-me). Nothing rejects.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -13234,7 +13273,7 @@
           "group": "start",
           "signature": "cueReward(cue: RewardCue): boolean",
           "documented": true,
-          "summary": "Tell the arcade a platform-currency reward is on its way, so it **shows it\nlanding**: in the Gem Arcade the currency flies from `origin` into the Gem\nbutton, wherever on your frame it sits, which pops as each mark lands, and\nthe player's total moves once the platform confirms the grant. The Gem\nArcade draws no wallet over your game: the player sees their Gems and\nCoins in the Gem menu. A payout you do not cue still flies, from the\nmiddle of your frame, so cue the ones the player earns on screen.\n\nCall it the moment your game decides to award — when your server has moved\n(or is about to move) the progression mapped onto a platform currency —\nand pass the centre of that currency's icon (or hero) on your screen, so\nthe flight starts from the mark the player is looking at:\n\n```js\nconst { x, y, width, height } = rewardGem.getBoundingClientRect(); // the gem's own box\ngem.cueReward({\n  currencySlug: 'GEMS', // or 'ARCADE_TICKETS', from the coin\n  expected: 15,\n  origin: { x: x + width / 2, y: y + height / 2 },\n});\n```\n\n**This is the platform-currency animation, and the only one.** The display\nof every platform currency — Gems and Coins alike — belongs to the\narcade: a game draws no flight or celebration of its own for one and keeps\nno counter of one. **If this returns `false`, do nothing** — there is no\nfallback celebration.\n\n**The arcade never takes your word for the amount.** What lands, and the\nplayer's new total, come from the platform itself; `expected` is drawn as\nprovisional, and a cue the platform never confirms fades on its own — a\ngrant clamped to zero, say, or one the receipt reports `suppressed`. So\nthe cue can only ever make the wallet move for a reward that really\nlanded — which it does on every channel, dev and test included.",
+          "summary": "Tell the arcade a platform-currency reward is on its way, so it **shows it\nlanding**: in the Gem Arcade the currency flies from `origin` into the Gem\nbutton, wherever on your frame it sits, which pops as each mark lands, and\nthe player's total moves once the platform confirms the grant. The Gem\nArcade draws no wallet over your game unless you ask (`setWalletVisible`):\nthe player sees their Gems and Coins in the Gem menu. A payout you do not\ncue still flies, from the middle of your frame, so cue the ones the player\nearns on screen.\n\nCall it the moment your game decides to award — when your server has moved\n(or is about to move) the progression mapped onto a platform currency —\nand pass the centre of that currency's icon (or hero) on your screen, so\nthe flight starts from the mark the player is looking at:\n\n```js\nconst { x, y, width, height } = rewardGem.getBoundingClientRect(); // the gem's own box\ngem.cueReward({\n  currencySlug: 'GEMS', // or 'ARCADE_TICKETS', from the coin\n  expected: 15,\n  origin: { x: x + width / 2, y: y + height / 2 },\n});\n```\n\n**This is the platform-currency animation, and the only one.** The display\nof every platform currency — Gems and Coins alike — belongs to the\narcade: a game draws no flight or celebration of its own for one and keeps\nno counter of one. **If this returns `false`, do nothing** — there is no\nfallback celebration.\n\n**The arcade never takes your word for the amount.** What lands, and the\nplayer's new total, come from the platform itself; `expected` is drawn as\nprovisional, and a cue the platform never confirms fades on its own — a\ngrant clamped to zero, say, or one the receipt reports `suppressed`. So\nthe cue can only ever make the wallet move for a reward that really\nlanded — which it does on every channel, dev and test included.",
           "deprecated": null,
           "params": [
             {
@@ -13257,7 +13296,7 @@
           "group": "start",
           "signature": "setWalletVisible(visible: boolean, options?: WalletVisibleOptions): boolean",
           "documented": true,
-          "summary": "Show or hide the player's wallets — Gems, Coins, the achievement score —\nthat an embedder draws over your game.\n\n**The Gem Arcade draws no wallet over a game** (since 2026-10-11): the\nplayer sees their balances in the Gem menu, and payouts fly into the Gem\nbutton. So under the Gem Arcade this changes nothing on screen — it is\naccepted and harmless, and a game that already calls it keeps working.\nCall it for an embedder that does draw wallets over your game: hide them\nwhile you play, show them on your menus.\n\n```js\nlevel.onStart = () => gem.setWalletVisible(false);\nmenu.onOpen = () => gem.setWalletVisible(true);\n```\n\n**It is screen state, not a toggle.** Each call is the whole answer and\nreplaces the last. Where an embedder draws wallets, shown ones arrive as\nrectangles in `gem.viewport.reserved` and hiding them gives that space\nback; the Gem Arcade sends none for wallets. `only` narrows what shows,\nwhere an embedder honours it; the Gem Arcade does not.\n\n**Never draw a platform balance yourself**, and never show a pending state\nfor one: the arcade takes every figure from the platform. If this returns\n`false`, do nothing in its place.",
+          "summary": "Ask the arcade to show, or stop showing, the player's wallets — Gems,\nCoins, the achievement score — over your game.\n\n**The Gem Arcade draws them on request** (the owner, 2026-10-29): a game\nthat says nothing gets no wallet over it, as since 2026-10-11, and the\nplayer sees their balances in the Gem menu; a game that asks gets them\ndrawn beside the Gem, from the platform's own figures. An Arcade from\nbefore that ignores the call, harmlessly.\n\n```js\ngem.setWalletVisible(true, { only: ['GEMS', 'ARCADE_TICKETS'] }); // every screen\nlevel.onStart = () => gem.setWalletVisible(false); // or put them away during play\n```\n\n**It is screen state, not a toggle.** Each call is the whole answer and\nreplaces the last. Shown wallets arrive as rectangles in\n`gem.viewport.reserved` (and widen the Gem's corner in the\n`--gem-reserved-*` variables), and hiding them gives that space back.\n`only` narrows what shows.\n\n**Never draw a platform balance yourself**, and never show a pending state\nfor one: the arcade takes every figure from the platform. If this returns\n`false`, do nothing in its place.",
           "deprecated": null,
           "params": [
             {
@@ -13286,7 +13325,7 @@
           "group": "start",
           "signature": "setMenu(menu: GameMenu): boolean",
           "documented": true,
-          "summary": "Put up to four entries of your own in the arcade's menu. The arcade keeps\none menu button over your game: it is how a player leaves, mutes, goes\nfullscreen, reports a problem and changes their Arcade-wide settings.\n\n```js\ngem.setMenu({\n  items: [{ id: 'how-to-play', label: t('How to play'), onSelect: () => help.open() }],\n});\n```\n\n**Your settings are not in it: draw your own settings button, always** —\ntop-right, with your Back button just to its left, clear of\n`gem.viewport.reserved`. The Arcade's menu never opens your settings\nscreen.\n\n**It is screen state, not a toggle.** Each call is the whole answer and\nreplaces the last, so call it again when the entries change — a new\nlanguage, a screen with different options. `gem.setMenu({})` takes\neverything of yours back out. The arcade's own entries are not yours to\nchange, and Return to the Arcade is always among them.\n\n**The arcade pauses your game while its menu is open** (`onPause`), and\nresumes it before a handler of yours runs. A handler opens a screen; it\nshould not assume the game was paused by you.",
+          "summary": "Put up to four entries of your own in the arcade's menu. The arcade keeps\none menu button over your game: it is how a player leaves, mutes, goes\nfullscreen, reports a problem and changes their Arcade-wide settings.\n\n```js\ngem.setMenu({\n  items: [{ id: 'how-to-play', label: t('How to play'), onSelect: () => help.open() }],\n});\n```\n\n**Your settings screen is not in it: draw your own settings button** —\ntop-right, with your Back button just to its left, clear of\n`gem.viewport.reserved`. The Arcade's menu never opens your settings\nscreen. Inside the Gem Arcade you may leave the button out while this\nreturns `true`, when every setting on your screen is declared with\n`gem.settings` and every action on it is one of these entries; it returns\n`false` before the bridge is up and under an embedder with no menu, and the\nbutton stays there.\n\n**It is screen state, not a toggle.** Each call is the whole answer and\nreplaces the last, so call it again when the entries change — a new\nlanguage, a screen with different options. `gem.setMenu({})` takes\neverything of yours back out. The arcade's own entries are not yours to\nchange, and Return to the Arcade is always among them.\n\n**The arcade pauses your game while its menu is open** (`onPause`), and\nresumes it before a handler of yours runs. A handler opens a screen; it\nshould not assume the game was paused by you.",
           "deprecated": null,
           "params": [
             {

package/docs/arcade-and-store.md

@@ -18,11 +18,17 @@ async function onBuyPressed(offer) {
   // Read through gem.me; nothing here carries an amount. `error` is "outcome unknown" (§9).
   if (outcome === 'ok' || reason === 'error') await refreshBalances();
 }
+
+// From the press on your own "Get VIP" button: the Arcade draws the offer.
+async function onVipPressed() {
+  const { outcome, reason } = await gem.store.showOffer(VIP_SKU);
+  if (outcome === 'ok' || reason === 'error') await refreshBalances();
+}
 ```
 
 **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)
@@ -33,15 +39,16 @@ payment itself. You get an outcome.
 - [7. Similar games, as cards](#7-similar-games-as-cards)
 - [8. The Arcade Store's offers](#8-the-arcade-stores-offers)
 - [9. Buying from the Arcade Store](#9-buying-from-the-arcade-store)
-- [10. Outcomes and reasons](#10-outcomes-and-reasons)
+- [10. Letting the Arcade show one offer](#10-letting-the-arcade-show-one-offer)
+- [11. Outcomes and reasons](#11-outcomes-and-reasons)
 
 ## 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) | your card or the Arcade's sheet, then the checkout  |
 
 `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
@@ -60,7 +67,7 @@ three and never grows:
 
 `reason` is a short code that says why. The set is open: a new Arcade build may send a reason your
 game has never seen, so branch on `outcome` and treat `reason` as a hint. The codes in use today are
-in [§10](#10-outcomes-and-reasons).
+in [§11](#11-outcomes-and-reasons).
 
 ## 3. What is available here
 
@@ -71,17 +78,19 @@ An Arcade that does not offer a feature answers every call for it at once with `
 if (gem.arcade.available.openGame) showMoreGamesSection();
 if (gem.arcade.available.appLinks) showGetTheAppButton();
 if (gem.store.available) showGetGemsButton();
+if (gem.store.showOfferAvailable) showGetVipButton();
 ```
 
-`gem.arcade.available` is `{ appLinks, openGame }`, and `gem.store.available` is one boolean. All of
-them are synchronous and `false` until the bridge is up. A feature can be off for reasons you
+`gem.arcade.available` is `{ appLinks, openGame }`, and `gem.store.available` and
+`gem.store.showOfferAvailable` are one boolean each. All of them are synchronous and `false` until
+the bridge is up. A feature can be off for reasons you
 cannot see from inside the frame: a TV, an in-app browser that cannot take payment, an app build
 where it is withheld. Do not guess; read it.
 
 ## 4. Call the acting ones from a press
 
-Three calls put something in front of the player: `gem.arcade.openApp`, `gem.arcade.openGame` and
-`gem.store.purchase`. **Call each one from the player's own press handler**, in the same turn as the
+Four calls put something in front of the player: `gem.arcade.openApp`, `gem.arcade.openGame`,
+`gem.store.purchase` and `gem.store.showOffer`. **Call each one from the player's own press handler**, in the same turn as the
 press. The Arcade checks that a person pressed, and refuses an ask nobody pressed for with
 `declined` / `busy`, showing nothing.
 
@@ -221,7 +230,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 +243,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 +264,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:
@@ -268,7 +282,57 @@ own celebration is visible.
   if (outcome === 'unavailable' && reason === 'error') await refreshBalances(); // not "nothing bought"
   ```
 
-## 10. Outcomes and reasons
+## 10. Letting the Arcade show one offer
+
+```js
+// Decide on the screen you draw the button on.
+const { offers } = await gem.store.offers();
+const vip = offers.find((offer) => offer.skuId === VIP_SKU);
+if (gem.store.showOfferAvailable && vip) showGetVipButton();
+else hideGetVipButton();
+
+// From the press on that button.
+const { outcome, reason } = await gem.store.showOffer(VIP_SKU);
+if (outcome === 'ok' || reason === 'error') await refreshBalances();
+```
+
+`showOffer(skuId)` asks the Arcade to draw one SKU from `offers()` in its own sheet, over your paused
+and hidden game. The Arcade draws the art, what the player gets, a sale if one is running, and, for a
+pass the player already holds, how long it has left. The sheet's Buy opens the same checkout
+`purchase` opens.
+
+Pick by who can say what the offer is:
+
+|                 | **You draw it: `offers()` + `purchase()`**                | **The Arcade draws it: `showOffer()`**                       |
+| --------------- | --------------------------------------------------------- | ------------------------------------------------------------ |
+| Use it for      | Gem packs: a name, an amount and a price say it all       | VIP and other passes, and bundles                            |
+| Your button     | says what it buys and shows `priceDisplay`                | says what it opens, such as "Get VIP"                        |
+| The press opens | the checkout, straight away                               | the Arcade's sheet, then the checkout if the player presses Buy |
+| Perks and sales | not available to you                                      | always current, in the player's language                     |
+| A holder sees   | the same Buy button                                       | what they already have                                       |
+
+- **Never write an offer's perks into your game.** They change without a new build of your game, and
+  yours would go stale. Your button only needs the offer's name.
+- **Do not show a price on the button.** The sheet shows the right one for this player, which a
+  sale or a pass can change, and `priceDisplay` does not say either of those. If you want a price on
+  screen, draw the offer yourself and use `purchase`.
+- **You cannot tell whether the player holds a pass.** The Arcade keeps that to itself, and the
+  sheet tells the player. So the button stays up for a holder, and that is fine: the sheet is what
+  they see, and they choose from there.
+- **Hide the button when the SKU is not in `offers()`.** A SKU that is not on sale here answers
+  `unavailable` / `not_found`, and the player would have pressed a button that does nothing.
+- **Read `showOfferAvailable`, not `available`.** An older Arcade can sell through `purchase` and
+  still not draw this sheet. It answers `unavailable` / `unsupported` and sends nothing. Hide the
+  button there.
+
+Every rule of `purchase` holds ([§9](#9-buying-from-the-arcade-store)), and the answers are the
+same, with one addition. `declined` / `cancelled` also covers the player leaving the sheet without
+pressing Buy, and you are not told which of the two they closed. That starts the same back-off as a
+closed checkout, shared with `purchase`: the next ask of either kind is `declined` / `busy` for a
+while. The press shows nothing during a back-off, so give the player something else to do on that
+screen.
+
+## 11. Outcomes and reasons
 
 | Call             | `ok`                      | `declined`          | `unavailable`                                                                                                 |
 | ---------------- | ------------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------- |
@@ -278,6 +342,7 @@ own celebration is visible.
 | `similarGames`   | cards, possibly none      |                     | `unsupported`, `error`                                                                                        |
 | `store.offers`   | offers, possibly none     |                     | `sign_in_required`, `store_off`, `unsupported`, `error`                                                       |
 | `store.purchase` | paid, or `pending`        | `cancelled`, `busy` | `sign_in_required`, `store_off`, `not_found`, the provider's reason, `unsupported`, `error` (outcome unknown) |
+| `store.showOffer` | paid, or `pending`       | `cancelled`, `busy` | `sign_in_required`, `store_off`, `not_found`, the provider's reason, `unsupported`, `error` (outcome unknown) |
 
 Every reason is a short code of lower-case letters and underscores. The Arcade turns a payment
 provider's own code into that shape before it reaches you.
@@ -291,5 +356,5 @@ Four reasons come from the SDK itself rather than the Arcade:
 - `error`: no reliable answer arrived. The ask could not be sent, a read or an open waited out its
   timeout (30 seconds for a read, two minutes for `openApp` and `openGame`), the bridge closed
   before the answer came, or the Arcade said it had no reliable answer. For a read, try again
-  later. For `store.purchase` it means **the outcome is unknown**, never "nothing was bought"
-  ([§9](#9-buying-from-the-arcade-store)).
+  later. For `store.purchase` and `store.showOffer` it means **the outcome is unknown**, never
+  "nothing was bought" ([§9](#9-buying-from-the-arcade-store)).