@indiegems/gem-web-sdk 7.9.1 → 8.1.0

package/docs/api/reference.json

@@ -2,7 +2,7 @@
   "schema_version": 1,
   "source": {
     "repo": "IndieGems/gem-web-sdk",
-    "version": "7.9.1"
+    "version": "8.1.0"
   },
   "entries": [
     {
@@ -61,6 +61,10 @@
           "key": "share",
           "title": "Sharing a link to your game"
         },
+        {
+          "key": "vibration",
+          "title": "Vibrating the device"
+        },
         {
           "key": "config",
           "title": "Your published config"
@@ -371,6 +375,29 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "GameConfig.rewarded_placements",
+          "name": "rewarded_placements",
+          "anchor": "gameconfig-rewarded_placements",
+          "group": "config",
+          "url": "https://gemarcade.com/developer/api/game#gameconfig-rewarded_placements",
+          "signature": "rewarded_placements?: SnapshotRewardedPlacement[]",
+          "documented": true,
+          "summary": "Your rewarded placements — what pressing a rewarded button grants. An\narray, one row per placement, each naming itself in `placement`, with its\n`grants`, the caps the platform enforces on it (`max_per_day`,\n`cooldown_seconds`, `max_held`) and what happens where no ad serves\n(`without_ads`).\n\nRead it to LABEL your button — \"+1 Revive\" — never to decide a reward. A\ngrant is an `item_grant`, with a `quantity` of the item its\n`item_definition_id` names, or a `currency_grant`, with an `amount` of the\ncurrency its `currency_id` names; the word on the button is that\ndefinition's `display_name`, from [GameConfig.item](https://gemarcade.com/developer/api/game#gameconfig-item) or\n[GameConfig.currency](https://gemarcade.com/developer/api/game#gameconfig-currency):\n\n```js\nconst row = config?.rewarded_placements?.find((p) => p.placement === 'classic_revive');\nconst grant = row?.grants[0];\nconst label =\n  grant?.type === 'item_grant'\n    ? `+${grant.quantity} ${config.item(grant.item_definition_id)?.display_name ?? ''}`\n    : grant?.type === 'currency_grant'\n      ? `+${grant.amount} ${config.currency(grant.currency_id)?.display_name ?? ''}`\n      : undefined;\n```\n\nWhether an ask grants anything is the platform's decision, made against\nthis config server-side; the grant lands on your game's inventory, and\nre-reading `gem.me.inventory` is the only way to learn that it did. Whether\nthe button could pay right now is [AdsApi.rewardedStatus](https://gemarcade.com/developer/api/game#adsapi-rewardedstatus).\n\nAbsent when your game declares none.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": [
+            {
+              "slug": "cross-promotion",
+              "anchor": null,
+              "url": "https://gemarcade.com/developer/docs/cross-promotion"
+            }
+          ]
+        },
         {
           "id": "GameConfig.version",
           "name": "version",
@@ -4019,7 +4046,7 @@
           "url": "https://gemarcade.com/developer/api/game#adoutcomekind",
           "signature": "type AdOutcomeKind = \"shown\" | \"no_ad\" | \"unavailable\"",
           "documented": true,
-          "summary": "The complete vocabulary of answers. Three values, and there will not be a\nfourth.\n\n- `shown` — a panel was painted and has now closed. Resume. **It grants\n  nothing.**\n- `no_ad` — nothing was painted. Carry on exactly as if you had not asked.\n  This is the common answer.\n- `unavailable` — the arcade could not render just now. Not a softer no; read\n  it exactly as you read `no_ad`.\n\nNo reason is given for a `no_ad`, and one will never be added: a reason would\ntell your game something about the player — an age, a consent state, a\nsubscription — that game code is deliberately not told.",
+          "summary": "The complete vocabulary of answers. Three values, and there will not be a\nfourth.\n\n- `shown` — a panel was painted and has now closed. Resume. **It grants\n  nothing.**\n- `no_ad` — nothing was painted. Carry on exactly as if you had not asked.\n  This is the common answer.\n- `unavailable` — the arcade could not render just now. Not a softer no; read\n  it exactly as you read `no_ad`.\n\nNo reason is given for a `no_ad`, and one will never be added: a reason would\ntell your game something about the player — an age, a consent state, a\nsubscription — that game code is deliberately not told.\n\nThe one thing you can learn is about **your own economy**, and not from this\nanswer: [AdsApi.rewardedStatus](https://gemarcade.com/developer/api/game#adsapi-rewardedstatus) reports your own declared rewarded caps\nas the platform holds them (a platform-wide per-placement maximum, where one\nis set, can lower a cap). It never reports anything about the player.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -4109,6 +4136,155 @@
             }
           ]
         },
