@indiegems/gem-web-sdk 7.9.0 → 8.0.0

package/docs/vibration.md

@@ -0,0 +1,141 @@
+# Vibration
+
+`navigator.vibrate` does nothing on any iPhone. It does not exist in Safari, in any other iOS
+browser, or in the Gem Arcade iPhone app, and Firefox removed it on every platform. A game that
+calls it vibrates on Android and nowhere else.
+
+`gem.vibration` vibrates wherever the player's device can. It takes the same pattern as
+`navigator.vibrate` and returns the same boolean, so switching is a rename:
+
+```js
+navigator.vibrate(30); // before: Android only
+gem.vibration.vibrate(30); // after: Android, and the Gem Arcade iPhone app
+```
+
+Two rules come before everything else on this page. Both are easy to get wrong.
+
+1. **Read `gem.vibration.available` live, after `awaitBridge()`, every time you need it.** On an
+   iPhone it is `false` until the bridge to the Arcade connects. If you build your settings screen
+   at boot and hide the vibration toggle then, it stays hidden on exactly the device this exists
+   for.
+2. **Never call `navigator.vibrate`**, with or without a guard, and never write a fallback to it.
+   `gem.vibration.vibrate` already calls `navigator.vibrate` itself wherever that works.
+
+## The whole integration
+
+Your game owns its vibration toggle; the Arcade has none. Keep the toggle in
+`gem.deviceSettings`, never in `localStorage`, which every publish of your game wipes.
+
+```js
+await gem.awaitBridge();
+
+// Your settings, kept by the Arcade so they survive your next publish.
+let settings = (await gem.deviceSettings.wait(1_500)) ?? {};
+
+// Build the row when the settings screen OPENS, never once at boot.
+function openSettings() {
+  vibrationRow.hidden = !gem.vibration.available;
+  vibrationToggle.checked = settings.vibration !== false;
+}
+
+vibrationToggle.onchange = () => {
+  settings = { ...settings, v: 1, vibration: vibrationToggle.checked };
+  void gem.deviceSettings.put(settings);
+};
+
+// Check your own toggle before every call. Nothing else: no fallback.
+function onHit() {
+  if (settings.vibration !== false) gem.vibration.vibrate(30);
+}
+```
+
+There is no `available` check before `vibrate`: where vibration is not available, `vibrate` does
+nothing and returns `false`. `available` exists to decide whether to show the toggle.
+
+## What a pattern is
+
+Exactly what `navigator.vibrate` takes. A number is one vibration of that many milliseconds; an
+array alternates vibration and pause, starting with a vibration.
+
+- **`0` or `[]` stops** a pattern that is still playing.
+- **A new call replaces** whatever is still playing.
+- **The pattern is capped**: at most 99 entries, each at most 10 000 ms, and **at most 10 seconds
+  in all**, vibrations and pauses together. A longer pattern is cut short, not refused.
+- **A negative, `NaN` or infinite entry refuses the whole pattern**: `vibrate` returns `false`.
+
+`vibrate` returns `true` when the pattern was accepted, never that a motor moved: the player may
+have vibration switched off in their phone's settings, which your game cannot see.
+
+## Nothing vibrates before the first tap
+
+Browsers allow vibration only after the player has tapped or pressed a key in your game. Before
+that, `vibrate` returns `false` and vibrates nothing, on Android and iPhone alike. So a buzz on
+load, or on a title screen nobody has touched, never plays.
+
+## A cookbook, by feel
+
+On an iPhone, a vibration of 40 ms or less plays as a crisp tap, stronger the longer it is; a
+longer one plays as a continuous buzz. On Android every entry is a buzz of that length.
+
+| Feel | Pattern | Use it for |
+| --- | --- | --- |
+| tick | `10` | a menu cursor moving, a dial clicking |
+| tap | `20` | a button press, a piece placed |
+| hit | `30` to `50` | taking damage, a landing, a collision |
+| heavy | `100` | an explosion, a boss hit; use it rarely |
+| alert | `[200, 100, 200]` | a warning, a timer running out |
+| cancel | `0` | stopping whatever is playing |
+
+Keep hit feedback at about 100 ms or less. Anything longer stops feeling like feedback and starts
+feeling like a phone call.
+
+## Stop on pause
+
+When your game pauses, stop anything still playing:
+
+```js
+onPause: (paused) => {
+  if (paused) gem.vibration.vibrate(0);
+},
+```
+
+The Arcade also stops a running pattern itself when it pauses your game or the player leaves it,
+but a pause your game makes on its own is yours to stop.
+
+## Where it vibrates
+
+| Where the player is | Vibrates? |
+| --- | --- |
+| An Android phone, in the Gem Arcade app or in Chrome | yes |
+| An iPhone, in the Gem Arcade app | yes |
+| An iPhone or iPad, in Safari or any other browser | no: `available` is `false` |
+| An iPad, in the Gem Arcade app | no: an iPad has no vibration motor |
+| Firefox, anywhere | no: `available` is `false` |
+| A desktop or laptop with a mouse | no: `available` is `false` |
+
+A laptop with a touch screen may report `available` as `true` and then vibrate nothing. That is
+harmless; it is why the toggle is your player's to switch off.
+
+## Gamepad rumble is separate
+
+A controller's rumble is `GamepadHapticActuator` (`gamepad.vibrationActuator`), not
+`navigator.vibrate`. It is unaffected by any of this, and `gem.vibration` does not drive it.
+
+## What not to do
+
+- **`navigator.vibrate?.(x)`.** It is still a direct call: it vibrates on Android and silently
+  nowhere else.
+- **`if ('vibrate' in navigator)` to decide whether to show the toggle.** It hides the toggle on
+  every iPhone, where `gem.vibration` works. Use `gem.vibration.available`.
+- **A wrapper that falls back to `navigator.vibrate`.** `gem.vibration.vibrate` already does that
+  where it works, and nowhere else does a fallback do anything.
+- **A user-agent check** to hide the toggle on iOS. Read `available`; it already knows.
+- **Reading `available` once at boot.** It is `false` on an iPhone until the bridge connects.
+- **Vibrating on load or every frame.** Nothing plays before the first tap, and a call every frame
+  is past the limit of 600 a minute: past it, `vibrate` returns `false`.
+- **Hit feedback longer than about 100 ms.**
+- **Keeping the toggle in `localStorage`.** It is gone after your next publish; use
+  `gem.deviceSettings`.
+
+When `vibrate` refuses a call for a reason you can fix (no tap yet, a bad pattern, the limit), the
+SDK says so once a session through your `log` option, which is `console.warn` unless you set it.

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
 
