@indiegems/gem-web-sdk 24.0.0 → 24.0.2

package/CHANGELOG.md

@@ -8,73 +8,205 @@ Each release states its impact on a game that upgrades to it:
 - **recommended**: nothing should break, but something is worth acting on: a type to rebuild against, a deprecation, or work you may stop doing.
 - **none**: upgrading asks nothing of a game.
 
-Its entries are grouped under up to five headings:
+A release opens with a short summary of what it is about, and its entries are grouped under up to six headings:
 
 - **Must change**: code or behaviour a game has to change, or it stops compiling or stops working.
 - **Should change**: something is deprecated. It keeps working for now; move off it before it is removed.
 - **May stop**: work a game can drop, because the SDK or the Arcade now does it.
 - **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.
+- **Fixes and improvements**: bugs fixed and behaviour improved without a change to the API. Nothing to change in your game.
+
+## 24.0.2
+
+Upgrading from 24.0.1. Impact: none.
+
+This release changes nothing in the public API and asks nothing of a game. The changes are internal: CI checks that the telemetry event lists stay in sync, telemetry documentation, and test vectors for the economy preview.
+
+Nothing in this release asks anything of a game.
+
+## 24.0.1
+
+Upgrading from 24.0.0. Impact: none.
+
+This release has no public API changes, so there is nothing to change in your game and no reason to rebuild. The commits only touch the SDK's release tooling and vendored test data.
+
+Nothing in this release asks anything of a game.
 
 ## 24.0.0
 
 Upgrading from 23.3.0. Impact: required.
 
+This release is mostly the economy-reset work: games can sell a pass by its slug, preview what a config grants including boosts and passes, read earnings from receipts, and gate on a player's passes and boost from a dedicated server. Pass `endsAt` is deprecated in favour of `daysLeft`. A game should review how it tells guests apart and how it reads the offer `kind` of a coin pack, and anyone running the parent conformance kit must adopt kit version 9.
+
 ### Must change
 
-- Stop using the store offers call answering sign_in_required as a test for a guest. A current Arcade now answers a guest with ok, because a guest can buy. Use GemPlayer.isGuest instead. It is true only when the Arcade says the player is a guest who can sign up here, and false for a full account, for a surface with no sign-up, and for an older Arcade that does not say. It follows a guest who signs up in place.
-- Check any code that branches on the offer kind. ArcadeOffer.kind is now typed as ArcadeOfferKind, and a pack of a platform currency other than GEMS is reported as coin_pack rather than gem_pack. The gem_pack value is deprecated. Handle coin_pack wherever you handle gem_pack, or such packs will fall through your branches.
-- If your tests run the parent conformance kit against an Arcade host or a stand-in for one, update them for kit version 9. The version constant moved from 8 to 9, there is a new storeScenario member on the parent under test, and there are six new pass cases. Supply a store scenario so those cases can run.
+- **Offer `kind` has a new value, and non-GEMS packs now report it.** `ArcadeOffer.kind` is now typed `ArcadeOfferKind`. A pack of any platform currency other than GEMS is reported as `coin_pack`. `gem_pack` is deprecated and stays for GEMS packs. Code that matches `kind === "gem_pack"` to find every currency pack will miss coin packs, and an exhaustive `switch` over `kind` will stop compiling.
+
+  ```ts
+  // before
+  if (offer.kind === "gem_pack") showPack(offer);
+
+  // after
+  if (offer.kind === "gem_pack" || offer.kind === "coin_pack") showPack(offer);
+  ```
+- **Do not use `gem.store.offers` answering `sign_in_required` to detect a guest.** A current Arcade answers a guest's `offers` with `ok`, because a guest can buy. On an older Arcade `signInAvailable` reads `true` for every player. For a sign-up gift or any guest-only prompt, read `gem.player.isGuest`. It is `true` only when the Arcade says the player is a guest who can sign up here. It is `false` for a full account, a surface with no sign-up, and an older Arcade that does not say, so no one with an account is offered a gift. It follows a guest who signs up in place.
+
+  ```ts
+  if (gem.player.isGuest) offerSignUpGift();
+  ```
+- **Parent conformance kit is now version 9.** `PARENT_CONFORMANCE_VERSION` went from 8 to 9. If you maintain an Arcade parent or a surface that runs the kit, add the new `storeScenario` member (a `StoreScenario`) to your `ParentUnderTest` adapter. The kit adds six pass cases:
+  - a pass listed by slug;
+  - a pass not on sale;
+  - a pass sold to a guest and to a holder;
+  - a pass left out after two declined sheets;
+  - a minor's listing, which must be indistinguishable from not on sale.
+
+  Games themselves do not run the kit.
 
 ### Should change
 
