@indiegems/gem-web-sdk 15.3.2 → 16.0.0

package/schema/bridge.v1.json

@@ -3767,11 +3767,16 @@
         "    - A DISMISSAL BACKS OFF, and the confirm control is quiet after paint",
         "      (both below; the arcade holds the quiet period for 400 ms).",
         "    - A SHORTFALL IS NEVER A SALE. `insufficient_funds` gets no top-up, no",
-        "      upsell and no way into a store, from the parent or from the game. A",
-        "      game cannot open the arcade's store, and no message here asks for it.",
-        "    - MONEY IS TAKEN ONLY ON THE PAYMENT PROVIDER'S PAGE, which a player",
-        "      reaches through the parent's own chrome. Nothing a frame sends starts",
-        "      a payment or carries a card field.",
+        "      upsell and no way into a store from THIS sheet. A game MAY open the",
+        "      arcade's store for one of the store's own SKUs -",
+        "      gem.requestStorePurchase, gated on `store` -",
+        "      but only from the player's press on a button of the game's; that",
+        "      sheet is the Arcade Store's, under its own rules, and nothing opens",
+        "      it by itself on a refusal here.",
+        "    - MONEY IS TAKEN ONLY ON THE PAYMENT PROVIDER'S PAGE OR THE OPERATING",
+        "      SYSTEM'S PURCHASE SHEET, which a player reaches through the parent's",
+        "      own chrome. Nothing a frame sends carries a price or a card field,",
+        "      and no payment starts without the player's own press there.",
         "",
         "  THE FRAME CHOOSES THE AMOUNT. Not the unit price - but `targetId` x",
         "  `currencySlug` x `quantity` is nevertheless the total, up to ten times the",
@@ -4834,6 +4839,731 @@
         }
       },
       "rateLimit": { "perMinute": 30 }
