@indiegems/gem-web-sdk 10.3.0 → 10.4.0

package/docs/api/api-reference-game.md

@@ -1,6 +1,6 @@
 # The browser surface — API reference
 
-Generated from `@indiegems/gem-web-sdk/sdk` v10.3.0, the version of the package this file ships in. Every symbol below carries an explicit anchor, its `anchor` in `reference.json` beside this file.
+Generated from `@indiegems/gem-web-sdk/sdk` v10.4.0, the version of the package this file ships in. Every symbol below carries an explicit anchor, its `anchor` in `reference.json` beside this file.
 
 `@indiegems/gem-web-sdk/sdk` is the one import a game writes, wherever its code runs. `@indiegems/gem-web-sdk/game` exports exactly the symbols on this page and nothing else, for a build that wants only this half.
 
@@ -5193,7 +5193,8 @@ Whether the panel is on screen right now.
 interface RewardCue
 ```
 
-A platform-currency reward on its way to the arcade's wallet — what
+A platform-currency reward on its way to the arcade — in the Gem Arcade, a
+flight into the Gem button at the top-left of your frame — what
 `gem.cueReward` takes.
 
 <a id="rewardcue-currencyslug"></a>
@@ -5205,8 +5206,8 @@ currencySlug: string
 ```
 
 The platform currency's slug, as `gem.platform.currencies.get()` lists it —
-`GEMS` or `ARCADE_TICKETS`. It decides which total in the arcade's wallet
-the payout flies into.
+`GEMS` or `ARCADE_TICKETS`. It decides what flies — gems or tickets — and
+which of the player's totals the payout moves.
 
 <a id="rewardcue-expected"></a>
 
@@ -5231,8 +5232,8 @@ origin?: { x: number; y: number }
 Where the flight starts, in CSS px of YOUR viewport: the centre of the
 currency's icon (or hero) your screen draws beside the reward — the gem
 for Gems, the ticket for Tickets. Measure that element's own box, not a
-row or panel around it. Leave it out and the arcade animates at its wallet
-alone.
+row or panel around it. Leave it out and the Gem Arcade flies the payout
+from the middle of your frame once the platform confirms it.
 
 <a id="rewardcue-origin-x"></a>
 
@@ -5500,9 +5501,9 @@ while connected, and only to an arcade that mirrors a game's mute.
 cueReward(cue: RewardCue): boolean
 ```
 
-Tell the arcade a platform-currency reward is on its way, so its wallet can
-show it landing — a pending state now and, once the platform confirms the
-grant, the currency flying from `origin` into the wallet.
+Tell the arcade a platform-currency reward is on its way, so it can show it
+landing — in the Gem Arcade, the currency flying from `origin` into the Gem
+button, the total moving once the platform confirms the grant.
 
 Prefer `gem.cueReward`, which says what the arcade does with it. This one
 sends only while connected, and only to an arcade that draws a wallet.
@@ -7703,9 +7704,10 @@ readonly recommended: GemRecommendedSettings | null
 ```
 
 The player's Arcade-wide defaults for this device — a volume, battery
-saver, a keyboard layout, the gamepad's confirm button, vibration, and the
+saver, a keyboard layout, the gamepad's confirm button, vibration, the
 camera and controls settings (look sensitivity, gamepad look sensitivity,
-invert look, touch movement) — or `null` when the Arcade did not send them.
+invert look, touch movement) and a starting graphics quality — or `null`
+when the Arcade did not send them.
 
 **Recommendations only; the player's own choice in your game wins.** Start
 a setting from here while the player has made no choice of their own for
@@ -7837,6 +7839,36 @@ On a touch screen, the movement thumbstick the player wants: `'floating'`
 appears where the thumb lands, `'fixed'` stays in one place. `'floating'`
 when the Arcade did not say. Your game draws the stick.
 
+<a id="gemrecommendedsettings-graphicsquality"></a>
+
+## GemRecommendedSettings.graphicsQuality
+
+```ts
+readonly graphicsQuality: GemGraphicsQuality
+```
+
+The graphics quality to START at on this device: `'low'`, `'medium'` or
+`'high'`. The Arcade picks it per device — the tier it detected, or the
+player's own Graphics choice — so a game opens at a quality that suits the
+device instead of guessing. A starting point, not a cap: while
+`graphicsQualityAuto` is true your game may adapt from here as it runs,
+and `createQualityGovernor` from `@indiegems/gem-web-sdk/quality` does
+that for you. When the Arcade did not say, `'low'` with `batterySaver`
+on and `'medium'` otherwise.
+
+<a id="gemrecommendedsettings-graphicsqualityauto"></a>
+
+## GemRecommendedSettings.graphicsQualityAuto
+
+```ts
+readonly graphicsQualityAuto: boolean
+```
+
+Whether the Arcade chose `graphicsQuality` for this device (`true`, the
+player left Graphics on Auto) or the player picked it by hand (`false`).
+While it is `false`, hold that quality: never step it down or up on your
+own. `true` when the Arcade did not say.
+
 <a id="gemcohort"></a>
 
 ## GemCohort