-- GamePass.endsAt is deprecated on the browser, function and server halves. An exact end instant is a value two games could match to link one player's identities, so the platform will stop sending it and it will read null. Move to GamePass.daysLeft, which gives whole days remaining, capped at 7. A known guest is answered as not holding the pass. See [the deprecation policy](docs/deprecation-policy.md#4-what-is-deprecated-today).
+- **`GamePass.endsAt` is deprecated; use `GamePass.daysLeft`.** An exact end instant could be matched across games to link one player's identities, so the platform will stop sending it and `endsAt` will read `null`. `daysLeft` is whole days, capped at 7. Show it as a countdown instead of computing from a timestamp.
 
-### May stop
+  ```ts
+  // before
+  const ends = pass.endsAt; // Date-like instant
+
+  // after
+  if (pass.daysLeft !== undefined) label = `${pass.daysLeft} days left`;
+  ```
+
+  Check the `daysLeft` type in the reference for how an open-ended pass reads.
 
-- If your game works out expected rewards or the effect of a player's boost by hand, you can drop that arithmetic. The config preview now computes the multiplier, platform grants with their rounding, and bonus eligibility for you.
+  See [the deprecation policy](docs/deprecation-policy.md#4-what-is-deprecated-today).
 
 ### Rebuild
 
-- Types changed in two places. The store offers result now allows an optional pass and optional earn multipliers on each offer. The server match object gains playerPasses and playerBoost. Recompiling is enough, unless your code supplies its own stand-in for the match object, which then needs the two new members.
+- **Types gained members; recompiling is enough.** `GemServer.match` and `GemMatchServer.match` gained `playerPasses` and `playerBoost`, and the offers result type gained optional `pass` and `earnMultipliers`. Existing code that only calls them compiles unchanged. Test doubles or fakes that implement `match` need the two new methods.
 
 ### New capability
 
-- Offers now say which pass they sell and which earn multipliers they carry. Each ArcadeOffer has an optional pass and optional earnMultipliers, so a game can show what an offer raises before the player buys it.
-- A game can sell a pass by its slug. StoreApi.passOnSale tells you whether the pass is on sale here, and StoreApi.showPass opens its sheet. The ShowPassOutcome it returns is ok only once a fresh read of the player's passes shows the pass held, and otherwise ok or pending as that type describes.
-- A game can preview what a config change would grant before applying it. You pass a config id, never an amount or a pass. The preview works out the player's multiplier, holdings and local offers, and reports grants, platform grants with a breakdown crediting a held pass or Boost, bonuses with eligibility and unmet requirements, and upsells for passes the player could buy. Rolls are reported as a count from a table, never an outcome. Errors and targets have their own types.
-- Earnings can be read from a receipt. The new earnings API turns a receipt's platform grant change into the same platform grant shape the preview uses, from the base amount granted and the boost source. It is available on the browser, on the function half, and on the server and match server. The function half resolves the currency from the invoking player's currencies, while the server half takes a currency id only.
-- A dedicated game server can now read a player's passes and Boost in a match. Use the match player passes read to gate on a pass, using the same GamePass shape as the browser. The match player Boost read returns a MatchPlayerBoost with its multipliers, for display only. Both reads go through optional runtime hooks, host.passes and host.boost, and an image without a hook, or a listen host, is refused by name. A refusal surfaces as an API error that keeps its original code.
+- **Sell a pass by its slug.** `gem.store.showPass(slug)` opens the Arcade's store sheet for a pass and answers a `ShowPassOutcome`. It answers `ok` only once a fresh read of `gem.me.passes` shows the pass held; see `ShowPassOutcome` for the other outcomes, including `pending`. `gem.store.passOnSale(slug)` tells you whether the store sells that pass here, so you can hide a button when it does not. A guest can buy, and a minor's listing is indistinguishable from not on sale.
 
-## 23.3.0
+  ```ts
+  if (await gem.store.passOnSale("season-pass")) {
+    const outcome = await gem.store.showPass("season-pass");
+  }
+  ```
+
+  Offers also carry `pass` (the slug of a pass they sell) and `earnMultipliers` (`ArcadeOfferEarnMultiplier`: a `currencySlug` and a `multiplierBp` in basis points). Use them to show what a pass or boost raises.
+- **Preview what a config grants.** `gem.gameConfig.preview` takes a config id, either `{ recipe }` or `{ progression, add? }`, never an amount or a pass. The SDK works out the result from the loaded config and the player's boost, passes and the offers on sale here. The `ConfigPreview` lists:
+  - `grants`: items, game currencies, and rolls as "N rolls from {table}", never an outcome;
+  - `platformGrants`: `base`, `total` and a `breakdown` crediting the held pass or boost, with `on_complete` mappings reported as "if it completes";
+  - `bonuses`: a `BonusPreview` per bonus with `eligible: true | false | 'unknown'` and its `unmet` requirements;
+  - `upsells`: a `PassUpsell` for each pass on sale that the player does not hold, listed only when it would raise a payout or make a bonus eligible.
+
+  ```ts
+  const preview = await gem.gameConfig.preview({ recipe: "forge_sword" });
+  for (const up of preview.upsells) offerPass(up);
+  ```
+
+  Check `PreviewError` for refusals.
+- **Read earnings from a receipt.** `gem.earnings.fromReceipt(change)` turns a receipt's `platform_grant` change into the same platform-grant shape the preview uses (`PlatformGrantPreview`, with a `PlatformGrantSource`), built from `base_granted` and the boost source. It is available in the browser, on the function half (the currency slug comes from the invoking player's currencies), and on the server half (by currency id only).
+
+  ```ts
+  const earned = gem.earnings.fromReceipt(receipt.changes[0]);
+  ```
+- **Gate on a player's passes and boost from a dedicated server.** `gem.match.playerPasses(playerId)` answers the same `GamePass` shape as the browser. It is what a server should gate on. `gem.match.playerBoost(playerId)` answers a `MatchPlayerBoost` (made of `MatchBoostMultiplier`s) and is for display only.
+
+  ```ts
+  const passes = await gem.match.playerPasses(playerId);
+  const boost = await gem.match.playerBoost(playerId);
+  ```
+
+  A refusal arrives as a `GemApiError` that keeps the API's code, such as `client_permission_denied` or `player_not_in_match`. These reads go through the runtime hooks `host.passes(playerId)` and `host.boost(playerId)`, which answer a `GemServerHostRead` (`{ status, body }`). Hosts implement them optionally. A runtime image without them, or a listen host, refuses the call by name.
+
+### Fixes and improvements
+
+- `gem.me.passes` now answers "not held" for a known guest without calling the server.
+- A guest's `gem.store.offers` now answers `ok` on a current Arcade, since a guest can buy.
 
-*Written from the API facts alone; no summary was generated for this release.*
+## 23.3.0
 
 Upgrading from 23.2.0. Impact: required.
 
-### Must change
+This release adds `signInAvailable`, a signal that tells a game whether a sign-in ask can show the player anything, so the game can decide whether to draw a sign-in button or offer a sign-up gift. The API changes are additive: `gem.account` gains a value and a change listener, and the `onPlayer` callback gains an optional second argument. In the Gem Arcade app every player is signed in, so the signal is `false` there.
+
+### Rebuild
 
-- FrameCallbacks.onPlayer changed its signature.
-- FrameOptions.onPlayer changed its signature.
+- The `onPlayer` callback now receives an optional second argument, `signInAvailable?: boolean`, in both `FrameOptions` and `FrameCallbacks`. Existing handlers that take only `player` still compile, so recompiling is enough. A handler that wants the value can take the second parameter:
+
+  ```ts
+  // before
+  onPlayer(player) { render(player); }
+
+  // after
+  onPlayer(player, signInAvailable) { render(player, signInAvailable); }
+  ```
 
 ### New capability
 
-- AccountApi.onSignInAvailableChange was added.
-- AccountApi.signInAvailable was added.
-- GemPlayer.signInAvailable was added.
-- SendPlayerInput.signInAvailable was added.
+- `gem.account.signInAvailable` says whether asking the player to sign in can show anything. `gem.account.onSignInAvailableChange` lets a game react when that value changes.
+
+  The value is:
+
+  - `false` before a player has arrived.
+  - `false` wherever the parent has no `signIn`.
+  - `true` when the parent is older than the field, which is how `requestSignIn` already behaved there.
+
+  `requestSignIn` itself is unchanged. Check the signal before drawing a sign-in button:
+
+  ```ts
+  function updateSignInButton(available: boolean) {
+    signInButton.hidden = !available;
+  }
+
+  updateSignInButton(gem.account.signInAvailable);
+  gem.account.onSignInAvailableChange((available) => updateSignInButton(available));
+  ```
+- The player object now carries an optional boolean `signInAvailable` (`GemPlayer.signInAvailable`), which is the value that `gem.account.signInAvailable` reads. `SendPlayerInput` accepts the same field.
+
+  In the Gem Arcade app every player is a full account, so `signInAvailable` is `false` there and a sign-in ask answers `signed_in` at once. To gate a sign-up gift, test `signInAvailable === true`.
+
+  On an older Arcade the signal reads `true` for every player. Until the Arcade is updated, combine it with the game's existing guest test:
+
+  ```ts
+  if (gem.account.signInAvailable === true && isGuest(player)) {
+    offerSignUpGift();
+  }
+  ```
 
 ## 23.2.0
 
-*Written from the API facts alone; no summary was generated for this release.*
+Upgrading from 23.1.3. Impact: recommended.
 
-Upgrading from 23.1.3. Impact: none.
+`rewardedStatus` now reports the Coin and Gem prices a rewarded placement can be unlocked with, as well as whether the ad can be watched. `grantable` now means the ad or any price can unlock the placement, so check any code that treats it as meaning an ad is available.
 
 ### New capability
 
-- RewardedOption was added.
-- RewardedStatus.adGrantable was added.
-- RewardedStatus.options was added.
+- A rewarded placement can now also be unlocked for platform Coins or Gems. The status you get from `rewardedStatus` has two new fields:
+
+  - `adGrantable` is true when the ad alone can unlock the placement. Ad caps limit only this value.
+  - `options` is the list of `RewardedOption` entries, the prices configured for the placement. It says nothing about the current player.
+
+  `grantable` is now true when the ad or any price can unlock the placement. A price counts only when the Arcade reports it as grantable. If the Arcade reports prices but no ad information, `adGrantable` reads as false.
+
+  Use the new fields to label the button, for example:
+
+  ```ts
+  if (status.adGrantable) {
+    showWatchAdButton();
+  }
+  if (status.options.length > 0) {
+    showPriceButtons(status.options);
+  }
+  ```
+
+  Currencies and scope for placement prices are set with `gemctl platform config`.
+
+### Fixes and improvements
+
+- `grantable` on the rewarded status now stays true when a Coin or Gem price can unlock the placement, even if the ad's caps have been reached. If your game used `grantable` to decide whether to show a "watch ad" button, switch to `adGrantable`.
 
 ## 23.1.3
 
@@ -96,23 +228,32 @@ 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.
 
+Games can now read the player's Arcade Text size and scale their UI to match by opting in with `onTextScale`. Games that don't opt in see no change. Anyone running the parent conformance kit must update their parent adapter for kit version 8.
+
 ### Must change
 
-- PARENT_CONFORMANCE_VERSION changed its signature.
-- GemCapability changed its signature.
-- GemHost.sendPrefs changed its signature.
-- GemPrefs.recommended changed its signature.
+- The parent conformance kit moved from version 7 to 8 and adds a `setTextScale` member to the `ParentUnderTest` adapter. If you run the kit against a parent or host implementation, add `setTextScale` to your adapter so the three new text-scale cases can run. Games that don't run the kit have nothing to change.
+
+### Rebuild
+
+- `GemCapability` gains the `"textScale"` member, and `GemPrefs.recommended` and the `GemHost.sendPrefs` argument gain an optional `textScale?: number`. Recompiling is enough for most games. Only code with an exhaustive `switch` or a `Record<GemCapability, …>` needs a `textScale` case or key added.
 
 ### New capability
 
-- ParentUnderTest.setTextScale was added.
-- Gem.textScale was added.
-- GemOptions.onTextScale was added.
-- GemRecommendedSettings.textScale was added.
+- A game can now follow the player's Arcade Text size. The value arrives as `gem.prefs.recommended.textScale`, an optional integer from 100 to 200. Passing `onTextScale` to `createGem` opts in and advertises the new `textScale` capability. The callback fires on the first push and on every change, and `gem.textScale` holds the latest value. The SDK applies nothing itself, so the game must apply the value. The host only sends the value to games that advertise the capability.
+
+  ```ts
+  const gem = await createGem({
+    onTextScale: (scale) => {
+      // 100 = normal size; apply it to the root font size
+      document.documentElement.style.fontSize = `${scale}%`;
+    },
+  });
+  ```
+
+  For the scale to take effect, size your UI in `rem` units.
 
 ## 23.0.6
 
@@ -152,50 +293,65 @@ Nothing in this release asks anything of a game.
 
 ## 23.0.0
 
-*Written from the API facts alone; no summary was generated for this release.*
-
 Upgrading from 22.0.0. Impact: required.
 
