@indiegems/gem-web-sdk 16.3.1 → 18.0.0

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

@@ -1,6 +1,6 @@
 # The function surface — API reference
 
-Generated from `@indiegems/gem-web-sdk/function` v16.3.1, 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/function` v18.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/function` exports exactly the symbols on this page and nothing else.
 

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.1, 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` v18.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.
 
@@ -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
@@ -4659,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
@@ -6919,6 +6969,37 @@ A corner of your frame, for `gem.setGemCorner`: where you would like the
 arcade's Gem button to sit. `'top-left'` is where it sits unless you ask.
 Physical corners: `'top-left'` is the top-left in every language.
 
+<a id="menustyle"></a>
+
+## MenuStyle
+
+```ts
+interface MenuStyle
+```
+
+Two colours for the arcade's own screens over your game, for
+`gem.setMenuStyle`: each exactly `#rrggbb`. The arcade works out the rest.
+
+<a id="menustyle-ground"></a>
+
+## MenuStyle.ground
+
+```ts
+readonly ground: string
+```
+
+The colour the arcade's surfaces are built on, such as `'#1b2a4a'`.
+
+<a id="menustyle-accent"></a>
+
+## MenuStyle.accent
+
+```ts
+readonly accent: string
+```
+
+The one highlight, at least 3:1 against `ground`, such as `'#ffb300'`.
+
 <a id="framestate"></a>
 
 ## FrameState
@@ -7296,6 +7377,29 @@ its control.
   up, for an arcade that cannot move its control, for a value that is not
   one of the four corners, and past this frame's own limit.
 
+<a id="gemframe-setmenustyle"></a>
+
+## GemFrame.setMenuStyle
+
+```ts
+setMenuStyle(style: MenuStyle | null): boolean
+```
+
+Give the arcade's own screens over your game two colours to wear, or
+`null` to hand them back to the player's style: the whole answer each
+time, the latest one winning.
+
+Prefer `gem.setMenuStyle`, which checks the colours and holds them across
+a reconnect. This one sends only while connected, and only to an arcade
+that can wear them.
+
+| Parameter | Type |
+| --- | --- |
+| `style` | `MenuStyle \| null` |
+
+**Returns.** whether the message left the frame: `false` before the bridge is
+  up, for an arcade that cannot wear them, and past this frame's own limit.
+
 <a id="gemframe-requestshare"></a>
 
 ## GemFrame.requestShare
@@ -11216,8 +11320,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)
 
@@ -11967,6 +12073,45 @@ with a warning on the console, and changes nothing.
   up (the corner is held and sent when it connects), under an embedder that
   cannot move its control, and for a value that is not a corner.
 
+<a id="gem-setmenustyle"></a>
+
+## Gem.setMenuStyle
+
+```ts
+setMenuStyle(style: MenuStyle | null): boolean
+```
+
+Give the arcade's own screens over your game your colours, so they match
+it: on the Gem Arcade, the burger button, the Gem menu and its pages, and
+every Arcade pop-up over the running game.
+
+```js
+gem.setMenuStyle({ ground: '#1b2a4a', accent: '#ffb300' });
+gem.setMenuStyle(null); // back to the player's own style
+```
+
+**Colours only.** `ground` is what the arcade's surfaces are built on and
+`accent` its one highlight; the arcade works out the text, rims, button
+shapes and fonts, so its screens stay readable on any ground.
+
+**The Arcade refuses colours it cannot use.** Each must be exactly
+`#rrggbb`, and `accent` must reach 3:1 contrast against `ground`. Anything
+else is ignored, with a warning on the console giving the measured ratio:
+the last colours stand, nothing is sent, and this returns `false`.
+
+**Your colours win over the player's chosen style while your game runs**,
+and the player's style comes back when it ends. It is screen state, not a
+toggle: each call is the whole answer, so you may change it between levels.
+Call it at boot, so your colours arrive with the first screen.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `style` | `MenuStyle \| null` | The two colours, or `null` to hand back to the player's style. |
+
+**Returns.** `true` when the arcade was told now; `false` before the bridge is
+  up (the colours are held and sent when it connects), under an embedder
+  that cannot wear them, and for colours it would refuse.
+
 <a id="gem-reportframe"></a>
 
 ## Gem.reportFrame

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.1, 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` v18.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.1"
+    "version": "18.0.0"
   },
   "entries": [
     {
@@ -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",
@@ -5576,6 +5592,29 @@
           "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": [
+            {
+              "name": "skuId",
+              "type": "string",
+              "optional": false,
+              "summary": null
+            }
+          ],
+          "returns": "Always resolves; never rejects.",
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "StoreApi.onSettled",
           "name": "onSettled",
@@ -8265,6 +8304,54 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "MenuStyle",
+          "name": "MenuStyle",
+          "anchor": "menustyle",
+          "group": "frame",
+          "signature": "interface MenuStyle",
+          "documented": true,
+          "summary": "Two colours for the arcade's own screens over your game, for\n`gem.setMenuStyle`: each exactly `#rrggbb`. The arcade works out the rest.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "MenuStyle.ground",
+          "name": "ground",
+          "anchor": "menustyle-ground",
+          "group": "frame",
+          "signature": "readonly ground: string",
+          "documented": true,
+          "summary": "The colour the arcade's surfaces are built on, such as `'#1b2a4a'`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "MenuStyle.accent",
+          "name": "accent",
+          "anchor": "menustyle-accent",
+          "group": "frame",
+          "signature": "readonly accent: string",
+          "documented": true,
+          "summary": "The one highlight, at least 3:1 against `ground`, such as `'#ffb300'`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "FrameState",
           "name": "FrameState",
