@indiegems/gem-web-sdk 23.0.6 → 23.1.1

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.1
+
+Upgrading from 23.1.0. Impact: none.
+
+Nothing in this release asks anything of a game.
+
+## 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.

package/docs/getting-started.md

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

package/docs/manifest.json

@@ -48,8 +48,8 @@
     },
     {
       "file": "changelog.md",
-      "sha256": "412ce6f6db6c2df07e8b360f71b13635f770453fcd616b4578723a6e85906d5c",
-      "updated": "2026-11-07T03:38:38Z"
+      "sha256": "ffe343dbeb0820cb452ac8395245fa39ae3d09e1b2252eaa3730b566f215a879",
+      "updated": "2026-11-07T17:43:13Z"
     },
     {
       "file": "daily-challenges.md",
@@ -78,8 +78,8 @@
     },
     {
       "file": "getting-started.md",
-      "sha256": "2cba7161b4896dd4a3f448a8ace3f0f2038b9a81de20b69ac8c000b3f50676e3",
-      "updated": "2026-11-07T03:38:38Z"
+      "sha256": "28ab09ea55162912ff25ae8ccb6f6cdc35e494d65ebf5e2b0ee8952ea0265a81",
+      "updated": "2026-11-07T17:43:13Z"
     },
     {
       "file": "graphics-route.md",
@@ -123,8 +123,8 @@
     },
     {
       "file": "rewarded-ads.md",
-      "sha256": "0658ec71ae9938040c2a493385cd9e360224b51309b3254438950124ae444743",
-      "updated": "2026-11-07T02:38:17Z"
+      "sha256": "81b421d4bde3f71b40c7a5a173e6a2c114a315215a11491e488872ff9e1909dc",
+      "updated": "2026-11-07T16:40:01Z"
     },
     {
       "file": "room-shapes.md",
@@ -143,8 +143,8 @@
     },
     {
       "file": "server-bundles.md",
-      "sha256": "58cca5bfe80a301e3b0a8fb35f38668ce8515be38eefcb13b6b2f78c9106280b",
-      "updated": "2026-11-07T03:38:38Z"
+      "sha256": "c6b46f9b4628385858f0834dc4f44b6e737adba5805f3faefda8d4db44878b44",
+      "updated": "2026-11-07T17:43:13Z"
     },
     {
       "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

@@ -110,7 +110,23 @@ rewarded_placements:
 | `cooldown_seconds`        | Seconds between two grants to one player, 0 to 86400. Defaults to 0.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
 | `max_held`                | No grant while the player already holds at least this many of the granted item. 1 to 100, and only on a placement whose grants are all items.                                                                                                                                                                                                                                                                                                                                                                                                                                 |
 | `without_ads`             | **Optional:** `grant` or `nothing`, and `nothing` when you leave it out. What a press gets when no ad plays: where no ad serves your channel at all, and where one does but no ad was available for this press or it failed to play (§8). `grant` pays the reward with no ad, within your caps, so write it out only for a reward that is fine to give free.                                                                                                                                                                                                                  |
-| `allowance_currency_slug` | Optional: one of your own currencies that each grant also spends 1 of. Use it when another path in your game must share the same daily cap. It must not be `client_writable`, must have `transfer_policy: none`, and needs a bucket that resets (daily, say) or it never refills.                                                                                                                                                                                                                                                                                             |
+| `allowance_currency_slug` | Optional: one of your own currencies that each grant also spends 1 of. Use it when another path in your game must share the same daily cap. It must not be `client_writable` and must have `transfer_policy: none`. A grant is refused while it is empty (§3). ⚠️ For an allowance your game grants per use, put it in a bucket that never resets (`reset_interval: never`) for now, even though the upload warns `rewarded_placement_allowance_no_reset` (below).                                                                                                            |
+
+⚠️ **Until a gem-api fix ships, an allowance in a resetting bucket refuses a player's first
+press.** A grant that creates the player's balance of the allowance currency is not stamped with
+the bucket's current period, so the next order on that player's inventory resets it, and the
+press's own check is that order. A bucket that resets to `reset_amount: 0` (`daily`, say) therefore
+empties the first grant before it can be spent, and the press answers `no_ad` with nothing granted.
+Meanwhile:
+
+- **An allowance your game grants per use** (one per level chest, say) needs no refill. Put its
+  currency in a bucket with `reset_interval: never`. The upload's
+  `rewarded_placement_allowance_no_reset` warning is about refilling, which such an allowance does
+  not need, so keep the bucket that never resets when the upload warns.
+- **For a daily cap on this placement alone**, use its own `max_per_day` (§6), which needs no
+  allowance.
+
+This advice will change once the fix is out.
 
 The placement only **selects** a reward your own config declared. Your game sends no reward, no
 amount, no watch time and no item in the request — nothing from your frame is trusted for that — so
@@ -216,6 +232,7 @@ after a press:
 | an ad source serves, but no ad was available for this press, or it failed to play         | your `without_ads` decides: `grant` grants within your caps, with no ad; `nothing` grants nothing, and the Arcade shows "No ad available right now" |
 | no ad source serves the channel (§8)                                                      | your `without_ads` decides, with no ad                                                                                                              |
 | a cap, a cooldown, `max_held`, the platform's spacing (§6), or something about the player | no                                                                                                                                                  |
+| the placement's `allowance_currency_slug` (§2) is empty                                   | no: the answer is `no_ad`, and on `dev` and `test` the console line says the allowance is spent (§10)                                               |
 
 The answer is `shown` whenever the Arcade put its ad stage up, however the ad then ended: watched
 to the end, closed early, or no ad could play and `without_ads` decided. It is `no_ad` when no
@@ -312,8 +329,10 @@ never in a ranked mode — because the platform cannot see a run (§6).
 **Within those rules, draw it only when `gem.ads.rewardedStatus` says it can pay** (SDK 8.1.0 and
 later). The status reads the placement's caps as the platform holds them: `declared`, `grantable`,
 `remainingToday`, `nextEligibleAt`, `heldLimitReached` and `resetsAt`. `grantable` is `false` when
-a cap is spent, a cooldown runs, the player holds `max_held`, or rewarded is off on the channel, so
-drawing on it never offers a press that is certain to pay nothing. Hide or grey the button out
+a cap is spent, a cooldown runs, the player holds `max_held`, or rewarded is off on the channel.
+It does **not** read the placement's `allowance_currency_slug`: with the allowance empty,
+`grantable` is still `true` and the press answers `no_ad`, so read the allowance currency's balance
+yourself before you draw a placement that declares one (§2). Hide or grey the button out
 otherwise, and say when it is back from `nextEligibleAt` or `resetsAt`. `grantable` is not a
 promise: a press can still pay nothing for reasons the read never reports. The status reserves
 nothing, and it never rejects:

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.6/gem-web-sdk.tgz
-curl -fsSL https://downloads.gemarcade.com/sdk/v23.0.6/gem-web-sdk.tgz.sri
+curl -fsSL -O https://downloads.gemarcade.com/sdk/v23.1.1/gem-web-sdk.tgz
+curl -fsSL https://downloads.gemarcade.com/sdk/v23.1.1/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.6",
+  "version": "23.1.1",
   "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": [