+This release adds a shared Friends window to the Arcade, opened with `gem.friends.inviteToPlay()` and `gem.friends.setInviteParams()`, and makes `gem.me.inventory.onChanged` fire for inventory changes the game did not make through the SDK. Games that only call the SDK need no code changes. Anyone who hosts games in their own parent page (a `GemHost` embedder) or runs the parent conformance kit must update for conformance version 7 and the wider message types.
+
 ### Must change
 
-- PARENT_CONFORMANCE_VERSION changed its signature.
-- GemFrame.requestArcade changed its signature.
-- FRAME_TO_PARENT changed its signature.
-- FrameMessage changed its signature.
-- GemCapability changed its signature.
-- PARENT_TO_FRAME changed its signature.
-- ParentMessage changed its signature.
-
-### New capability
-
-- ParentFixture.channel was added.
-- ParentFixture.gameId was added.
-- ParentUnderTest.deliverSocket was added.
-- CharactersApi.refreshHeld was added.
-- FriendsApi.inviteToPlay was added.
-- FriendsApi.setInviteParams was added.
-- FriendsApiDependencies.inviteToPlay was added.
-- FriendsApiDependencies.setInviteParams was added.
-- PlayInviteRequest was added.
-- FrameCallbacks.onInventoryChanged was added.
-- FrameCallbacks.onPlayInviteResult was added.
-- FrameOptions.onInventoryChanged was added.
-- FrameOptions.onPlayInviteResult was added.
-- GemHost.answerPlayInvite was added.
-- GemHost.relayInventoryEvent was added.
-- GemHost.sendInventoryChanged was added.
-- GemInventoryChanged was added.
-- GemInviteParams was added.
-- GemPlayInviteResult was added.
-- GemRequestPlayInvite was added.
-- HostCallbacks.onInviteParams was added.
-- HostCallbacks.onRequestPlayInvite was added.
-- HostOptions.onInviteParams was added.
-- HostOptions.onRequestPlayInvite was added.
-- validateGemInventoryChanged was added.
-- validateGemInviteParams was added.
-- validateGemPlayInviteResult was added.
-- validateGemRequestPlayInvite was added.
+- The parent conformance kit moves from version 6 to **7**. If you embed games with your own parent and run the kit, update your test setup:
+
+  - The fixture now names a game and a channel (`ParentFixture.gameId`, `ParentFixture.channel`). Use the values the kit gives you, and make your parent's inventory relay check the token's game and channel against them.
+  - Your adapter (`ParentUnderTest`) gains `deliverSocket`. The kit uses it to push socket events into your parent so the new inventory cases can run. Implement it so the socket event reaches the same relay path a real socket would.
+  - Five new inventory cases now run against every parent, including one checking that another game's inventory change is never relayed.
+
+  A parent that fails these cases does not pass conformance version 7.
+
+### May stop
+
+- You can stop polling or manually re-reading inventory after a reward lands. Previously `gem.me.inventory.onChanged` fired only for writes made through the SDK, so games re-read inventory after `gem.functions.invoke`. When the Arcade relays `gem.inventoryChanged` (it must advertise the `inventoryChanged` capability), the SDK drops its cached inventory reads for `gem.me` and every character it holds, and `onChanged` fires. This covers grants from your function or server, purchases, gifts and changes from another device.
+
+### Rebuild
+
+- The message unions and message-name lists grew. `FrameMessage` and `FRAME_TO_PARENT` gain `gem.requestPlayInvite` and `gem.inviteParams`. `ParentMessage` and `PARENT_TO_FRAME` gain `gem.inventoryChanged` and `gem.playInviteResult`. Recompiling is enough for most code. If you have an exhaustive `switch` over these unions, or a table keyed by the message names, add cases for the new messages, or the build will fail or the messages will be unhandled.
+- `GemCapability` gains two members: `playInvites` and `inventoryChanged`. Recompiling is enough unless you have an exhaustive `switch` or a `Record<GemCapability, ...>`. In that case, add entries for the two new values.
+- `GemFrame.requestArcade` now takes `GemArcadeAsk | GemFriendsWindowAsk` instead of `GemArcadeAsk`. Callers are unaffected and recompiling is enough. If you implement or wrap `GemFrame` yourself (for example in a test double), widen your `requestArcade` parameter to the new union.
+
+  ```ts
+  // before
+  requestArcade(msg: GemArcadeAsk): boolean
+  // after
+  requestArcade(msg: GemArcadeAsk | GemFriendsWindowAsk): boolean
+  ```
+
+### New capability
+
+- A game can ask the Arcade to open its shared **Friends window**, and can declare the launch params that window carries when the player opens it from the Arcade menu. Share and friend invites now use the same launch params. Both calls need the `playInvites` capability.
+
+  ```ts
+  // On a player press (e.g. an "Invite friends" button):
+  const shown = await gem.friends.inviteToPlay({ params: { room: "ABCD" } });
+  // shown is false outside the Arcade, without the capability, without a user press,
+  // while another sheet is open, or on timeout. It never rejects.
+
+  // Standing declaration for the window opened from the Arcade menu:
+  gem.friends.setInviteParams({ room: "ABCD" });
+  gem.friends.setInviteParams(null); // clear it
+  ```
+
+  - `inviteToPlay({ params? })` returns `Promise<boolean>`. It is limited to 6 asks a minute.
+  - `setInviteParams(params | null)` is limited to 30 a minute. The SDK holds the value and re-sends it on every handshake. It re-checks the value against the parent's `shareRemap`.
+  - `params` has the same shape and rules as the params of `gem.share.request`. Where `gem.share.request` throws on invalid params, the two invite calls log a warning and send nothing.
+- For embedders: a parent built on `GemHost` can now serve the Friends window and relay inventory changes.
+
+  - **Friends window**: pass `onRequestPlayInvite` and `onInviteParams` (in `HostOptions`/`HostCallbacks`) to handle the game's `gem.requestPlayInvite` and `gem.inviteParams` messages. Call `host.answerPlayInvite(...)` to send back `gem.playInviteResult { requestId, shown }`.
+  - **Inventory**: `GemHost` relays the game's `game_inventory_changed` socket event as `gem.inventoryChanged`. It crosses only after a token, only for the token's game and channel, and only to a frame that advertised the `inventoryChanged` capability. No fields are copied, and sends are coalesced to at most one every two seconds. If you parse the socket yourself, call `sendInventoryChanged` for the same send; `relayInventoryEvent` is also new on `GemHost`.
+  - **Validators**: `validateGemRequestPlayInvite`, `validateGemInviteParams`, `validateGemPlayInviteResult` and `validateGemInventoryChanged` check the new messages (`GemRequestPlayInvite`, `GemInviteParams`, `GemPlayInviteResult`, `GemInventoryChanged`).
+
+### Fixes and improvements
+
+- `gem.me.inventory.onChanged` now fires when the game's inventory changes on the server (a grant from your function or server, a purchase, a gift, or a change from another device). Before, it fired only for writes made through the SDK, so games had to poll after `gem.functions.invoke` to see a reward land. This needs an Arcade that relays `gem.inventoryChanged`.
+- A closed `GemHost` no longer sends a trailing `gem.inventoryChanged` after it has been closed.
 
 ## 22.0.0
 
