@indiegems/gem-web-sdk 20.1.0 → 21.1.0

package/docs/brand-art.md

@@ -2,8 +2,8 @@
 
 The SDK ships the platform's own art for its two currencies, **Gems** and **Coins**, and for
 **trophies**. You need it only if your game draws Gems, Coins or a trophy on its own screens. Read
-§1 before you pick a file: each currency has two kinds of art, and which one you use depends on what
-the screen is for.
+§1 before you pick a file: each currency has more than one kind of art, and which one you use
+depends on what the screen is for.
 
 > **Draw the platform's current marks with `gem.branding`, and keep these files as the fallback.**
 > `gem.branding.currencyMark('GEMS', { size: 20 })` and `gem.branding.trophy()` hand you the same
@@ -19,25 +19,35 @@ screen, and how much more your game can still pay (the earn allowance) — and n
 own. §5 is the creator's ruling and is not optional.
 
 > **The Coins art is a 3D render, open to a designer pass.** It is a gold coin with the platform's
-> gem in relief at its centre, a raised rim and a ridged edge, so a player reads it as the Arcade's
-> currency in every game rather than one game's gold. It replaced the tangerine coin of 2026-10-21,
-> which replaced the tangerine ticket of 2026-09-28. The files keep their `ticket-*` names, as the
-> currency keeps its slug `ARCADE_TICKETS`. If the art is redrawn again, the new art replaces these
-> files **under the same names** in a later SDK release, so a game that imports them picks it up on
-> its next SDK update. Lay your screens out from the sizes on this page, not from the drawing.
-
-## 1. Two kinds of currency art: pick by the ROLE of the screen
+> gem at its centre, so a player reads it as the Arcade's currency in every game rather than one
+> game's gold. The hero and the two piles (§3) are one coin — painted gold, a thick rounded edge, a
+> faceted gem standing on its face; the hero's also has a thin groove inside its rim and its gem
+> raised on a sloped base — and the icons keep the earlier gold coin, whose rings and gem channel
+> read better in a few pixels. Every coin is turned so its edge shows on the right. This
+> art replaced the gold coin of 2026-10-25, which replaced the tangerine coin of 2026-10-21. The
+> files keep their `ticket-*` names, as the currency keeps its slug `ARCADE_TICKETS`. If the art is
+> redrawn again, the new art replaces these files **under the same names** in a later SDK release,
+> so a game that imports them picks it up on its next SDK update. Lay your screens out from the
+> sizes on this page, not from the drawing.
+
+## 1. Pick the currency art by the role of the screen
 
 | You are drawing | Use | Drawn at |
 | --------------- | --- | -------- |
 | Gems **inline**, beside a number: a price, a "+15" reward label, a small chip | the **icon**, `gem-icon-20-*` or `gem-icon-32-*` | 16–40 CSS px |
 | Gems as **the subject of a reward presentation**: a victory or reward screen where the gem is what the player looks at, such as a victory overlay with a sunburst behind the reward | the **hero**, `gem-hero-*` | 64–256 CSS px |
-| Coins **inline**, beside a number | the **icon**, `ticket-icon-20-*` or `ticket-icon-32-*` | 16–40 CSS px |
+| Coins **inline** in your game's screens, beside a number | the **in-game icon**, `ticket-icon-ingame-20-*` or `ticket-icon-ingame-32-*` | 16–40 CSS px |
+| Coins as **a reward sized by how much it is**: a reward card, a results screen's payout | a **pile**, `ticket-pile-1-*` or `ticket-pile-2-*` (§3) | 64–256 CSS px |
 | Coins as **the subject of a reward presentation** | the **hero**, `ticket-hero-*` | 64–256 CSS px |
 
 The role decides first and the size follows from it. A price tag is inline even if you make it
 large; a reward screen is a presentation even on a small phone.
 
+`ticket-icon-20-*` and `ticket-icon-32-*` are the **arcade's wallet icon**: the same coin inside the
+violet rim the Gems icon wears, which the arcade draws in its own wallet. Inside your game that rim
+reads as the arcade's chrome, so draw the in-game icon there; a game that already draws the wallet
+icon keeps working, and moves to the in-game one when it next touches the screen.
+
 - **Never use the hero at icon sizes.** It is one render drawn to be seen large; shrunk to 20 px its
   outline goes under a pixel, its facet lines vanish and the gem smudges into the background.
 - **Never use the icon at hero sizes.** Each icon file is a separate render drawn for one small box,
@@ -114,12 +124,30 @@ outline weight — 1.5 px at 20, 2 px at 32.
 | | | `ticket-icon-32-2x.png` | 64 × 64 |
 | | | `ticket-icon-32-3x.png` | 96 × 96 |
 