+        {
+          "id": "AdsApi.rewardedStatus",
+          "name": "rewardedStatus",
+          "anchor": "adsapi-rewardedstatus",
+          "group": "ads",
+          "url": "https://gemarcade.com/developer/api/game#adsapi-rewardedstatus",
+          "signature": "rewardedStatus(placement: string): Promise<RewardedStatus>",
+          "documented": true,
+          "summary": "Whether a rewarded placement could pay right now, so you can decide whether\nto draw its button. **It never says whether an ad will play.**\n\nThe answer comes from your own `rewarded_placements` config — its daily\ncap, cooldown and `max_held` — applied to this player's use of it, as the\nplatform holds them. Nothing in it describes the player. `grantable: true`\nmeans the platform would grant if an ad is watched or, where no ad serves,\nunder the placement's `without_ads: grant`; a player can still press the\nbutton and get `no_ad`, for reasons your game is not told.\n\nNOTHING REJECTS, like everything else on `gem.ads`. Without a play token,\nwhen the read fails or takes longer than ten seconds, or for a `placement`\noutside the grammar [AdRequest.placement](https://gemarcade.com/developer/api/game#adrequest-placement) documents, it resolves not\ndeclared and not grantable, with no `resetsAt`, and the reason goes to your\n`onError` handler.\n\nIt is a read of the platform, so call it when you draw the button — on a\nresults or death screen — not every frame. Calls for one placement that\noverlap share one request. Draw the rest of the screen first rather than\nholding it on this answer.\n\n⚠️ It grants nothing and reserves nothing. The reward is granted by the\nplatform when the player asks with `requestAd`; re-read `gem.me.inventory`\nafter that ask settles, whatever it settled as.",
+          "deprecated": null,
+          "params": [
+            {
+              "name": "placement",
+              "type": "string",
+              "optional": false,
+              "summary": "A placement your `rewarded_placements` config declares."
+            }
+          ],
+          "returns": "The placement's state. Always resolves; never rejects.",
+          "throws": null,
+          "example": "```ts\nconst status = await gem.ads.rewardedStatus('classic_revive');\nreviveButton.disabled = !status.grantable;\nif (status.nextEligibleAt !== undefined) {\n  reviveButton.title = `Back at ${new Date(status.nextEligibleAt).toLocaleTimeString()}`;\n}\n```",
+          "defaultValue": null,
+          "guides": [
+            {
+              "slug": "cross-promotion",
+              "anchor": null,
+              "url": "https://gemarcade.com/developer/docs/cross-promotion"
+            }
+          ]
+        },
+        {
+          "id": "RewardedStatus",
+          "name": "RewardedStatus",
+          "anchor": "rewardedstatus",
+          "group": "ads",
+          "url": "https://gemarcade.com/developer/api/game#rewardedstatus",
+          "signature": "interface RewardedStatus",
+          "documented": true,
+          "summary": "What [AdsApi.rewardedStatus](https://gemarcade.com/developer/api/game#adsapi-rewardedstatus) answers: the state of one rewarded\nplacement for this player, from your own declared caps.\n\nEvery figure comes from **your** `rewarded_placements` config — `max_per_day`,\n`cooldown_seconds`, `max_held` — applied to this player's use of it, as the\nplatform holds them. The platform can hold a placement's daily cap below what\nyou declared, never above it. Nothing here describes the player.\n\n⚠️ **It never says whether an ad will play.** Whether one does depends on\nthings your game is deliberately not told. A player can see your button,\npress it, and get `no_ad`: read that `no_ad` like any other, and never guess\na reason.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "RewardedStatus.declared",
+          "name": "declared",
+          "anchor": "rewardedstatus-declared",
+          "group": "ads",
+          "url": "https://gemarcade.com/developer/api/game#rewardedstatus-declared",
+          "signature": "readonly declared: boolean",
+          "documented": true,
+          "summary": "Whether this channel's published config declares the placement.\n\n`false` for a placement your config does not name, a config that is not\npromoted to the channel being played, and every answer the platform did not\ngive (see [RewardedStatus.resetsAt](https://gemarcade.com/developer/api/game#rewardedstatus-resetsat)).",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "RewardedStatus.grantable",
+          "name": "grantable",
+          "anchor": "rewardedstatus-grantable",
+          "group": "ads",
+          "url": "https://gemarcade.com/developer/api/game#rewardedstatus-grantable",
+          "signature": "readonly grantable: boolean",
+          "documented": true,
+          "summary": "Whether pressing your button could pay right now: the platform would grant\nthe reward if an ad is watched or, where no ad serves, under the\nplacement's `without_ads: grant`.\n\n**Not a promise that an ad will play, and not a promise of a reward.** It\nis `false` whenever a cap is spent, a cooldown is running, the player holds\n`max_held`, rewarded is off on this channel, or the arcade running your\ngame does not take ad requests at all.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "RewardedStatus.remainingToday",
+          "name": "remainingToday",
+          "anchor": "rewardedstatus-remainingtoday",
+          "group": "ads",
+          "url": "https://gemarcade.com/developer/api/game#rewardedstatus-remainingtoday",
+          "signature": "readonly remainingToday?: number",
+          "documented": true,
+          "summary": "Grants left today under the placement's daily cap, a non-negative integer.\n\nABSENT — no key, never a sentinel — when the placement has no daily cap,\nand on any answer where `declared` is `false`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "RewardedStatus.nextEligibleAt",
+          "name": "nextEligibleAt",
+          "anchor": "rewardedstatus-nexteligibleat",
+          "group": "ads",
+          "url": "https://gemarcade.com/developer/api/game#rewardedstatus-nexteligibleat",
+          "signature": "readonly nextEligibleAt?: number",
+          "documented": true,
+          "summary": "When the placement's cooldown ends, in epoch milliseconds — render it with\n`new Date(nextEligibleAt)`.\n\nABSENT when no cooldown is running.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "RewardedStatus.heldLimitReached",
+          "name": "heldLimitReached",
+          "anchor": "rewardedstatus-heldlimitreached",
+          "group": "ads",
+          "url": "https://gemarcade.com/developer/api/game#rewardedstatus-heldlimitreached",
+          "signature": "readonly heldLimitReached: boolean",
+          "documented": true,
+          "summary": "Whether the player already holds the placement's `max_held` of the item it\ngrants. Spend one first.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "RewardedStatus.resetsAt",
+          "name": "resetsAt",
+          "anchor": "rewardedstatus-resetsat",
+          "group": "ads",
+          "url": "https://gemarcade.com/developer/api/game#rewardedstatus-resetsat",
+          "signature": "readonly resetsAt?: number",
+          "documented": true,
+          "summary": "When the daily count resets — the next 00:00 UTC — in epoch milliseconds.\nTake it from here rather than computing midnight in game code.\n\nABSENT when the platform gave no answer: no play token yet, a read that\nfailed or took longer than ten seconds, or a platform that does not serve\nthis read. Then the rest of the status reads not declared and not\ngrantable, and the reason went to your `onError` handler.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "AnalyticsValue",
           "name": "AnalyticsValue",
@@ -6100,6 +6276,30 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "GemFrame.showPortraitBorders",
+          "name": "showPortraitBorders",
+          "anchor": "gemframe-showportraitborders",
+          "group": "frame",
+          "url": "https://gemarcade.com/developer/api/game#gemframe-showportraitborders",
+          "signature": "showPortraitBorders(name: string | null): boolean",
+          "documented": true,
+          "summary": "Tell the arcade which of your store page's portrait borders to paint beside\nyour game, or `null` for none.\n\nPrefer `gem.showPortraitBorders`, which holds your choice until the bridge\nis up and paces a burst of changes for you. This one sends every call it\naccepts, only while connected, and only to an arcade that paints borders.",
+          "deprecated": null,
+          "params": [
+            {
+              "name": "name",
+              "type": "string | null",
+              "optional": false,
+              "summary": null
+            }
+          ],
+          "returns": "whether the message left the frame — `false` for a string that is\n  not a border name (with a console warning), before the bridge is up, for\n  an arcade that paints no borders, and past this frame's own limit.",
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "GemFrame.setWalletVisible",
           "name": "setWalletVisible",
@@ -6184,6 +6384,30 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "GemFrame.requestVibrate",
+          "name": "requestVibrate",
+          "anchor": "gemframe-requestvibrate",
+          "group": "frame",
+          "url": "https://gemarcade.com/developer/api/game#gemframe-requestvibrate",
+          "signature": "requestVibrate(pattern: readonly number[]): boolean",
+          "documented": true,
+          "summary": "Ask the arcade to play a vibration pattern where this frame has no\n`navigator.vibrate` of its own. Nothing comes back.\n\nPrefer `gem.vibration.vibrate`, which calls `navigator.vibrate` itself\nwhere it exists, normalizes the pattern and caps its total length. This one\nchecks only the message's bounds, sends only while connected, and only to\nan arcade that handles vibration.",
+          "deprecated": null,
+          "params": [
+            {
+              "name": "pattern",
+              "type": "readonly number[]",
+              "optional": false,
+              "summary": null
+            }
+          ],
+          "returns": "whether the message left the frame — `false` before the bridge is\n  up, for an arcade that does not handle vibration, and past this frame's\n  own limit of 600 a minute.",
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "GemFrame.reportFrameStats",
           "name": "reportFrameStats",
@@ -6359,7 +6583,7 @@
           "url": "https://gemarcade.com/developer/api/game#friend-badges",
           "signature": "readonly badges: readonly PlayerBadge[]",
           "documented": true,
-          "summary": "The player's equipped badges, in display order. Always a list, and empty\nuntil platform achievements equip any.",
+          "summary": "The player's equipped badges, at most two, in the order the player\narranged them. Always a list — empty when they wear none, or when their\nidentity is withheld — so draw what is there and key on `itemId`.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -6444,7 +6668,7 @@
           "url": "https://gemarcade.com/developer/api/game#listfriendsoptions-limit",
           "signature": "readonly limit?: number",
           "documented": true,
-          "summary": "Friends per page — default 50, at most 200. A player holds at most 1000\nfriends, so five max-size pages is the whole list.",
+          "summary": "Friends per page — default 50, at most 200. A player holds at most 1000\nfriends, so five max-size pages is the whole list. A larger value is\nclamped to 200; a value that is not a non-negative integer is refused with\n`invalid`.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -6487,6 +6711,261 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "FriendChallenge",
+          "name": "FriendChallenge",
+          "anchor": "friendchallenge",
+          "group": "friends",
+          "url": "https://gemarcade.com/developer/api/game#friendchallenge",
+          "signature": "interface FriendChallenge",
+          "documented": true,
+          "summary": "One friend challenge this player received, in THIS game on THIS channel.\n\nWhat the platform holds, not what the card said: there is no rendered line,\nbecause your game renders its own copy from [FriendChallenge.template](https://gemarcade.com/developer/api/game#friendchallenge-template)\nand [FriendChallenge.params](https://gemarcade.com/developer/api/game#friendchallenge-params). Who sent it is\n[FriendChallenge.from](https://gemarcade.com/developer/api/game#friendchallenge-from), resolved by the platform from its own records.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "FriendChallenge.id",
+          "name": "id",
+          "anchor": "friendchallenge-id",
+          "group": "friends",
+          "url": "https://gemarcade.com/developer/api/game#friendchallenge-id",
+          "signature": "readonly id: string",
+          "documented": true,
+          "summary": "The challenge's id — the value the Arcade puts in the `gemChallenge`\nlaunch key, and what [FriendsApi.markAnswered](https://gemarcade.com/developer/api/game#friendsapi-markanswered) takes. Opaque: compare\nit, store it, never parse it.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "FriendChallenge.from",
+          "name": "from",
+          "anchor": "friendchallenge-from",
+          "group": "friends",
+          "url": "https://gemarcade.com/developer/api/game#friendchallenge-from",
+          "signature": "readonly from: Friend",
+          "documented": true,
+          "summary": "Who sent it, with the same display identity a [Friend](https://gemarcade.com/developer/api/game#friend) row carries.\n\nThe ONLY name to show. Never read a name out of\n[FriendChallenge.params](https://gemarcade.com/developer/api/game#friendchallenge-params): a name in a param is one nobody checked.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "FriendChallenge.template",
+          "name": "template",
+          "anchor": "friendchallenge-template",
+          "group": "friends",
+          "url": "https://gemarcade.com/developer/api/game#friendchallenge-template",
+          "signature": "readonly template: string",
+          "documented": true,
+          "summary": "The `friend_challenge_templates[].key` it was sent with — which of your\ntemplates, so your game knows what was asked.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "FriendChallenge.params",
+          "name": "params",
+          "anchor": "friendchallenge-params",
+          "group": "friends",
+          "url": "https://gemarcade.com/developer/api/game#friendchallenge-params",
+          "signature": "readonly params: Readonly<Record<string, string | number>>",
+          "documented": true,
+          "summary": "The params exactly as sent: integers as numbers, date, enum and code\nparams as strings. The template constrained them when the challenge was\nsent, but the config may have changed since, so check each one against\nwhat your game expects before it does anything — as you would a launch\nkey.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "FriendChallenge.createdAt",
+          "name": "createdAt",
+          "anchor": "friendchallenge-createdat",
+          "group": "friends",
+          "url": "https://gemarcade.com/developer/api/game#friendchallenge-createdat",
+          "signature": "readonly createdAt: number",
+          "documented": true,
+          "summary": "When it was sent, in Unix seconds.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "FriendChallenge.openedAt",
+          "name": "openedAt",
+          "anchor": "friendchallenge-openedat",
+          "group": "friends",
+          "url": "https://gemarcade.com/developer/api/game#friendchallenge-openedat",
+          "signature": "readonly openedAt?: number",
+          "documented": true,
+          "summary": "When the player pressed Play on it in the Arcade, in Unix seconds. Absent\nuntil they have.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "FriendChallenge.answeredAt",
+          "name": "answeredAt",
+          "anchor": "friendchallenge-answeredat",
+          "group": "friends",
+          "url": "https://gemarcade.com/developer/api/game#friendchallenge-answeredat",
+          "signature": "readonly answeredAt?: number",
+          "documented": true,
+          "summary": "When a game marked it answered with [FriendsApi.markAnswered](https://gemarcade.com/developer/api/game#friendsapi-markanswered), in\nUnix seconds. Absent until one has — so present on a relaunch of a\nchallenge already played, which is how a replay is told from a first\nattempt.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "FriendChallengesPage",
+          "name": "FriendChallengesPage",
+          "anchor": "friendchallengespage",
+          "group": "friends",
+          "url": "https://gemarcade.com/developer/api/game#friendchallengespage",
+          "signature": "interface FriendChallengesPage",
+          "documented": true,
+          "summary": "One page of the friend challenges this player holds in this game.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "FriendChallengesPage.challenges",
+          "name": "challenges",
+          "anchor": "friendchallengespage-challenges",
+          "group": "friends",
+          "url": "https://gemarcade.com/developer/api/game#friendchallengespage-challenges",
+          "signature": "readonly challenges: readonly FriendChallenge[]",
+          "documented": true,
+          "summary": "The page's challenges, newest first, answered ones last.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "FriendChallengesPage.nextCursor",
+          "name": "nextCursor",
+          "anchor": "friendchallengespage-nextcursor",
+          "group": "friends",
+          "url": "https://gemarcade.com/developer/api/game#friendchallengespage-nextcursor",
+          "signature": "readonly nextCursor?: string",
+          "documented": true,
+          "summary": "Present exactly when another page exists — pass it back as\n[ListFriendChallengesOptions.cursor](https://gemarcade.com/developer/api/game#listfriendchallengesoptions-cursor) to continue. Opaque: mint\nnothing, store nothing, compare nothing.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "ListFriendChallengesOptions",
+          "name": "ListFriendChallengesOptions",
+          "anchor": "listfriendchallengesoptions",
+          "group": "friends",
+          "url": "https://gemarcade.com/developer/api/game#listfriendchallengesoptions",
+          "signature": "interface ListFriendChallengesOptions",
+          "documented": true,
+          "summary": "What [FriendsApi.inbox](https://gemarcade.com/developer/api/game#friendsapi-inbox) takes.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "ListFriendChallengesOptions.limit",
+          "name": "limit",
+          "anchor": "listfriendchallengesoptions-limit",
+          "group": "friends",
+          "url": "https://gemarcade.com/developer/api/game#listfriendchallengesoptions-limit",
+          "signature": "readonly limit?: number",
+          "documented": true,
+          "summary": "Challenges per page — default 50, at most 200. The platform keeps at most\n200 per player, so one max-size page is the whole inbox. A larger value is\nclamped to 200; a value that is not a non-negative integer is refused with\n`invalid`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "ListFriendChallengesOptions.cursor",
+          "name": "cursor",
+          "anchor": "listfriendchallengesoptions-cursor",
+          "group": "friends",
+          "url": "https://gemarcade.com/developer/api/game#listfriendchallengesoptions-cursor",
+          "signature": "readonly cursor?: string",
+          "documented": true,
+          "summary": "The previous page's [FriendChallengesPage.nextCursor](https://gemarcade.com/developer/api/game#friendchallengespage-nextcursor), verbatim. A\ncursor the platform did not mint is refused with `invalid`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "ListFriendChallengesOptions.signal",
+          "name": "signal",
+          "anchor": "listfriendchallengesoptions-signal",
+          "group": "friends",
+          "url": "https://gemarcade.com/developer/api/game#listfriendchallengesoptions-signal",
+          "signature": "readonly signal?: AbortSignal",
+          "documented": true,
+          "summary": "Abort the read.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "FriendChallengeRequest",
           "name": "FriendChallengeRequest",
@@ -6801,7 +7280,7 @@
           "url": "https://gemarcade.com/developer/api/game#friendsapi",
           "signature": "class FriendsApi",
           "documented": true,
-          "summary": "Reading the signed-in player's accepted friends, and asking the Arcade to\nsend one of them a friend challenge.\n\nReached as `gem.friends`. Display identity only, and every accepted friend\nappears whether or not they have played this game — an invite-a-friend flow\nneeds exactly the ones who have not. The graph itself — requests, accepts,\nblocks — is managed on the Arcade, not here. So is a friend challenge's\nsend: [FriendsApi.challenge](https://gemarcade.com/developer/api/game#friendsapi-challenge) asks, and the Arcade confirms with the\nplayer and sends.\n\n```js\nlet page = await gem.friends.list();\nrender(page.friends);\nwhile (page.nextCursor) {\n  page = await gem.friends.list({ cursor: page.nextCursor });\n  render(page.friends);\n}\n```",
+          "summary": "Reading the signed-in player's accepted friends, asking the Arcade to send\none of them a friend challenge, and reading the friend challenges this\nplayer received in this game.\n\nReached as `gem.friends`. Display identity only, and every accepted friend\nappears whether or not they have played this game — an invite-a-friend flow\nneeds exactly the ones who have not. The graph itself — requests, accepts,\nblocks — is managed on the Arcade, not here. So is a friend challenge's\nsend: [FriendsApi.challenge](https://gemarcade.com/developer/api/game#friendsapi-challenge) asks, and the Arcade confirms with the\nplayer and sends. The receiving side is [FriendsApi.launchedChallenge](https://gemarcade.com/developer/api/game#friendsapi-launchedchallenge)\n(the challenge this frame was launched with), [FriendsApi.inbox](https://gemarcade.com/developer/api/game#friendsapi-inbox) and\n[FriendsApi.markAnswered](https://gemarcade.com/developer/api/game#friendsapi-markanswered).\n\n```js\nlet page = await gem.friends.list();\nrender(page.friends);\nwhile (page.nextCursor) {\n  page = await gem.friends.list({ cursor: page.nextCursor });\n  render(page.friends);\n}\n```",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -6829,7 +7308,7 @@
             }
           ],
           "returns": null,
