@indiegems/gem-web-sdk 20.1.0 → 21.1.0

package/docs/inventory-and-catalogs.md

@@ -654,18 +654,25 @@ subject. [brand-art.md](brand-art.md) has both, how to draw them, and the rest o
 
 ### Being paid in one
 
-Every game can choose between two purchase owners for the same published platform price:
-
-| Call                             | Who owns confirmation | Transport                                                     | Result                                   |
-| -------------------------------- | --------------------- | ------------------------------------------------------------- | ---------------------------------------- |
-| `gem.purchases.request(...)`     | the platform          | postMessage bridge; platform sheet always opens               | `ok`, `declined`, or `unavailable`       |
-| `gem.me.mutations.purchase(...)` | your game             | direct authenticated SDK request; no bridge or platform sheet | an order-style result or a `GemApiError` |
-
-There is no approval step. Both paths are available to every game.
+**Spend platform currency with `gem.purchases.request`.** Every game sells for Gems, Coins or any
+other platform currency through the arcade's buy sheet: the platform confirms the purchase with the
+player, offers a guest an account, and processes the order. Build your shop's Buy button on it.
+
+| Call                             | Who owns confirmation | Transport                                                     | Use it for                                                                          |
+| -------------------------------- | --------------------- | ------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| `gem.purchases.request(...)`     | the platform          | postMessage bridge; platform sheet always opens               | **every platform-currency purchase** — answers `ok`, `declined` or `unavailable`    |
+| `gem.me.mutations.purchase(...)` | your game             | direct authenticated SDK request; no bridge or platform sheet | recipes paid in your own game currency or items (`payment: { kind: 'configured' }`) |
+
+`gem.me.mutations.purchase` with a `platform_currency` payment is **not for spending on
+gemarcade.com**. A web guest has no account the platform lets spend, so gem-api refuses them
+`guest_upgrade_required`; the SDK then hands the attempt to the arcade as a safety net (see
+[Game-owned direct purchase](#game-owned-direct-purchase)), but that is a fallback for games that
+have not moved yet, not a flow to design for. A game that spends directly today should move its Buy
+button to `gem.purchases.request`.
 
 #### Platform-owned purchase sheet
 
-Use the bridge path when you want the arcade to confirm and process the purchase:
+This is how a game spends platform currency. The arcade confirms and processes the purchase:
 
 ```js
 const config = await gem.gameConfig.load();
@@ -705,8 +712,8 @@ button's handler, never from a timer or on load: without one the answer is `decl
 `busy`, and nothing is shown. After a player cancels, the arcade answers further asks from your
 game `busy` for a short, growing interval — do not re-ask on `cancelled`.
 
-Hide this specific affordance when `gem.frame.parentSupports('purchases')` is false. That check does
-not apply to the direct SDK path.
+Hide your Buy button when `gem.frame.parentSupports('purchases')` is false: that parent cannot sell
+for platform currency.
 
 The sheet shows the item's or recipe's picture from its `icon_url`. You never write that field: it
 is the `icon:` file you upload with your config (`icon: icons/extra-life.png` in the YAML, uploaded
@@ -731,7 +738,12 @@ backend it answers `undefined` by design: there, your placeholder is what you se
 
 #### Game-owned direct purchase
 
-Use the direct path when your game provides its own purchase UI and does not want the platform sheet:
+The direct path submits an order from your game with no platform sheet. Its job is recipes paid in
+your own game currency or items (`payment: { kind: 'configured' }`, below). It also accepts a
+`platform_currency` payment, but **do not spend platform currency this way on gemarcade.com**: a
+web guest is refused (below), and every game spends Gems and Coins through
+[the sheet](#platform-owned-purchase-sheet). The form is documented for games that have not moved
+yet:
 
 ```js
 const result = await gem.me.mutations.purchase({
@@ -809,6 +821,35 @@ try {
 Do not retry an unsafe write after a timeout; re-read inventory or use the returned order/purchase
 ids for support.
 
+**A guest is refused `guest_upgrade_required`, and you draw nothing.** The platform lets only a
+player with an account spend Gems or Coins — which is why platform currency is spent through
+[the sheet](#platform-owned-purchase-sheet), where the arcade handles a guest itself. This is the
+safety net for a game that still spends directly. When a guest's direct purchase is refused, the SDK
+hands the attempt to the arcade, which offers the player an account over your game, and your call
+rejects at once with a `GemApiError` whose `code` is `guest_upgrade_required`. Treat it exactly
+like a decline: return to the shop silently, with no sign-up, "log in to buy" or error screen of
+your own — the arcade's is already showing. The `default` arm of the switch above must not draw
+anything for it either, so give it a quiet case of its own:
+
+```js
+case 'guest_upgrade_required':
+  return; // the arcade is offering the player an account; draw nothing
+```
+
+If the player makes an account and buys the item from the arcade's sheet, the purchase completes
+after your call has answered — sometimes after a reload. Hear it with `gem.purchases.onSettled`:
+
+```js
+gem.purchases.onSettled(({ kind, targetId, quantity }) => {
+  showGrantFeedback(targetId, quantity); // then re-read; the SDK already refreshed gem.me
+});
+```
+
+The SDK confirms the purchase with the platform before it calls you, and refreshes `gem.me`, so
+`gem.me.inventory.onChanged` fires too. It hears nothing on an arcade that does not support it, and
+never for a purchase an `ok` already reported. This needs SDK 21.1.0 or later; an older build shows
+the guest your `default` arm instead of the arcade's offer.
+
 **`targetId` is the UUID, never the slug.** `config.item(...)` accepts either because it is your
 local lookup. The purchase catalog is keyed by ids. Recipes also require `catalogId`.
 
@@ -817,21 +858,22 @@ local lookup. The purchase catalog is keyed by ids. Recipes also require `catalo
 One vocabulary covers both paths: the sheet's `res.reason` and the direct path's `err.code` are
 the same strings.
 
-| Code                                                                                                                  | What happened                                                                   | What to do                                                                       |
-| --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
-| `unknown_currency`                                                                                                    | the slug is not an active platform currency                                     | write `ARCADE_TICKETS` or `GEMS`; the direct path's message lists what is active |
-| `currency_not_in_game_payable`                                                                                        | the currency exists but cannot pay for game items                               | price in a currency `gemctl platform config` lists under `platform_prices`       |
-| `not_purchasable`                                                                                                     | the target is not in the purchase catalog on this channel, or cannot be bought  | send the id (not the slug); promote the config version that prices it            |
-| `no_price_in_currency`                                                                                                | the target has no price in that currency                                        | ask in the currency it is priced in, or add the price                            |
-| `busy`                                                                                                                | a purchase is already in flight, or a sheet is open                             | ask again only from a fresh player action                                        |
-| `cancelled`                                                                                                           | the player dismissed the sheet                                                  | nothing — return to the shop                                                     |
-| `insufficient_funds`                                                                                                  | the player cannot afford it                                                     | say so in your shop's words; never draw a top-up screen                          |
-| `price_mismatch`, `config_version_stale`                                                                              | the price or config changed since your catalog read; nothing was charged        | re-read the catalog and re-render                                                |
-| `platform_currency_unavailable`                                                                                       | the currency is not available to this purchase right now                        | show the store as unavailable                                                    |
-| `not_available`                                                                                                       | the recipe is outside its availability window, or inactive; nothing was charged | hide or disable the row until its window opens                                   |
-| `recipe_locked`                                                                                                       | the recipe's prerequisites are not met; nothing was charged                     | show the lock from `recipeAvailability().lockReasons`                            |
-| `recipe_on_cooldown`, `recipe_max_uses_exceeded`, `item_max_stack_exceeded`, `recipe_costs_unmet`, `quantity_invalid` | the recipe or item refused this purchase before any charge                      | reflect it on the row; `recipeAvailability` has the detail                       |
-| `error`                                                                                                               | anything else, or no reliable answer                                            | one neutral "store unavailable"; after `unavailable`, re-read inventory          |
+| Code                                                                                                                  | What happened                                                                          | What to do                                                                       |
+| --------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| `unknown_currency`                                                                                                    | the slug is not an active platform currency                                            | write `ARCADE_TICKETS` or `GEMS`; the direct path's message lists what is active |
+| `currency_not_in_game_payable`                                                                                        | the currency exists but cannot pay for game items                                      | price in a currency `gemctl platform config` lists under `platform_prices`       |
+| `not_purchasable`                                                                                                     | the target is not in the purchase catalog on this channel, or cannot be bought         | send the id (not the slug); promote the config version that prices it            |
+| `no_price_in_currency`                                                                                                | the target has no price in that currency                                               | ask in the currency it is priced in, or add the price                            |
+| `busy`                                                                                                                | a purchase is in flight, a sheet is open, or the arcade is offering a guest an account | ask again only from a fresh player action                                        |
+| `cancelled`                                                                                                           | the player dismissed the sheet                                                         | nothing — return to the shop                                                     |
+| `insufficient_funds`                                                                                                  | the player cannot afford it                                                            | say so in your shop's words; never draw a top-up screen                          |
+| `guest_upgrade_required`                                                                                              | the player is a guest; only an account may spend. Nothing was charged                  | nothing — the arcade offers them an account; draw no sign-up screen of your own  |
+| `price_mismatch`, `config_version_stale`                                                                              | the price or config changed since your catalog read; nothing was charged               | re-read the catalog and re-render                                                |
+| `platform_currency_unavailable`                                                                                       | the currency is not available to this purchase right now                               | show the store as unavailable                                                    |
+| `not_available`                                                                                                       | the recipe is outside its availability window, or inactive; nothing was charged        | hide or disable the row until its window opens                                   |
+| `recipe_locked`                                                                                                       | the recipe's prerequisites are not met; nothing was charged                            | show the lock from `recipeAvailability().lockReasons`                            |
+| `recipe_on_cooldown`, `recipe_max_uses_exceeded`, `item_max_stack_exceeded`, `recipe_costs_unmet`, `quantity_invalid` | the recipe or item refused this purchase before any charge                             | reflect it on the row; `recipeAvailability` has the detail                       |
+| `error`                                                                                                               | anything else, or no reliable answer                                                   | one neutral "store unavailable"; after `unavailable`, re-read inventory          |
 
 Reasons are for your shop's state and your logs. Branch money on `outcome` and on a re-read of
 inventory, never on a reason, and do not retry because of one.

package/docs/manifest.json

@@ -13,8 +13,8 @@
     },
     {
       "file": "analytics.md",
-      "sha256": "42f3d0d3360e1a6066c21015bd4925475b4336a53611bf04acb773a7c6084e62",
-      "updated": "2026-10-30T16:54:41Z"
+      "sha256": "5814655859e3d6b223f94b71f1b064783b0f242d409c3ec3078089cb4b7c8ec5",
+      "updated": "2026-11-04T17:17:14Z"
     },
     {
       "file": "arcade-and-store.md",
@@ -28,8 +28,8 @@
     },
     {
       "file": "arcade-economy.md",
-      "sha256": "b72474b4694842a1fda030ab9df79987d2906f7a8c922e8630622d747a4b2c3c",
-      "updated": "2026-10-30T13:36:37Z"
+      "sha256": "c0f25495a536d5facdbb63cbcd89acf558e2fe79d44f3a99d35284de1937fc42",
+      "updated": "2026-11-04T17:09:56Z"
     },
     {
       "file": "async-opponents.md",
@@ -38,8 +38,8 @@
     },
     {
       "file": "brand-art.md",
-      "sha256": "b7f8dda1afdb8d56cadee752e6b09fc62238372b68ebc8a746518e528f52e167",
-      "updated": "2026-10-29T21:40:17Z"
+      "sha256": "7d4d5c7226710742efdb958e10387d5e5a3de0622a686734c885720e16a5b128",
+      "updated": "2026-11-02T21:18:05Z"
     },
     {
       "file": "branding.md",
@@ -48,8 +48,8 @@
     },
     {
       "file": "changelog.md",
-      "sha256": "8a292ee18fe7f910be0af049d96df66ccebf5c810fe5495c11d5352f7ee121f4",
-      "updated": "2026-11-03T00:39:38Z"
+      "sha256": "31164cb6810097240ce18733c76b45b0b3e5ba9cda6738bfce7e27503cd90ad1",
+      "updated": "2026-11-04T19:04:00Z"
     },
     {
       "file": "daily-challenges.md",
@@ -73,18 +73,23 @@
     },
     {
       "file": "game-economy-tutorial.md",
-      "sha256": "c037a74f206f094392f09e0f7b292271145a4d72b631b93f878705171e52475a",
-      "updated": "2026-10-25T19:46:22Z"
+      "sha256": "0ab25a9d69cf5e40351624355da5ef84e1431bf8a8a420e2c4d7350e20a5b1c5",
+      "updated": "2026-11-04T16:44:33Z"
     },
     {
       "file": "getting-started.md",
-      "sha256": "0c4cee83ffc77711f43ccdaafb394283a5a412b78395db1434ebbc2ab6943667",
-      "updated": "2026-11-03T00:39:38Z"
+      "sha256": "4cb0f2fec9438cd03a2a785ad6247fe60b32d95c9a9fdcbf0e2cc4390c9f767a",
+      "updated": "2026-11-04T19:04:00Z"
+    },
+    {
+      "file": "graphics-route.md",
+      "sha256": "c71c826502b415a89dd069f79d22b82f7a9fe49c9da7f5e7a1052763c826f41f",
+      "updated": "2026-11-04T17:45:35Z"
     },
     {
       "file": "inventory-and-catalogs.md",
-      "sha256": "dab6e42f4ad5cc2a63c2adb11e85053f963cd3166d1c447394cd6f532bb6c006",
-      "updated": "2026-11-02T18:42:37Z"
+      "sha256": "2094c555eb5a1a3d817a597ac07b2b193077f92176eb9596c2ba3ed461363bb6",
+      "updated": "2026-11-04T16:43:14Z"
     },
     {
       "file": "leaderboards.md",
@@ -138,8 +143,8 @@
     },
     {
       "file": "server-bundles.md",
-      "sha256": "f54aeb88c268e5b657be9d0ea323d44cc61bfbb76fc84670f8a607d4514b005d",
-      "updated": "2026-11-03T00:39:38Z"
+      "sha256": "a0df89891432d799fe7ad59534c68265937fe5096739afa5fbe230de97837af3",
+      "updated": "2026-11-04T19:04:00Z"
     },
     {
       "file": "serverless-functions-js.md",
@@ -163,8 +168,8 @@
     },
     {
       "file": "what-a-game-must-do.md",
-      "sha256": "059f3c8a31c0f6098d2c8e4836b79e866d0c5486443dc89039e160648946bd68",
-      "updated": "2026-11-02T23:27:22Z"
+      "sha256": "523886cf799570ab3631bbc9db11e03554d2ad403a1083d94038a48acd4fb611",
+      "updated": "2026-11-04T18:23:48Z"
     }
   ]
 }

package/docs/server-bundles.md

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

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

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

package/package.json

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