@indiegems/gem-web-sdk 23.0.5 → 23.1.0

package/docs/changelog.md

@@ -16,6 +16,32 @@ 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.
 
+## 23.1.0
+
+*Written from the API facts alone; no summary was generated for this release.*
+
+Upgrading from 23.0.6. Impact: required.
+
+### Must change
+
+- PARENT_CONFORMANCE_VERSION changed its signature.
+- GemCapability changed its signature.
+- GemHost.sendPrefs changed its signature.
+- GemPrefs.recommended changed its signature.
+
+### New capability
+
+- ParentUnderTest.setTextScale was added.
+- Gem.textScale was added.
+- GemOptions.onTextScale was added.
+- GemRecommendedSettings.textScale was added.
+
+## 23.0.6
+
+Upgrading from 23.0.5. Impact: none.
+
+Nothing in this release asks anything of a game.
+
 ## 23.0.5
 
 Upgrading from 23.0.4. Impact: none.

package/docs/getting-started.md

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

package/docs/manifest.json

@@ -48,8 +48,8 @@
     },
     {
       "file": "changelog.md",
-      "sha256": "9ebd99bb5155af5a9e87e07f5c70b6028e373919ad519d7603ec3e94ceb589f2",
-      "updated": "2026-11-06T15:26:06Z"
+      "sha256": "08a45ac742126bf110a16e9373e09a4e06fd4ab8cd68d62309a512a1712c8c53",
+      "updated": "2026-11-07T14:55:28Z"
     },
     {
       "file": "daily-challenges.md",
@@ -78,8 +78,8 @@
     },
     {
       "file": "getting-started.md",
-      "sha256": "0f4d813421826fb8d1b412422d698d9c2f6d8cf0403af37e77683941c90b8274",
-      "updated": "2026-11-06T15:26:06Z"
+      "sha256": "a711052efd2252ddda2bed1af1394f8c57692086d5e3acdd6ccf2e5b7a14b4fc",
+      "updated": "2026-11-07T14:55:28Z"
     },
     {
       "file": "graphics-route.md",
@@ -123,8 +123,8 @@
     },
     {
       "file": "rewarded-ads.md",
-      "sha256": "c8fdcdd1075e330c8ddd8cd6bf8a61f697082764358b4e5dd556a9bcd9cbaba2",
-      "updated": "2026-11-06T14:23:15Z"
+      "sha256": "0658ec71ae9938040c2a493385cd9e360224b51309b3254438950124ae444743",
+      "updated": "2026-11-07T02:38:17Z"
     },
     {
       "file": "room-shapes.md",
@@ -143,8 +143,8 @@
     },
     {
       "file": "server-bundles.md",
-      "sha256": "996dbc24a224f309ed7b28e32ed8a929e4027269204745f789d9c2190f7db3fe",
-      "updated": "2026-11-06T15:26:06Z"
+      "sha256": "e0249cef381f23d156443b6a0b73c3a9616055e5434acf39fbdcada04ec0e745",
+      "updated": "2026-11-07T14:55:28Z"
     },
     {
       "file": "serverless-functions-js.md",
@@ -168,8 +168,8 @@
     },
     {
       "file": "what-a-game-must-do.md",
-      "sha256": "341a5fa4bec0435ece65183ea2edd601037767cc58cf7f0e5929547ad2253161",
-      "updated": "2026-11-05T16:22:23Z"
+      "sha256": "f70fe9fad67c6b386bddc53f1f876bb78f6a5e11c35f565bb93e925d65a99874",
+      "updated": "2026-11-06T22:48:07Z"
     }
   ]
 }

package/docs/rewarded-ads.md

@@ -505,13 +505,18 @@ reward because of anything else you have read about a channel.
 stops the placement, so it tells you what to draw, not which state you are in. It never says
 whether an ad will play.
 
+To see what each channel serves without a running game, run `gemctl rewarded status`: it answers
+for browsers and for the native apps. Its answer is the same for every player, so it cannot say what
+one player gets, and the platform can move a channel after you read it. Keep the button on
+`grantable`.
+
 **Test ads never serve on `release`**, and a reward granted on `dev` or `test` never reaches
 `release`: inventory is per channel.
 
 What each state means for a game:
 
-- **Build the final shape now.** The code in §5 is the same code in every state. Under
-  `without_ads: grant`, a reward that should be free until ads serve is free in state B: the same
+- **Build one shape for every state.** The code in §5 is the same code in every state. Under
+  `without_ads: grant`, a reward that should be free where no ad serves is free in state B: the same
   benefit, under the same caps. In state C the same placement plays an ad when one is available.
   It still pays with no ad whenever no ad can play for a press, because no ad was available or the
   ad failed. So in state C too, a `grant` placement's caps are the only limit on it. There is

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

