@indiegems/gem-web-sdk 7.3.1 → 7.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indiegems/gem-web-sdk",
-  "version": "7.3.1",
+  "version": "7.4.1",
   "description": "postMessage bridge contract between gem-web and browser-playable games",
   "license": "UNLICENSED",
   "type": "module",
@@ -40,6 +40,11 @@
     "!dist/*.map",
     "!dist/gem-web-sdk.devtools.min.js",
     "schema/bridge.v1.json",
-    "brand/*.png"
+    "schema/capabilities.public.json",
+    "brand/*.png",
+    "docs/*.md",
+    "docs/manifest.json",
+    "docs/api/*.md",
+    "docs/api/reference.json"
   ]
 }

package/schema/bridge.v1.json

@@ -794,6 +794,41 @@
       "rateLimit": { "perMinute": 12 }
     },
 
+    {
+      "type": "gem.earnAllowanceChanged",
+      "direction": "parentToFrame",
+      "transport": "port",
+      "$comment": [
+        "The player's earn allowance for this game MAY have changed, so the",
+        "frame should re-read it from gem-api",
+        "(`GET /v1/games/{game_id}/players/me/earn-allowance`) if it shows it.",
+        "Gated on `earnAllowance`: a parent sends it only when",
+        "`frameSupports('earnAllowance')`.",
+        "",
+        "NO FIELDS, AND IT SHOULD STAY THAT WAY. The frame re-reads from gem-api,",
+        "the authority, so the bridge never becomes a second source of truth for",
+        "the figure. This message never carries `limit`, `earned`, `remaining`, a",
+        "balance, a grant amount or any game's id: a figure here would be one a",
+        "parent could get wrong, and one the game could not tell from the real",
+        "answer. `gem.requestContext` and `gem.ready` are the precedent for a",
+        "message that carries only its own occurrence.",
+        "",
+        "WHEN A PARENT MAY SEND IT: after a grant by this game, or after a",
+        "platform-wide change the parent knows moved this game's consolidated",
+        "figure. NOT after another game's grant that left this game's figure",
+        "where it was: that send would tell this game, to the second, when",
+        "another game paid the player -- a timing oracle for payouts this game",
+        "is otherwise never shown. It should coalesce a burst -- one trailing",
+        "send per second or so -- so it stays well inside the limit.",
+        "",
+        "A HINT, NOT A GUARANTEE. A game reads the allowance on its own schedule",
+        "and never depends on this message to read it; an embedder that never",
+        "sends it is not defective. The SDK makes no request because of it."
+      ],
+      "fields": {},
+      "rateLimit": { "perMinute": 30 }
+    },
+
     {
       "type": "gem.viewport",
       "direction": "parentToFrame",
@@ -823,11 +858,34 @@
         "variables stay unset and a game's `var(--gem-safe-top, env(...))` falls",
         "back to the browser's own answer.",
         "",
-        "INSETS ONLY — no chrome state, no form factor, no orientation. What the",
+        "GEOMETRY ONLY — no chrome state, no form factor, no orientation. What the",
         "parent's chrome is doing is the parent's business, and a form-factor",
         "signal crossing the bridge is an owner decision this message does not",
-        "reopen (public-docs/what-a-game-must-do.md, the television section). A",
-        "game learns that part of its box is unusable, not why.",
+        "reopen (docs/what-a-game-must-do.md, the television section). A",
+        "game learns WHICH part of its box is unusable, never why.",
+        "",
+        "AMENDED, DELIBERATELY: this message once carried insets only. It now also",
+        "carries `reserved`, rectangles of the frame covered by the parent's own",
+        "controls floating over the game (a Back tab in a corner, the wallet chips",
+        "shown beside it). An inset can only describe a full-width or full-height band,",
+        "and a corner tab expressed as a top inset would take the whole top strip",
+        "from a full-bleed game to clear a control a few dozen pixels wide. A",
+        "rectangle says exactly which part, and still says nothing about what the",
+        "control is, whether it is showing a balance, or why it is there: the",
+        "principle above holds, only the shape of the answer is finer.",
+        "",
+        "THE FOLD, for a frame that cannot read `reserved`. A frame that did not",
+        "advertise `reservedAreas` predates the field and would ignore it (a",
+        "receiver ignores unknown fields), leaving its HUD under the parent's",
+        "control. So a conforming parent sends `reserved` ONLY to a frame that",
+        "advertised `reservedAreas`, with the true insets beside it; to any other",
+        "frame it sends NO `reserved` and instead folds the area into",
+        "`insets.top`: the larger of the true top inset and the bottom edge",
+        "(`y + height`) of every reserved rectangle that touches the frame's top",
+        "edge (`y` of 0). A game honouring `--gem-safe-top` then clears the control",
+        "at the cost of a full-width band, which is the best an older frame can",
+        "be told. A reserved rectangle that does not touch the top edge has no",
+        "fold and is not sent to such a frame at all.",
         "",
         "NOT the TV overscan allowance. `env()` is 0 on every television and the",
         "title-safe margin is documented as the game's own; folding the arcade's",
@@ -847,6 +905,30 @@
             "bottom": { "kind": "int", "min": 0, "max": 4096 },
             "left": { "kind": "int", "min": 0, "max": 4096 }
           }
+        },
+        "reserved": {
+          "kind": "array",
+          "maxItems": 4,
+          "optional": true,
+          "$comment": [
+            "Rectangles of the frame covered by the parent's controls, in CSS px of",
+            "the frame's own coordinate space measured from its top-left corner — the",
+            "same space as `insets` and `gem.rewardCue`'s `origin`. A game must not put",
+            "essential UI or a touch target inside one. Sent only to a frame that",
+            "advertised `reservedAreas`; absent means the parent reserves nothing, and",
+            "an EMPTY array means the same, said explicitly. Rounded OUTWARD by the",
+            "sender, like the insets: the conservative direction keeps a button clear",
+            "of the control. 16384 is a bound, not a size."
+          ],
+          "items": {
+            "kind": "object",
+            "fields": {
+              "x": { "kind": "int", "min": 0, "max": 16384 },
+              "y": { "kind": "int", "min": 0, "max": 16384 },
+              "width": { "kind": "int", "min": 0, "max": 16384 },
+              "height": { "kind": "int", "min": 0, "max": 16384 }
+            }
+          }
         }
       },
       "rateLimit": { "perMinute": 60 }
@@ -945,7 +1027,7 @@
         "The parent holds that socket because it holds the player token and",
         "`POST /v1/ws/ticket` accepts only player tokens. The frame holds a",
         "game-scoped token by design, so it cannot open the socket and must not be",
-        "handed a credential for one. See public-docs/rooms-and-matches.md §3.",
+        "handed a credential for one. See docs/rooms-and-matches.md §3.",
         "",
         "CARRIES NO ROOM STATE. No member list, no display names, no join code, no",
         "connection details. The frame re-reads the room over its OWN token and",
@@ -1118,7 +1200,7 @@
         "look at a room, and cannot seat anybody in one.",
         "",
         "NO PARTY ID CROSSES. The payload gem-api sends carries one; it stops",
-        "here. The frame has no party surface (public-docs/p2p-and-parties.md",
+        "here. The frame has no party surface (docs/p2p-and-parties.md",
         "§7.1), and the v2 room routes deliberately replaced the platform party",
         "id with a room-scoped marker — relaying it here would put back the",
         "cross-game social-graph fact that removal was for.",
@@ -1197,7 +1279,7 @@
         "the frame over the frame's OWN TLS connection (POST",
         "/matches/{id}/join-credential), so a parent that rewrites an SDP cannot",
         "impersonate a peer — it can only break the connection. See",
-        "public-docs/p2p-and-parties.md §3.",
+        "docs/p2p-and-parties.md §3.",
         "",
         "`data` is gem-api's grammar, not this bridge's. It is emitted as a",
         "bounded plain-data object rather than a declared field list because the",
@@ -1378,7 +1460,7 @@
         "party name. A party is ACCOUNT-LEVEL AND CROSS-GAME — its record carries",
         "which other games the members suggest playing and what platforms they are",
         "on — so handing it to a game frame would export the player's social graph",
-        "and their activity across the whole catalog. See public-docs/p2p-and-parties.md",
+        "and their activity across the whole catalog. See docs/p2p-and-parties.md",
         "§6 and DESIGN.md §10."
       ],
       "fields": {
@@ -2210,6 +2292,155 @@
       "rateLimit": { "perMinute": 60 }
     },
 
+    {
+      "type": "gem.walletDisplay",
+      "direction": "frameToParent",
+      "transport": "port",
+      "$comment": [
+        "Whether the arcade shows the player's platform wallets (Gems, Tickets, the",
+        "achievement score) over the game right now — and, optionally, which of them.",
+        "",
+        "OPT-OUT. With no message at all, the parent shows EVERY wallet: a game that",
+        "does nothing gets them. A game hides them while it needs the screen — active",
+        "gameplay, typically — and shows them again on its menus.",
+        "",
+        "  visible: false                      hidden, except event pops (below)",
+        "  visible: true, no currencies/score  every wallet",
+        "  visible: true, currencies/score     only those: the slugs in `currencies`,",
+        "                                      plus the score if `score` is true",
+        "",
+        "The narrowing is in force when EITHER optional field is present, and is",
+        "ignored while `visible` is false. It is for a screen about one currency (a",
+        "ticket store); leaving it out is always safe. `currencies` are platform",
+        "currency slugs (`GEMS`, `ARCADE_TICKETS`), matched exactly and",
+        "case-sensitively against the wallets the parent draws; a slug it does not",
+        "draw is ignored. `score` is its own field so it can never collide with a slug.",
+        "",
+        "SCREEN STATE, NOT A TOGGLE. Each message is the whole answer and the latest",
+        "one wins; nothing accumulates. The SDK re-sends the latest state after every",
+        "handshake, so a parent that reconnects never shows wallets over gameplay the",
+        "game had hidden them from.",
+        "",
+        "EVENTS ARE THE PARENT'S AND OVERRIDE THIS. While wallets are hidden (or",
+        "narrowed away), the parent still pops one up briefly when something happens",
+        "to it: a reward cue, a pending grant, a landing, a spend, a daily-maximum",
+        "note, a score change. The game's state never cancels those. Only wallets",
+        "shown BECAUSE OF THIS STATE reserve space: they extend `gem.viewport`'s",
+        "`reserved`, and hiding them shrinks it back to the parent's own Back tab. An",
+        "event pop floats over the game and never moves its layout. Where the parent",
+        "docks its wallets beside the frame rather than over it, this changes",
+        "nothing.",
+        "",
+        "A PRESENTATION REQUEST ONLY. Not an authorization control, and it carries no",
+        "numbers: the parent takes every figure it shows from the platform. A game",
+        "never draws a platform balance itself and never implements a pending state.",
+        "",
+        "Gated by `walletDisplay`: sent only to a parent that advertised it."
+      ],
+      "fields": {
+        "visible": { "kind": "boolean" },
+        "currencies": {
+          "kind": "array",
+          "maxItems": 8,
+          "optional": true,
+          "items": { "kind": "string", "maxLength": 64 },
+          "$comment": "Narrow to these platform currency slugs while visible, each 1..64 characters; the SDK drops an empty or over-long entry on the way out rather than cutting it into a different slug."
+        },
+        "score": {
+          "kind": "boolean",
+          "optional": true,
+          "$comment": "With the narrowing: whether the achievement score is among the wallets shown."
+        }
+      },
+      "rateLimit": { "perMinute": 60 }
+    },
+
+    {
+      "type": "gem.requestShare",
+      "direction": "frameToParent",
+      "transport": "port",
+      "$comment": [
+        "Ask the arcade to share a link to this game - to a puzzle, a board, a",
+        "level - opened with the launch parameters in `params`. Gated by the",
+        "`share` capability: sent only to a parent that advertised it.",
+        "",
+        "WHY THE PARENT BUILDS THE LINK. A link the game built itself carries no",
+        "share token, does not unfurl with the game's own card, and the frame is",
+        "denied `clipboard-write`, so it has no copy fallback where the platform",
+        "share sheet is missing. The game says WHAT to open; the parent decides",
+        "whether to share, builds the URL, holds the token and renders every",
+        "surface.",
+        "",
+        "ONE WAY, AND NOTHING ANSWERS IT. No requestId, no text, no URL and no",
+        "game id travel in this message, and no message travels back. The game",
+        "never learns whether the player shared, cancelled or was refused, so it",
+        "has nothing to gate progress or a reward on. An empty `params` array is",
+        "valid: it shares the game with no deep link.",
+        "",
+        "WHAT THE PARENT OWES, none of which this schema can enforce:",
+        "",
+        "  REFUSE RESERVED KEYS. A key the parent reads from the play URL itself",
+        "  refuses the whole request: the reserved launch keys, the same list the",
+        "  SDK refuses before sending, which includes `play`, `channel`, `_s`,",
+        "  every `utm_` key, `fbclid`, `ttclid`, `gclid` and `msclkid`.",
+        "",
+        "  BUILD FROM THE FRAMED GAME, NEVER FROM THE MESSAGE. The link is",
+        "  `/games/<id>?play=1&<params>&_s=<token>`, where `<id>` is the game the",
+        "  parent framed. It never carries `channel`: a shared link opens the live",
+        "  game, whatever channel the sharer was playing.",
+        "",
+        "  ROUND-TRIP THE BUILT URL. Parse the built link's query with the parent's",
+        "  own launch-query parse and refuse the whole request if what comes back",
+        "  differs from what went in, in any key, value or order. Never trim to",
+        "  make it fit. The whole URL is capped at 2 KB.",
+        "",
+        "  CHECK ACTIVATION ON RECEIPT. Read `navigator.userActivation.isActive`",
+        "  synchronously when the message arrives, before any `await`. With it,",
+        "  share or copy in the same tick (a click in the frame activates its",
+        "  ancestors).",
+        "",
+        "  WITHOUT ACTIVATION, OPEN YOUR OWN SHARE PANEL. The player shares from",
+        "  the parent's chrome with a click of their own. Never write the",
+        "  clipboard unprompted.",
+        "",
+        "  ONE AT A TIME, AND CAPPED. One request in flight at a time, a 10 s",
+        "  cooldown after the player dismisses one, and 20 per session. A dropped",
+        "  request is logged by the parent, never surfaced to the player or the",
+        "  frame.",
+        "",
+        "  RETURN FOCUS TO THE FRAME when the sheet or panel closes, so the game's",
+        "  keyboard input keeps working.",
+        "",
+        "  THE TEXT IS THE PARENT'S. The share text is the parent's fixed,",
+        "  localized \"Play {game} on Gem Arcade\". No game-supplied text is",
+        "  shared: copy a game authored, sent under the platform's name, is a",
+        "  phishing kit with the platform's name on it.",
+        "",
+        "  SEND NOTHING BACK. No outcome, no acknowledgement, and no error for a",
+        "  refusal - not even for a malformed or reserved request.",
+        "",
+        "Everything in `params` is public: it is written into a link the player",
+        "hands to anyone. A game puts no personal identifier in it."
+      ],
+      "fields": {
+        "params": {
+          "kind": "array",
+          "maxItems": 16,
+          "items": {
+            "kind": "object",
+            "fields": {
+              "key": { "kind": "string", "maxLength": 64 },
+              "value": { "kind": "string", "maxLength": 512 }
+            }
+          }
+        }
+      },
+      "rateLimit": {
+        "perMinute": 6,
+        "$comment": "Bounds a BUGGY game. NOT a security control: a hostile game posts on the port it holds rather than calling the SDK. What bounds a player's experience is the parent's one-at-a-time rule, its cooldown and its per-session cap."
+      }
+    },
+
     {
       "type": "gem.frameStats",
       "direction": "frameToParent",
@@ -2957,6 +3188,208 @@
         }
       },
       "rateLimit": { "perMinute": 12 }
