@indiegems/gem-web-sdk 17.0.0 → 18.1.0

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

@@ -1,6 +1,6 @@
 # The function surface — API reference
 
-Generated from `@indiegems/gem-web-sdk/function` 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/function` v18.1.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/function` exports exactly the symbols on this page and nothing else.
 
@@ -23,7 +23,11 @@ type AnalyticsValue = string | number
 A value attached to an event.
 
 A **string** is a dimension and a **number** is a measure, and which one a
-key is was decided in your game config, not here. Dimensions are closed sets
+key is was decided in your game config, not here. The one exception, in a
+browser game, is a key your config declares as an integer `range`
+dimension: there a number is that dimension's value, sent as its decimal. A
+dedicated server and a serverless function read no config, so there a
+range dimension goes as its decimal string. Dimensions are closed sets
 declared ahead of time — that is the whole reason there is no free-text
 property — and measures are the numbers the platform sums, averages and
 takes the min and max of.
@@ -267,7 +271,10 @@ track(name: string, props?: Readonly<Record<string, AnalyticsValue>>): void
 Record an event. Synchronous, and it never throws.
 
 String values become dimensions and numbers become measures, matched
-against your `analytics_events` declaration server-side. Nothing is sent
+against your `analytics_events` declaration server-side. A number on a key
+that declaration makes an integer `range` dimension is that dimension's
+value instead — `level: 7` against `level: { range: { min: 1, max: 50 } }`
+— and so is its decimal string, `level: '7'`. Nothing is sent
 yet: the event joins a queue that goes out on a timer, at 50 events, and
 on the way out of the page.
 
@@ -275,12 +282,16 @@ on the way out of the page.
 a name starting `gem_` is refused here rather than sent and rejected
 there.
 
+⚠️ In a serverless function the SDK holds no config, so a number there is
+always a measure: pass a range dimension as its decimal string.
+
 | Parameter | Type | Description |
 | --- | --- | --- |
 | `name` | `string` | A declared event id — the `id` of an entry in your config's
   `analytics_events`. |
