@indiegems/gem-web-sdk 16.3.1 → 17.0.0

package/docs/api/reference.json

@@ -2,7 +2,7 @@
   "schema_version": 2,
   "source": {
     "repo": "IndieGems/gem-web-sdk",
-    "version": "16.3.1"
+    "version": "17.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",
@@ -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,

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,33 @@ 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.

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": "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 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

package/docs/manifest.json

@@ -18,8 +18,8 @@
     },
     {
       "file": "arcade-and-store.md",
-      "sha256": "e055b2b1ec540da9fae8f41c025de99b0faec29cef8fca35285ee34e23120941",
-      "updated": "2026-10-29T23:35:13Z"
+      "sha256": "7320826529435d290159c8b0707f69819124607d1b38160dbc85f63b385fdea9",
+      "updated": "2026-10-30T13:36:37Z"
     },
     {
       "file": "arcade-avatars.md",
@@ -28,8 +28,8 @@
     },
     {
       "file": "arcade-economy.md",
-      "sha256": "f0bdc98d765fa4794090fc035d2c32d9c125cbdae58ba89fb5e76fcf1fb9da94",
-      "updated": "2026-10-29T23:35:13Z"
+      "sha256": "b72474b4694842a1fda030ab9df79987d2906f7a8c922e8630622d747a4b2c3c",
+      "updated": "2026-10-30T13:36:37Z"
     },
     {
       "file": "async-opponents.md",
@@ -48,8 +48,8 @@
     },
     {
       "file": "changelog.md",
-      "sha256": "e66efedcc9662bea610d3d4edc4e0125f3078e2b49059770f4553d57f37368b3",
-      "updated": "2026-10-29T23:50:25Z"
+      "sha256": "b795d5ed73558a4d355196971fb4bd9689ca15d38fd01d9a67b4cf6c0e8ff25d",
+      "updated": "2026-10-30T14:09:44Z"
     },
     {
       "file": "daily-challenges.md",
@@ -78,13 +78,13 @@
     },
     {
       "file": "getting-started.md",
-      "sha256": "5f6b7c1e3763cb647379ccc96fc8eb4e5f22551f60cfe56bc6a957312f431fe3",
-      "updated": "2026-10-29T23:50:25Z"
+      "sha256": "a69a8be43e655a71717c1d15ff3e9136103c17eebd9074c2f3dab4fad07d2689",
+      "updated": "2026-10-30T14:09:44Z"
     },
     {
       "file": "inventory-and-catalogs.md",
-      "sha256": "032b911f515a7c81b0bcee6065300049651fef8b2108e7930e1d1354eada7a87",
-      "updated": "2026-10-29T23:35:13Z"
+      "sha256": "9c898355af92ab7e17035bad964dce57b26e64624b18e83149b88ae10b96fd9c",
+      "updated": "2026-10-30T13:36:37Z"
     },
     {
       "file": "leaderboards.md",
@@ -138,8 +138,8 @@
     },
     {
       "file": "server-bundles.md",
-      "sha256": "387d213d3770f21dccb32c94aac57b5af32bcac8bbe5ca9a6c3c2d8d51e5a2a2",
-      "updated": "2026-10-29T23:50:25Z"
+      "sha256": "d00bc2ea3896c2e262619bf87b2892dd954c9ef87d37dfb5881bb6ef7439401a",
+      "updated": "2026-10-30T14:09:44Z"
     },
     {
       "file": "serverless-functions-js.md",

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.1/gem-web-sdk.tgz
-curl -fsSL https://downloads.gemarcade.com/sdk/v16.3.1/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/package.json

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

package/schema/bridge.v1.json

@@ -5581,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"
+      ]
     }
   }
 }