@indiegems/gem-web-sdk 7.9.0 → 7.9.1

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

@@ -571,73 +571,117 @@ 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 cluster of its own over it, in the
-**top-right corner**:
+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 corner itself, always there. It opens
+- **The menu button**, in the **top-right corner**, always there. It opens
   [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), to the left of it, while your
-  screen [shows them](#the-arcades-wallet-show-it-never-draw-it). When gameplay hides them with
-  `gem.setWalletVisible(false)`, the cluster shrinks to the menu button alone.
+- **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,
+  and still taps the Arcade takes.
 
-**The top-left corner is yours.** Put your own back or home button there — the one that moves around
-_inside_ your game, back to your level select or your title screen. **Put no settings, pause-menu or
-burger button of your own top-right**: your settings open from the Arcade's menu, and a second
-button under the Arcade's would mean something else in every game.
+**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.
+
+**Put no settings, pause-menu or burger button of your own top-right**: your settings open from the
+Arcade's menu, and a second button under the Arcade's would mean something else in every game.
+
+**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.
 
 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.
 
-An inset cannot say that — as a top inset, a tab a few dozen pixels wide would take your whole top
+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:
+from its top-left corner — one per wallet shown, and one for the menu button:
 
 ```json
 {
   "insets": { "top": 47, "right": 0, "bottom": 34, "left": 0 },
-  "reserved": [{ "x": 8, "y": 51, "width": 104, "height": 34 }]
+  "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 }
+  ]
 }
 ```
 
 **The SDK turns them into one pair of custom properties per corner**, written beside
 `--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. Push the corner's UI clear of it:
+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:
 
 ```css
-/* your back button in the top-left corner, which the arcade leaves clear */
+/* 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 */
 #back {
   top: var(--gem-safe-top, env(safe-area-inset-top, 0px));
   left: var(--gem-safe-left, 0px);
 }
-/* a score in the top-right corner, below the arcade's cluster */
-#score {
-  top: max(var(--gem-safe-top, env(safe-area-inset-top, 0px)), var(--gem-reserved-tr-height, 0px));
-  right: var(--gem-safe-right, 0px);
-}
-/* or a row along the top, stopping short of it */
-#top-bar {
-  padding-left: var(--gem-reserved-tl-width, 0px);
-  padding-right: var(--gem-reserved-tr-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 {
+  top: max(
+    var(--gem-safe-top, env(safe-area-inset-top, 0px)),
+    var(--gem-reserved-tl-height, 0px),
+    var(--gem-reserved-tr-height, 0px)
+  );
 }
 ```
 
-All eight 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. A rectangle belongs to the corner its centre lies nearest to. For a HUD laid out
-from script, read `gem.viewport.reserved` — `[]` when nothing is covered.
+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).
 
-**Lay out against it whenever it changes.** Shown wallets widen the top-right rectangle; hiding them
-shrinks it to the menu button alone. A wallet the arcade pops up for a moment while they are hidden
-never reserves anything — it floats over your game and moves nothing. Read every corner, not only the
-one this page names today: `--gem-reserved-tl-*` is `0px` now, and a layout that honours it anyway
-is right under any embedder.
+```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);
+```
+
+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.
 
 **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
-`--gem-safe-top` — past the bottom of the cluster. That game keeps working, at the cost of a full-width
+`--gem-safe-top` — past the bottom of the row. That game keeps working, at the cost of a full-width
 band; upgrading gives the band back.
 
 ## Which store-page experiment brought this player in: cohorts
@@ -854,38 +898,25 @@ 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: show it, never draw it
+## The Arcade's wallet: always shown, 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, beside its menu button in
-the top-right corner of your frame on a phone.
-
-**They are shown unless your game hides them.** A game that does nothing has every wallet on show
-the whole time. The one rule: **hide them during gameplay, show them on your menus.**
-
-```js
-level.onStart = () => gem.setWalletVisible(false);
-pauseMenu.onOpen = () => gem.setWalletVisible(true);
-```
-
-- **While hidden, the Arcade still pops a wallet up** for a moment when something happens to it —
-  a reward you cued with `gem.cueReward`, a spend, a landing, a daily-maximum note, a score change
-  — then hides it again. Your state never cancels that, so a reward mid-level still shows.
-- **It is screen state, not a toggle.** Each call is the whole answer and replaces the last. Call it
-  as often as you like: before the Arcade connects the state is held and sent when it does, and
-  again after any reconnect; a repeat of the current state is not re-sent.
-- **Shown wallets take space; a pop does not.** Shown, they widen the top-right
-  [reserved area](#the-arcades-own-controls-reserved-areas) beside the menu button, so lay your
-  screen out against `--gem-reserved-tr-*`; hidden, it shrinks back to the button alone. A pop floats
-  over your game and never moves its layout.
-- **Narrowing is optional.** On a screen that sells in one currency — a ticket store — you may show
-  only that one: `gem.setWalletVisible(true, { only: ['ARCADE_TICKETS'] })`, with `'score'` for the
-  achievement score. Use it only there; leaving it out shows every wallet, which is always safe.
-- **Where the Arcade docks its wallets beside your frame** — a desktop page — they are always on
-  show, and this changes nothing. Call it anyway; the same code is right everywhere.
-- **`false` means nobody is listening** — no connection yet, or an embedder that draws no wallet.
-  Do nothing in its place.
+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
+[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.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.
 
 ## No accidental text selection
 

package/package.json

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