-          "throws": "`invalid` when the cursor is not one a previous page minted,\n  `forbidden` in a context with no player — this is a player surface, and\n  a game server has no friend list.",
+          "throws": "`invalid` when the cursor is not one a previous page minted or\n  `limit` is not a non-negative integer,\n  `forbidden` in a context with no player — this is a player surface, and\n  a game server has no friend list.",
           "example": null,
           "defaultValue": null,
           "guides": []
@@ -6858,6 +7337,78 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "FriendsApi.inbox",
+          "name": "inbox",
+          "anchor": "friendsapi-inbox",
+          "group": "friends",
+          "url": "https://gemarcade.com/developer/api/game#friendsapi-inbox",
+          "signature": "inbox(options?: ListFriendChallengesOptions): Promise<FriendChallengesPage>",
+          "documented": true,
+          "summary": "Read one page of the friend challenges this player holds in THIS game on\nTHIS channel — in every state. Answered challenges are INCLUDED, and sort\nafter the rest; within each part, newest first.\n\nPass the result's `nextCursor` back as `cursor` until it stops arriving.\nA guest holds no challenges, so a guest's page is empty rather than a\nrefusal — build the screen for the empty state, not around an error.\n\nFor the one challenge this frame was launched with, use\n[FriendsApi.launchedChallenge](https://gemarcade.com/developer/api/game#friendsapi-launchedchallenge) rather than searching this list.",
+          "deprecated": null,
+          "params": [
+            {
+              "name": "options",
+              "type": "ListFriendChallengesOptions",
+              "optional": false,
+              "summary": null
+            }
+          ],
+          "returns": null,
+          "throws": "`invalid` when the cursor is not one a previous page minted or\n  `limit` is not a non-negative integer,\n  `forbidden` in a context with no player of this game — a game server,\n  or a token that is not a game-scoped player token.",
+          "example": "```ts\nconst page = await gem.friends.inbox();\nfor (const c of page.challenges) {\n  if (c.template !== 'beat_code_jar') continue;\n  renderChallengeRow(c.from, c.params, c.answeredAt !== undefined);\n}\n```",
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "FriendsApi.launchedChallenge",
+          "name": "launchedChallenge",
+          "anchor": "friendsapi-launchedchallenge",
+          "group": "friends",
+          "url": "https://gemarcade.com/developer/api/game#friendsapi-launchedchallenge",
+          "signature": "launchedChallenge(options?: { signal?: AbortSignal }): Promise<FriendChallenge | null>",
+          "documented": true,
+          "summary": "The friend challenge this frame was launched with, or `null`.\n\nWhen a player opens a friend challenge in the Arcade, the Arcade launches\nyour game with the challenge's params as launch keys plus its own\n`gemChallenge` key. This reads that key — never parse it yourself — and\nlooks the challenge up, so you get the sender from the platform's records\nand the params as they were sent.\n\nThe key is read ONCE, when `createGem` runs, so cleaning your URL with\n`history.replaceState` afterwards changes nothing here.\n\nRESOLVES `null`, never rejects, for every launch that is not this\nplayer's challenge in this game: no `gemChallenge` key, a value that is\nnot a challenge id, a challenge that is not this player's (a link\nsomeone shared), one from another game or channel, and every guest\nlaunch. Treat `null` as an ordinary launch.\n\nA RELAUNCH REPLAYS. Pressing Play again in the Arcade relaunches the\nsame challenge, so the same one comes back; it carries\n[FriendChallenge.answeredAt](https://gemarcade.com/developer/api/game#friendchallenge-answeredat) once a game has called\n[FriendsApi.markAnswered](https://gemarcade.com/developer/api/game#friendsapi-markanswered), which is how a replay is told from a\nfirst attempt. Asks the platform on every call, so `answeredAt` is\ncurrent.",
+          "deprecated": null,
+          "params": [
+            {
+              "name": "options",
+              "type": "{ signal?: AbortSignal }",
+              "optional": false,
+              "summary": null
+            }
+          ],
+          "returns": null,
+          "throws": "What any platform read throws: `forbidden` in a context with no\n  player of this game, `unavailable` and `rate_limited` when the platform\n  cannot answer now — and `not_found` for a 404 that is NOT the platform's\n  uniform challenge answer (no `inbox_item_not_found` code), which is a\n  platform that does not serve this read rather than an ordinary launch.",
+          "example": "```ts\nconst challenge = await gem.friends.launchedChallenge();\nif (challenge?.template === 'beat_code_jar') {\n  // Check every param before it does anything: the config may have changed since.\n  const jar = challenge.params.jar;\n  if (typeof jar === 'string' && /^[A-Z0-9]{7}$/.test(jar)) {\n    startJar(jar, { from: challenge.from, replay: challenge.answeredAt !== undefined });\n  }\n}\n```",
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "FriendsApi.markAnswered",
+          "name": "markAnswered",
+          "anchor": "friendsapi-markanswered",
+          "group": "friends",
+          "url": "https://gemarcade.com/developer/api/game#friendsapi-markanswered",
+          "signature": "markAnswered(id: string): Promise<void>",
+          "documented": true,
+          "summary": "Mark one of this player's friend challenges answered — the player has\nplayed it. Call it when your game has finished the attempt the challenge\nasked for, win or lose.\n\nIdempotent: a second call changes nothing, and a challenge keeps the\nfirst time it was answered. The sender is told nothing — there is no read\nreceipt — so this is your game's own record, which\n[FriendChallenge.answeredAt](https://gemarcade.com/developer/api/game#friendchallenge-answeredat) reads back.",
+          "deprecated": null,
+          "params": [
+            {
+              "name": "id",
+              "type": "string",
+              "optional": false,
+              "summary": "A [FriendChallenge.id](https://gemarcade.com/developer/api/game#friendchallenge-id), from\n  [FriendsApi.launchedChallenge](https://gemarcade.com/developer/api/game#friendsapi-launchedchallenge) or [FriendsApi.inbox](https://gemarcade.com/developer/api/game#friendsapi-inbox)."
+            }
+          ],
+          "returns": null,
+          "throws": "`not_found` when no challenge of this player's in this game and\n  channel has that id — one answer for unknown and someone else's;\n  `invalid` when `id` cannot be a challenge id at all, before anything is\n  sent; `forbidden` in a context with no player of this game;\n  `rate_limited` past the platform's per-player budget.",
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "FunctionInvokeOptions",
           "name": "FunctionInvokeOptions",
