@indiegems/gem-web-sdk 23.2.0 → 24.0.0

package/docs/manifest.json

@@ -13,13 +13,13 @@
     },
     {
       "file": "analytics.md",
-      "sha256": "5814655859e3d6b223f94b71f1b064783b0f242d409c3ec3078089cb4b7c8ec5",
-      "updated": "2026-11-04T17:17:14Z"
+      "sha256": "3f81025a763f96d0ca17f57377042a3e3890797983265cdb1721902b700aa3a6",
+      "updated": "2026-11-09T18:54:26Z"
     },
     {
       "file": "arcade-and-store.md",
-      "sha256": "79bd7829d5a6577d3619d7fd831b74065df883e11eadd1b8153754d97a88474a",
-      "updated": "2026-11-02T18:42:37Z"
+      "sha256": "73e77f3bd0124f69d53b42714fb24c7d128dd1be97e203fc3a353a8eb4e3c05a",
+      "updated": "2026-11-11T01:56:34Z"
     },
     {
       "file": "arcade-avatars.md",
@@ -28,8 +28,8 @@
     },
     {
       "file": "arcade-economy.md",
-      "sha256": "108b3225a45dce776907344f8a3865b99b6e16598c6f70ddf0e8b923cf330a7e",
-      "updated": "2026-11-04T21:50:20Z"
+      "sha256": "6fadbb07d8a6ab44cb231b12a6ba89ce65a46bf42841bff932d3813aa4e0931a",
+      "updated": "2026-11-11T01:56:34Z"
     },
     {
       "file": "async-opponents.md",
@@ -48,8 +48,8 @@
     },
     {
       "file": "changelog.md",
-      "sha256": "819160e36c0258c34aa3e8b06ea0f1e26a50bcc83c5919780de2b33f4fac1cd9",
-      "updated": "2026-11-09T16:19:51Z"
+      "sha256": "f58b3ff7bc37b6da56ac6cc57a72baf32d5e8be83be29be1ec2420971076cee9",
+      "updated": "2026-11-11T03:16:15Z"
     },
     {
       "file": "daily-challenges.md",
@@ -63,8 +63,8 @@
     },
     {
       "file": "deprecation-policy.md",
-      "sha256": "8134d5463e2737116ed23341bf177c51cede4bd86dabec54d76a82c5bfdfade1",
-      "updated": "2026-10-14T22:38:02Z"
+      "sha256": "4622fbf889603436d753013296e9aa8f9edd460ebdae91e4e8594698ea5a0500",
+      "updated": "2026-11-10T21:45:26Z"
     },
     {
       "file": "friends.md",
@@ -78,8 +78,8 @@
     },
     {
       "file": "getting-started.md",
-      "sha256": "763113c6da4ae1d154ba655e44e87f32912a66ea7db40a61dca9c17f51fcc234",
-      "updated": "2026-11-09T16:19:51Z"
+      "sha256": "18a2affd0d2420cd543aabeb3f5d2ef366ef654685e303ef1c9ee2e0ed24eeca",
+      "updated": "2026-11-11T03:16:15Z"
     },
     {
       "file": "graphics-route.md",
@@ -88,8 +88,8 @@
     },
     {
       "file": "inventory-and-catalogs.md",
-      "sha256": "f0445a3b56f7a31590acd9ef2874a7f51cc8d89b6fbfc7de9ea5861f1ef555ca",
-      "updated": "2026-11-08T20:08:14Z"
+      "sha256": "22998fb3ff26d4f9f29d2a73ce6db0ccf42ca2b635f171023a2e2214bbea4b1a",
+      "updated": "2026-11-11T01:56:34Z"
     },
     {
       "file": "leaderboards.md",
@@ -113,18 +113,18 @@
     },
     {
       "file": "platform-rules.md",
-      "sha256": "ab5b971555490956ef50f6141b0f58a6a34335a7e4cc1ef0e4d339a259c9a062",
-      "updated": "2026-10-21T19:36:16Z"
+      "sha256": "e9cb3cf1945002d182d917b0f3f7cfdf26f41de9ec9cd34a47c487cb4c615152",
+      "updated": "2026-11-11T01:56:34Z"
     },
     {
       "file": "player-sign-in.md",
-      "sha256": "22c798ff32ee15dda88f08f6701146f83fe92568c737d9321edd3e2550cb2df9",
-      "updated": "2026-11-09T02:37:14Z"
+      "sha256": "ebdaa0a35815c72148bd72f529b5ecee264c2eeb703e73fdfc277066be63fab4",
+      "updated": "2026-11-11T01:30:40Z"
     },
     {
       "file": "rewarded-ads.md",
-      "sha256": "f632d54aa605b34dc071b59d49e7ecfd35ab95eb6f601885ceb0d3d6fc41a949",
-      "updated": "2026-11-09T15:28:20Z"
+      "sha256": "505a6addbac54b9a154ca0b1afd727d319ba35f5f2a9b24d9835ac2a9104ded8",
+      "updated": "2026-11-11T01:56:34Z"
     },
     {
       "file": "room-shapes.md",
@@ -143,8 +143,8 @@
     },
     {
       "file": "server-bundles.md",
-      "sha256": "b712e407e79482f1edc596ebcaab00852429fbaacebb05d04a2a2f9cbe1f5b9c",
-      "updated": "2026-11-09T16:19:51Z"
+      "sha256": "acc4cd517d6c330640fae1affb2ba15a74c671ae72bdc11d13589ba7b66d5432",
+      "updated": "2026-11-11T03:16:15Z"
     },
     {
       "file": "serverless-functions-js.md",
@@ -168,8 +168,8 @@
     },
     {
       "file": "what-a-game-must-do.md",
-      "sha256": "f70fe9fad67c6b386bddc53f1f876bb78f6a5e11c35f565bb93e925d65a99874",
-      "updated": "2026-11-06T22:48:07Z"
+      "sha256": "c5400f43a1218de0d2838d4332dce4c05afe21ff04e352d2e201ef5bb4268bed",
+      "updated": "2026-11-09T18:39:56Z"
     }
   ]
 }

