@indiegems/gem-web-sdk 10.3.0 → 10.4.0

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/v10.3.0/gem-web-sdk.tgz
-curl -fsSL https://downloads.gemarcade.com/sdk/v10.3.0/gem-web-sdk.tgz.sri
+curl -fsSL -O https://downloads.gemarcade.com/sdk/v10.4.0/gem-web-sdk.tgz
+curl -fsSL https://downloads.gemarcade.com/sdk/v10.4.0/gem-web-sdk.tgz.sri
 openssl dgst -sha384 -binary gem-web-sdk.tgz | openssl base64 -A
 ```
 

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

@@ -702,53 +702,49 @@ the `var()` above, or read `gem.viewport`. The release checklist looks for the b
 
 ### The arcade's own controls: reserved areas
 
-On a phone your game is full-bleed, and the arcade keeps one row of its own over the top of it:
-
-- **The menu button**, in the **top-right corner**, always there. It opens
-  [the Arcade's menu](#the-arcades-menu): Return to the Arcade, mute, the player's Arcade-wide
-  settings and the rest. Not your settings: those are [your own button](#game-settings).
-- **The player's wallets** (Gems, Tickets, their achievement score), in the **middle of the row**,
-  [there unless your game hides them](#the-arcades-wallet-shown-unless-you-hide-it-never-drawn),
-  during play as well as on your menus. They are translucent, so your game shows through them — but they are still the Arcade's,
-  and still taps the Arcade takes.
+The Arcade keeps **one control of its own over every game**, on every device — a phone's full-bleed
+game, a framed or full-window game on a desktop, a tablet or a TV in native fullscreen:
+
+- **The Gem button**, the Gem Arcade's gem, in the **top-left corner**, always there (a touch target, about
+  50px across). It opens [the Arcade's menu](#the-arcades-menu): Return to the Arcade, the player's Gems,
+  Tickets and achievement score, mute, the player's Arcade-wide settings and the rest. Not your
+  settings: those are [your own button](#game-settings).
+- **Nothing else.** The player's wallets (Gems, Tickets, their achievement score) are **not** drawn
+  over your game: the player opens the Gem menu to see them, and every platform-currency payout
+  flies into the Gem button ([the Arcade's wallet](#the-arcades-wallet-in-the-gem-menu-never-drawn-by-you)).
+  When the player switches the frame-rate readout on, it sits beside the gem and is reserved the
+  same way.
 
 **The top of the screen has one layout, in every game:**
 
-| Where                                        | Whose        | What goes there                                                                                                                                                                                              |
-| -------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| **Top-left**                                 | yours        | Your **Home / Back** buttons, drawn when a screen needs them, in the space to the left of the wallets. They move around _inside_ your game — back to your level select or title screen — and never leave it. |
-| **Middle and top-right**                     | the Arcade's | Its wallets and its menu button. Nothing of yours.                                                                                                                                                           |
-| **Centre and right, below the Arcade's row** | yours        | Your **information**: score, moves, a timer, a level name. It starts under the bottom of the Arcade's row, never beside it or under it.                                                                      |
-
-Keep the left for Home / Back even on a screen that has neither today: a player learns where "back"
-is once, across every game, and information that sits there on one screen teaches them the wrong
-thing on the next.
+| Where                                | Whose        | What goes there                                                                                                                                                                                         |
+| ------------------------------------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Top-left corner**                  | the Arcade's | Its Gem button. Nothing of yours under it.                                                                                                                                                              |
+| **Top-left, right of the Gem**       | yours        | Your **Home / Back** buttons, drawn when a screen needs them, level with the Gem and just to its right. They move around _inside_ your game — back to your level select or title screen — and never leave it. |
+| **Centre of the top row**            | yours        | Your **information**: score, moves, a timer, a level name.                                                                                                                                              |
+| **Top-right**                        | yours        | Your **settings** button ([Game settings](#game-settings)).                                                                                                                                             |
 
-**Your settings button goes top-right, clear of the Arcade's controls**: never under one, and below
-any the Arcade keeps in that corner. [Game settings](#game-settings) shows how to place it.
+Keep the spot beside the Gem for Home / Back even on a screen that has neither today: a player
+learns where "back" is once, across every game, and information that sits there on one screen
+teaches them the wrong thing on the next.
 
-**How much room the top-left has.** The menu button is about 48px across — the size of a Home or
-Back button. With every wallet shown, the narrowest phones (360px wide) leave roughly 68px to the
-left of the wallets: room for **one** button. Two buttons, or a wide one, go on their own row below
-the Arcade's. Do not copy those numbers — read the space, as below.
+**Your settings button goes top-right**, clear of any Arcade control: under the Gem Arcade there is
+none in that corner, but another embedder may keep one there. [Game settings](#game-settings) shows
+how to place it.
 
 Those rectangles of your frame are **reserved**: keep essential UI and every touch target out of
-them. **Never hard-code their size or height.** They differ by phone, and in native fullscreen the
-whole row may rise into the camera band — read them, as below.
+them. **Never hard-code their size or position.** They differ by phone, and in native fullscreen the
+gem may rise into the camera band — read them, as below.
 
-An inset cannot say that — as a top inset, a button a few dozen pixels wide would take your whole top
-strip. So `gem.viewport` also carries the rectangles, in the same CSS pixels of your frame, measured
-from its top-left corner — one per wallet shown, and one for the menu button:
+An inset cannot say that — as a left or top inset, a button a few dozen pixels wide would take a whole
+strip of your screen. So `gem.viewport` also carries the rectangles, in the same CSS pixels of your
+frame, measured from its top-left corner — one for the Gem button, and one for the frame-rate
+readout while the player shows it:
 
 ```json
 {
   "insets": { "top": 47, "right": 0, "bottom": 34, "left": 0 },
-  "reserved": [
-    { "x": 68, "y": 51, "width": 72, "height": 28 },
-    { "x": 144, "y": 51, "width": 72, "height": 28 },
-    { "x": 220, "y": 51, "width": 72, "height": 28 },
-    { "x": 304, "y": 51, "width": 48, "height": 48 }
-  ]
+  "reserved": [{ "x": 8, "y": 55, "width": 52, "height": 52 }]
 }
 ```
 
@@ -756,59 +752,44 @@ from its top-left corner — one per wallet shown, and one for the menu button:
 `--gem-safe-*` before anything else hears the push: `--gem-reserved-tl-width` and
 `--gem-reserved-tl-height`, and the same pair for `tr`, `bl` and `br` — how far that corner's
 reserved rectangles reach in from its two edges. A rectangle belongs to the corner its centre lies
-nearest to.
-
-⚠️ **The wallets sit in the middle, so they count toward BOTH top corners.** A wallet left of
-centre is a top-left rectangle, one right of centre a top-right one. While wallets are shown,
-`--gem-reserved-tl-height` is the bottom of the wallets and `--gem-reserved-tl-width` reaches to the
-middle of the screen — even though the corner itself, left of the first wallet, is clear. So:
+nearest to. Under the Gem Arcade the Gem button is a top-left rectangle, so:
 
 ```css