-Like the Gems icon, each size is **its own render** of the hero's coin, not the hero scaled down.
-The coin is turned a little so its edge shows, and the lines that part its rim, field and gem — a
-groove inside the rim, a crease above the edge, a channel round the gem — are drawn wider and
+Like the Gems icon, each size is **its own render**, not the hero scaled down: the earlier gold
+coin, turned a little so its edge shows on the right, with the lines that part its rim, field and
+gem — a groove inside the rim, a crease above the edge, a channel round the gem — drawn wider and
 darker the smaller the size, so they still read in a few pixels. The 20 px coin has a slightly
 smaller gem and no ridges on its edge. Each is drawn on its own pixel grid inside the gem icon's
-violet outline. The arcade's wallet draws the same files.
+violet outline. These are the **wallet icon**: the arcade's wallet draws the same files.
+
+### The in-game Coins icon
+
+The same coin for **your game's own screens**, without the violet rim. A burnt-orange edge runs
+round its light right-hand side instead, so it stays distinct on a pale background, and its edge
+band is smooth. It comes in the same renditions and ratios, framed exactly as the wallet icon, so
+one swaps for the other in the same box.
+
+| Rendition | For a CSS box of | File | Pixels |
+| --------- | ---------------- | ---- | ------ |
+| 20 | up to about 24 px | `ticket-icon-ingame-20-1x.png` | 20 × 20 |
+| | | `ticket-icon-ingame-20-1.5x.png` | 30 × 30 |
+| | | `ticket-icon-ingame-20-2x.png` | 40 × 40 |
+| | | `ticket-icon-ingame-20-3x.png` | 60 × 60 |
+| 32 | above 24, up to about 40 px | `ticket-icon-ingame-32-1x.png` | 32 × 32 |
+| | | `ticket-icon-ingame-32-1.5x.png` | 48 × 48 |
+| | | `ticket-icon-ingame-32-2x.png` | 64 × 64 |
+| | | `ticket-icon-ingame-32-3x.png` | 96 × 96 |
 
 ## 3. The hero art
 
@@ -147,10 +175,31 @@ size you draw it multiplied by the screen's `devicePixelRatio`:
 **Do not draw it larger than 256 CSS pixels.** On a 3× screen that needs more than the largest file,
 and the art softens as it is stretched. Below 64 px, use the icon (§2).
 
+### The coin piles
+
+Two heaps of the hero's coin, for a Coins reward your game **offers or has just paid** where the
+size of the heap says how much: a reward card, or a results screen's payout. Pile 1 is a few short
+stacks; pile 2 holds about twice the coins.
+
+| Pile | Use it for | Files |
+| ---- | ---------- | ----- |
+| 1 | an everyday reward | `ticket-pile-1-128.png`, `ticket-pile-1-256.png`, `ticket-pile-1-384.png`, `ticket-pile-1-512.png`, `ticket-pile-1-768.png` |
+| 2 | a bigger reward | `ticket-pile-2-128.png`, `ticket-pile-2-256.png`, `ticket-pile-2-384.png`, `ticket-pile-2-512.png`, `ticket-pile-2-768.png` |
+
+**Pick the pile by where the reward sits among your game's own rewards, not by a number of Coins.**
+Where a reward's size doesn't matter, the hero does as well.
+
+Both piles share one frame: a square, transparent PNG with a margin all round, each heap centred
+across and standing on the same baseline. Pile 2 fills the frame and pile 1 is drawn smaller, so the
+two side by side climb from left to right with no scaling in your layout. Draw them at the hero's
+sizes, **64 to 256 CSS pixels**, and pick the file as for the hero above.
+
 ## 4. Loading and drawing the art
 
-The platform serves every one of these files through `gem.branding` ([branding.md](branding.md)),
+The platform serves the icons and the heroes through `gem.branding` ([branding.md](branding.md)),
 which is what to draw first. The copies below are the fallback for when it answers `unavailable`.
+The in-game Coins icon and the coin piles are not in the platform's manifest yet: draw them from
+here.
 
 All of it is in the package you already install, under `brand/`, and published beside it on the CDN —
 the same bytes either way, for the version you are on.

package/docs/changelog.md

@@ -16,6 +16,46 @@ Its entries are grouped under up to five headings:
 - **Rebuild**: a type changed. Recompile against the new version; code that compiles today keeps compiling unless the entry says otherwise.
 - **New capability**: something a game can now do. Nothing changes unless you use it.
 