+    },
+    {
+      "type": "gem.requestFriendChallenge",
+      "direction": "frameToParent",
+      "transport": "port",
+      "$comment": [
+        "Ask the parent to send one friend challenge to one of the player's",
+        "friends, on the player's behalf. Gated by the `friendChallenges`",
+        "capability. Answered by `gem.friendChallengeResult`.",
+        "",
+        "WHY THIS CROSSES THE BRIDGE AT ALL. A game knows the moment a challenge",
+        "is worth sending - a board just beaten, a score just set - but a send",
+        "puts a card in another person's Arcade inbox, and that is an account-",
+        "session act the game-scoped token is refused by construction. So the game",
+        "ASKS, and the parent, which holds the account session, previews it,",
+        "renders its own confirmation sheet, and sends only on the player's Send.",
+        "This is a platform decision amending DESIGN.md section 10's 'no invites",
+        "in the frame'.",
+        "",
+        "NO GAME ID, NO CHANNEL AND NO TEXT ARE SENT, deliberately. The parent",
+        "takes the game and the channel from what it framed; a game id or a",
+        "channel the frame supplied would be one the frame chose. And the card's",
+        "words are not the game's to write here: the platform renders them",
+        "server-side from the template this game PUBLISHED in its config, filled",
+        "with `params`, and screened there. Game-authored copy, rendered inside",
+        "the platform's own chrome and delivered to someone else's inbox, is a",
+        "spam and phishing channel with the platform's name on it.",
+        "",
+        "WHAT THE PARENT OWES, none of which this schema can enforce:",
+        "",
+        "  ONE SHEET AT A TIME. An ask arriving while a challenge sheet - or any",
+        "  other sheet or dialog that holds the stage: a purchase, a sign-in",
+        "  prompt, a leave question - is open is answered `cancelled` with",
+        "  nothing rendered. The busy set is two-way: an open challenge sheet",
+        "  holds the stage against those asks too. Twelve sheets a minute is",
+        "  inside the rate limit below and is a consent-fatigue attack.",
+        "",
+        "  A QUIET INPUT WINDOW AFTER PAINT. The frame chooses the moment it asks,",
+        "  so a Send control that is actionable the instant it paints is a",
+        "  tap-jacking target. Quiet input on it briefly after paint, as for",
+        "  gem.requestPurchase.",
+        "",
+        "  RENDER ONLY FROM THE PREVIEW RESPONSE. The recipient's name, the game's",
+        "  title and the challenge line on the sheet come from the platform's",
+        "  preview of this ask, never from anything in this message. That is what",
+        "  makes the sheet something a game cannot forge.",
+        "",
+        "  TREAT EVERY FIELD AS UNTRUSTED TEXT. The generated validator checks",
+        "  type and length and nothing else - these strings may carry `../`,",
+        "  `%2e%2e`, NUL, newlines, RTL overrides and astral Unicode. Pre-check",
+        "  them (the grammar is on each field below), pass them to the platform",
+        "  only as body fields, never interpolate one into a path, a query or a",
+        "  log line, and never echo one to a player.",
+        "",
+        "NOT AN AUTHORIZATION CONTROL. The player's Send press in the parent's",
+        "chrome is the control, and the platform's account-session send is the",
+        "enforcement: it re-checks the friendship, the template, the params and",
+        "every budget, whatever reached it."
+      ],
+      "fields": {
+        "requestId": {
+          "kind": "string",
+          "maxLength": 64,
+          "$comment": "Opaque and frame-chosen. The parent treats it as an echo-only correlator and derives its own request identity, exactly as it does for gem.requestPurchase - it is not unique across tabs or reloads and must never key anything. It may also contain newlines and control characters, so it is not safe to write into a log line unescaped."
+        },
+        "playerId": {
+          "kind": "string",
+          "maxLength": 64,
+          "$comment": "The friend's player id, as `gem.friends.list()` returned it. BOTH the SDK and the parent require a UUID and answer anything else `invalid` with code `recipient_invalid` and no `param` - not `param_invalid` with `param: 'playerId'`, which a template may legitimately declare as a param of its own. A well-formed id is still frame-chosen: whether it names a friend is the platform's to judge, on the preview and again on the send, and a non-friend is answered `refused`."
+        },
+        "template": {
+          "kind": "string",
+          "maxLength": 64,
+          "$comment": "A template key from this game's published `friend_challenge_templates` config. The grammar is `^[a-z0-9][a-z0-9_-]{0,63}$`; codegen emits type and length only, so the SDK and the parent each pre-check the charset and answer a miss `invalid` with code `unknown_template`. Whether the key exists on the framed channel is the platform's to judge."
+        },
+        "params": {
+          "kind": "json",
+          "optional": true,
+          "$comment": [
+            "The template's params: a plain object of at most 8 keys, each value",
+            "a string or a safe integer. ABSENT when the game passed none, and the",
+            "parent reads absent as `{}`. Bounded by the message-level walk",
+            "(`maxMessageNodes` and the rest) rather than by a field list - the",
+            "`gem.gameContext.context` treatment - because the keys are declared",
+            "by the game's own config, not by this schema.",
+            "",
+            "The parent pre-checks the shape and the key count and answers a",
+            "miss `invalid` (`param_invalid`, or `param_undeclared` over 8 keys);",
+            "the platform is authoritative on every value. NEVER A PLAYER NAME:",
+            "the platform shows who sent the challenge itself, from its own",
+            "records."
+          ]
+        }
+      },
+      "rateLimit": {
+        "perMinute": 12,
+        "$comment": "Bounds a BUGGY game, and sits deliberately ABOVE the platform's own 10 sends a minute per sender, so the platform's `rate_limited` - with its Retry-After - is what a game actually meets, rather than an ask silently discarded here. NOT a security control: a hostile game posts on the port it holds rather than calling the SDK. What stops a game nagging is the parent's one-sheet-at-a-time rule and the player's own Send press."
+      }
+    },
+    {
+      "type": "gem.friendChallengeResult",
+      "direction": "parentToFrame",
+      "transport": "port",
+      "$comment": [
+        "The answer to one gem.requestFriendChallenge. Gated by the",
+        "`friendChallenges` capability.",
+        "",
+        "HOW A GAME SHOULD READ EACH ONE:",
+        "  accepted     - the player pressed Send and the platform accepted it.",
+        "                 NOT A DELIVERY RECEIPT: a delivery, a duplicate and",
+        "                 every drop - moderation, age, a mute, the recipient's",
+        "                 budget - answer identically, by design, so a game",
+        "                 cannot learn a stranger's settings from it. Do not",
+        "                 resend.",
+        "  cancelled    - the player closed the sheet, or something else held",
+        "                 the stage and nothing was rendered. Return to the game",
+        "                 SILENTLY; an error after a deliberate Cancel reads as a",
+        "                 bug.",
+        "  refused      - this player cannot send this one: a guest or signed",
+        "                 out, not friends with that player, or no access to",
+        "                 this channel. No reason rides on it, deliberately -",
+        "                 each is an account-state fact, and the parent owns",
+        "                 every account-state explanation. Age and moderation",
+        "                 NEVER answer refused: a denied or restricted sender",
+        "                 is answered accepted (a silent drop) or cancelled",
+        "                 (the sheet with Send withheld).",
+        "  unavailable  - no answer arrived, or the platform could not take a",
+        "                 challenge just now (switched off for this game, no",
+        "                 build on this channel, an outage). It does NOT prove",
+        "                 nothing was sent: the parent may have sent and the",
+        "                 answer been lost at a gate or a timeout. A game may",
+        "                 fall back to its own share sheet.",
+        "  rate_limited - the player's sending budget is spent. `retryAfterMs`",
+        "                 says for how long, and it can be a whole day.",
+        "  invalid      - a programming error for the developer, not the",
+        "                 player: `code` says which, and `param`, `channel`,",
+        "                 `configVersion` and `detail` narrow it.",
+        "",
+        "NEVER AUTO-RETRIED; ONLY A FRESH PLAYER ACTION MAY ASK AGAIN. Each ask",
+        "puts a sheet in front of a person, and a daily-budget wait can be 24",
+        "hours - a game that retried on `rate_limited` or `unavailable` would be",
+        "nagging, not recovering.",
+        "",
+        "EVERY FIELD EXCEPT `requestId` AND `outcome` IS OPTIONAL, AND A RECEIVER",
+        "MUST TOLERATE ANY COMBINATION OF THEM. Each one's comment says when the",
+        "Arcade sends it; that is a description of one sender, not a constraint",
+        "this schema makes. A bare {requestId, outcome} is always valid.",
+        "",
+        "`accepted`, `cancelled`, `refused` and `unavailable` CARRY NO REASON,",
+        "and a parent must not attach one: no `code`, no `detail`."
+      ],
+      "fields": {
+        "requestId": {
+          "kind": "string",
+          "maxLength": 64,
+          "$comment": "Echoes the gem.requestFriendChallenge that asked. Echo-only."
+        },
+        "outcome": {
+          "kind": "enum",
+          "values": ["accepted", "cancelled", "refused", "unavailable", "rate_limited", "invalid"],
+          "$comment": "SIX VALUES, CLOSED PERMANENTLY. `check-schema-freeze` treats a new enum value as breaking: an N-1 frame's generated validator refuses the whole message and the ask times out. So the vocabulary that may grow - why a request was invalid - lives in `code`, a string, and not here."
+        },
+        "code": {
+          "kind": "string",
+          "maxLength": 64,
+          "optional": true,
+          "$comment": "Sent with `outcome: 'invalid'`. One of `unknown_template`, `template_not_on_channel`, `param_invalid`, `param_undeclared`, `recipient_invalid` today - the BRIDGE vocabulary: the platform's own code with its `friend_challenge_` prefix stripped, plus `recipient_invalid`, which only the parent and the SDK raise. A STRING, NOT AN ENUM, deliberately, so the platform can add a detail code without a bridge break. The SDK passes it through verbatim; a receiver must not fail on a value it does not know."
+        },
+        "param": {
+          "kind": "string",
+          "maxLength": 64,
+          "optional": true,
+          "$comment": "Sent when `code` is `param_invalid` or `param_undeclared` and a single param key is known to be at fault. A key from the game's own config, echoed."
+        },
+        "channel": {
+          "kind": "string",
+          "maxLength": 16,
+          "optional": true,
+          "$comment": "Sent when `code` is `template_not_on_channel`: the channel the send named, whose promoted config lacks the template. A STRING, on `code`'s argument, so a new channel is not a bridge break. Reaches only a TEAM MEMBER of the game - everyone else is answered `unknown_template` - because only a team member can act on it, and non-release config is not everyone's to learn about."
+        },
+        "configVersion": {
+          "kind": "int",
+          "min": 0,
+          "max": 9007199254740991,
+          "optional": true,
+          "$comment": "Sent when `code` is `template_not_on_channel` and a config version is promoted to that channel: the version the template is missing from. Team members only, as `channel`."
+        },
+        "retryAfterMs": {
+          "kind": "int",
+          "min": 0,
+          "max": 86400000,
+          "optional": true,
+          "$comment": "Sent with `outcome: 'rate_limited'`: the platform's Retry-After, in milliseconds - the bridge's unit, as `gem.token.denied.retryAfterMs` and `gem.willTerminate.graceMs` are. At most a day, because the daily budget is the longest window. The SDK converts it to whole seconds for `GemApiError.retryAfterSeconds`. A floor for the next PLAYER-initiated ask, never a timer to retry on."
+        },
+        "detail": {
+          "kind": "string",
+          "maxLength": 300,
+          "optional": true,
+          "$comment": "Sent ONLY with `outcome: 'invalid'`, and never with any other outcome: the platform's own message for the refusal, truncated, for the developer's console. With `template_not_on_channel` it carries the command that fixes it. Never shown to a player."
+        }
+      },
+      "rateLimit": { "perMinute": 30 }
     }
   ],