@indiegems/gem-web-sdk 7.5.0 → 7.7.0

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

@@ -187,9 +187,9 @@ try {
 
 `awaitBridge()` resolves when the bridge leaves `waiting` — connected, refused or closed — or at a
 bounded timeout (default 10s), with the state it settled on. **Proceed on every outcome.**
-`connected` is the Arcade; anything else is a boot without a parent, which your game must survive
-anyway. The wait costs nothing when the handshake is quick: it settles the moment the frame
-connects. Unframed it is never answered, because no parent ever pushes one.
+`connected` is a Gem host listening; anything else is a boot with no session, which your game must
+survive anyway. The wait costs nothing when the handshake is quick: it settles the moment the frame
+connects, and at once when the page that framed it is refused.
 
 The measured stakes, from the first game to hit this on an iPhone: listener up at ~300ms, then a
 main-thread block — the parent's offer, queued behind the block, was delivered twenty seconds later
@@ -515,8 +515,8 @@ them**, so the whole migration for a stylesheet is one declaration per edge:
 ```
 
 The `env()` fallback is not decoration. Under a parent that has not sent the message — an older
-arcade, a third-party embedder, your game opened in a plain tab during development — the
-properties are never set and the browser's own answer stands, which is what your game did before.
+arcade or dev host, a third-party embedder — the properties are never set and the browser's own
+answer stands, which is what your game did before.
 Under a parent that has, the variable wins. One line, correct in both worlds. The four names are
 `--gem-safe-top`, `--gem-safe-right`, `--gem-safe-bottom` and `--gem-safe-left`.
 
@@ -538,17 +538,21 @@ 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 on top of it, in the
-**top-left corner** of your frame: a small **Back** tab — the Gem Arcade wordmark — and, beside it,
-the player's wallets (Gems, Tickets, their achievement score) while they are
-[shown](#the-arcades-wallet-show-it-never-draw-it). The cluster stays in the top-left and runs along
-the top row at most about three quarters of the way across on the narrowest phone — but do not
-hard-code a size: read it, as below. Those rectangles of your frame are **reserved**: keep essential
-UI and every touch target out of them.
+On a phone your game is full-bleed, and the arcade keeps one row of its own across the top of it,
+with the middle left open for a centred camera:
 
-**The arcade never takes the right side.** Put your own settings, pause or menu button **top-right**
-— that corner is yours. And **do not put a back arrow of your own top-left**: it would sit under the
-arcade's Back tab, which leaves the game, while yours would mean something else.
+- **Top-left: the Back tab** — the Gem Arcade wordmark, always there. **Do not put a back arrow of
+  your own top-left**: it would sit under the arcade's tab, which leaves the game, while yours would
+  mean something else.
+- **Top-right: the player's wallets** (Gems, Tickets, their achievement score) while your screen
+  [shows them](#the-arcades-wallet-show-it-never-draw-it). Put your own settings, pause or menu
+  button top-right **below** them, at `top: var(--gem-reserved-tr-height, …)` — and when gameplay
+  hides the wallets with `gem.setWalletVisible(false)`, that rectangle shrinks to nothing and your
+  button moves up into the corner on its own.
+
+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
 strip. So `gem.viewport` also carries the rectangles, in the same CSS pixels of your frame, measured
@@ -567,13 +571,21 @@ from its top-left corner:
 reserved rectangles reach in from its two edges. Push the corner's UI clear of it:
 
 ```css
-/* a score in the top-left corner, below the cluster */
+/* settings in the top-right corner, below the wallets — and up in the corner when they are hidden */
+#settings {
+  top: max(var(--gem-safe-top, env(safe-area-inset-top, 0px)), var(--gem-reserved-tr-height, 0px));
+  right: var(--gem-safe-right, 0px);
+}
+/* a score in the top-left corner, below the tab */
 #score {
   top: max(var(--gem-safe-top, env(safe-area-inset-top, 0px)), var(--gem-reserved-tl-height, 0px));
   left: var(--gem-safe-left, 0px);
 }
-/* or a row along the top, starting after it */
-#top-bar { padding-left: var(--gem-reserved-tl-width, 0px); }
+/* or a row along the top, between the two */
+#top-bar {
+  padding-left: var(--gem-reserved-tl-width, 0px);
+  padding-right: var(--gem-reserved-tr-width, 0px);
+}
 ```
 
 All eight are written on every push, `0px` for a clear corner, so a rotation never leaves a stale
@@ -581,9 +593,9 @@ value; they are never set under an embedder that sends no viewport, which is wha
 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.
 
-**Lay out against it whenever it changes.** Shown wallets widen the reserved area beside the tab;
-hiding them shrinks it back to the tab 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.
+**Lay out against it whenever it changes.** Shown wallets reserve the top-right corner; hiding them
+shrinks it to nothing, and only the tab's top-left rectangle is left. A wallet the arcade pops up for
+a moment while they are hidden never reserves anything — it floats over your game and moves nothing.
 
 **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
@@ -764,7 +776,8 @@ and the release checklist checks that it does.
 
 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 Back tab.
+Arcade takes every figure from the platform and draws the wallets itself, 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.**
@@ -780,10 +793,10 @@ pauseMenu.onOpen = () => gem.setWalletVisible(true);
 - **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
-  [reserved area](#the-arcades-own-controls-reserved-areas) beside the Back tab, so lay your menu
-  out against `--gem-reserved-tl-*`; hidden, it shrinks back to the tab. A pop floats over your game
-  and never moves its layout.
+- **Shown wallets take space; a pop does not.** Shown, they reserve the top-right
+  [corner](#the-arcades-own-controls-reserved-areas), so lay your menu out against
+  `--gem-reserved-tr-*` — your settings button sits below them; hidden, the corner is yours again and
+  the same `var()` moves the button up. 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indiegems/gem-web-sdk",
-  "version": "7.5.0",
+  "version": "7.7.0",
   "description": "postMessage bridge contract between gem-web and browser-playable games",
   "license": "UNLICENSED",
   "type": "module",
@@ -31,6 +31,10 @@
       "types": "./dist/server-api.d.ts",
       "import": "./dist/gem-web-sdk.server-api.js"
     },
+    "./function": {
+      "types": "./dist/function.d.ts",
+      "import": "./dist/gem-web-sdk.function.js"
+    },
     "./schema": "./schema/bridge.v1.json",
     "./brand/*": "./brand/*"
   },
@@ -45,6 +49,7 @@
     "docs/*.md",
     "docs/manifest.json",
     "docs/api/*.md",
-    "docs/api/reference.json"
+    "docs/api/reference.json",
+    "CHANGELOG.md"
   ]
 }

package/schema/bridge.v1.json

@@ -894,7 +894,7 @@
         "AMENDED, DELIBERATELY: this message once carried insets only. It now also",
         "carries `reserved`, rectangles of the frame covered by the parent's own",
         "controls floating over the game (a Back tab in a corner, the wallet chips",
-        "shown beside it). An inset can only describe a full-width or full-height band,",
+        "shown in another). An inset can only describe a full-width or full-height band,",
         "and a corner tab expressed as a top inset would take the whole top strip",
         "from a full-bleed game to clear a control a few dozen pixels wide. A",
         "rectangle says exactly which part, and still says nothing about what the",