@indiegems/gem-web-sdk 9.1.1 → 9.1.2

package/docs/platform-rules.md

@@ -328,9 +328,9 @@ longer one, are in [`server-bundles.md`](server-bundles.md#how-long-your-server-
 
 Decided by the platform on **2026-09-26**, and a contract rather than an implementation fact.
 
-The **Boost** is the only thing the Arcade sells for real money. While a player has one, they earn
-**Gems and Tickets** faster — every grant is multiplied — and their earning limits and holdings cap
-are raised by the same tier. It **never** touches achievement points. The platform applies all of
+The **Boost** is something the Arcade sells for real money, in its own store. While a player has
+one, they earn **Gems and Tickets** faster — every grant is multiplied — and their earning limits
+and holdings cap are raised by the same tier. It **never** touches achievement points. The platform applies all of
 it on its own side, when it pays: a game does nothing to make a boost work, and cannot make one
 work harder.
 

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

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

@@ -595,6 +595,13 @@ there is no route by which the frame could request one. `createGem` forwards all
   nothing after the pause. So the pause edge is your last guaranteed moment. Write anything the
   player would mind losing there, and never hold it back for a terminate warning that may not come.
 
+  **Re-read on resume.** Your game is told that it was paused and resumed, never why, and never
+  what the player did in the meantime. Their Gems and Tickets can change while you are paused, so
+  if your game keeps anything worked out from a balance, such as a Buy button it greyed out or a
+  "not enough Gems" line, read `gem.platform.currencies.get()` again on every `onPause(false)`
+  rather than trusting what it read before the pause
+  ([inventory-and-catalogs.md](inventory-and-catalogs.md#reading-the-players-balance)).
+
 - **`onWillTerminate`** — persist now. `graceMs` is a promise about how long the parent will wait.
 - **`onViewport`** — where your frame's own edges are under a cutout. **Most games need no
   handler**: the SDK has already written the same numbers to `--gem-safe-top` and friends on your
@@ -700,8 +707,8 @@ On a phone your game is full-bleed, and the arcade keeps one row of its own over
   [the Arcade's menu](#the-arcades-menu-your-settings-live-in-it): Return to the Arcade, your
   settings, mute and the rest.
 - **The player's wallets** (Gems, Tickets, their achievement score), in the **middle of the row**,
-  [always there](#the-arcades-wallet-always-shown-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,
+  [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 top of the screen has one layout, in every game:**
@@ -1021,25 +1028,28 @@ 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: always shown, never drawn
+## The Arcade's wallet: shown unless you hide it, never drawn
 
 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.
 
-**The Arcade shows every wallet the whole time, during play too** (since 2026-10-04). They are
-small, translucent chips in the middle of the top row, and they are
+**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`, gameplay included. There is nothing for
-your game to call.
+`--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.
 
-⚠️ **`gem.setWalletVisible` no longer hides anything in the Arcade.** It was how a game hid the
-wallets for gameplay and showed them on its menus, and narrowed them to one currency on a store
-screen. The Arcade still accepts the call — it returns `true`, and existing games need no change —
-but the wallets stay up whatever it is told. **Do not design a screen around the top row being
-clear during play**: it is not. Another embedder may still honour the call, so leaving it in is
-harmless; new code does not need it.
+⚠️ **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.
 
 ## No accidental text selection
 
@@ -1195,7 +1205,7 @@ members. `gem.player.displayHandle` and `gem.player.avatarUrl` still work, and a
 
 ### The signed-in player's Boost: show it, never gate on it
 
-`gem.player` also carries **`boost`** — the player's Boost, the Arcade's one real-money product.
+`gem.player` also carries **`boost`** — the player's Boost, which the Arcade sells for real money.
 While it lasts the player earns Gems and Tickets faster (never achievement points), and the
 platform raises their earning limits to match. The platform does all of that on its own side when
 it pays; your game does nothing to make a boost work.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indiegems/gem-web-sdk",
-  "version": "9.1.1",
+  "version": "9.1.2",
   "description": "postMessage bridge contract between gem-web and browser-playable games",
   "license": "UNLICENSED",
   "type": "module",

package/schema/bridge.v1.json

@@ -616,7 +616,7 @@
           "optional": true,
           "$comment": [
             "The player's Boost, FOR DISPLAY ONLY — a platform rule, not advice. A",
-            "Boost is the Arcade's one real-money product: it",
+            "Boost is something the Arcade sells for real money: it",
             "multiplies what the player EARNS in platform currencies (Gems and",
             "Tickets) and raises their earning limits. It never touches achievement",
             "points.",
@@ -2813,11 +2813,8 @@
         "the following is not offering a degraded store, it is offering a game a",
         "button that charges a player:",
         "",
-        "  PAYABLE, EARNED CURRENCIES ONLY. `currencySlug` is frame-chosen and this",
-        "  schema does not constrain which currency it names. The argument that let",
-        "  this ship without a top-up flow binds a currency a player EARNS: short of",
-        "  Gems or Tickets the answer is to go and play, and neither is sold for",
-        "  money. It does not bind a currency a player BUYS. So resolve the slug",
+        "  PAYABLE CURRENCIES ONLY. `currencySlug` is frame-chosen and this schema",
+        "  does not constrain which currency it names. So resolve the slug",
         "  against the platform's own currency records - an active currency the",
         "  platform marks payable in games - and refuse the rest, `declined` with",
         "  `unknown_currency` or `currency_not_in_game_payable`. Resolve it EXACTLY,",
@@ -2828,6 +2825,28 @@
         "  the frame does choose which wallet pays; the prompt names that currency",
         "  and its price from platform records, which keeps the choice the player's.",
         "",
+        "  A PAYABLE CURRENCY MAY BE ONE THE PLAYER BOUGHT. This shipped on the",
+        "  argument that a payable currency is only ever EARNED: short of Gems or",
+        "  Tickets the answer was to go and play, and neither was sold for money.",
+        "  That is no longer true of Gems. The arcade's own store sells them, and",
+        "  bought Gems stay payable in games (owner decision, 2026-10-06). So",
+        "  where a balance came from protects",
+        "  nobody, and no parent may lean on it. What stands between a game and a",
+        "  balance a player paid for is the rest of this list, and these four are",
+        "  the ones the old argument stood in for:",
+        "",
+        "    - THE CONFIRMATION IS THE PARENT'S, and it costs a gesture. The sheet is",
+        "      drawn in the parent's own chrome from platform records, and only on",
+        "      user activation (below).",
+        "    - A DISMISSAL BACKS OFF, and the confirm control is quiet after paint",
+        "      (both below; the arcade holds the quiet period for 400 ms).",
+        "    - A SHORTFALL IS NEVER A SALE. `insufficient_funds` gets no top-up, no",
+        "      upsell and no way into a store, from the parent or from the game. A",
+        "      game cannot open the arcade's store, and no message here asks for it.",
+        "    - MONEY IS TAKEN ONLY ON THE PAYMENT PROVIDER'S PAGE, which a player",
+        "      reaches through the parent's own chrome. Nothing a frame sends starts",
+        "      a payment or carries a card field.",
+        "",
         "  THE FRAME CHOOSES THE AMOUNT. Not the unit price - but `targetId` x",
         "  `currencySlug` x `quantity` is nevertheless the total, up to ten times the",
         "  most expensive item in a catalog the game itself publishes. Render unit",