@@ -7998,10 +8030,11 @@ The unsafe margin on each edge of your frame.
 readonly reserved: readonly GemReservedArea[]
 ```
 
-Rectangles of your frame the arcade's own controls cover — its menu button
-in the top-right corner, and the wallets in the middle of the top row while they are shown (see
-`setWalletVisible`). Keep essential UI and touch targets out of them. Empty
-when the arcade covers nothing.
+Rectangles of your frame the arcade's own controls cover — in the Gem
+Arcade, its Gem button in the top-left corner, and the frame-rate readout
+beside it while the player shows it; an embedder that draws wallets over
+your game adds theirs (see `setWalletVisible`). Keep essential UI and touch
+targets out of them. Empty when the arcade covers nothing.
 
 A stylesheet reads the per-corner custom properties the SDK stamps from
 these instead — `--gem-reserved-tl-height` and friends.
@@ -8080,8 +8113,8 @@ While shown, show ONLY these: platform currency slugs as
 `gem.platform.currencies.get()` lists them (`GEMS`, `ARCADE_TICKETS`),
 matched exactly, and the literal `'score'` for the achievement score. Only
 for a screen about one currency, such as a ticket store; leave it out and
-every wallet shows, which is always safe. The Gem Arcade ignores it and
-shows every wallet while shown.
+every wallet shows, which is always safe. The Gem Arcade draws no wallet
+over a game, so it has nothing to narrow and ignores it.
 
 <a id="gamemenuitem"></a>
 
@@ -8929,6 +8962,20 @@ honouring them is part of the platform's release checklist.
 Read it at the moment you need it rather than caching it: the locale can
 change mid-session.
 
+<a id="gem-paused"></a>
+
+## Gem.paused
+
+```ts
+readonly paused: boolean
+```
+
+Whether the arcade has your game paused right now: `true` from an
+`onPause(true)` until the `onPause(false)` that follows it, `false` before
+any. The same pause `onPause` tells you about, readable at any moment —
+for code that was not around when the edge arrived, such as a frame-time
+monitor deciding whether a slow frame counts.
+
 <a id="gem-cohorts"></a>
 
 ## Gem.cohorts
@@ -9084,10 +9131,13 @@ is ignored by the arcade, which keeps the image it is showing.
 cueReward(cue: RewardCue): boolean
 ```
 
-Tell the arcade a platform-currency reward is on its way, so its **wallet
-shows it landing**: a pending state right away and, once the platform
-confirms the grant, the currency flying from `origin` into the wallet with
-a bounce as the total moves.
+Tell the arcade a platform-currency reward is on its way, so it **shows it
+landing**: in the Gem Arcade the currency flies from `origin` into the Gem
+button at the top-left of your frame, which pops as each mark lands, and
+the player's total moves once the platform confirms the grant. The Gem
+Arcade draws no wallet over your game: the player sees their Gems and
+Tickets in the Gem menu. A payout you do not cue still flies, from the
+middle of your frame, so cue the ones the player earns on screen.
 
 Call it the moment your game decides to award — when your server has moved
 (or is about to move) the progression mapped onto a platform currency —
@@ -9135,28 +9185,23 @@ setWalletVisible(visible: boolean, options?: WalletVisibleOptions): boolean
 Show or hide the player's wallets — Gems, Tickets, the achievement score —
 that an embedder draws over your game.
 
-**Shown unless you hide them.** Call nothing and the Gem Arcade shows
-every wallet the whole time, during play too. A game that wants the top
-row for gameplay hides them while it plays and shows them again on its
-menus (the Gem Arcade honours this again since 2026-10-08, on a phone,
-where the wallets sit over your game; where they sit beside the frame it
-changes nothing).
+**The Gem Arcade draws no wallet over a game** (since 2026-10-11): the
+player sees their balances in the Gem menu, and payouts fly into the Gem
+button. So under the Gem Arcade this changes nothing on screen — it is
+accepted and harmless, and a game that already calls it keeps working.
+Call it for an embedder that does draw wallets over your game: hide them
+while you play, show them on your menus.
 
 ```js
 level.onStart = () => gem.setWalletVisible(false);
 menu.onOpen = () => gem.setWalletVisible(true);
 ```
 
-The Gem Arcade does NOT act on `only`: a shown wallet there is every
-wallet. Another embedder may honour it.
-
 **It is screen state, not a toggle.** Each call is the whole answer and
