@indiegems/gem-web-sdk 10.3.1 → 11.0.0

package/docs/manifest.json

@@ -33,8 +33,8 @@
     },
     {
       "file": "changelog.md",
-      "sha256": "25047a1c8498f92990b4d50768cf49d1cd4acd2a27dd42db595ca322aa56a2a9",
-      "updated": "2026-10-11T19:08:27Z"
+      "sha256": "49abc51f04333f12f5b88687a4d5cd702bac1ab28a8f19533f9253ba015ec41a",
+      "updated": "2026-10-11T20:42:08Z"
     },
     {
       "file": "cross-promotion.md",
@@ -68,8 +68,8 @@
     },
     {
       "file": "getting-started.md",
-      "sha256": "327be77c7b742f7ecfb3ca8f4869480e72942ea9f7293e25634c47c056a38eae",
-      "updated": "2026-10-11T19:08:27Z"
+      "sha256": "f46be1e65cc5936ad3c06c27f5eb33b250651003f8880c36bf4f0deb50b30e09",
+      "updated": "2026-10-11T20:42:08Z"
     },
     {
       "file": "inventory-and-catalogs.md",
@@ -123,8 +123,8 @@
     },
     {
       "file": "server-bundles.md",
-      "sha256": "c6bf3689c928b6cb24d86faa380e6ed4bece1f3dd6e8dfc71c1ff9de1ed0dd42",
-      "updated": "2026-10-11T19:08:27Z"
+      "sha256": "74b7d0964881a74ee12097bdee41afec12ca03d3feddb5a935bea7483a79967d",
+      "updated": "2026-10-11T20:42:08Z"
     },
     {
       "file": "serverless-functions-js.md",
@@ -148,8 +148,8 @@
     },
     {
       "file": "what-a-game-must-do.md",
-      "sha256": "c5797bd913fbd8c62fb3fbe83b6c8c6cb22f5aec984c0d56f3f0198c917fee7d",
-      "updated": "2026-10-11T18:48:12Z"
+      "sha256": "ab4f18f2c1cfccf54b01027dea77d229f0a9f086e373d6cfd4c741fd0004557f",
+      "updated": "2026-10-11T19:48:44Z"
     }
   ]
 }

package/docs/server-bundles.md

@@ -80,8 +80,8 @@ To check the download yourself: the package npm serves is, byte for byte, the fi
 also publishes on its download host, with the hash beside it:
 
 ```bash
-curl -fsSL -O https://downloads.gemarcade.com/sdk/v10.3.1/gem-web-sdk.tgz
-curl -fsSL https://downloads.gemarcade.com/sdk/v10.3.1/gem-web-sdk.tgz.sri
+curl -fsSL -O https://downloads.gemarcade.com/sdk/v11.0.0/gem-web-sdk.tgz
+curl -fsSL https://downloads.gemarcade.com/sdk/v11.0.0/gem-web-sdk.tgz.sri
 openssl dgst -sha384 -binary gem-web-sdk.tgz | openssl base64 -A
 ```
 

package/docs/what-a-game-must-do.md

@@ -924,12 +924,18 @@ same push as `muted` and `reducedMotion`, and again whenever the player changes
 | `gamepadLookSensitivity` | `20` to `400` | Look speed for a gamepad stick, as a percentage: `100` is 1×.                                                |
 | `invertLookY`    | `true` / `false`      | Up/down look inverted: pushing up or dragging up looks down. Pitch only, never yaw.                          |
 | `touchMovement`  | `'floating'` / `'fixed'` | On a touch screen, a movement stick that appears where the thumb lands, or one fixed in place.            |
+| `graphicsQuality` | `'low'` / `'medium'` / `'high'` | The graphics quality to start at on this device.                                                  |
+| `graphicsQualityAuto` | `true` / `false` | `true`: the Arcade picked that tier for this device, so you may adapt from it. `false`: the player picked it, so hold it. |
 