@@ -8645,6 +8732,29 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "GemFrame.setMenuStyle",
+          "name": "setMenuStyle",
+          "anchor": "gemframe-setmenustyle",
+          "group": "frame",
+          "signature": "setMenuStyle(style: MenuStyle | null): boolean",
+          "documented": true,
+          "summary": "Give the arcade's own screens over your game two colours to wear, or\n`null` to hand them back to the player's style: the whole answer each\ntime, the latest one winning.\n\nPrefer `gem.setMenuStyle`, which checks the colours and holds them across\na reconnect. This one sends only while connected, and only to an arcade\nthat can wear them.",
+          "deprecated": null,
+          "params": [
+            {
+              "name": "style",
+              "type": "MenuStyle | null",
+              "optional": false,
+              "summary": null
+            }
+          ],
+          "returns": "whether the message left the frame: `false` before the bridge is\n  up, for an arcade that cannot wear them, and past this frame's own limit.",
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "GemFrame.requestShare",
           "name": "requestShare",
@@ -12790,7 +12900,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,
@@ -13325,6 +13435,29 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "Gem.setMenuStyle",
+          "name": "setMenuStyle",
+          "anchor": "gem-setmenustyle",
+          "group": "start",
+          "signature": "setMenuStyle(style: MenuStyle | null): boolean",
+          "documented": true,
+          "summary": "Give the arcade's own screens over your game your colours, so they match\nit: on the Gem Arcade, the burger button, the Gem menu and its pages, and\nevery Arcade pop-up over the running game.\n\n```js\ngem.setMenuStyle({ ground: '#1b2a4a', accent: '#ffb300' });\ngem.setMenuStyle(null); // back to the player's own style\n```\n\n**Colours only.** `ground` is what the arcade's surfaces are built on and\n`accent` its one highlight; the arcade works out the text, rims, button\nshapes and fonts, so its screens stay readable on any ground.\n\n**The Arcade refuses colours it cannot use.** Each must be exactly\n`#rrggbb`, and `accent` must reach 3:1 contrast against `ground`. Anything\nelse is ignored, with a warning on the console giving the measured ratio:\nthe last colours stand, nothing is sent, and this returns `false`.\n\n**Your colours win over the player's chosen style while your game runs**,\nand the player's style comes back when it ends. It is screen state, not a\ntoggle: each call is the whole answer, so you may change it between levels.\nCall it at boot, so your colours arrive with the first screen.",
+          "deprecated": null,
+          "params": [
+            {
+              "name": "style",
+              "type": "MenuStyle | null",
+              "optional": false,
+              "summary": "The two colours, or `null` to hand back to the player's style."
+            }
+          ],
+          "returns": "`true` when the arcade was told now; `false` before the bridge is\n  up (the colours are held and sent when it connects), under an embedder\n  that cannot wear them, and for colours it would refuse.",
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "Gem.reportFrame",
           "name": "reportFrame",

package/docs/arcade-and-store.md

@@ -18,6 +18,12 @@ 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
@@ -33,7 +39,8 @@ 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
 
@@ -41,7 +48,7 @@ itself. You get an outcome.
 | ------------ | ------------------------------------------------ | --------------------------------------------------- |
 | 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      |
+| 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.
 
@@ -273,7 +282,57 @@ arrives, so your 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`                                                                                                 |
 | ---------------- | ------------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------- |
@@ -283,6 +342,7 @@ arrives, so your 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.
@@ -296,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)).

package/docs/arcade-economy.md

@@ -204,9 +204,9 @@ 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, opens its own checkout and
-takes the money ([arcade-and-store.md](arcade-and-store.md)). The real-money product that changes
+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×
@@ -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 checkout 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/changelog.md

@@ -16,6 +16,46 @@ 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.
 
+## 18.0.0
+
+Upgrading from 17.0.0. Impact: required.
+
+### Rebuild
+
+- The set of capability names a game can query has a new member, menuStyle. Recompiling is enough, but if your code handles every capability name exhaustively, add a case for the new one.
+- The frame message type has a new member for menu style, and the list of messages a game frame sends to the Arcade now includes gem.menuStyle. Recompiling is enough, but code that handles every message exhaustively needs a case for the new message.
+
+### New capability
+
+- A game can now hand the Arcade its own colours for the Arcade menu by calling Gem.setMenuStyle with a MenuStyle value. Check for the menuStyle capability first, since an older Arcade will not act on it. The same call is also available on the frame object.
+
+## 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.

package/docs/getting-started.md

@@ -50,7 +50,7 @@ either way.
 ```jsonc
 // package.json
 "dependencies": {
-  "@indiegems/gem-web-sdk": "16.3.1"
+  "@indiegems/gem-web-sdk": "18.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 checkout 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