+## 21.1.0
+
+Upgrading from 21.0.0. Impact: required.
+
+### Must change
+
+- ShareApi.request now returns a promise instead of nothing. When the Arcade refuses a share, the promise rejects with a ShareRefusal that names the reason and the offending param. Await the call and handle the rejection, for example by telling the player the share could not be sent. With an older Arcade the promise resolves at once, as before. The SDK also refuses, before sending, share params whose keys the Arcade reserves for its own play links, and the error names the key. If your game uses such a name as its own share param, rename it. A current Arcade carries most reserved keys through a share link and returns them unchanged, but an older one still refuses them.
+- PurchaseRefusalCode has a new value, guest_upgrade_required, returned when a web guest tries to spend platform currency directly. Treat it like any other decline: draw no purchase, and do not retry. If you switch over the refusal codes exhaustively, add a case for it or your code will stop compiling.
+
+### Should change
+
+- Spend Gems and Coins through the Arcade's purchase sheet, not through a direct spend on the entity mutations. A web guest's direct spend is now refused. The SDK hands that one refusal to the Arcade as a safety net and rejects your call with the original error straight away, without waiting for an answer or retrying. Move any direct platform-currency spend to the purchase sheet flow. See [the deprecation policy](deprecation-policy.md#4-what-is-deprecated-today).
+
+### Rebuild
+
+- Several types and signatures changed in compatible ways: GemFrame.requestPurchase gained an optional origin argument, GemFrame.requestShare gained an optional requestId argument, the MutationsApi constructor gained an optional hand-off callback, and GemCapability, ParentMessage and PARENT_TO_FRAME gained new capabilities and message kinds for purchase settlement, graphics routes and share results. Recompiling is enough. If you test against your own stand-in for the Arcade, rebuild it against this release and bring it up to the newer parent conformance version.
+
+### New capability
+
+- PurchaseApi.onSettled lets a game hear a purchase that completed after its original call had already been answered, for example one finished through the Arcade after a guest's refused spend. The game is told once the platform confirms the purchase, as a PurchaseSettlement, and the player's data is refreshed. Subscribe to it so you can grant the purchase when it lands. It only fires on an Arcade that supports it.
+- Gem.graphics lets a game ask which renderer to create just before it creates one. The answer says the route to use and whether the device is on the platform's list of devices known to draw wrongly on WebGL. The answer is WebGL everywhere except on a listed device, and there WebGPU only if it hands out an adapter. A listed device with no working WebGPU gets your safe WebGL recipe. The call is time-bounded and never rejects. The list ships built in, and the Arcade can replace it for live games without a rebuild. Call it before creating a renderer and make every canvas follow the answer.
+- A new dev-tools entry point is available for a game's dev-only code, such as a cheat panel, level skipper or debug menu. Importing it from that code marks the build as carrying dev-only code. Builds so marked can be uploaded and played on the dev channel but are refused on the test and release channels. Keep the import behind a build-time switch that is off for test and release builds so the marker is absent from them.
+
+## 21.0.0
+
+Upgrading from 20.1.0. Impact: required.
+
+### May stop
+
+- You do not need to write your own code to count lost WebGL contexts for analytics. Every game now reports each loss automatically, with no code of its own. The SDK only observes the loss, so whether your game restores its context stays your decision, and your own handling keeps working unchanged.
+
+### Rebuild
+
+- The set of platform event names now includes a new member, gem_graphics_context_lost, which the SDK emits when the browser takes away one of the game's WebGL contexts. Recompiling is enough for most games. If your game switches over every platform event name exhaustively, or maps each name to a value, add a case for the new name so it still compiles.
+
+### New capability
+
+- A new in-game Coins icon is available in two sizes, 20 and 32, each at four pixel ratios: 1x, 1.5x, 2x and 3x. It is the Coins coin without the violet rim, so it does not look like the Arcade's own chrome inside a game. Use it wherever your game shows Coins. The wallet icon keeps its violet rim.
+- Two coin piles are now available for showing a Coins reward sized by how much it is: pile 1 for an everyday reward and pile 2 for a bigger one. Each comes in five widths: 128, 256, 384, 512 and 768. They share one frame and baseline, so a row of them climbs from the smaller to the larger. Larger piles are reserved for the Arcade's own shop. The Coins hero art remains the choice when the size of the reward does not matter.
+
 ## 20.1.0
 
 Upgrading from 20.0.0. Impact: required.

package/docs/game-economy-tutorial.md

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

package/docs/getting-started.md

@@ -50,7 +50,7 @@ either way.
 ```jsonc
 // package.json
 "dependencies": {
-  "@indiegems/gem-web-sdk": "20.1.0"
+  "@indiegems/gem-web-sdk": "21.1.0"
 }
 ```
 
@@ -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,16 +355,18 @@ 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.
 
@@ -363,12 +377,18 @@ What reaches the frame:
   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 +396,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 +437,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 +506,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.