@indiegems/gem-web-sdk 20.1.0 → 21.1.0

package/docs/api/reference.json

@@ -2,7 +2,7 @@
   "schema_version": 2,
   "source": {
     "repo": "IndieGems/gem-web-sdk",
-    "version": "20.1.0"
+    "version": "21.1.0"
   },
   "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": [
             {
@@ -4733,9 +4737,9 @@
           "name": "PlatformEventName",
           "anchor": "platformeventname",
           "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\"",
+          "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` | — | — |",
+          "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": []
@@ -30371,9 +30768,9 @@
           "name": "PlatformEventName",
           "anchor": "platformeventname",
           "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\"",
+          "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` | — | — |",
+          "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**: