@indiegems/gem-web-sdk 14.0.3 → 15.0.0

package/docs/api/reference.json

@@ -2,7 +2,7 @@
   "schema_version": 2,
   "source": {
     "repo": "IndieGems/gem-web-sdk",
-    "version": "14.0.3"
+    "version": "15.0.0"
   },
   "entries": [
     {
@@ -9368,6 +9368,22 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "GemOptions.onAudioChannels",
+          "name": "onAudioChannels",
+          "anchor": "gemoptions-onaudiochannels",
+          "group": "start",
+          "signature": "readonly onAudioChannels?: (channels: GemAudioChannels) => void",
+          "documented": true,
+          "summary": "The player turned your game's music, or its sound effects, on or off with\nthe Arcade's **Music** and **Sound** switches. Passing this tells the\nArcade your game honours the two separately, so both switches work for it.\n\nCalled once the Arcade's preferences first arrive, and again whenever\neither value changes. **Turn your music off while `music` is false, and\nyour sound effects off while `sounds` is false**, and back on when they\nare true:\n\n```js\ncreateGem({\n  allowedEmbedders,\n  onAudioChannels: ({ music, sounds }) => {\n    musicBus.gain.value = music ? 1 : 0;   // the music only\n    effectsBus.gain.value = sounds ? 1 : 0; // everything else\n  },\n});\n```\n\nBoth are `true` until the Arcade says otherwise, and under an Arcade that\nhas no such switches. They are the player's Arcade switches, **not your\ngame's settings**: apply them on top of your own music and sound settings\n(music plays while `music` AND your own music setting are on) and never\nsave them as the player's choice in your game. `muted` is unchanged —\nstill the master mute the SDK applies for you.\n\nWithout this option the Arcade cannot tell your music from your effects:\nit mutes your whole game when the player turns both off, and its Music\nswitch flips your own `icon: 'music'` toggle when you declared one with\n[Gem.settings](api-reference-game.md#gem-settings). The same two values are always readable as\n`gem.prefs.music` and `gem.prefs.sounds`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "GemOptions.selectableText",
           "name": "selectableText",
@@ -9799,6 +9815,38 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "GemPrefs.music",
+          "name": "music",
+          "anchor": "gemprefs-music",
+          "group": "player",
+          "signature": "readonly music: boolean",
+          "documented": true,
+          "summary": "The player wants your game's music on — the Arcade's **Music** switch.\n`true` when the Arcade never said.\n\nWhile it is false, stop your music and keep your sound effects playing.\nIt sits on top of `muted` and of your own music setting, and is never\nsaved as one: see [GemOptions.onAudioChannels](api-reference-game.md#gemoptions-onaudiochannels), which is how your\ngame tells the Arcade it honours this.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemPrefs.sounds",
+          "name": "sounds",
+          "anchor": "gemprefs-sounds",
+          "group": "player",
+          "signature": "readonly sounds: boolean",
+          "documented": true,
+          "summary": "The player wants your game's sound effects on — the Arcade's **Sound**\nswitch: every sound that is not your music. `true` when the Arcade never\nsaid.\n\nWhile it is false, silence your effects and keep your music playing. It\nsits on top of `muted` and of your own sound settings, and is never saved\nas one: see [GemOptions.onAudioChannels](api-reference-game.md#gemoptions-onaudiochannels).",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "GemPrefs.locale",
           "name": "locale",
@@ -9831,6 +9879,54 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "GemAudioChannels",
+          "name": "GemAudioChannels",
+          "anchor": "gemaudiochannels",
+          "group": "player",
+          "signature": "interface GemAudioChannels",
+          "documented": true,
+          "summary": "Which of your game's two audio channels the player wants on, from the\nArcade's **Music** and **Sound** switches — what\n[GemOptions.onAudioChannels](api-reference-game.md#gemoptions-onaudiochannels) is called with. Both are `true` when the\nArcade never said.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemAudioChannels.music",
+          "name": "music",
+          "anchor": "gemaudiochannels-music",
+          "group": "player",
+          "signature": "readonly music: boolean",
+          "documented": true,
+          "summary": "Play your music. While false, stop it and keep your effects.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemAudioChannels.sounds",
+          "name": "sounds",
+          "anchor": "gemaudiochannels-sounds",
+          "group": "player",
+          "signature": "readonly sounds: boolean",
+          "documented": true,
+          "summary": "Play your sound effects. While false, silence them and keep your music.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "GemRecommendedSettings",
           "name": "GemRecommendedSettings",

package/docs/changelog.md

@@ -16,6 +16,24 @@ 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.
 
+## 15.0.0
+
+*Written from the API facts alone; no summary was generated for this release.*
+
+Upgrading from 14.0.3. Impact: required.
+
+### Must change
+
+- GemCapability changed its signature.
+- GemHost.sendPrefs changed its signature.
+
+### New capability
+
+- GemAudioChannels was added.
+- GemOptions.onAudioChannels was added.
+- GemPrefs.music was added.
+- GemPrefs.sounds was added.
+
 ## 14.0.3
 
 Upgrading from 14.0.2. Impact: none.

package/docs/getting-started.md

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

package/docs/manifest.json

@@ -38,8 +38,8 @@
     },
     {
       "file": "changelog.md",
-      "sha256": "7858f383ced2f344a4f7852bd4d0ae8d3a2f114f21d2e6e7660e64dd6e2220ae",
-      "updated": "2026-10-21T20:47:06Z"
+      "sha256": "2405f222d6ba0120f9f58dd645a0b8e1659a55faac605935a38d00d50d529e97",
+      "updated": "2026-10-22T16:01:54Z"
     },
     {
       "file": "daily-challenges.md",
@@ -68,8 +68,8 @@
     },
     {
       "file": "getting-started.md",
-      "sha256": "5b5a3affd113400ea9aecbc6af254831ff543278c125a9a11a18fa08ed390171",
-      "updated": "2026-10-21T20:47:06Z"
+      "sha256": "3a6e8a015c5ae067364effd2c0c5432239096d0dc0b5d75ab369194d4f7c8346",
+      "updated": "2026-10-22T16:01:54Z"
     },
     {
       "file": "inventory-and-catalogs.md",
@@ -128,8 +128,8 @@
     },
     {
       "file": "server-bundles.md",
-      "sha256": "72e4035ee007042a4bae279afd4440f36c8d64e0c750978fac6a150fad190d78",
-      "updated": "2026-10-21T20:47:06Z"
+      "sha256": "5e07246cbfdb39d211fcee4f4610b9e6ca8ac8439c1a26751cf80ff68f383459",
+      "updated": "2026-10-22T16:01:54Z"
     },
     {
       "file": "serverless-functions-js.md",
@@ -153,8 +153,8 @@
     },
     {
       "file": "what-a-game-must-do.md",
-      "sha256": "a0f1fd58acd28c72cca3574032c087ffbe2cb34e311086c99eceec7e2f9b7f20",
-      "updated": "2026-10-21T19:36:16Z"
+      "sha256": "1dae31932542cf7d49e8b1c1bc456e62cfb72204e88ea776919cca12c690c859",
+      "updated": "2026-10-22T15:46:02Z"
     }
   ]
 }

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/v14.0.3/gem-web-sdk.tgz
-curl -fsSL https://downloads.gemarcade.com/sdk/v14.0.3/gem-web-sdk.tgz.sri
+curl -fsSL -O https://downloads.gemarcade.com/sdk/v15.0.0/gem-web-sdk.tgz
+curl -fsSL https://downloads.gemarcade.com/sdk/v15.0.0/gem-web-sdk.tgz.sri
 openssl dgst -sha384 -binary gem-web-sdk.tgz | openssl base64 -A
 ```
 

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

@@ -585,12 +585,15 @@ credit for it until you say so.
 Five messages arrive that a game cannot ask for — the parent pushes them on its own schedule, and
 there is no route by which the frame could request one. `createGem` forwards all five:
 
-- **`onPrefs`** — `reducedMotion`, `muted`, `locale`, `showFrameStats` and `recommended`, sent
-  once after the handshake and again on every change. Also **held**, as `gem.prefs`, because a component mounted
+- **`onPrefs`** — `reducedMotion`, `muted`, `music`, `sounds`, `locale`, `showFrameStats` and
+  `recommended`, sent once after the handshake and again on every change. Also **held**, as `gem.prefs`, because a component mounted
   after the push would otherwise have missed it and cannot ask again. Read it where you need it
   rather than caching it — the locale changes mid-session. `muted` is the Arcade's mute: the SDK
   silences your page itself, and your own mute control follows it — see
-  [sound](#sound-your-own-mute-control-and-the-arcades) below. `showFrameStats` you need not act
+  [sound](#sound-your-own-mute-control-and-the-arcades) below. `music` and `sounds` are the
+  Arcade's Music and Sound switches, which your game honours itself — see
+  [the Arcade's Music and Sound switches](#the-arcades-music-and-sound-switches-onaudiochannels).
+  `showFrameStats` you need not act
   on: the SDK counts your frames itself — see [the Arcade's FPS overlay](#the-arcades-fps-overlay). See the language section for how to combine
   `locale` with your own detection. `recommended` is the player's Arcade-wide defaults, which your
   own settings start from — see [game settings](#game-settings).
@@ -1017,11 +1020,15 @@ This is the whole model, and every other page that mentions settings links here:
 - **The Arcade's settings are the player's Arcade-wide defaults for this device.** Your game reads
   them from `gem.prefs.recommended` (and `muted` and `reducedMotion` from `gem.prefs`) and applies
   them again on `onPrefs`. The Arcade never asks your game anything about them.
+- **The quick row's Music and Sound switches are the Arcade's, for every game**: they reach your
+  game as `gem.prefs.music` and `gem.prefs.sounds`, and `onAudioChannels` is how your game honours
+  them ([the Arcade's Music and Sound switches](#the-arcades-music-and-sound-switches-onaudiochannels)).
 - **Every game draws its own settings button, top-right ([the top of the
   screen](#the-top-of-the-screen)), and its own settings screen.** The Arcade's menu never opens it.
 - **A game should also declare its settings — all of them, up to eight — to the Arcade's menu**,
-  with `gem.settings.declare`: the Arcade's Settings screen lists every one, and the first music
-  and colour-help toggles fill the Music and Color slots of its fixed quick row. It is a second way
+  with `gem.settings.declare`: the Arcade's Settings screen lists every one, and the first
+  colour-help toggle fills the Color slot of its fixed quick row (the first music toggle fills Music
+  for a game that does not pass `onAudioChannels`). It is a second way
   to reach them, never the only one, and never a second mute or vibration switch ([mirror your
   settings into the Arcade's menu](#mirror-your-settings-into-the-arcades-menu-gemsettings)).
 - **A setting starts from `recommended` until the player changes it in your game, and then the
@@ -1149,12 +1156,15 @@ player's Arcade-wide ones, in two places:
   fit the three kinds below, not a chosen few: a player who opens the menu mid-game finds every one
   of them without hunting for your settings screen.
 - **Its quick row is fixed: Music, Sound, Color and Vibration, in that order**, with the Arcade's
-  own labels; Vibration is there on phones and tablets only. Sound (your game's mute) and Vibration
-  (the player's Arcade setting) are the Arcade's. Your game fills the other two: **Music** with the
-  first `toggle` you declare with `icon: 'music'`, and **Color** with the first `toggle` you
-  declare with `icon: 'eye'` — a colour-help, colour-blind or high-contrast switch. A slot your
-  game does not fill stays in its place, greyed and inert. Nothing else of yours reaches the quick
-  row.
+  own labels; Vibration is there on phones and tablets only. **Music and Sound are the Arcade's
+  switches for your music and your sound effects**, which reach your game as `gem.prefs.music` and
+  `gem.prefs.sounds` — pass `onAudioChannels` so both work for your game
+  ([the Arcade's Music and Sound switches](#the-arcades-music-and-sound-switches-onaudiochannels)).
+  For a game that does not, the Arcade's Music falls back to the first `toggle` you declare with
+  `icon: 'music'`. Vibration is the player's Arcade setting. **Color** is your game's: the first
+  `toggle` you declare with `icon: 'eye'` — a colour-help, colour-blind or high-contrast switch. A
+  slot that nothing fills stays in its place, greyed and inert. Nothing else of yours reaches the
+  quick row.
 
 **It is a mirror, never a replacement: keep your own settings button and screen**, with every
 setting you declare on it too. An embedder that draws no game settings shows none of this, and the
@@ -1220,10 +1230,10 @@ musicToggle.onchange = () => {
 - **Labels are already in the player's language** (`gem.prefs.locale`): the Arcade does not
   translate them, and cuts them at 40 characters. Declare again when the language changes. The
   quick row shows the Arcade's own labels; yours are what its Settings list shows.
-- **Never declare a second mute or vibration switch.** The quick row already has the Arcade's Sound
-  (your game's mute) and Vibration (the player's Arcade setting); a "Mute", "Sound off" or
-  "Vibration" of yours beside them is a second switch for the same thing, and the player cannot
-  tell which one wins. **Your own levels are yours to declare**: a game volume, music volume or
+- **Never declare a second mute or vibration switch.** The quick row already has the Arcade's Music
+  and Sound (`gem.prefs.music` and `gem.prefs.sounds`, on top of the Arcade's mute) and Vibration
+  (the player's Arcade setting); a "Mute", "All sound off" or "Vibration" of yours beside them is a
+  second switch for the same thing, and the player cannot tell which one wins. **Your own levels are yours to declare**: a game volume, music volume or
   sound-effects volume is your game's level, which starts from the Arcade's `recommended` volume
   like any [game setting](#game-settings) and is set over it — and so are Music and Sound effects
   on/off toggles. Graphics quality and the controls defaults (look sensitivity, invert, touch stick,
@@ -1473,6 +1483,45 @@ calls above, the Arcade's entry and yours stay in step whichever the player uses
   starts, and nothing earlier. The boot order on this page already does that; an `AudioContext` made
   in a module that runs before `createGem` is out of reach.
 
+### The Arcade's Music and Sound switches: `onAudioChannels`
+
+The quick row of the Arcade's Gem menu has a **Music** switch and a **Sound** switch, for every
+game. They tell your game whether to play its **music** and whether to play its **sound effects**
+(everything that is not music: effects, ambience, interface sounds, voices). Only your game knows
+which of its sounds is which, so **your game does the switching**: pass `onAudioChannels` to
+`createGem`, turn your music off when `music` is false, and turn your effects off when `sounds` is
+false.
+
+```js
+const gem = createGem({
+  // ...
+  onAudioChannels: ({ music, sounds }) => {
+    musicBus.gain.value = music ? 1 : 0; // false: stop the music, keep the effects
+    effectsBus.gain.value = sounds ? 1 : 0; // false: silence the effects, keep the music
+  },
+});
+```
+
+- **Passing it is how the Arcade knows.** The SDK tells the Arcade your game honours the two
+  switches only when you pass `onAudioChannels`. Without it the Arcade cannot split your audio: it
+  mutes your whole game (`muted`) when the player turns both off, and its Music switch flips your own
+  music toggle if you [declared one](#mirror-your-settings-into-the-arcades-menu-gemsettings) with
+  `icon: 'music'`. Turning only Sound off then does nothing to your game.
+- **Called when the Arcade's preferences first arrive, and again whenever either value changes** —
+  not on every `gem.prefs` push. The same two values are always readable as `gem.prefs.music` and
+  `gem.prefs.sounds`.
+- **Both are `true` until the Arcade says otherwise**, and stay `true` under an Arcade or an
+  embedder that has no such switches, so the default is the audio your game plays today.
+- **They sit on top of your own settings, and are never saved as them.** Your music plays while
+  `music` is true **and** your own music setting is on; your effects play while `sounds` is true
+  **and** your own sound setting is on. Do not write the Arcade's switch into your saved settings or
+  change your own toggle because it moved: when the player turns it back on, your game's own choice
+  is still there. A music or effects **volume** of yours stays yours too.
+- **Apply them at once, even while paused.** The Gem menu holds your game paused while it is open,
+  and a player who turns Music off expects the music to stop while the menu is still open.
+- **`muted` is unchanged.** It is still the master mute the SDK applies for you, above both
+  switches.
+
 ### Start sound right away; a lift releases it where the browser holds it
 
 **Start your music and sound as soon as the game is ready.** Don't wait for a touch you may not

package/package.json

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

package/schema/bridge.v1.json

@@ -891,6 +891,51 @@
             "the frame would be counting for nobody."
           ]
         },
+        "music": {
+          "kind": "boolean",
+          "optional": true,
+          "$comment": [
+            "The player wants this game's MUSIC on (true) or off (false) — the",
+            "Arcade's Music switch (owner decision 2026-10-22). Absent means true.",
+            "",
+            "A WISH A COOPERATING GAME HONOURS, NOT A MUTE THE SDK ENFORCES. `muted`",
+            "above stays the master mute: the SDK silences the whole frame on it,",
+            "whatever the game does. `music` and `sounds` split the game's audio",
+            "into its two channels, and only the game knows which of its sounds is",
+            "which, so nothing below the game can act on them: a game that opted in",
+            "(capability `audioChannels`) stops its music while this is false and",
+            "starts it again on true, and leaves its sound effects alone. Both",
+            "apply on top of `muted` and on top of the game's own settings — music",
+            "plays only while `muted` is false, this is true, and the game's own",
+            "music setting is on — and a game never writes this into its own saved",
+            "setting.",
+            "",
+            "OPTIONAL because it is additive: a parent that predates it sends none,",
+            "and the frame reads the absence as true — the music the game would",
+            "have played anyway. A parent may send it to any frame (an older one",
+            "ignores the unknown field), but only a frame that advertised",
+            "`audioChannels` is promising to act on it; see that row for what a",
+            "parent does for one that did not.",
+            "",
+            "Sent in every push, like `muted`, and again whenever it changes."
+          ]
+        },
+        "sounds": {
+          "kind": "boolean",
+          "optional": true,
+          "$comment": [
+            "The player wants this game's SOUND EFFECTS on (true) or off (false) —",
+            "the Arcade's Sound switch (owner decision 2026-10-22): every sound the",
+            "game makes that is not its music (effects, ambience, interface clicks,",
+            "voices). Absent means true.",
+            "",
+            "The same contract as `music` above, for the other channel: a wish a",
+            "game that advertised `audioChannels` honours by silencing its effects",
+            "while this is false and leaving its music alone, on top of `muted`",
+            "(still the master mute the SDK enforces) and of the game's own",
+            "settings. OPTIONAL because it is additive; absence is true."
+          ]
+        },
         "locale": {
           "kind": "string",
           "maxLength": 35,

package/schema/capabilities.public.json

@@ -161,6 +161,14 @@
         }
       ]
     },
+    "audioChannels": {
+      "implemented": true,
+      "gates": [
+        {
+          "namespace": "gem.prefs"
+        }
+      ]
+    },
     "walletDisplay": {
       "implemented": true,
       "gates": [