@@ -7911,7 +8462,7 @@
           "url": "https://gemarcade.com/developer/api/game#gemplayer-badges",
           "signature": "readonly badges: readonly PlayerBadge[]",
           "documented": true,
-          "summary": "The player's equipped badges, in display order. Always a list, and empty\nuntil platform achievements equip any.",
+          "summary": "The player's equipped badges, at most two, in the order the player\narranged them. Always a list — empty when they wear none, or when their\nidentity is withheld — so draw what is there and key on `itemId`.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -8834,7 +9385,7 @@
           "url": "https://gemarcade.com/developer/api/game#gem-ads",
           "signature": "readonly ads: AdsApi",
           "documented": true,
-          "summary": "One full-screen cross-promotion at a natural break in play, rendered by\nthe arcade over your paused game.\n\nAsk at a break the player already expects — a level ending, a round\nfinishing — never mid-input. **The answer is usually no, and that is\nordinary rather than a failure:** carry straight on, and draw no\nplaceholder while you wait.\n\nNothing here rejects. The arcade pauses your game while a panel is up and\nresumes it when the promise settles, so you do not pause anything yourself.\n\n⚠️ `shown` **grants nothing.** It is not a receipt and not an entitlement,\nand a reward must never be handed out on the strength of it.\n\nYou are told no reason for a no, and there is nothing to infer from one.",
+          "summary": "One full-screen cross-promotion at a natural break in play, rendered by\nthe arcade over your paused game.\n\nAsk at a break the player already expects — a level ending, a round\nfinishing — never mid-input. **The answer is usually no, and that is\nordinary rather than a failure:** carry straight on, and draw no\nplaceholder while you wait.\n\nNothing here rejects. The arcade pauses your game while a panel is up and\nresumes it when the promise settles, so you do not pause anything yourself.\n\n⚠️ `shown` **grants nothing.** It is not a receipt and not an entitlement,\nand a reward must never be handed out on the strength of it.\n\nYou are told no reason for a no, and there is nothing to infer from one\nabout the player. What you can read is your own economy:\n`rewardedStatus(placement)` says whether a rewarded placement could pay\nright now under your own declared caps — never whether an ad will play.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -8895,6 +9446,29 @@
             }
           ]
         },