-The last four are the camera and controls settings: see
+`lookSensitivity` to `touchMovement` are the camera and controls settings: see
 [camera and look controls](#camera-and-look-controls) for telling the Arcade which of them your game
 uses, and for `gem.controls.look()`, which applies the two sensitivities and the invert for you. An
 older Arcade sends `recommended` without them; the SDK then fills each with its default (`100`,
-`100`, `false`, `'floating'`), so whenever `recommended` is not `null` all nine fields are there.
+`100`, `false`, `'floating'`). The last two are the starting graphics quality: see
+[graphics quality](#graphics-quality-the-arcade-picks-the-start-your-game-adapts). An older Arcade
+sends neither; the SDK then fills `graphicsQuality` from `batterySaver` (`'low'` when it is on,
+`'medium'` otherwise) and `graphicsQualityAuto` with `true`, and reads a tier it does not know as
+`'medium'`. So whenever `recommended` is not `null`, all eleven fields are there.
 
 **They are recommendations, and the player's own choice in your game always wins:**
 
@@ -949,6 +955,7 @@ older Arcade sends `recommended` without them; the SDK then fills each with its
 const DEFAULTS = {
   volume: 100, batterySaver: false, keyboardLayout: 'wasd', gamepadConfirm: 'south', vibration: true,
   lookSensitivity: 100, gamepadLookSensitivity: 100, invertLookY: false, touchMovement: 'floating',
+  graphicsQuality: 'medium',
 };
 let chosen = {}; // ONLY what the player picked in your settings screen
 
@@ -1067,6 +1074,66 @@ function frame(dt) {
   `touchMovement: 'game'` if your game only has one kind.
 - **No camera, no call.** A game with no camera to turn declares nothing and never calls `look`.
 
+## Graphics quality: the Arcade picks the start, your game adapts
+
+Players open a lot of games they have never played. Each one should open at a quality that suits
+the device instead of guessing and stuttering for the first minute. The work is split three ways:
+
+- **The Arcade picks the starting tier, per device**, and sends it as
+  `gem.prefs.recommended.graphicsQuality`: `'low'`, `'medium'` or `'high'`. On Auto, the player's
+  default, it is the tier the Arcade measured for this browser on this device. Otherwise it is the
+  player's own choice in the Arcade's Settings: Battery saver (`'low'`, and cap your frame rate and
+  cut effects too), Balanced (`'medium'`) or Best looking (`'high'`).
+- **Your game adapts from there while it runs**: one level down when frames stay slow, one level up
+  when there is plenty of room. `createQualityGovernor` does this for you, so you do not write a
+  frame-time monitor of your own.
+- **A choice the player made by hand is held.** `graphicsQualityAuto` is `false` when the player
+  picked the tier, and then you render at exactly that tier and never move it yourself. Your own
+  quality option, if your settings screen has one, still wins over the Arcade's, as every
+  [recommended setting](#start-from-the-players-arcade-wide-defaults-gemprefsrecommended) does.
+
+The governor is a separate import, so a game that does not use it carries none of it:
+
+```js
+import { createQualityGovernor } from '@indiegems/gem-web-sdk/quality';
+
+// Your own levels, lowest first. Names, or a count: `levels: 4` means levels 0 to 3.
+const governor = createQualityGovernor({
+  gem,
+  levels: ['low', 'medium', 'high'],
+  onChange: (level) => applyQuality(level), // shadows, resolution scale, particles…
+});
+applyQuality(governor.level); // where it starts; onChange is not called for that
+```
+
+What it does, so you know what to expect:
+
+- **It starts at the Arcade's tier.** A tier whose name is one of your levels starts there;
+  otherwise `'low'` is your lowest level, `'high'` your highest and `'medium'` your middle one. With
+  no Arcade (`gem.prefs` is `null`, or no `gem`), it starts in the middle.
+- **It measures your frames itself**, with `requestAnimationFrame`. If your loop already knows its
+  frame time, pass `manual: true` and call `governor.frame(dtMs)` once a frame instead; the first
+  `frame` call switches it to your numbers anyway, so frames are never counted twice.
+- **Down fast, up slow.** One level down after about 2 seconds of slow frames (the 90th-percentile
+  frame over 1.25 times your frame budget), one level up after about 10 seconds with room to spare
+  (under 0.7 times the budget), and never more than one level above where it started. A single
+  hitch is not slow frames. After every change it ignores 2 seconds of frames, and a level it
+  already had to leave takes twice as long to climb back into.
+- **Your budget is `1000 / targetFps`**, and `targetFps` is 60 unless you say. A game that caps
+  itself at 30 frames a second on battery saver passes `targetFps: 30`, or every frame reads as
+  slow.
+- **It never counts a paused game**: not while the Arcade has you paused (`gem.paused`), and not
+  while the tab is hidden. It also ignores the first 2 seconds, which are your game loading.
+- **It holds a hand-picked tier.** While `graphicsQualityAuto` is `false` it stays at the start and
+  never calls `onChange` on its own. Pass `auto: false` to hold whatever the Arcade says, or
+  `start: 'high'` to start from a level the player chose in your own settings.
+- **A new recommendation starts it over.** When the player changes Graphics in the Arcade's
+  Settings, the governor goes back to the new start and calls `onChange(level, 'reset')`. It reads
+  `gem.prefs` live, so you do not have to tell it.
+- **`governor.stats`** has what it measured (`fps`, `p90Ms` and `budgetMs`, the level's index,
+  whether it is holding or paused), for your own debug overlay. Call `governor.dispose()` when your
+  game stops rendering for good.
+
 ## The Arcade's menu
 
 The Arcade keeps one button over every game, on every device: the Gem, at the top-left. Its menu is
@@ -1390,41 +1457,91 @@ This is a platform rule, not advice — see
 
 ### Arcade avatars: the character the player wears, and changing it mid-game
 
-Some games draw **Arcade avatars**: whole characters the player owns as Arcade portrait items and
-wears as their Arcade portrait (store tag `arcade-avatars`). Such a game keys its own model on
-**`avatarIconId`**, the worn item's id — on `gem.player` for the signed-in player, as on every room
-member — rather than on the thumbnail.
+Some games draw **Arcade avatars** (store tag `arcade-avatars`): the player's look in your game is
+something they own and wear in the Arcade. The Arcade's avatar picker has **two tabs**, and they
+are **two separate worn choices** — wearing one never changes the other:
 
-**Redraw from `onPlayer`, not from boot alone.** The Arcade sends the player again whenever the
-portrait they wear changes, including mid-game from the Arcade's own menu, without your game
-asking. `onPlayer` runs and `gem.player` holds the new value; a field missing from the new player
-is missing now.
+| Tab | What the player wears | On `gem.player` and every room member |
+|---|---|---|
+| **2D** | a portrait — a picture | `avatarIconId`, `avatarIconUrl` (`avatar_icon_id`, `avatar_icon_url` on the wire) |
+| **3D** | a 3D character — a rigged model | `avatar3dId`, `avatar3dModelUrl`, `avatar3dIconUrl` (`avatar_3d_id`, `avatar_3d_model_url`, `avatar_3d_icon_url`) |
 
-**A "Change avatar" button belongs in your own UI**, and `gem.openAvatarPicker()` opens the
-Arcade's picker from it. The Arcade pauses your game while the picker is open, saves the player's
-choice, sends the player again, and resumes you:
+- **`avatar3dId`** is the worn 3D character's item id. Absent means none is worn — draw your
+  game's default look.
+- **`avatar3dModelUrl`** is its model: a binary glTF (`.glb`, a few hundred kB) with one rig,
+  `root > body > (head, arm_l, arm_r > hand_socket, leg_l, leg_r)`, sometimes with animation clips
+  (an idle, say). It never changes at its URL, so cache it by URL.
+- **`avatar3dIconUrl`** is a rendered portrait of that character, for a roster or a menu where
+  loading the model is too much. It is **not** the 2D portrait.
+
+**Draw the 3D character, falling back to what you did before.** A game that drew characters
+before the 3D tab existed keyed its own models on `avatarIconId`. Keep that mapping as the
+fallback, and prefer the 3D character when one is worn:
 
 ```js
-const gem = createGem({ onPlayer: (p) => hero.wear(avatarOfItem(p.avatarIconId)) });
+import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
+import { platformIconUrl } from '@indiegems/gem-web-sdk/sdk';
+
+const loader = new GLTFLoader();
+
+async function characterFor(p) {
+  // 1. The 3D character the player wears — the platform's own model.
+  const url = platformIconUrl(p.avatar3dModelUrl); // pins the host, as for pictures
+  if (p.avatar3dId && url) {
+    try {
+      const gltf = await loader.loadAsync(url);
+      return { scene: gltf.scene, clips: gltf.animations };
+    } catch {
+      // A model that fails to load is not a reason to show nothing.
+    }
+  }
+  // 2. Your old mapping of the worn 2D portrait, then your default.
+  return myModelForPortrait(p.avatarIconId) ?? myDefaultCharacter();
+}
+
+const gem = createGem({ onPlayer: async (p) => hero.wear(await characterFor(p)) });
+```
+
+- **Pass every URL through `platformIconUrl` first** — the model too. Loading it is a request that
+  carries your player's `Referer`, so only the platform's own item host is allowed; anything else
+  reads as absent. Against a development backend that includes the development image host, so
+  there the fallback is what you see.
+- **Attach things by the rig's names**, not by your old model's: a held item goes on
+  `hand_socket`. Play the model's own clips when it has them; your game's animations may not fit
+  its rig.
+- **Keep loading off the critical path.** Start the boot with your default look and swap the
+  character in when the model arrives; a player on a slow connection should not wait for it.
+
+**Redraw from `onPlayer`, not from boot alone.** The Arcade sends the player again whenever what
+they wear changes — either tab — including mid-game from the Arcade's own menu, without your game
+asking. `onPlayer` runs and `gem.player` holds the new values; a field missing from the new player
+is missing now (a player who takes off their 3D character has no `avatar3dId`).
 
+**A "Change avatar" button belongs in your own UI**, and `gem.openAvatarPicker()` opens the
+Arcade's picker from it. Pass `{ tab: '3d' }` or `{ tab: '2d' }` to open on a tab; omit it and
+the Arcade decides (a game tagged `arcade-avatars` gets the 3D tab). The Arcade pauses your game
+while the picker is open, saves the player's choice, sends the player again, and resumes you:
+
+```js
 changeAvatar.hidden = !gem.avatarPickerAvailable; // read it live
 changeAvatar.onclick = () => {
-  if (!gem.openAvatarPicker()) changeAvatar.hidden = true;
+  if (!gem.openAvatarPicker({ tab: '3d' })) changeAvatar.hidden = true;
 };
 ```
 
 - **`gem.avatarPickerAvailable`** says whether the Arcade will open its picker here. It is `false`
   outside the Arcade, before the bridge is up, and under an embedder that has no picker.
 - **`gem.openAvatarPicker()`** returns `true` when the Arcade was asked and `false` when it was not
-  (the same cases, or more than six asks a minute). It never throws and never waits.
+  (the same cases, or more than six asks a minute). It never throws and never waits. An Arcade
+  older than the tabs ignores `tab` and opens its picker as before.
 - **Nothing answers it.** The outcome is the new player through `onPlayer`. A player who closes the
   picker unchanged produces nothing, so never wait for an answer or poll `gem.player`.
 
-**Your server is not told.** A server-authoritative game reads each member's `avatar_icon_id` from
-the room read (`GET /v1/games/{game_id}/game-rooms/{game_room_id}`, or `gem.room.get()` on a
-dedicated server), and nothing pushes a change to it. So when `onPlayer` brings a different
-`avatarIconId`, have your client tell your server, and have the server **re-read the room** —
-never trust the id the client sends.
+**Your server is not told.** A server-authoritative game reads each member's `avatar_3d_id`,
+`avatar_3d_model_url` and `avatar_icon_id` from the room read
+(`GET /v1/games/{game_id}/game-rooms/{game_room_id}`, or `gem.room.get()` on a dedicated server),
+and nothing pushes a change to it. So when `onPlayer` brings a different avatar, have your client
+tell your server, and have the server **re-read the room** — never trust an id the client sends.
 
 ## Which backend — no longer yours, and what the override is for
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indiegems/gem-web-sdk",
-  "version": "10.3.1",
+  "version": "11.0.0",
   "description": "postMessage bridge contract between gem-web and browser-playable games",
   "license": "UNLICENSED",
   "type": "module",
@@ -35,6 +35,10 @@
       "types": "./dist/function.d.ts",
       "import": "./dist/gem-web-sdk.function.js"
     },
+    "./quality": {
+      "types": "./dist/quality.d.ts",
+      "import": "./dist/gem-web-sdk.quality.js"
+    },
     "./schema": "./schema/bridge.v1.json",
     "./brand/*": "./brand/*"
   },

package/schema/bridge.v1.json

@@ -557,7 +557,13 @@
         "from the parent's menu. A frame replaces its whole copy with each one; a",
         "field absent from the latest message is absent now. There is no other",
         "signal that the portrait changed, and no reply to the request that",
-        "opened the picker: this message is the outcome."
+        "opened the picker: this message is the outcome.",
+        "",
+        "The WORN 3D CHARACTER (`avatar3dId`, `avatar3dModelUrl`,",
+        "`avatar3dIconUrl`) is re-sent the same way: whenever it changes, from",
+        "either tab of the parent's picker, the whole message goes again. It is",
+        "a separate worn choice from the portrait — wearing one never changes",
+        "the other — so a message may carry either, both or neither."
       ],
       "fields": {
         "untrusted": {
@@ -620,6 +626,52 @@
             "the way it drops a non-digit `discriminator`."
           ]
         },
