@indiegems/gem-web-sdk 21.0.0 → 21.1.1

package/docs/manifest.json

@@ -13,8 +13,8 @@
     },
     {
       "file": "analytics.md",
-      "sha256": "0883e3c53f500f4d0554d7d62ef938bc53676800b11a285e0da508c6fcc4076d",
-      "updated": "2026-11-02T22:24:57Z"
+      "sha256": "5814655859e3d6b223f94b71f1b064783b0f242d409c3ec3078089cb4b7c8ec5",
+      "updated": "2026-11-04T17:17:14Z"
     },
     {
       "file": "arcade-and-store.md",
@@ -28,8 +28,8 @@
     },
     {
       "file": "arcade-economy.md",
-      "sha256": "b72474b4694842a1fda030ab9df79987d2906f7a8c922e8630622d747a4b2c3c",
-      "updated": "2026-10-30T13:36:37Z"
+      "sha256": "c0f25495a536d5facdbb63cbcd89acf558e2fe79d44f3a99d35284de1937fc42",
+      "updated": "2026-11-04T17:09:56Z"
     },
     {
       "file": "async-opponents.md",
@@ -48,8 +48,8 @@
     },
     {
       "file": "changelog.md",
-      "sha256": "ed2476deed910a61badb23023267b5a8292467d3812c211adf3baf23c42ae914",
-      "updated": "2026-11-03T21:36:35Z"
+      "sha256": "e0cdfb5efc261694e3cca35e23a1e62768db192468cafeae9144835ea7ac99b3",
+      "updated": "2026-11-04T20:17:46Z"
     },
     {
       "file": "daily-challenges.md",
@@ -73,18 +73,23 @@
     },
     {
       "file": "game-economy-tutorial.md",
-      "sha256": "c037a74f206f094392f09e0f7b292271145a4d72b631b93f878705171e52475a",
-      "updated": "2026-10-25T19:46:22Z"
+      "sha256": "0ab25a9d69cf5e40351624355da5ef84e1431bf8a8a420e2c4d7350e20a5b1c5",
+      "updated": "2026-11-04T16:44:33Z"
     },
     {
       "file": "getting-started.md",
-      "sha256": "dd7328fd2462efd7373904f1c14085fd75b046d76670113cd0762825d0c0f107",
-      "updated": "2026-11-03T21:36:35Z"
+      "sha256": "7d2cbe5cf8e26e102f52c8dac279998d11a67d82042b7e6051d1e4fb1548b0a5",
+      "updated": "2026-11-04T20:17:46Z"
+    },
+    {
+      "file": "graphics-route.md",
+      "sha256": "c71c826502b415a89dd069f79d22b82f7a9fe49c9da7f5e7a1052763c826f41f",
+      "updated": "2026-11-04T17:45:35Z"
     },
     {
       "file": "inventory-and-catalogs.md",
-      "sha256": "dab6e42f4ad5cc2a63c2adb11e85053f963cd3166d1c447394cd6f532bb6c006",
-      "updated": "2026-11-02T18:42:37Z"
+      "sha256": "2094c555eb5a1a3d817a597ac07b2b193077f92176eb9596c2ba3ed461363bb6",
+      "updated": "2026-11-04T16:43:14Z"
     },
     {
       "file": "leaderboards.md",
@@ -138,8 +143,8 @@
     },
     {
       "file": "server-bundles.md",
-      "sha256": "736e7b4ceb810944331274f940cb47e7d3d4a57f815340a9ade7ffc5f01cd0fa",
-      "updated": "2026-11-03T21:36:35Z"
+      "sha256": "31eeb1f555faf35123c4f22d072960448ef03f5ac4e76cc8c09748e127a88524",
+      "updated": "2026-11-04T20:17:46Z"
     },
     {
       "file": "serverless-functions-js.md",
@@ -163,8 +168,8 @@
     },
     {
       "file": "what-a-game-must-do.md",
-      "sha256": "059f3c8a31c0f6098d2c8e4836b79e866d0c5486443dc89039e160648946bd68",
-      "updated": "2026-11-02T23:27:22Z"
+      "sha256": "523886cf799570ab3631bbc9db11e03554d2ad403a1083d94038a48acd4fb611",
+      "updated": "2026-11-04T18:23:48Z"
     }
   ]
 }

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/v21.0.0/gem-web-sdk.tgz
-curl -fsSL https://downloads.gemarcade.com/sdk/v21.0.0/gem-web-sdk.tgz.sri
+curl -fsSL -O https://downloads.gemarcade.com/sdk/v21.1.1/gem-web-sdk.tgz
+curl -fsSL https://downloads.gemarcade.com/sdk/v21.1.1/gem-web-sdk.tgz.sri
 openssl dgst -sha384 -binary gem-web-sdk.tgz | openssl base64 -A
 ```
 
@@ -550,7 +550,7 @@ document**, so the call shapes provably match the contract:
 | Loot                      | `getDropRates`                                                                                                                                                                                                                                                                                                                                                                                                                       |
 | Leaderboards              | `getLeaderboard` (the whole board — seed a match from current ranks), `getEntityLeaderboard` (one entity's own runs, best first, with its personal best — the read for deciding a reward from what the player actually did). Not `getFriendLeaderboard`: that view is per viewer, so a credential with no player identity is refused                                                                                                 |
 | Transfers                 | `listTransfers`, `initiateInventoryTransfer`, `getTransferDetails`, `acceptTransfer`, `cancelInventoryTransfer`, `rejectTransfer`                                                                                                                                                                                                                                                                                                    |
-| Platform-funded purchases | `getPurchaseCatalog` — the catalog read only. A **player client** may use `gem.me.mutations.purchase` for a direct platform-currency order because its token fixes the player, game and channel. A dedicated server token names no player and cannot start one; have the player's client initiate it. |
+| Platform-funded purchases | `getPurchaseCatalog` — the catalog read only. A player spends platform currency only through the arcade's purchase sheet, which their **client** opens with `gem.purchases.request` ([inventory-and-catalogs.md](inventory-and-catalogs.md#16-selling-for-a-platform-currency)). A dedicated server token names no player and cannot start one; have the player's client initiate it. |
 | Game rooms                | `getGameRoomV2`, `updateGameRoomV2`, `getRoomArgs`, `putRoomArgs`, `listGameRooms`, `closeGameRoom`, `kickPlayer`, `transferHostV2` — the reads pre-bound to your own room as `gem.room.get()` / `gem.room.args()`. [Below](#what-your-server-reads-at-startup)                                                                                                                                                                      |
 | Game config               | `getChannelAssignment` — which config version your server's own channel is running, and a short-lived signed URL for that version's JSON. Pass `gem.identity.channel`: the read is fenced to your own game and channel |
 | Room templates            | `listResolvedTemplates`, `getResolvedTemplate`                                                                                                                                                                                                                                                                                                                                                                                       |

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

@@ -1454,6 +1454,36 @@ function frame(dt) {
   kind draws that one and ignores the field.
 - **No camera, no call.** A game with no camera to turn never calls `look`.
 
+## WebGL or WebGPU: ask before you make your renderer
+
+Every game that renders with WebGL asks the SDK which renderer to make, just before it makes its
+first one, and follows the answer for every canvas on the page:
+
+```js
+const { route, listed } = await gem.graphics.preferredRoute();
+```
+
+`route` is `webgl` almost everywhere. It is `webgpu` only on a device the platform lists as broken
+on WebGL (today the Pixel 10's PowerVR D-Series GPU, on every route but Vulkan, where WebGL crashes
+the game in Chrome and the whole Arcade app), and only where WebGPU is available. `listed` is true
+on such a device. So:
+
+- `route` is `webgpu`: make your WebGPU renderer, and check it really started on WebGPU (with
+  three.js, `renderer.backend.isWebGPUBackend` after `await renderer.init()`). If it did not, draw
+  your **safe WebGL recipe**.
+- `route` is `webgl` and `listed` is true: draw your safe WebGL recipe. For every listed device
+  today that is no shadow maps.
+- Otherwise: your normal WebGL renderer.
+
+That holds for every WebGL canvas the page makes, menus included: one crash takes every context on
+the page with it. Supporting both means `WebGLRenderer` by default plus `WebGPURenderer` only on
+listed devices, never `WebGPURenderer` everywhere, and custom GLSL needs a TSL port for WebGPU.
+The call is bounded: it resolves within 1 second by default, normally at once after
+`awaitBridge()`, and never rejects. Do not detect devices yourself; the list is the platform's and
+reaches your live game without a new build. [`graphics-route.md`](graphics-route.md) has the
+three.js pattern, what both renderers cost, and how to test each answer with the `gemGraphics`
+launch key.
+
 ## Graphics quality: the Arcade picks the start, your game adapts
 
 Players open a lot of games they have never played. Each one should open at a quality that suits
@@ -2258,8 +2288,9 @@ with your game's card, and shares it through its own sheet, copy or Share panel.
 only where `gem.share.available` is true.
 
 Two things before you reach for it: **call it from the click**, synchronously, never from a timer
-or after an `await`; and **never gate a reward on it**, because your game is told nothing back,
-not even whether the player shared.
+or after an `await`; and **never gate a reward on it**, because nothing about the player comes
+back, not even whether they shared. Its promise rejects only when the Arcade refused the link,
+naming why, so catch it and log it.
 [Linking to your game](getting-started.md#linking-to-your-game) is the section.
 
 ## If your game vibrates

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indiegems/gem-web-sdk",
-  "version": "21.0.0",
+  "version": "21.1.1",
   "description": "postMessage bridge contract between gem-web and browser-playable games",
   "license": "UNLICENSED",
   "type": "module",
@@ -39,6 +39,10 @@
       "types": "./dist/quality.d.ts",
       "import": "./dist/gem-web-sdk.quality.js"
     },
+    "./dev-tools": {
+      "types": "./dist/dev-tools.d.ts",
+      "import": "./dist/gem-web-sdk.dev-tools.js"
+    },
     "./conformance": {
       "types": "./dist/conformance.d.ts",
       "import": "./dist/gem-web-sdk.conformance.js"

package/schema/bridge.v1.json

@@ -2106,6 +2106,80 @@
       "rateLimit": { "perMinute": 12 }
     },
 
+    {
+      "type": "gem.graphicsRoutes",
+      "direction": "parentToFrame",
+      "transport": "port",
+      "$comment": [
+        "The devices on which a game should draw with WebGPU rather than WebGL.",
+        "Gated by the `graphicsRoutes` capability.",
+        "",
+        "WEBGL IS THE DEFAULT and stays so (owner decision 2026-11-04): WebGPU",
+        "generally performs worse out of the box. An entry names a device whose",
+        "WebGL route is broken — the Pixel 10's PowerVR D-Series crashes on",
+        "every route but Vulkan, one entry a route — so a game that asks",
+        "`gem.graphics.preferredRoute()` is told the device is listed and to",
+        "make its WebGPU renderer there, drawing its safe WebGL recipe where",
+        "WebGPU is unavailable.",
+        "",
+        "THE WHOLE LIST, REPLACING THE SDK'S BUILT-IN ONE. Every SDK build carries",
+        "a default list; this message is how a new entry reaches games already",
+        "live, and how one that turns out wrong is taken away, with no game",
+        "rebuilt. An EMPTY `entries` means 'no device needs WebGPU', which is an",
+        "answer; never receiving the message means only 'this embedder never",
+        "said', and the frame then uses its built-in list.",
+        "",
+        "OPEN VOCABULARIES, matched exactly, never by pattern. `gpu`, `route` and",
+        "`host` are the families the SDK's own `gem_graphics_context_lost`",
+        "report reads off the WebGL renderer string:",
+        "`gpu` e.g. `powervr_d_series`, `route` e.g. `angle_gles`, `host`",
+        "`android_webview` or `other`. Strings rather than enums on purpose: a",
+        "family a newer SDK learns must not fail an older frame's validation of",
+        "the whole list. A value a frame does not know simply matches nothing.",
+        "An absent `route` or `host` matches any.",
+        "",
+        "PUSHED ONCE, right after the handshake accept and before anything else",
+        "the parent sends, because a game asks just before it makes its renderer",
+        "— which is at boot. The frame waits a bounded moment for it and answers",
+        "from its built-in list when it does not come, so a parent that",
+        "advertises nothing costs a game nothing, and one that advertises and",
+        "stays silent costs it that wait at boot.",
+        "",
+        "Public, like everything on the bridge: a device list, nothing about the",
+        "player. The frame does not report back which entry matched."
+      ],
+      "fields": {
+        "entries": {
+          "kind": "array",
+          "maxItems": 32,
+          "items": {
+            "kind": "object",
+            "fields": {
+              "gpu": {
+                "kind": "string",
+                "maxLength": 32,
+                "$comment": "The GPU family, e.g. `powervr_d_series`."
+              },
+              "route": {
+                "kind": "string",
+                "maxLength": 32,
+                "optional": true,
+                "$comment": "The WebGL route, e.g. `angle_gles`. Absent matches any route."
+              },
+              "host": {
+                "kind": "string",
+                "maxLength": 32,
+                "optional": true,
+                "$comment": "`android_webview` or `other`. Absent matches either."
+              }
+            }
+          },
+          "$comment": "Every device that should draw with WebGPU. Empty means none."
+        }
+      },
+      "rateLimit": { "perMinute": 12 }
+    },
+
     {
       "type": "gem.devtools",
       "direction": "parentToFrame",
@@ -3483,18 +3557,38 @@
         "whether to share, builds the URL, holds the token and renders every",
         "surface.",
         "",
-        "ONE WAY, AND NOTHING ANSWERS IT. No requestId, no text, no URL and no",
-        "game id travel in this message, and no message travels back. The game",
-        "never learns whether the player shared, cancelled or was refused, so it",
-        "has nothing to gate progress or a reward on. An empty `params` array is",
-        "valid: it shares the game with no deep link.",
+        "NOTHING ABOUT THE PLAYER COMES BACK. No text, no URL and no game id",
+        "travel in this message. The game never learns whether the player",
+        "shared, cancelled or dismissed the sheet, so it has nothing to gate",
+        "progress or a reward on. The one answer is `gem.shareResult`, and only",
+        "where both ends advertised `shareResult` and the request carries a",
+        "`requestId`: whether the parent TOOK the request or REFUSED it, and",
+        "why, decided on receipt from the request alone. Without those, nothing",
+        "travels back, as before. An empty `params` array is valid: it shares",
+        "the game with no deep link.",
         "",
         "WHAT THE PARENT OWES, none of which this schema can enforce:",
         "",
-        "  REFUSE RESERVED KEYS. A key the parent reads from the play URL itself",
-        "  refuses the whole request: the reserved launch keys, the same list the",
-        "  SDK refuses before sending, which includes `play`, `channel`, `_s`,",
-        "  every `utm_` key, `fbclid`, `ttclid`, `gclid` and `msclkid`.",
+        "  RESERVED KEYS: REMAP THEM, OR REFUSE THE REQUEST. The reserved",
+        "  launch keys are the ones the parent reads from the play URL itself",
+        "  (gem-api's launch-query-rules.json: `play`, `channel`, `invite`,",
+        "  `_s`, every `utm_` key, the ad-click ids and more). A parent that",
+        "  advertises `shareRemap` writes each one into the link under",
+        "  launch-query-rules.json's `share_key_escape_prefix` (`gemEsc_`), with",
+        "  a game key that already begins with the prefix escaped the same way,",
+        "  and removes the prefix once before forwarding the play URL's query",
+        "  into the frame, so the game reads back exactly the key it shared. It",
+        "  never acts on an escaped key itself, and a raw reserved key is still",
+        "  stripped before the frame. It still refuses `share_refused_keys`",
+        "  (`_s`, `embedder`) and a key too long to stay a valid key once",
+        "  escaped. A parent that does not advertise `shareRemap` refuses the",
+        "  whole request on any reserved key; the SDK refuses those before",
+        "  sending to such a parent.",
+        "",
+        "  A restored click id or `utm_` value is whatever the link says: anyone",
+        "  who edits a share link can forge one, and third-party tags in the",
+        "  game's frame then read it as attribution. Accepted by the owner's",
+        "  decision; a game must not trust it as attribution.",
         "",
         "  BUILD FROM THE FRAMED GAME, NEVER FROM THE MESSAGE. The link is",
         "  `/games/<id>?play=1&<params>&_s=<token>`, where `<id>` is the game the",
@@ -3528,13 +3622,26 @@
         "  shared: copy a game authored, sent under the platform's name, is a",
         "  phishing kit with the platform's name on it.",
         "",
-        "  SEND NOTHING BACK. No outcome, no acknowledgement, and no error for a",
-        "  refusal - not even for a malformed or reserved request.",
+        "  ANSWER ONLY WHAT THE REQUEST DECIDES. To a frame that advertised",
+        "  `shareResult`, a parent that advertised it answers a request carrying",
+        "  a `requestId` with exactly one `gem.shareResult`, on receipt, before",
+        "  any sheet or panel opens: `refused` with the reason for a request its",
+        "  key, round-trip or length checks refuse, and `accepted` for every",
+        "  other, including one it then drops under the rules above. Nothing",
+        "  that depends on the player - shared, cancelled, dismissed, a",
+        "  cooldown after a dismissal - is ever answered. To any other frame, or",
+        "  for a request with no `requestId`, send nothing back.",
         "",
         "Everything in `params` is public: it is written into a link the player",
         "hands to anyone. A game puts no personal identifier in it."
       ],
       "fields": {
+        "requestId": {
+          "kind": "string",
+          "maxLength": 64,
+          "optional": true,
+          "$comment": "Opaque and frame-chosen. Echo-only. Sent only to a parent that advertised `shareResult`, which answers it with one `gem.shareResult`. Absent from every SDK before it."
+        },
         "params": {
           "kind": "array",
           "maxItems": 16,
@@ -3553,6 +3660,54 @@
       }
     },
 
+    {
+      "type": "gem.shareResult",
+      "direction": "parentToFrame",
+      "transport": "port",
+      "$comment": [
+        "The answer to one gem.requestShare that carried a `requestId`. Gated by",
+        "the `shareResult` capability: sent only by a parent that advertised it,",
+        "to a frame that advertised it.",
+        "",
+        "  accepted - the parent took the request. NOT A SHARE: it says nothing",
+        "             about whether a sheet opened, or whether the player shared,",
+        "             and a request the parent then drops under its pacing rules",
+        "             is `accepted` too.",
+        "  refused  - the parent will not share this link; `reason` says why,",
+        "             and `key` names the param when one key caused it.",
+        "",
+        "ANSWERED ON RECEIPT, FROM THE REQUEST ALONE, before any sheet or panel",
+        "opens, so neither the answer nor its timing says anything about the",
+        "player. The game is told what to fix, and nothing else."
+      ],
+      "fields": {
+        "requestId": {
+          "kind": "string",
+          "maxLength": 64,
+          "$comment": "Echoes the gem.requestShare that asked. Echo-only."
+        },
+        "outcome": {
+          "kind": "enum",
+          "values": ["accepted", "refused"],
+          "$comment": "Closed at two. Why a request was refused is `reason`, which is open."
+        },
+        "reason": {
+          "kind": "string",
+          "maxLength": 64,
+          "format": "code",
+          "optional": true,
+          "$comment": "With `refused` only. An open code, from launch-query-rules.json's `share_refusal_codes`: `reserved_key` (a key the parent keeps for itself and does not carry), `round_trip` (the built link does not parse back to what was asked, or an escaped key would not be a valid key), `too_long` (the link is over 2 KB). A receiver must not fail on a code it does not know."
+        },
+        "key": {
+          "kind": "string",
+          "maxLength": 64,
+          "optional": true,
+          "$comment": "With `refused` only: the param key that caused it, exactly as the request named it, when one key did. Absent for a refusal of the whole link (`too_long`)."
+        }
+      },
+      "rateLimit": { "perMinute": 30 }
+    },
+
     {
       "type": "gem.requestAvatarPicker",
       "direction": "frameToParent",
@@ -3991,6 +4146,35 @@
           "maxLength": 64,
           "optional": true,
           "$comment": "Required for recipes, which are addressed within a catalog. Comes from the game's published config."
+        },
+        "origin": {
+          "kind": "enum",
+          "values": ["sheet", "direct_refused"],
+          "optional": true,
+          "$comment": [
+            "Why the frame is asking. ABSENT MEANS `sheet`: an SDK older than the field",
+            "sends none.",
+            "",
+            "  sheet           - the game called `gem.purchases.request`: the player",
+            "                    pressed the game's Buy and expects the parent's sheet.",
+            "  direct_refused  - the game spent directly (`gem.me.mutations.purchase`)",
+            "                    and gem-api refused it 403 `guest_upgrade_required`:",
+            "                    the player has no account the platform lets spend.",
+            "                    The SDK hands the attempt to the parent so it can offer",
+            "                    the player an account, then rejects the game's call",
+            "                    with that error at once, without waiting for this",
+            "                    ask's answer. `currencySlug` is the platform's exact",
+            "                    slug, from the player's balances, never the game's",
+            "                    string.",
+            "",
+            "A HINT FROM UNTRUSTED CODE, NOT A FACT. A game can post either value on",
+            "the port it holds. The parent decides what to draw from its own record of",
+            "the player, never from this field, and every obligation above applies to",
+            "a `direct_refused` ask unchanged: it is answered `gem.purchaseResult` like",
+            "any other, and a sheet it opens spends only on the player's own press.",
+            "A parent that does not read the field treats the ask as a sheet ask,",
+            "which is the safe reading of either value."
+          ]
         }
       },
       "rateLimit": {
@@ -4222,6 +4406,11 @@
             "    recipe_max_uses_exceeded,",
             "    item_max_stack_exceeded,",
             "    recipe_costs_unmet, quantity_invalid",
+            "  the player is a guest the platform does     declined     guest_upgrade_required",
+            "    not let spend (gem-api 403",
+            "    guest_upgrade_required, or the parent",
+            "    knows it first), whether or not the",
+            "    parent offered them an account",
             "  gem-api confirmation_required               -            NEVER REACHES THE",
             "                                                           GAME: the parent",
             "                                                           handles it itself,",
@@ -4229,7 +4418,8 @@
             "                                                           the player's age",
             "  gem-api 429 (its limiter is per IP, so it   declined     error",
             "    would describe other people's activity),",
-            "    403, nonce conflicts, and every account",
+            "    any other 403, nonce conflicts, and every",
+            "    other account",
             "    state - sanction, age, region",
             "  5xx, a network failure, a timeout, an `ok`  unavailable  error, or absent",
             "    the frame could not verify, and a charge",
@@ -4254,6 +4444,67 @@
       },
       "rateLimit": { "perMinute": 30 }
     },
+    {
+      "type": "gem.purchaseSettled",
+      "direction": "parentToFrame",
+      "transport": "port",
+      "$comment": [
+        "A platform-currency purchase of this game's own item or recipe has",
+        "completed, and no gem.purchaseResult reports it. Gated by the",
+        "`purchaseSettled` capability. Pushed, unasked, once per such purchase",
+        "while the frame session lasts.",
+        "",
+        "WHEN. The parent finished a purchase the game asked for in an earlier",
+        "session or on a promise already answered: the typical case is a guest",
+        "whose spend was refused (`guest_upgrade_required`), who made an account",
+        "and confirmed the parent's sheet after the game's ask had been answered,",
+        "or after a reload had dropped it. A purchase answered `ok` through",
+        "gem.purchaseResult is never ALSO reported here.",
+        "",
+        "A HINT, NOT A RECEIPT, modelled on gem.storePurchaseSettled. The SDK",
+        "confirms `purchaseId` against the platform's own record with the",
+        "frame's token before it tells the game, exactly as it confirms a",
+        "gem.purchaseResult `ok`, and re-reads the player's inventory either way",
+        "but on a definite `absent`. A game never grants on the strength of this",
+        "message: it re-reads inventory, which is where the truth is.",
+        "",
+        "EVERY FIELD IS THE PARENT'S, AND PUBLIC. The ids are this game's own,",
+        "from its published config; `purchaseId` follows",
+        "gem.purchaseResult.purchaseId's rules: opaque, high-entropy, minted for",
+        "this disclosure. No price, no currency and no balance cross here."
+      ],
+      "fields": {
+        "purchaseKind": {
+          "kind": "enum",
+          "values": ["item", "recipe"],
+          "$comment": "As on gem.requestPurchase."
+        },
+        "targetId": {
+          "kind": "string",
+          "maxLength": 64,
+          "$comment": "The item-definition or recipe id that was bought, as on gem.requestPurchase."
+        },
+        "catalogId": {
+          "kind": "string",
+          "maxLength": 64,
+          "optional": true,
+          "$comment": "The recipe's catalog, for a recipe; absent for an item."
+        },
+        "quantity": {
+          "kind": "int",
+          "min": 1,
+          "max": 10,
+          "$comment": "How many were bought, 1..=10 as on gem.requestPurchase. Always 1 for a recipe."
+        },
+        "purchaseId": {
+          "kind": "string",
+          "maxLength": 64,
+          "optional": true,
+          "$comment": "The platform's own id for this purchase, under gem.purchaseResult.purchaseId's rules. The SDK confirms it before it tells the game; a hint without one is never reported to the game as a purchase, though the SDK still re-reads the player's inventory."
+        }
+      },
+      "rateLimit": { "perMinute": 30 }
+    },
     {
       "type": "gem.deviceSettings.put",
       "direction": "frameToParent",

package/schema/capabilities.public.json

@@ -27,6 +27,12 @@
         "gem.purchaseResult"
       ]
     },
+    "purchaseSettled": {
+      "implemented": true,
+      "gates": [
+        "gem.purchaseSettled"
+      ]
+    },
     "avatar3dPurchases": {
       "implemented": true,
       "gates": [
@@ -86,6 +92,12 @@
         "gem.clusterTarget"
       ]
     },
+    "graphicsRoutes": {
+      "implemented": true,
+      "gates": [
+        "gem.graphicsRoutes"
+      ]
+    },
     "parties": {
       "implemented": true,
       "gates": [
@@ -217,6 +229,20 @@
         "gem.requestShare"
       ]
     },
+    "shareResult": {
+      "implemented": true,
+      "gates": [
+        "gem.shareResult"
+      ]
+    },
+    "shareRemap": {
+      "implemented": true,
+      "gates": [
+        {
+          "namespace": "gem.share"
+        }
+      ]
+    },
     "avatarPicker": {
       "implemented": true,
       "gates": [