+    },
+    {
+      "type": "gem.requestAppLinks",
+      "direction": "frameToParent",
+      "transport": "port",
+      "$comment": [
+        "Ask which app listings the player can be sent to from here: the Gem",
+        "Arcade app's, and this game's own. Gated by the `appLinks` capability.",
+        "Answered by `gem.appLinksResult`.",
+        "",
+        "A READ, NOT AN ACT. It renders nothing and opens nothing, so it needs",
+        "no user activation and takes no part in the acting-message mutex. A",
+        "game asks so it can draw the right store badge, or no badge at all,",
+        "before the player presses anything; the press is `gem.requestOpenApp`.",
+        "",
+        "NOTHING BUT THE CORRELATOR IS SENT. The parent knows which game it",
+        "framed and which platform the player is on; a game id or a platform",
+        "the frame supplied would be one the frame chose."
+      ],
+      "fields": {
+        "requestId": {
+          "kind": "string",
+          "maxLength": 64,
+          "$comment": "Opaque and frame-chosen. Echo-only, exactly as on gem.requestPurchase: not unique across tabs or reloads, never a key, and not safe to write into a log line unescaped."
+        }
+      },
+      "rateLimit": { "perMinute": 12 }
+    },
+    {
+      "type": "gem.appLinksResult",
+      "direction": "parentToFrame",
+      "transport": "port",
+      "$comment": [
+        "The answer to one gem.requestAppLinks. Gated by the `appLinks`",
+        "capability.",
+        "",
+        "WHICH STORE, NEVER A URL. `arcade` is present when `gem.requestOpenApp`",
+        "with target `arcade` would open a store listing from here; `game` when",
+        "target `game` would. Each says which store it is, so a game can draw the",
+        "matching badge. The link itself is built by the parent from a fixed",
+        "template and never crosses: a URL the frame could read is a URL the",
+        "frame could be tricked into trusting, and a URL the frame could send",
+        "back is a redirect it chose.",
+        "",
+        "ABSENT MEANS NO LISTING HERE: a desktop browser, a platform without a",
+        "listing yet, or the player already inside that app (the outcome is",
+        "still `ok`; `reason` may say `already_in_app`). A game hides the button",
+        "for an absent entry.",
+        "",
+        "OUTCOMES, closed at three as gem.purchaseResult's are:",
+        "  ok          - the answer is in `arcade` and `game`, either or both",
+        "                of which may be absent.",
+        "  declined    - the parent chose not to answer.",
+        "  unavailable - no reliable answer. A game hides both buttons.",
+        "Everything finer is `reason`, an open code."
+      ],
+      "fields": {
+        "requestId": {
+          "kind": "string",
+          "maxLength": 64,
+          "$comment": "Echoes the gem.requestAppLinks that asked. Echo-only."
+        },
+        "outcome": {
+          "kind": "enum",
+          "values": ["ok", "declined", "unavailable"],
+          "$comment": "THREE VALUES, CLOSED for gem.purchaseResult's reason: `check-schema-freeze` treats a new enum value as breaking, so the vocabulary that may grow lives in `reason`."
+        },
+        "reason": {
+          "kind": "string",
+          "maxLength": 64,
+          "format": "code",
+          "optional": true,
+          "$comment": "WHY, as an open machine code (`^[a-z_]{1,64}$`): `already_in_app`, `store_off`, `error` and whatever the parent adds later. Normalized to the code grammar before it is sent, as gem.storePurchaseResult's. A receiver maps a code it does not know to its own fallback and must not fail on one. Advisory: a game branches on `outcome` and on which entries are present, never on this."
+        },
+        "arcade": {
+          "kind": "object",
+          "optional": true,
+          "$comment": "Present when the Gem Arcade app has a store listing the parent can open from here. Absent inside the Gem Arcade app itself.",
+          "fields": {
+            "store": {
+              "kind": "enum",
+              "values": ["app_store", "google_play"],
+              "$comment": "Which store the listing is in, for the badge. A store that is not one of these is a new optional field behind a capability of its own, never a third value here: an N-1 frame would refuse the whole message."
+            }
+          }
+        },
+        "game": {
+          "kind": "object",
+          "optional": true,
+          "$comment": "Present when THIS game has its own app recorded for the player's platform (staff-recorded, a store id per platform, never a URL). Absent when it has none, or inside that app's own wrapper.",
+          "fields": {
+            "store": {
+              "kind": "enum",
+              "values": ["app_store", "google_play"],
+              "$comment": "As `arcade.store`."
+            }
+          }
+        }
+      },
+      "rateLimit": { "perMinute": 30 }
+    },
+    {
+      "type": "gem.requestOpenApp",
+      "direction": "frameToParent",
+      "transport": "port",
+      "$comment": [
+        "Ask the parent to open a store listing: the Gem Arcade app's",
+        "(`target: arcade`) or this game's own (`target: game`). Gated by the",
+        "`appLinks` capability. Answered by `gem.openAppResult`.",
+        "",
+        "AN ACTING MESSAGE. It leaves the game, so the parent holds it to the",
+        "rules every acting message shares (gem.requestOpenGame and",
+        "gem.requestStorePurchase state them too):",
+        "",
+        "  A PERSON MUST HAVE PRESSED. Read `navigator.userActivation.isActive`",
+        "  synchronously on receipt, before any `await`, or accept a controller",
+        "  press the PARENT PAGE observed itself. A pad press the frame reports is",
+        "  never trusted. A missing `userActivation` API FAILS CLOSED. Without a",
+        "  press, answer `declined` / `busy` and show nothing.",
+        "",
+        "  ONE AT A TIME, ACROSS EVERY ACTING MESSAGE. While this, an open-game,",
+        "  a store purchase, a gem.requestPurchase, a share or a friend challenge",
+        "  is open, answer `declined` / `busy` and show nothing.",
+        "",
+        "  BOTH BEFORE RESOLVING ANYTHING. Activation and the mutex are checked",
+        "  before the target is looked up, so a refusal says nothing about it.",
+        "",
+        "  BOUND TO THE FRAME SESSION. An answer for a frame that has since gone",
+        "  is dropped, never delivered to whatever game is framed next.",
+        "",
+        "THE PARENT BUILDS THE URL from a fixed template and the store id it",
+        "holds (never from anything in this message), rechecks it against the",
+        "template's host and path, and opens it with `noopener,noreferrer` or the",
+        "app shell's allowlisted external-link path. Where it cannot open one (a",
+        "TV, a refused pop-up) it shows its own sheet with a QR code and the",
+        "short URL as text, and answers `ok` / `handed_off`.",
+        "",
+        "ANSWERED AT THE HAND-OFF, never later: as the listing's window or the",
+        "store app opens, or as the QR sheet goes up. The answer never waits on",
+        "the player closing the sheet, so it always arrives well inside the",
+        "game's two-minute wait. Closing the sheet is not reported; while it is",
+        "up, it still holds the one acting slot, and a second acting ask is",
+        "`declined` / `busy`."
+      ],
+      "fields": {
+        "requestId": {
+          "kind": "string",
+          "maxLength": 64,
+          "$comment": "Opaque and frame-chosen. Echo-only."
+        },
+        "target": {
+          "kind": "enum",
+          "values": ["arcade", "game"],
+          "$comment": "Which listing. A closed set, so the validator refuses anything else at the boundary. The parent resolves the listing itself; nothing here names a store, a platform or a URL."
+        }
+      },
+      "rateLimit": {
+        "perMinute": 6,
+        "$comment": "gem.requestShare's limit: it bounds a BUGGY game. NOT a security control: a hostile game posts on the port it holds rather than calling the SDK. What bounds the player's experience is the parent's activation check and its one-at-a-time rule."
+      }
+    },
+    {
+      "type": "gem.openAppResult",
+      "direction": "parentToFrame",
+      "transport": "port",
+      "$comment": [
+        "The answer to one gem.requestOpenApp. Gated by the `appLinks`",
+        "capability.",
+        "",
+        "  ok          - the listing opened, in a new tab or the store app, or",
+        "                (`reason: handed_off`) the parent showed its own QR",
+        "                sheet. The game carries on; nothing left the page.",
+        "  declined    - nothing was opened: no press, or another acting",
+        "                message open (`busy`).",
+        "  unavailable - there is no such listing here (`already_in_app`,",
+        "                `not_found`), or no reliable answer.",
+        "",
+        "NEVER AUTO-RETRIED. Only a fresh press may ask again."
+      ],
+      "fields": {
+        "requestId": {
+          "kind": "string",
+          "maxLength": 64,
+          "$comment": "Echoes the gem.requestOpenApp that asked. Echo-only."
+        },
+        "outcome": {
+          "kind": "enum",
+          "values": ["ok", "declined", "unavailable"],
+          "$comment": "Closed at three, as gem.appLinksResult's."
+        },
+        "reason": {
+          "kind": "string",
+          "maxLength": 64,
+          "format": "code",
+          "optional": true,
+          "$comment": "An open code, on any outcome: `handed_off` with `ok`; `busy` with `declined`; `already_in_app`, `not_found` or `error` 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 }
+    },
+    {
+      "type": "gem.requestOpenGame",
+      "direction": "frameToParent",
+      "transport": "port",
+      "$comment": [
+        "Ask the parent to open ANOTHER game in place of this one. Gated by the",
+        "`openGame` capability. Answered by `gem.openGameResult`.",
+        "",
+        "AN ACTING MESSAGE, under every rule gem.requestOpenApp states: a press",
+        "the parent can see (a missing `userActivation` API fails closed), one",
+        "acting message at a time, both checked before `ref` is resolved, and the",
+        "answer bound to this frame session.",
+        "",
+        "WHAT THE PARENT DOES WITH IT. It resolves `ref` with the platform for",
+        "the session's channel, exactly as its own `/play/<ref>` route would, and",
+        "answers before it moves:",
+        "",
+        "  - unknown, hidden, not on this channel, the wrong engine or the wrong",
+        "    form factor: `unavailable` / `not_found`, with no difference between",
+        "    \"does not exist\" and \"you may not see it\";",
+        "  - this same game: `declined` / `same_game`;",
+        "  - otherwise `ok`, then its own non-interactive \"Opening <game>\" card",
+        "    over this game's hidden frame, then `gem.willTerminate` with the",
+        "    ordinary save grace, then the other game. Back returns the player",
+        "    to this game's page, never relaunching it by itself.",
+        "",
+        "NO CONFIRMATION SHEET, by owner decision: games are developed in-house",
+        "and trusted, and the parent's card still shows that the Arcade moved the",
+        "player. If third-party games ever ship, this is revisited first."
+      ],
+      "fields": {
+        "requestId": {
+          "kind": "string",
+          "maxLength": 64,
+          "$comment": "Opaque and frame-chosen. Echo-only."
+        },
+        "ref": {
+          "kind": "string",
+          "maxLength": 40,
+          "format": "gameRef",
+          "$comment": "The game to open: its id (a UUID) or its web address (a URL slug: 3 to 40 lower-case letters, digits and single hyphens, starting and ending with a letter or digit), exactly what the parent's `/play/<ref>` route accepts. The `gameRef` format holds it to that grammar at both ends, so nothing else reaches a lookup. Whether it names a game the player may open is the platform's to judge."
+        }
+      },
+      "rateLimit": {
+        "perMinute": 6,
+        "$comment": "gem.requestOpenApp's limit and its argument: it bounds a BUGGY game, not a hostile one."
+      }
+    },
+    {
+      "type": "gem.openGameResult",
+      "direction": "parentToFrame",
+      "transport": "port",
+      "$comment": [
+        "The answer to one gem.requestOpenGame. Gated by the `openGame`",
+        "capability.",
+        "",
+        "  ok          - the other game is opening. `gem.willTerminate` follows;",
+        "                save then, not after this.",
+        "  declined    - nothing moved: no press or another acting message open",
+        "                (`busy`), or `ref` names this game (`same_game`).",
+        "  unavailable - no game the player can open here (`not_found`), or no",
+        "                reliable answer.",
+        "",
+        "NEVER AUTO-RETRIED. Only a fresh press may ask again."
+      ],
+      "fields": {
+        "requestId": {
+          "kind": "string",
+          "maxLength": 64,
+          "$comment": "Echoes the gem.requestOpenGame that asked. Echo-only."
+        },
+        "outcome": {
+          "kind": "enum",
+          "values": ["ok", "declined", "unavailable"],
+          "$comment": "Closed at three, as gem.appLinksResult's."
+        },
+        "reason": {
+          "kind": "string",
+          "maxLength": 64,
+          "format": "code",
+          "optional": true,
+          "$comment": "An open code: `busy` or `same_game` with `declined`; `not_found` or `error` 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 }
+    },
+    {
+      "type": "gem.requestSimilarGames",
+      "direction": "frameToParent",
+      "transport": "port",
+      "$comment": [
+        "Ask for games like this one, as the Arcade home page shows them. Gated",
+        "by the `openGame` capability, because a list of games is useful only",
+        "beside the message that opens one. Answered by `gem.similarGamesResult`.",
+        "",
+        "A READ, NOT AN ACT: no activation, no mutex. The parent asks the",
+        "platform's similar-games read for the game it framed (never a game the",
+        "frame names), on the release channel, browser games only, never",
+        "personalized."
+      ],
+      "fields": {
+        "requestId": {
+          "kind": "string",
+          "maxLength": 64,
+          "$comment": "Opaque and frame-chosen. Echo-only."
+        },
+        "limit": {
+          "kind": "int",
+          "min": 1,
+          "max": 24,
+          "optional": true,
+          "$comment": "How many games at most. Absent means 12. The bound matches the platform's own, so a limit the SDK accepts is one the read honours."
+        }
+      },
+      "rateLimit": { "perMinute": 12 }
+    },
+    {
+      "type": "gem.similarGamesResult",
+      "direction": "parentToFrame",
+      "transport": "port",
+      "maxBytes": 524288,
+      "$comment": [
+        "The answer to one gem.requestSimilarGames. Gated by the `openGame`",
+        "capability.",
+        "",
+        "`games` holds up to 24 cards, best first, and is empty unless the",
+        "outcome is `ok` (an `ok` may be empty too: hide the section). Each card",
+        "is what an Arcade home tile shows. The parent leaves `previewVideoUrl`",
+        "out under reduced motion, data saver or a phone form factor, which the",
+        "frame cannot see for itself.",
+        "",
+        "ANOTHER DEVELOPER'S TEXT, AND MARKED SO. A card's name, tagline, short",
+        "description and tags are written by the other game's team, so they sit",
+        "under `untrusted`, as a player's name does on gem.player, and the SDK",
+        "hands them to the game as `PlayerText`. Render them as text, never as",
+        "markup. Outside `untrusted` a card carries only platform values: ids, a",
+        "slug that has passed the platform's own grammar, and platform media",
+        "URLs.",
+        "",
+        "ITS OWN BYTE CAP, `maxBytes`, above the protocol's `maxMessageBytes`.",
+        "Twenty-four cards of five media URLs each (signed URLs run to several",
+        "hundred characters) do not fit the protocol's 64 KB at the walk's three",
+        "bytes a character. It is parent-to-frame only, so the receiver is the",
+        "game, and a frame that predates it never advertised `openGame` and is",
+        "never sent one."
+      ],
+      "fields": {
+        "requestId": {
+          "kind": "string",
+          "maxLength": 64,
+          "$comment": "Echoes the gem.requestSimilarGames that asked. Echo-only."
+        },
+        "outcome": {
+          "kind": "enum",
+          "values": ["ok", "declined", "unavailable"],
+          "$comment": "Closed at three, as gem.appLinksResult's."
+        },
+        "reason": {
+          "kind": "string",
+          "maxLength": 64,
+          "format": "code",
+          "optional": true,
+          "$comment": "An open code, sent with `declined` or `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."
+        },
+        "games": {
+          "kind": "array",
+          "maxItems": 24,
+          "$comment": "The cards, best first. Empty unless `ok`.",
+          "items": {
+            "kind": "object",
+            "fields": {
+              "gameId": {
+                "kind": "string",
+                "maxLength": 36,
+                "format": "gameRef",
+                "$comment": "The game's id, a UUID: what gem.requestOpenGame's `ref` takes."
+              },
+              "slug": {
+                "kind": "string",
+                "maxLength": 40,
+                "format": "gameRef",
+                "optional": true,
+                "$comment": "The game's web address, when it has one. Absent for a game with none."
+              },
+              "iconUrl": {
+                "kind": "string",
+                "maxLength": 1024,
+                "format": "url",
+                "$comment": "The game's icon, on the platform's media host. Structurally validated only; see gem.player.avatarIconUrl for what the format does not do."
+              },
+              "capsuleLandscapeUrl": {
+                "kind": "string",
+                "maxLength": 1024,
+                "format": "url",
+                "$comment": "The landscape tile art, as the home page draws it."
+              },
+              "capsulePortraitUrl": {
+                "kind": "string",
+                "maxLength": 1024,
+                "format": "url",
+                "$comment": "The portrait tile art."
+              },
+              "previewVideoUrl": {
+                "kind": "string",
+                "maxLength": 1024,
+                "format": "url",
+                "optional": true,
+                "$comment": "The tile's hover clip. Absent when the game has none, and whenever the parent judges a clip unwelcome: reduced motion, data saver, a phone."
+              },
+              "previewPosterUrl": {
+                "kind": "string",
+                "maxLength": 1024,
+                "format": "url",
+                "optional": true,
+                "$comment": "The still shown before and instead of the clip."
+              },
+              "untrusted": {
+                "kind": "object",
+                "$comment": "Text the OTHER game's team wrote. Never markup; see the message comment.",
+                "fields": {
+                  "name": {
+                    "kind": "string",
+                    "maxLength": 64,
+                    "$comment": "The game's public name."
+                  },
+                  "tagline": {
+                    "kind": "string",
+                    "maxLength": 64,
+                    "$comment": "One line under the name. May be empty."
+                  },
+                  "shortDescription": {
+                    "kind": "string",
+                    "maxLength": 320,
+                    "$comment": "A sentence or two. May be empty."
+                  },
+                  "tags": {
+                    "kind": "array",
+                    "maxItems": 10,
+                    "items": { "kind": "string", "maxLength": 32 },
+                    "$comment": "The game's store tags, as shown on the tile."
+                  }
+                }
+              }
+            }
+          }
+        }
+      },
+      "rateLimit": { "perMinute": 30 }
+    },
+    {
+      "type": "gem.requestStoreOffers",
+      "direction": "frameToParent",
+      "transport": "port",
+      "$comment": [
+        "Ask what the Arcade Store sells to this player, here, for real money:",
+        "Gem packs, Boosts, passes and bundles. Gated by the `store` capability.",
+        "Answered by `gem.storeOffersResult`.",
+        "",
+        "WHY THE PARENT ANSWERS IT. The price a player pays depends on the",
+        "payment rail the parent is on - the website's checkout or the app",
+        "store's own price - which only the parent knows, and the platform's",
+        "listing reads need the account session the frame never holds. So the",
+        "parent reads the same listing its own Arcade Store shows, minus",
+        "per-player offers (the daily deal, a first-purchase special), with",
+        "names in the same localization the store shows and prices formatted by",
+        "the active rail. A SKU the app store does not return is left out.",
+        "",
+        "A READ, NOT AN ACT: no activation, no mutex. Per-session state comes",
+        "back as a reason: `store_off` where the store is withheld (an age or",
+        "region policy, a TV, an in-app browser that takes no payment) and",
+        "`sign_in_required` for a guest, who may then be offered",
+        "gem.requestSignIn."
+      ],
+      "fields": {
+        "requestId": {
+          "kind": "string",
+          "maxLength": 64,
+          "$comment": "Opaque and frame-chosen. Echo-only."
+        }
+      },
+      "rateLimit": { "perMinute": 12 }
+    },
+    {
+      "type": "gem.storeOffersResult",
+      "direction": "parentToFrame",
+      "transport": "port",
+      "maxBytes": 262144,
+      "$comment": [
+        "The answer to one gem.requestStoreOffers. Gated by the `store`",
+        "capability.",
+        "",
+        "`offers` is empty unless the outcome is `ok`. Each is one SKU the",
+        "player could buy here right now through gem.requestStorePurchase.",
+        "",
+        "WHAT IS NOT HERE, deliberately. No numeric price: `priceDisplay` is the",
+        "rail's own formatted string, and a game shows it exactly as given,",
+        "never parsing it or computing a discount from it. No balance. And no",
+        "per-offer availability flag: one would reveal a recent purchase through",
+        "its cooldown, so the parent's sheet explains a cooldown instead.",
+        "",
+        "THE NAMES ARE THE PLATFORM'S, not a game developer's: the Arcade",
+        "Store's own catalog copy, which is why `name` and `description` sit",
+        "outside an `untrusted` object.",
+        "",
+        "ITS OWN BYTE CAP, `maxBytes`, on gem.similarGamesResult's argument: a",
+        "full catalog of offers with art does not fit the protocol's 64 KB at",
+        "the walk's arithmetic, and the receiver is the game."
+      ],
+      "fields": {
+        "requestId": {
+          "kind": "string",
+          "maxLength": 64,
+          "$comment": "Echoes the gem.requestStoreOffers that asked. Echo-only."
+        },
+        "outcome": {
+          "kind": "enum",
+          "values": ["ok", "declined", "unavailable"],
+          "$comment": "Closed at three, as gem.appLinksResult's."
+        },
+        "reason": {
+          "kind": "string",
+          "maxLength": 64,
+          "format": "code",
+          "optional": true,
+          "$comment": "An open code, sent with `declined` or `unavailable`: `store_off`, `sign_in_required`, `error`. 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."
+        },
+        "offers": {
+          "kind": "array",
+          "maxItems": 32,
+          "$comment": "What the store sells here, in the store's own order. Empty unless `ok`.",
+          "items": {
+            "kind": "object",
+            "fields": {
+              "skuId": {
+                "kind": "string",
+                "maxLength": 64,
+                "$comment": "The platform's SKU id: what gem.requestStorePurchase's `skuId` takes."
+              },
+              "kind": {
+                "kind": "enum",
+                "values": ["gem_pack", "boost", "pass", "bundle"],
+                "$comment": "What sort of thing it is. A new sort of SKU is left out of this list by the parent, never sent as a fifth value: an N-1 frame would refuse the whole message."
+              },
+              "name": {
+                "kind": "string",
+                "maxLength": 80,
+                "$comment": "The store's own name for it, localized as the store shows it."
+              },
+              "description": {
+                "kind": "string",
+                "maxLength": 400,
+                "$comment": "What the player gets, in the store's words. May be empty."
+              },
+              "imageUrl": {
+                "kind": "string",
+                "maxLength": 1024,
+                "format": "url",
+                "optional": true,
+                "$comment": "The SKU's art on the platform's media host. Absent when it has none; the offer is still listed."
+              },
+              "priceDisplay": {
+                "kind": "string",
+                "maxLength": 32,
+                "$comment": "The price, formatted by the active payment rail in the player's storefront currency. Show it exactly as given."
+              },
+              "grant": {
+                "kind": "object",
+                "optional": true,
+                "$comment": "For a Gem pack: the currency and amount it grants. Absent for every other kind.",
+                "fields": {
+                  "currency": {
+                    "kind": "string",
+                    "maxLength": 32,
+                    "$comment": "The platform currency's exact slug, e.g. GEMS."
+                  },
+                  "amount": {
+                    "kind": "int",
+                    "min": 1,
+                    "max": 1000000000,
+                    "$comment": "How much of it."
+                  }
+                }
+              }
+            }
+          }
+        }
+      },
+      "rateLimit": { "perMinute": 30 }
+    },
+    {
+      "type": "gem.requestStorePurchase",
+      "direction": "frameToParent",
+      "transport": "port",
+      "$comment": [
+        "Ask the parent to open the Arcade Store's purchase sheet for ONE SKU it",
+        "listed in gem.storeOffersResult - real money, not Gems. Gated by the",
+        "`store` capability. Answered by `gem.storePurchaseResult`.",
+        "",
+        "THE GAME ASKS; THE PLATFORM SELLS. Nothing in this message is a price,",
+        "a card field, a URL or a token. The parent renders its own sheet from",
+        "platform records, takes money only on the payment provider's page or",
+        "the operating system's purchase sheet, and tells the game the outcome.",
+        "",
+        "AN ACTING MESSAGE, under every rule gem.requestOpenApp states: a press",
+        "the parent can see (a missing `userActivation` API fails closed), one",
+        "acting message at a time across all of them, both checked before",
+        "`skuId` is resolved, and the answer bound to this frame session. And:",
+        "",
+        "  ONLY A SKU IT WOULD LIST. `skuId` must be one gem.storeOffersResult",
+        "  would list to this player right now; anything else is `unavailable`",
+        "  with nothing shown.",
+        "",
+        "  THE STORE'S OWN SHEET. Over the paused game, hidden not dimmed, with",
+        "  the parent's bar saying the Arcade Store is open, game chrome frozen,",
+        "  and focus never landing on a money control. \"Not now\" has the",
+        "  default focus. Buy arms visibly for a moment and then takes a FRESH",
+        "  press; input during arming restarts it.",
+        "",
+        "  BACK OFF AFTER A DISMISSAL. `cancelled` is disclosed, so after the",
+        "  player dismisses a sheet a game started, further asks from that game",
+        "  are `declined` / `busy`, unrendered, for an interval that grows with",
+        "  each dismissal (the Arcade: 30 s, 2 min, 10 min, then the rest of the",
+        "  session).",
+        "",
+        "  RESUME, THEN ANSWER. The result is sent after the game has been told",
+        "  it is resumed, so the game's own celebration is visible.",
+        "",
+        "  EVIDENCE, NOT ACCOUNTING. The parent marks the checkout as started by",
+        "  a game, with the game it framed, for attribution only.",
+        "",
+        "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.requestPurchase'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.storePurchaseResult",
+      "direction": "parentToFrame",
+      "transport": "port",
+      "$comment": [
+        "The answer to one gem.requestStorePurchase. Gated by the `store`",
+        "capability.",
+        "",
+        "  ok          - the player paid. With no reason, fulfilment has",
+        "                settled: re-read balances and inventory through",
+        "                `gem.me`; nothing here carries an amount. With",
+        "                `reason: pending`, the provider has not settled yet (or",
+        "                the player left before it did): `gem.storePurchaseSettled`",
+        "                follows when it does, and a game re-reads on resume too.",
+        "  declined    - nothing was bought: the player dismissed the sheet",
+        "                (`cancelled`), or no press, another acting message open",
+        "                or a back-off running (`busy`).",
+        "  unavailable - no sale the parent can vouch for. With `store_off`",
+        "                (the store withheld), `sign_in_required` (a guest),",
+        "                `not_found` (an unknown SKU) or the provider's own",
+        "                failure code, nothing was bought. With `error`, the",
+        "                OUTCOME IS UNKNOWN: the parent has no reliable answer, and",
+        "                the player may have paid. The SDK resolves the same",
+        "                `unavailable` / `error` when the port closes under an open",
+        "                purchase, which can be after the player paid. A game",
+        "                re-reads balances and inventory through `gem.me` and",
+        "                keeps listening for gem.storePurchaseSettled.",
+        "",
+        "NO TIMEOUT ON THE GAME'S SIDE while the port is alive: the parent always",
+        "answers, and settlement can take as long as the provider takes.",
+        "NEVER AUTO-RETRIED. Only a fresh press may ask again."
+      ],
+      "fields": {
+        "requestId": {
+          "kind": "string",
+          "maxLength": 64,
+          "$comment": "Echoes the gem.requestStorePurchase 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`. The parent normalizes every reason to the code grammar before it is sent, a provider's code included, and sends `error` when nothing is left — GemHost's answer methods lower-case it, map any other character to `_` and cut it to 64 — so a malformed code never fails outbound validation and leaves the purchase waiting. A receiver must not fail on a code it does not know."
+        }
+      },
+      "rateLimit": { "perMinute": 30 }
+    },
+    {
+      "type": "gem.storePurchaseSettled",
+      "direction": "parentToFrame",
+      "transport": "port",
+      "$comment": [
+        "A store purchase this game started, answered `ok` / `pending`, has",
+        "since settled. Gated by the `store` capability. Pushed, unasked, once",
+        "per such purchase while the frame session lasts; a purchase that",
+        "settles after the frame has gone is not reported to the next one.",
+        "",
+        "A HINT, NOT A RECEIPT. It carries the SKU and nothing else: no amount,",
+        "no order id. A game re-reads balances and inventory through `gem.me`,",
+        "which is where the truth is."
+      ],
+      "fields": {
+        "skuId": {
+          "kind": "string",
+          "maxLength": 64,
+          "$comment": "The SKU the settled purchase was for, as the game asked for it."
+        }
+      },
+      "rateLimit": { "perMinute": 30 }
     }
   ],