+        "avatar3dId": {
+          "kind": "string",
+          "maxLength": 64,
+          "optional": true,
+          "$comment": [
+            "The item-definition id of the 3D CHARACTER the player wears (gem-api",
+            "`avatar_3d_id`, a UUID; item type `avatar_3d`) — the same id a",
+            "game-room member's `avatar_3d_id` carries. A game that draws Arcade",
+            "avatars keys its character on this first, and falls back to its own",
+            "mapping of `avatarIconId` when it is absent.",
+            "",
+            "INDEPENDENT of `avatarIconId`: the portrait and the 3D character are",
+            "two worn choices, and wearing one never changes the other. Absent",
+            "means no 3D character is worn (the game's default look), or an older",
+            "parent; a parent never sends an empty string. Sent with",
+            "`avatar3dModelUrl` and `avatar3dIconUrl`, all three describing the",
+            "same item.",
+            "",
+            "Bounded here and shape-checked by the frame, exactly as `avatarIconId`",
+            "is and for the same reason: the frame keeps it only when it is a UUID."
+          ]
+        },
+        "avatar3dModelUrl": {
+          "kind": "string",
+          "maxLength": 2048,
+          "format": "url",
+          "optional": true,
+          "$comment": [
+            "The worn 3D character's MODEL (gem-api `avatar_3d_model_url`): a",
+            "binary glTF (`.glb`, `model/gltf-binary`) on the platform's item CDN,",
+            "one rig `root > body > (head, arm_l, arm_r > hand_socket, leg_l,",
+            "leg_r)`, possibly with animation clips. Immutable at its URL. Absent",
+            "when no 3D character is worn. Structurally validated only, like",
+            "`avatarIconUrl`, with the same pin caveat: THE CONSUMER MUST PIN THE",
+            "ORIGIN before fetching it — the SDK's `platformIconUrl` does, for",
+            "models as for pictures — or a hostile parent supplies a request-time",
+            "beacon carrying the Referer."
+          ]
+        },
+        "avatar3dIconUrl": {
+          "kind": "string",
+          "maxLength": 2048,
+          "format": "url",
+          "optional": true,
+          "$comment": "The worn 3D character's PORTRAIT RENDER (gem-api `avatar_3d_icon_url`) — a picture of the model, for a roster or a menu where loading the model is too much. NOT the 2D portrait (`avatarIconUrl`), which is a separate worn choice. Absent when no 3D character is worn. Same pin caveat as `avatarIconUrl`."
+        },
         "badges": {
           "kind": "array",
           "maxItems": 2,
@@ -804,7 +856,8 @@
           "$comment": [
             "The player's ARCADE-WIDE DEFAULTS for this device, which the Arcade",
             "keeps in its own Settings: a starting volume, battery saver, a keyboard",
-            "layout, the gamepad's confirm button, and vibration. RECOMMENDATIONS",
+            "layout, the gamepad's confirm button, vibration, the camera and",
+            "controls settings and a starting graphics quality. RECOMMENDATIONS",
             "ONLY. The game's own saved settings win: a game starts a setting from",
             "here only while the player has made no choice of their own in that",
             "game, and never overwrites one the player made because this changed.",
@@ -824,6 +877,16 @@
             "the game side all four are present whenever the object is. A game says",
             "which of them it leaves to the player with `gem.controlsDeclare`.",
             "",
+            "THE GRAPHICS TWO ARE OPTIONAL INSIDE IT TOO (owner decision",
+            "2026-10-11): `graphicsQuality` and `graphicsQualityAuto`, the quality",
+            "a game STARTS at on this device. The Arcade picks the start (the",
+            "player's Graphics setting, or the tier it detected for this device on",
+            "Auto); the game adapts from there while it runs, and holds the start",
+            "when the player picked it by hand. A parent built against an older SDK",
+            "omits them, and the SDK fills `graphicsQuality` from `batterySaver`",
+            "(`low` when it is on, `medium` otherwise) and `graphicsQualityAuto`",
+            "with true, so on the game side both are present whenever the object is.",
+            "",
             "`muted`, `reducedMotion` and `showFrameStats` stay where they are, at",
             "the top of this message, and keep their meaning: they are the Arcade's",
             "own state the frame acts on, not a recommendation. The Arcade starts",
@@ -900,6 +963,31 @@
                 "only `floating` or `fixed` today, and the SDK maps any other value to",
                 "the default, `floating`, so a game only ever sees those two."
               ]
+            },
+            "graphicsQuality": {
+              "kind": "string",
+              "maxLength": 16,
+              "format": "code",
+              "optional": true,
+              "$comment": [
+                "The graphics quality a game should START at on this device: `low`,",
+                "`medium` or `high`. The player's Graphics setting decides it --",
+                "Battery saver sends `low`, Balanced `medium`, Best looking `high`,",
+                "and Auto (the default) sends the tier the Arcade detected for this",
+                "device. A starting point, not a cap: a game adapts from here while it",
+                "runs unless `graphicsQualityAuto` is false.",
+                "",
+                "A CODE, NOT AN ENUM, so the vocabulary can grow without costing an",
+                "older frame the whole message (see WIDENING above): a parent sends",
+                "only `low`, `medium` or `high` today, and the SDK maps any other",
+                "value to `medium`, so a game only ever sees those three. When it is",
+                "absent the SDK fills `low` if `batterySaver` is true, else `medium`."
+              ]
+            },
+            "graphicsQualityAuto": {
+              "kind": "boolean",
+              "optional": true,
+              "$comment": "True when the Arcade detected `graphicsQuality` for this device (the player left Graphics on Auto), so the game may step its quality up or down from there as it measures frames; false when the player picked it by hand, so the game holds it and changes it only when the player does (in the Arcade or in the game's own settings). Default true when absent."
             }
           }
         }
