@indiegems/gem-web-sdk 17.0.0 → 18.0.0

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

@@ -1,6 +1,6 @@
 # The browser surface — API reference
 
-Generated from `@indiegems/gem-web-sdk/sdk` v17.0.0, the version of the package this file ships in. Every symbol below carries an explicit anchor, its `anchor` in `reference.json` beside this file.
+Generated from `@indiegems/gem-web-sdk/sdk` v18.0.0, the version of the package this file ships in. Every symbol below carries an explicit anchor, its `anchor` in `reference.json` beside this file.
 
 `@indiegems/gem-web-sdk/sdk` is the one import a game writes, wherever its code runs. `@indiegems/gem-web-sdk/game` exports exactly the symbols on this page and nothing else, for a build that wants only this half.
 
@@ -6969,6 +6969,37 @@ A corner of your frame, for `gem.setGemCorner`: where you would like the
 arcade's Gem button to sit. `'top-left'` is where it sits unless you ask.
 Physical corners: `'top-left'` is the top-left in every language.
 
+<a id="menustyle"></a>
+
+## MenuStyle
+
+```ts
+interface MenuStyle
+```
+
+Two colours for the arcade's own screens over your game, for
+`gem.setMenuStyle`: each exactly `#rrggbb`. The arcade works out the rest.
+
+<a id="menustyle-ground"></a>
+
+## MenuStyle.ground
+
+```ts
+readonly ground: string
+```
+
+The colour the arcade's surfaces are built on, such as `'#1b2a4a'`.
+
+<a id="menustyle-accent"></a>
+
+## MenuStyle.accent
+
+```ts
+readonly accent: string
+```
+
+The one highlight, at least 3:1 against `ground`, such as `'#ffb300'`.
+
 <a id="framestate"></a>
 
 ## FrameState
@@ -7346,6 +7377,29 @@ its control.
   up, for an arcade that cannot move its control, for a value that is not
   one of the four corners, and past this frame's own limit.
 
+<a id="gemframe-setmenustyle"></a>
+
+## GemFrame.setMenuStyle
+
+```ts
+setMenuStyle(style: MenuStyle | null): boolean
+```
+
+Give the arcade's own screens over your game two colours to wear, or
+`null` to hand them back to the player's style: the whole answer each
+time, the latest one winning.
+
+Prefer `gem.setMenuStyle`, which checks the colours and holds them across
+a reconnect. This one sends only while connected, and only to an arcade
+that can wear them.
+
+| Parameter | Type |
+| --- | --- |
+| `style` | `MenuStyle \| null` |
+
+**Returns.** whether the message left the frame: `false` before the bridge is
+  up, for an arcade that cannot wear them, and past this frame's own limit.
+
 <a id="gemframe-requestshare"></a>
 
 ## GemFrame.requestShare
@@ -12019,6 +12073,45 @@ with a warning on the console, and changes nothing.
   up (the corner is held and sent when it connects), under an embedder that
   cannot move its control, and for a value that is not a corner.
 
+<a id="gem-setmenustyle"></a>
+
+## Gem.setMenuStyle
+
+```ts
+setMenuStyle(style: MenuStyle | null): boolean
+```
+
+Give the arcade's own screens over your game your colours, so they match
+it: on the Gem Arcade, the burger button, the Gem menu and its pages, and
+every Arcade pop-up over the running game.
+
+```js
+gem.setMenuStyle({ ground: '#1b2a4a', accent: '#ffb300' });
+gem.setMenuStyle(null); // back to the player's own style
+```
+
+**Colours only.** `ground` is what the arcade's surfaces are built on and
+`accent` its one highlight; the arcade works out the text, rims, button
+shapes and fonts, so its screens stay readable on any ground.
+
+**The Arcade refuses colours it cannot use.** Each must be exactly
+`#rrggbb`, and `accent` must reach 3:1 contrast against `ground`. Anything
+else is ignored, with a warning on the console giving the measured ratio:
+the last colours stand, nothing is sent, and this returns `false`.
+
+**Your colours win over the player's chosen style while your game runs**,
+and the player's style comes back when it ends. It is screen state, not a
+toggle: each call is the whole answer, so you may change it between levels.
+Call it at boot, so your colours arrive with the first screen.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `style` | `MenuStyle \| null` | The two colours, or `null` to hand back to the player's style. |
+
+**Returns.** `true` when the arcade was told now; `false` before the bridge is
+  up (the colours are held and sent when it connects), under an embedder
+  that cannot wear them, and for colours it would refuse.
+
 <a id="gem-reportframe"></a>
 
 ## Gem.reportFrame

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

@@ -1,6 +1,6 @@
 # The server surface — API reference
 
