@indiegems/gem-web-sdk 23.3.0 → 24.0.0

package/docs/api/reference.json

@@ -2,7 +2,7 @@
   "schema_version": 2,
   "source": {
     "repo": "IndieGems/gem-web-sdk",
-    "version": "23.3.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"
@@ -5589,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,
@@ -5671,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,
@@ -5687,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,
@@ -5712,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",
@@ -5815,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,
@@ -5831,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,
@@ -5863,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.",
@@ -5902,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": [
             {
@@ -5918,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",
@@ -7858,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",
@@ -8496,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,
@@ -8512,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,
@@ -8528,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,
@@ -8544,13 +9122,29 @@
           "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,
+          "throws": null,
+          "example": null,
+          "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,
@@ -8559,6 +9153,93 @@
           "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",
@@ -12033,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",
@@ -13415,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",
@@ -16660,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",
@@ -18015,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",
@@ -18061,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",
@@ -27049,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",
@@ -27398,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",
@@ -27982,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",
@@ -28297,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",
@@ -28805,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,
@@ -28897,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",
@@ -29626,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",
@@ -29672,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",
@@ -30205,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,
@@ -30297,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",
@@ -32335,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",
@@ -34375,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",
@@ -38603,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",
@@ -40640,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",