package/docs/platform-rules.md

@@ -326,41 +326,50 @@ longer one, are in [`server-bundles.md`](server-bundles.md#how-long-your-server-
 
 ## 8. A player's Boost is for display, never a gate
 
-Decided by the platform on **2026-09-26**, and a contract rather than an implementation fact.
+Decided by the platform on **2026-09-26**, restated for VIP on **2026-11-10**, and a contract
+rather than an implementation fact.
 
-The **Boost** is something the Arcade sells for real money, in its own store. While a player has
-one, they earn **Gems and Coins** faster — every grant is multiplied — and their earning limits
-and holdings cap are raised by the same tier. It **never** touches achievement points. The platform applies all of
-it on its own side, when it pays: a game does nothing to make a boost work, and cannot make one
-work harder.
+**Gate on the pass, never on the boost.** What a player paid for is unlocked by the pass, and the
+multiplier it brings is only ever shown.
 
-A game **may show** it. `gem.player.boost` carries each boostable currency's multiplier and the
-whole days left, so a reward screen can say "2× Coins"; see
+A player's earnings multiplier comes from **VIP**, a pass that pays +50% Coins, or from a **Boost**
+bought before the Boost was retired. The platform applies it on its own side, when it pays: every
+Coins grant is multiplied, and the earning limits with it. It **never** touches achievement points.
+A game does nothing to make it work, and cannot make it work harder.
+
+A game **may show** it. `gem.player.boost` carries each currency's multiplier and the whole days
+left, so a reward screen can say "+50% Coins"; see
 [what a game must do](what-a-game-must-do.md#the-signed-in-players-boost-show-it-never-gate-on-it).
-A dedicated server can read the same effective boost for a player in its match, and the same rule
-holds there.
+To show what a payout will be, use `gem.gameConfig.preview`, never your own arithmetic on the
+multiplier. A dedicated server can read the same multiplier for a player in its match
+(`gem.match.playerBoost`), and the same rule holds there.
 
-A game **must not gate** anything on it:
+A game **must not gate** anything on the multiplier:
 
 - **No content or power behind it.** No level, item, character, mode, stat, difficulty setting or
-  extra attempt may depend on whether the player is boosted. A boosted and an unboosted player play
-  the same game.
-- **No prices that depend on it**, and no discount or surcharge keyed on boost status.
-- **No matchmaking on it.** Never exclude, separate or wait on a player because of their boost.
-- **No nagging.** No "you're not boosted" loops, interstitials or countdown pressure. The Arcade owns
-  the Boost store; a game does not sell or advertise boosts.
-
-Three reasons, any one of which would be enough. It is **advisory**: the browser value is pushed on
-connect and on change, so it can lag a boost that just started or ended, and the platform's own
-figure is what pays. It is **forgeable** inside your page, so a gate on it is a gate anyone can
-open. And gating on it turns a faster faucet into pay-to-win, which is the line the Arcade's economy
-is drawn on.
+  extra attempt may depend on whether, or by how much, the player earns faster. A player at 1x and a
+  player at 1.5x play the same game.
+- **No prices that depend on it**, and no discount or surcharge keyed on it.
+- **No matchmaking on it.** Never exclude, separate or wait on a player because of it.
+- **No nagging.** No "you're not boosted" loops, interstitials or countdown pressure.
+
+**What VIP unlocks goes behind the pass.** A VIP room, a VIP roll or a VIP track is a
+`requires: [{ kind: 'holds_pass', pass: 'vip' }]` on the item, recipe, bonus or track, which the
+platform checks when it runs; or a decision your function or server makes from its pass read
+(`gem.me.passes` in a function, `gem.match.playerPasses` on a server). The browser's
+`gem.me.passes` draws the door; it never opens it. Offer VIP only before a reward, by the rules in
+[inventory-and-catalogs.md](inventory-and-catalogs.md#offering-vip-before-a-reward-the-upsell).
+
+Three reasons not to gate on the multiplier, any one of which would be enough. It is **advisory**:
+the browser value is pushed on connect and on change, so it can lag, and the platform's own figure
+is what pays. It is **forgeable** inside your page, so a gate on it is a gate anyone can open. And it
+**is not the purchase**: a player can hold an old Boost without VIP, so a gate on the multiplier
+opens for the wrong player and stays shut for none.
 
 It carries **a day count, never an instant — and capped at 7**, so `7` means "7 or more" — and
-nothing about the tier, the price or whether the player paid at all: free and paid boosts look
-identical to a game. A second-precision expiry would be a near-unique value per player that two
-games could join on, and an exact day count would jump by a purchase's term the moment the player
-paid. Show `7` as "7+ days", never as an end date.
+nothing about the tier, the price or whether the player paid at all. A second-precision expiry
+would be a near-unique value per player that two games could join on, and an exact day count would
+jump by a purchase's term the moment the player paid. Show `7` as "7+ days", never as an end date.
 
 ## Where the rest of it is
 

package/docs/player-sign-in.md

@@ -17,8 +17,65 @@ signInButton.onclick = async () => {
 };
 ```
 
-That is the whole surface. Your game never draws a sign-in form and never handles a password; it
-could not be trusted with either, and it does not need to be.
+That is almost the whole surface. Your game never draws a sign-in form and never handles a
+password; it could not be trusted with either, and it does not need to be.
+
+## Before you draw the button
+
+Not every player can be shown a sign-in. Before you draw "Sign in to claim", read
+`gem.account.signInAvailable`, and listen for it to change:
+
+```js
+const drawUpsell = (available) => {
+  signInButton.hidden = !available;
+};
+drawUpsell(gem.account.signInAvailable);
+gem.account.onSignInAvailableChange(drawUpsell);
+```
+
+- **`true`**: pressing the button will normally put the Arcade's sign-in up for this player. It can
+  still answer `declined` at a busy moment, such as while the Arcade has a sheet or a menu open.
+- **`false`**: pressing it would show nothing. Don't draw the offer. Either the player is already
+  signed in (an ask answers `signed_in` at once), or nothing can be shown here (it answers
+  `unavailable`). It is also `false` until the player is known, and again once the game is
+  disconnected.
+
+**In current Gem Arcade app builds (v3.33.174 and later), every player is already signed in.** The
+app signs each player in to a full account: a device account, Play Games or Game Center, or another
+sign-in. So `signInAvailable` is `false` there, and an ask answers `signed_in` at once, with nothing
+shown. Don't draw a sign-in offer in the app. Older app builds run an older Arcade, where the next
+paragraph applies: `signInAvailable` reads `true` there.
+
+On an Arcade older than this signal, `signInAvailable` reads `true` for every player, a full
+account included. That is how a sign-in ask behaved before the signal existed. So a game that reads
+it keeps its button there, and a player who is already signed in and presses it gets `signed_in`
+at once, with nothing shown. Keep handling every answer quietly (section 3).
+
+`onSignInAvailableChange` runs only when the answer changes: when the player arrives, when a guest
+signs up in place, and when the game is disconnected. It returns a function that stops it.
+
+### Gating a sign-up gift
+
+If your game gives a gift for signing up, offer it only while **`gem.player.isGuest`** is `true`:
+
+```js
+const gem = createGem({
+  // Runs for each pushed player, again when a guest signs up in place.
+  onPlayer: (player) => (signUpGift.hidden = !player.isGuest),
+});
+```
+
+`isGuest` is `true` only when the Arcade says the player is a guest it can sign up here. It is
+`false` for a full account, where the Arcade offers no sign-up, and on an older Arcade that does not
+say, so a gift gated on it never reaches a player who already has an account. On such an older
+Arcade no gift shows at all: the safe way to be wrong.
+
+Use it rather than `signInAvailable`, which reads `true` for every player on an older Arcade (it
+keeps a sign-in button working there), and rather than `gem.store.offers()` answering
+`sign_in_required`, which no longer means a guest: a current Arcade answers a guest's `offers()`
+with `ok`, because a guest can buy, and signs them up first. Pressing the ask answers `signed_in`
+for a player who was signed in all along too, so that answer is no proof of a sign-up either; what
+the gift pays is granted by your function or server, which reads the account itself.
 
 ## 1. Save before you ask
 
@@ -56,7 +113,7 @@ and nothing has changed; hide the upsell.
 |---|---|---|
 | `signed_in` | the player is signed in | re-read, then hide the upsell |
 | `declined` | the player closed the prompt, or the Arcade chose not to show one | return to the game silently |
-| `unavailable` | the Arcade does not offer this here, or never answered | return to the game silently |
+| `unavailable` | the Arcade does not offer this here, or never answered | return to the game silently; `signInAvailable` was `false` for most of these |
 
 `requestSignIn` always resolves when it resolves at all. There is no error branch and no
 `try`/`catch` to write.

package/docs/rewarded-ads.md

@@ -213,7 +213,7 @@ the player then did, so **branch on your inventory, never on the outcome**, as f
   The upload refuses it, and `ad: false` with no `platform_prices` too, since then nothing unlocks
   the placement.
 - **Each currency's spend scope applies,** as it does to an item's price
-  ([`inventory-and-catalogs.md`](inventory-and-catalogs.md#what-coins-and-gems-may-buy-the-spend-scope)):
+  ([`inventory-and-catalogs.md`](inventory-and-catalogs.md#what-coins-may-buy-the-spend-scope)):
   where Coins may price cosmetics only, a Coin price on a placement that grants anything else is
   refused. Gems may price any placement. `gemctl platform config` lists which currencies your
   game may price in, and each one's spend scope: author against it, never against a list you
@@ -226,6 +226,37 @@ for a placement yet.** Until then your prices are not offered, the placement unl
 alone, `ad: false` included, and `rewardedStatus` carries no `options` (§5). Nothing in your game
 needs to change when it goes live: draw the button from `rewardedStatus` and it follows.
 
+### A placement or the store?
+
+Now that a placement can take Coins and Gems, pick by what the player is buying:
+
+- **A single-reward button** (a hint, an extra life, a skip) is a **rewarded placement**, with
+  `platform_prices` for Coins and Gems. Whether it offers the ad, Coins, Gems or any mix is then a
+  config switch (`ad` and `platform_prices`), not code: the button and its `requestAd` stay the
+  same, and the Arcade shows the player the choices.
+- **A real shop** (several items, quantities, locked items) is **store items and recipes** with
+  `platform_prices`
+  ([`inventory-and-catalogs.md`](inventory-and-catalogs.md#16-selling-for-a-platform-currency)).
+  A placement grants one fixed reward per press: it has no list of items, no quantity, and no
+  prerequisite to lock anything behind.
+
+A hint button the player can unlock with an ad or 2 Gems:
+
+```yaml
+rewarded_placements:
+  - placement: hint # exactly the string your game passes
+    grants:
+      - { type: item_grant, item_definition_slug: hint_token, quantity: 1 }
+    max_per_day: 5 # limits the ad only
+    platform_prices:
+      - { currency: GEMS, price: 2 }
+```
+
+Add `{ currency: ARCADE_TICKETS, price: 20 }` beside it for Coins where Coins' spend scope lets
+them price a hint (above), and `ad: false` to drop the ad. Do not also sell `hint_token` in your
+shop: the reward then counts as sold for a platform currency (§1), the upload warns, and outside
+test ads its ad is only served where the platform verifies completion with the ad provider.
+
 ## 3. Ask from the press, then re-read
 
 ```js

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.2.0/gem-web-sdk.tgz
-curl -fsSL https://downloads.gemarcade.com/sdk/v23.2.0/gem-web-sdk.tgz.sri
+curl -fsSL -O https://downloads.gemarcade.com/sdk/v24.0.0/gem-web-sdk.tgz
+curl -fsSL https://downloads.gemarcade.com/sdk/v24.0.0/gem-web-sdk.tgz.sri
 openssl dgst -sha384 -binary gem-web-sdk.tgz | openssl base64 -A
 ```
 
@@ -829,11 +829,13 @@ The short version: the browser half is what a player's **session** can do, and t
 what a **match** can do. `gem.rooms.join()` has no meaning to a process that exists because a match
 was already allocated.
 
-**`gem.me.passes` is browser and function only**, and that is a limit rather than a principle. The
-platform has a match read of which passes a player in your match holds, but your bundle cannot call
-it: it requires the allocation nonce, which the runtime never hands to a bundle, as the boost read
-does, and it answers `403` to every caller until game servers are granted `passes.read`.
-[arcade-and-store.md](arcade-and-store.md#on-a-dedicated-server) has what to do instead.
+**`gem.me.passes` is browser and function only, and `gem.match.playerPasses(playerId)` is the
+server's.** Both routes behind a player's passes and Boost in your match require the allocation
+nonce, which never enters your bundle, so the platform half of the runtime makes the read for you,
+as it does `gem.match.end()`: `gem.match.playerPasses(playerId)` for what to gate on, and
+`gem.match.playerBoost(playerId)` for display only. Each throws on a runtime image that predates it
+and on a listen host. [arcade-and-store.md](arcade-and-store.md#on-a-dedicated-server) has the
+details.
 
 **Rooms are the case where those two answers differ**, so they are worth stating separately rather
 than filed under "browser-only". `gem.rooms` — join, leave, ready up, quick-join — is a player

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

@@ -2404,10 +2404,13 @@ Not on the list above either. When a player reaches for something only an accoun
 `gem.account.requestSignIn` asks the Arcade to sign them in, in its own chrome. Your game draws no
 form and passes nothing.
 
-Two things before you reach for it: **save first**, because the Arcade may sign the player in by
-taking the whole page away, and your game then starts again rather than hearing an answer; and on
-`signed_in`, **re-read what you loaded**, because the player underneath your game may not be the
-one who was there a moment ago. [`player-sign-in.md`](player-sign-in.md) is the page.
+Draw the offer only while `gem.account.signInAvailable` is `true`: it is `false` for a player
+already signed in (every player in a current Gem Arcade app build, v3.33.174 and later, is), and
+wherever nothing can be shown. Two
+things before you reach for it: **save first**, because the Arcade may sign the player in by taking
+the whole page away, and your game then starts again rather than hearing an answer; and on `signed_in`, **re-read what you loaded**, because the player
+underneath your game may not be the one who was there a moment ago.
+[`player-sign-in.md`](player-sign-in.md) is the page.
 
 ## A Share button, if your game has something worth sending a friend
 

package/package.json

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

package/schema/bridge.v1.json

@@ -840,6 +840,47 @@
               ]
             }
           }
+        },
+        "signInAvailable": {
+          "kind": "boolean",
+          "optional": true,
+          "$comment": [
+            "Whether a `gem.requestSignIn` from a player's press would put the",
+            "Arcade's sign-in prompt up for THIS player HERE.",
+            "The SDK reads it as `gem.account.signInAvailable`, so a game hides a",
+            "\"Sign in to claim\" offer that could show nothing.",
+            "",
+            "`true`: a browser guest on a surface that offers sign-up. An ask can",
+            "still answer `declined` at a busy moment (a sheet, a menu, a parked",
+            "game, a second ask); those holds are momentary and not part of this",
+            "field. `false`: an ask shows nothing — it answers `signed_in` at once",
+            "(a full account, which every player in the Gem Arcade app is) or",
+            "`unavailable` (a garden that offers no sign-up, a surface with no",
+            "sign-in). A parent",
+            "that knows sends it on EVERY `gem.player`, `false` included, and",
+            "re-sends the message when it changes (a guest who signs up in place).",
+            "",
+            "ABSENT means an older parent, and a frame reads it as `true`, which is",
+            "what `gem.requestSignIn` did there before this field: a game that adopts",
+            "it keeps its button on an old host. So a parent must never omit it to",
+            "mean `false`.",
+            "",
+            "A BOOLEAN, NEVER AN ENUM. A new enum value is breaking here: an N-1",
+            "frame's validator would refuse the whole message and cost the game its",
+            "player's name.",
+            "",
+            "Platform-assigned, so it sits outside `untrusted`. Ungated like the rest",
+            "of `gem.player`; it means something only beside the `signIn`",
+            "capability, without which the SDK reads `false` whatever it says.",
+            "",
+            "DISCLOSURE. `true` tells a game \"this is a browser guest\": the fact",
+            "`gem.requestSignIn` already discloses, since a",
+            "full account answers `signed_in` at once and a guest's answer follows a",
+            "person. `false` reveals less: it does not tell a signed-in player from",
+            "a surface with no sign-in. And `gem.player` is withheld until the launch is",
+            "confirmed, so an unconfirmed launch learns nothing. It carries no",
+            "sanction, session or age band."
+          ]
         }
       },
       "rateLimit": { "perMinute": 12 }
@@ -6002,7 +6043,7 @@
       "transport": "port",
       "$comment": [
         "Ask what the Arcade Store sells to this player, here, for real money:",
-        "Gem packs, Boosts, passes and bundles. Gated by the `store` capability.",
+        "Coin packs, Boosts, passes and bundles. Gated by the `store` capability.",
         "Answered by `gem.storeOffersResult`.",
         "",
         "WHY THE PARENT ANSWERS IT. The price a player pays depends on the",
@@ -6016,9 +6057,13 @@
         "",
         "A READ, NOT AN ACT: no activation, no mutex. Per-session state comes",
         "back as a reason: `store_off` where the store is withheld (an age or",
-        "region policy, a TV, an in-app browser that takes no payment) and",
-        "`sign_in_required` for a guest, who may then be offered",
-        "gem.requestSignIn."
+        "region policy, a TV, an in-app browser that takes no payment).",
+        "",
+        "A GUEST IS ANSWERED `ok`, with what the store would sell them:",
+        "buying takes a guest through sign-up first, in the parent's own",
+        "chrome, and back to the offer. An",
+        "older parent answered a guest `sign_in_required`, and a frame must",
+        "still read that as nothing for sale."
       ],
       "fields": {
         "requestId": {
@@ -6049,6 +6094,23 @@
         "instead, and a purchase of that offer is answered `declined` /",
         "`cancelled`.",
         "",
+        "WHAT A PASS SAYS, AND WHAT IT MUST NOT. A pass offer names its",
+        "offering slug in `pass` and the earning",
+        "multipliers it carries in `earnMultipliers`, so a game can find VIP by",
+        "slug and preview what it would add without naming a SKU or a number.",
+        "A parent lists a pass only where it would open that pass's sheet: an",
+        "offering with `visible_to_games`, to a player who has not declined",
+        "its sheet twice today. For a KNOWN MINOR it leaves the pass out",
+        "exactly as if it were not on sale - the same `ok`, the same other",
+        "offers, no reason - so a game can never tell a minor from a pass that",
+        "is not sold here. A holder still sees it: the sheet adds time.",
+        "",
+        "COIN PACKS ARE `gem_pack`. The kind enum is closed (a fifth value",
+        "would be refused whole by an N-1 frame), so a pack of any platform",
+        "currency crosses as `gem_pack` with `grant` naming the currency, and",
+        "the SDK reports a pack whose `grant.currency` is not GEMS as",
+        "`coin_pack`.",
+        "",
         "THE NAMES ARE THE PLATFORM'S, not a game developer's: the Arcade",
         "Store's own catalog copy, which is why `name` and `description` sit",
         "outside an `untrusted` object.",
@@ -6090,7 +6152,7 @@
               "kind": {
                 "kind": "enum",
                 "values": ["gem_pack", "boost", "pass", "bundle"],
-                "$comment": "What sort of thing it is. A new sort of SKU is left out of this list by the parent, never sent as a fifth value: an N-1 frame would refuse the whole message."
+                "$comment": "What sort of thing it is. A new sort of SKU is left out of this list by the parent, never sent as a fifth value: an N-1 frame would refuse the whole message. `gem_pack` is a pack of ANY platform currency, Coins included: `grant` says which."
               },
               "name": {
                 "kind": "string",
@@ -6117,12 +6179,12 @@
               "grant": {
                 "kind": "object",
                 "optional": true,
-                "$comment": "For a Gem pack: the currency and amount it grants. Absent for every other kind.",
+                "$comment": "For a currency pack (`gem_pack`): the currency and amount it grants. Absent for every other kind.",
                 "fields": {
                   "currency": {
                     "kind": "string",
                     "maxLength": 32,
-                    "$comment": "The platform currency's exact slug, e.g. GEMS."
+                    "$comment": "The platform currency's exact slug, e.g. ARCADE_TICKETS for Coins."
                   },
                   "amount": {
                     "kind": "int",
@@ -6131,6 +6193,34 @@
                     "$comment": "How much of it."
                   }
                 }
+              },
+              "pass": {
+                "kind": "string",
+                "maxLength": 64,
+                "optional": true,
+                "$comment": "For a pass, or a bundle carrying one: the pass's offering slug, e.g. `vip` - the slug `gem.me.passes` and a `holds_pass` requirement name. Absent for everything else, and from an older parent. Additive: no `v` bump."
+              },
+              "earnMultipliers": {
+                "kind": "array",
+                "maxItems": 8,
+                "optional": true,
+                "$comment": "For an offer that makes the player earn a platform currency faster while held - a pass with the `earn_boost` feature, or a Boost: one entry per currency, as `gem.player`'s `boost.multipliers` carry them. Absent or empty when it boosts nothing. The platform's multiplier, never a game's: the preview reads it to say what holding the pass would add.",
+                "items": {
+                  "kind": "object",
+                  "fields": {
+                    "currencySlug": {
+                      "kind": "string",
+                      "maxLength": 32,
+                      "$comment": "The currency's slug, e.g. ARCADE_TICKETS."
+                    },
+                    "multiplierBp": {
+                      "kind": "int",
+                      "min": 10000,
+                      "max": 1000000,
+                      "$comment": "Basis points: 10000 is 1x, 15000 is 1.5x. gem-api clamps what it applies to 10x."
+                    }
+                  }
+                }
               }
             }
           }