@indiegems/gem-web-sdk 21.0.0 → 21.1.1

package/docs/api/reference.json

@@ -2,7 +2,7 @@
   "schema_version": 2,
   "source": {
     "repo": "IndieGems/gem-web-sdk",
-    "version": "21.0.0"
+    "version": "21.1.1"
   },
   "entries": [
     {
@@ -85,6 +85,10 @@
           "key": "vibration",
           "title": "Vibrating the device"
         },
+        {
+          "key": "graphics",
+          "title": "WebGL or WebGPU"
+        },
         {
           "key": "controls",
           "title": "Camera and look controls"
@@ -2564,7 +2568,7 @@
           "group": "saves",
           "signature": "purchase(request: ConfiguredPurchaseRequest, options?: PurchaseOptions): Promise<ConfiguredPurchaseResult>",
           "documented": true,
-          "summary": "Purchase an item or recipe through the game's authenticated SDK transport.\n\nOne call covers both direct payment types:\n\n- `payment: { kind: 'configured' }` runs a recipe and charges the costs in\n  your game config.\n- `payment: { kind: 'platform_currency', currencySlug: 'GEMS' }` resolves\n  the target's published platform price and spends the player's platform\n  balance directly. It does not send a bridge message or open the platform\n  purchase sheet; your game owns any confirmation UI.\n\nThe game supplies no amount, config version or nonce. The SDK resolves the\ncurrent published price and config version, mints the nonce, and the\nplatform checks all of them again before it debits anything.\n\nA REFUSAL CARRIES A `code` — branch on `err.code`, in the vocabulary\n`gem.purchases.request` answers in (`PurchaseRefusalCode`). Before\nsending a `platform_currency` payment the SDK itself throws a\n`PurchaseRefusal` (a `RangeError`) for `unknown_currency`,\n`not_purchasable`, `no_price_in_currency` or `quantity_invalid`, with a\nmessage naming the active slugs or what the target is priced in. The\nplatform's own refusals arrive as a `GemApiError` whose `code` is its wire\ncode — `insufficient_funds`, `recipe_locked`, `price_mismatch`, … Never\ndraw a top-up or payment screen of your own for either.",
+          "summary": "Purchase an item or recipe through the game's authenticated SDK transport.\n\nOne call covers both direct payment types:\n\n- `payment: { kind: 'configured' }` runs a recipe and charges the costs in\n  your game config.\n- `payment: { kind: 'platform_currency', currencySlug: 'GEMS' }` resolves\n  the target's published platform price and spends the player's platform\n  balance directly. It does not send a bridge message or open the platform\n  purchase sheet; your game owns any confirmation UI.\n\nThe game supplies no amount, config version or nonce. The SDK resolves the\ncurrent published price and config version, mints the nonce, and the\nplatform checks all of them again before it debits anything.\n\nA REFUSAL CARRIES A `code` — branch on `err.code`, in the vocabulary\n`gem.purchases.request` answers in (`PurchaseRefusalCode`). Before\nsending a `platform_currency` payment the SDK itself throws a\n`PurchaseRefusal` (a `RangeError`) for `unknown_currency`,\n`not_purchasable`, `no_price_in_currency` or `quantity_invalid`, with a\nmessage naming the active slugs or what the target is priced in. The\nplatform's own refusals arrive as a `GemApiError` whose `code` is its wire\ncode — `insufficient_funds`, `recipe_locked`, `price_mismatch`, … Never\ndraw a top-up or payment screen of your own for either.\n\n`guest_upgrade_required` means the player is a guest, and the platform\nlets only an account spend. TREAT IT LIKE A DECLINE AND DRAW NOTHING: the\nSDK has already handed the attempt to the arcade, which offers the player\nan account over your game. The call rejects at once rather than waiting\nfor them; if they make one and buy, [PurchaseApi.onSettled](api-reference-game.md#purchaseapi-onsettled) hears it.",
           "deprecated": null,
           "params": [
             {
@@ -4735,7 +4739,7 @@
           "group": "analytics",
           "signature": "type PlatformEventName = \"gem_session_start\" | \"gem_session_end\" | \"gem_pause\" | \"gem_resume\" | \"gem_boot_ready\" | \"gem_match_started\" | \"gem_match_ended\" | \"gem_auth_lost\" | \"gem_graphics_context_lost\"",
           "documented": true,
-          "summary": "Every event the SDK emits by itself.\n\nA game never sends these — `gem.analytics.track` refuses the whole\n`gem_` namespace — but the names are published because a game reading its\nown funnel needs the vocabulary, and because a funnel declared in the game\nconfig names them as steps.\n\n| Event | Dimensions | Measures |\n|---|---|---|\n| `gem_session_start` | — | — |\n| `gem_session_end` | `reason` ([SessionEndReason](api-reference-game.md#sessionendreason)) | `duration_ms` |\n| `gem_pause` / `gem_resume` | — | — |\n| `gem_boot_ready` | — | `boot_ms` |\n| `gem_match_started` / `gem_match_ended` | `transport` ([MatchTransport](api-reference-game.md#matchtransport)) | — |\n| `gem_auth_lost` | — | — |\n| `gem_graphics_context_lost` | `gpu`, `host`, `route` | `context_ms`, `hidden`, `nth_loss` |\n\n`gem_graphics_context_lost` is the browser taking a WebGL context away —\nusually a GPU driver fault, sized per device across every game\n(`analytics/graphics.ts` lists the dimension values).",
+          "summary": "Every event the SDK emits by itself.\n\nA game never sends these — `gem.analytics.track` refuses the whole\n`gem_` namespace — but the names are published because a game reading its\nown funnel needs the vocabulary, and because a funnel declared in the game\nconfig names them as steps.\n\n| Event | Dimensions | Measures |\n|---|---|---|\n| `gem_session_start` | — | — |\n| `gem_session_end` | `reason` ([SessionEndReason](api-reference-game.md#sessionendreason)) | `duration_ms` |\n| `gem_pause` / `gem_resume` | — | — |\n| `gem_boot_ready` | — | `boot_ms` |\n| `gem_match_started` / `gem_match_ended` | `transport` ([MatchTransport](api-reference-game.md#matchtransport)) | — |\n| `gem_auth_lost` | — | — |\n| `gem_graphics_context_lost` | `gpu`, `host`, `route` | `context_ms`, `hidden`, `nth_loss` |\n\n`gem_graphics_context_lost` is the browser taking a WebGL context away, or a\nWebGPU device (`route` is then `webgpu`) — usually a GPU driver fault, sized\nper device across every game (`analytics/graphics.ts` lists the dimension\nvalues).",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -9088,9 +9092,9 @@
           "name": "requestShare",
           "anchor": "gemframe-requestshare",
           "group": "frame",
-          "signature": "requestShare(params: readonly { key: string; value: string }[]): boolean",
+          "signature": "requestShare(params: readonly { key: string; value: string }[], requestId?: string): boolean",
           "documented": true,
-          "summary": "Ask the arcade to share a link to your game, opened with these launch\nparameters. The arcade builds the link and shows its own share sheet, copy\nor Share panel; nothing comes back, not even whether the player shared.\n\nPrefer `gem.share.request`, which checks each key and value against the\narcade's rules and throws on the one that would be refused. This one checks\nonly the message's bounds, sends only while connected, and only to an\narcade that handles share.",
+          "summary": "Ask the arcade to share a link to your game, opened with these launch\nparameters. The arcade builds the link and shows its own share sheet, copy\nor Share panel; nothing about the player comes back, not even whether they\nshared.\n\nPrefer `gem.share.request`, which checks each key and value against the\narcade's rules, throws on the one that would be refused, and rejects with\nthe arcade's own refusal. This one checks only the message's bounds, sends\nonly while connected, and only to an arcade that handles share.",
           "deprecated": null,
           "params": [
             {
@@ -9098,6 +9102,12 @@
               "type": "readonly { key: string; value: string }[]",
               "optional": false,
               "summary": null
+            },
+            {
+              "name": "requestId",
+              "type": "string",
+              "optional": true,
+              "summary": "Pass one only to an arcade that advertised\n  `shareResult`, which answers it with one `gem.shareResult` through\n  `onShareResult`; any other arcade ignores it. Omit it and nothing\n  answers."
             }
           ],
           "returns": "whether the message left the frame — `false` before the bridge is\n  up, for an arcade that does not handle share, and past this frame's own\n  limit of six a minute.",
@@ -13116,6 +13126,27 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "Gem.graphics",
+          "name": "graphics",
+          "anchor": "gem-graphics",
+          "group": "start",
+          "signature": "readonly graphics: GraphicsApi",
+          "documented": true,
+          "summary": "Which renderer to make — WebGPU or WebGL — on this device, and whether\nthe device is listed as broken on WebGL. Ask\n`gem.graphics.preferredRoute()` just before you make your first renderer.\n\nWebGL is the answer almost everywhere; `webgpu` only on a listed device,\nwhere WebGPU is available. A listed device that ends up on WebGL draws the\ngame's safe WebGL recipe. The list is the platform's, so a new entry\nreaches your live game without a new build.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": [
+            {
+              "slug": "graphics-route",
+              "anchor": null
+            }
+          ]
+        },
         {
           "id": "Gem.moments",
           "name": "moments",
@@ -13186,7 +13217,7 @@
           "group": "start",
           "signature": "readonly share: ShareApi",
           "documented": true,
-          "summary": "Ask the arcade to share a link to your game — opened at the puzzle, board\nor level your launch parameters name — from your own Share button.\n\nThe arcade builds the link, which unfurls with your game's card, and shares\nit through its own share sheet, a copy, or its own Share panel. Show your\nbutton only where [ShareApi.available](api-reference-game.md#shareapi-available) is true, and read it again in\nthe click handler, because `request` throws once it has gone false:\n\n```js\nshareButton.hidden = !gem.share.available;\nshareButton.onclick = () => {\n  if (!gem.share.available) return;\n  gem.share.request({ params: { jar: 'JAR-K7P3QXM', n: '2' } });\n};\n```\n\n- **Call it synchronously from the click** — never from a timer, after an\n  `await`, or on a game event.\n- **Never gate progress or a reward on sharing.** You are told nothing\n  back, not even whether the player shared.\n- **No personal identifiers in `params`.** The link is public.\n- **The share text is the arcade's own**; your game supplies none.",
+          "summary": "Ask the arcade to share a link to your game — opened at the puzzle, board\nor level your launch parameters name — from your own Share button.\n\nThe arcade builds the link, which unfurls with your game's card, and shares\nit through its own share sheet, a copy, or its own Share panel. Show your\nbutton only where [ShareApi.available](api-reference-game.md#shareapi-available) is true, and read it again in\nthe click handler, because `request` throws once it has gone false:\n\n```js\nshareButton.hidden = !gem.share.available;\nshareButton.onclick = () => {\n  if (!gem.share.available) return;\n  gem.share.request({ params: { jar: 'JAR-K7P3QXM', n: '2' } }).catch((err) => {\n    // A ShareRefusal: err.reason ('reserved_key', 'round_trip', 'too_long')\n    // and err.key say what to fix. Log it; show the player nothing.\n    console.warn(err);\n  });\n};\n```\n\n- **Call it synchronously from the click** — never from a timer, after an\n  `await`, or on a game event.\n- **Never gate progress or a reward on sharing.** Nothing about the player\n  comes back, not even whether they shared. The promise rejects only when\n  the arcade refused the share, with a [ShareRefusal](api-reference-game.md#sharerefusal) naming why.\n- **No personal identifiers in `params`.** The link is public.\n- **The share text is the arcade's own**; your game supplies none.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -14361,6 +14392,205 @@
             }
           ]
         },
+        {
+          "id": "GemGraphicsRoute",
+          "name": "GemGraphicsRoute",
+          "anchor": "gemgraphicsroute",
+          "group": "graphics",
+          "signature": "type GemGraphicsRoute = \"webgpu\" | \"webgl\"",
+          "documented": true,
+          "summary": "Which renderer to make: `webgpu` or `webgl`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemPreferredRoute",
+          "name": "GemPreferredRoute",
+          "anchor": "gempreferredroute",
+          "group": "graphics",
+          "signature": "interface GemPreferredRoute",
+          "documented": true,
+          "summary": "What `gem.graphics.preferredRoute()` answers.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemPreferredRoute.route",
+          "name": "route",
+          "anchor": "gempreferredroute-route",
+          "group": "graphics",
+          "signature": "readonly route: GemGraphicsRoute",
+          "documented": true,
+          "summary": "Which renderer to make. `webgpu` only when `listed` is true and the\nbrowser hands out a WebGPU adapter; `webgl` everywhere else.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemPreferredRoute.listed",
+          "name": "listed",
+          "anchor": "gempreferredroute-listed",
+          "group": "graphics",
+          "signature": "readonly listed: boolean",
+          "documented": true,
+          "summary": "Whether the platform lists this device as broken on WebGL. When true and\n`route` is `webgl` (no WebGPU here), or your WebGPU renderer fails to\nstart, draw your safe WebGL recipe — for every listed device today, no\nshadow maps — on every WebGL canvas the page makes, menus included.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemGraphicsRouteEntry",
+          "name": "GemGraphicsRouteEntry",
+          "anchor": "gemgraphicsrouteentry",
+          "group": "graphics",
+          "signature": "interface GemGraphicsRouteEntry",
+          "documented": true,
+          "summary": "One device that should draw with WebGPU, as the platform's list names it.\nAn absent `route` or `host` matches any.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemGraphicsRouteEntry.gpu",
+          "name": "gpu",
+          "anchor": "gemgraphicsrouteentry-gpu",
+          "group": "graphics",
+          "signature": "readonly gpu: string",
+          "documented": true,
+          "summary": "The GPU family, e.g. `powervr_d_series`, `adreno`, `mali`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemGraphicsRouteEntry.route",
+          "name": "route",
+          "anchor": "gemgraphicsrouteentry-route",
+          "group": "graphics",
+          "signature": "readonly route?: string",
+          "documented": true,
+          "summary": "The route WebGL takes there, e.g. `angle_gles` (OpenGL ES),\n`native_gl` (no ANGLE, as the Arcade's Android app reports) or\n`angle_vulkan`. Absent matches any route.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemGraphicsRouteEntry.host",
+          "name": "host",
+          "anchor": "gemgraphicsrouteentry-host",
+          "group": "graphics",
+          "signature": "readonly host?: string",
+          "documented": true,
+          "summary": "`android_webview` (an Android app's WebView, the Arcade app's included) or\n`other`. Absent matches either.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "PreferredRouteOptions",
+          "name": "PreferredRouteOptions",
+          "anchor": "preferredrouteoptions",
+          "group": "graphics",
+          "signature": "interface PreferredRouteOptions",
+          "documented": true,
+          "summary": "Options for [GraphicsApi.preferredRoute](api-reference-game.md#graphicsapi-preferredroute).",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "PreferredRouteOptions.timeoutMs",
+          "name": "timeoutMs",
+          "anchor": "preferredrouteoptions-timeoutms",
+          "group": "graphics",
+          "signature": "readonly timeoutMs?: number",
+          "documented": true,
+          "summary": "The longest the answer may take, in milliseconds. Default 1000, at most\n5000. When it runs out, the answer comes from what is known by then.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GraphicsApi",
+          "name": "GraphicsApi",
+          "anchor": "graphicsapi",
+          "group": "graphics",
+          "signature": "interface GraphicsApi",
+          "documented": true,
+          "summary": "Which renderer to make. Reached as `gem.graphics`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GraphicsApi.preferredRoute",
+          "name": "preferredRoute",
+          "anchor": "graphicsapi-preferredroute",
+          "group": "graphics",
+          "signature": "preferredRoute(options?: PreferredRouteOptions): Promise<GemPreferredRoute>",
+          "documented": true,
+          "summary": "Which renderer to make, and whether this device is listed. Ask once, just\nbefore you make your first renderer, and follow it for every canvas.\n\n`route` is `webgl` almost everywhere. It is `webgpu` only on a device the\nplatform lists as broken on WebGL (today the PowerVR D-Series GPU in the\nPixel 10, on every route but Vulkan), and only when WebGPU is available\nthere. `listed` is true on such a device: when `route` is `webgl` there,\nor making the WebGPU renderer fails, draw your safe WebGL recipe.\n\nResolves within `timeoutMs` (default 1000 ms) and never rejects; normally\nat once after `gem.awaitBridge()`. The launch key `gemGraphics=webgpu`,\n`gemGraphics=safe` or `gemGraphics=webgl` forces the answer, for testing.",
+          "deprecated": null,
+          "params": [
+            {
+              "name": "options",
+              "type": "PreferredRouteOptions",
+              "optional": true,
+              "summary": "See [PreferredRouteOptions](api-reference-game.md#preferredrouteoptions)."
+            }
+          ],
+          "returns": "`{ route, listed }`.",
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "GemMatchServerModule",
           "name": "GemMatchServerModule",
@@ -16712,6 +16942,125 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "PurchaseApi.onSettled",
+          "name": "onSettled",
+          "anchor": "purchaseapi-onsettled",
+          "group": "purchases",
+          "signature": "onSettled(listener: (settlement: PurchaseSettlement) => void): () => void",
+          "documented": true,
+          "summary": "Hear about a purchase of yours that completed AFTER its own call answered\n— returns a function that stops listening.\n\nThe case it exists for: a guest's `gem.me.mutations.purchase` is refused\n`guest_upgrade_required` (your call rejects at once, and you show\nnothing), the arcade offers the player an account, and they make one and\nconfirm the arcade's sheet a minute later — or after a reload, when the\ncall that asked is gone. This is how your game hears that it happened.\n\nTHE SDK CONFIRMS IT FIRST. A listener is called only once the platform\nitself, asked with your game's own token, says the purchase was granted;\na claim it cannot confirm is never reported. The player's inventory is\nre-read either way, so `gem.me.inventory.onChanged` fires too. Treat it\nlike an `ok`: grant feedback, then re-read inventory rather than assuming\nwhat landed.\n\nHears nothing on an arcade that does not support it (the\n`purchaseSettled` capability), and never for a purchase an `ok` already\nreported.",
+          "deprecated": null,
+          "params": [
+            {
+              "name": "listener",
+              "type": "(settlement: PurchaseSettlement) => void",
+              "optional": false,
+              "summary": null
+            }
+          ],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "PurchaseSettlement",
+          "name": "PurchaseSettlement",
+          "anchor": "purchasesettlement",
+          "group": "purchases",
+          "signature": "interface PurchaseSettlement",
+          "documented": true,
+          "summary": "A purchase of one of your game's own items or recipes that completed after\nthe call that asked for it had answered. What [PurchaseApi.onSettled](api-reference-game.md#purchaseapi-onsettled)\nhears.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "PurchaseSettlement.kind",
+          "name": "kind",
+          "anchor": "purchasesettlement-kind",
+          "group": "purchases",
+          "signature": "readonly kind: \"item\" | \"recipe\"",
+          "documented": true,
+          "summary": "`item` or `recipe`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "PurchaseSettlement.targetId",
+          "name": "targetId",
+          "anchor": "purchasesettlement-targetid",
+          "group": "purchases",
+          "signature": "readonly targetId: string",
+          "documented": true,
+          "summary": "The item-definition or recipe id that was bought.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "PurchaseSettlement.catalogId",
+          "name": "catalogId",
+          "anchor": "purchasesettlement-catalogid",
+          "group": "purchases",
+          "signature": "readonly catalogId?: string",
+          "documented": true,
+          "summary": "The recipe's catalog; absent for an item.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "PurchaseSettlement.quantity",
+          "name": "quantity",
+          "anchor": "purchasesettlement-quantity",
+          "group": "purchases",
+          "signature": "readonly quantity: number",
+          "documented": true,
+          "summary": "How many were bought. Always 1 for a recipe.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "PurchaseSettlement.purchaseId",
+          "name": "purchaseId",
+          "anchor": "purchasesettlement-purchaseid",
+          "group": "purchases",
+          "signature": "readonly purchaseId: string",
+          "documented": true,
+          "summary": "The platform's own id for this purchase, which the SDK confirmed with the\nplatform before calling you. A handle for logs and support, as on\n[PurchaseOutcome](api-reference-game.md#purchaseoutcome)'s `ok`; nothing reads it back.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "Avatar3dPurchaseRequest",
           "name": "Avatar3dPurchaseRequest",
@@ -16765,9 +17114,9 @@
           "name": "PurchaseRefusalCode",
           "anchor": "purchaserefusalcode",
           "group": "purchases",
-          "signature": "type PurchaseRefusalCode = \"unknown_currency\" | \"currency_not_in_game_payable\" | \"not_purchasable\" | \"no_price_in_currency\" | \"busy\" | \"cancelled\" | \"insufficient_funds\" | \"price_mismatch\" | \"config_version_stale\" | \"platform_currency_unavailable\" | \"not_available\" | \"recipe_locked\" | \"already_owned\" | \"recipe_on_cooldown\" | \"recipe_max_uses_exceeded\" | \"item_max_stack_exceeded\" | \"recipe_costs_unmet\" | \"quantity_invalid\" | \"error\"",
+          "signature": "type PurchaseRefusalCode = \"unknown_currency\" | \"currency_not_in_game_payable\" | \"not_purchasable\" | \"no_price_in_currency\" | \"busy\" | \"cancelled\" | \"insufficient_funds\" | \"price_mismatch\" | \"config_version_stale\" | \"platform_currency_unavailable\" | \"not_available\" | \"recipe_locked\" | \"already_owned\" | \"guest_upgrade_required\" | \"recipe_on_cooldown\" | \"recipe_max_uses_exceeded\" | \"item_max_stack_exceeded\" | \"recipe_costs_unmet\" | \"quantity_invalid\" | \"error\"",
           "documented": true,
-          "summary": "Every reason a purchase can be refused, on either purchase path.\n\n- `unknown_currency` — the slug names no active platform currency. There are\n  no aliases: `TICKETS` is the retired name for Gems and is refused, never\n  resolved. Write `GEMS` or `ARCADE_TICKETS`.\n- `currency_not_in_game_payable` — the currency exists but cannot pay for game\n  items.\n- `not_purchasable` — the target is not in the purchase catalog, or cannot be\n  bought (not published on this channel, inactive, or its config does not\n  convert).\n- `no_price_in_currency` — the target has prices, but none in that currency.\n- `busy` — another purchase is in flight, a sheet is already open, the\n  platform is backing off after a cancel, or the ask came without a player's\n  click or key press.\n- `cancelled` — the player dismissed the platform sheet.\n- `insufficient_funds` — the player cannot afford it.\n- `price_mismatch`, `config_version_stale` — the price or config changed\n  between reading the catalog and buying; nothing was charged. Re-read.\n- `platform_currency_unavailable` — the currency is not available to this\n  purchase right now.\n- `not_available` — the recipe is outside its availability window, or\n  inactive; nothing was charged. Hide or disable it until its window opens.\n- `recipe_locked` — the recipe's prerequisites are not met.\n- `already_owned` — the player already owns the 3D avatar\n  `gem.avatars3d.purchase` asked for; nothing was charged. Only that call\n  answers it.\n- `recipe_on_cooldown`, `recipe_max_uses_exceeded`, `item_max_stack_exceeded`,\n  `recipe_costs_unmet`, `quantity_invalid` — the recipe or item refused this\n  purchase, before any charge.\n- `error` — anything else, including a reason this SDK version does not know\n  and an answer that never arrived.\n\nFOR YOUR LOGS AND YOUR SHOP'S STATE, NEVER FOR A PAYMENT SCREEN. Grey out a\nlocked recipe; fix a slug. Never draw a top-up, \"buy more\" or payment UI of\nyour own — only the arcade may, and a game screen that looks like one is an\nimitation of platform payment chrome.",
+          "summary": "Every reason a purchase can be refused, on either purchase path.\n\n- `unknown_currency` — the slug names no active platform currency. There are\n  no aliases: `TICKETS` is the retired name for Gems and is refused, never\n  resolved. Write `GEMS` or `ARCADE_TICKETS`.\n- `currency_not_in_game_payable` — the currency exists but cannot pay for game\n  items.\n- `not_purchasable` — the target is not in the purchase catalog, or cannot be\n  bought (not published on this channel, inactive, or its config does not\n  convert).\n- `no_price_in_currency` — the target has prices, but none in that currency.\n- `busy` — another purchase is in flight, a sheet is already open, the\n  platform is backing off after a cancel, or the ask came without a player's\n  click or key press.\n- `cancelled` — the player dismissed the platform sheet.\n- `insufficient_funds` — the player cannot afford it.\n- `price_mismatch`, `config_version_stale` — the price or config changed\n  between reading the catalog and buying; nothing was charged. Re-read.\n- `platform_currency_unavailable` — the currency is not available to this\n  purchase right now.\n- `not_available` — the recipe is outside its availability window, or\n  inactive; nothing was charged. Hide or disable it until its window opens.\n- `recipe_locked` — the recipe's prerequisites are not met.\n- `already_owned` — the player already owns the 3D avatar\n  `gem.avatars3d.purchase` asked for; nothing was charged. Only that call\n  answers it.\n- `guest_upgrade_required` — the player is playing as a guest, and the\n  platform lets only an account spend. Nothing was charged. TREAT IT EXACTLY\n  LIKE A DECLINE, AND DRAW NOTHING: the arcade offers the player an account\n  itself, over your game, and a sign-up or \"log in to buy\" screen of your own\n  would be a second one. A game on `gem.me.mutations.purchase` gets it as a\n  `GemApiError` after the SDK has already handed the attempt to the arcade.\n- `recipe_on_cooldown`, `recipe_max_uses_exceeded`, `item_max_stack_exceeded`,\n  `recipe_costs_unmet`, `quantity_invalid` — the recipe or item refused this\n  purchase, before any charge.\n- `error` — anything else, including a reason this SDK version does not know\n  and an answer that never arrived.\n\nFOR YOUR LOGS AND YOUR SHOP'S STATE, NEVER FOR A PAYMENT SCREEN. Grey out a\nlocked recipe; fix a slug. Never draw a top-up, \"buy more\" or payment UI of\nyour own — only the arcade may, and a game screen that looks like one is an\nimitation of platform payment chrome.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -17720,6 +18069,54 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "ShareRefusal",
+          "name": "ShareRefusal",
+          "anchor": "sharerefusal",
+          "group": "share",
+          "signature": "class ShareRefusal",
+          "documented": true,
+          "summary": "The arcade refused a share, and why. `gem.share.request`'s promise rejects\nwith it. Fix the params it names: the same share is refused again.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "ShareRefusal.reason",
+          "name": "reason",
+          "anchor": "sharerefusal-reason",
+          "group": "share",
+          "signature": "readonly reason: string",
+          "documented": true,
+          "summary": "Why, as a machine code. OPEN-ENDED, so keep a `default` arm:\n\n- `reserved_key` — [ShareRefusal.key](api-reference-game.md#sharerefusal-key) is a key the arcade keeps for\n  itself and does not carry in a share link.\n- `round_trip` — the link the arcade built does not read back as what you\n  asked for, or [ShareRefusal.key](api-reference-game.md#sharerefusal-key) is too long to carry.\n- `too_long` — the whole link is over 2 KB. Share fewer or shorter params.\n- `error` — the arcade refused without saying why.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "ShareRefusal.key",
+          "name": "key",
+          "anchor": "sharerefusal-key",
+          "group": "share",
+          "signature": "readonly key?: string",
+          "documented": true,
+          "summary": "The param key that caused it, exactly as you passed it, when one key did.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "ShareApi",
           "name": "ShareApi",
@@ -17757,9 +18154,9 @@
           "name": "request",
           "anchor": "shareapi-request",
           "group": "share",
-          "signature": "request(request?: ShareRequest): void",
+          "signature": "request(request?: ShareRequest): Promise<void>",
           "documented": true,
-          "summary": "Ask the arcade to share a link that opens your game with `params`. Call it\nsynchronously from your own Share button's click handler. It returns\nnothing, and nothing ever comes back — not even whether the player shared —\nso never gate progress or a reward on it.",
+          "summary": "Ask the arcade to share a link that opens your game with `params`. Call it\nsynchronously from your own Share button's click handler. Nothing about the\nplayer ever comes back — not even whether they shared — so never gate\nprogress or a reward on it.",
           "deprecated": null,
           "params": [
             {
@@ -17769,8 +18166,8 @@
               "summary": null
             }
           ],
-          "returns": null,
-          "throws": "`Error` when [ShareApi.available](api-reference-game.md#shareapi-available) is false, and `TypeError`,\n  naming the parameter, for one the arcade would refuse: more than 16, a\n  key that is not a letter followed by up to 63 letters, digits, `_` or\n  `-`, a key the arcade reserves for itself, or a value that is not a\n  string, is over 512 characters, or holds a control, format or unpaired\n  surrogate character. Nothing is sent when it throws.",
+          "returns": "a promise that REJECTS with a [ShareRefusal](api-reference-game.md#sharerefusal) when the arcade\n  refused the share, naming the reason and the param, and otherwise\n  resolves with nothing. Resolving does not mean the player shared, or saw\n  a sheet at all. An older arcade never refuses out loud, so there it\n  resolves at once.",
+          "throws": "`Error` when [ShareApi.available](api-reference-game.md#shareapi-available) is false, and `TypeError`,\n  naming the parameter, for one the arcade would refuse: more than 16, a\n  key that is not a letter followed by up to 63 letters, digits, `_` or\n  `-`, a key the arcade keeps for itself, or a value that is not a string,\n  is over 512 characters, or holds a control, format or unpaired surrogate\n  character. Nothing is sent when it throws. Which keys the arcade keeps\n  depends on the arcade: a current one carries reserved keys such as\n  `invite` and refuses only `embedder` (and `_s`, which is not a valid key\n  anyway); an older one refuses all of them.",
           "example": null,
           "defaultValue": null,
           "guides": []
@@ -30373,7 +30770,7 @@
           "group": "analytics",
           "signature": "type PlatformEventName = \"gem_session_start\" | \"gem_session_end\" | \"gem_pause\" | \"gem_resume\" | \"gem_boot_ready\" | \"gem_match_started\" | \"gem_match_ended\" | \"gem_auth_lost\" | \"gem_graphics_context_lost\"",
           "documented": true,
-          "summary": "Every event the SDK emits by itself.\n\nA game never sends these — `gem.analytics.track` refuses the whole\n`gem_` namespace — but the names are published because a game reading its\nown funnel needs the vocabulary, and because a funnel declared in the game\nconfig names them as steps.\n\n| Event | Dimensions | Measures |\n|---|---|---|\n| `gem_session_start` | — | — |\n| `gem_session_end` | `reason` ([SessionEndReason](api-reference-function.md#sessionendreason)) | `duration_ms` |\n| `gem_pause` / `gem_resume` | — | — |\n| `gem_boot_ready` | — | `boot_ms` |\n| `gem_match_started` / `gem_match_ended` | `transport` (`MatchTransport`) | — |\n| `gem_auth_lost` | — | — |\n| `gem_graphics_context_lost` | `gpu`, `host`, `route` | `context_ms`, `hidden`, `nth_loss` |\n\n`gem_graphics_context_lost` is the browser taking a WebGL context away —\nusually a GPU driver fault, sized per device across every game\n(`analytics/graphics.ts` lists the dimension values).",
+          "summary": "Every event the SDK emits by itself.\n\nA game never sends these — `gem.analytics.track` refuses the whole\n`gem_` namespace — but the names are published because a game reading its\nown funnel needs the vocabulary, and because a funnel declared in the game\nconfig names them as steps.\n\n| Event | Dimensions | Measures |\n|---|---|---|\n| `gem_session_start` | — | — |\n| `gem_session_end` | `reason` ([SessionEndReason](api-reference-function.md#sessionendreason)) | `duration_ms` |\n| `gem_pause` / `gem_resume` | — | — |\n| `gem_boot_ready` | — | `boot_ms` |\n| `gem_match_started` / `gem_match_ended` | `transport` (`MatchTransport`) | — |\n| `gem_auth_lost` | — | — |\n| `gem_graphics_context_lost` | `gpu`, `host`, `route` | `context_ms`, `hidden`, `nth_loss` |\n\n`gem_graphics_context_lost` is the browser taking a WebGL context away, or a\nWebGPU device (`route` is then `webgpu`) — usually a GPU driver fault, sized\nper device across every game (`analytics/graphics.ts` lists the dimension\nvalues).",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -33417,7 +33814,7 @@
           "group": "inventory",
           "signature": "purchase(request: ConfiguredPurchaseRequest, options?: PurchaseOptions): Promise<ConfiguredPurchaseResult>",
           "documented": true,
-          "summary": "Purchase an item or recipe through the game's authenticated SDK transport.\n\nOne call covers both direct payment types:\n\n- `payment: { kind: 'configured' }` runs a recipe and charges the costs in\n  your game config.\n- `payment: { kind: 'platform_currency', currencySlug: 'GEMS' }` resolves\n  the target's published platform price and spends the player's platform\n  balance directly. It does not send a bridge message or open the platform\n  purchase sheet; your game owns any confirmation UI.\n\nThe game supplies no amount, config version or nonce. The SDK resolves the\ncurrent published price and config version, mints the nonce, and the\nplatform checks all of them again before it debits anything.\n\nA REFUSAL CARRIES A `code` — branch on `err.code`, in the vocabulary\n`gem.purchases.request` answers in (`PurchaseRefusalCode`). Before\nsending a `platform_currency` payment the SDK itself throws a\n`PurchaseRefusal` (a `RangeError`) for `unknown_currency`,\n`not_purchasable`, `no_price_in_currency` or `quantity_invalid`, with a\nmessage naming the active slugs or what the target is priced in. The\nplatform's own refusals arrive as a `GemApiError` whose `code` is its wire\ncode — `insufficient_funds`, `recipe_locked`, `price_mismatch`, … Never\ndraw a top-up or payment screen of your own for either.",
+          "summary": "Purchase an item or recipe through the game's authenticated SDK transport.\n\nOne call covers both direct payment types:\n\n- `payment: { kind: 'configured' }` runs a recipe and charges the costs in\n  your game config.\n- `payment: { kind: 'platform_currency', currencySlug: 'GEMS' }` resolves\n  the target's published platform price and spends the player's platform\n  balance directly. It does not send a bridge message or open the platform\n  purchase sheet; your game owns any confirmation UI.\n\nThe game supplies no amount, config version or nonce. The SDK resolves the\ncurrent published price and config version, mints the nonce, and the\nplatform checks all of them again before it debits anything.\n\nA REFUSAL CARRIES A `code` — branch on `err.code`, in the vocabulary\n`gem.purchases.request` answers in (`PurchaseRefusalCode`). Before\nsending a `platform_currency` payment the SDK itself throws a\n`PurchaseRefusal` (a `RangeError`) for `unknown_currency`,\n`not_purchasable`, `no_price_in_currency` or `quantity_invalid`, with a\nmessage naming the active slugs or what the target is priced in. The\nplatform's own refusals arrive as a `GemApiError` whose `code` is its wire\ncode — `insufficient_funds`, `recipe_locked`, `price_mismatch`, … Never\ndraw a top-up or payment screen of your own for either.\n\n`guest_upgrade_required` means the player is a guest, and the platform\nlets only an account spend. TREAT IT LIKE A DECLINE AND DRAW NOTHING: the\nSDK has already handed the attempt to the arcade, which offers the player\nan account over your game. The call rejects at once rather than waiting\nfor them; if they make one and buy, `PurchaseApi.onSettled` hears it.",
           "deprecated": null,
           "params": [
             {

package/docs/arcade-economy.md

@@ -116,8 +116,8 @@ them only for fraud or moderation ([achievements.md](achievements.md)).
 ## 5. Spending: price each item in the currency it deserves
 
 Any game may sell an item or a recipe for a platform currency, with no server and no approval: the
-item or recipe carries `platform_prices`, and the player pays through the arcade's purchase sheet or
-your own purchase screen
+item or recipe carries `platform_prices`, and the player pays through the arcade's purchase sheet,
+`gem.purchases.request`
 ([inventory-and-catalogs.md](inventory-and-catalogs.md#16-selling-for-a-platform-currency)). What a
 currency may price is a platform setting on that currency, its **spend scope**:
 

package/docs/changelog.md

@@ -16,6 +16,35 @@ 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.
 
+## 21.1.1
+
+Upgrading from 21.1.0. Impact: none.
+
+Nothing in this release asks anything of a game.
+
+## 21.1.0
+
+Upgrading from 21.0.0. Impact: required.
+
+### Must change
+
+- ShareApi.request now returns a promise instead of nothing. When the Arcade refuses a share, the promise rejects with a ShareRefusal that names the reason and the offending param. Await the call and handle the rejection, for example by telling the player the share could not be sent. With an older Arcade the promise resolves at once, as before. The SDK also refuses, before sending, share params whose keys the Arcade reserves for its own play links, and the error names the key. If your game uses such a name as its own share param, rename it. A current Arcade carries most reserved keys through a share link and returns them unchanged, but an older one still refuses them.
+- PurchaseRefusalCode has a new value, guest_upgrade_required, returned when a web guest tries to spend platform currency directly. Treat it like any other decline: draw no purchase, and do not retry. If you switch over the refusal codes exhaustively, add a case for it or your code will stop compiling.
+
+### Should change
+
+- Spend Gems and Coins through the Arcade's purchase sheet, not through a direct spend on the entity mutations. A web guest's direct spend is now refused. The SDK hands that one refusal to the Arcade as a safety net and rejects your call with the original error straight away, without waiting for an answer or retrying. Move any direct platform-currency spend to the purchase sheet flow. See [the deprecation policy](deprecation-policy.md#4-what-is-deprecated-today).
+
+### Rebuild
+
+- Several types and signatures changed in compatible ways: GemFrame.requestPurchase gained an optional origin argument, GemFrame.requestShare gained an optional requestId argument, the MutationsApi constructor gained an optional hand-off callback, and GemCapability, ParentMessage and PARENT_TO_FRAME gained new capabilities and message kinds for purchase settlement, graphics routes and share results. Recompiling is enough. If you test against your own stand-in for the Arcade, rebuild it against this release and bring it up to the newer parent conformance version.
+
+### New capability
+
+- PurchaseApi.onSettled lets a game hear a purchase that completed after its original call had already been answered, for example one finished through the Arcade after a guest's refused spend. The game is told once the platform confirms the purchase, as a PurchaseSettlement, and the player's data is refreshed. Subscribe to it so you can grant the purchase when it lands. It only fires on an Arcade that supports it.
+- Gem.graphics lets a game ask which renderer to create just before it creates one. The answer says the route to use and whether the device is on the platform's list of devices known to draw wrongly on WebGL. The answer is WebGL everywhere except on a listed device, and there WebGPU only if it hands out an adapter. A listed device with no working WebGPU gets your safe WebGL recipe. The call is time-bounded and never rejects. The list ships built in, and the Arcade can replace it for live games without a rebuild. Call it before creating a renderer and make every canvas follow the answer.
+- A new dev-tools entry point is available for a game's dev-only code, such as a cheat panel, level skipper or debug menu. Importing it from that code marks the build as carrying dev-only code. Builds so marked can be uploaded and played on the dev channel but are refused on the test and release channels. Keep the import behind a build-time switch that is off for test and release builds so the marker is absent from them.
+
 ## 21.0.0
 
 Upgrading from 20.1.0. Impact: required.

package/docs/game-economy-tutorial.md

@@ -268,7 +268,7 @@ if (av.locked) {
 The platform checks the prerequisite **before** it takes any Coins: a locked player who buys
 anyway is refused `recipe_locked` and charged nothing. See
 [`inventory-and-catalogs.md`](inventory-and-catalogs.md#16-selling-for-a-platform-currency) for the
-two purchase paths and the full rule.
+full rule, and why platform currency is spent through the arcade's sheet.
 
 ### Buying it, and reading a refusal
 
@@ -291,8 +291,11 @@ if (res.outcome === 'ok' || res.outcome === 'unavailable') {
 }
 ```
 
-With your own purchase screen (`gem.me.mutations.purchase`), the same strings arrive as `err.code`
-— see [`inventory-and-catalogs.md`](inventory-and-catalogs.md#why-a-purchase-was-refused).
+Spend Coins and Gems through this sheet, never `gem.me.mutations.purchase`: on gemarcade.com a web
+guest is refused a direct spend (`guest_upgrade_required`), and the sheet is where the arcade offers
+them an account. A recipe your game charges in its own currency (`payment: { kind: 'configured' }`)
+reports the same strings as `err.code` — see
+[`inventory-and-catalogs.md`](inventory-and-catalogs.md#why-a-purchase-was-refused).
 
 **Never draw a top-up or payment screen of your own** — no "get more Coins", no checkout, nothing
 shaped like the arcade's purchase sheet. A player short of Coins earns more by playing; your shop