@@ -336,30 +492,26 @@ Upgrading from 17.0.0. Impact: required.
 
 ## 17.0.0
 
-*Written from the API facts alone; no summary was generated for this release.*
-
 Upgrading from 16.3.1. Impact: required.
 
+This release adds `gem.store.showOffer`, which lets a game point at a single SKU and have the Arcade draw the offer in its own sheet, for promotions whose pitch the bridge cannot carry (pass perks, sales, what a holder already has). Games that only use `gem.store.purchase` need no code changes beyond recompiling. If you run your own parent with `GemHost`, the conformance version moves to 3 and you should re-run the conformance kit.
+
 ### Must change
 
-- PARENT_CONFORMANCE_VERSION changed its signature.
-- FRAME_TO_PARENT changed its signature.
-- FrameMessage changed its signature.
-- GemCapability changed its signature.
-- PARENT_TO_FRAME changed its signature.
-- ParentMessage changed its signature.
+- The parent conformance version went from `2` to `3`. If you embed games with `GemHost` (your own parent page) rather than only building a game for the Arcade, re-run the conformance kit: kit 3 adds three store-offer-sheet cases. Its checkout back-off now also holds a sheet back, so a game cannot get around a back-off by switching from a purchase request to a sheet request. A game that only runs inside the Arcade has nothing to change for this.
+
+### Rebuild
+
+- The message and capability unions each gained a member: `GemCapability` now includes `"storeOfferSheet"`, `FrameMessage` includes `GemRequestStoreOfferSheet` (`"gem.requestStoreOfferSheet"` in `FRAME_TO_PARENT`), and `ParentMessage` includes `GemStoreOfferSheetResult` (`"gem.storeOfferSheetResult"` in `PARENT_TO_FRAME`). Recompiling is enough for most games. Only code that switches exhaustively over one of these unions, or over those constant lists, needs a new case for the added member.
 
 ### New capability
 
