@indiegems/gem-web-sdk 23.2.0 → 24.0.0

package/docs/api/reference.json

@@ -2,7 +2,7 @@
   "schema_version": 2,
   "source": {
     "repo": "IndieGems/gem-web-sdk",
-    "version": "23.2.0"
+    "version": "24.0.0"
   },
   "entries": [
     {
@@ -77,6 +77,10 @@
           "key": "store",
           "title": "The Arcade Store, for real money"
         },
+        {
+          "key": "payout-preview",
+          "title": "Showing a platform payout: preview, upsells and receipts"
+        },
         {
           "key": "branding",
           "title": "The platform branding: logo, wordmark, currency marks"
@@ -3929,7 +3933,7 @@
           "group": "account",
           "signature": "type SignInOutcomeKind = \"signed_in\" | \"declined\" | \"unavailable\"",
           "documented": true,
-          "summary": "The complete vocabulary of answers. Three values, and there will not be a\nfourth.\n\n- `signed_in` — the player is signed in, and [Gem.identity](api-reference-game.md#gem-identity),\n  [Gem.player](api-reference-game.md#gem-player) and [Gem.me](api-reference-game.md#gem-me) already answer for their account.\n  Re-read anything you loaded before asking. Also the answer for a player who\n  was signed in all along.\n- `declined` — the player closed the prompt, or the arcade chose not to show\n  one. Return to the game silently.\n- `unavailable` — the arcade could not offer sign-in, or never answered.\n\nNo reason is given for a `declined`, and one will never be added: why a\nsign-in did not happen is a fact about the player's account, and the arcade\nis the one that explains those.",
+          "summary": "The complete vocabulary of answers. Three values, and there will not be a\nfourth.\n\n- `signed_in` — the player is signed in, and [Gem.identity](api-reference-game.md#gem-identity),\n  [Gem.player](api-reference-game.md#gem-player) and [Gem.me](api-reference-game.md#gem-me) already answer for their account.\n  Re-read anything you loaded before asking. Also the answer for a player who\n  was signed in all along.\n- `declined` — the player closed the prompt, or the arcade chose not to show\n  one. Return to the game silently.\n- `unavailable` — the arcade could not offer sign-in, or never answered.\n  [AccountApi.signInAvailable](api-reference-game.md#accountapi-signinavailable) says so before you draw the button.\n\nNo reason is given for a `declined`, and one will never be added: why a\nsign-in did not happen is a fact about the player's account, and the arcade\nis the one that explains those.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -3986,6 +3990,50 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "AccountApi.signInAvailable",
+          "name": "signInAvailable",
+          "anchor": "accountapi-signinavailable",
+          "group": "account",
+          "signature": "readonly signInAvailable: boolean",
+          "documented": true,
+          "summary": "Whether [AccountApi.requestSignIn](api-reference-game.md#accountapi-requestsignin) can show this player a sign-in\nhere. Read it before you draw a \"Sign in to claim\" button, and hide the\noffer when it is `false`.\n\n- `true` — a guest the arcade can offer sign-up to. An ask may still\n  answer `declined` at a busy moment.\n- `false` — an ask would show nothing. The player is already signed in\n  (it answers `signed_in` at once; every player in a current Gem Arcade\n  app build, v3.33.174 and later, is), or there is no Arcade sign-in here\n  (it answers `unavailable`). Also `false` until the player is known.\n\nOn an arcade older than this signal it reads `true` for every player, a\nfull account included, as before it existed. So gate a sign-up gift on it\nand on the guest test you use today; see docs/player-sign-in.md.\n[AccountApi.onSignInAvailableChange](api-reference-game.md#accountapi-onsigninavailablechange) tells you when it changes.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": "```ts\nconst draw = (available: boolean) => {\n  signInButton.hidden = !available;\n};\ndraw(gem.account.signInAvailable);\ngem.account.onSignInAvailableChange(draw);\n```",
+          "defaultValue": null,
+          "guides": [
+            {
+              "slug": "player-sign-in",
+              "anchor": null
+            }
+          ]
+        },
+        {
+          "id": "AccountApi.onSignInAvailableChange",
+          "name": "onSignInAvailableChange",
+          "anchor": "accountapi-onsigninavailablechange",
+          "group": "account",
+          "signature": "onSignInAvailableChange(listener: (available: boolean) => void): () => void",
+          "documented": true,
+          "summary": "Runs `listener` whenever [AccountApi.signInAvailable](api-reference-game.md#accountapi-signinavailable) changes: when\nthe player arrives, when the arcade changes its answer (a guest who signs\nup), and when the connection closes. Not on a re-sent player with the same\nanswer.",
+          "deprecated": null,
+          "params": [
+            {
+              "name": "listener",
+              "type": "(available: boolean) => void",
+              "optional": false,
+              "summary": null
+            }
+          ],
+          "returns": "A function that stops the listener.",
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "AccountApi.requestSignIn",
           "name": "requestSignIn",
@@ -4735,7 +4783,7 @@
           "group": "analytics",
           "signature": "experiment(key: string, count: number): Promise<number>",
           "documented": true,
-          "summary": "Which arm of one of your experiments this player gets — the same answer on\nevery call, every refresh and every device. Use it wherever you would have\npicked an arm with `Math.random()`, which deals a player a new arm on each\nvisit and makes the test unreadable.\n\nPass a COUNT and get an index, `0` to `count - 1`; pass a LIST of strings\nand get one of them. A string listed twice is twice as likely.\n\n```js\nconst tutorial = await gem.analytics.experiment('tutorial_length', ['short', 'long']);\nconst layout = await gem.analytics.experiment('shop_layout', 3); // 0, 1 or 2\n```\n\nThe selection is a hash of the key and the signed-in player's id — FNV-1a\n32-bit over `\"<key>:<playerId>\"`, then MurmurHash3's 32-bit finalizer, mod\nthe arm count; see\n[experimentSelection](api-reference-game.md#experimentselection), which computes the same answer for an id you\nhold. Hashing the key in is what keeps your experiments independent: the\nplayers in one experiment's first arm are not the same players in every\nother experiment's first arm.\n\n⚠️ **Keep the key and the arms fixed for the life of the experiment.** A new\ncount or list re-deals every player. To start over on purpose, use a new\nkey.\n\n⚠️ **NOTHING IS RECORDED FOR YOU.** The selection is not sent anywhere, and\nthe SDK does not add it to your events. To analyse an experiment, declare a\ndimension for it on the events you want to break down, with the arms as its\nvalues, named after the experiment, and pass the selection there yourself:\n`gem.analytics.track('tutorial_finished', { tutorial_length: tutorial })`.\nNever the platform's `variant` field, which belongs to store-page\nexperiments.\n\nWAITS FOR THE PLAYER. The id arrives with the first play token, so a call\nduring boot waits for it, and rejects as [Gem.awaitIdentity](api-reference-game.md#gem-awaitidentity) does\nwhen none arrives — outside the Arcade, the Gem Editor or the dev host.\nThere is no random fallback: catch the rejection and play your control arm.\nA guest is selected by their guest id, which is stable for as long as their\nguest account lasts; once they sign in to an account they are that\naccount's player, and its selection applies.\n\nIn a serverless function it selects for the player who invoked it, with\nno wait, and rejects when a game server invoked it.\n\nWorks with analytics turned off: it reads no setting and sends nothing.",
+          "summary": "Which arm of one of your experiments this player gets — the same answer on\nevery call, every refresh and every device. Use it wherever you would have\npicked an arm with `Math.random()`, which deals a player a new arm on each\nvisit and makes the test unreadable.\n\nPass a COUNT and get an index, `0` to `count - 1`; pass a LIST of strings\nand get one of them. A string listed twice is twice as likely.\n\n```js\nconst tutorial = await gem.analytics.experiment('tutorial_length', ['short', 'long']);\nconst layout = await gem.analytics.experiment('shop_layout', 3); // 0, 1 or 2\n```\n\nThe selection is a hash of the key and the signed-in player's id — FNV-1a\n32-bit over `\"<key>:<playerId>\"`, then MurmurHash3's 32-bit finalizer, mod\nthe arm count; see\n[experimentSelection](api-reference-game.md#experimentselection), which computes the same answer for an id you\nhold. Hashing the key in is what keeps your experiments independent: the\nplayers in one experiment's first arm are not the same players in every\nother experiment's first arm.\n\n⚠️ **Keep the key and the arms fixed for the life of the experiment.** A new\ncount or list re-deals every player. To start over on purpose, use a new\nkey.\n\n⚠️ **NOTHING IS RECORDED FOR YOU.** The selection is not sent anywhere, and\nthe SDK does not add it to your events. To analyse an experiment, declare a\ndimension for it on the events you want to break down, with the arms as its\nvalues, named after the experiment, and pass the selection there yourself:\n`gem.analytics.track('tutorial_finished', { tutorial_length: tutorial })`.\nNever the platform's `variant` field, which belongs to store-page\nexperiments. For the platform's results to show the test, also declare it\nunder `analytics_tests` in your game config (see docs/analytics.md).\n\nWAITS FOR THE PLAYER. The id arrives with the first play token, so a call\nduring boot waits for it, and rejects as [Gem.awaitIdentity](api-reference-game.md#gem-awaitidentity) does\nwhen none arrives — outside the Arcade, the Gem Editor or the dev host.\nThere is no random fallback: catch the rejection and play your control arm.\nA guest is selected by their guest id, which is stable for as long as their\nguest account lasts; once they sign in to an account they are that\naccount's player, and its selection applies.\n\nIn a serverless function it selects for the player who invoked it, with\nno wait, and rejects when a game server invoked it.\n\nWorks with analytics turned off: it reads no setting and sends nothing.",
           "deprecated": null,
           "params": [
             {
@@ -5545,9 +5593,9 @@
           "name": "kind",
           "anchor": "arcadeoffer-kind",
           "group": "store",
-          "signature": "readonly kind: \"gem_pack\" | \"boost\" | \"pass\" | \"bundle\"",
+          "signature": "readonly kind: ArcadeOfferKind",
           "documented": true,
-          "summary": "What sort of thing it is.",
+          "summary": "What sort of thing it is: `coin_pack`, `boost`, `pass` or `bundle` — or\n`gem_pack`, which is deprecated: Gems are being retired, and a pack of\nCoins is `coin_pack`. Keep a `default` arm. See\n[the deprecation policy](../deprecation-policy.md).",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -5627,7 +5675,7 @@
           "group": "store",
           "signature": "readonly grant?: { currency: string; amount: number }",
           "documented": true,
-          "summary": "For a Gem pack: the platform currency and the amount it grants.",
+          "summary": "For a Coin pack: the platform currency and the amount it grants.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -5643,7 +5691,7 @@
           "group": "store",
           "signature": "readonly currency: string",
           "documented": true,
-          "summary": "The platform currency's exact slug, e.g. `GEMS`.",
+          "summary": "The platform currency's exact slug, e.g. `ARCADE_TICKETS` for Coins.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -5668,6 +5716,166 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "ArcadeOffer.pass",
+          "name": "pass",
+          "anchor": "arcadeoffer-pass",
+          "group": "store",
+          "signature": "readonly pass?: string",
+          "documented": true,
+          "summary": "For a pass, or a bundle carrying one: the pass's slug, such as `vip` — the\nslug `gem.me.passes` reports and [StoreApi.showPass](api-reference-game.md#storeapi-showpass) takes. Absent\nfor everything else, and on an older Arcade.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "ArcadeOffer.earnMultipliers",
+          "name": "earnMultipliers",
+          "anchor": "arcadeoffer-earnmultipliers",
+          "group": "store",
+          "signature": "readonly earnMultipliers: readonly ArcadeOfferEarnMultiplier[]",
+          "documented": true,
+          "summary": "For an offer that makes the player earn a platform currency faster while\nthey hold it: one entry per currency. Empty when it boosts nothing.\n\nThe platform's own figure, for `gem.gameConfig.preview` to work out what\nholding it would add. **Never multiply a reward by it yourself**: the\npreview rounds the way the platform pays.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "ArcadeOfferKind",
+          "name": "ArcadeOfferKind",
+          "anchor": "arcadeofferkind",
+          "group": "store",
+          "signature": "type ArcadeOfferKind = \"coin_pack\" | \"gem_pack\" | \"boost\" | \"pass\" | \"bundle\"",
+          "documented": true,
+          "summary": "What sort of SKU an [ArcadeOffer](api-reference-game.md#arcadeoffer) is. `gem_pack` is deprecated: Gems\nare being retired, and a pack of Coins is `coin_pack`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "ArcadeOfferEarnMultiplier",
+          "name": "ArcadeOfferEarnMultiplier",
+          "anchor": "arcadeofferearnmultiplier",
+          "group": "store",
+          "signature": "interface ArcadeOfferEarnMultiplier",
+          "documented": true,
+          "summary": "One currency an [ArcadeOffer](api-reference-game.md#arcadeoffer) boosts while it is held.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "ArcadeOfferEarnMultiplier.currencySlug",
+          "name": "currencySlug",
+          "anchor": "arcadeofferearnmultiplier-currencyslug",
+          "group": "store",
+          "signature": "readonly currencySlug: string",
+          "documented": true,
+          "summary": "The currency's slug, e.g. `ARCADE_TICKETS`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "ArcadeOfferEarnMultiplier.multiplierBp",
+          "name": "multiplierBp",
+          "anchor": "arcadeofferearnmultiplier-multiplierbp",
+          "group": "store",
+          "signature": "readonly multiplierBp: number",
+          "documented": true,
+          "summary": "Basis points: `10000` is 1x, `15000` is 1.5x. An integer, so the preview\nrounds exactly as the platform does.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "ShowPassOutcome",
+          "name": "ShowPassOutcome",
+          "anchor": "showpassoutcome",
+          "group": "store",
+          "signature": "interface ShowPassOutcome",
+          "documented": true,
+          "summary": "What [StoreApi.showPass](api-reference-game.md#storeapi-showpass) resolves with: an [ArcadeOutcome](api-reference-game.md#arcadeoutcome), plus\nwhether a fresh read shows the pass held.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "ShowPassOutcome.outcome",
+          "name": "outcome",
+          "anchor": "showpassoutcome-outcome",
+          "group": "store",
+          "signature": "readonly outcome: ArcadeOutcomeKind",
+          "documented": true,
+          "summary": "What happened: `ok`, `declined` or `unavailable`. Branch on this.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "ShowPassOutcome.reason",
+          "name": "reason",
+          "anchor": "showpassoutcome-reason",
+          "group": "store",
+          "signature": "readonly reason?: string",
+          "documented": true,
+          "summary": "Why, as a machine code — `busy`, `cancelled`, `not_found`, `pending`,\n`store_off`, `sign_in_required` and more. OPEN-ENDED: the arcade may send a\ncode this SDK has never heard of, so keep a `default` arm and never show a\ncode to a player. Absent when there is nothing to add.\n\nThree are the SDK's own, answered without asking the arcade:\n`unsupported` (the arcade here does not offer this), `invalid_argument`\n(the SDK refused what you passed) and `busy` (another ask of the same kind\nis still open). `error` means no reliable answer arrived — the ask never\nleft, the wait ran out, the bridge closed or the arcade had none. For\n`gem.store.purchase` that makes the outcome UNKNOWN, not a refusal: the\nplayer may have paid.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "ShowPassOutcome.held",
+          "name": "held",
+          "anchor": "showpassoutcome-held",
+          "group": "store",
+          "signature": "readonly held: boolean",
+          "documented": true,
+          "summary": "Whether a fresh read of `gem.me.passes` showed the pass held once the\nsheet closed. `true` exactly when `outcome` is `ok` with no `reason`: a\nrecipe the game runs next gets the pass's bonus.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "StoreOffersOutcome",
           "name": "StoreOffersOutcome",
@@ -5771,7 +5979,7 @@
           "group": "store",
           "signature": "interface StoreApi",
           "documented": true,
-          "summary": "**Real money.** The Arcade Store's own Gem packs, Boosts, passes and bundles,\nbought with the player's money through the Arcade Store's own checkout.\n`gem.store` is one of these. To spend Gems or Coins on your game's own items,\nuse `gem.purchases`.",
+          "summary": "**Real money.** The Arcade Store's own Coin packs, Boosts, passes and bundles,\nbought with the player's money through the Arcade Store's own checkout.\n`gem.store` is one of these. To spend Coins on your game's own items, use\n`gem.purchases`. Only the Arcade sells Coins: a game never sells currency\nfor money.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -5787,7 +5995,7 @@
           "group": "store",
           "signature": "readonly available: boolean",
           "documented": true,
-          "summary": "Whether the Arcade Store answers here, synchronously. Draw your own \"Get\nGems\" button only when it is true.",
+          "summary": "Whether the Arcade Store answers here, synchronously. Draw your own \"Get\nCoins\" button only when it is true.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -5819,7 +6027,7 @@
           "group": "store",
           "signature": "offers(): Promise<StoreOffersOutcome>",
           "documented": true,
-          "summary": "What the store sells this player here: names, art and the rail's own\nprices. `unavailable` / `sign_in_required` for a guest (offer\n`gem.account.requestSignIn`), `unavailable` / `store_off` where the store\nis withheld. Re-read on resume: what is on sale can change.",
+          "summary": "What the store sells this player here: names, art and the rail's own\nprices. A guest is answered too: buying takes them through sign-up first,\nin the Arcade's own screens. `unavailable` / `store_off` where the store is\nwithheld. An older Arcade answers a guest `unavailable` /\n`sign_in_required`. Re-read on resume: what is on sale can change.",
           "deprecated": null,
           "params": [],
           "returns": "Always resolves; never rejects.",
@@ -5858,7 +6066,7 @@
           "group": "store",
           "signature": "showOffer(skuId: string): Promise<ArcadeOutcome>",
           "documented": true,
-          "summary": "Ask the arcade to show one SKU from [StoreApi.offers](api-reference-game.md#storeapi-offers) in its own\nsheet, over your paused and hidden game: its art, what the player gets, a\nsale if one is on, and, for a pass the player already holds, how long it\nhas left. The sheet's Buy opens the same checkout as\n[StoreApi.purchase](api-reference-game.md#storeapi-purchase). Like `purchase`, it needs no press.\n\nUse it for an offer you would have to hardcode a pitch for: VIP and other\npasses, and bundles. Your button only needs to say what it opens. Draw a\nGem pack yourself and use `purchase` instead. Check\n[StoreApi.showOfferAvailable](api-reference-game.md#storeapi-showofferavailable) first, and that the SKU is in `offers`.\n\nIt answers exactly as `purchase` does, with one addition: `declined` /\n`cancelled` also covers the player leaving the sheet without pressing Buy,\nand you are not told which of the two they closed. Do not ask again\nunprompted; the player's next press opens it again. `unavailable` / `unsupported`\nmeans this Arcade does not draw the sheet, and nothing was sent.\n`unavailable` / `error` means **the outcome is unknown**: re-read balances\nand inventory through `gem.me`, and keep listening with\n[StoreApi.onSettled](api-reference-game.md#storeapi-onsettled).\n\nNO TIMEOUT: it waits for as long as the arcade is connected, because a\nplayer may read a sheet and pay for as long as they like.",
+          "summary": "Ask the arcade to show one SKU from [StoreApi.offers](api-reference-game.md#storeapi-offers) in its own\nsheet, over your paused and hidden game: its art, what the player gets, a\nsale if one is on, and, for a pass the player already holds, how long it\nhas left. The sheet's Buy opens the same checkout as\n[StoreApi.purchase](api-reference-game.md#storeapi-purchase). Like `purchase`, it needs no press.\n\nUse it for an offer you would have to hardcode a pitch for: VIP and other\npasses, and bundles. Your button only needs to say what it opens. Draw a\nCoin pack yourself and use `purchase` instead. For a pass, call\n[StoreApi.showPass](api-reference-game.md#storeapi-showpass) with its slug. Check\n[StoreApi.showOfferAvailable](api-reference-game.md#storeapi-showofferavailable) first, and that the SKU is in `offers`.\n\nIt answers exactly as `purchase` does, with one addition: `declined` /\n`cancelled` also covers the player leaving the sheet without pressing Buy,\nand you are not told which of the two they closed. Do not ask again\nunprompted; the player's next press opens it again. `unavailable` / `unsupported`\nmeans this Arcade does not draw the sheet, and nothing was sent.\n`unavailable` / `error` means **the outcome is unknown**: re-read balances\nand inventory through `gem.me`, and keep listening with\n[StoreApi.onSettled](api-reference-game.md#storeapi-onsettled).\n\nNO TIMEOUT: it waits for as long as the arcade is connected, because a\nplayer may read a sheet and pay for as long as they like.",
           "deprecated": null,
           "params": [
             {
@@ -5874,6 +6082,52 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "StoreApi.showPass",
+          "name": "showPass",
+          "anchor": "storeapi-showpass",
+          "group": "store",
+          "signature": "showPass(slug: string): Promise<ShowPassOutcome>",
+          "documented": true,
+          "summary": "Show a pass by its slug in the Arcade's own sheet, over your paused game.\nPass it `upsell.pass` straight from `gem.gameConfig.preview`, never a\nliteral. Sugar over [StoreApi.offers](api-reference-game.md#storeapi-offers) and [StoreApi.showOffer](api-reference-game.md#storeapi-showoffer):\nit finds the offer whose `pass` is `slug` and shows that. A guest is taken\nthrough sign-up first, then back to the sheet.\n\n- `ok`, `held: true` — **a fresh read of `gem.me.passes` shows the pass\n  held.** Run the recipe or claim now, and the pass's bonus applies.\n- `ok` / `pending`, `held: false` — the player paid, and the pass has not\n  arrived yet (Ask to Buy, a slow payment). Run the recipe now, without\n  the bonus: the platform holds nothing back for later.\n- `declined` — they closed the sheet. Run the recipe as it is, and don't\n  ask again at this reward moment.\n- `unavailable` / `not_found` — the pass is not on sale to this player\n  here, or this Arcade is too old to say which offer is a pass, and\n  nothing opened. `unavailable` / `unsupported` — this Arcade draws no\n  sheet. Run the recipe as it is.\n- `unavailable` / `error` — **the outcome is unknown, and the player may\n  have paid.** Run the recipe; `gem.me.passes.on('changed')` hears the\n  pass if it arrives.\n\nNO TIMEOUT on the sheet, as with `showOffer`. After a paid `ok` it reads\n`gem.me.passes` for about ten seconds before it settles for `pending`.",
+          "deprecated": null,
+          "params": [
+            {
+              "name": "slug",
+              "type": "string",
+              "optional": false,
+              "summary": null
+            }
+          ],
+          "returns": "Always resolves; never rejects.",
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "StoreApi.passOnSale",
+          "name": "passOnSale",
+          "anchor": "storeapi-passonsale",
+          "group": "store",
+          "signature": "passOnSale(slug: string): Promise<boolean>",
+          "documented": true,
+          "summary": "Whether the pass `slug` is on sale to this player here, so\n[StoreApi.showPass](api-reference-game.md#storeapi-showpass) would open it. For a screen that sells a pass\noutside a reward moment, such as a \"VIP perks\" panel; at a reward moment,\n`gem.gameConfig.preview`'s `upsells` already says so. `false` where the\nstore is off, for a player the platform won't sell it to, after the\nplayer declined its sheet twice today, and on an older Arcade. A player\nwho holds the pass may still read `true`: the sheet adds time.",
+          "deprecated": null,
+          "params": [
+            {
+              "name": "slug",
+              "type": "string",
+              "optional": false,
+              "summary": null
+            }
+          ],
+          "returns": "Always resolves; never rejects.",
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "StoreApi.onSettled",
           "name": "onSettled",
@@ -7814,6 +8068,374 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "PreviewTarget",
+          "name": "PreviewTarget",
+          "anchor": "previewtarget",
+          "group": "payout-preview",
+          "signature": "type PreviewTarget = { recipe: string } | { progression: string; add?: number }",
+          "documented": true,
+          "summary": "What to preview: a recipe, or a progression with the delta the game is about\nto apply. A config id, never an amount and never a pass.\n\n- `{ recipe: 'open_chest' }` — the recipe's grants, its roll, its bonuses,\n  and the platform payouts of any progression it adds to.\n- `{ progression: 'run_complete' }` — the progression's `on_complete`\n  payouts, \"if it completes\".\n- `{ progression: 'puzzles_cleared', add: 3 }` — its `on_add` payouts for\n  that delta, and its `on_complete` payouts if it completes.\n\nIds and slugs are both accepted, as everywhere in `gem.gameConfig`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "PreviewGrant",
+          "name": "PreviewGrant",
+          "anchor": "previewgrant",
+          "group": "payout-preview",
+          "signature": "type PreviewGrant = { kind: \"item\"; itemId: string; quantity: number } | { kind: \"currency\"; currencyId: string; amount: number } | { kind: \"roll\"; lootTableId: string; count: number }",
+          "documented": true,
+          "summary": "One thing a claim grants in your game. A roll is a count of rolls from a loot\ntable, never what they land on: never show a locked roll's outcome.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "UnmetRequirement",
+          "name": "UnmetRequirement",
+          "anchor": "unmetrequirement",
+          "group": "payout-preview",
+          "signature": "interface UnmetRequirement",
+          "documented": true,
+          "summary": "One requirement a bonus has that the player does not meet: where it is, and its kind.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "UnmetRequirement.index",
+          "name": "index",
+          "anchor": "unmetrequirement-index",
+          "group": "payout-preview",
+          "signature": "readonly index: number",
+          "documented": true,
+          "summary": "Its position in the bonus's `requires`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "UnmetRequirement.kind",
+          "name": "kind",
+          "anchor": "unmetrequirement-kind",
+          "group": "payout-preview",
+          "signature": "readonly kind: string",
+          "documented": true,
+          "summary": "Its kind, such as `holds_pass`. Never the pass or the item it names.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "BonusPreview",
+          "name": "BonusPreview",
+          "anchor": "bonuspreview",
+          "group": "payout-preview",
+          "signature": "interface BonusPreview",
+          "documented": true,
+          "summary": "One `bonuses` entry, and whether this player gets it.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "BonusPreview.id",
+          "name": "id",
+          "anchor": "bonuspreview-id",
+          "group": "payout-preview",
+          "signature": "readonly id: string",
+          "documented": true,
+          "summary": "The bonus's id, as you configured it.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "BonusPreview.grants",
+          "name": "grants",
+          "anchor": "bonuspreview-grants",
+          "group": "payout-preview",
+          "signature": "readonly grants: readonly PreviewGrant[]",
+          "documented": true,
+          "summary": "What it grants.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "BonusPreview.eligible",
+          "name": "eligible",
+          "anchor": "bonuspreview-eligible",
+          "group": "payout-preview",
+          "signature": "readonly eligible: boolean | \"unknown\"",
+          "documented": true,
+          "summary": "`true` — every requirement holds now. `false` — at least one does not\n(see `unmet`). `'unknown'` — one the browser cannot see, such as owning a\nplatform item; never a guess. Advisory: the run decides.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "BonusPreview.unmet",
+          "name": "unmet",
+          "anchor": "bonuspreview-unmet",
+          "group": "payout-preview",
+          "signature": "readonly unmet: readonly UnmetRequirement[]",
+          "documented": true,
+          "summary": "The requirements that do not hold. Empty unless `eligible` is `false`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "PassUpsell",
+          "name": "PassUpsell",
+          "anchor": "passupsell",
+          "group": "payout-preview",
+          "signature": "interface PassUpsell",
+          "documented": true,
+          "summary": "What holding one pass would add to a claim.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "PassUpsell.pass",
+          "name": "pass",
+          "anchor": "passupsell-pass",
+          "group": "payout-preview",
+          "signature": "readonly pass: string",
+          "documented": true,
+          "summary": "The pass's slug: what `gem.store.showPass` takes.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "PassUpsell.name",
+          "name": "name",
+          "anchor": "passupsell-name",
+          "group": "payout-preview",
+          "signature": "readonly name: string",
+          "documented": true,
+          "summary": "The store's own name for it, localized. Show this, never your own word for it.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "PassUpsell.offer",
+          "name": "offer",
+          "anchor": "passupsell-offer",
+          "group": "payout-preview",
+          "signature": "readonly offer: ArcadeOffer",
+          "documented": true,
+          "summary": "The pass's offer, as `gem.store.offers` lists it.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "PassUpsell.platformGrants",
+          "name": "platformGrants",
+          "anchor": "passupsell-platformgrants",
+          "group": "payout-preview",
+          "signature": "readonly platformGrants: readonly { currencySlug?: string; currencyId?: string; total: number; extra: number; ifComplete?: true }[]",
+          "documented": true,
+          "summary": "Each payout this pass would raise: the new `total`, and the `extra` over now.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "PassUpsell.bonuses",
+          "name": "bonuses",
+          "anchor": "passupsell-bonuses",
+          "group": "payout-preview",
+          "signature": "readonly bonuses: readonly { id: string; grants: readonly PreviewGrant[] }[]",
+          "documented": true,
+          "summary": "The bonuses this pass would make eligible.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "ConfigPreview",
+          "name": "ConfigPreview",
+          "anchor": "configpreview",
+          "group": "payout-preview",
+          "signature": "interface ConfigPreview",
+          "documented": true,
+          "summary": "What [PreviewTarget](api-reference-game.md#previewtarget) would give this player now, and what each pass would add.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "ConfigPreview.grants",
+          "name": "grants",
+          "anchor": "configpreview-grants",
+          "group": "payout-preview",
+          "signature": "readonly grants: readonly PreviewGrant[]",
+          "documented": true,
+          "summary": "Your game's own grants: items, game currencies, rolls.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "ConfigPreview.platformGrants",
+          "name": "platformGrants",
+          "anchor": "configpreview-platformgrants",
+          "group": "payout-preview",
+          "signature": "readonly platformGrants: readonly PlatformGrantPreview[]",
+          "documented": true,
+          "summary": "One per platform payout that would fire.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "ConfigPreview.bonuses",
+          "name": "bonuses",
+          "anchor": "configpreview-bonuses",
+          "group": "payout-preview",
+          "signature": "readonly bonuses: readonly BonusPreview[]",
+          "documented": true,
+          "summary": "One per `bonuses` entry, in config order.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "ConfigPreview.upsells",
+          "name": "upsells",
+          "anchor": "configpreview-upsells",
+          "group": "payout-preview",
+          "signature": "readonly upsells: readonly PassUpsell[]",
+          "documented": true,
+          "summary": "One per pass on sale here, not held, that would change this answer. Empty\nmeans show no upsell: no pass would add anything, or none is on sale to\nthis player (a minor, a store that is off, a pass declined twice today, or\nalready held).",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "PreviewError",
+          "name": "PreviewError",
+          "anchor": "previewerror",
+          "group": "failures",
+          "signature": "class PreviewError",
+          "documented": true,
+          "summary": "Why `gem.gameConfig.preview` could not work out an answer.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "PreviewError.code",
+          "name": "code",
+          "anchor": "previewerror-code",
+          "group": "failures",
+          "signature": "readonly code: \"unsupported\" | \"not_found\" | \"invalid_argument\"",
+          "documented": true,
+          "summary": "`not_found` — the config has no recipe or progression by that id or\nslug; `invalid_argument` — the target is not `{ recipe }` or\n`{ progression, add? }` with a positive whole `add`; `unsupported` —\nnot in a browser game (a function or a server runs the recipe and reads\nthe receipt).",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "GemLookSpeed",
           "name": "GemLookSpeed",
@@ -8452,13 +9074,13 @@
           "guides": []
         },
         {
-          "id": "GamePass",
-          "name": "GamePass",
-          "anchor": "gamepass",
-          "group": "saves",
-          "signature": "interface GamePass",
+          "id": "PlatformGrantSource",
+          "name": "PlatformGrantSource",
+          "anchor": "platformgrantsource",
+          "group": "payout-preview",
+          "signature": "type PlatformGrantSource = { source: \"pass\"; pass: string; amount: number } | { source: \"boost\"; amount: number }",
           "documented": true,
-          "summary": "One pass games may see, and whether this player holds it. Listed whether they\nhold it or not, and this is everything a game learns about it.",
+          "summary": "Where the part of a payout above its base comes from.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -8468,13 +9090,13 @@
           "guides": []
         },
         {
-          "id": "GamePass.pass",
-          "name": "pass",
-          "anchor": "gamepass-pass",
-          "group": "saves",
-          "signature": "readonly pass: string",
+          "id": "PlatformGrantPreview",
+          "name": "PlatformGrantPreview",
+          "anchor": "platformgrantpreview",
+          "group": "payout-preview",
+          "signature": "interface PlatformGrantPreview",
           "documented": true,
-          "summary": "The pass's offering slug, such as `vip`. Stable and not localized: key on this.",
+          "summary": "One platform payout — Coins, today — as the preview expects it or a receipt\nreports it, in one shape, so \"you will earn\" and \"you earned\" render with one\ncomponent.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -8484,13 +9106,13 @@
           "guides": []
         },
         {
-          "id": "GamePass.held",
-          "name": "held",
-          "anchor": "gamepass-held",
-          "group": "saves",
-          "signature": "readonly held: boolean",
+          "id": "PlatformGrantPreview.currencySlug",
+          "name": "currencySlug",
+          "anchor": "platformgrantpreview-currencyslug",
+          "group": "payout-preview",
+          "signature": "readonly currencySlug?: string",
           "documented": true,
-          "summary": "Whether the player holds it right now.",
+          "summary": "The currency's slug, e.g. `ARCADE_TICKETS`. Absent when unknown.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -8500,13 +9122,13 @@
           "guides": []
         },
         {
-          "id": "GamePass.endsAt",
-          "name": "endsAt",
-          "anchor": "gamepass-endsat",
-          "group": "saves",
-          "signature": "readonly endsAt: string | null",
+          "id": "PlatformGrantPreview.currencyId",
+          "name": "currencyId",
+          "anchor": "platformgrantpreview-currencyid",
+          "group": "payout-preview",
+          "signature": "readonly currencyId?: string",
           "documented": true,
-          "summary": "When the player stops holding it, RFC 3339 in UTC, grace and any queued\nperiod included. `null` when it is not held, and when it is held with no\nend, so read [GamePass.held](api-reference-game.md#gamepass-held) first: `null` alone never means ended.",
+          "summary": "The currency's id, when it is known.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -8515,6 +9137,109 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "PlatformGrantPreview.base",
+          "name": "base",
+          "anchor": "platformgrantpreview-base",
+          "group": "payout-preview",
+          "signature": "readonly base: number",
+          "documented": true,
+          "summary": "What a player with no pass and no Boost gets.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "PlatformGrantPreview.total",
+          "name": "total",
+          "anchor": "platformgrantpreview-total",
+          "group": "payout-preview",
+          "signature": "readonly total: number",
+          "documented": true,
+          "summary": "What this player gets: `base` plus `breakdown`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "PlatformGrantPreview.breakdown",
+          "name": "breakdown",
+          "anchor": "platformgrantpreview-breakdown",
+          "group": "payout-preview",
+          "signature": "readonly breakdown: readonly PlatformGrantSource[]",
+          "documented": true,
+          "summary": "The part above `base`, and what it is from. Empty when `total` is `base`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "PlatformGrantPreview.ifComplete",
+          "name": "ifComplete",
+          "anchor": "platformgrantpreview-ifcomplete",
+          "group": "payout-preview",
+          "signature": "readonly ifComplete?: true",
+          "documented": true,
+          "summary": "`true` for an `on_complete` payout in a preview: it pays only if this\nclaim completes the progression. Absent otherwise, and on a receipt.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "EarningsApi",
+          "name": "EarningsApi",
+          "anchor": "earningsapi",
+          "group": "payout-preview",
+          "signature": "interface EarningsApi",
+          "documented": true,
+          "summary": "`gem.earnings`: what a payout was, in the shape `gem.gameConfig.preview`\nsays it would be.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "EarningsApi.fromReceipt",
+          "name": "fromReceipt",
+          "anchor": "earningsapi-fromreceipt",
+          "group": "payout-preview",
+          "signature": "fromReceipt(change: unknown): Promise<PlatformGrantPreview | null>",
+          "documented": true,
+          "summary": "Turn one `platform_grant` change from an order's receipt into a\n[PlatformGrantPreview](api-reference-game.md#platformgrantpreview): `base` is what a player with no pass and no\nBoost would have got under the same limits, `total` what this player got,\nand `breakdown` the pass's or the Boost's part, even when a limit trimmed\nthe payout. Draw \"you earned\" with the component that drew \"you will\nearn\". Resolves `null` for any other kind of change.\n\n**This and `preview` are the only way to show a platform payout.** Never\nmultiply by `gem.player.boost`, and never copy a config amount into your\ngame.",
+          "deprecated": null,
+          "params": [
+            {
+              "name": "change",
+              "type": "unknown",
+              "optional": false,
+              "summary": null
+            }
+          ],
+          "returns": "Always resolves; never rejects.",
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "PassesEvent",
           "name": "PassesEvent",
@@ -11989,6 +12714,22 @@
             }
           ]
         },
+        {
+          "id": "GemPlayer.isGuest",
+          "name": "isGuest",
+          "anchor": "gemplayer-isguest",
+          "group": "player",
+          "signature": "readonly isGuest: boolean",
+          "documented": true,
+          "summary": "Whether the Arcade says this player is a **guest it can sign up here**.\n\n`true` only when the Arcade said so. `false` for a player with a full\naccount, on a surface that offers no sign-up, and when the Arcade did not\nsay — an older Arcade — so `false` is never proof of an account. That\nmakes it the test for a sign-up gift: offer one only while this is\n`true`, and the gift can never reach a player who already has an account.\n\nIt changes when a guest signs up in place: `gem.player` is pushed again,\nand `onPlayer` hears it.\n\n```js\nconst gem = createGem({ onPlayer: (player) => (signUpGift.hidden = !player.isGuest) });\n```\n\nFor drawing only, like everything on `gem.player`: what a sign-up earns\nis granted by your function or server, which reads the account itself.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "GemPlayer.playerId",
           "name": "playerId",
@@ -13371,6 +14112,22 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "Gem.earnings",
+          "name": "earnings",
+          "anchor": "gem-earnings",
+          "group": "start",
+          "signature": "readonly earnings: EarningsApi",
+          "documented": true,
+          "summary": "What a platform payout was: `gem.earnings.fromReceipt(change)` turns a\nreceipt's `platform_grant` change into the shape `gem.gameConfig.preview`\ngives, so \"you will earn\" and \"you earned\" draw with one component.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "Gem.purchases",
           "name": "purchases",
@@ -16616,6 +17373,86 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "GamePass",
+          "name": "GamePass",
+          "anchor": "gamepass",
+          "group": "saves",
+          "signature": "interface GamePass",
+          "documented": true,
+          "summary": "One pass games may see, and whether this player holds it. Listed whether they\nhold it or not, and this is everything a game learns about it.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GamePass.pass",
+          "name": "pass",
+          "anchor": "gamepass-pass",
+          "group": "saves",
+          "signature": "readonly pass: string",
+          "documented": true,
+          "summary": "The pass's offering slug, such as `vip`. Stable and not localized: key on this.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GamePass.held",
+          "name": "held",
+          "anchor": "gamepass-held",
+          "group": "saves",
+          "signature": "readonly held: boolean",
+          "documented": true,
+          "summary": "Whether the player holds it right now.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GamePass.daysLeft",
+          "name": "daysLeft",
+          "anchor": "gamepass-daysleft",
+          "group": "saves",
+          "signature": "readonly daysLeft: number",
+          "documented": true,
+          "summary": "Whole days the player keeps it, rounded up so a pass with any time left\nreads at least `1`, and **capped at 7**: `7` means \"7 or more\", and is\nalso what a pass held with no end reads. `0` when it is not held. Show\n`7` as \"7+ days left\", never as an exact end.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GamePass.endsAt",
+          "name": "endsAt",
+          "anchor": "gamepass-endsat",
+          "group": "saves",
+          "signature": "readonly endsAt: string | null",
+          "documented": true,
+          "summary": "When the player stops holding it, RFC 3339 in UTC, grace and any queued\nperiod included. `null` when it is not held, and when it is held with no\nend, so read [GamePass.held](api-reference-game.md#gamepass-held) first: `null` alone never means ended.",
+          "deprecated": "Use [GamePass.daysLeft](api-reference-game.md#gamepass-daysleft). An exact instant is a value two\ngames could match to link one player's identities, so the platform will\nstop sending it; it reads `null` then. See\n[the deprecation policy](../deprecation-policy.md).",
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "PlatformCurrencyAccess",
           "name": "PlatformCurrencyAccess",
@@ -17971,6 +18808,52 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "GemServerHost.passes",
+          "name": "passes",
+          "anchor": "gemserverhost-passes",
+          "group": "match",
+          "signature": "passes(playerId: string): Promise<GemServerHostRead>",
+          "documented": true,
+          "summary": "Ask the platform half which game-visible passes a player in this match\nholds: the match pass read, made with the allocation's own proof.\n\nMAY BE ABSENT on older platform images, exactly as `endMatch` may, and a\nlisten host never has it. `gem.match.playerPasses(playerId)` is this call;\nyou rarely call it yourself.\n\nResolves with what the platform answered — see [GemServerHostRead](api-reference-game.md#gemserverhostread)\n— and rejects only when the platform half could not be asked at all.",
+          "deprecated": null,
+          "params": [
+            {
+              "name": "playerId",
+              "type": "string",
+              "optional": false,
+              "summary": null
+            }
+          ],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemServerHost.boost",
+          "name": "boost",
+          "anchor": "gemserverhost-boost",
+          "group": "match",
+          "signature": "boost(playerId: string): Promise<GemServerHostRead>",
+          "documented": true,
+          "summary": "Ask the platform half for a player's Boost, for display: the match boost\nread, made with the allocation's own proof.\n\nMAY BE ABSENT on older platform images and on a listen host.\n`gem.match.playerBoost(playerId)` is this call; you rarely call it\nyourself. Resolves and rejects as [GemServerHost.passes](api-reference-game.md#gemserverhost-passes) does.",
+          "deprecated": null,
+          "params": [
+            {
+              "name": "playerId",
+              "type": "string",
+              "optional": false,
+              "summary": null
+            }
+          ],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "GemServerHost.log",
           "name": "log",
@@ -18017,6 +18900,54 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "GemServerHostRead",
+          "name": "GemServerHostRead",
+          "anchor": "gemserverhostread",
+          "group": "match",
+          "signature": "interface GemServerHostRead",
+          "documented": true,
+          "summary": "What the platform half answered to a player read it made for this match:\nthe HTTP status and the decoded JSON body, untouched.\n\nThe runtime adds only the allocation's proof, which never enters the bundle\nprocess; the SDK reads the body and turns a refusal into a `GemApiError`, so\na runtime never has to know what the route's answer means.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemServerHostRead.status",
+          "name": "status",
+          "anchor": "gemserverhostread-status",
+          "group": "match",
+          "signature": "readonly status: number",
+          "documented": true,
+          "summary": "The HTTP status the platform answered with.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemServerHostRead.body",
+          "name": "body",
+          "anchor": "gemserverhostread-body",
+          "group": "match",
+          "signature": "readonly body: unknown",
+          "documented": true,
+          "summary": "The decoded JSON body, or `null` when there was none.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "GemServerBundle",
           "name": "GemServerBundle",
@@ -27005,6 +27936,173 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "PlatformGrantSource",
+          "name": "PlatformGrantSource",
+          "anchor": "platformgrantsource",
+          "group": "match",
+          "signature": "type PlatformGrantSource = { source: \"pass\"; pass: string; amount: number } | { source: \"boost\"; amount: number }",
+          "documented": true,
+          "summary": "Where the part of a payout above its base comes from.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "PlatformGrantPreview",
+          "name": "PlatformGrantPreview",
+          "anchor": "platformgrantpreview",
+          "group": "match",
+          "signature": "interface PlatformGrantPreview",
+          "documented": true,
+          "summary": "One platform payout — Coins, today — as the preview expects it or a receipt\nreports it, in one shape, so \"you will earn\" and \"you earned\" render with one\ncomponent.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "PlatformGrantPreview.currencySlug",
+          "name": "currencySlug",
+          "anchor": "platformgrantpreview-currencyslug",
+          "group": "match",
+          "signature": "readonly currencySlug?: string",
+          "documented": true,
+          "summary": "The currency's slug, e.g. `ARCADE_TICKETS`. Absent when unknown.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "PlatformGrantPreview.currencyId",
+          "name": "currencyId",
+          "anchor": "platformgrantpreview-currencyid",
+          "group": "match",
+          "signature": "readonly currencyId?: string",
+          "documented": true,
+          "summary": "The currency's id, when it is known.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "PlatformGrantPreview.base",
+          "name": "base",
+          "anchor": "platformgrantpreview-base",
+          "group": "match",
+          "signature": "readonly base: number",
+          "documented": true,
+          "summary": "What a player with no pass and no Boost gets.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "PlatformGrantPreview.total",
+          "name": "total",
+          "anchor": "platformgrantpreview-total",
+          "group": "match",
+          "signature": "readonly total: number",
+          "documented": true,
+          "summary": "What this player gets: `base` plus `breakdown`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "PlatformGrantPreview.breakdown",
+          "name": "breakdown",
+          "anchor": "platformgrantpreview-breakdown",
+          "group": "match",
+          "signature": "readonly breakdown: readonly PlatformGrantSource[]",
+          "documented": true,
+          "summary": "The part above `base`, and what it is from. Empty when `total` is `base`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "PlatformGrantPreview.ifComplete",
+          "name": "ifComplete",
+          "anchor": "platformgrantpreview-ifcomplete",
+          "group": "match",
+          "signature": "readonly ifComplete?: true",
+          "documented": true,
+          "summary": "`true` for an `on_complete` payout in a preview: it pays only if this\nclaim completes the progression. Absent otherwise, and on a receipt.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "EarningsApi",
+          "name": "EarningsApi",
+          "anchor": "earningsapi",
+          "group": "match",
+          "signature": "interface EarningsApi",
+          "documented": true,
+          "summary": "`gem.earnings`: what a payout was, in the shape `gem.gameConfig.preview`\nsays it would be.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "EarningsApi.fromReceipt",
+          "name": "fromReceipt",
+          "anchor": "earningsapi-fromreceipt",
+          "group": "match",
+          "signature": "fromReceipt(change: unknown): Promise<PlatformGrantPreview | null>",
+          "documented": true,
+          "summary": "Turn one `platform_grant` change from an order's receipt into a\n[PlatformGrantPreview](api-reference-server.md#platformgrantpreview): `base` is what a player with no pass and no\nBoost would have got under the same limits, `total` what this player got,\nand `breakdown` the pass's or the Boost's part, even when a limit trimmed\nthe payout. Draw \"you earned\" with the component that drew \"you will\nearn\". Resolves `null` for any other kind of change.\n\n**This and `preview` are the only way to show a platform payout.** Never\nmultiply by `gem.player.boost`, and never copy a config amount into your\ngame.",
+          "deprecated": null,
+          "params": [
+            {
+              "name": "change",
+              "type": "unknown",
+              "optional": false,
+              "summary": null
+            }
+          ],
+          "returns": "Always resolves; never rejects.",
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "FunctionInvokeOptions",
           "name": "FunctionInvokeOptions",
@@ -27354,6 +28452,86 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "GamePass",
+          "name": "GamePass",
+          "anchor": "gamepass",
+          "group": "match",
+          "signature": "interface GamePass",
+          "documented": true,
+          "summary": "One pass games may see, and whether this player holds it. Listed whether they\nhold it or not, and this is everything a game learns about it.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GamePass.pass",
+          "name": "pass",
+          "anchor": "gamepass-pass",
+          "group": "match",
+          "signature": "readonly pass: string",
+          "documented": true,
+          "summary": "The pass's offering slug, such as `vip`. Stable and not localized: key on this.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GamePass.held",
+          "name": "held",
+          "anchor": "gamepass-held",
+          "group": "match",
+          "signature": "readonly held: boolean",
+          "documented": true,
+          "summary": "Whether the player holds it right now.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GamePass.daysLeft",
+          "name": "daysLeft",
+          "anchor": "gamepass-daysleft",
+          "group": "match",
+          "signature": "readonly daysLeft: number",
+          "documented": true,
+          "summary": "Whole days the player keeps it, rounded up so a pass with any time left\nreads at least `1`, and **capped at 7**: `7` means \"7 or more\", and is\nalso what a pass held with no end reads. `0` when it is not held. Show\n`7` as \"7+ days left\", never as an exact end.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GamePass.endsAt",
+          "name": "endsAt",
+          "anchor": "gamepass-endsat",
+          "group": "match",
+          "signature": "readonly endsAt: string | null",
+          "documented": true,
+          "summary": "When the player stops holding it, RFC 3339 in UTC, grace and any queued\nperiod included. `null` when it is not held, and when it is held with no\nend, so read [GamePass.held](api-reference-server.md#gamepass-held) first: `null` alone never means ended.",
+          "deprecated": "Use [GamePass.daysLeft](api-reference-server.md#gamepass-daysleft). An exact instant is a value two\ngames could match to link one player's identities, so the platform will\nstop sending it; it reads `null` then. See\n[the deprecation policy](../deprecation-policy.md).",
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "Clock",
           "name": "Clock",
@@ -27938,6 +29116,22 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "GemServerHostRead",
+          "name": "GemServerHostRead",
+          "anchor": "gemserverhostread",
+          "group": "host",
+          "signature": "interface GemServerHostRead",
+          "documented": true,
+          "summary": "What the platform half answered to a player read it made for this match:\nthe HTTP status and the decoded JSON body, untouched.\n\nThe runtime adds only the allocation's proof, which never enters the bundle\nprocess; the SDK reads the body and turns a refusal into a `GemApiError`, so\na runtime never has to know what the route's answer means.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "SendOptions",
           "name": "SendOptions",
@@ -28253,6 +29447,118 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "MatchBoostMultiplier",
+          "name": "MatchBoostMultiplier",
+          "anchor": "matchboostmultiplier",
+          "group": "match",
+          "signature": "interface MatchBoostMultiplier",
+          "documented": true,
+          "summary": "One platform currency's Boost, as a dedicated server reads it.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "MatchBoostMultiplier.currencySlug",
+          "name": "currencySlug",
+          "anchor": "matchboostmultiplier-currencyslug",
+          "group": "match",
+          "signature": "readonly currencySlug: string",
+          "documented": true,
+          "summary": "The currency's slug, e.g. `GEMS` or `ARCADE_TICKETS`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "MatchBoostMultiplier.multiplier",
+          "name": "multiplier",
+          "anchor": "matchboostmultiplier-multiplier",
+          "group": "match",
+          "signature": "readonly multiplier: number",
+          "documented": true,
+          "summary": "How much faster the player earns it right now: `2` is 2x, `1` is not boosted.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "MatchPlayerBoost",
+          "name": "MatchPlayerBoost",
+          "anchor": "matchplayerboost",
+          "group": "match",
+          "signature": "interface MatchPlayerBoost",
+          "documented": true,
+          "summary": "A player's Boost, as a dedicated server reads it — **for display only**,\nexactly as `gem.player.boost` is in the browser.\n\n⚠️ **Show it; never gate on it.** Nothing a player can do, reach or win may\ndepend on whether they are boosted. To gate on something a player paid for,\ngate on a pass: `gem.match.playerPasses`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "MatchPlayerBoost.active",
+          "name": "active",
+          "anchor": "matchplayerboost-active",
+          "group": "match",
+          "signature": "readonly active: boolean",
+          "documented": true,
+          "summary": "Whether any currency earns faster than 1x right now.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "MatchPlayerBoost.multipliers",
+          "name": "multipliers",
+          "anchor": "matchplayerboost-multipliers",
+          "group": "match",
+          "signature": "readonly multipliers: readonly MatchBoostMultiplier[]",
+          "documented": true,
+          "summary": "One entry per boostable platform currency, boosted or not.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "MatchPlayerBoost.expiresInDays",
+          "name": "expiresInDays",
+          "anchor": "matchplayerboost-expiresindays",
+          "group": "match",
+          "signature": "readonly expiresInDays?: number",
+          "documented": true,
+          "summary": "Whole days until the soonest boosted currency drops back to 1x, rounded up\nand **capped at 7** (`7` means \"7 or more\"). Absent when nothing is boosted.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "PlayerText",
           "name": "PlayerText",
@@ -28761,7 +30067,7 @@
           "name": "match",
           "anchor": "gemserver-match",
           "group": "api",
-          "signature": "readonly match: { end: null; setBackfill: null; reportPlayers: null }",
+          "signature": "readonly match: { end: null; setBackfill: null; reportPlayers: null; playerPasses: null; playerBoost: null }",
           "documented": true,
           "summary": "Ending the match.\n\n`end()` is HOW A SERVER-AUTHORITATIVE GAME FINISHES. It tells the platform\nthe match is over; the platform then tells the runtime, and your server\nwinds down through its ordinary shutdown. You do not stop the process\nyourself.\n\nIt always means THIS match — the id is already known, so there is nothing to\npass and no way to end someone else's.\n\nThe platform half makes the request, not your process: it holds the proof\nthat this server is the one allocated to the match, which the platform\nrequires. On a platform image too old to offer that, `end()` throws rather\nthan sending a request without the proof.",
           "deprecated": null,
@@ -28853,6 +30159,80 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "GemServer.match.playerPasses",
+          "name": "playerPasses",
+          "anchor": "gemserver-match-playerpasses",
+          "group": "api",
+          "signature": "playerPasses(playerId: string, signal?: AbortSignal): Promise<readonly GamePass[]>",
+          "documented": true,
+          "summary": "Which game-visible passes a player in this match holds, in the shape\n`gem.me.passes.list()` gives in the browser: one entry per pass the\nplatform marked visible to games, held or not, with `held` and\n`daysLeft`.\n\n**This is what to gate on** — a VIP door, a VIP-only mode. `held` is\nexactly what a `requires: holds_pass` requirement on the same slug\ndecides. Read it when the player joins and again when you need it; it is\nnot pushed.",
+          "deprecated": null,
+          "params": [
+            {
+              "name": "playerId",
+              "type": "string",
+              "optional": false,
+              "summary": "A player in THIS match. Anyone else is refused\n  `not_found` (`player_not_in_match`) and nothing about them is read."
+            },
+            {
+              "name": "signal",
+              "type": "AbortSignal",
+              "optional": true,
+              "summary": "Not used — the platform half bounds its own request."
+            }
+          ],
+          "returns": null,
+          "throws": "When the platform image running this server predates the hook, or\n  on a listen host (a player's browser hosting a P2P match), which holds no\n  allocation proof. A `GemApiError` when the platform refuses, including\n  `forbidden` (`client_permission_denied`) until the platform grants game\n  servers the pass read.",
+          "example": "```js\nconst vip = (await gem.match.playerPasses(playerId)).find((p) => p.pass === 'vip');\nif (vip?.held) openVipLounge(playerId);\n```",
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemServer.match.playerBoost",
+          "name": "playerBoost",
+          "anchor": "gemserver-match-playerboost",
+          "group": "api",
+          "signature": "playerBoost(playerId: string, signal?: AbortSignal): Promise<MatchPlayerBoost>",
+          "documented": true,
+          "summary": "A player's Boost, **for display only** — \"2x Coins\" on a results screen.\nNever gate content, difficulty, matchmaking or power on it; gate on a pass\nwith `playerPasses`.",
+          "deprecated": null,
+          "params": [
+            {
+              "name": "playerId",
+              "type": "string",
+              "optional": false,
+              "summary": "A player in THIS match."
+            },
+            {
+              "name": "signal",
+              "type": "AbortSignal",
+              "optional": true,
+              "summary": "Not used — the platform half bounds its own request."
+            }
+          ],
+          "returns": null,
+          "throws": "As `playerPasses` does.",
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemServer.earnings",
+          "name": "earnings",
+          "anchor": "gemserver-earnings",
+          "group": "api",
+          "signature": "readonly earnings: EarningsApi",
+          "documented": true,
+          "summary": "What a platform payout was: `earnings.fromReceipt(change)` turns a\n`platform_grant` change from a receipt into the shape the browser's payout\npreview gives — `base`, `total`, and the pass's or the Boost's part — to\nsend to the player whose screen draws it.\n\nA server has no read of the platform's currencies, so the answer carries\n`currencyId` and no `currencySlug`; the browser's `gem.earnings` fills the\nslug in.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "GemServer.analytics",
           "name": "analytics",
@@ -29582,6 +30962,52 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "GemServerHost.passes",
+          "name": "passes",
+          "anchor": "gemserverhost-passes",
+          "group": "host",
+          "signature": "passes(playerId: string): Promise<GemServerHostRead>",
+          "documented": true,
+          "summary": "Ask the platform half which game-visible passes a player in this match\nholds: the match pass read, made with the allocation's own proof.\n\nMAY BE ABSENT on older platform images, exactly as `endMatch` may, and a\nlisten host never has it. `gem.match.playerPasses(playerId)` is this call;\nyou rarely call it yourself.\n\nResolves with what the platform answered — see [GemServerHostRead](api-reference-server.md#gemserverhostread)\n— and rejects only when the platform half could not be asked at all.",
+          "deprecated": null,
+          "params": [
+            {
+              "name": "playerId",
+              "type": "string",
+              "optional": false,
+              "summary": null
+            }
+          ],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemServerHost.boost",
+          "name": "boost",
+          "anchor": "gemserverhost-boost",
+          "group": "host",
+          "signature": "boost(playerId: string): Promise<GemServerHostRead>",
+          "documented": true,
+          "summary": "Ask the platform half for a player's Boost, for display: the match boost\nread, made with the allocation's own proof.\n\nMAY BE ABSENT on older platform images and on a listen host.\n`gem.match.playerBoost(playerId)` is this call; you rarely call it\nyourself. Resolves and rejects as [GemServerHost.passes](api-reference-server.md#gemserverhost-passes) does.",
+          "deprecated": null,
+          "params": [
+            {
+              "name": "playerId",
+              "type": "string",
+              "optional": false,
+              "summary": null
+            }
+          ],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "GemServerHost.log",
           "name": "log",
@@ -29628,6 +31054,38 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "GemServerHostRead.status",
+          "name": "status",
+          "anchor": "gemserverhostread-status",
+          "group": "host",
+          "signature": "readonly status: number",
+          "documented": true,
+          "summary": "The HTTP status the platform answered with.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemServerHostRead.body",
+          "name": "body",
+          "anchor": "gemserverhostread-body",
+          "group": "host",
+          "signature": "readonly body: unknown",
+          "documented": true,
+          "summary": "The decoded JSON body, or `null` when there was none.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "HostTokenSourceOptions.clock",
           "name": "clock",
@@ -30161,7 +31619,7 @@
           "name": "match",
           "anchor": "gemmatchserver-match",
           "group": "start",
-          "signature": "readonly match: { end: null; setBackfill: null; reportPlayers: null }",
+          "signature": "readonly match: { end: null; setBackfill: null; reportPlayers: null; playerPasses: null; playerBoost: null }",
           "documented": true,
           "summary": "Ending the match.\n\n`end()` is HOW A SERVER-AUTHORITATIVE GAME FINISHES. It tells the platform\nthe match is over; the platform then tells the runtime, and your server\nwinds down through its ordinary shutdown. You do not stop the process\nyourself.\n\nIt always means THIS match — the id is already known, so there is nothing to\npass and no way to end someone else's.\n\nThe platform half makes the request, not your process: it holds the proof\nthat this server is the one allocated to the match, which the platform\nrequires. On a platform image too old to offer that, `end()` throws rather\nthan sending a request without the proof.",
           "deprecated": null,
@@ -30253,6 +31711,80 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "GemMatchServer.match.playerPasses",
+          "name": "playerPasses",
+          "anchor": "gemmatchserver-match-playerpasses",
+          "group": "start",
+          "signature": "playerPasses(playerId: string, signal?: AbortSignal): Promise<readonly GamePass[]>",
+          "documented": true,
+          "summary": "Which game-visible passes a player in this match holds, in the shape\n`gem.me.passes.list()` gives in the browser: one entry per pass the\nplatform marked visible to games, held or not, with `held` and\n`daysLeft`.\n\n**This is what to gate on** — a VIP door, a VIP-only mode. `held` is\nexactly what a `requires: holds_pass` requirement on the same slug\ndecides. Read it when the player joins and again when you need it; it is\nnot pushed.",
+          "deprecated": null,
+          "params": [
+            {
+              "name": "playerId",
+              "type": "string",
+              "optional": false,
+              "summary": "A player in THIS match. Anyone else is refused\n  `not_found` (`player_not_in_match`) and nothing about them is read."
+            },
+            {
+              "name": "signal",
+              "type": "AbortSignal",
+              "optional": true,
+              "summary": "Not used — the platform half bounds its own request."
+            }
+          ],
+          "returns": null,
+          "throws": "When the platform image running this server predates the hook, or\n  on a listen host (a player's browser hosting a P2P match), which holds no\n  allocation proof. A `GemApiError` when the platform refuses, including\n  `forbidden` (`client_permission_denied`) until the platform grants game\n  servers the pass read.",
+          "example": "```js\nconst vip = (await gem.match.playerPasses(playerId)).find((p) => p.pass === 'vip');\nif (vip?.held) openVipLounge(playerId);\n```",
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemMatchServer.match.playerBoost",
+          "name": "playerBoost",
+          "anchor": "gemmatchserver-match-playerboost",
+          "group": "start",
+          "signature": "playerBoost(playerId: string, signal?: AbortSignal): Promise<MatchPlayerBoost>",
+          "documented": true,
+          "summary": "A player's Boost, **for display only** — \"2x Coins\" on a results screen.\nNever gate content, difficulty, matchmaking or power on it; gate on a pass\nwith `playerPasses`.",
+          "deprecated": null,
+          "params": [
+            {
+              "name": "playerId",
+              "type": "string",
+              "optional": false,
+              "summary": "A player in THIS match."
+            },
+            {
+              "name": "signal",
+              "type": "AbortSignal",
+              "optional": true,
+              "summary": "Not used — the platform half bounds its own request."
+            }
+          ],
+          "returns": null,
+          "throws": "As `playerPasses` does.",
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemMatchServer.earnings",
+          "name": "earnings",
+          "anchor": "gemmatchserver-earnings",
+          "group": "start",
+          "signature": "readonly earnings: EarningsApi",
+          "documented": true,
+          "summary": "What a platform payout was: `earnings.fromReceipt(change)` turns a\n`platform_grant` change from a receipt into the shape the browser's payout\npreview gives — `base`, `total`, and the pass's or the Boost's part — to\nsend to the player whose screen draws it.\n\nA server has no read of the platform's currencies, so the answer carries\n`currencyId` and no `currencySlug`; the browser's `gem.earnings` fills the\nslug in.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "GemMatchServer.analytics",
           "name": "analytics",
@@ -31018,7 +32550,7 @@
           "group": "analytics",
           "signature": "experiment(key: string, count: number): Promise<number>",
           "documented": true,
-          "summary": "Which arm of one of your experiments this player gets — the same answer on\nevery call, every refresh and every device. Use it wherever you would have\npicked an arm with `Math.random()`, which deals a player a new arm on each\nvisit and makes the test unreadable.\n\nPass a COUNT and get an index, `0` to `count - 1`; pass a LIST of strings\nand get one of them. A string listed twice is twice as likely.\n\n```js\nconst tutorial = await gem.analytics.experiment('tutorial_length', ['short', 'long']);\nconst layout = await gem.analytics.experiment('shop_layout', 3); // 0, 1 or 2\n```\n\nThe selection is a hash of the key and the signed-in player's id — FNV-1a\n32-bit over `\"<key>:<playerId>\"`, then MurmurHash3's 32-bit finalizer, mod\nthe arm count; see\n`experimentSelection`, which computes the same answer for an id you\nhold. Hashing the key in is what keeps your experiments independent: the\nplayers in one experiment's first arm are not the same players in every\nother experiment's first arm.\n\n⚠️ **Keep the key and the arms fixed for the life of the experiment.** A new\ncount or list re-deals every player. To start over on purpose, use a new\nkey.\n\n⚠️ **NOTHING IS RECORDED FOR YOU.** The selection is not sent anywhere, and\nthe SDK does not add it to your events. To analyse an experiment, declare a\ndimension for it on the events you want to break down, with the arms as its\nvalues, named after the experiment, and pass the selection there yourself:\n`gem.analytics.track('tutorial_finished', { tutorial_length: tutorial })`.\nNever the platform's `variant` field, which belongs to store-page\nexperiments.\n\nWAITS FOR THE PLAYER. The id arrives with the first play token, so a call\nduring boot waits for it, and rejects as `Gem.awaitIdentity` does\nwhen none arrives — outside the Arcade, the Gem Editor or the dev host.\nThere is no random fallback: catch the rejection and play your control arm.\nA guest is selected by their guest id, which is stable for as long as their\nguest account lasts; once they sign in to an account they are that\naccount's player, and its selection applies.\n\nIn a serverless function it selects for the player who invoked it, with\nno wait, and rejects when a game server invoked it.\n\nWorks with analytics turned off: it reads no setting and sends nothing.",
+          "summary": "Which arm of one of your experiments this player gets — the same answer on\nevery call, every refresh and every device. Use it wherever you would have\npicked an arm with `Math.random()`, which deals a player a new arm on each\nvisit and makes the test unreadable.\n\nPass a COUNT and get an index, `0` to `count - 1`; pass a LIST of strings\nand get one of them. A string listed twice is twice as likely.\n\n```js\nconst tutorial = await gem.analytics.experiment('tutorial_length', ['short', 'long']);\nconst layout = await gem.analytics.experiment('shop_layout', 3); // 0, 1 or 2\n```\n\nThe selection is a hash of the key and the signed-in player's id — FNV-1a\n32-bit over `\"<key>:<playerId>\"`, then MurmurHash3's 32-bit finalizer, mod\nthe arm count; see\n`experimentSelection`, which computes the same answer for an id you\nhold. Hashing the key in is what keeps your experiments independent: the\nplayers in one experiment's first arm are not the same players in every\nother experiment's first arm.\n\n⚠️ **Keep the key and the arms fixed for the life of the experiment.** A new\ncount or list re-deals every player. To start over on purpose, use a new\nkey.\n\n⚠️ **NOTHING IS RECORDED FOR YOU.** The selection is not sent anywhere, and\nthe SDK does not add it to your events. To analyse an experiment, declare a\ndimension for it on the events you want to break down, with the arms as its\nvalues, named after the experiment, and pass the selection there yourself:\n`gem.analytics.track('tutorial_finished', { tutorial_length: tutorial })`.\nNever the platform's `variant` field, which belongs to store-page\nexperiments. For the platform's results to show the test, also declare it\nunder `analytics_tests` in your game config (see docs/analytics.md).\n\nWAITS FOR THE PLAYER. The id arrives with the first play token, so a call\nduring boot waits for it, and rejects as `Gem.awaitIdentity` does\nwhen none arrives — outside the Arcade, the Gem Editor or the dev host.\nThere is no random fallback: catch the rejection and play your control arm.\nA guest is selected by their guest id, which is stable for as long as their\nguest account lasts; once they sign in to an account they are that\naccount's player, and its selection applies.\n\nIn a serverless function it selects for the player who invoked it, with\nno wait, and rejects when a game server invoked it.\n\nWorks with analytics turned off: it reads no setting and sends nothing.",
           "deprecated": null,
           "params": [
             {
@@ -32291,6 +33823,173 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "PlatformGrantSource",
+          "name": "PlatformGrantSource",
+          "anchor": "platformgrantsource",
+          "group": "player",
+          "signature": "type PlatformGrantSource = { source: \"pass\"; pass: string; amount: number } | { source: \"boost\"; amount: number }",
+          "documented": true,
+          "summary": "Where the part of a payout above its base comes from.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "PlatformGrantPreview",
+          "name": "PlatformGrantPreview",
+          "anchor": "platformgrantpreview",
+          "group": "player",
+          "signature": "interface PlatformGrantPreview",
+          "documented": true,
+          "summary": "One platform payout — Coins, today — as the preview expects it or a receipt\nreports it, in one shape, so \"you will earn\" and \"you earned\" render with one\ncomponent.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "PlatformGrantPreview.currencySlug",
+          "name": "currencySlug",
+          "anchor": "platformgrantpreview-currencyslug",
+          "group": "player",
+          "signature": "readonly currencySlug?: string",
+          "documented": true,
+          "summary": "The currency's slug, e.g. `ARCADE_TICKETS`. Absent when unknown.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "PlatformGrantPreview.currencyId",
+          "name": "currencyId",
+          "anchor": "platformgrantpreview-currencyid",
+          "group": "player",
+          "signature": "readonly currencyId?: string",
+          "documented": true,
+          "summary": "The currency's id, when it is known.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "PlatformGrantPreview.base",
+          "name": "base",
+          "anchor": "platformgrantpreview-base",
+          "group": "player",
+          "signature": "readonly base: number",
+          "documented": true,
+          "summary": "What a player with no pass and no Boost gets.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "PlatformGrantPreview.total",
+          "name": "total",
+          "anchor": "platformgrantpreview-total",
+          "group": "player",
+          "signature": "readonly total: number",
+          "documented": true,
+          "summary": "What this player gets: `base` plus `breakdown`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "PlatformGrantPreview.breakdown",
+          "name": "breakdown",
+          "anchor": "platformgrantpreview-breakdown",
+          "group": "player",
+          "signature": "readonly breakdown: readonly PlatformGrantSource[]",
+          "documented": true,
+          "summary": "The part above `base`, and what it is from. Empty when `total` is `base`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "PlatformGrantPreview.ifComplete",
+          "name": "ifComplete",
+          "anchor": "platformgrantpreview-ifcomplete",
+          "group": "player",
+          "signature": "readonly ifComplete?: true",
+          "documented": true,
+          "summary": "`true` for an `on_complete` payout in a preview: it pays only if this\nclaim completes the progression. Absent otherwise, and on a receipt.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "EarningsApi",
+          "name": "EarningsApi",
+          "anchor": "earningsapi",
+          "group": "player",
+          "signature": "interface EarningsApi",
+          "documented": true,
+          "summary": "`gem.earnings`: what a payout was, in the shape `gem.gameConfig.preview`\nsays it would be.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "EarningsApi.fromReceipt",
+          "name": "fromReceipt",
+          "anchor": "earningsapi-fromreceipt",
+          "group": "player",
+          "signature": "fromReceipt(change: unknown): Promise<PlatformGrantPreview | null>",
+          "documented": true,
+          "summary": "Turn one `platform_grant` change from an order's receipt into a\n[PlatformGrantPreview](api-reference-function.md#platformgrantpreview): `base` is what a player with no pass and no\nBoost would have got under the same limits, `total` what this player got,\nand `breakdown` the pass's or the Boost's part, even when a limit trimmed\nthe payout. Draw \"you earned\" with the component that drew \"you will\nearn\". Resolves `null` for any other kind of change.\n\n**This and `preview` are the only way to show a platform payout.** Never\nmultiply by `gem.player.boost`, and never copy a config amount into your\ngame.",
+          "deprecated": null,
+          "params": [
+            {
+              "name": "change",
+              "type": "unknown",
+              "optional": false,
+              "summary": null
+            }
+          ],
+          "returns": "Always resolves; never rejects.",
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "CurrencyBalance",
           "name": "CurrencyBalance",
@@ -34331,70 +36030,6 @@
           "defaultValue": null,
           "guides": []
         },
-        {
-          "id": "GamePass",
-          "name": "GamePass",
-          "anchor": "gamepass",
-          "group": "player",
-          "signature": "interface GamePass",
-          "documented": true,
-          "summary": "One pass games may see, and whether this player holds it. Listed whether they\nhold it or not, and this is everything a game learns about it.",
-          "deprecated": null,
-          "params": [],
-          "returns": null,
-          "throws": null,
-          "example": null,
-          "defaultValue": null,
-          "guides": []
-        },
-        {
-          "id": "GamePass.pass",
-          "name": "pass",
-          "anchor": "gamepass-pass",
-          "group": "player",
-          "signature": "readonly pass: string",
-          "documented": true,
-          "summary": "The pass's offering slug, such as `vip`. Stable and not localized: key on this.",
-          "deprecated": null,
-          "params": [],
-          "returns": null,
-          "throws": null,
-          "example": null,
-          "defaultValue": null,
-          "guides": []
-        },
-        {
-          "id": "GamePass.held",
-          "name": "held",
-          "anchor": "gamepass-held",
-          "group": "player",
-          "signature": "readonly held: boolean",
-          "documented": true,
-          "summary": "Whether the player holds it right now.",
-          "deprecated": null,
-          "params": [],
-          "returns": null,
-          "throws": null,
-          "example": null,
-          "defaultValue": null,
-          "guides": []
-        },
-        {
-          "id": "GamePass.endsAt",
-          "name": "endsAt",
-          "anchor": "gamepass-endsat",
-          "group": "player",
-          "signature": "readonly endsAt: string | null",
-          "documented": true,
-          "summary": "When the player stops holding it, RFC 3339 in UTC, grace and any queued\nperiod included. `null` when it is not held, and when it is held with no\nend, so read [GamePass.held](api-reference-function.md#gamepass-held) first: `null` alone never means ended.",
-          "deprecated": null,
-          "params": [],
-          "returns": null,
-          "throws": null,
-          "example": null,
-          "defaultValue": null,
-          "guides": []
-        },
         {
           "id": "PassesEvent",
           "name": "PassesEvent",
@@ -38559,6 +40194,86 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "GamePass",
+          "name": "GamePass",
+          "anchor": "gamepass",
+          "group": "player",
+          "signature": "interface GamePass",
+          "documented": true,
+          "summary": "One pass games may see, and whether this player holds it. Listed whether they\nhold it or not, and this is everything a game learns about it.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GamePass.pass",
+          "name": "pass",
+          "anchor": "gamepass-pass",
+          "group": "player",
+          "signature": "readonly pass: string",
+          "documented": true,
+          "summary": "The pass's offering slug, such as `vip`. Stable and not localized: key on this.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GamePass.held",
+          "name": "held",
+          "anchor": "gamepass-held",
+          "group": "player",
+          "signature": "readonly held: boolean",
+          "documented": true,
+          "summary": "Whether the player holds it right now.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GamePass.daysLeft",
+          "name": "daysLeft",
+          "anchor": "gamepass-daysleft",
+          "group": "player",
+          "signature": "readonly daysLeft: number",
+          "documented": true,
+          "summary": "Whole days the player keeps it, rounded up so a pass with any time left\nreads at least `1`, and **capped at 7**: `7` means \"7 or more\", and is\nalso what a pass held with no end reads. `0` when it is not held. Show\n`7` as \"7+ days left\", never as an exact end.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GamePass.endsAt",
+          "name": "endsAt",
+          "anchor": "gamepass-endsat",
+          "group": "player",
+          "signature": "readonly endsAt: string | null",
+          "documented": true,
+          "summary": "When the player stops holding it, RFC 3339 in UTC, grace and any queued\nperiod included. `null` when it is not held, and when it is held with no\nend, so read [GamePass.held](api-reference-function.md#gamepass-held) first: `null` alone never means ended.",
+          "deprecated": "Use [GamePass.daysLeft](api-reference-function.md#gamepass-daysleft). An exact instant is a value two\ngames could match to link one player's identities, so the platform will\nstop sending it; it reads `null` then. See\n[the deprecation policy](../deprecation-policy.md).",
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "PlatformCurrencyAccess",
           "name": "PlatformCurrencyAccess",
@@ -40596,6 +42311,22 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "GemFunction.earnings",
+          "name": "earnings",
+          "anchor": "gemfunction-earnings",
+          "group": "start",
+          "signature": "readonly earnings: EarningsApi",
+          "documented": true,
+          "summary": "What a platform payout was: `earnings.fromReceipt(change)` turns a\n`platform_grant` change from a receipt into the shape the browser's payout\npreview gives — `base`, `total`, and the pass's or the Boost's part — to\nreturn to the game that draws it.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "GemFunction.profiles",
           "name": "profiles",