@indiegems/gem-web-sdk 21.0.0 → 21.1.1

package/docs/getting-started.md

@@ -50,7 +50,7 @@ either way.
 ```jsonc
 // package.json
 "dependencies": {
-  "@indiegems/gem-web-sdk": "21.0.0"
+  "@indiegems/gem-web-sdk": "21.1.1"
 }
 ```
 
@@ -294,21 +294,33 @@ parameters the link should open your game with:
 shareButton.hidden = !gem.share.available;
 shareButton.addEventListener('click', () => {
   if (!gem.share.available) return;
-  gem.share.request({ params: { jar: 'JAR-K7P3QXM', n: '2', beat: '812' } });
+  gem.share.request({ params: { jar: 'JAR-K7P3QXM', n: '2', beat: '812' } }).catch((err) => {
+    // A ShareRefusal: the arcade refused this link. err.reason and err.key say
+    // what to fix. Log it for yourself; show the player nothing.
+    console.warn(err);
+  });
 });
 ```
 
 The arcade builds the link, which unfurls with your game's own card, and shares it through the
-player's share sheet, a copy, or its own Share panel. Your game is told nothing back — not
-whether the player shared, cancelled, or closed the panel — and `request` returns nothing.
-Where the arcade handles it, `gem.share.available` is true; outside the arcade, before the
-bridge is up, and anywhere the arcade does not share your game, it is false.
+player's share sheet, a copy, or its own Share panel. Nothing about the player comes back — not
+whether they shared, cancelled, or closed the panel. Where the arcade handles it,
+`gem.share.available` is true; outside the arcade, before the bridge is up, and anywhere the
+arcade does not share your game, it is false.
 
 `request` checks every parameter against the rules below **before** anything is sent, and
 throws on the first one the arcade would refuse, naming it: more than 16, a key that breaks the
-key rule or is one of the arcade's own, or a value that is not a string, is too long, or holds
-a character a link cannot carry. A mistake shows up at your desk, not as a Share button that
-does nothing for players — try it in the SDK's `examples/dev-harness/` with **share** ticked.
+key rule or is one the arcade will not carry, or a value that is not a string, is too long, or
+holds a character a link cannot carry. A mistake shows up at your desk, not as a Share button
+that does nothing for players — try it in the SDK's `examples/dev-harness/` with **share**
+ticked.
+
+`request` also returns a promise. It **rejects with a `ShareRefusal`** when the arcade refuses
+the link anyway, which only it can judge — the whole link over 2 KB, say — with `err.reason`
+(`reserved_key`, `round_trip`, `too_long`, or a code newer than your SDK) and `err.key`, the
+parameter that caused it when one did. Otherwise it resolves, and resolving says only that the
+arcade took the request, never that a player shared. An older arcade does not answer, so there
+it resolves at once. Catch it: an uncaught refusal is an unhandled rejection in your console.
 
 **Where `available` is false, build the link yourself.** Use the `/games/<id>` page with
 `play=1`, which opens straight into your game and unfurls with its card, and hand it to the
@@ -343,32 +355,43 @@ const jarIndex = Number.isInteger(n) && n >= 1 && n <= JAR_COUNT ? n : null;
 
 That is the whole contract for your own keys. The bridge carries no launch message, and the SDK
 has no API for them: the arcade does the forwarding, so a build you published on any SDK version
-gets it without a code change. Two keys are not yours, and they are the platform's (below):
-`gemChallenge`, which belongs to [friend challenges](friends.md#friend-challenges), and
+gets it without a code change. Three keys are not yours, and they are the platform's (below):
+`gemChallenge`, which belongs to [friend challenges](friends.md#friend-challenges),
 `gemPlayWith`, an opaque ticket the arcade adds when it opens your game to play with a friend or a
-party mate, which names nobody your game can recognise. Never define either, and never parse
-either yourself. The SDK reads them for you —
-`gem.friends.launchedChallenge()` answers the challenge `gemChallenge` names, or `null`, and every
+party mate, which names nobody your game can recognise, and `gemGraphics`, which a developer adds
+to force [the graphics route](graphics-route.md#testing-the-gemgraphics-launch-key) while
+testing. Never define any of them, and never parse them yourself. The SDK reads them for you —
+`gem.friends.launchedChallenge()` answers the challenge `gemChallenge` names, or `null`, every
 `gem.rooms.quickJoin()` passes `gemPlayWith` on
-([Landing in a friend's room](rooms-and-matches.md#5e-landing-in-a-friends-room-play-with)) — and
-they are the only launch keys it reads. Each is read once, when `createGem` runs, so cleaning your
-URL afterwards does not lose it. Call `createGem` before you clean the URL, or leave both keys in
+([Landing in a friend's room](rooms-and-matches.md#5e-landing-in-a-friends-room-play-with)), and
+`gem.graphics.preferredRoute()` answers what `gemGraphics` forces — and they are the only launch
+keys it reads. Each is read once, when `createGem` runs, so cleaning your
+URL afterwards does not lose it. Call `createGem` before you clean the URL, or leave these keys in
 place: a key removed before `createGem` runs is never seen, so `launchedChallenge()` resolves
 `null` with no error and a quick-join plays with nobody.
 
-What reaches the frame:
+What reaches the frame. These rules are gem-api's published launch-query rules
+(`launch-query-rules.json`), the one source the arcade's website and the SDK both read; this page
+and `gem.share.request` are checked against that file, so the keys and limits below are the ones
+the arcade applies:
 
 - **The query only.** A fragment (`#…`) is never forwarded.
 - **Not the arcade's own keys.** These are stripped and never reach the game, and they are the
   only keys the arcade keeps for itself; it never interprets yours:
   - Store and play-page switches: `play`, `channel`, `purchase`, and `build`, which pins one
     of your own builds when you play it from your Builds page.