@@ -2852,11 +2940,14 @@
         "ASKS, and the parent, which holds the account session, renders the",
         "picker in its own chrome and saves the choice.",
         "",
-        "NO FIELDS, AND NO REPLY. The game names nothing — not an item, not a",
-        "filter, not a line of text: which portraits are offered and what the",
+        "ONE OPTIONAL FIELD, AND NO REPLY. The game names nothing but which tab",
+        "it would like the picker to open on (`tab`, below) — not an item, not",
+        "a filter, not a line of text: which avatars are offered and what the",
         "picker says are the parent's. And nothing answers this message. THE",
-        "OUTCOME IS A NEW `gem.player`: when the worn portrait changes, the",
-        "parent re-sends it with the new `avatarIconId` and `avatarIconUrl`, as",
+        "OUTCOME IS A NEW `gem.player`: when the worn portrait or 3D character",
+        "changes, the parent re-sends it with the new `avatarIconId` and",
+        "`avatarIconUrl`, or `avatar3dId`, `avatar3dModelUrl` and",
+        "`avatar3dIconUrl`, as",
         "it does for a change the player makes from the parent's menu without",
         "the game asking. A reply would be a second copy of an identity fact",
         "(`gem.signInResult`'s argument), and the picker may stay open for as",
@@ -2886,7 +2977,25 @@
         "picker is the control, and the account-session save is the",
         "enforcement."
       ],
-      "fields": {},
+      "fields": {
+        "tab": {
+          "kind": "enum",
+          "values": ["2d", "3d"],
+          "optional": true,
+          "$comment": [
+            "Which tab the picker opens on: `2d` the portrait (`avatarIconId`),",
+            "`3d` the 3D character (`avatar3dId`). Absent",
+            "means the parent decides — for a game that draws Arcade avatars it",
+            "opens the 3D tab. A HINT, not a restriction: the player may switch",
+            "tabs, and a parent with one tab ignores it.",
+            "",
+            "ADDITIVE, so no `v` bump: an older parent validated this message",
+            "with no fields and ignores an unknown one (rule 4), so it opens its",
+            "picker as before. A CLOSED enum, so a third value is a breaking",
+            "change under the freeze — an older parent would refuse the whole ask."
+          ]
+        }
+      },
       "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 stops a game nagging is the parent's one-at-a-time rule and its freedom to drop an ask."