@indiegems/gem-web-sdk 15.1.2 → 15.3.0

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

@@ -53,8 +53,10 @@ No `baseUrl`. The Arcade names the backend on every token and the SDK routes the
 tokens only if its origin is allowed, and the pages that matter are always allowed without a word
 from you:
 
-- **the Gem Arcade website and app** — the SDK carries their origins as `ARCADE_EMBEDDERS`, on every
-  platform the app runs on;
+- **the Gem Arcade website, developer site and app** — the SDK carries their origins as
+  `ARCADE_EMBEDDERS`, on every platform the app runs on. The developer site,
+  `https://developer.gemarcade.com`, is where you play your own dev and test builds; a build accepts
+  it once it is built with an SDK that lists it;
 - **a dev host on your own machine** — `gemctl serve` and the Gem Editor frame a locally-served game
   from a loopback origin whose port changes every run, and the SDK admits that shape by rule, only
   while your game itself is served from loopback. Once published, nothing about the rule applies.
@@ -1074,19 +1076,20 @@ The player sets their defaults once, in the Arcade's Settings, separately for ea
 and a television can say different things. They reach your game as `gem.prefs.recommended`, in the
 same push as `muted` and `reducedMotion`, and again whenever the player changes one:
 
-| Field                    | Values                          | What it suggests                                                                                                                 |
-| ------------------------ | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
-| `volume`                 | `0` to `100`                    | Your master volume's starting level, as a percentage — divide by 100 for a gain. A level, never a mute.                          |
-| `batterySaver`           | `true` / `false`                | Spend less power: a lower frame rate, fewer effects, a lower resolution.                                                         |
-| `keyboardLayout`         | `'wasd'` / `'arrows'`           | Which keys move by default.                                                                                                      |
-| `gamepadConfirm`         | `'south'` / `'east'`            | Which face button confirms, by position: the bottom one (A on an Xbox controller) or the right one (B). The other one goes back. |
-| `vibration`              | `true` / `false`                | Your vibration toggle's starting state ([if your game vibrates](#if-your-game-vibrates)).                                        |
-| `lookSensitivity`        | `20` to `400`                   | Look speed for touch, mouse and pen, as a percentage of the base speeds: `100` is 1×.                                            |
-| `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.        |
+| Field                    | Values                          | What it suggests                                                                                                                     |
+| ------------------------ | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `volume`                 | `0` to `100`                    | Your master volume's starting level, as a percentage — divide by 100 for a gain. A level, never a mute.                              |
+| `batterySaver`           | `true` / `false`                | Spend less power: a lower frame rate, fewer effects, a lower resolution.                                                             |
+| `keyboardLayout`         | `'wasd'` / `'arrows'`           | Which keys move by default.                                                                                                          |
+| `gamepadConfirm`         | `'south'` / `'east'`            | Which face button confirms, by position: the bottom one (A on an Xbox controller) or the right one (B). The other one goes back.     |
+| `vibration`              | `true` / `false`                | Your vibration toggle's starting state ([if your game vibrates](#if-your-game-vibrates)).                                            |
+| `lookSensitivity`        | `20` to `400`                   | Look speed for touch, mouse and pen, as a percentage of the base speeds: `100` is 1×.                                                |
+| `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.            |
+| `colorHelp`              | `true` / `false` / `null`       | Color help: start your colour-blind aids (patterns or symbols beside colours, a colour-blind palette) on, or off. `null`: no advice. |
 
 `lookSensitivity` to `touchMovement` are the camera and controls settings: see
 [camera and look controls](#camera-and-look-controls) for `gem.controls.look()`, which applies the
@@ -1096,7 +1099,15 @@ older Arcade sends `recommended` without them; the SDK then fills each with its
 [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.
+`'medium'`. So whenever `recommended` is not `null`, those eleven fields are there.
+
+`colorHelp` is the player's **Color help** default, and the one field the SDK does not fill: an
+older Arcade omits it and you read `null`, which means the Arcade made **no recommendation** — not
+`false`. Keep your own default then. A game that offers colour-blind aids starts them from it, on
+first run or while the player has not chosen in your game, and never lets it override the player's
+own choice; it is the natural start for the `toggle` you declare with `icon: 'eye'`
+([the Arcade's quick row](#mirror-your-settings-into-the-arcades-menu-gemsettings)). A game with
+no such aids ignores it.
 
 **They are recommendations, and the player's own choice in your game always wins:**
 
@@ -1124,6 +1135,7 @@ const DEFAULTS = {
   invertLookY: false,
   touchMovement: 'floating',
   graphicsQuality: 'medium',
+  colorHelp: false, // your own default; `recommended.colorHelp` is null when the Arcade said nothing
 };
 let chosen = {}; // ONLY what the player picked in your settings screen
 

package/package.json

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

package/schema/bridge.v1.json

@@ -972,10 +972,11 @@
             "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, 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.",
+            "controls settings, a starting graphics quality and Color help.",
+            "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.",
             "A game may ignore it entirely.",
             "",
             "OPTIONAL because it is additive: a parent that predates it sends the",
@@ -1002,6 +1003,10 @@
             "(`low` when it is on, `medium` otherwise) and `graphicsQualityAuto`",
             "with true, so on the game side both are present whenever the object is.",
             "",
+            "`colorHelp` IS OPTIONAL INSIDE IT AND STAYS ABSENT (owner decision",
+            "2026-10-23): the SDK does NOT fill it. An older parent omits it and the",
+            "game reads `null`, \"no recommendation\", never false.",
+            "",
             "`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",
@@ -1103,6 +1108,25 @@
               "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."
+            },
+            "colorHelp": {
+              "kind": "boolean",
+              "optional": true,
+              "$comment": [
+                "The player's Arcade-wide Color help default for this device (owner",
+                "decision 2026-10-23): true asks a game that offers colour-blind aids",
+                "-- patterns or symbols beside colours, a colour-blind palette -- to",
+                "start with them ON; false asks it to start with them off. A DEFAULT",
+                "ONLY, like every field here: a game applies it on first run, or",
+                "while the player has made no choice of their own in that game, and",
+                "never overrides the player's in-game choice. A game with no such",
+                "aids ignores it.",
+                "",
+                "ABSENT IS NOT FALSE. A parent built against an older SDK omits it,",
+                "and that absence means the Arcade made no recommendation: the SDK",
+                "reports `null` and the game keeps its own default. Unlike the",
+                "camera and controls fields there is no neutral value to invent."
+              ]
             }
           }
         }