@indiegems/gem-web-sdk 7.9.1 → 8.1.0

package/docs/api/api-reference-game.md

@@ -1,6 +1,6 @@
 # The browser surface — API reference
 
-Generated from `@indiegems/gem-web-sdk/sdk` v7.9.1. Every symbol below links to its page on the Gem Arcade developer site.
+Generated from `@indiegems/gem-web-sdk/sdk` v8.1.0. Every symbol below links to its page on the Gem Arcade developer site.
 
 `@indiegems/gem-web-sdk/sdk` is the one import a game writes, wherever its code runs. `@indiegems/gem-web-sdk/game` exports exactly the symbols on this page and nothing else, for a build that wants only this half.
 
@@ -247,6 +247,47 @@ check that a funnel you declared names events you are actually sending.
 
 Absent when your game declares none.
 
+## GameConfig.rewarded_placements
+
+[GameConfig.rewarded_placements](https://gemarcade.com/developer/api/game#gameconfig-rewarded_placements)
+
+```ts
+rewarded_placements?: SnapshotRewardedPlacement[]
+```
+
+Your rewarded placements — what pressing a rewarded button grants. An
+array, one row per placement, each naming itself in `placement`, with its
+`grants`, the caps the platform enforces on it (`max_per_day`,
+`cooldown_seconds`, `max_held`) and what happens where no ad serves
+(`without_ads`).
+
+Read it to LABEL your button — "+1 Revive" — never to decide a reward. A
+grant is an `item_grant`, with a `quantity` of the item its
+`item_definition_id` names, or a `currency_grant`, with an `amount` of the
+currency its `currency_id` names; the word on the button is that
+definition's `display_name`, from [GameConfig.item](https://gemarcade.com/developer/api/game#gameconfig-item) or
+[GameConfig.currency](https://gemarcade.com/developer/api/game#gameconfig-currency):
+
+```js
+const row = config?.rewarded_placements?.find((p) => p.placement === 'classic_revive');
+const grant = row?.grants[0];
+const label =
+  grant?.type === 'item_grant'
+    ? `+${grant.quantity} ${config.item(grant.item_definition_id)?.display_name ?? ''}`
+    : grant?.type === 'currency_grant'
+      ? `+${grant.amount} ${config.currency(grant.currency_id)?.display_name ?? ''}`
+      : undefined;
+```
+
+Whether an ask grants anything is the platform's decision, made against
+this config server-side; the grant lands on your game's inventory, and
+re-reading `gem.me.inventory` is the only way to learn that it did. Whether
+the button could pay right now is [AdsApi.rewardedStatus](https://gemarcade.com/developer/api/game#adsapi-rewardedstatus).
+
+Absent when your game declares none.
+
+**Guides.** [cross-promotion](https://gemarcade.com/developer/docs/cross-promotion)
+
 ## GameConfig.version
 
 [GameConfig.version](https://gemarcade.com/developer/api/game#gameconfig-version)
@@ -2934,6 +2975,11 @@ No reason is given for a `no_ad`, and one will never be added: a reason would
 tell your game something about the player — an age, a consent state, a
 subscription — that game code is deliberately not told.
 
+The one thing you can learn is about **your own economy**, and not from this
+answer: [AdsApi.rewardedStatus](https://gemarcade.com/developer/api/game#adsapi-rewardedstatus) reports your own declared rewarded caps
+as the platform holds them (a platform-wide per-placement maximum, where one
+is set, can lower a cap). It never reports anything about the player.
+
 ## AdOutcome
 
 [AdOutcome](https://gemarcade.com/developer/api/game#adoutcome)
@@ -3009,6 +3055,160 @@ startNextLevel();
 
 **Guides.** [cross-promotion](https://gemarcade.com/developer/docs/cross-promotion)
 
+## AdsApi.rewardedStatus
+
+[AdsApi.rewardedStatus](https://gemarcade.com/developer/api/game#adsapi-rewardedstatus)
+
+```ts
+rewardedStatus(placement: string): Promise<RewardedStatus>
+```
+
+Whether a rewarded placement could pay right now, so you can decide whether
+to draw its button. **It never says whether an ad will play.**
+
+The answer comes from your own `rewarded_placements` config — its daily
+cap, cooldown and `max_held` — applied to this player's use of it, as the
+platform holds them. Nothing in it describes the player. `grantable: true`
+means the platform would grant if an ad is watched or, where no ad serves,
+under the placement's `without_ads: grant`; a player can still press the
+button and get `no_ad`, for reasons your game is not told.
+
+NOTHING REJECTS, like everything else on `gem.ads`. Without a play token,
+when the read fails or takes longer than ten seconds, or for a `placement`
+outside the grammar [AdRequest.placement](https://gemarcade.com/developer/api/game#adrequest-placement) documents, it resolves not
+declared and not grantable, with no `resetsAt`, and the reason goes to your
+`onError` handler.
+
+It is a read of the platform, so call it when you draw the button — on a
+results or death screen — not every frame. Calls for one placement that
+overlap share one request. Draw the rest of the screen first rather than
+holding it on this answer.
+
+⚠️ It grants nothing and reserves nothing. The reward is granted by the
+platform when the player asks with `requestAd`; re-read `gem.me.inventory`
+after that ask settles, whatever it settled as.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `placement` | `string` | A placement your `rewarded_placements` config declares. |
+
+**Returns.** The placement's state. Always resolves; never rejects.
+
+```ts
+const status = await gem.ads.rewardedStatus('classic_revive');
+reviveButton.disabled = !status.grantable;
+if (status.nextEligibleAt !== undefined) {
+  reviveButton.title = `Back at ${new Date(status.nextEligibleAt).toLocaleTimeString()}`;
+}
+```
+
+**Guides.** [cross-promotion](https://gemarcade.com/developer/docs/cross-promotion)
+
+## RewardedStatus
+
+[RewardedStatus](https://gemarcade.com/developer/api/game#rewardedstatus)
+
+```ts
+interface RewardedStatus
+```
+
+What [AdsApi.rewardedStatus](https://gemarcade.com/developer/api/game#adsapi-rewardedstatus) answers: the state of one rewarded
+placement for this player, from your own declared caps.
+
+Every figure comes from **your** `rewarded_placements` config — `max_per_day`,
+`cooldown_seconds`, `max_held` — applied to this player's use of it, as the
+platform holds them. The platform can hold a placement's daily cap below what
+you declared, never above it. Nothing here describes the player.
+
+⚠️ **It never says whether an ad will play.** Whether one does depends on
+things your game is deliberately not told. A player can see your button,
+press it, and get `no_ad`: read that `no_ad` like any other, and never guess
+a reason.
+
+## RewardedStatus.declared
+
+[RewardedStatus.declared](https://gemarcade.com/developer/api/game#rewardedstatus-declared)
+
+```ts
+readonly declared: boolean
+```
+
+Whether this channel's published config declares the placement.
+
+`false` for a placement your config does not name, a config that is not
+promoted to the channel being played, and every answer the platform did not
+give (see [RewardedStatus.resetsAt](https://gemarcade.com/developer/api/game#rewardedstatus-resetsat)).
+
+## RewardedStatus.grantable
+
+[RewardedStatus.grantable](https://gemarcade.com/developer/api/game#rewardedstatus-grantable)
+
+```ts
+readonly grantable: boolean
+```
+
+Whether pressing your button could pay right now: the platform would grant
+the reward if an ad is watched or, where no ad serves, under the
+placement's `without_ads: grant`.
+
+**Not a promise that an ad will play, and not a promise of a reward.** It
+is `false` whenever a cap is spent, a cooldown is running, the player holds
+`max_held`, rewarded is off on this channel, or the arcade running your
+game does not take ad requests at all.
+
+## RewardedStatus.remainingToday
+
+[RewardedStatus.remainingToday](https://gemarcade.com/developer/api/game#rewardedstatus-remainingtoday)
+
+```ts
+readonly remainingToday?: number
+```
+
+Grants left today under the placement's daily cap, a non-negative integer.
+
+ABSENT — no key, never a sentinel — when the placement has no daily cap,
+and on any answer where `declared` is `false`.
+
+## RewardedStatus.nextEligibleAt
+
+[RewardedStatus.nextEligibleAt](https://gemarcade.com/developer/api/game#rewardedstatus-nexteligibleat)
+
+```ts
+readonly nextEligibleAt?: number
+```
+
+When the placement's cooldown ends, in epoch milliseconds — render it with
+`new Date(nextEligibleAt)`.
+
+ABSENT when no cooldown is running.
+
+## RewardedStatus.heldLimitReached
+
+[RewardedStatus.heldLimitReached](https://gemarcade.com/developer/api/game#rewardedstatus-heldlimitreached)
+
+```ts
+readonly heldLimitReached: boolean
+```
+
+Whether the player already holds the placement's `max_held` of the item it
+grants. Spend one first.
+
+## RewardedStatus.resetsAt
+
+[RewardedStatus.resetsAt](https://gemarcade.com/developer/api/game#rewardedstatus-resetsat)
+
+```ts
+readonly resetsAt?: number
+```
+
+When the daily count resets — the next 00:00 UTC — in epoch milliseconds.
+Take it from here rather than computing midnight in game code.
+
+ABSENT when the platform gave no answer: no play token yet, a read that
+failed or took longer than ten seconds, or a platform that does not serve
+this read. Then the rest of the status reads not declared and not
+grantable, and the reason went to your `onError` handler.
+
 ## AnalyticsValue
 
 [AnalyticsValue](https://gemarcade.com/developer/api/game#analyticsvalue)
@@ -4863,6 +5063,29 @@ sends only while connected, and only to an arcade that draws a wallet.
 **Returns.** whether it entered the send path — `false` before the bridge is
   up, and `false` for an arcade with no wallet to move.
 
+## GemFrame.showPortraitBorders
+
+[GemFrame.showPortraitBorders](https://gemarcade.com/developer/api/game#gemframe-showportraitborders)
+
+```ts
+showPortraitBorders(name: string | null): boolean
+```
+
+Tell the arcade which of your store page's portrait borders to paint beside
+your game, or `null` for none.
+
+Prefer `gem.showPortraitBorders`, which holds your choice until the bridge
+is up and paces a burst of changes for you. This one sends every call it
+accepts, only while connected, and only to an arcade that paints borders.
+
+| Parameter | Type |
+| --- | --- |
+| `name` | `string \| null` |
+
+**Returns.** whether the message left the frame — `false` for a string that is
+  not a border name (with a console warning), before the bridge is up, for
+  an arcade that paints no borders, and past this frame's own limit.
+
 ## GemFrame.setWalletVisible
 
 [GemFrame.setWalletVisible](https://gemarcade.com/developer/api/game#gemframe-setwalletvisible)
@@ -4935,6 +5158,30 @@ arcade that handles share.
   up, for an arcade that does not handle share, and past this frame's own
   limit of six a minute.
 
+## GemFrame.requestVibrate
+
+[GemFrame.requestVibrate](https://gemarcade.com/developer/api/game#gemframe-requestvibrate)
+
+```ts
+requestVibrate(pattern: readonly number[]): boolean
+```
+
+Ask the arcade to play a vibration pattern where this frame has no
+`navigator.vibrate` of its own. Nothing comes back.
+
+Prefer `gem.vibration.vibrate`, which calls `navigator.vibrate` itself
+where it exists, normalizes the pattern and caps its total length. This one
+checks only the message's bounds, sends only while connected, and only to
+an arcade that handles vibration.
+
+| Parameter | Type |
+| --- | --- |
+| `pattern` | `readonly number[]` |
+
+**Returns.** whether the message left the frame — `false` before the bridge is
+  up, for an arcade that does not handle vibration, and past this frame's
+  own limit of 600 a minute.
+
 ## GemFrame.reportFrameStats
 
 [GemFrame.reportFrameStats](https://gemarcade.com/developer/api/game#gemframe-reportframestats)
@@ -5067,8 +5314,9 @@ draw your own placeholder rather than a broken image. Pass it through
 readonly badges: readonly PlayerBadge[]
 ```
 
-The player's equipped badges, in display order. Always a list, and empty
-until platform achievements equip any.
+The player's equipped badges, at most two, in the order the player
+arranged them. Always a list — empty when they wear none, or when their
+identity is withheld — so draw what is there and key on `itemId`.
 
 ## FriendsPage
 
@@ -5121,7 +5369,9 @@ readonly limit?: number
 ```
 
 Friends per page — default 50, at most 200. A player holds at most 1000
-friends, so five max-size pages is the whole list.
+friends, so five max-size pages is the whole list. A larger value is
+clamped to 200; a value that is not a non-negative integer is refused with
+`invalid`.
 
 ## ListFriendsOptions.cursor
 
@@ -5144,6 +5394,181 @@ readonly signal?: AbortSignal
 
 Abort the read.
 
+## FriendChallenge
+
+[FriendChallenge](https://gemarcade.com/developer/api/game#friendchallenge)
+
+```ts
+interface FriendChallenge
+```
+
+One friend challenge this player received, in THIS game on THIS channel.
+
+What the platform holds, not what the card said: there is no rendered line,
+because your game renders its own copy from [FriendChallenge.template](https://gemarcade.com/developer/api/game#friendchallenge-template)
+and [FriendChallenge.params](https://gemarcade.com/developer/api/game#friendchallenge-params). Who sent it is
+[FriendChallenge.from](https://gemarcade.com/developer/api/game#friendchallenge-from), resolved by the platform from its own records.
+
+## FriendChallenge.id
+
+[FriendChallenge.id](https://gemarcade.com/developer/api/game#friendchallenge-id)
+
+```ts
+readonly id: string
+```
+
+The challenge's id — the value the Arcade puts in the `gemChallenge`
+launch key, and what [FriendsApi.markAnswered](https://gemarcade.com/developer/api/game#friendsapi-markanswered) takes. Opaque: compare
+it, store it, never parse it.
+
+## FriendChallenge.from
+
+[FriendChallenge.from](https://gemarcade.com/developer/api/game#friendchallenge-from)
+
+```ts
+readonly from: Friend
+```
+
+Who sent it, with the same display identity a [Friend](https://gemarcade.com/developer/api/game#friend) row carries.
+
+The ONLY name to show. Never read a name out of
+[FriendChallenge.params](https://gemarcade.com/developer/api/game#friendchallenge-params): a name in a param is one nobody checked.
+
+## FriendChallenge.template
+
+[FriendChallenge.template](https://gemarcade.com/developer/api/game#friendchallenge-template)
+
+```ts
+readonly template: string
+```
+
+The `friend_challenge_templates[].key` it was sent with — which of your
+templates, so your game knows what was asked.
+
+## FriendChallenge.params
+
+[FriendChallenge.params](https://gemarcade.com/developer/api/game#friendchallenge-params)
+
+```ts
+readonly params: Readonly<Record<string, string | number>>
+```
+
+The params exactly as sent: integers as numbers, date, enum and code
+params as strings. The template constrained them when the challenge was
+sent, but the config may have changed since, so check each one against
+what your game expects before it does anything — as you would a launch
+key.
+
+## FriendChallenge.createdAt
+
+[FriendChallenge.createdAt](https://gemarcade.com/developer/api/game#friendchallenge-createdat)
+
+```ts
+readonly createdAt: number
+```
+
+When it was sent, in Unix seconds.
+
+## FriendChallenge.openedAt
+
+[FriendChallenge.openedAt](https://gemarcade.com/developer/api/game#friendchallenge-openedat)
+
+```ts
+readonly openedAt?: number
+```
+
+When the player pressed Play on it in the Arcade, in Unix seconds. Absent
+until they have.
+
+## FriendChallenge.answeredAt
+
+[FriendChallenge.answeredAt](https://gemarcade.com/developer/api/game#friendchallenge-answeredat)
+
+```ts
+readonly answeredAt?: number
+```
+
+When a game marked it answered with [FriendsApi.markAnswered](https://gemarcade.com/developer/api/game#friendsapi-markanswered), in
+Unix seconds. Absent until one has — so present on a relaunch of a
+challenge already played, which is how a replay is told from a first
+attempt.
+
+## FriendChallengesPage
+
+[FriendChallengesPage](https://gemarcade.com/developer/api/game#friendchallengespage)
+
+```ts
+interface FriendChallengesPage
+```
+
+One page of the friend challenges this player holds in this game.
+
+## FriendChallengesPage.challenges
+
+[FriendChallengesPage.challenges](https://gemarcade.com/developer/api/game#friendchallengespage-challenges)
+
+```ts
+readonly challenges: readonly FriendChallenge[]
+```
+
+The page's challenges, newest first, answered ones last.
+
+## FriendChallengesPage.nextCursor
+
+[FriendChallengesPage.nextCursor](https://gemarcade.com/developer/api/game#friendchallengespage-nextcursor)
+
+```ts
+readonly nextCursor?: string
+```
+
+Present exactly when another page exists — pass it back as
+[ListFriendChallengesOptions.cursor](https://gemarcade.com/developer/api/game#listfriendchallengesoptions-cursor) to continue. Opaque: mint
+nothing, store nothing, compare nothing.
+
+## ListFriendChallengesOptions
+
+[ListFriendChallengesOptions](https://gemarcade.com/developer/api/game#listfriendchallengesoptions)
+
+```ts
+interface ListFriendChallengesOptions
+```
+
+What [FriendsApi.inbox](https://gemarcade.com/developer/api/game#friendsapi-inbox) takes.
+
+## ListFriendChallengesOptions.limit
+
+[ListFriendChallengesOptions.limit](https://gemarcade.com/developer/api/game#listfriendchallengesoptions-limit)
+
+```ts
+readonly limit?: number
+```
+
+Challenges per page — default 50, at most 200. The platform keeps at most
+200 per player, so one max-size page is the whole inbox. A larger value is
+clamped to 200; a value that is not a non-negative integer is refused with
+`invalid`.
+
+## ListFriendChallengesOptions.cursor
+
+[ListFriendChallengesOptions.cursor](https://gemarcade.com/developer/api/game#listfriendchallengesoptions-cursor)
+
+```ts
+readonly cursor?: string
+```
+
+The previous page's [FriendChallengesPage.nextCursor](https://gemarcade.com/developer/api/game#friendchallengespage-nextcursor), verbatim. A
+cursor the platform did not mint is refused with `invalid`.
+
+## ListFriendChallengesOptions.signal
+
+[ListFriendChallengesOptions.signal](https://gemarcade.com/developer/api/game#listfriendchallengesoptions-signal)
+
+```ts
+readonly signal?: AbortSignal
+```
+
+Abort the read.
+
 ## FriendChallengeRequest
 
 [FriendChallengeRequest](https://gemarcade.com/developer/api/game#friendchallengerequest)
@@ -5423,15 +5848,18 @@ channel: the version the template is missing from.
 class FriendsApi
 ```
 
-Reading the signed-in player's accepted friends, and asking the Arcade to
-send one of them a friend challenge.
+Reading the signed-in player's accepted friends, asking the Arcade to send
+one of them a friend challenge, and reading the friend challenges this
+player received in this game.
 
 Reached as `gem.friends`. Display identity only, and every accepted friend
 appears whether or not they have played this game — an invite-a-friend flow
 needs exactly the ones who have not. The graph itself — requests, accepts,
 blocks — is managed on the Arcade, not here. So is a friend challenge's
 send: [FriendsApi.challenge](https://gemarcade.com/developer/api/game#friendsapi-challenge) asks, and the Arcade confirms with the
-player and sends.
+player and sends. The receiving side is [FriendsApi.launchedChallenge](https://gemarcade.com/developer/api/game#friendsapi-launchedchallenge)
+(the challenge this frame was launched with), [FriendsApi.inbox](https://gemarcade.com/developer/api/game#friendsapi-inbox) and
+[FriendsApi.markAnswered](https://gemarcade.com/developer/api/game#friendsapi-markanswered).
 
 ```js
 let page = await gem.friends.list();
@@ -5460,7 +5888,8 @@ have played this one.
 | --- | --- |
 | `options` | `ListFriendsOptions` |
 
-**Throws.** `invalid` when the cursor is not one a previous page minted,
+**Throws.** `invalid` when the cursor is not one a previous page minted or
+  `limit` is not a non-negative integer,
   `forbidden` in a context with no player — this is a player surface, and
   a game server has no friend list.
 
@@ -5520,6 +5949,123 @@ challengeButton.onclick = async () => {
 };
 ```
 
+## FriendsApi.inbox
+
+[FriendsApi.inbox](https://gemarcade.com/developer/api/game#friendsapi-inbox)
+
+```ts
+inbox(options?: ListFriendChallengesOptions): Promise<FriendChallengesPage>
+```
+
+Read one page of the friend challenges this player holds in THIS game on
+THIS channel — in every state. Answered challenges are INCLUDED, and sort
+after the rest; within each part, newest first.
+
+Pass the result's `nextCursor` back as `cursor` until it stops arriving.
+A guest holds no challenges, so a guest's page is empty rather than a
+refusal — build the screen for the empty state, not around an error.
+
+For the one challenge this frame was launched with, use
+[FriendsApi.launchedChallenge](https://gemarcade.com/developer/api/game#friendsapi-launchedchallenge) rather than searching this list.
+
+| Parameter | Type |
+| --- | --- |
+| `options` | `ListFriendChallengesOptions` |
+
+**Throws.** `invalid` when the cursor is not one a previous page minted or
+  `limit` is not a non-negative integer,
+  `forbidden` in a context with no player of this game — a game server,
+  or a token that is not a game-scoped player token.
+
+```ts
+const page = await gem.friends.inbox();
+for (const c of page.challenges) {
+  if (c.template !== 'beat_code_jar') continue;
+  renderChallengeRow(c.from, c.params, c.answeredAt !== undefined);
+}
+```
+
+## FriendsApi.launchedChallenge
+
+[FriendsApi.launchedChallenge](https://gemarcade.com/developer/api/game#friendsapi-launchedchallenge)
+
+```ts
+launchedChallenge(options?: { signal?: AbortSignal }): Promise<FriendChallenge | null>
+```
+
+The friend challenge this frame was launched with, or `null`.
+
+When a player opens a friend challenge in the Arcade, the Arcade launches
+your game with the challenge's params as launch keys plus its own
+`gemChallenge` key. This reads that key — never parse it yourself — and
+looks the challenge up, so you get the sender from the platform's records
+and the params as they were sent.
+
+The key is read ONCE, when `createGem` runs, so cleaning your URL with
+`history.replaceState` afterwards changes nothing here.
+
+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 challenge that is not this player's (a link
+someone shared), one from another game or channel, and every guest
+launch. Treat `null` as an ordinary launch.
+
+A RELAUNCH REPLAYS. Pressing Play again in the Arcade relaunches the
+same challenge, so the same one comes back; it carries
+[FriendChallenge.answeredAt](https://gemarcade.com/developer/api/game#friendchallenge-answeredat) once a game has called
+[FriendsApi.markAnswered](https://gemarcade.com/developer/api/game#friendsapi-markanswered), which is how a replay is told from a
+first attempt. Asks the platform on every call, so `answeredAt` is
+current.
+
+| Parameter | Type |
+| --- | --- |
+| `options` | `{ signal?: AbortSignal }` |
+
+**Throws.** What any platform read throws: `forbidden` in a context with no
+  player of this game, `unavailable` and `rate_limited` when the platform
+  cannot answer now — and `not_found` for a 404 that is NOT the platform's
+  uniform challenge answer (no `inbox_item_not_found` code), which is a
+  platform that does not serve this read rather than an ordinary launch.
+
+```ts
+const challenge = await gem.friends.launchedChallenge();
+if (challenge?.template === 'beat_code_jar') {
+  // Check every param before it does anything: the config may have changed since.
+  const jar = challenge.params.jar;
+  if (typeof jar === 'string' && /^[A-Z0-9]{7}$/.test(jar)) {
+    startJar(jar, { from: challenge.from, replay: challenge.answeredAt !== undefined });
+  }
+}
+```
+
+## FriendsApi.markAnswered
+
+[FriendsApi.markAnswered](https://gemarcade.com/developer/api/game#friendsapi-markanswered)
+
+```ts
+markAnswered(id: string): Promise<void>
+```
+
+Mark one of this player's friend challenges answered — the player has
+played it. Call it when your game has finished the attempt the challenge
+asked for, win or lose.
+
+Idempotent: a second call changes nothing, and a challenge keeps the
+first time it was answered. The sender is told nothing — there is no read
+receipt — so this is your game's own record, which
+[FriendChallenge.answeredAt](https://gemarcade.com/developer/api/game#friendchallenge-answeredat) reads back.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `id` | `string` | A [FriendChallenge.id](https://gemarcade.com/developer/api/game#friendchallenge-id), from
+  [FriendsApi.launchedChallenge](https://gemarcade.com/developer/api/game#friendsapi-launchedchallenge) or [FriendsApi.inbox](https://gemarcade.com/developer/api/game#friendsapi-inbox). |
+
+**Throws.** `not_found` when no challenge of this player's in this game and
+  channel has that id — one answer for unknown and someone else's;
+  `invalid` when `id` cannot be a challenge id at all, before anything is
+  sent; `forbidden` in a context with no player of this game;
+  `rate_limited` past the platform's per-player budget.
+
 ## FunctionInvokeOptions
 
 [FunctionInvokeOptions](https://gemarcade.com/developer/api/game#functioninvokeoptions)
@@ -6561,8 +7107,9 @@ draw your own placeholder rather than a broken image. Pass it through
 readonly badges: readonly PlayerBadge[]
 ```
 
-The player's equipped badges, in display order. Always a list, and empty
-until platform achievements equip any.
+The player's equipped badges, at most two, in the order the player
+arranged them. Always a list — empty when they wear none, or when their
+identity is withheld — so draw what is there and key on `itemId`.
 
 ## GemPrefs
 
@@ -7342,7 +7889,10 @@ resumes it when the promise settles, so you do not pause anything yourself.
 ⚠️ `shown` **grants nothing.** It is not a receipt and not an entitlement,
 and a reward must never be handed out on the strength of it.
 
-You are told no reason for a no, and there is nothing to infer from one.
+You are told no reason for a no, and there is nothing to infer from one
+about the player. What you can read is your own economy:
+`rewardedStatus(placement)` says whether a rewarded placement could pay
+right now under your own declared caps — never whether an ad will play.
 
 **Guides.** [cross-promotion](https://gemarcade.com/developer/docs/cross-promotion)
 
@@ -7405,6 +7955,40 @@ shareButton.onclick = () => {
 
 **Guides.** [getting-started](https://gemarcade.com/developer/docs/getting-started)
 
+## Gem.vibration
+
+[Gem.vibration](https://gemarcade.com/developer/api/game#gem-vibration)
+
+```ts
+readonly vibration: VibrationApi
+```
+
+Vibrate the player's device — call this instead of `navigator.vibrate`,
+which does nothing on any iPhone. It takes the same pattern and returns the
+same boolean, calls `navigator.vibrate` itself where that works, and asks
+the arcade to vibrate where it does not.
+
+Read [VibrationApi.available](https://gemarcade.com/developer/api/game#vibrationapi-available) live, after `awaitBridge()`, to decide
+whether to show your game's vibration toggle — on an iPhone it is `false`
+until the bridge connects — and check that toggle before every call:
+
+```js
+await gem.awaitBridge();
+vibrationRow.hidden = !gem.vibration.available;
+
+function onHit() {
+  if (settings.vibration) gem.vibration.vibrate(30);
+}
+```
+
+- **Never call `navigator.vibrate`**, guarded or not, and never fall back
+  to it: this already does.
+- **Nothing vibrates before the player's first tap** in your game; the
+  call returns `false` until then.
+- **Stop on pause** with `gem.vibration.vibrate(0)`.
+
+**Guides.** [vibration](https://gemarcade.com/developer/docs/vibration)
+
 ## Gem.analytics
 
 [Gem.analytics](https://gemarcade.com/developer/api/game#gem-analytics)
@@ -7499,12 +8083,17 @@ readonly friends: FriendsApi
 The signed-in player's accepted friends — display identity only,
 read-only, paginated — and the one ask that reaches past them:
 [FriendsApi.challenge](https://gemarcade.com/developer/api/game#friendsapi-challenge), which asks the Arcade to send a friend a
-challenge after the player confirms it in the Arcade's own sheet.
+challenge after the player confirms it in the Arcade's own sheet. The
+receiving side reads the challenges this player holds in this game:
+[FriendsApi.launchedChallenge](https://gemarcade.com/developer/api/game#friendsapi-launchedchallenge) for the one this frame was launched
+with, [FriendsApi.inbox](https://gemarcade.com/developer/api/game#friendsapi-inbox) for all of them, and
+[FriendsApi.markAnswered](https://gemarcade.com/developer/api/game#friendsapi-markanswered) once one has been played.
 
 Every accepted friend appears whether or not they have played this game;
 an invite-a-friend flow needs exactly the ones who have not. The graph
 itself — requests, accepts, blocks, presence — stays on the Arcade: there
-is nothing here to mutate and nothing that says who is online.
+is nothing here to mutate but a challenge's own answered mark, and nothing
+that says who is online.
 
 A player surface only. In a context with no player — a game server — the
 platform refuses the read; a server has no friend list.
@@ -7698,6 +8287,51 @@ arcade just said is not sent.
 | --- | --- |
 | `muted` | `boolean` |
 
+## Gem.showPortraitBorders
+
+[Gem.showPortraitBorders](https://gemarcade.com/developer/api/game#gem-showportraitborders)
+
+```ts
+showPortraitBorders(name: string | null): void
+```
+
+Choose which of your store page's **portrait borders** the arcade paints on
+either side of your game, or `null` for none.
+
+On a desktop browser, the arcade's desktop app or a television, the arcade
+shows a portrait-only game as a centred portrait column. With borders
+declared on your store page (`media.portrait_borders`), it paints one of
+those images beside the column instead of its own bars. Call this at
+start-up and on every theme change, with the border that goes with what is
+on screen:
+
+```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: a theme with no art
+}
+```
+
+Until your first call the arcade shows the page's first border. Whether
+your game is letterboxed at all is decided by your store page's
+`orientations`, never by this call, so call it unconditionally: before the
+connection exists your choice is held and sent when it connects, a burst of
+changes (a picker previewing on hover) reaches the arcade as its final
+value, and an arcade that paints no borders is simply not told. The arcade
+owns the change itself — when and how the image swaps — and sends no
+acknowledgement.
+
+A name is 1 to 40 characters of `a-z`, `0-9`, `_` and `-`, starting with a
+letter or digit — the store page's own rule. Anything else is refused with
+a console warning and never sent; a valid name your page does not declare
+is ignored by the arcade, which keeps the image it is showing.
+
+| Parameter | Type |
+| --- | --- |
+| `name` | `string \| null` |
+
 ## Gem.cueReward
 
 [Gem.cueReward](https://gemarcade.com/developer/api/game#gem-cuereward)
@@ -8798,7 +9432,8 @@ interface PlayerBadge
 One badge a player has equipped — an icon the platform shows beside their
 name.
 
-Always an empty list today; platform achievements fill it with at most two.
+A player wears at most two, in the order they arranged them. Each is an icon
+they own — an achievement in any game may have awarded it.
 
 ## PlayerBadge.itemId
 
@@ -8922,8 +9557,9 @@ draw your own placeholder rather than a broken image. Pass it through
 readonly badges: readonly PlayerBadge[]
 ```
 
-The player's equipped badges, in display order. Always a list, and empty
-until platform achievements equip any.
+The player's equipped badges, at most two, in the order the player
+arranged them. Always a list — empty when they wear none, or when their
+identity is withheld — so draw what is there and key on `itemId`.
 
 ## mapIdentity
 
@@ -11247,6 +11883,61 @@ A unit test that constructs the SDK in a simulated DOM has to give its
 window a parent of its own, because a simulated top-level window is exactly
 what this refuses.
 
+## VibrationApi
+
+[VibrationApi](https://gemarcade.com/developer/api/game#vibrationapi)
+
+```ts
+interface VibrationApi
+```
+
+`gem.vibration` — vibrate the player's device, on every platform that can.
+Call it instead of `navigator.vibrate`, which does nothing on any iPhone.
+
+## VibrationApi.available
+
+[VibrationApi.available](https://gemarcade.com/developer/api/game#vibrationapi-available)
+
+```ts
+readonly available: boolean
+```
+
+Whether this device can vibrate for your game: decide from this whether to
+show your game's vibration toggle. Read it live, every time — after
+`awaitBridge()`, and again when your settings screen opens — never once at
+boot: on an iPhone it is `false` until the bridge connects.
+
+`false` on a desktop with a mouse, in iOS Safari, in Firefox, before the
+bridge is up where vibration goes through the arcade, and after the
+session ends there.
+
+## VibrationApi.vibrate
+
+[VibrationApi.vibrate](https://gemarcade.com/developer/api/game#vibrationapi-vibrate)
+
+```ts
+vibrate(pattern: number | readonly number[]): boolean
+```
+
+Vibrate: takes what `navigator.vibrate` takes and returns what it returns.
+`pattern` is a duration in milliseconds, or an array of alternating
+vibration and pause durations, starting with a vibration. `0` or `[]`
+stops a pattern that is still playing, and every call replaces it.
+
+The pattern is capped at 99 entries of at most 10 000 ms each, and at
+10 000 ms in all: a longer one is cut short, not refused.
+
+Check your game's own vibration toggle before every call. Returns `false`,
+and vibrates nothing, when [VibrationApi.available](https://gemarcade.com/developer/api/game#vibrationapi-available) is false, before
+the player's first tap or key press in your game, for a pattern with a
+negative or non-finite entry, and past 600 calls a minute; each of the last
+three says so once a session through your `log`. `true` means the pattern
+was accepted, never that a motor moved.
+
+| Parameter | Type |
+| --- | --- |
+| `pattern` | `number \| readonly number[]` |
+
 ## LeaderboardPeriod.id
 
 [LeaderboardPeriod.id](https://gemarcade.com/developer/api/game#leaderboardperiod-id)
@@ -11415,8 +12106,9 @@ draw your own placeholder rather than a broken image. Pass it through
 readonly badges: readonly PlayerBadge[]
 ```
 
-The player's equipped badges, in display order. Always a list, and empty
-until platform achievements equip any.
+The player's equipped badges, at most two, in the order the player
+arranged them. Always a list — empty when they wear none, or when their
+identity is withheld — so draw what is there and key on `itemId`.
 
 ## LeaderboardEntry.rank
 
@@ -12856,8 +13548,9 @@ draw your own placeholder rather than a broken image. Pass it through
 readonly badges: readonly PlayerBadge[]
 ```
 
-The player's equipped badges, in display order. Always a list, and empty
-until platform achievements equip any.
+The player's equipped badges, at most two, in the order the player
+arranged them. Always a list — empty when they wear none, or when their
+identity is withheld — so draw what is there and key on `itemId`.
 
 ## PlayerProfile.playerId
 
@@ -14890,8 +15583,9 @@ draw your own placeholder rather than a broken image. Pass it through
 readonly badges: readonly PlayerBadge[]
 ```
 
-The player's equipped badges, in display order. Always a list, and empty
-until platform achievements equip any.
+The player's equipped badges, at most two, in the order the player
+arranged them. Always a list — empty when they wear none, or when their
+identity is withheld — so draw what is there and key on `itemId`.
 
 ## RoomMember.playerId
 
@@ -15654,8 +16348,9 @@ draw your own placeholder rather than a broken image. Pass it through
 readonly badges: readonly PlayerBadge[]
 ```
 
-The player's equipped badges, in display order. Always a list, and empty
-until platform achievements equip any.
+The player's equipped badges, at most two, in the order the player
+arranged them. Always a list — empty when they wear none, or when their
+identity is withheld — so draw what is there and key on `itemId`.
 
 ## ShowcaseFriendEntry.playerId