@indiegems/gem-web-sdk 7.9.1 → 8.0.0

package/docs/friends.md

@@ -11,9 +11,10 @@ for (const friend of page.friends) {
 }
 ```
 
-That read, and one ask — [sending a friend a challenge](#friend-challenges), which the Arcade
-confirms with the player and sends itself — are the whole surface. The boundary around them is the
-thing to understand before you design against it.
+That read, one ask — [sending a friend a challenge](#friend-challenges), which the Arcade
+confirms with the player and sends itself — and [reading the challenges the player
+received](#reading-the-challenges-a-player-received) in your game are the whole surface. The
+boundary around them is the thing to understand before you design against it.
 
 ## What the read is, and is not
 
@@ -31,7 +32,8 @@ Everything else about the friend graph stays on the Arcade, by design:
   platform screens with the player's own account credential — a game frame holds a play token,
   and a play token cannot touch the graph. Sending a [friend challenge](#friend-challenges) does
   not touch it either: your game asks, and the Arcade sends only after the player confirms in its
-  own sheet.
+  own sheet. The one write a play token has is marking one of the player's own friend challenges
+  answered (`gem.friends.markAnswered`), which records that they played it and tells nobody.
 - **No states.** Pending requests, blocks and relationship history do not appear. An accepted
   friend appears; everyone else does not exist on this surface.
 - **No presence, no invites.** Nothing here says who is online or delivers an invite — an invite
@@ -174,15 +176,88 @@ existing `instanceof GemApiError` handling keeps working:
 
 ### When a challenge launches your game
 
-The friend's tap opens your game with the challenge's params in its launch query, read exactly as
-[your own launch keys](getting-started.md#linking-to-your-game) are: the param keys are
-launch-query keys, and every value arrived in a link, so validate it the same way. The Arcade adds
-one key of its own, `gemChallenge`, which is the platform's, not yours: never parse it. The SDK
-method that reads it ships in a later release.
+The friend's tap opens your game with the challenge's params in its launch query, and with one key
+of the platform's own, `gemChallenge`. **Do not read either from the URL to find the challenge.**
+Ask the SDK:
+
+```js
+const challenge = await gem.friends.launchedChallenge();
+if (challenge?.template === 'beat_code_jar') {
+  // Check every param before it does anything, as you would a launch key: the template
+  // constrained it when it was sent, but your config may have changed since.
+  const jar = typeof challenge.params.jar === 'string' && /^[A-Z0-9]{7}$/.test(challenge.params.jar)
+    ? challenge.params.jar
+    : null;
+  if (jar) {
+    startJar(jar, {
+      from: challenge.from, // who sent it, from the platform's records
+      replay: challenge.answeredAt !== undefined, // already played once
+    });
+  }
+}
+```
+
+`launchedChallenge()` reads `gemChallenge` once, when `createGem` runs — so cleaning your URL
+with `history.replaceState` afterwards changes nothing — and looks the challenge up on the
+platform. The order matters the other way too: call `createGem` before you clean the URL, or
+leave `gemChallenge` in place, because a key removed before `createGem` runs is never seen and
+`launchedChallenge()` resolves `null` with no error. You get the sender as a [friend row](#what-the-read-is-and-is-not), the template key and
+the params exactly as they were sent.
+
+It **resolves `null`**, never rejects, for every launch that is not this player's challenge in
+this game: no `gemChallenge` key, a value that is not a challenge id, a link naming someone
+else's challenge, one from another game or channel, and every guest launch. Treat `null` as an
+ordinary launch. Only a real failure — the platform unreachable, a context with no player —
+rejects.
+
+**Never put a name in a param, and never read one out.** A param key like `by=`, `from=` or
+`name=` is forbidden: the sender is `challenge.from`, resolved by the platform, and a name in a
+param is one nobody checked — your game would render whatever the sending client put there.
 
 **A relaunch replays the same challenge.** When the player presses Play again in the Arcade, it
-reuses the launch query, so the same params arrive again. Make answering a challenge idempotent:
-a second run of the same challenge is a replay, not a new one.
+reuses the launch query, so the same challenge comes back. Tell a replay from a first attempt by
+`answeredAt`, and make answering idempotent.
+
+### Marking a challenge answered
+
+When the attempt the challenge asked for is over — won or lost — mark it:
+
+```js
+await gem.friends.markAnswered(challenge.id);
+```
+
+It is idempotent: a challenge keeps the first time it was answered, and a second call changes
+nothing. It tells the sender nothing — there are no read receipts — so it is your game's own
+record, read back as `answeredAt` on every later read. It rejects `not_found` for an id that is
+not one of this player's challenges in this game and channel (one answer for unknown and
+someone else's), and `invalid`, before anything is sent, for a value that cannot be a challenge
+id at all.
+
+### Reading the challenges a player received
+
+`gem.friends.inbox()` lists the friend challenges this player holds **in this game, on this
+channel**, in every state:
+
+```js
+let page = await gem.friends.inbox();
+renderChallenges(page.challenges);
+while (page.nextCursor) {
+  page = await gem.friends.inbox({ cursor: page.nextCursor });
+  renderChallenges(page.challenges);
+}
+```
+
+- **Answered challenges are included, and sort last**; within each part, newest first. Filter on
+  `answeredAt` if you only want the open ones.
+- **A guest's page is empty**, not a refusal — a guest is never sent a challenge. Build the screen
+  for the empty state first.
+- **Paged like the friends list**: default 50, at most 200, an opaque cursor passed back verbatim.
+  A player holds at most 200 friend challenges across every game, so one max-size page is all of
+  them.
+- `openedAt` is when the player pressed Play on it in the Arcade. There is no "seen" time: that is
+  the Arcade's, not your game's.
+
+For the challenge this launch carried, use `launchedChallenge()` rather than searching the inbox.
 
 ## Inspecting a player: game profiles
 

package/docs/getting-started.md

@@ -50,7 +50,7 @@ either way.
 ```jsonc
 // package.json
 "dependencies": {
-  "@indiegems/gem-web-sdk": "7.9.1"
+  "@indiegems/gem-web-sdk": "8.0.0"
 }
 ```
 
@@ -342,8 +342,11 @@ That is the whole contract for your own keys. The bridge carries no launch messa
 has no API for them: the arcade does the forwarding, so a build you published on any SDK version
 gets it without a code change. The one key that is not yours is the platform's `gemChallenge`
 (below), which belongs to [friend challenges](friends.md#friend-challenges): never define it, and
-never parse it yourself. The SDK will read it for you, and that is the only launch key it will
-ever read: the method ships in a later release, and until then a game has nothing to do with it.
+never parse it yourself. The SDK reads it for you — `gem.friends.launchedChallenge()` answers the
+challenge it names, or `null` — and that is the only launch key it will ever read. It is read once,
+when `createGem` runs, so cleaning your URL afterwards does not lose it. Call `createGem` before
+you clean the URL, or leave `gemChallenge` in place: a key removed before `createGem` runs is never
+seen, and `launchedChallenge()` then resolves `null` with no error.
 
 What reaches the frame:
 
@@ -365,9 +368,10 @@ What reaches the frame:
   letter, so the arcade keeps that space for itself.
 
 - **One platform key.** `gemChallenge` does reach the frame — the arcade adds it when a player
-  opens a friend challenge — but it is the platform's, not yours. Do not define a key of that
-  name, and treat every key beginning with `gem` as reserved: a friend-challenge template refuses
-  a param named that way.
+  opens a friend challenge — but it is the platform's, not yours: read the challenge with
+  `gem.friends.launchedChallenge()`, never from the URL. Do not define a key of that name, and
+  treat every key beginning with `gem` as reserved: a friend-challenge template refuses a param
+  named that way.
 - **Bounded.** At most 16 parameters. A key is a letter followed by up to 63 letters, digits,
   `_` or `-`. A value is at most 512 characters with no control or format characters. An entry
   that breaks a rule is dropped on its own; the rest of the link still arrives.

package/docs/manifest.json

@@ -33,8 +33,8 @@
     },
     {
       "file": "changelog.md",
-      "sha256": "8a2e021addc2980433e722ba6ca2c7f5fa81cb8eac921e0bda28e44e3484d09d",
-      "updated": "2026-10-05T17:22:40Z"
+      "sha256": "37bae4170e89587ee8c498891fa2dac008f09fb01fcfbcf87b1310340d2cfc62",
+      "updated": "2026-10-06T19:43:21Z"
     },
     {
       "file": "cross-promotion.md",
@@ -58,8 +58,8 @@
     },
     {
       "file": "friends.md",
-      "sha256": "1c0a427a4e86d4c0e48faad9a80bdef9d528a60485b5aadee18d7759d9051e63",
-      "updated": "2026-10-01T16:38:53Z"
+      "sha256": "002e6f61050cd188baa0b9b056c9ceaccd96e653361e0c28646baa5632e525df",
+      "updated": "2026-10-06T16:37:15Z"
     },
     {
       "file": "game-economy-tutorial.md",
@@ -68,8 +68,8 @@
     },
     {
       "file": "getting-started.md",
-      "sha256": "3c38e5b14c78b70b107d5e5b5499fa9340975d602642a8eb91f2dd969d1b605b",
-      "updated": "2026-10-05T17:22:40Z"
+      "sha256": "77ce7b2223d18267ac3ca2f49e09481752539f2674910e2cb12832825c945000",
+      "updated": "2026-10-06T19:43:21Z"
     },
     {
       "file": "inventory-and-catalogs.md",
@@ -113,33 +113,38 @@
     },
     {
       "file": "saving-player-progress.md",
-      "sha256": "e556b9ef033b0ae611a7d136da3422c8145367939848eda193ab2674087c884f",
-      "updated": "2026-10-01T18:37:21Z"
+      "sha256": "08778cccc7d7a9a26a005a070bb2cc98784752ebec9dfce9873ef3d4e674e1e0",
+      "updated": "2026-10-05T16:53:25Z"
     },
     {
       "file": "server-bundles.md",
-      "sha256": "13f5846ad8ee3d27e83916b8d95b4d3fdfcbeb85f94e095cc0c04e14dc2577b2",
-      "updated": "2026-10-05T17:22:40Z"
+      "sha256": "49f51b37e969b6120d2df6cf6d2f33d2856c1602fd7504a7b308a9ea21c9b502",
+      "updated": "2026-10-06T19:43:21Z"
     },
     {
       "file": "serverless-functions-js.md",
-      "sha256": "86b0f9f0b742a662ebb78b1538cbbc399309725faf22f46f613b63b5e0864082",
-      "updated": "2026-10-02T17:17:29Z"
+      "sha256": "8d5bda66dfebd93e80fe97b2f09c0651c26dc83b16827bdae7aa25f198f89e0b",
+      "updated": "2026-10-03T00:26:43Z"
     },
     {
       "file": "serverless-functions.md",
-      "sha256": "c830daf736713744909700bf93ff5ba139b8b5d8ad3c2b4e057ca813fc6179f7",
-      "updated": "2026-10-02T18:52:17Z"
+      "sha256": "1edaa60a8aaf20499f24d661f169790cacfdb11c26529735a93e5b7b996e5432",
+      "updated": "2026-10-03T00:26:43Z"
     },
     {
       "file": "trading-and-gifting.md",
       "sha256": "d7ee3c85540ab8aae29988c16a76bee3ba03cc66b10d2faaf5cd7210a80a0544",
       "updated": "2026-08-26T03:27:49Z"
     },
+    {
+      "file": "vibration.md",
+      "sha256": "3608da64abcef207cf0875f9d32f3aed88d4fb23512bc70d0a9684a570263a44",
+      "updated": "2026-10-06T17:36:25Z"
+    },
     {
       "file": "what-a-game-must-do.md",
-      "sha256": "f44c1fd73678b1b569c59bc94bb55cfa2bdb957d798f5985ea5b3024865ed4a6",
-      "updated": "2026-10-04T19:51:47Z"
+      "sha256": "436a8b61c46a3de6c7d5db65293bdcd17426412742dffd21f976bf87d1418d88",
+      "updated": "2026-10-06T17:36:25Z"
     }
   ]
 }

package/docs/saving-player-progress.md

@@ -436,6 +436,47 @@ game, and a key you experiment with on `dev` cannot break a shipped build.
 | a difficulty, a control scheme, a level counter | `gem.me.settings` — a string per key | yes |
 | a volume, a quality preset, a dismissed tip | `gem.deviceSettings` — one object per device | **no** |
 
+## Starting over as a new player while you test
+
+Testing a first launch, a tutorial or a new player's economy means getting your own account
+back to nothing on your game. Do not write code for it. A throwaway serverless function, or a
+reset button you mean to remove later, is the workaround this replaces. gemctl does it, on
+`dev` or `test`, for the account you are signed in as:
+
+```bash
+gemctl support reset --player me --channel dev --reason "fresh tutorial run"
+```
+
+`--channel test` works the same way. `--reason` is required and is kept on the audit record, so
+say why in a few words, with no personal data or tokens. Run it from your project's directory,
+or add `--game <game-id>`.
+
+The order matters, and two of the steps are the ones people skip:
+
+1. **Close the game first.** A running game still holds the old state, and its next autosave
+   writes it straight back over the reset.
+2. **Run the reset.**
+3. **Clear the site data of the page the game runs in, with the game still closed.** That is
+   the Arcade, or the page `gemctl serve` opened, not the game's own origin. `gem.deviceSettings`
+   lives in that page's storage on this device, and no reset reaches it. Skip this and the old
+   volume, quality and dismissed tips come back. Clearing the Arcade's site data also signs you
+   out of it and clears the device settings of every game you have played there on this device;
+   the page `gemctl serve` opened holds only the game you are serving.
+4. **Reopen the game.** It should see what a new player sees: `null` from
+   `gem.me.saves.get`, an empty `gem.me.settings.list()`, and `null` device settings.
+
+The reset clears this player's state **in this game, on that one channel**: saves,
+`gem.me.settings`, inventory and progressions, and the rest of what the game keeps for them.
+It does not touch your other channels, your other games, achievements, or your Gems and
+Tickets. Your purchases and what you paid stay on record, but an item a purchase delivered on
+that channel is cleared with the rest, and the answer lists those purchases.
+`gemctl support reset --help` has the full list, and the answer names whatever it left alone.
+
+**It never runs on `release`.** gemctl refuses before sending anything, and so does the
+platform. It is a tool for testing your own game, not something a game ships. A "New game" or
+"Reset progress" button for players is game code: it overwrites or clears the player's slots
+with `gem.me.saves` and their keys with `gem.me.settings`, as described above.
+
 ## What the platform already does with these, so you do not
 
 **A player's erasure covers their saves.** When an account is erased the stored payloads go with

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

package/docs/serverless-functions-js.md

@@ -33,8 +33,9 @@ message and the stack go to the platform's log for the invocation, never to the
 `handleJson` whose input is not JSON, or whose return value JSON cannot carry, fails the same way.
 
 **`console.*` reaches the invocation's log** at the matching level (`debug`, `info`, `warn`,
-`error`); `console.log` and every other method log at `info`. As with a component's `log`, nothing
-reads it back to you: the invocation id is what you quote about one call.
+`error`); `console.log` and every other method log at `info`. As with a component's `log`,
+`gemctl function logs` reads it back for a call on `dev`, and a call on `test` or `release` keeps
+no line.
 
 ## 2. Writing one
 

package/docs/serverless-functions.md

@@ -81,7 +81,7 @@ everything a function can reach:
 | `call-api`      | One request to the platform API, made **as your game's server**: a method, a `/v1/` path and a JSON body, and nothing else |
 | `download-link` | A save's contents, fetched from the download link the save's record carries                                                |
 | `upload-link`   | A save's new contents, sent to the upload link the platform issued for them                                                |
-| `log`           | A line kept on the platform under this call's invocation id, cut at 1 KiB                                                  |
+| `log`           | A line kept 24 hours under this call's invocation id, on `dev` only, cut at 1 KiB                                          |
 | `random-bytes`  | Randomness. The function has no other source                                                                               |
 | `now-ms`        | Unix time in milliseconds. The function has no other clock                                                                 |
 
@@ -120,9 +120,9 @@ Anything that changes several players at once — settling a match, trading betw
 granting a whole room its rewards — is your **game server's** job, or the job of a function your
 server calls, which is not bound to a player.
 
-**`log` is not a debugger.** What it writes stays on the platform under the call's invocation id,
-and no command reads it back to you. The invocation id is what you quote when you ask the platform
-team about one call.
+**`gemctl function logs` reads back what `log` wrote** (section 7), with a line saying how each
+call ended — but only for a call on `dev`, and only for 24 hours. A call on `test` or `release`
+keeps no line, so to see what a tester or a player hit, make the same call on `dev`.
 
 **A function cannot call a function.** `call-api` to `/v1/functions/invoke` is refused with
 `function_cannot_invoke`.
@@ -732,8 +732,10 @@ It reports:
 - `function_message`: your `Err` text, on a `function_error`;
 - `reason`: on a `function_failed`, which limit or fault ended the call;
 - `round_trip_ms`: measured by gemctl, from sending the call to the last byte back;
-- `invocation_id`: what the platform files the call under. **Keep it.** It is the only handle on
-  the platform's side of one call, including whatever the function passed to `log`.
+- `invocation_id`: what the platform files the call under. **Keep it.** It is what you pass to
+  `--invocation-id` to read that call's lines, and what you quote when you report the call;
+- `logs`: on a `test` or `release` call that reached your function, that it left no log lines. A
+  `dev` call that reached it prints the `gemctl function logs` command that reads its lines instead.
 
 Anything but `returned` exits 1.
 
@@ -744,6 +746,48 @@ If the call is refused before anything is invoked, the problem is your sign-in:
 be a developer on the game, `test` needs a grant on it, and `release` needs a game your account may
 play.
 
+### Reading what it logged
+
+`gemctl function logs` reads what your function wrote with `log`, newest first, with one closing
+line per call saying how it ended.
+
+```bash
+gemctl function logs --invocation-id <invocation-id>   # one call: what it logged, how it ended
+gemctl function logs --outcome error                   # every call whose handle returned Err
+gemctl function logs --level warn                      # what your function warned about
+```
+
+⚠️ **Only a call on `dev` leaves lines.** A call on `test` or `release` leaves none, so there is
+no channel to choose and nothing here shows what a tester or a player hit. Make the same call on
+`dev`, with the input that failed, and read that.
+
+Each row is one of two kinds, and both carry the call's `invocation_id` and its `caller`, `player`
+or `game_server`:
+
+- **A line your function logged**: its `level` and its `message`.
+- **The closing line**: `outcome` is `ok`, `error`, `timeout`, `cpu_exceeded` or `failed`, with the
+  call's `wall_ms` and `cpu_ms`. On `error`, `message` is your `Err` text. On `failed`, `reason`
+  says what ended the call, and when your own code trapped, `message` is the trap's message.
+
+Newest first means a call's closing line comes before what it logged. **A call's logging is
+capped**: once it reaches its per-call log limit, that `log` call and every later one go
+unrecorded, and the closing line's `dropped_log_lines` says how many. A log that stops part-way
+with a nonzero count means your function logged too much, not that it went quiet.
+
+`--invocation-id`, `--level` (`debug`, `info`, `warn` or `error`) and `--outcome` narrow the page.
+`--level` picks what your function logged and `--outcome` picks closing lines, so the two cannot be
+combined: to see everything a failed call logged, pass its invocation id. The window is the last 24
+hours unless `--start-ns` and `--end-ns` (Unix nanoseconds) narrow it, and a full page ends with a
+hint carrying `--cursor` for the next, older one. There is no follow mode.
+
+**An empty page does not prove your function was not called.** Lines take a few seconds to arrive
+and are kept for 24 hours. A call the platform refused before your function ran leaves none — a bad
+credential, a malformed request, a channel serving nothing, a full pool, a component that could not
+be downloaded — and its `invoke` answer is its only record.
+
+Every `message` was written by your function's code, and any member of your game's team can read
+it. Log ids, not anything personal about a player.
+
 ## 8. When a call is refused
 
 Every answer from a call that reached your function carries an invocation id: success,
@@ -766,7 +810,9 @@ the last column: it is `true` exactly where this table says to retry.
 | `403 forbidden`                                            | The call carried an account sign-in rather than a game-scoped or game-server token                        | Call from your game or its server, or through `gemctl function invoke` |
 
 A `trap` is a panic, an `unreachable`, an out-of-bounds access or a stack overflow, and no stack
-trace comes back with it. The other three reasons are the limits in section 2.
+trace comes back with it. On `dev`, the call's closing line in `gemctl function logs` carries the
+trap's message when your own code trapped (section 7). The other three reasons are the limits in
+section 2.
 
 Publishing has its own refusals, and nothing is stored when one happens:
 

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

@@ -1183,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.1",
+  "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",