-  - Platform switches: `devtools`, `devLocale`, and `gem_test_ads`, the mode of the arcade's
-    rewarded TEST ads.
-  - The arcade's own sign-in return marker: `social`.
-  - Attribution and campaign keys, which the arcade keeps out of every game: `_s`, `utm_*`
-    (every key with that prefix, matched case-sensitively, so UTM_X and utmost are yours),
-    `fbclid`, `ttclid`, `gclid`, `msclkid`.
+  - Platform switches: `devtools`, `devLocale`, `gem_test_ads`, the mode of the arcade's
+    rewarded TEST ads, and `moments` and `ads`, the dev host's test moment and ad modes.
+  - The arcade's own sign-up and sign-in keys: `invite`, a friend's invite code, and `social`,
+    the sign-in return marker.
+  - Attribution and campaign keys: `_s`, `utm_*` (every key with that prefix, matched
+    case-sensitively, so UTM_X and utmost are yours), `fbclid`, `ttclid`, `gclid`, `gbraid`,
+    `wbraid`, `msclkid`. The arcade strips the visitor's own campaign and click ids, but a link
+    a game shares, or one anyone writes by hand, can still put `utm_*` and the click ids into
+    your frame, restored from their escaped form.
+
+  A link your game shares can still carry most of them: see
+  [Sharing a reserved key](#sharing-a-reserved-key) below.
   - `embedder`, which stays what
     [the embedder allowlist](what-a-game-must-do.md#1-the-embedder-allowlist) says: never read
     from the URL — a link cannot even try.
@@ -376,16 +399,40 @@ What reaches the frame:
   A key starting with `_` can never be one of yours: the key rule below requires a leading
   letter, so the arcade keeps that space for itself.
 
-- **Two platform keys.** `gemChallenge` and `gemPlayWith` do reach the frame — the arcade adds the
-  first when a player opens a friend challenge, and the second when it opens your game to play
-  with someone — but they are the platform's, not yours: read the challenge with
-  `gem.friends.launchedChallenge()`, let `gem.rooms.quickJoin()` carry `gemPlayWith`, and never
-  read either from the URL. Do not define a key of either name, and treat every key beginning
-  with `gem` as reserved: a friend-challenge template refuses a param named that way.
+- **Three platform keys.** `gemChallenge`, `gemPlayWith` and `gemGraphics` do reach the frame —
+  the arcade adds the first when a player opens a friend challenge, and the second when it opens
+  your game to play with someone, and you add the third yourself to test the graphics route — but
+  they are the platform's, not yours: read the challenge with `gem.friends.launchedChallenge()`,
+  let `gem.rooms.quickJoin()` carry `gemPlayWith`, ask `gem.graphics.preferredRoute()` rather than
+  reading `gemGraphics`, and never read any of them from the URL. Do not define a key of any of
+  these names, and treat every key beginning with `gem` as reserved: a friend-challenge template
+  refuses a param named that way.
 - **Bounded.** At most 16 parameters. A key is a letter followed by up to 63 letters, digits,
   `_` or `-`. A value is at most 512 characters with no control or format characters. An entry
   that breaks a rule is dropped on its own; the rest of the link still arrives.
 
+#### Sharing a reserved key
+
+A current arcade carries the arcade's own keys in a link your game shares, so you never need to
+rename a parameter for it. It writes each one into the link under an escaped name it never reads
+itself, and puts the original name back before your game reads its URL: share
+`{ island: '7', invite: 'K2' }` and the frame that link opens reads `island=7&invite=K2`. The
+arcade's own uses of those keys are unaffected — an invite it put in a link itself still signs a
+friend up, and still never reaches your game.
+
+A restored click id or `utm_` value is whatever the link says. Anyone who edits a share link can
+forge one, and third-party tags in your frame (analytics, ads) will read it as attribution. Never
+trust it as attribution.
+
+Two keys it never carries: `embedder`, and `_s`, which breaks the key rule anyway. A key it has
+to escape must also stay a valid key once escaped, so keep a reserved one (a `utm_` key, say) to
+57 characters. `gem.share.request` throws on each of these before it sends.
+
+An older arcade, or a development host that has not caught up, refuses the whole share on any
+reserved key and does not say why. So where the arcade has not said it carries them,
+`gem.share.request` throws on every reserved key before it sends, naming the key — rename the
+parameter there, or wait for the arcade.
+
 Four things to hold onto when you share:
 
 **Call `request` synchronously from your own Share button's click handler.** Never from a
@@ -393,7 +440,8 @@ timer, after an `await`, or on a game event such as a win: the arcade only share
 player's own click, and anywhere else it opens its Share panel instead, if it does anything.
 
 **Never gate progress or a reward on sharing.** You cannot tell whether a player shared — the
-arcade does not say, by design — so a reward for sharing is a reward for pressing a button.
+arcade does not say, by design, and a resolved `request` does not mean it — so a reward for
+sharing is a reward for pressing a button.
 
 **Put no personal identifiers in the parameters.** No player id, name, email or anything that
 leads back to a person: the link is public, and it is handed to whoever the player sends it to.
@@ -461,6 +509,53 @@ disagree. Running it twice is safe — it replaces what it finds.
 **Your bundler does not matter.** It is a command rather than a plugin, so anything that ends
 with a directory you upload can run it, including a build you assembled by hand.
 
+### Keep dev-only code on the dev channel
+
+A cheat panel, a level skipper or a debug menu is worth having in the builds you test, and must
+never reach a player. **Mark it, and the platform keeps it off the test and release channels for
+you.** Import the SDK's dev-tools mark from your dev-only code, and from nowhere else:
+
+```ts
+// src/dev/index.ts — everything dev-only lives under src/dev/
+import '@indiegems/gem-web-sdk/dev-tools';
+
+export function mountDevPanel() {
+  /* ... */
+}
+```
+
+A build that carries that code carries the mark. It uploads and plays on `dev` as usual, and a
+promote to `test` or `release` is refused, naming the build.
+
+Load the dev code behind one switch your bundler sets at build time, so a release build leaves
+it out entirely, mark included:
+
+```ts
+// src/main.ts
+declare const __DEV_TOOLS__: boolean;
+if (__DEV_TOOLS__) void import('./dev').then((m) => m.mountDevPanel());
+```
+
+```ts
+// vite.config.ts
+export default defineConfig(({ mode }) => ({
+  define: { __DEV_TOOLS__: JSON.stringify(mode !== 'release') },
+}));
+```
+
+```jsonc
+// package.json
+"scripts": {
+  "build": "vite build && gem-sdk-stamp dist",
+  "build:release": "vite build --mode release && gem-sdk-stamp dist"
+}
+```
+
+`build` is the one you play and put on `dev`; `build:release` is the one you upload for `test`
+and `release`. **Use a build-time switch, never one read at run time** (a URL parameter, a key
+combination, the channel the game finds itself on): those leave the code in the files every
+player downloads, for anyone to read and switch on.
+
 ### Then upload and promote
 
 ```bash

package/docs/graphics-route.md

@@ -0,0 +1,188 @@
+# WebGL or WebGPU: ask before you make your renderer
+
+Some phones crash under WebGL. On the Pixel 10 (its PowerVR D-Series GPU), the phone's OpenGL ES
+graphics driver fails under WebGL. In Chrome a three.js game there shows a white board while its
+HTML still draws. In the Gem Arcade Android app it is worse: the app's WebView draws on the same
+driver, inside the app's own process, so the crash closes the whole app. WebGPU on the same phone
+runs on a different driver and draws cleanly, in Chrome and in the app.
+
+So the SDK tells your game which renderer to make. Ask it once, just before you make your first
+renderer, and follow the answer:
+
+```js
+const { route, listed } = await gem.graphics.preferredRoute();
+// route: 'webgpu' or 'webgl'. listed: whether this device is listed as broken on WebGL.
+```
+
+**WebGL is the answer almost everywhere.** WebGPU generally performs worse out of the box, so
+`route` is `webgpu` only on a device the platform lists as broken on WebGL, and only when WebGPU is
+available there. Do not detect devices yourself: the list is the platform's, and it changes without
+your game shipping a build.
+
+**Every game that renders with WebGL asks, before its first draw.** In the app the first crash
+closes the app, so a reload after a lost context cannot help there: only a choice made before
+anything draws does. A game that does not use WebGL at all has nothing to ask.
+
+## The three answers
+
+| `route`  | `listed` | What your game draws                                                       |
+| -------- | -------- | -------------------------------------------------------------------------- |
+| `webgpu` | `true`   | Your WebGPU renderer. If it fails to start, your **safe WebGL recipe**.    |
+| `webgl`  | `true`   | Your **safe WebGL recipe**: a listed device with no WebGPU to move to.     |
+| `webgl`  | `false`  | Your normal WebGL renderer. This is almost every player.                   |
+
+**The safe WebGL recipe** is your game drawn without what crashes a listed device's driver. For
+every listed device today (the PowerVR D-Series) that is **no shadow maps**. The crash follows
+shader makeup, so test your safe recipe on the device if you can, and turn off whatever else your
+testing shows. On a listed device, never fall back to three.js's own automatic WebGL 2 backend (the
+check below): it runs on the same broken driver.
+
+**Follow the answer for every canvas on the page**, menus, HUDs and 2D-looking WebGL plates
+included. One GPU process serves every canvas (in the app, the app's own process), so when one
+WebGL canvas crashes the driver, every context on the page goes with it. A game whose 3D board
+draws on WebGPU but whose menu plates stay on WebGL keeps those plates on the safe recipe. Ask once
+and keep the answer: it is the same for the whole page.
+
+## What `preferredRoute()` promises
+
+- **It is quick, and it never blocks your first frame.** It is a bounded async call: it resolves
+  within `timeoutMs` (default 1000 ms, at most 5000), and normally at once after
+  `await gem.awaitBridge()`. When the time runs out it answers from what it knows by then.
+- **It never rejects.** Anything that goes wrong inside it answers `webgl`, not listed: the
+  default.
+- **`webgpu` means WebGPU is there.** The SDK checks that the browser hands out a WebGPU adapter
+  before it answers `webgpu`. Your game still checks that its WebGPU renderer really started (the
+  pattern below).
+
+```js
+const { route, listed } = await gem.graphics.preferredRoute({ timeoutMs: 500 });
+```
+
+## three.js
+
+Make `WebGLRenderer` by default, and `WebGPURenderer` only when the answer is `webgpu`. Load the
+WebGPU build with a dynamic `import()`, so it is a separate chunk that only those players download:
+
+```js
+import * as THREE from 'three';
+
+// `gem` is what createGem() returned. Call createGem before you make any renderer.
+await gem.awaitBridge();
+const { route, listed } = await gem.graphics.preferredRoute();
+
+async function createRenderer() {
+  if (route === 'webgpu') {
+    try {
+      const { WebGPURenderer } = await import('three/webgpu');
+      const renderer = new WebGPURenderer({ antialias: true });
+      await renderer.init();
+      // WebGPURenderer quietly falls back to its own WebGL 2 backend when it cannot
+      // get a WebGPU device. On a listed device that backend is the broken driver,
+      // and everywhere it is slower than WebGLRenderer: never keep it.
+      if (renderer.backend.isWebGPUBackend) return { renderer, safe: false };
+      renderer.dispose();
+    } catch (error) {
+      console.warn('WebGPU renderer failed; drawing the safe WebGL recipe', error);
+    }
+  }
+  return { renderer: new THREE.WebGLRenderer({ antialias: true }), safe: listed };
+}
+
+const { renderer, safe } = await createRenderer();
+// The safe WebGL recipe on a listed device: for the PowerVR D-Series, no shadow maps.
+renderer.shadowMap.enabled = !safe;
+document.body.appendChild(renderer.domElement);
+renderer.setAnimationLoop(() => renderer.render(scene, camera));
+```
+
+Every other `WebGLRenderer` the page makes (a menu, a preview, a second view) follows `listed` the
+same way: on a listed device it draws the safe recipe.
+
+Things to know about that pattern:
+
+- **Keep the backend check.** After `await renderer.init()`, `renderer.backend.isWebGPUBackend`
+  says whether WebGPU really started. Without it, a WebGPU failure on a listed device lands on
+  three.js's WebGL 2 backend, on the very driver the answer was steering you away from.
+- **Let each renderer make its own canvas** (`renderer.domElement`). A canvas that has handed out a
+  WebGPU context cannot hand out a WebGL one, so the fallback needs a fresh canvas.
+- **Use three.js r171 or later**, where `three` and `three/webgpu` share one core, so the same scene,
+  meshes and built-in materials draw with either renderer. Pin three.js to an exact version: what
+  `WebGPURenderer` draws differently from `WebGLRenderer` moves between releases.
+
+Other engines take the same shape: ask, try WebGPU when `route` is `webgpu`, check it really
+started, and on a listed device make your WebGL renderer with the safe recipe.
+
+## What supporting both costs
+
+**"Both" means `WebGLRenderer` by default, plus `WebGPURenderer` on real WebGPU for listed
+devices.** It never means `WebGPURenderer` everywhere: on its WebGL 2 backend it is about 40%
+slower than `WebGLRenderer` ([as three.js measured it](https://github.com/mrdoob/three.js/issues/34585)).
+On real WebGPU it keeps up: one of our games drew its board in 4.05 ms against 4.81 ms on desktop,
+and at 61 fps with shadows on the Pixel 10.
+
+- **Custom shaders need a TSL port.** `WebGPURenderer` runs no GLSL and no `onBeforeCompile`. A
+  `ShaderMaterial`, `RawShaderMaterial`, an `onBeforeCompile` patch or an `EffectComposer` pass is
+  WebGL-only; under `WebGPURenderer` it needs a TSL (node material) equivalent.
+- **The look can differ.** Colour blending, clipping, clear coat and ambient light have each needed
+  a fix in one game to look the same on both renderers. Compare the two side by side (testing,
+  below).
+- **The WebGPU build is big, so load it only when chosen.** One game's WebGPU chunk is 662 KB
+  (188 KB gzipped). With `await import('three/webgpu')` behind `route === 'webgpu'`, as above,
+  players on WebGL never download it.
+
+## Lost WebGPU devices are counted for you
+
+The SDK counts every lost WebGL context, per device, across every game (the
+`gem_graphics_context_lost` event in [analytics](analytics.md)). It counts a lost WebGPU device
+the same way, with `route` set to `webgpu`, whether or not your game recovers. A device your game
+destroys itself is not counted. Your game still handles a loss itself: three.js reports it through
+`renderer.onDeviceLost`.
+
+## Where the list comes from
+
+The SDK ships with a built-in list. Today it has one entry: the PowerVR D-Series GPU on **every
+route but Vulkan**. Chrome reports this GPU on its OpenGL ES route (`angle_gles`), and the Arcade
+app's WebView names the bare chip with no ANGLE (`native_gl`); both crash, and both are listed. The
+same GPU on the Vulkan route (`angle_vulkan`) draws fine on WebGL and is not listed, so when Chrome
+moves this GPU to Vulkan, Chrome players there go back to WebGL on their own. No other device is
+listed.
+
+The Arcade can send its current list to your game when it connects, and that list replaces the
+built-in one. That is how a new entry reaches your game while it is live, with no new build from
+you: the next time a player opens your game, the Arcade's list applies.
+
+When the Arcade sends no list, or one the SDK cannot read, your game uses the built-in list. It
+never crashes or hangs on a missing or broken list.
+
+## Testing: the `gemGraphics` launch key
+
+Add `gemGraphics` to your game's address in the Arcade to force one of the three answers:
+
+| Launch key            | Answer                                   | Stands for                         |
+| --------------------- | ---------------------------------------- | ---------------------------------- |
+| `gemGraphics=webgpu`  | `{ route: 'webgpu', listed: true }`      | a listed device with WebGPU        |
+| `gemGraphics=safe`    | `{ route: 'webgl', listed: true }`       | a listed device without WebGPU     |
+| `gemGraphics=webgl`   | `{ route: 'webgl', listed: false }`      | any other device                   |
+
+The Arcade forwards it to your game like any [launch key](getting-started.md), and the SDK reads it
+once, when `createGem` runs. To check your game on every route:
+
+1. Open your game in a browser with WebGPU (desktop Chrome or Edge) with `gemGraphics=webgpu` added
+   to the address, for example
+   `https://gemarcade.com/games/<gameId>?play=1&gemGraphics=webgpu`.
+2. The browser console shows `[gem] graphics route forced to webgpu by the gemGraphics launch key`.
+3. Play through your game's scenes and check that everything draws. With three.js,
+   `renderer.backend.isWebGPUBackend` is `true` on this route.
+4. Open it again with `gemGraphics=safe` and check the safe recipe draws, on every canvas.
+5. Open it once more with `gemGraphics=webgl` and check your normal WebGL renderer.
+
+A browser without WebGPU answers `{ route: 'webgl', listed: true }` for `gemGraphics=webgpu`, as a
+listed device without WebGPU would, and the console says so.
+
+## What the SDK reads, and what it sends
+
+To match the list, the SDK makes one throwaway WebGL context on an offscreen canvas of its own,
+never on one of yours, reads which GPU and graphics route the browser uses, and releases it at
+once. It does this once a page, before your renderer exists. Nothing about the answer is sent
+anywhere: the SDK does not report which answer it gave. What it does send is the count of lost
+contexts and devices above.

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.