@@ -1152,6 +1183,18 @@ or after an `await`; and **never gate a reward on it**, because your game is tol
 not even whether the player shared.
 [Linking to your game](getting-started.md#linking-to-your-game) is the section.
 
+## If your game vibrates
+
+Not on the list above either. `navigator.vibrate` does nothing on any iPhone, so call
+`gem.vibration.vibrate` instead: it takes the same pattern, returns the same boolean, and vibrates
+wherever the player's device can, the Gem Arcade iPhone app included.
+
+Two things before you reach for it: **read `gem.vibration.available` live, after `awaitBridge()`**,
+to decide whether to show your vibration toggle, because on an iPhone it is `false` until the
+bridge connects; and **never call `navigator.vibrate`**, guarded or not, because the SDK already
+does wherever that works. Your game owns the toggle and keeps it in `gem.deviceSettings`.
+[`vibration.md`](vibration.md) is the page.
+
 ## A decision the player must not make, if your game has one
 
 Not on the list above either: most games trust the browser with everything they do and lose nothing

package/package.json

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

package/schema/bridge.v1.json

@@ -2604,6 +2604,66 @@
       }
     },
 
+    {
+      "type": "gem.vibrate",
+      "direction": "frameToParent",
+      "transport": "port",
+      "$comment": [
+        "Ask the parent to play a vibration pattern on the player's device, where",
+        "the frame cannot: `navigator.vibrate` is undefined in every WebKit (so in",
+        "every iOS browser and the iOS app's WKWebView) and in Firefox 129 and",
+        "later. Gated by the `vibration` capability: sent only to a parent that",
+        "advertised it.",
+        "",
+        "THE SAME VALUE `navigator.vibrate` WOULD HAVE BEEN GIVEN. `pattern` is the",
+        "Vibration API's pattern, already validated and normalized by the SDK:",
+        "alternating on and off durations in milliseconds, starting with on, with",
+        "no trailing pause. An empty array CANCELS a running pattern. A new",
+        "message replaces whatever is still playing.",
+        "",
+        "ONE WAY, AND NOTHING ANSWERS IT. No requestId, and no message travels",
+        "back: the game already has its answer (`gem.vibration.vibrate` returns",
+        "whether the message left the frame), and a reply would tell a game the",
+        "state of the parent's own gates.",
+        "",
+        "WHAT THE PARENT OWES, none of which this schema can enforce:",
+        "",
+        "  REFUSE A TOTAL OVER 10 000 ms. The sum of every entry, on and off, is",
+        "  at most 10 000. The SDK truncates to that before sending; a message",
+        "  over it was written by hand, and is refused whole, never clamped.",
+        "",
+        "  GATE ON THE FRAME'S OWN ACTIVATION, NOT THE PAGE'S. The player's Play",
+        "  click has already activated the parent document before any game runs,",
+        "  so the parent's sticky activation proves nothing about the game. Drop",
+        "  the message until a tap inside this frame document has activated it.",
+        "",
+        "  DROP IT WHILE THE GAME CANNOT BE SEEN: the page hidden, or the game",
+        "  paused behind the parent's own menu. Cancel a running pattern on pause",
+        "  or hide.",
+        "",
+        "  SEND NOTHING BACK. No outcome, no acknowledgement, and no error for a",
+        "  refusal - not for an unadvertised type, a malformed or oversized",
+        "  pattern, or the rate limit - so a game cannot read the parent's gates",
+        "  or its limiter.",
+        "",
+        "Not an Arcade surface: the parent draws nothing and the player sees",
+        "nothing of the platform's. It is a device effect the game would have had",
+        "from `navigator.vibrate` on a Chromium browser."
+      ],
+      "fields": {
+        "pattern": {
+          "kind": "array",
+          "maxItems": 99,
+          "$comment": "At least 0 entries (an empty array cancels) and at most 99, Chromium's bound. The total is at most 10 000 ms, which the parent checks: a sum has no field shape.",
+          "items": { "kind": "int", "min": 0, "max": 10000 }
+        }
+      },
+      "rateLimit": {
+        "perMinute": 600,
+        "$comment": "Bounds a BUGGY game - one that vibrates every frame - at ten a second. NOT a security control: a hostile game posts on the port it holds rather than calling the SDK. What bounds the motor is the parent's native throttle and its duty-cycle budget."
+      }
+    },
+
     {
       "type": "gem.frameStats",
       "direction": "frameToParent",

package/schema/capabilities.public.json

@@ -191,6 +191,15 @@
         "gem.requestShare"
       ]
     },
+    "vibration": {
+      "implemented": true,
+      "gates": [
+        "gem.vibrate",
+        {
+          "namespace": "gem.vibration"
+        }
+      ]
+    },
     "gameMenu": {
       "implemented": true,
       "gates": [