-| `props` | `Readonly<Record<string, AnalyticsValue>>` | Dimensions (strings) and measures (numbers), merged over
-  whatever [AnalyticsApi.setContext](#analyticsapi-setcontext) holds. |
+| `props` | `Readonly<Record<string, AnalyticsValue>>` | Dimensions (strings, or a number on a `range` dimension) and
+  measures (numbers), merged over whatever [AnalyticsApi.setContext](#analyticsapi-setcontext)
+  holds. |
 
 <a id="analyticsapi-setcontext"></a>
 

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.1.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.
 
@@ -3430,7 +3430,11 @@ type AnalyticsValue = string | number
 A value attached to an event.
 
 A **string** is a dimension and a **number** is a measure, and which one a
-key is was decided in your game config, not here. Dimensions are closed sets
+key is was decided in your game config, not here. The one exception, in a
+browser game, is a key your config declares as an integer `range`
+dimension: there a number is that dimension's value, sent as its decimal. A
+dedicated server and a serverless function read no config, so there a
+range dimension goes as its decimal string. Dimensions are closed sets
 declared ahead of time — that is the whole reason there is no free-text
 property — and measures are the numbers the platform sums, averages and
 takes the min and max of.
@@ -3674,7 +3678,10 @@ track(name: string, props?: Readonly<Record<string, AnalyticsValue>>): void
 Record an event. Synchronous, and it never throws.
 
 String values become dimensions and numbers become measures, matched
-against your `analytics_events` declaration server-side. Nothing is sent
+against your `analytics_events` declaration server-side. A number on a key
+that declaration makes an integer `range` dimension is that dimension's
+value instead — `level: 7` against `level: { range: { min: 1, max: 50 } }`
+— and so is its decimal string, `level: '7'`. Nothing is sent
 yet: the event joins a queue that goes out on a timer, at 50 events, and
 on the way out of the page.
 
@@ -3682,12 +3689,16 @@ on the way out of the page.
 a name starting `gem_` is refused here rather than sent and rejected
 there.
 
+⚠️ In a serverless function the SDK holds no config, so a number there is
+always a measure: pass a range dimension as its decimal string.
+
 | Parameter | Type | Description |
 | --- | --- | --- |
 | `name` | `string` | A declared event id — the `id` of an entry in your config's
   `analytics_events`. |
-| `props` | `Readonly<Record<string, AnalyticsValue>>` | Dimensions (strings) and measures (numbers), merged over
-  whatever [AnalyticsApi.setContext](#analyticsapi-setcontext) holds. |
+| `props` | `Readonly<Record<string, AnalyticsValue>>` | Dimensions (strings, or a number on a `range` dimension) and
+  measures (numbers), merged over whatever [AnalyticsApi.setContext](#analyticsapi-setcontext)
+  holds. |
 
 <a id="analyticsapi-setcontext"></a>
 
@@ -6969,6 +6980,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 +7388,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 +12084,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.1.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.
 
@@ -21,7 +21,11 @@ type AnalyticsValue = string | number
 A value attached to an event.
 
 A **string** is a dimension and a **number** is a measure, and which one a
-key is was decided in your game config, not here. Dimensions are closed sets
+key is was decided in your game config, not here. The one exception, in a
+browser game, is a key your config declares as an integer `range`
+dimension: there a number is that dimension's value, sent as its decimal. A
+dedicated server and a serverless function read no config, so there a
+range dimension goes as its decimal string. Dimensions are closed sets
 declared ahead of time — that is the whole reason there is no free-text
 property — and measures are the numbers the platform sums, averages and
 takes the min and max of.

package/docs/api/reference.json

@@ -2,7 +2,7 @@
   "schema_version": 2,
   "source": {
     "repo": "IndieGems/gem-web-sdk",
-    "version": "17.0.0"
+    "version": "18.1.0"
   },
   "entries": [
     {
@@ -4147,7 +4147,7 @@
           "group": "analytics",
           "signature": "type AnalyticsValue = string | number",
           "documented": true,
-          "summary": "A value attached to an event.\n\nA **string** is a dimension and a **number** is a measure, and which one a\nkey is was decided in your game config, not here. Dimensions are closed sets\ndeclared ahead of time — that is the whole reason there is no free-text\nproperty — and measures are the numbers the platform sums, averages and\ntakes the min and max of.",
+          "summary": "A value attached to an event.\n\nA **string** is a dimension and a **number** is a measure, and which one a\nkey is was decided in your game config, not here. The one exception, in a\nbrowser game, is a key your config declares as an integer `range`\ndimension: there a number is that dimension's value, sent as its decimal. A\ndedicated server and a serverless function read no config, so there a\nrange dimension goes as its decimal string. Dimensions are closed sets\ndeclared ahead of time — that is the whole reason there is no free-text\nproperty — and measures are the numbers the platform sums, averages and\ntakes the min and max of.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -4424,7 +4424,7 @@
           "group": "analytics",
           "signature": "track(name: string, props?: Readonly<Record<string, AnalyticsValue>>): void",
           "documented": true,
-          "summary": "Record an event. Synchronous, and it never throws.\n\nString values become dimensions and numbers become measures, matched\nagainst your `analytics_events` declaration server-side. Nothing is sent\nyet: the event joins a queue that goes out on a timer, at 50 events, and\non the way out of the page.\n\n⚠️ `gem_` IS RESERVED. The SDK emits the platform's own events itself, so\na name starting `gem_` is refused here rather than sent and rejected\nthere.",
+          "summary": "Record an event. Synchronous, and it never throws.\n\nString values become dimensions and numbers become measures, matched\nagainst your `analytics_events` declaration server-side. A number on a key\nthat declaration makes an integer `range` dimension is that dimension's\nvalue instead — `level: 7` against `level: { range: { min: 1, max: 50 } }`\n— and so is its decimal string, `level: '7'`. Nothing is sent\nyet: the event joins a queue that goes out on a timer, at 50 events, and\non the way out of the page.\n\n⚠️ `gem_` IS RESERVED. The SDK emits the platform's own events itself, so\na name starting `gem_` is refused here rather than sent and rejected\nthere.\n\n⚠️ In a serverless function the SDK holds no config, so a number there is\nalways a measure: pass a range dimension as its decimal string.",
           "deprecated": null,
           "params": [
             {
@@ -4437,7 +4437,7 @@
               "name": "props",
               "type": "Readonly<Record<string, AnalyticsValue>>",
               "optional": false,
-              "summary": "Dimensions (strings) and measures (numbers), merged over\n  whatever [AnalyticsApi.setContext](api-reference-game.md#analyticsapi-setcontext) holds."
+              "summary": "Dimensions (strings, or a number on a `range` dimension) and\n  measures (numbers), merged over whatever [AnalyticsApi.setContext](api-reference-game.md#analyticsapi-setcontext)\n  holds."
             }
           ],
           "returns": null,
@@ -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",
@@ -24289,7 +24383,7 @@
           "group": "analytics",
           "signature": "type AnalyticsValue = string | number",
           "documented": true,
-          "summary": "A value attached to an event.\n\nA **string** is a dimension and a **number** is a measure, and which one a\nkey is was decided in your game config, not here. Dimensions are closed sets\ndeclared ahead of time — that is the whole reason there is no free-text\nproperty — and measures are the numbers the platform sums, averages and\ntakes the min and max of.",
+          "summary": "A value attached to an event.\n\nA **string** is a dimension and a **number** is a measure, and which one a\nkey is was decided in your game config, not here. The one exception, in a\nbrowser game, is a key your config declares as an integer `range`\ndimension: there a number is that dimension's value, sent as its decimal. A\ndedicated server and a serverless function read no config, so there a\nrange dimension goes as its decimal string. Dimensions are closed sets\ndeclared ahead of time — that is the whole reason there is no free-text\nproperty — and measures are the numbers the platform sums, averages and\ntakes the min and max of.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -29538,7 +29632,7 @@
           "group": "analytics",
           "signature": "type AnalyticsValue = string | number",
           "documented": true,
-          "summary": "A value attached to an event.\n\nA **string** is a dimension and a **number** is a measure, and which one a\nkey is was decided in your game config, not here. Dimensions are closed sets\ndeclared ahead of time — that is the whole reason there is no free-text\nproperty — and measures are the numbers the platform sums, averages and\ntakes the min and max of.",
+          "summary": "A value attached to an event.\n\nA **string** is a dimension and a **number** is a measure, and which one a\nkey is was decided in your game config, not here. The one exception, in a\nbrowser game, is a key your config declares as an integer `range`\ndimension: there a number is that dimension's value, sent as its decimal. A\ndedicated server and a serverless function read no config, so there a\nrange dimension goes as its decimal string. Dimensions are closed sets\ndeclared ahead of time — that is the whole reason there is no free-text\nproperty — and measures are the numbers the platform sums, averages and\ntakes the min and max of.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -29815,7 +29909,7 @@
           "group": "analytics",
           "signature": "track(name: string, props?: Readonly<Record<string, AnalyticsValue>>): void",
           "documented": true,
-          "summary": "Record an event. Synchronous, and it never throws.\n\nString values become dimensions and numbers become measures, matched\nagainst your `analytics_events` declaration server-side. Nothing is sent\nyet: the event joins a queue that goes out on a timer, at 50 events, and\non the way out of the page.\n\n⚠️ `gem_` IS RESERVED. The SDK emits the platform's own events itself, so\na name starting `gem_` is refused here rather than sent and rejected\nthere.",
+          "summary": "Record an event. Synchronous, and it never throws.\n\nString values become dimensions and numbers become measures, matched\nagainst your `analytics_events` declaration server-side. A number on a key\nthat declaration makes an integer `range` dimension is that dimension's\nvalue instead — `level: 7` against `level: { range: { min: 1, max: 50 } }`\n— and so is its decimal string, `level: '7'`. Nothing is sent\nyet: the event joins a queue that goes out on a timer, at 50 events, and\non the way out of the page.\n\n⚠️ `gem_` IS RESERVED. The SDK emits the platform's own events itself, so\na name starting `gem_` is refused here rather than sent and rejected\nthere.\n\n⚠️ In a serverless function the SDK holds no config, so a number there is\nalways a measure: pass a range dimension as its decimal string.",
           "deprecated": null,
           "params": [
             {
@@ -29828,7 +29922,7 @@
               "name": "props",
               "type": "Readonly<Record<string, AnalyticsValue>>",
               "optional": false,
-              "summary": "Dimensions (strings) and measures (numbers), merged over\n  whatever [AnalyticsApi.setContext](api-reference-function.md#analyticsapi-setcontext) holds."
+              "summary": "Dimensions (strings, or a number on a `range` dimension) and\n  measures (numbers), merged over whatever [AnalyticsApi.setContext](api-reference-function.md#analyticsapi-setcontext)\n  holds."
             }
           ],
           "returns": null,

package/docs/changelog.md

@@ -16,6 +16,27 @@ 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.1.0
+
+Upgrading from 18.0.0. Impact: recommended.
+
+### New capability
+
+- A number sent for an analytics dimension that your game config declares as a range is now delivered as that dimension, written as its decimal. Previously such events went out as a measure and were refused as missing a dimension. If your game dropped, skipped or worked around these events, you can send the number directly. Numbers on other fields remain measures, and events your config does not declare are sent as before. The analytics options also gain a declarations field, which the SDK fills in from your game config, so you normally do not set it. Code that runs on a server or in a function should still send a range as its decimal string.
+
+## 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.1.0"
 }
 ```
 

package/docs/manifest.json

@@ -13,8 +13,8 @@
     },
     {
       "file": "analytics.md",
-      "sha256": "afced8f94514818eca6de3e72bdd988b2cee10925086c3bfa47c0a8ec8967454",
-      "updated": "2026-10-23T00:13:14Z"
+      "sha256": "42f3d0d3360e1a6066c21015bd4925475b4336a53611bf04acb773a7c6084e62",
+      "updated": "2026-10-30T16:54:41Z"
     },
     {
       "file": "arcade-and-store.md",
@@ -48,8 +48,8 @@
     },
     {
       "file": "changelog.md",
-      "sha256": "b795d5ed73558a4d355196971fb4bd9689ca15d38fd01d9a67b4cf6c0e8ff25d",
-      "updated": "2026-10-30T14:09:44Z"
+      "sha256": "75530d611c02d513b1789d787e83a219392cfa92bfa70b1995aaa46bd233fbbd",
+      "updated": "2026-10-30T18:08:09Z"
     },
     {
       "file": "daily-challenges.md",
@@ -78,8 +78,8 @@
     },
     {
       "file": "getting-started.md",
-      "sha256": "a69a8be43e655a71717c1d15ff3e9136103c17eebd9074c2f3dab4fad07d2689",
-      "updated": "2026-10-30T14:09:44Z"
+      "sha256": "cefcb0179415e448ac16b5e7e23be35c48745aa1b4ac5e23e7375f58b3c8890c",
+      "updated": "2026-10-30T18:08:09Z"
     },
     {
       "file": "inventory-and-catalogs.md",
@@ -138,8 +138,8 @@
     },
     {
       "file": "server-bundles.md",
-      "sha256": "d00bc2ea3896c2e262619bf87b2892dd954c9ef87d37dfb5881bb6ef7439401a",
-      "updated": "2026-10-30T14:09:44Z"
+      "sha256": "a5bdf1ca63a3c5f9f3ca8b123cc569135779960934c74176453f2596a22da7f4",
+      "updated": "2026-10-30T18:08:09Z"
     },
     {
       "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.1.0/gem-web-sdk.tgz
+curl -fsSL https://downloads.gemarcade.com/sdk/v18.1.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.1.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",