-/* your information — score, moves, a timer — below the WHOLE of the arcade's row: the taller of
-   the two top corners. It moves up by itself when gameplay hides the wallets. */
-#info {
-  top: max(
-    var(--gem-safe-top, env(safe-area-inset-top, 0px)),
-    var(--gem-reserved-tl-height, 0px),
-    var(--gem-reserved-tr-height, 0px)
-  );
-  right: var(--gem-safe-right, 0px);
-}
-/* ONE Home or Back button, level with the arcade's row, in the clear corner to the wallets' left */
+/* ONE Home or Back button, level with the Gem, just to its right */
 #back {
   top: var(--gem-safe-top, env(safe-area-inset-top, 0px));
-  left: var(--gem-safe-left, 0px);
+  left: max(var(--gem-safe-left, 0px), var(--gem-reserved-tl-width, 0px));
 }
-/* a ROW of your own buttons does not fit beside the wallets: start it below the arcade's row,
-   like your information */
-#nav {
+/* your information — score, moves, a timer — clear of every top corner the arcade reserves */
+#info {
   top: max(
     var(--gem-safe-top, env(safe-area-inset-top, 0px)),
-    var(--gem-reserved-tl-height, 0px),
     var(--gem-reserved-tr-height, 0px)
   );
+  left: max(var(--gem-safe-left, 0px), var(--gem-reserved-tl-width, 0px));
+  right: var(--gem-safe-right, 0px);
 }
 ```
 
-The per-corner properties cannot say how wide the clear corner is — only that the corner's
-rectangles reach in to the middle. To know whether your button fits beside the wallets, read the
-rectangles from script: the clear width at the top-left is the smallest `x` among
-`gem.viewport.reserved` (the whole width when the list is empty).
+The per-corner properties say how far a corner's rectangles reach, not how much room is left beside
+them. To know whether a row of your own buttons fits beside the Gem, read the rectangles from
+script: the room to the right of the top-left ones is the frame's width less the furthest right
+edge among them.
 
 ```js
 const reserved = gem.viewport?.reserved ?? [];