-- StoreApi.showOffer was added.
-- StoreApi.showOfferAvailable was added.
-- GemHost.answerStoreOfferSheet was added.
-- GemRequestStoreOfferSheet was added.
-- GemStoreOfferSheetResult was added.
-- HostCallbacks.onRequestStoreOfferSheet was added.
-- HostOptions.onRequestStoreOfferSheet was added.
-- validateGemRequestStoreOfferSheet was added.
-- validateGemStoreOfferSheetResult was added.
+- `store.showOffer` hands the Arcade one SKU and the Arcade draws the offer in its own sheet. Use it when the pitch is something your game cannot draw faithfully: a pass's perks, a sale, or what a holder already has. The sheet's Buy button opens the same checkout as a normal purchase, and none of the pitch details cross to the game, so the game never redraws a promotion.
+
+  - Use `store.purchase` for an offer your game draws itself, and `store.showOffer` for the rest.
+  - `store.showOfferAvailable` is a synchronous check you can call first to see whether the Arcade will draw a sheet, so you can fall back or hide the entry point.
+  - `showOffer` shares `purchase`'s bounds and acting lock, and waits with no timeout, as `purchase` does.
+- For parents built on `GemHost`, there is a new request and result pair for the offer sheet. Pass `onRequestStoreOfferSheet` in `HostOptions` (it is also on `HostCallbacks`) to receive a `GemRequestStoreOfferSheet`. When the player is done with the sheet, answer it with `GemHost.answerStoreOfferSheet`, which sends a `GemStoreOfferSheetResult` to the game. `validateGemRequestStoreOfferSheet` and `validateGemStoreOfferSheetResult` validate the two message shapes.
 
 ## 16.3.1
 
@@ -490,21 +642,42 @@ Upgrading from 15.0.0. Impact: none.
 
 ## 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
+This release adds the Arcade's Music and Sound switches for games: pass `onAudioChannels` to `createGem` and the game is told separately when to play music and when to play sound effects. Nothing in the existing API is removed. The release is marked required because public types changed (`GemCapability`, `GemHost.sendPrefs`), so rebuild the game against it.
+
+### Rebuild
 
-- GemCapability changed its signature.
-- GemHost.sendPrefs changed its signature.
+- Two public types changed in additive ways. Recompiling is enough for almost every game and no code change is needed.
+
+  - `GemCapability` gained the `"audioChannels"` token. Only a game that switches exhaustively over `GemCapability` (for example with a `never` check in the default branch) will fail to compile. Add a case for `"audioChannels"` there.
+  - `GemHost.sendPrefs` now accepts optional `music?: boolean` and `sounds?: boolean` in its `prefs` argument. Existing calls stay valid. This only matters to a game or test harness that implements or calls the host side.
 
 ### New capability
 
-- GemAudioChannels was added.
-- GemOptions.onAudioChannels was added.
-- GemPrefs.music was added.
-- GemPrefs.sounds was added.
+- The Arcade's Gem menu has Music and Sound switches. A game can now honour them by passing `onAudioChannels` to `createGem`. The SDK cannot split a game's audio itself, so it advertises the `audioChannels` capability only when the game passes this handler.
+
+  ```ts
+  const gem = createGem({
+    onAudioChannels: ({ music, sounds }: GemAudioChannels) => {
+      musicBus.setEnabled(music);
+      sfxBus.setEnabled(sounds);
+    },
+  });
+  ```
+
+  Behaviour:
+
+  - The handler is called on the first `gem.prefs` and again whenever either value changes.
+  - `gem.prefs.music` and `gem.prefs.sounds` are always present and default to `true`, including when the Arcade does not send them.
+  - `muted` stays the master mute, which the SDK enforces. It is not folded into `music` or `sounds`, so check both if you need the effective state.
+  - The new `GemAudioChannels` type describes the `{ music, sounds }` argument.
+
+  A game that does not pass `onAudioChannels` keeps working. The Arcade falls back to setting `muted: true` while both switches are off. It drives Music through the game's declared `icon: 'music'` setting (`gem.settingChange`) where there is one.
+
+### Fixes and improvements
+
+- The Gem menu's quick-row Music switch previously worked only for games that declared an `icon: 'music'` setting, and Sound was only the master mute. Both are now independent switches that every game can honour through `onAudioChannels`.
 
 ## 14.0.3
 
@@ -856,33 +1029,57 @@ Upgrading from 8.0.0. Impact: required.
 
 ## 8.0.0
 
-*Written from the API facts alone; no summary was generated for this release.*
-
 Upgrading from 7.9.1. Impact: required.
 