-Generated from `@indiegems/gem-web-sdk/sdk` v17.0.0, the version of the package this file ships in. Every symbol below carries an explicit anchor, its `anchor` in `reference.json` beside this file.
+Generated from `@indiegems/gem-web-sdk/sdk` v18.0.0, the version of the package this file ships in. Every symbol below carries an explicit anchor, its `anchor` in `reference.json` beside this file.
 
 `@indiegems/gem-web-sdk/sdk` is the one import a game writes, wherever its code runs. `@indiegems/gem-web-sdk/server` exports exactly the symbols on this page and nothing else, for a build that wants only this half.
 

package/docs/api/reference.json

@@ -2,7 +2,7 @@
   "schema_version": 2,
   "source": {
     "repo": "IndieGems/gem-web-sdk",
-    "version": "17.0.0"
+    "version": "18.0.0"
   },
   "entries": [
     {
@@ -8304,6 +8304,54 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "MenuStyle",
+          "name": "MenuStyle",
+          "anchor": "menustyle",
+          "group": "frame",
+          "signature": "interface MenuStyle",
+          "documented": true,
+          "summary": "Two colours for the arcade's own screens over your game, for\n`gem.setMenuStyle`: each exactly `#rrggbb`. The arcade works out the rest.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "MenuStyle.ground",
+          "name": "ground",
+          "anchor": "menustyle-ground",
+          "group": "frame",
+          "signature": "readonly ground: string",
+          "documented": true,
+          "summary": "The colour the arcade's surfaces are built on, such as `'#1b2a4a'`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "MenuStyle.accent",
+          "name": "accent",
+          "anchor": "menustyle-accent",
+          "group": "frame",
+          "signature": "readonly accent: string",
+          "documented": true,
+          "summary": "The one highlight, at least 3:1 against `ground`, such as `'#ffb300'`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "FrameState",
           "name": "FrameState",
@@ -8684,6 +8732,29 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "GemFrame.setMenuStyle",
+          "name": "setMenuStyle",
+          "anchor": "gemframe-setmenustyle",
+          "group": "frame",
+          "signature": "setMenuStyle(style: MenuStyle | null): boolean",
+          "documented": true,
+          "summary": "Give the arcade's own screens over your game two colours to wear, or\n`null` to hand them back to the player's style: the whole answer each\ntime, the latest one winning.\n\nPrefer `gem.setMenuStyle`, which checks the colours and holds them across\na reconnect. This one sends only while connected, and only to an arcade\nthat can wear them.",
+          "deprecated": null,
+          "params": [
+            {
+              "name": "style",
+              "type": "MenuStyle | null",
+              "optional": false,
+              "summary": null
+            }
+          ],
+          "returns": "whether the message left the frame: `false` before the bridge is\n  up, for an arcade that cannot wear them, and past this frame's own limit.",
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "GemFrame.requestShare",
           "name": "requestShare",
@@ -13364,6 +13435,29 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "Gem.setMenuStyle",
+          "name": "setMenuStyle",
+          "anchor": "gem-setmenustyle",
+          "group": "start",
+          "signature": "setMenuStyle(style: MenuStyle | null): boolean",
+          "documented": true,
+          "summary": "Give the arcade's own screens over your game your colours, so they match\nit: on the Gem Arcade, the burger button, the Gem menu and its pages, and\nevery Arcade pop-up over the running game.\n\n```js\ngem.setMenuStyle({ ground: '#1b2a4a', accent: '#ffb300' });\ngem.setMenuStyle(null); // back to the player's own style\n```\n\n**Colours only.** `ground` is what the arcade's surfaces are built on and\n`accent` its one highlight; the arcade works out the text, rims, button\nshapes and fonts, so its screens stay readable on any ground.\n\n**The Arcade refuses colours it cannot use.** Each must be exactly\n`#rrggbb`, and `accent` must reach 3:1 contrast against `ground`. Anything\nelse is ignored, with a warning on the console giving the measured ratio:\nthe last colours stand, nothing is sent, and this returns `false`.\n\n**Your colours win over the player's chosen style while your game runs**,\nand the player's style comes back when it ends. It is screen state, not a\ntoggle: each call is the whole answer, so you may change it between levels.\nCall it at boot, so your colours arrive with the first screen.",
+          "deprecated": null,
+          "params": [
+            {
+              "name": "style",
+              "type": "MenuStyle | null",
+              "optional": false,
+              "summary": "The two colours, or `null` to hand back to the player's style."
+            }
+          ],
+          "returns": "`true` when the arcade was told now; `false` before the bridge is\n  up (the colours are held and sent when it connects), under an embedder\n  that cannot wear them, and for colours it would refuse.",
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "Gem.reportFrame",
           "name": "reportFrame",

package/docs/changelog.md

@@ -16,6 +16,19 @@ Its entries are grouped under up to five headings:
 - **Rebuild**: a type changed. Recompile against the new version; code that compiles today keeps compiling unless the entry says otherwise.
 - **New capability**: something a game can now do. Nothing changes unless you use it.
 
+## 18.0.0
+
+Upgrading from 17.0.0. Impact: required.
+
+### Rebuild
+
+- The set of capability names a game can query has a new member, menuStyle. Recompiling is enough, but if your code handles every capability name exhaustively, add a case for the new one.
+- The frame message type has a new member for menu style, and the list of messages a game frame sends to the Arcade now includes gem.menuStyle. Recompiling is enough, but code that handles every message exhaustively needs a case for the new message.
+
+### New capability
+
+- A game can now hand the Arcade its own colours for the Arcade menu by calling Gem.setMenuStyle with a MenuStyle value. Check for the menuStyle capability first, since an older Arcade will not act on it. The same call is also available on the frame object.
+
 ## 17.0.0
 
 *Written from the API facts alone; no summary was generated for this release.*

package/docs/getting-started.md

@@ -50,7 +50,7 @@ either way.
 ```jsonc
 // package.json
 "dependencies": {
-  "@indiegems/gem-web-sdk": "17.0.0"
+  "@indiegems/gem-web-sdk": "18.0.0"
 }
 ```
 

package/docs/manifest.json

@@ -48,8 +48,8 @@
     },
     {
       "file": "changelog.md",
-      "sha256": "b795d5ed73558a4d355196971fb4bd9689ca15d38fd01d9a67b4cf6c0e8ff25d",
-      "updated": "2026-10-30T14:09:44Z"
+      "sha256": "bd5cfd2b2d1d1989a8407e147ce29165caada49f78bcd0d708ded1babe98fc09",
+      "updated": "2026-10-30T15:46:14Z"
     },
     {
       "file": "daily-challenges.md",
@@ -78,8 +78,8 @@
     },
     {
       "file": "getting-started.md",
-      "sha256": "a69a8be43e655a71717c1d15ff3e9136103c17eebd9074c2f3dab4fad07d2689",
-      "updated": "2026-10-30T14:09:44Z"
+      "sha256": "67a444eb6e1cbf0bbf9af6309db48ae44e9c03a692df60a35c12e604cb646065",
+      "updated": "2026-10-30T15:46:14Z"
     },
     {
       "file": "inventory-and-catalogs.md",
@@ -138,8 +138,8 @@
     },
     {
       "file": "server-bundles.md",
-      "sha256": "d00bc2ea3896c2e262619bf87b2892dd954c9ef87d37dfb5881bb6ef7439401a",
-      "updated": "2026-10-30T14:09:44Z"
+      "sha256": "8c2ff15c97a0eb09c9a50ae78b5e728635a478ee879a8aa788b82ca7de387eee",
+      "updated": "2026-10-30T15:46:14Z"
     },
     {
       "file": "serverless-functions-js.md",
@@ -163,8 +163,8 @@
     },
     {
       "file": "what-a-game-must-do.md",
-      "sha256": "9d6f2121306bfee8b886d9555a644faa843d16f0c5200e257698336d747136b1",
-      "updated": "2026-10-29T21:40:17Z"
+      "sha256": "8faa9ef2cef2a5eb73cf95d7c52af914325c2bc26834625c9cb4b5748eecc616",
+      "updated": "2026-10-30T14:09:09Z"
     }
   ]
 }

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/v17.0.0/gem-web-sdk.tgz
-curl -fsSL https://downloads.gemarcade.com/sdk/v17.0.0/gem-web-sdk.tgz.sri
+curl -fsSL -O https://downloads.gemarcade.com/sdk/v18.0.0/gem-web-sdk.tgz
+curl -fsSL https://downloads.gemarcade.com/sdk/v18.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