+        {
+          "id": "Gem.vibration",
+          "name": "vibration",
+          "anchor": "gem-vibration",
+          "group": "start",
+          "url": "https://gemarcade.com/developer/api/game#gem-vibration",
+          "signature": "readonly vibration: VibrationApi",
+          "documented": true,
+          "summary": "Vibrate the player's device — call this instead of `navigator.vibrate`,\nwhich does nothing on any iPhone. It takes the same pattern and returns the\nsame boolean, calls `navigator.vibrate` itself where that works, and asks\nthe arcade to vibrate where it does not.\n\nRead [VibrationApi.available](https://gemarcade.com/developer/api/game#vibrationapi-available) live, after `awaitBridge()`, to decide\nwhether to show your game's vibration toggle — on an iPhone it is `false`\nuntil the bridge connects — and check that toggle before every call:\n\n```js\nawait gem.awaitBridge();\nvibrationRow.hidden = !gem.vibration.available;\n\nfunction onHit() {\n  if (settings.vibration) gem.vibration.vibrate(30);\n}\n```\n\n- **Never call `navigator.vibrate`**, guarded or not, and never fall back\n  to it: this already does.\n- **Nothing vibrates before the player's first tap** in your game; the\n  call returns `false` until then.\n- **Stop on pause** with `gem.vibration.vibrate(0)`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": [
+            {
+              "slug": "vibration",
+              "anchor": null,
+              "url": "https://gemarcade.com/developer/docs/vibration"
+            }
+          ]
+        },
         {
           "id": "Gem.analytics",
           "name": "analytics",
@@ -8983,7 +9557,7 @@
           "url": "https://gemarcade.com/developer/api/game#gem-friends",
           "signature": "readonly friends: FriendsApi",
           "documented": true,
-          "summary": "The signed-in player's accepted friends — display identity only,\nread-only, paginated — and the one ask that reaches past them:\n[FriendsApi.challenge](https://gemarcade.com/developer/api/game#friendsapi-challenge), which asks the Arcade to send a friend a\nchallenge after the player confirms it in the Arcade's own sheet.\n\nEvery accepted friend appears whether or not they have played this game;\nan invite-a-friend flow needs exactly the ones who have not. The graph\nitself — requests, accepts, blocks, presence — stays on the Arcade: there\nis nothing here to mutate and nothing that says who is online.\n\nA player surface only. In a context with no player — a game server — the\nplatform refuses the read; a server has no friend list.",
+          "summary": "The signed-in player's accepted friends — display identity only,\nread-only, paginated — and the one ask that reaches past them:\n[FriendsApi.challenge](https://gemarcade.com/developer/api/game#friendsapi-challenge), which asks the Arcade to send a friend a\nchallenge after the player confirms it in the Arcade's own sheet. The\nreceiving side reads the challenges this player holds in this game:\n[FriendsApi.launchedChallenge](https://gemarcade.com/developer/api/game#friendsapi-launchedchallenge) for the one this frame was launched\nwith, [FriendsApi.inbox](https://gemarcade.com/developer/api/game#friendsapi-inbox) for all of them, and\n[FriendsApi.markAnswered](https://gemarcade.com/developer/api/game#friendsapi-markanswered) once one has been played.\n\nEvery accepted friend appears whether or not they have played this game;\nan invite-a-friend flow needs exactly the ones who have not. The graph\nitself — requests, accepts, blocks, presence — stays on the Arcade: there\nis nothing here to mutate but a challenge's own answered mark, and nothing\nthat says who is online.\n\nA player surface only. In a context with no player — a game server — the\nplatform refuses the read; a server has no friend list.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -9166,6 +9740,30 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "Gem.showPortraitBorders",
+          "name": "showPortraitBorders",
+          "anchor": "gem-showportraitborders",
+          "group": "start",
+          "url": "https://gemarcade.com/developer/api/game#gem-showportraitborders",
+          "signature": "showPortraitBorders(name: string | null): void",
+          "documented": true,
+          "summary": "Choose which of your store page's **portrait borders** the arcade paints on\neither side of your game, or `null` for none.\n\nOn a desktop browser, the arcade's desktop app or a television, the arcade\nshows a portrait-only game as a centred portrait column. With borders\ndeclared on your store page (`media.portrait_borders`), it paints one of\nthose images beside the column instead of its own bars. Call this at\nstart-up and on every theme change, with the border that goes with what is\non screen:\n\n```js\nconst BORDERS = new Set(['meadow', 'alpine']); // the names your store page declares\n\nfunction applyTheme(id) {\n  document.body.dataset.theme = id;\n  gem.showPortraitBorders(BORDERS.has(id) ? id : null); // null: a theme with no art\n}\n```\n\nUntil your first call the arcade shows the page's first border. Whether\nyour game is letterboxed at all is decided by your store page's\n`orientations`, never by this call, so call it unconditionally: before the\nconnection exists your choice is held and sent when it connects, a burst of\nchanges (a picker previewing on hover) reaches the arcade as its final\nvalue, and an arcade that paints no borders is simply not told. The arcade\nowns the change itself — when and how the image swaps — and sends no\nacknowledgement.\n\nA name is 1 to 40 characters of `a-z`, `0-9`, `_` and `-`, starting with a\nletter or digit — the store page's own rule. Anything else is refused with\na console warning and never sent; a valid name your page does not declare\nis ignored by the arcade, which keeps the image it is showing.",
+          "deprecated": null,
+          "params": [
+            {
+              "name": "name",
+              "type": "string | null",
+              "optional": false,
+              "summary": null
+            }
+          ],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "Gem.cueReward",
           "name": "cueReward",
@@ -10411,7 +11009,7 @@
           "url": "https://gemarcade.com/developer/api/game#playerbadge",
           "signature": "interface PlayerBadge",
           "documented": true,
-          "summary": "One badge a player has equipped — an icon the platform shows beside their\nname.\n\nAlways an empty list today; platform achievements fill it with at most two.",
+          "summary": "One badge a player has equipped — an icon the platform shows beside their\nname.\n\nA player wears at most two, in the order they arranged them. Each is an icon\nthey own — an achievement in any game may have awarded it.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -10581,7 +11179,7 @@
           "url": "https://gemarcade.com/developer/api/game#playeridentity-badges",
           "signature": "readonly badges: readonly PlayerBadge[]",
           "documented": true,
-          "summary": "The player's equipped badges, in display order. Always a list, and empty\nuntil platform achievements equip any.",
+          "summary": "The player's equipped badges, at most two, in the order the player\narranged them. Always a list — empty when they wear none, or when their\nidentity is withheld — so draw what is there and key on `itemId`.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -13221,6 +13819,64 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "VibrationApi",
+          "name": "VibrationApi",
+          "anchor": "vibrationapi",
+          "group": "vibration",
+          "url": "https://gemarcade.com/developer/api/game#vibrationapi",
+          "signature": "interface VibrationApi",
+          "documented": true,
+          "summary": "`gem.vibration` — vibrate the player's device, on every platform that can.\nCall it instead of `navigator.vibrate`, which does nothing on any iPhone.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "VibrationApi.available",
+          "name": "available",
+          "anchor": "vibrationapi-available",
+          "group": "vibration",
+          "url": "https://gemarcade.com/developer/api/game#vibrationapi-available",
+          "signature": "readonly available: boolean",
+          "documented": true,
+          "summary": "Whether this device can vibrate for your game: decide from this whether to\nshow your game's vibration toggle. Read it live, every time — after\n`awaitBridge()`, and again when your settings screen opens — never once at\nboot: on an iPhone it is `false` until the bridge connects.\n\n`false` on a desktop with a mouse, in iOS Safari, in Firefox, before the\nbridge is up where vibration goes through the arcade, and after the\nsession ends there.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "VibrationApi.vibrate",
+          "name": "vibrate",
+          "anchor": "vibrationapi-vibrate",
+          "group": "vibration",
+          "url": "https://gemarcade.com/developer/api/game#vibrationapi-vibrate",
+          "signature": "vibrate(pattern: number | readonly number[]): boolean",
+          "documented": true,
+          "summary": "Vibrate: takes what `navigator.vibrate` takes and returns what it returns.\n`pattern` is a duration in milliseconds, or an array of alternating\nvibration and pause durations, starting with a vibration. `0` or `[]`\nstops a pattern that is still playing, and every call replaces it.\n\nThe pattern is capped at 99 entries of at most 10 000 ms each, and at\n10 000 ms in all: a longer one is cut short, not refused.\n\nCheck your game's own vibration toggle before every call. Returns `false`,\nand vibrates nothing, when [VibrationApi.available](https://gemarcade.com/developer/api/game#vibrationapi-available) is false, before\nthe player's first tap or key press in your game, for a pattern with a\nnegative or non-finite entry, and past 600 calls a minute; each of the last\nthree says so once a session through your `log`. `true` means the pattern\nwas accepted, never that a motor moved.",
+          "deprecated": null,
+          "params": [
+            {
+              "name": "pattern",
+              "type": "number | readonly number[]",
+              "optional": false,
+              "summary": null
+            }
+          ],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "LeaderboardPeriod.id",
           "name": "id",
@@ -13450,7 +14106,7 @@
           "url": "https://gemarcade.com/developer/api/game#leaderboardentry-badges",
           "signature": "readonly badges: readonly PlayerBadge[]",
           "documented": true,
-          "summary": "The player's equipped badges, in display order. Always a list, and empty\nuntil platform achievements equip any.",
+          "summary": "The player's equipped badges, at most two, in the order the player\narranged them. Always a list — empty when they wear none, or when their\nidentity is withheld — so draw what is there and key on `itemId`.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -15323,7 +15979,7 @@
           "url": "https://gemarcade.com/developer/api/game#playerprofile-badges",
           "signature": "readonly badges: readonly PlayerBadge[]",
           "documented": true,
-          "summary": "The player's equipped badges, in display order. Always a list, and empty\nuntil platform achievements equip any.",
+          "summary": "The player's equipped badges, at most two, in the order the player\narranged them. Always a list — empty when they wear none, or when their\nidentity is withheld — so draw what is there and key on `itemId`.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -18018,7 +18674,7 @@
           "url": "https://gemarcade.com/developer/api/game#roommember-badges",
           "signature": "readonly badges: readonly PlayerBadge[]",
           "documented": true,
-          "summary": "The player's equipped badges, in display order. Always a list, and empty\nuntil platform achievements equip any.",
+          "summary": "The player's equipped badges, at most two, in the order the player\narranged them. Always a list — empty when they wear none, or when their\nidentity is withheld — so draw what is there and key on `itemId`.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -19169,7 +19825,7 @@
           "url": "https://gemarcade.com/developer/api/game#showcasefriendentry-badges",
           "signature": "readonly badges: readonly PlayerBadge[]",
           "documented": true,
-          "summary": "The player's equipped badges, in display order. Always a list, and empty\nuntil platform achievements equip any.",
+          "summary": "The player's equipped badges, at most two, in the order the player\narranged them. Always a list — empty when they wear none, or when their\nidentity is withheld — so draw what is there and key on `itemId`.",
           "deprecated": null,
           "params": [],
           "returns": null,