-### Must change
+This release adds `gem.vibration`, which vibrates on iPhones and other browsers without `navigator.vibrate`, and `gem.friends` reads for the friend challenges a player received. Rebuild your game against the new types: `GemCapability`, `FrameMessage` and `BucketConfig` all gained members, which can break exhaustive code.
+
+### Rebuild
+
+- `GemCapability` gains `"vibration"`, `FrameMessage` gains `GemVibrate`, and `FRAME_TO_PARENT` gains `"gem.vibrate"`. Recompiling is enough for most games. If you have an exhaustive `switch` over these unions, or a `Record<GemCapability, …>`, add a case or entry for the new member. If you use `FRAME_TO_PARENT` as a list of known message types, expect one more entry.
+- `BucketConfig` gains an optional `max_balance?: number | null`, a per-bucket holding cap that is omitted when there is none. Recompiling is enough. Code that reads bucket configs should treat a missing or `null` value as no cap.
+
+### New capability
+
+- **Read friend challenges a player received.** `gem.friends` gains three calls for the receiving side of friend challenges:
+
+  - `gem.friends.launchedChallenge(opts?)` resolves to the `FriendChallenge` the player launched your game from, or `null` for an ordinary launch.
+  - `gem.friends.inbox(opts?)` resolves to a `FriendChallengesPage` of every challenge the player received, paged with an opaque cursor like `list`. Answered challenges are included and sorted last, so you can recognise a relaunch.
+  - `gem.friends.markAnswered(id)` marks a challenge answered. It is idempotent.
+
+  ```ts
+  const gem = await createGem();
+  const challenge = await gem.friends.launchedChallenge();
+  if (challenge && !challenge.answeredAt) {
+    // start the challenge round, then when the player finishes:
+    await gem.friends.markAnswered(challenge.id);
+  }
+  ```
+
+  Things to know:
+
+  - `createGem` reads `gemChallenge` from `location.search` when it runs. If your game reads its own launch keys and cleans the URL with `history.replaceState`, do that **after** `createGem`, otherwise `launchedChallenge` silently resolves `null`. Use `launchedChallenge` instead of reading the URL yourself.
+  - `launchedChallenge` never rejects for an ordinary launch. It resolves `null` for no challenge key, a value that is not a UUID, or the platform's uniform not-found answer (`inbox_item_not_found`), as with a shared link or guest launch. Any other 404 still rejects.
+  - `launchedChallenge` is not cached. Check `answeredAt` on each call to tell a replay apart.
+  - `markAnswered` rejects with `not_found` for an unknown challenge or someone else's, and with `invalid` locally for a value that cannot be an id.
+  - `limit` in `inbox` and `list` must be a non-negative integer. A negative, fractional or `NaN` limit is refused with `invalid`.
+  - Challenge `params` come from another player, so check each one before using it.
+- **Vibrate on every platform that can.** `navigator.vibrate` is missing in every WebKit browser, including the Gem Arcade iOS app, and in Firefox 129+. `gem.vibration` is a drop-in for it, taking the same pattern and returning the same boolean.
+
+  ```ts
+  if (gem.vibration.available) {
+    const ok = gem.vibration.vibrate([30, 40, 30]);
+  }
+  ```
+
+  The SDK picks the route by feature detection. If `navigator.vibrate` exists and the device has a coarse pointer, it vibrates locally in the frame. Otherwise it asks the Arcade, if the Arcade supports vibration. If neither works, `available` is `false` and `vibrate` returns `false`.
+
+  The same rules apply on both routes:
+
+  - The frame must have had user activation.
+  - A pattern has at most 99 entries, each 0 to 10 000 ms, and a 10 s total.
+  - At most 600 calls per minute are allowed.
 
-- BucketConfig changed its signature.
-- FRAME_TO_PARENT changed its signature.
-- FrameMessage changed its signature.
-- GemCapability changed its signature.
-
-### New capability
-
-- FriendChallenge was added.
-- FriendChallengesPage was added.
-- FriendsApi.inbox was added.
-- FriendsApi.launchedChallenge was added.
-- FriendsApi.markAnswered was added.
-- FriendsApiDependencies.launchedChallengeId was added.
-- ListFriendChallengesOptions was added.
-- Gem.vibration was added.
-- GemFrame.requestVibrate was added.
-- VibrationApi was added.
-- GemVibrate was added.
-- HostCallbacks.onVibrate was added.
-- HostOptions.onVibrate was added.
-- validateGemVibrate was added.
+  A refused call returns `false` and logs one warning per session through the game's raw log option. `GemFrame.requestVibrate` is the low-level message call behind it. Most games should use `gem.vibration`.
 
 ## 7.9.1