@@ -971,6 +971,35 @@ read the rectangles, so the arcade sends it none and instead raises `insets.top`
 `--gem-safe-top` — past the bottom of the row. That game keeps working, at the cost of a full-width
 band; upgrading gives the band back.
 
+### Matching the Arcade to your game: `gem.setMenuStyle`
+
+The burger button and everything the Arcade draws over your game wear the player's Arcade style
+until you say otherwise. To make them match your game, give the Arcade two colours:
+
+```js
+gem.setMenuStyle({ ground: '#1b2a4a', accent: '#ffb300' }); // at boot, with your first screen
+gem.setMenuStyle(null); // back to the player's own style
+```
+
+- **Colours only.** `ground` is what the Arcade's surfaces are built on and `accent` is its one
+  highlight. The Arcade works out the text, rims, button shapes and fonts, so its screens stay
+  readable on any ground.
+- **What the Arcade refuses.** Each colour must be exactly `#rrggbb`, and `accent` must reach 3:1
+  contrast against `ground`. Anything else is ignored, with a warning on the console giving the
+  measured ratio: the last colours stand, nothing is sent, and the call returns `false`.
+- **What wears your colours.** The burger button, the Gem menu and its pages, and every Arcade
+  pop-up over your running game, purchase sheets included. They do not reach the Arcade's other
+  screens.
+- **Your colours win while your game runs.** They replace the style the player chose, and that
+  style comes back when your game ends.
+- **It is screen state, not a toggle**: each call is the whole answer, held before the Arcade
+  connects and sent again after any reconnect, so you may change it between levels. A change the
+  Arcade receives while its menu or a pop-up is open waits until that closes.
+
+`gem.setMenuStyle` returns `true` when the Arcade was told, and `false` before it connects, under an
+embedder that cannot wear your colours, and for colours it would refuse. On `false` from an embedder
+there is nothing else to do: never draw a look-alike of its menu.
+
 ## Which store-page experiment brought this player in: cohorts
 
 **You need this only if you run an A/B experiment on your store page and want the game to match

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indiegems/gem-web-sdk",
-  "version": "17.0.0",
+  "version": "18.0.0",
   "description": "postMessage bridge contract between gem-web and browser-playable games",
   "license": "UNLICENSED",
   "type": "module",