@@ -1149,20 +1149,21 @@ 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.            |
-| `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. |
+| 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.                                             |
+| `textScale`              | `100` to `200` / `null`         | Text size, as a percent: scale your whole interface by it. Sent only to a game that passes `onTextScale`: see [text size](#the-arcades-text-size-size-in-rem-apply-ontextscale). |
 
 `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
@@ -1242,6 +1243,96 @@ owns — starts from `recommended` the same way and is kept in `gem.me.settings`
 ([sound](#sound-your-own-mute-control-and-the-arcades)), and `reducedMotion` is the player's
 accessibility setting, which your game honours.
 
+### The Arcade's Text size: size in `rem`, apply `onTextScale`
+
+The player picks a **Text size** in the Arcade's Settings, per device: 100, 115, 130, 150, 180 or
+200%, or System, which follows the phone's own font size. The Arcade never enlarges your game's
+text for you — inside your frame, text renders at the size you chose — so a game that wants to
+honour it applies it, and applies it to **the whole interface**, not to text alone. Text that grows
+inside boxes that do not is exactly what breaks: labels overflow, overlap and clip.
+
+**Pass `onTextScale` and set your root font size from it.** Passing the handler is what asks the
+Arcade for the value; a game without one is never sent it, and `gem.textScale` stays `null`:
+
+```js
+const MAX = 150; // the largest size your layout supports: at least 130, ideally 150
+let chosen = null; // the size the player picked in YOUR settings, or null: "Arcade's size"
+
+const applyTextSize = (p) => {
+  document.documentElement.style.fontSize = (chosen ?? Math.min(p ?? 100, MAX)) + '%';
+};
+
+const gem = createGem({ allowedEmbedders, onTextScale: applyTextSize });
+```
+
+It is called on the first push — with `null` when the Arcade gave no advice — and again whenever
+the value changes. The player's own choice in your game beats the Arcade's, the Arcade's is clamped
+to what your layout supports, and with neither you render at 100%. The SDK applies nothing itself.
+
+**This works only if your interface is sized in `rem`:**
+
+- **Every length in your DOM UI is `rem`, `em` or `%`, never `px`:** font sizes, padding, gaps,
+  widths, heights, radii and borders. Then the root font size scales them all together.
+- **Leave the root alone.** The root font size is the browser's default (`100%`), set only by the
+  handler above. A `font` or `font-size` rule on `html` or `:root` breaks every `rem`: put your base
+  font on `body` instead.
+- **Media queries stay in `px`**, and so do values you measure at runtime (positions, safe-area
+  insets). A `rem` in a media query does not follow your root anyway.
+- **Panels that hold text are capped to the screen:** `width: min(22rem, 100% - 2rem)`, so a panel
+  that grows never runs off a phone.
+- **Boxes that hold text grow with it:** `min-height` rather than `height`, and wrapping (or a
+  fit-text routine whose floor you check) rather than `white-space: nowrap` with
+  `overflow: hidden` or an ellipsis on an action label.
+- **Lay out against measured chrome, not constants.** Code that reserves room for a HUD bar or a
+  gear button measures it (`getBoundingClientRect`, a `ResizeObserver`) instead of hard-coding
+  pixels.
+- **Canvas text counts too.** A game that draws interface text on a canvas scales it from the same
+  value.
+- **`text-size-adjust` is not a fix.** It does not protect your layout from any text scaling. Keep
+  `100%` only as cheap protection against iOS's own inflation.
+
+A board or playfield sized from the viewport (a `1/390` unit, say) may keep that unit: it follows
+the screen, which is right for the playfield. Menus, the HUD, settings and dialogs use `rem`.
+
+**Support at least 130%,** with 150% the target and 200% for a game that is mostly text. Check every
+screen at 100%, 130% and your maximum on a phone held upright (390×844), a phone held sideways
+(844×390) and a desktop (1280×800), in your longest language: nothing clipped, overlapping or off
+screen. A phone held sideways runs out of height first, so every screen must fit or scroll
+vertically at your maximum. Rendered text is at least **12 CSS px**, and at least **14 CSS px** for
+what the player must read to act (costs, instructions, buttons), at a 360 CSS px wide viewport.
+
+**A text-size setting of your own** is kept per device, like the Arcade setting it overrides (in
+[device settings](#device-settings-what-this-device-remembers-about-your-game)): a size chosen on a
+phone should not follow the player to a television. Declare it as a `choice` with `icon: 'text'`
+whose **first option is the Arcade's size** — the `null` state, which a slider cannot express:
+
+```js
+{
+  id: 'text',
+  label: t('Text size'),
+  kind: 'choice',
+  icon: 'text',
+  value: chosen === null ? 'arcade' : String(chosen),
+  options: [
+    { id: 'arcade', label: t("Arcade's size") },
+    { id: '100', label: '100%' },
+    { id: '130', label: '130%' },
+    { id: '150', label: '150%' },
+  ],
+}
+```
+
+Your choice overrides the Arcade's **for your game only**; nothing you do changes the Arcade's
+setting.
+
+**Two rules hold however your game uses it, because a text size hints at a player's eyesight:**
+
+- **Never put a text size in analytics.** No event, dimension or measure carries `textScale`, your
+  resolved size, or the value of a text-size change. Recording that the player opened your text
+  settings, without the value, is fine.
+- **Save only the player's own choice.** Never store the Arcade's value as if the player had picked
+  it, and a `null` choice stays `null`, so a later change to the Arcade setting still reaches them.
+
 ### Mirror your settings into the Arcade's menu: `gem.settings`
 
 Optional, and worth doing. The Arcade's Gem menu shows your game's own settings beside the
@@ -1304,8 +1395,24 @@ const declared = () => [
   { id: 'music', label: t('Music'), kind: 'toggle', value: music.on, icon: 'music' }, // the quick row's Music
   { id: 'sfx', label: t('Sound effects'), kind: 'toggle', value: sfx.on, icon: 'sfx' },
   { id: 'colors', label: t('Color help'), kind: 'toggle', value: colorHelp, icon: 'eye' }, // its Color
-  { id: 'musicVolume', label: t('Music volume'), kind: 'slider', value: musicVolume, min: 0, max: 100, step: 5 },
-  { id: 'speed', label: t('Game speed'), kind: 'slider', value: speed, min: 0.5, max: 2, step: 0.25 },
+  {
+    id: 'musicVolume',
+    label: t('Music volume'),
+    kind: 'slider',
+    value: musicVolume,
+    min: 0,
+    max: 100,
+    step: 5,
+  },
+  {
+    id: 'speed',
+    label: t('Game speed'),
+    kind: 'slider',
+    value: speed,
+    min: 0.5,
+    max: 2,
+    step: 0.25,
+  },
   {
     id: 'difficulty',
     label: t('Difficulty'),

package/package.json

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

package/schema/bridge.v1.json

@@ -1007,6 +1007,10 @@
             "2026-10-23): the SDK does NOT fill it. An older parent omits it and the",
             "game reads `null`, \"no recommendation\", never false.",
             "",
+            "`textScale` IS OPTIONAL INSIDE IT AND NOT FILLED either (owner",
+            "decision 2026-11-05), and a parent sends it only where the game",
+            "advertised `textScale`; an absent one is no advice.",
+            "",
             "`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",
@@ -1127,6 +1131,42 @@
                 "reports `null` and the game keeps its own default. Unlike the",
                 "camera and controls fields there is no neutral value to invent."
               ]
+            },
+            "textScale": {
+              "kind": "int",
+              "min": 100,
+              "max": 200,
+              "optional": true,
+              "$comment": [
+                "The player's Arcade Text size for this device, as a percent (owner",
+                "decision 2026-11-05): 100 is the size",
+                "the game was designed at, 200 is twice that. A game sized in `rem`",
+                "applies it by setting its ROOT font size, so its whole interface",
+                "-- text, padding, boxes and icons -- scales together. The Arcade",
+                "never applies it for a game: inside a game's frame, text renders at",
+                "the size the game chose.",
+                "",
+                "A DEFAULT ONLY, like every field here: the player's own text size in",
+                "the game wins, and a game clamps this to the largest size its layout",
+                "supports. A game never saves it as the player's choice and never",
+                "records it in analytics.",
+                "",
+                "BOUNDED 100..200 PERMANENTLY. Any integer in range is valid; a",
+                "parent sends only the six sizes of the Arcade's own control (100,",
+                "115, 130, 150, 180, 200 -- Android's font-scale ladder), its System",
+                "choice resolved to one of them. Nothing below 100: games design to",
+                "a 12 CSS px floor.",
+                "",
+                "SENT ONLY TO A FRAME THAT ADVERTISED `textScale`, which the SDK does",
+                "when the game passes `onTextScale` to `createGem`. That limits which",
+                "games receive the value; it is not a security control. A parent",
+                "whose `recommended` would fail validation with this field in it",
+                "sends `recommended` again without it, so a bad text size never costs",
+                "a game its volume, Color help or graphics.",
+                "",
+                "ABSENT IS NO ADVICE. A parent built against an older SDK, or one",
+                "that keeps no text size, omits it, and the SDK reports `null`."
+              ]
             }
           }
         }

package/schema/capabilities.public.json

@@ -195,6 +195,14 @@
         }
       ]
     },
+    "textScale": {
+      "implemented": true,
+      "gates": [
+        {
+          "namespace": "gem.textScale"
+        }
+      ]
+    },
     "walletDisplay": {
       "implemented": true,
       "gates": [