-const clearLeft = reserved.length ? Math.min(...reserved.map((r) => r.x)) : window.innerWidth;
-nav.classList.toggle('below-arcade-row', clearLeft < nav.offsetWidth + 8);
+const topLeft = reserved.filter((r) => r.x + r.width / 2 < window.innerWidth / 2);
+const from = topLeft.length ? Math.max(...topLeft.map((r) => r.x + r.width)) : 0;
+nav.classList.toggle('below-arcade-row', window.innerWidth - from < nav.offsetWidth + 8);
 ```
 
 All eight properties are written on every push, `0px` for a clear corner, so a rotation never leaves
 a stale value; they are never set under an embedder that sends no viewport, which is what the `0px`
 fallback is for. `gem.viewport.reserved` is `[]` when nothing is covered.
 
-**Lay out against it whenever it changes.** The wallets' rectangles are there for the whole
-session on the Arcade's phone layout, and their number and width can change as the player's
-balances and currencies do. Read every corner, not only the ones this page names today: a layout that honours
-all four is right under any embedder.
+**Lay out against it whenever it changes.** The Gem button's rectangle is there for the whole
+session, and it moves with a rotation, a resize or the frame-rate readout. Read every corner, not
+only the one this page names today: a layout that honours all four is right under any embedder.
 
 **Older SDKs get it folded into the top inset.** A game on an SDK from before reserved areas cannot
 read the rectangles, so the arcade sends it none and instead raises `insets.top` — and so
@@ -943,12 +924,18 @@ same push as `muted` and `reducedMotion`, and again whenever the player changes
 | `gamepadLookSensitivity` | `20` to `400` | Look speed for a gamepad stick, as a percentage: `100` is 1×.                                                |
 | `invertLookY`    | `true` / `false`      | Up/down look inverted: pushing up or dragging up looks down. Pitch only, never yaw.                          |
 | `touchMovement`  | `'floating'` / `'fixed'` | On a touch screen, a movement stick that appears where the thumb lands, or one fixed in place.            |
+| `graphicsQuality` | `'low'` / `'medium'` / `'high'` | The graphics quality to start at on this device.                                                  |
+| `graphicsQualityAuto` | `true` / `false` | `true`: the Arcade picked that tier for this device, so you may adapt from it. `false`: the player picked it, so hold it. |
 
-The last four are the camera and controls settings: see
+`lookSensitivity` to `touchMovement` are the camera and controls settings: see
 [camera and look controls](#camera-and-look-controls) for telling the Arcade which of them your game
 uses, and for `gem.controls.look()`, which applies the two sensitivities and the invert for you. An
 older Arcade sends `recommended` without them; the SDK then fills each with its default (`100`,
-`100`, `false`, `'floating'`), so whenever `recommended` is not `null` all nine fields are there.
+`100`, `false`, `'floating'`). The last two are the starting graphics quality: see
+[graphics quality](#graphics-quality-the-arcade-picks-the-start-your-game-adapts). An older Arcade
+sends neither; the SDK then fills `graphicsQuality` from `batterySaver` (`'low'` when it is on,
+`'medium'` otherwise) and `graphicsQualityAuto` with `true`, and reads a tier it does not know as
+`'medium'`. So whenever `recommended` is not `null`, all eleven fields are there.
 
 **They are recommendations, and the player's own choice in your game always wins:**
 
@@ -968,6 +955,7 @@ older Arcade sends `recommended` without them; the SDK then fills each with its
 const DEFAULTS = {
   volume: 100, batterySaver: false, keyboardLayout: 'wasd', gamepadConfirm: 'south', vibration: true,
   lookSensitivity: 100, gamepadLookSensitivity: 100, invertLookY: false, touchMovement: 'floating',
+  graphicsQuality: 'medium',
 };
 let chosen = {}; // ONLY what the player picked in your settings screen
 
@@ -1021,7 +1009,7 @@ gem.controls.declare({
 });
 ```
 