package/schema/bridge.v1.json

@@ -3145,6 +3145,64 @@
       "rateLimit": { "perMinute": 12 }
     },
 
+    {
+      "type": "gem.menuStyle",
+      "direction": "frameToParent",
+      "transport": "port",
+      "$comment": [
+        "The colours the game would like the arcade's own screens over it to wear,",
+        "so they match the game: in the Gem Arcade, the burger button, the Gem menu",
+        "and its pages, and every Arcade pop-up over the running game. With no",
+        "message at all those screens wear the player's own Arcade style.",
+        "",
+        "TWO COLOURS, BOTH OR NEITHER. `ground` is the colour the arcade's surfaces",
+        "are built on and `accent` its one highlight. A message with neither hands",
+        "the arcade back to the player's own style; a message with only one is",
+        "refused by the parent. The parent works out everything else, text, rims,",
+        "button shapes and fonts, so a game can never make its screens unreadable.",
+        "",
+        "SCREEN STATE, NOT A TOGGLE, like `gem.gemCorner`. Each message is the whole",
+        "answer and the latest one wins, so a game may change it between levels.",
+        "The SDK holds it from before the bridge is up and re-sends it after every",
+        "handshake, so a parent that reconnects wears what the game had asked.",
+        "",
+        "THE PARENT DECIDES, AND IT CHECKS AGAIN. The frame is untrusted, so a",
+        "parent checks both values itself before a byte of them reaches a style:",
+        "exactly `#` and six hexadecimal digits, and at least 3:1 WCAG contrast",
+        "between `accent` and `ground`. On failure it keeps the screens as they",
+        "are and tells the game nothing; the SDK refuses the same values on the",
+        "game's side, where a developer sees why. A format of its own is not used",
+        "for the hex, because a parent built on an older contract refuses a format",
+        "it does not know.",
+        "",
+        "ON THE PARENT'S TERMS. In the Gem Arcade the game's colours win over the",
+        "player's chosen style for as long as that game runs, a change that arrives",
+        "while one of the arcade's surfaces is open waits for it to close, and the",
+        "player's own style comes back when the game ends.",
+        "",
+        "A PRESENTATION REQUEST ONLY, and not an authorization control. Cosmetic:",
+        "nothing may key a trust decision on it.",
+        "",
+        "Gated by `menuStyle`: sent only to a parent that advertised it. To any",
+        "other, `gem.setMenuStyle` returns false."
+      ],
+      "fields": {
+        "ground": {
+          "kind": "string",
+          "maxLength": 7,
+          "optional": true,
+          "$comment": "`#rrggbb`, the colour the arcade's surfaces are built on. Absent with `accent` to clear."
+        },
+        "accent": {
+          "kind": "string",
+          "maxLength": 7,
+          "optional": true,
+          "$comment": "`#rrggbb`, the one highlight, at least 3:1 against `ground`. Absent with `ground` to clear."
+        }
+      },
+      "rateLimit": { "perMinute": 12 }
+    },
+
     {
       "type": "gem.settingsDeclare",
       "direction": "frameToParent",

package/schema/capabilities.public.json

@@ -302,6 +302,12 @@
         "gem.requestStoreOfferSheet",
         "gem.storeOfferSheetResult"
       ]
+    },
+    "menuStyle": {
+      "implemented": true,
+      "gates": [
+        "gem.menuStyle"
+      ]
     }
   }
 }