-replaces the last. While hidden, the arcade still pops a wallet up for a
-moment when something happens to it — a reward you cued, a spend, a
-landing — and your state never cancels that. Shown wallets cover the
-middle of your frame's top row, each arriving as a rectangle in
-`gem.viewport.reserved`; hiding them gives that space back. A wallet the
-arcade pops up for a moment floats over your game and moves nothing.
+replaces the last. Where an embedder draws wallets, shown ones arrive as
+rectangles in `gem.viewport.reserved` and hiding them gives that space
+back; the Gem Arcade sends none for wallets. `only` narrows what shows,
+where an embedder honours it; the Gem Arcade does not.
 
 **Never draw a platform balance yourself**, and never show a pending state
 for one: the arcade takes every figure from the platform. If this returns
@@ -11692,6 +11737,17 @@ readonly code: "unknown_currency" | "not_purchasable" | "no_price_in_currency" |
 Which check refused: `unknown_currency`, `not_purchasable`,
 `no_price_in_currency` or `quantity_invalid`.
 
+<a id="gemgraphicsquality"></a>
+
+## GemGraphicsQuality
+
+```ts
+type GemGraphicsQuality = "low" | "medium" | "high"
+```
+
+A graphics quality tier: `'low'`, `'medium'` or `'high'`. What
+`gem.prefs.recommended.graphicsQuality` holds.
+
 <a id="servertokengrant"></a>
 
 ## ServerTokenGrant

package/docs/api/api-reference-server.md

@@ -1,6 +1,6 @@
 # The server surface — API reference
 
-Generated from `@indiegems/gem-web-sdk/sdk` v10.3.0, the version of the package this file ships in. Every symbol below carries an explicit anchor, its `anchor` in `reference.json` beside this file.
+Generated from `@indiegems/gem-web-sdk/sdk` v10.4.0, the version of the package this file ships in. Every symbol below carries an explicit anchor, its `anchor` in `reference.json` beside this file.
 
 `@indiegems/gem-web-sdk/sdk` is the one import a game writes, wherever its code runs. `@indiegems/gem-web-sdk/server` exports exactly the symbols on this page and nothing else, for a build that wants only this half.
 

package/docs/api/reference.json