-It is screen state, like [`gem.setWalletVisible`](#the-arcades-wallet-shown-unless-you-hide-it-never-drawn):
+It is screen state, like [`gem.setWalletVisible`](#the-arcades-wallet-in-the-gem-menu-never-drawn-by-you):
 each call is the whole answer, the latest wins, and the SDK holds it and sends it again after a
 reconnect. It returns `false` before the bridge is up (it is held and sent on connect) and under an
 embedder that does not show these settings; it never throws. A key or a value other than these is
@@ -1086,11 +1074,71 @@ function frame(dt) {
   `touchMovement: 'game'` if your game only has one kind.
 - **No camera, no call.** A game with no camera to turn declares nothing and never calls `look`.
 
+## 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
+the device instead of guessing and stuttering for the first minute. The work is split three ways:
+
+- **The Arcade picks the starting tier, per device**, and sends it as
+  `gem.prefs.recommended.graphicsQuality`: `'low'`, `'medium'` or `'high'`. On Auto, the player's
+  default, it is the tier the Arcade measured for this browser on this device. Otherwise it is the
+  player's own choice in the Arcade's Settings: Battery saver (`'low'`, and cap your frame rate and
+  cut effects too), Balanced (`'medium'`) or Best looking (`'high'`).
+- **Your game adapts from there while it runs**: one level down when frames stay slow, one level up
+  when there is plenty of room. `createQualityGovernor` does this for you, so you do not write a
+  frame-time monitor of your own.
+- **A choice the player made by hand is held.** `graphicsQualityAuto` is `false` when the player
+  picked the tier, and then you render at exactly that tier and never move it yourself. Your own
+  quality option, if your settings screen has one, still wins over the Arcade's, as every
+  [recommended setting](#start-from-the-players-arcade-wide-defaults-gemprefsrecommended) does.
+
+The governor is a separate import, so a game that does not use it carries none of it:
+
+```js
+import { createQualityGovernor } from '@indiegems/gem-web-sdk/quality';
+
+// Your own levels, lowest first. Names, or a count: `levels: 4` means levels 0 to 3.
+const governor = createQualityGovernor({
+  gem,
+  levels: ['low', 'medium', 'high'],
+  onChange: (level) => applyQuality(level), // shadows, resolution scale, particles…
+});
+applyQuality(governor.level); // where it starts; onChange is not called for that
+```
+
+What it does, so you know what to expect:
+
+- **It starts at the Arcade's tier.** A tier whose name is one of your levels starts there;
+  otherwise `'low'` is your lowest level, `'high'` your highest and `'medium'` your middle one. With
+  no Arcade (`gem.prefs` is `null`, or no `gem`), it starts in the middle.
+- **It measures your frames itself**, with `requestAnimationFrame`. If your loop already knows its
+  frame time, pass `manual: true` and call `governor.frame(dtMs)` once a frame instead; the first
+  `frame` call switches it to your numbers anyway, so frames are never counted twice.
+- **Down fast, up slow.** One level down after about 2 seconds of slow frames (the 90th-percentile
+  frame over 1.25 times your frame budget), one level up after about 10 seconds with room to spare
+  (under 0.7 times the budget), and never more than one level above where it started. A single
+  hitch is not slow frames. After every change it ignores 2 seconds of frames, and a level it
+  already had to leave takes twice as long to climb back into.
+- **Your budget is `1000 / targetFps`**, and `targetFps` is 60 unless you say. A game that caps
+  itself at 30 frames a second on battery saver passes `targetFps: 30`, or every frame reads as
+  slow.
+- **It never counts a paused game**: not while the Arcade has you paused (`gem.paused`), and not
+  while the tab is hidden. It also ignores the first 2 seconds, which are your game loading.
+- **It holds a hand-picked tier.** While `graphicsQualityAuto` is `false` it stays at the start and
+  never calls `onChange` on its own. Pass `auto: false` to hold whatever the Arcade says, or
+  `start: 'high'` to start from a level the player chose in your own settings.
+- **A new recommendation starts it over.** When the player changes Graphics in the Arcade's
+  Settings, the governor goes back to the new start and calls `onChange(level, 'reset')`. It reads
+  `gem.prefs` live, so you do not have to tell it.
+- **`governor.stats`** has what it measured (`fps`, `p90Ms` and `budgetMs`, the level's index,
+  whether it is holding or paused), for your own debug overlay. Call `governor.dispose()` when your
+  game stops rendering for good.
+
 ## The Arcade's menu
 
-The Arcade keeps one menu button over every game, on every device. Its menu is how a player leaves
-(**Return to the Arcade**), mutes, goes fullscreen, reports a problem and changes their Arcade-wide
-settings — the ones that reach you as [`gem.prefs.recommended`](#game-settings). You can add up to
+The Arcade keeps one button over every game, on every device: the Gem, at the top-left. Its menu is
+how a player leaves (**Return to the Arcade**), sees their Gems, Tickets and achievement score, mutes,
+goes fullscreen, reports a problem and changes their Arcade-wide settings — the ones that reach you as [`gem.prefs.recommended`](#game-settings). You can add up to
 four entries of your own:
 
 ```js
@@ -1207,28 +1255,24 @@ its music out than cut it, say. The Arcade still shows its button for your game
 so this is a promise: your `onPrefs` handler must go quiet on `muted: true` and come back on `false`,
 and the release checklist checks that it does.
 
-## The Arcade's wallet: shown unless you hide it, never drawn
+## The Arcade's wallet: in the Gem menu, never drawn by you
 
 The player's platform balances — Gems, Tickets (`ARCADE_TICKETS`) and their achievement score —
 belong to the Arcade. **Your game never draws one**, and never shows a pending state for one: the
-Arcade takes every figure from the platform and draws the wallets itself, in the middle of the row
-across the top of your frame on a phone, with its menu button at the right end.
-
-**By default the Arcade shows every wallet the whole time, during play too.** They are small,
-translucent chips in the middle of the top row, and while shown they are
-[reserved rectangles](#the-arcades-own-controls-reserved-areas): lay every screen out below both
-`--gem-reserved-tl-height` and `--gem-reserved-tr-height`. A game that calls nothing keeps them.
-
-**A game may hide them for gameplay** (honoured again since 2026-10-08): call
-`gem.setWalletVisible(false)` when play starts and `gem.setWalletVisible(true)` when a menu opens.
-While hidden, their rectangles leave `gem.viewport.reserved` and the top row is the game's; the
-Arcade still pops a wallet up for a moment when something happens to it (a reward you cued, a
-spend, a landing), floating over the game without moving anything. This applies on a phone, where
-the wallets sit over your game; where the Arcade docks them beside the frame it changes nothing.
-Read the `--gem-reserved-*` properties rather than assuming either state.
-
-⚠️ **The Arcade ignores the `only` option**: a shown wallet is every wallet. Do not build a store
-screen that relies on narrowing them to one currency.
+Arcade takes every figure from the platform and shows them itself.
+
+**The Gem Arcade draws no wallet over your game** (since 2026-10-11). Nothing of it sits in your top
+row, at rest or when a balance moves. The player opens the Gem menu — the Gem button at the
+top-left — to see their Gems, Tickets and achievement score, and every payout
+[`gem.cueReward`](inventory-and-catalogs.md#showing-the-reward-land-in-the-arcades-wallet) announces
+flies into the Gem button. A payout you do not cue flies too, from the middle of your frame, so cue
+the ones the player earns on screen and the flight starts where they are looking.
+
+**`gem.setWalletVisible` changes nothing on the Gem Arcade.** It is still part of the contract, so a
+game that calls it keeps working, and it is the call to make for an embedder that draws wallets over
+games: hide them while you play, show them on your menus. Under the Gem Arcade there is no wallet to
+show or hide and no wallet rectangle in `gem.viewport.reserved`. The `only` option is ignored there
+as well.
 
 ## No accidental text selection
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indiegems/gem-web-sdk",
-  "version": "10.3.0",
+  "version": "10.4.0",
   "description": "postMessage bridge contract between gem-web and browser-playable games",
   "license": "UNLICENSED",
   "type": "module",
@@ -35,6 +35,10 @@
       "types": "./dist/function.d.ts",
       "import": "./dist/gem-web-sdk.function.js"
     },
+    "./quality": {
+      "types": "./dist/quality.d.ts",
+      "import": "./dist/gem-web-sdk.quality.js"
+    },
     "./schema": "./schema/bridge.v1.json",
     "./brand/*": "./brand/*"
   },

package/schema/bridge.v1.json

@@ -804,7 +804,8 @@
           "$comment": [
             "The player's ARCADE-WIDE DEFAULTS for this device, which the Arcade",
             "keeps in its own Settings: a starting volume, battery saver, a keyboard",
-            "layout, the gamepad's confirm button, and vibration. RECOMMENDATIONS",
+            "layout, the gamepad's confirm button, vibration, the camera and",
+            "controls settings and a starting graphics quality. RECOMMENDATIONS",
             "ONLY. The game's own saved settings win: a game starts a setting from",
             "here only while the player has made no choice of their own in that",
             "game, and never overwrites one the player made because this changed.",
@@ -824,6 +825,16 @@
             "the game side all four are present whenever the object is. A game says",
             "which of them it leaves to the player with `gem.controlsDeclare`.",
             "",
+            "THE GRAPHICS TWO ARE OPTIONAL INSIDE IT TOO (owner decision",
+            "2026-10-11): `graphicsQuality` and `graphicsQualityAuto`, the quality",
+            "a game STARTS at on this device. The Arcade picks the start (the",
+            "player's Graphics setting, or the tier it detected for this device on",
+            "Auto); the game adapts from there while it runs, and holds the start",
+            "when the player picked it by hand. A parent built against an older SDK",
+            "omits them, and the SDK fills `graphicsQuality` from `batterySaver`",
+            "(`low` when it is on, `medium` otherwise) and `graphicsQualityAuto`",
+            "with true, so on the game side both are present whenever the object is.",
+            "",
             "`muted`, `reducedMotion` and `showFrameStats` stay where they are, at",
             "the top of this message, and keep their meaning: they are the Arcade's",
             "own state the frame acts on, not a recommendation. The Arcade starts",
@@ -900,6 +911,31 @@
                 "only `floating` or `fixed` today, and the SDK maps any other value to",
                 "the default, `floating`, so a game only ever sees those two."
               ]
+            },
+            "graphicsQuality": {
+              "kind": "string",
+              "maxLength": 16,
+              "format": "code",
+              "optional": true,
+              "$comment": [
+                "The graphics quality a game should START at on this device: `low`,",
+                "`medium` or `high`. The player's Graphics setting decides it --",
+                "Battery saver sends `low`, Balanced `medium`, Best looking `high`,",
+                "and Auto (the default) sends the tier the Arcade detected for this",
+                "device. A starting point, not a cap: a game adapts from here while it",
+                "runs unless `graphicsQualityAuto` is false.",
+                "",
+                "A CODE, NOT AN ENUM, so the vocabulary can grow without costing an",
+                "older frame the whole message (see WIDENING above): a parent sends",
+                "only `low`, `medium` or `high` today, and the SDK maps any other",
+                "value to `medium`, so a game only ever sees those three. When it is",
+                "absent the SDK fills `low` if `batterySaver` is true, else `medium`."
+              ]
+            },
+            "graphicsQualityAuto": {
+              "kind": "boolean",
+              "optional": true,
+              "$comment": "True when the Arcade detected `graphicsQuality` for this device (the player left Graphics on Auto), so the game may step its quality up or down from there as it measures frames; false when the player picked it by hand, so the game holds it and changes it only when the player does (in the Arcade or in the game's own settings). Default true when absent."
             }
           }
         }
@@ -2437,9 +2473,10 @@
       "$comment": [
         "A platform-currency reward is on its way — the game's SERVER has just",
         "moved (or is about to move) a progression mapped onto a platform currency,",
-        "and the game would like the arcade's wallet to show it landing: a pending",
-        "state now and, when the platform confirms the grant, the currency flying",
-        "from `origin` into the wallet.",
+        "and the game would like the arcade to show it landing: the currency flying",
+        "from `origin` into the arcade's chrome — in the Gem Arcade, into its Gem",
+        "button at the frame's top-left — and the total moving when the platform",
+        "confirms the grant.",
         "",
         "A PRESENTATION CUE, NOT A CLAIM. Nothing here is trusted as a number. The",
         "amount that lands and the player's new total reach the parent from gem-api",
@@ -2452,7 +2489,8 @@
         "`origin` is where the flight starts, in CSS px of the frame's own",
         "coordinate space — the same space `gem.viewport` speaks — measured from",
         "the frame's top-left corner; the parent translates it into its own page.",
-        "Absent, the arcade animates at the wallet alone. Integers, like",
+        "Absent, the Gem Arcade flies the confirmed grant from the middle of the",
+        "frame, as it does a grant no cue announced. Integers, like",
         "`gem.viewport`'s insets: a fractional pixel is not a placement, and the",
         "SDK rounds and clamps on the way out. 16384 is a bound, not a size.",
         "",
@@ -2472,10 +2510,9 @@
         "other, `gem.cueReward` returns false and the game does NOTHING. There is",
         "no fallback celebration: Gems display belongs to the arcade (the",
         "creator's ruling, 2026-09-24), so a game draws no Gems flight, counter or",
-        "celebration of its own. The same holds for Tickets (`ARCADE_TICKETS`): the",
-        "arcade's wallet shows Gems and Tickets side by side and flies a payout",
-        "into the one `currencySlug` names. `origin` is the centre of the game's icon for",
-        "that currency — its gem, or its ticket."
+        "celebration of its own. The same holds for Tickets (`ARCADE_TICKETS`):",
+        "`currencySlug` decides what flies and which total moves. `origin` is the",
+        "centre of the game's icon for that currency — its gem, or its ticket."
       ],
       "fields": {
         "currencySlug": { "kind": "string", "maxLength": 32 },
@@ -2531,6 +2568,12 @@
         "docks its wallets beside the frame rather than over it, this changes",
         "nothing.",
         "",
+        "THE GEM ARCADE DRAWS NO WALLET OVER A GAME (since 2026-10-11): the player",
+        "sees their balances in its Gem menu and payouts fly into its Gem button, so",
+        "it advertises this message, accepts it, and changes nothing on screen — no",
+        "wallet is shown, popped up or reserved whatever the game says. The rules",
+        "above are for a parent that does draw wallets over the frame.",
+        "",
         "A PRESENTATION REQUEST ONLY. Not an authorization control, and it carries no",
         "numbers: the parent takes every figure it shows from the platform. A game",
         "never draws a platform balance itself and never implements a pending state.",