@indiegems/gem-web-sdk 7.9.1 → 8.1.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

@@ -353,6 +353,117 @@ one refused orientation, in fullscreen, once they are already the right way roun
 That is best effort (iOS does not implement it, and the native app's webview declines
 it), which is why the panel exists and why it always offers a way past.
 
+**The same declaration decides how a computer or a television shows your game.** Neither is held
+two ways round, so the Arcade reads your phone and tablet rows instead and, for a portrait-only
+game, draws a centred portrait column.
+[Art beside a portrait game](#art-beside-a-portrait-game-on-a-wide-screen-portrait-borders) below
+has the exact rule, and the art you can put beside that column.
+
+## Art beside a portrait game on a wide screen: portrait borders
+
+**You need this only if your game is portrait-only and you want your own art beside it on a
+computer or a television.** On a desktop browser, the Arcade's desktop app or a TV, the Arcade
+draws a portrait-only game as a centred 9:16 column and fills the space either side with its own
+bars. Portrait borders put your art there instead: you publish a named set of images with your
+store page, and your game says which one goes with what is on screen.
+
+### When the Arcade letterboxes a game
+
+**Your store page's `orientations` decide it, and nothing else does.** Declaring borders never
+turns the letterbox on, and there is no desktop orientation to declare. The rule:
+
+1. Take `tablet` if you declared both its `portrait` and its `landscape`; otherwise `phone` if you
+   declared both of its; otherwise stop, and the game is not letterboxed.
+2. The game is letterboxed to portrait when, on that device, `portrait` is `full` or `partial` and
+   `landscape` is `none`.
+
+| `orientations`, each pair portrait / landscape | Letterboxed on a computer or TV |
+| ---------------------------------------------- | ------------------------------- |
+| nothing declared                               | no                              |
+| tablet `full` / `none`                         | yes                             |
+| phone `full` / `none`, no tablet               | yes                             |
+| phone `partial` / `none`, no tablet            | yes                             |
+| phone `full` / `none`, tablet `full` / `full`  | no — the tablet decides         |
+| phone `full` / `none`, tablet `none` / `full`  | no — the tablet decides         |
+| tablet `none` / `full`                         | no                              |
+| tablet `partial` / `partial`                   | no                              |
+| tablet `full` / `partial`                      | no                              |
+
+A phone or a tablet is never letterboxed: it gets the rotate panel from the section above. On a
+computer or TV, a game the rule does not letterbox fills the play area and its borders never show.
+**A store page with borders and orientations that never letterbox uploads with a
+`portrait_borders_unused` warning** — the page is accepted, and the art will not appear anywhere.
+
+### Declaring the borders
+
+Add them to your store page's `media`, one entry per image:
+
+```yaml
+media:
+  portrait_borders:
+    - name: meadow # the first entry is the default
+      src: borders/meadow.jpg
+    - name: alpine
+      src: borders/alpine.jpg
+```
+
+- **Up to 16 entries**, each with a `name` and a `src`. A name is 1 to 40 characters of `a-z`,
+  `0-9`, `_` and `-`, starts with a letter or digit, and is unique on the page.
+- **The first entry is the default.** The Arcade shows it the moment play starts, before your game
+  has said anything, so put first the one most players should see.
+- **16:9, at least 1920×1080; 2560×1440 is ideal.** PNG, JPEG or WebP. An AVIF, GIF or SVG uploads
+  without complaint and then fails the page's processing.
+- **Opaque.** A transparent area shows the Arcade's own bars through it.
+- **Keep the interesting part away from the middle.** The image is scaled to cover the whole play
+  area and centred, and your game covers the centre. How much shows either side changes with the
+  shape of the player's screen — in a window narrower than the column, the art shows above and
+  below instead — so nothing in the art can line up with your game's edge.
+- **Upload with a current `gemctl`.** An older one refuses `portrait_borders` as an unknown key.
+
+### Choosing one from your game
+
+Call `gem.showPortraitBorders` at start-up and on every theme change, with the name of the border
+that goes with what is on screen, and `null` for a theme that has no art:
+
+```js
+const BORDERS = new Set(['meadow', 'alpine']); // the names your store page declares
+
+function applyTheme(id) {
+  document.body.dataset.theme = id;
+  gem.showPortraitBorders(BORDERS.has(id) ? id : null); // null: the Arcade's own bars show again
+}
+```
+
+- **Call it unconditionally.** On a phone, or on a screen where your game is not letterboxed, the
+  Arcade keeps your choice and shows nothing, and nothing tells your game which case it is in — do
+  not look for a signal. `gem.frame.parentSupports('portraitBorders')` says whether this Arcade can
+  paint borders at all, never whether it is painting them now.
+- **It is safe at any time.** Before the connection exists your choice is held and sent when the
+  Arcade connects. A burst of calls — a theme picker previewing on hover — reaches the Arcade as
+  its final value, at most one a second, so it never trips a rate limit. An embedder that paints
+  no borders is not told, and nothing is raised.
+- **The Arcade owns the change.** When and how the image swaps is the Arcade's; you get no
+  acknowledgement and no say in the timing. A game that restores a saved theme just after it
+  starts shows the default for a moment, then its own.
+- **It shows only while your game is playing** — not before play starts, and not while your key
+  art covers the play area.
+- **A string that is not a valid name is refused on your side**, with a console warning, and never
+  sent. The SDK does not trim it, lower-case it or shorten it.
+- **A valid name your page does not declare is ignored**, and the Arcade keeps what it is showing.
+  On the dev and test channels the Arcade's own page logs a console warning naming the value, the
+  channel whose page it looked in, and the names that page declares; on release it says nothing.
+
+### Publishing order and experiments
+
+- **Publish the store page before, or together with, the build that uses a new name.** A build
+  asking for a name its page does not carry yet keeps the current image until the page arrives.
+  Rolling a build back is harmless; rolling the page back can remove a name, and the Arcade then
+  keeps showing what it has.
+- **Every arm of a store-page experiment must carry every name your build uses.** The set comes
+  from the page the player opened, so an arm without a name falls under the rule above.
+- **The borders come from the store page on screen.** To see your dev-channel borders, open your
+  game's store page on the dev channel. `gemctl serve` does not letterbox and shows no borders.
+
 ## An achievement unlock — celebrate it yourself, or declare the Arcade's
 
 By default the Arcade draws no card when a player unlocks one of your game's
@@ -429,8 +540,10 @@ credit for it until you say so.
   entry fields few and ordinary — and never gate first play behind one. A player made to type on a
   remote before they may play mostly does not.
 - **A TV performance budget.** TV-browser SoCs are weak next to any desktop: ship a player-settable
-  render-scale option (render at DPR 1 and upscale), bound memory, assume a fixed 16:9 frame — there
-  is no `orientationchange` rescue coming — and keep your heights `dvh`-safe.
+  render-scale option (render at DPR 1 and upscale), bound memory, assume a fixed frame — 16:9, or
+  a centred 9:16 column when your store page makes you
+  [a letterboxed portrait game](#art-beside-a-portrait-game-on-a-wide-screen-portrait-borders) —
+  with no `orientationchange` rescue coming, and keep your heights `dvh`-safe.
 - **Reduced motion.** TV browsers rarely expose `prefers-reduced-motion`, so the pushed
   `gem.prefs.reducedMotion` is the only signal a TV player has; honor it. It arrives with
   [the prefs the parent pushes](#what-the-parent-says-about-the-session-prefs-pause-and-terminate)
@@ -1016,7 +1129,15 @@ renderer serves all of them.
 | `displayTag`    | The precomposed `Name#0001`                                                                 | `PlayerText` |
 | `avatarIconId`  | The portrait item's id                                                                      | `string`     |
 | `avatarIconUrl` | The portrait's thumbnail                                                                    | `string`     |
-| `badges`        | Equipped badges in display order, each `{ itemId, iconUrl }` — always a list, empty for now | array        |
+| `badges`        | Equipped badges, at most two, in the player's order, each `{ itemId, iconUrl }`             | array        |
+
+**A player chooses what they wear**: a portrait and up to two badges, each an icon they own — one
+an achievement in your game or any other may have awarded them ([achievements.md](achievements.md)
+§1). The portrait arrives as `avatarIconId` and `avatarIconUrl`, and the badges as `badges`, in the
+order the player put them in. `badges` is always a list — empty for a player who wears none, and on
+a row whose identity is withheld — so draw what is there, never pad it to two, and key on `itemId`,
+never on a position. A player can also equip a title, and colours and animations for their name and
+title. The SDK's identity does not carry those, so draw the name in your own style.
 
 **The name and the tag are player-authored, so both are `PlayerText`** on every surface, not only
 some. Convert with `text.toPlain()` where you render, never before.
@@ -1183,6 +1304,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.1.0",
   "description": "postMessage bridge contract between gem-web and browser-playable games",
   "license": "UNLICENSED",
   "type": "module",

package/schema/bridge.v1.json

@@ -590,7 +590,7 @@
           "kind": "array",
           "maxItems": 2,
           "optional": true,
-          "$comment": "Equipped badges in display order — empty until platform achievements equip any, and never more than two. Each is an item id and a thumbnail URL, the same pin caveat as `avatarIconUrl`.",
+          "$comment": "Equipped badges in the order the player arranged them — never more than two, and empty when the player wears none. Each is an item id and a thumbnail URL, the same pin caveat as `avatarIconUrl`.",
           "items": {
             "kind": "object",
             "fields": {
@@ -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",
@@ -2655,6 +2715,47 @@
       "rateLimit": { "perMinute": 120 }
     },
 
+    {
+      "type": "gem.portraitBorders",
+      "direction": "frameToParent",
+      "transport": "port",
+      "$comment": [
+        "Which of the store page's portrait borders the parent paints beside the",
+        "game while it letterboxes a portrait game on a wide screen. `name` is one",
+        "of the names the page declares under `media.portrait_borders`; absent",
+        "means clear the sides to the parent's own bars, for a theme with no art.",
+        "",
+        "A KEY INTO PUBLISHED ART, NEVER THE ART. The images are the store page's,",
+        "served and reviewed like every other store image; the frame chooses only",
+        "which one and when. The parent looks `name` up by exact match in the list",
+        "the page it is showing declares, and never renders it as text or builds a",
+        "URL from it. A name that list does not hold is ignored and the current",
+        "image stays. Transitions, their timing and any minimum dwell are the",
+        "parent's, swaps wait while a trusted overlay is up, and the frame gets no",
+        "acknowledgement.",
+        "",
+        "`name` is a plain bounded string with no format: a border name may carry",
+        "digits and hyphens, which the `code` format refuses. The SDK sends only",
+        "names matching `^[a-z0-9][a-z0-9_-]{0,39}$`, the store page's own rule, and",
+        "a parent checks the same rule on receipt.",
+        "",
+        "STATE, NOT A MOMENT. The SDK holds the game's latest choice until the",
+        "bridge connects and sends at most one a second, latest wins, so a burst",
+        "(a theme picker previewing on hover) delivers its final value well inside",
+        "the limit below.",
+        "",
+        "Gated by `portraitBorders`, which a parent that paints borders advertises",
+        "to EVERY game on every device, whether or not the game declares borders or",
+        "is letterboxed right now. It is never a signal of form factor or letterbox",
+        "state, and the parent answers nothing, so the frame learns nothing about",
+        "how it is being shown."
+      ],
+      "fields": {
+        "name": { "kind": "string", "maxLength": 40, "optional": true }
+      },
+      "rateLimit": { "perMinute": 60 }
+    },
+
     {
       "type": "gem.error",
       "direction": "both",

package/schema/capabilities.public.json

@@ -123,6 +123,12 @@
         "gem.frameStats"
       ]
     },
+    "portraitBorders": {
+      "implemented": true,
+      "gates": [
+        "gem.portraitBorders"
+      ]
+    },
     "engagement": {
       "implemented": true,
       "gates": [
@@ -191,6 +197,15 @@
         "gem.requestShare"
       ]
     },
+    "vibration": {
+      "implemented": true,
+      "gates": [
+        "gem.vibrate",
+        {
+          "namespace": "gem.vibration"
+        }
+      ]
+    },
     "gameMenu": {
       "implemented": true,
       "gates": [