@@ -2,7 +2,7 @@
   "schema_version": 2,
   "source": {
     "repo": "IndieGems/gem-web-sdk",
-    "version": "10.3.0"
+    "version": "10.4.0"
   },
   "entries": [
     {
@@ -6152,7 +6152,7 @@
           "group": "platform",
           "signature": "interface RewardCue",
           "documented": true,
-          "summary": "A platform-currency reward on its way to the arcade's wallet — what\n`gem.cueReward` takes.",
+          "summary": "A platform-currency reward on its way to the arcade — in the Gem Arcade, a\nflight into the Gem button at the top-left of your frame — what\n`gem.cueReward` takes.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -6168,7 +6168,7 @@
           "group": "platform",
           "signature": "currencySlug: string",
           "documented": true,
-          "summary": "The platform currency's slug, as `gem.platform.currencies.get()` lists it —\n`GEMS` or `ARCADE_TICKETS`. It decides which total in the arcade's wallet\nthe payout flies into.",
+          "summary": "The platform currency's slug, as `gem.platform.currencies.get()` lists it —\n`GEMS` or `ARCADE_TICKETS`. It decides what flies — gems or tickets — and\nwhich of the player's totals the payout moves.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -6200,7 +6200,7 @@
           "group": "platform",
           "signature": "origin?: { x: number; y: number }",
           "documented": true,
-          "summary": "Where the flight starts, in CSS px of YOUR viewport: the centre of the\ncurrency's icon (or hero) your screen draws beside the reward — the gem\nfor Gems, the ticket for Tickets. Measure that element's own box, not a\nrow or panel around it. Leave it out and the arcade animates at its wallet\nalone.",
+          "summary": "Where the flight starts, in CSS px of YOUR viewport: the centre of the\ncurrency's icon (or hero) your screen draws beside the reward — the gem\nfor Gems, the ticket for Tickets. Measure that element's own box, not a\nrow or panel around it. Leave it out and the Gem Arcade flies the payout\nfrom the middle of your frame once the platform confirms it.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -6484,7 +6484,7 @@
           "group": "frame",
           "signature": "cueReward(cue: RewardCue): boolean",
           "documented": true,
-          "summary": "Tell the arcade a platform-currency reward is on its way, so its wallet can\nshow it landing — a pending state now and, once the platform confirms the\ngrant, the currency flying from `origin` into the wallet.\n\nPrefer `gem.cueReward`, which says what the arcade does with it. This one\nsends only while connected, and only to an arcade that draws a wallet.",
+          "summary": "Tell the arcade a platform-currency reward is on its way, so it can show it\nlanding — in the Gem Arcade, the currency flying from `origin` into the Gem\nbutton, the total moving once the platform confirms the grant.\n\nPrefer `gem.cueReward`, which says what the arcade does with it. This one\nsends only while connected, and only to an arcade that draws a wallet.",
           "deprecated": null,
           "params": [
             {
@@ -8702,7 +8702,7 @@
           "group": "player",
           "signature": "readonly recommended: GemRecommendedSettings | null",
           "documented": true,
-          "summary": "The player's Arcade-wide defaults for this device — a volume, battery\nsaver, a keyboard layout, the gamepad's confirm button, vibration, and the\ncamera and controls settings (look sensitivity, gamepad look sensitivity,\ninvert look, touch movement) — or `null` when the Arcade did not send them.\n\n**Recommendations only; the player's own choice in your game wins.** Start\na setting from here while the player has made no choice of their own for\nit, and never overwrite one they made because this changed:\n\n```js\nconst saved = gem.deviceSettings.current ?? {};\nconst volume = saved.volume ?? gem.prefs?.recommended?.volume ?? 100;\n```\n\nUnlike `muted` and `reducedMotion`, nothing here is applied for you, and\nnothing obliges you to use it. See the guide's \"Game settings\" section.",
+          "summary": "The player's Arcade-wide defaults for this device — a volume, battery\nsaver, a keyboard layout, the gamepad's confirm button, vibration, the\ncamera and controls settings (look sensitivity, gamepad look sensitivity,\ninvert look, touch movement) and a starting graphics quality — or `null`\nwhen the Arcade did not send them.\n\n**Recommendations only; the player's own choice in your game wins.** Start\na setting from here while the player has made no choice of their own for\nit, and never overwrite one they made because this changed:\n\n```js\nconst saved = gem.deviceSettings.current ?? {};\nconst volume = saved.volume ?? gem.prefs?.recommended?.volume ?? 100;\n```\n\nUnlike `muted` and `reducedMotion`, nothing here is applied for you, and\nnothing obliges you to use it. See the guide's \"Game settings\" section.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -8876,6 +8876,38 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "GemRecommendedSettings.graphicsQuality",
+          "name": "graphicsQuality",
+          "anchor": "gemrecommendedsettings-graphicsquality",
+          "group": "player",
+          "signature": "readonly graphicsQuality: GemGraphicsQuality",
+          "documented": true,
+          "summary": "The graphics quality to START at on this device: `'low'`, `'medium'` or\n`'high'`. The Arcade picks it per device — the tier it detected, or the\nplayer's own Graphics choice — so a game opens at a quality that suits the\ndevice instead of guessing. A starting point, not a cap: while\n`graphicsQualityAuto` is true your game may adapt from here as it runs,\nand `createQualityGovernor` from `@indiegems/gem-web-sdk/quality` does\nthat for you. When the Arcade did not say, `'low'` with `batterySaver`\non and `'medium'` otherwise.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemRecommendedSettings.graphicsQualityAuto",
+          "name": "graphicsQualityAuto",
+          "anchor": "gemrecommendedsettings-graphicsqualityauto",
+          "group": "player",
+          "signature": "readonly graphicsQualityAuto: boolean",
+          "documented": true,
+          "summary": "Whether the Arcade chose `graphicsQuality` for this device (`true`, the\nplayer left Graphics on Auto) or the player picked it by hand (`false`).\nWhile it is `false`, hold that quality: never step it down or up on your\nown. `true` when the Arcade did not say.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "GemCohort",
           "name": "GemCohort",
@@ -9069,7 +9101,7 @@
           "group": "player",
           "signature": "readonly reserved: readonly GemReservedArea[]",
           "documented": true,
-          "summary": "Rectangles of your frame the arcade's own controls cover — its menu button\nin the top-right corner, and the wallets in the middle of the top row while they are shown (see\n`setWalletVisible`). Keep essential UI and touch targets out of them. Empty\nwhen the arcade covers nothing.\n\nA stylesheet reads the per-corner custom properties the SDK stamps from\nthese instead — `--gem-reserved-tl-height` and friends.",
+          "summary": "Rectangles of your frame the arcade's own controls cover — in the Gem\nArcade, its Gem button in the top-left corner, and the frame-rate readout\nbeside it while the player shows it; an embedder that draws wallets over\nyour game adds theirs (see `setWalletVisible`). Keep essential UI and touch\ntargets out of them. Empty when the arcade covers nothing.\n\nA stylesheet reads the per-corner custom properties the SDK stamps from\nthese instead — `--gem-reserved-tl-height` and friends.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -9181,7 +9213,7 @@
           "group": "platform",
           "signature": "readonly only?: readonly string[]",
           "documented": true,
-          "summary": "While shown, show ONLY these: platform currency slugs as\n`gem.platform.currencies.get()` lists them (`GEMS`, `ARCADE_TICKETS`),\nmatched exactly, and the literal `'score'` for the achievement score. Only\nfor a screen about one currency, such as a ticket store; leave it out and\nevery wallet shows, which is always safe. The Gem Arcade ignores it and\nshows every wallet while shown.",
+          "summary": "While shown, show ONLY these: platform currency slugs as\n`gem.platform.currencies.get()` lists them (`GEMS`, `ARCADE_TICKETS`),\nmatched exactly, and the literal `'score'` for the achievement score. Only\nfor a screen about one currency, such as a ticket store; leave it out and\nevery wallet shows, which is always safe. The Gem Arcade draws no wallet\nover a game, so it has nothing to narrow and ignores it.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -9949,6 +9981,22 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "Gem.paused",
+          "name": "paused",
+          "anchor": "gem-paused",
+          "group": "start",
+          "signature": "readonly paused: boolean",
+          "documented": true,
+          "summary": "Whether the arcade has your game paused right now: `true` from an\n`onPause(true)` until the `onPause(false)` that follows it, `false` before\nany. The same pause `onPause` tells you about, readable at any moment —\nfor code that was not around when the edge arrived, such as a frame-time\nmonitor deciding whether a slow frame counts.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "Gem.cohorts",
           "name": "cohorts",
@@ -10057,7 +10105,7 @@
           "group": "start",
           "signature": "cueReward(cue: RewardCue): boolean",
           "documented": true,
-          "summary": "Tell the arcade a platform-currency reward is on its way, so its **wallet\nshows it landing**: a pending state right away and, once the platform\nconfirms the grant, the currency flying from `origin` into the wallet with\na bounce as the total moves.\n\nCall it the moment your game decides to award — when your server has moved\n(or is about to move) the progression mapped onto a platform currency —\nand pass the centre of that currency's icon (or hero) on your screen, so\nthe flight starts from the mark the player is looking at:\n\n```js\nconst { x, y, width, height } = rewardGem.getBoundingClientRect(); // the gem's own box\ngem.cueReward({\n  currencySlug: 'GEMS', // or 'ARCADE_TICKETS', from the ticket\n  expected: 15,\n  origin: { x: x + width / 2, y: y + height / 2 },\n});\n```\n\n**This is the platform-currency animation, and the only one.** The display\nof every platform currency — Gems and Tickets alike — belongs to the\narcade: a game draws no flight or celebration of its own for one and keeps\nno counter of one. **If this returns `false`, do nothing** — there is no\nfallback celebration.\n\n**The arcade never takes your word for the amount.** What lands, and the\nplayer's new total, come from the platform itself; `expected` is drawn as\nprovisional, and a cue the platform never confirms fades on its own — a\ngrant clamped to zero, say, or one the receipt reports `suppressed`. So\nthe cue can only ever make the wallet move for a reward that really\nlanded — which it does on every channel, dev and test included.",
+          "summary": "Tell the arcade a platform-currency reward is on its way, so it **shows it\nlanding**: in the Gem Arcade the currency flies from `origin` into the Gem\nbutton at the top-left of your frame, which pops as each mark lands, and\nthe player's total moves once the platform confirms the grant. The Gem\nArcade draws no wallet over your game: the player sees their Gems and\nTickets in the Gem menu. A payout you do not cue still flies, from the\nmiddle of your frame, so cue the ones the player earns on screen.\n\nCall it the moment your game decides to award — when your server has moved\n(or is about to move) the progression mapped onto a platform currency —\nand pass the centre of that currency's icon (or hero) on your screen, so\nthe flight starts from the mark the player is looking at:\n\n```js\nconst { x, y, width, height } = rewardGem.getBoundingClientRect(); // the gem's own box\ngem.cueReward({\n  currencySlug: 'GEMS', // or 'ARCADE_TICKETS', from the ticket\n  expected: 15,\n  origin: { x: x + width / 2, y: y + height / 2 },\n});\n```\n\n**This is the platform-currency animation, and the only one.** The display\nof every platform currency — Gems and Tickets alike — belongs to the\narcade: a game draws no flight or celebration of its own for one and keeps\nno counter of one. **If this returns `false`, do nothing** — there is no\nfallback celebration.\n\n**The arcade never takes your word for the amount.** What lands, and the\nplayer's new total, come from the platform itself; `expected` is drawn as\nprovisional, and a cue the platform never confirms fades on its own — a\ngrant clamped to zero, say, or one the receipt reports `suppressed`. So\nthe cue can only ever make the wallet move for a reward that really\nlanded — which it does on every channel, dev and test included.",
           "deprecated": null,
           "params": [
             {
@@ -10080,7 +10128,7 @@
           "group": "start",
           "signature": "setWalletVisible(visible: boolean, options?: WalletVisibleOptions): boolean",
           "documented": true,
-          "summary": "Show or hide the player's wallets — Gems, Tickets, the achievement score —\nthat an embedder draws over your game.\n\n**Shown unless you hide them.** Call nothing and the Gem Arcade shows\nevery wallet the whole time, during play too. A game that wants the top\nrow for gameplay hides them while it plays and shows them again on its\nmenus (the Gem Arcade honours this again since 2026-10-08, on a phone,\nwhere the wallets sit over your game; where they sit beside the frame it\nchanges nothing).\n\n```js\nlevel.onStart = () => gem.setWalletVisible(false);\nmenu.onOpen = () => gem.setWalletVisible(true);\n```\n\nThe Gem Arcade does NOT act on `only`: a shown wallet there is every\nwallet. Another embedder may honour it.\n\n**It is screen state, not a toggle.** Each call is the whole answer and\nreplaces the last. While hidden, the arcade still pops a wallet up for a\nmoment when something happens to it — a reward you cued, a spend, a\nlanding — and your state never cancels that. Shown wallets cover the\nmiddle of your frame's top row, each arriving as a rectangle in\n`gem.viewport.reserved`; hiding them gives that space back. A wallet the\narcade pops up for a moment floats over your game and moves nothing.\n\n**Never draw a platform balance yourself**, and never show a pending state\nfor one: the arcade takes every figure from the platform. If this returns\n`false`, do nothing in its place.",
+          "summary": "Show or hide the player's wallets — Gems, Tickets, the achievement score —\nthat an embedder draws over your game.\n\n**The Gem Arcade draws no wallet over a game** (since 2026-10-11): the\nplayer sees their balances in the Gem menu, and payouts fly into the Gem\nbutton. So under the Gem Arcade this changes nothing on screen — it is\naccepted and harmless, and a game that already calls it keeps working.\nCall it for an embedder that does draw wallets over your game: hide them\nwhile you play, show them on your menus.\n\n```js\nlevel.onStart = () => gem.setWalletVisible(false);\nmenu.onOpen = () => gem.setWalletVisible(true);\n```\n\n**It is screen state, not a toggle.** Each call is the whole answer and\nreplaces the last. Where an embedder draws wallets, shown ones arrive as\nrectangles in `gem.viewport.reserved` and hiding them gives that space\nback; the Gem Arcade sends none for wallets. `only` narrows what shows,\nwhere an embedder honours it; the Gem Arcade does not.\n\n**Never draw a platform balance yourself**, and never show a pending state\nfor one: the arcade takes every figure from the platform. If this returns\n`false`, do nothing in its place.",
           "deprecated": null,
           "params": [
             {
@@ -12778,6 +12826,22 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "GemGraphicsQuality",
+          "name": "GemGraphicsQuality",
+          "anchor": "gemgraphicsquality",
+          "group": "player",
+          "signature": "type GemGraphicsQuality = \"low\" | \"medium\" | \"high\"",
+          "documented": true,
+          "summary": "A graphics quality tier: `'low'`, `'medium'` or `'high'`. What\n`gem.prefs.recommended.graphicsQuality` holds.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "ServerTokenGrant",
           "name": "ServerTokenGrant",

package/docs/brand-art.md

@@ -75,7 +75,7 @@ These are the Arcade's own icon renders — the files its wallet draws — with
 for byte, apart from stripping the colour-space and resolution tags every browser already assumes. They are the gem
 of the arcade's Gems flight — a 3D model rendered in Blender, a round cut with the icon's six facet
 colours — at rest and without its motion blur, so the gem a player sees in your price is the gem
-that flies into their wallet. Each size has its own recipe, in CSS px, so it carries the same visual
+that flies into the Gem button when they are paid. Each size has its own recipe, in CSS px, so it carries the same visual
 weight on every screen:
 
 | Size | Outline | Girdle line | Facet lines | Sparkle |
@@ -282,7 +282,8 @@ too, with the ticket in place of the gem. Amended 2026-09-30 for the earn allowa
 decision of that date); the ruling's other rules are unchanged. In rules:
 
 - **Keep no Gems counter.** Your game shows no Gems balance, running total or wallet of its own, on
-  any screen. The arcade's wallet is the only place Gems accrue, and the only place a total is shown.
+  any screen. The arcade's wallet is the only place Gems accrue, and the only place a total is shown
+  — in the Gem Arcade, the Gem menu, which the player opens from the Gem button at the top-left.
 - **Draw no Gems flight or celebration of your own.** No particles flying to a corner, no counting-up
   number, no burst of gems. `gem.cueReward` is the animation, and the arcade draws it.
 - **Show no Gems amount at all when you are not connected to the arcade.** Without the arcade there is
@@ -306,8 +307,9 @@ decision of that date); the ruling's other rules are unchanged. In rules:
   with the canvas's `getBoundingClientRect()`.
 
   A Tickets payout is cued the same way, from the ticket, with `currencySlug: 'ARCADE_TICKETS'`. The
-  arcade's wallet shows Gems and Tickets side by side and flies each payout into the total of the
-  currency the cue names, so the slug is what decides where your ticket lands.
+  slug decides what flies — gems or tickets — and which total the platform moves. In the Gem Arcade
+  every payout flies into the Gem button at the top-left of your frame; no wallet is drawn over
+  your game.
 - **If `cueReward` returns `false`, do nothing.** There is no fallback celebration. `false` means the
   arcade will not show the payout here — the bridge is not up, or the embedder has no wallet — and
   your game does not replace it with one of its own. Your reward screen still says what was earned;

package/docs/changelog.md

@@ -16,6 +16,26 @@ 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.
 
+## 10.4.0
+
+Upgrading from 10.3.1. Impact: required.
+
+### Rebuild
+
+- The recommended preferences type gained optional graphics quality and automatic fields, and the host method that sends preferences accepts the same two fields. Existing code keeps working; recompile your game against the new types. Host or test-harness code that sends preferences can now also pass the graphics quality tier and the automatic flag.
+
+### New capability
+
+- The recommended settings now carry a graphics quality tier and an automatic flag. The Arcade picks a starting tier per device (low, medium or high) and a game can start from it. An unknown tier is read as medium, a missing tier follows the battery saver setting (low when it is on, otherwise medium), and a missing automatic flag is read as true, so both values are always present in the game. When the automatic flag is false the player picked the tier by hand, and the game should keep it rather than adapt it.
+- The new paused value holds the latest state of the pause signal. Code that starts after the pause signal has already arrived, such as a frame-time monitor created mid-game, can read it to learn whether the game is currently paused.
+- A new optional quality entry point lets a game adapt its graphics level to frame time. It starts at the Arcade's tier mapped onto the game's own levels. It steps down one level after about two seconds of slow frames and up one level after about ten seconds of comfortably fast frames, never going above one level over its start. It ignores paused and hidden time, holds steady when the player chose the tier by hand, and restarts when a new recommendation arrives. It can run on animation frames or be fed frame times manually. A game that does not import it pays nothing in size.
+
+## 10.3.1
+
+Upgrading from 10.3.0. Impact: none.
+
+Nothing in this release asks anything of a game.
+
 ## 10.3.0
 
 Upgrading from 10.2.0. Impact: required.

package/docs/daily-challenges.md

@@ -320,11 +320,11 @@ Four things to know before you ship one:
   in" is not in general when the allowance refills. Each date's allowance is spent once, whatever
   the player does to their time zone.
 
-**When a completion pays a platform currency, show it where it happened.** The arcade draws the
-player's Gems and Tickets in its own chrome, and without a cue a payout lands there silently, in a
-corner the player is not looking at. At the moment your game shows the challenge complete, call
+**When a completion pays a platform currency, show it where it happened.** The arcade shows the
+player's Gems and Tickets in its own chrome, and without a cue a payout flies from the middle of
+your frame, not from the payout the player is looking at. At the moment your game shows the challenge complete, call
 `gem.cueReward` with the currency that paid (`GEMS` or `ARCADE_TICKETS`) and the centre of its icon
-beside the payout on your completion screen, and the payout flies from there into the wallet:
+beside the payout on your completion screen, and the payout flies from there into the Gem button:
 [inventory-and-catalogs.md](inventory-and-catalogs.md#showing-the-reward-land-in-the-arcades-wallet).
 **If it returns `false`, do nothing** — no celebration of your own, no counter, no flight;
 platform-currency display belongs to the arcade, and a game not connected to it shows no

package/docs/getting-started.md

@@ -50,7 +50,7 @@ either way.
 ```jsonc
 // package.json
 "dependencies": {
-  "@indiegems/gem-web-sdk": "10.3.0"
+  "@indiegems/gem-web-sdk": "10.4.0"
 }
 ```
 

package/docs/inventory-and-catalogs.md

@@ -589,14 +589,15 @@ the source progression from a function the player calls, on a progression that o
 ### Showing the reward land in the arcade's wallet
 
 **Platform-currency display belongs to the arcade** (the creator's ruling, 2026-09-24) — Gems and
-Tickets alike. The arcade draws the player's platform currencies in its own chrome while your game
-runs, and moves a total when the platform confirms a grant. Your game keeps no counter or balance
+Tickets alike. The arcade shows the player's platform currencies in its own chrome — in the Gem
+Arcade, the Gem menu the player opens from the Gem button at the top-left of your frame; no wallet
+is drawn over your game — and moves a total when the platform confirms a grant. Your game keeps no counter or balance
 of a platform currency of its own, draws no flight or celebration of its own, and shows no
 platform-currency amount at all when it is not connected to the arcade.
 
 What your game does is ask for the payout to start on **your** screen, from the currency's icon (or
-hero) beside the reward, so the currency flies from there into the wallet and the total bounces up
-as it lands. A Gems payout is cued from the gem:
+hero) beside the reward, so the currency flies from there into the arcade — in the Gem Arcade,
+into the Gem button, which pops as each mark lands. A Gems payout is cued from the gem:
 
 ```js
 const { x, y, width, height } = rewardGem.getBoundingClientRect(); // the gem element's own box
@@ -609,8 +610,10 @@ gem.cueReward({
 
 `origin` is the **centre of the gem on screen** — measure the gem element itself, not the row or
 panel around it. A Tickets payout is the same call with `currencySlug: 'ARCADE_TICKETS'`, from the
-ticket: the slug decides which total the payout flies into. **If `cueReward` returns `false`, do
-nothing**: there is no fallback celebration.
+ticket: the slug decides what flies and which total moves. **A payout you do not cue still flies**
+in the Gem Arcade, from the middle of your frame, once the platform confirms it — cue it so the
+flight starts where the player is looking. **If `cueReward` returns `false`, do nothing**: there is
+no fallback celebration.
 `false` means the arcade will not show it here — the bridge is not up, or the embedder has no wallet
 — and your game does not draw one of its own in its place.
 
@@ -898,7 +901,8 @@ buyButton.disabled = !gems || gems.balance < price; // can the player afford it?
 ```
 
 **Read it to decide, never to display.** Platform-currency display belongs to the arcade: its
-wallet shows the player's Gems and Tickets totals while your game runs, and your game keeps no
+wallet — the Gem menu, in the Gem Arcade — shows the player's Gems and Tickets totals while your
+game runs, and your game keeps no
 counter, balance or wallet total of either of its own ([brand-art.md](brand-art.md) §5). Use the
 balance to enable a purchase or to say "not enough Gems" — not to draw a number.
 

package/docs/manifest.json

@@ -28,13 +28,13 @@
     },
     {
       "file": "brand-art.md",
-      "sha256": "cf54939a0fcee1f5a6e11b9de52b5ed498ec8c373683e92aa5bc6654b12eb0ab",
-      "updated": "2026-10-01T03:49:20Z"
+      "sha256": "87267dca53e5506b1aee77ac9819aef8025c8e0de2780e65a2ea3b7236a9c0ab",
+      "updated": "2026-10-11T18:48:12Z"
     },
     {
       "file": "changelog.md",
-      "sha256": "daae6b71cecc9761bc1e3ed5603c5d8f366e0533ce4ecc6d6c57f546efe1a292",
-      "updated": "2026-10-11T18:22:44Z"
+      "sha256": "fd69a4c08141e0646d695adedce0d313de2295cfd6bc656433ce33dd02ec731a",
+      "updated": "2026-10-11T19:38:28Z"
     },
     {
       "file": "cross-promotion.md",
@@ -43,8 +43,8 @@
     },
     {
       "file": "daily-challenges.md",
-      "sha256": "f4842b2fe01c8780020326f4722ab69dc01c1f40e1e6455cf2fb27752094383d",
-      "updated": "2026-10-10T14:37:50Z"
+      "sha256": "0423168355c22724e705def15ca19a5651b7f0da3598ec5aabcc69c32e0bb401",
+      "updated": "2026-10-11T18:48:12Z"
     },
     {
       "file": "dedicated-server-flow.md",
@@ -68,13 +68,13 @@
     },
     {
       "file": "getting-started.md",
-      "sha256": "fd566ed7d7f0b1b2b9bea823de5455d2ee9a66072e7303df1bc5c12c1acddcbe",
-      "updated": "2026-10-11T18:22:44Z"
+      "sha256": "f2c13478823888b777058bbdc4de41216dd8b48d7e7efab3a31334f980d647ec",
+      "updated": "2026-10-11T19:38:28Z"
     },
     {
       "file": "inventory-and-catalogs.md",
-      "sha256": "3e0f71db5b4f5d2d256289f90ffec3ed2887a70b1e72b02f55ec64815043d900",
-      "updated": "2026-10-09T00:13:03Z"
+      "sha256": "fecd1299ef19bc50ea17abe96bbe49f62dc366a9fc0f354c843a42b2d5a2f9e2",
+      "updated": "2026-10-11T18:48:12Z"
     },
     {
       "file": "leaderboards.md",
@@ -123,8 +123,8 @@
     },
     {
       "file": "server-bundles.md",
-      "sha256": "c6935f10ba645e8a9d3fd48c10f313324bfdbca6fcbd273dfade6579dcfd32e8",
-      "updated": "2026-10-11T18:22:44Z"
+      "sha256": "04bb5fb5f631a52c7962728a74602ce7eec6ee6a1a3efa6197542ce5aa4cce95",
+      "updated": "2026-10-11T19:38:28Z"
     },
     {
       "file": "serverless-functions-js.md",
@@ -148,8 +148,8 @@
     },
     {
       "file": "what-a-game-must-do.md",
-      "sha256": "44fa07b8f379181cfac9a89c8fa672946d0e4aaeefe1fd3386cc3565abcb3c95",
-      "updated": "2026-10-11T17:59:34Z"
+      "sha256": "ce2abba4b32ee1c0dd69eabaaac1f33e2534ac5b58e9a45c4f8a7b3bd3e11f27",
+      "updated": "2026-10-11T19:25:48Z"
     }
   ]
 }