@indiegems/gem-web-sdk 8.0.0 → 8.1.0

package/docs/api/reference.json

@@ -2,7 +2,7 @@
   "schema_version": 1,
   "source": {
     "repo": "IndieGems/gem-web-sdk",
-    "version": "8.0.0"
+    "version": "8.1.0"
   },
   "entries": [
     {
@@ -375,6 +375,29 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "GameConfig.rewarded_placements",
+          "name": "rewarded_placements",
+          "anchor": "gameconfig-rewarded_placements",
+          "group": "config",
+          "url": "https://gemarcade.com/developer/api/game#gameconfig-rewarded_placements",
+          "signature": "rewarded_placements?: SnapshotRewardedPlacement[]",
+          "documented": true,
+          "summary": "Your rewarded placements — what pressing a rewarded button grants. An\narray, one row per placement, each naming itself in `placement`, with its\n`grants`, the caps the platform enforces on it (`max_per_day`,\n`cooldown_seconds`, `max_held`) and what happens where no ad serves\n(`without_ads`).\n\nRead it to LABEL your button — \"+1 Revive\" — never to decide a reward. A\ngrant is an `item_grant`, with a `quantity` of the item its\n`item_definition_id` names, or a `currency_grant`, with an `amount` of the\ncurrency its `currency_id` names; the word on the button is that\ndefinition's `display_name`, from [GameConfig.item](https://gemarcade.com/developer/api/game#gameconfig-item) or\n[GameConfig.currency](https://gemarcade.com/developer/api/game#gameconfig-currency):\n\n```js\nconst row = config?.rewarded_placements?.find((p) => p.placement === 'classic_revive');\nconst grant = row?.grants[0];\nconst label =\n  grant?.type === 'item_grant'\n    ? `+${grant.quantity} ${config.item(grant.item_definition_id)?.display_name ?? ''}`\n    : grant?.type === 'currency_grant'\n      ? `+${grant.amount} ${config.currency(grant.currency_id)?.display_name ?? ''}`\n      : undefined;\n```\n\nWhether an ask grants anything is the platform's decision, made against\nthis config server-side; the grant lands on your game's inventory, and\nre-reading `gem.me.inventory` is the only way to learn that it did. Whether\nthe button could pay right now is [AdsApi.rewardedStatus](https://gemarcade.com/developer/api/game#adsapi-rewardedstatus).\n\nAbsent when your game declares none.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": [
+            {
+              "slug": "cross-promotion",
+              "anchor": null,
+              "url": "https://gemarcade.com/developer/docs/cross-promotion"
+            }
+          ]
+        },
         {
           "id": "GameConfig.version",
           "name": "version",
@@ -4023,7 +4046,7 @@
           "url": "https://gemarcade.com/developer/api/game#adoutcomekind",
           "signature": "type AdOutcomeKind = \"shown\" | \"no_ad\" | \"unavailable\"",
           "documented": true,
-          "summary": "The complete vocabulary of answers. Three values, and there will not be a\nfourth.\n\n- `shown` — a panel was painted and has now closed. Resume. **It grants\n  nothing.**\n- `no_ad` — nothing was painted. Carry on exactly as if you had not asked.\n  This is the common answer.\n- `unavailable` — the arcade could not render just now. Not a softer no; read\n  it exactly as you read `no_ad`.\n\nNo reason is given for a `no_ad`, and one will never be added: a reason would\ntell your game something about the player — an age, a consent state, a\nsubscription — that game code is deliberately not told.",
+          "summary": "The complete vocabulary of answers. Three values, and there will not be a\nfourth.\n\n- `shown` — a panel was painted and has now closed. Resume. **It grants\n  nothing.**\n- `no_ad` — nothing was painted. Carry on exactly as if you had not asked.\n  This is the common answer.\n- `unavailable` — the arcade could not render just now. Not a softer no; read\n  it exactly as you read `no_ad`.\n\nNo reason is given for a `no_ad`, and one will never be added: a reason would\ntell your game something about the player — an age, a consent state, a\nsubscription — that game code is deliberately not told.\n\nThe one thing you can learn is about **your own economy**, and not from this\nanswer: [AdsApi.rewardedStatus](https://gemarcade.com/developer/api/game#adsapi-rewardedstatus) reports your own declared rewarded caps\nas the platform holds them (a platform-wide per-placement maximum, where one\nis set, can lower a cap). It never reports anything about the player.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -4113,6 +4136,155 @@
             }
           ]
         },
+        {
+          "id": "AdsApi.rewardedStatus",
+          "name": "rewardedStatus",
+          "anchor": "adsapi-rewardedstatus",
+          "group": "ads",
+          "url": "https://gemarcade.com/developer/api/game#adsapi-rewardedstatus",
+          "signature": "rewardedStatus(placement: string): Promise<RewardedStatus>",
+          "documented": true,
+          "summary": "Whether a rewarded placement could pay right now, so you can decide whether\nto draw its button. **It never says whether an ad will play.**\n\nThe answer comes from your own `rewarded_placements` config — its daily\ncap, cooldown and `max_held` — applied to this player's use of it, as the\nplatform holds them. Nothing in it describes the player. `grantable: true`\nmeans the platform would grant if an ad is watched or, where no ad serves,\nunder the placement's `without_ads: grant`; a player can still press the\nbutton and get `no_ad`, for reasons your game is not told.\n\nNOTHING REJECTS, like everything else on `gem.ads`. Without a play token,\nwhen the read fails or takes longer than ten seconds, or for a `placement`\noutside the grammar [AdRequest.placement](https://gemarcade.com/developer/api/game#adrequest-placement) documents, it resolves not\ndeclared and not grantable, with no `resetsAt`, and the reason goes to your\n`onError` handler.\n\nIt is a read of the platform, so call it when you draw the button — on a\nresults or death screen — not every frame. Calls for one placement that\noverlap share one request. Draw the rest of the screen first rather than\nholding it on this answer.\n\n⚠️ It grants nothing and reserves nothing. The reward is granted by the\nplatform when the player asks with `requestAd`; re-read `gem.me.inventory`\nafter that ask settles, whatever it settled as.",
+          "deprecated": null,
+          "params": [
+            {
+              "name": "placement",
+              "type": "string",
+              "optional": false,
+              "summary": "A placement your `rewarded_placements` config declares."
+            }
+          ],
+          "returns": "The placement's state. Always resolves; never rejects.",
+          "throws": null,
+          "example": "```ts\nconst status = await gem.ads.rewardedStatus('classic_revive');\nreviveButton.disabled = !status.grantable;\nif (status.nextEligibleAt !== undefined) {\n  reviveButton.title = `Back at ${new Date(status.nextEligibleAt).toLocaleTimeString()}`;\n}\n```",
+          "defaultValue": null,
+          "guides": [
+            {
+              "slug": "cross-promotion",
+              "anchor": null,
+              "url": "https://gemarcade.com/developer/docs/cross-promotion"
+            }
+          ]
+        },
+        {
+          "id": "RewardedStatus",
+          "name": "RewardedStatus",
+          "anchor": "rewardedstatus",
+          "group": "ads",
+          "url": "https://gemarcade.com/developer/api/game#rewardedstatus",
+          "signature": "interface RewardedStatus",
+          "documented": true,
+          "summary": "What [AdsApi.rewardedStatus](https://gemarcade.com/developer/api/game#adsapi-rewardedstatus) answers: the state of one rewarded\nplacement for this player, from your own declared caps.\n\nEvery figure comes from **your** `rewarded_placements` config — `max_per_day`,\n`cooldown_seconds`, `max_held` — applied to this player's use of it, as the\nplatform holds them. The platform can hold a placement's daily cap below what\nyou declared, never above it. Nothing here describes the player.\n\n⚠️ **It never says whether an ad will play.** Whether one does depends on\nthings your game is deliberately not told. A player can see your button,\npress it, and get `no_ad`: read that `no_ad` like any other, and never guess\na reason.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "RewardedStatus.declared",
+          "name": "declared",
+          "anchor": "rewardedstatus-declared",
+          "group": "ads",
+          "url": "https://gemarcade.com/developer/api/game#rewardedstatus-declared",
+          "signature": "readonly declared: boolean",
+          "documented": true,
+          "summary": "Whether this channel's published config declares the placement.\n\n`false` for a placement your config does not name, a config that is not\npromoted to the channel being played, and every answer the platform did not\ngive (see [RewardedStatus.resetsAt](https://gemarcade.com/developer/api/game#rewardedstatus-resetsat)).",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "RewardedStatus.grantable",
+          "name": "grantable",
+          "anchor": "rewardedstatus-grantable",
+          "group": "ads",
+          "url": "https://gemarcade.com/developer/api/game#rewardedstatus-grantable",
+          "signature": "readonly grantable: boolean",
+          "documented": true,
+          "summary": "Whether pressing your button could pay right now: the platform would grant\nthe reward if an ad is watched or, where no ad serves, under the\nplacement's `without_ads: grant`.\n\n**Not a promise that an ad will play, and not a promise of a reward.** It\nis `false` whenever a cap is spent, a cooldown is running, the player holds\n`max_held`, rewarded is off on this channel, or the arcade running your\ngame does not take ad requests at all.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "RewardedStatus.remainingToday",
+          "name": "remainingToday",
+          "anchor": "rewardedstatus-remainingtoday",
+          "group": "ads",
+          "url": "https://gemarcade.com/developer/api/game#rewardedstatus-remainingtoday",
+          "signature": "readonly remainingToday?: number",
+          "documented": true,
+          "summary": "Grants left today under the placement's daily cap, a non-negative integer.\n\nABSENT — no key, never a sentinel — when the placement has no daily cap,\nand on any answer where `declared` is `false`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "RewardedStatus.nextEligibleAt",
+          "name": "nextEligibleAt",
+          "anchor": "rewardedstatus-nexteligibleat",
+          "group": "ads",
+          "url": "https://gemarcade.com/developer/api/game#rewardedstatus-nexteligibleat",
+          "signature": "readonly nextEligibleAt?: number",
+          "documented": true,
+          "summary": "When the placement's cooldown ends, in epoch milliseconds — render it with\n`new Date(nextEligibleAt)`.\n\nABSENT when no cooldown is running.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "RewardedStatus.heldLimitReached",
+          "name": "heldLimitReached",
+          "anchor": "rewardedstatus-heldlimitreached",
+          "group": "ads",
+          "url": "https://gemarcade.com/developer/api/game#rewardedstatus-heldlimitreached",
+          "signature": "readonly heldLimitReached: boolean",
+          "documented": true,
+          "summary": "Whether the player already holds the placement's `max_held` of the item it\ngrants. Spend one first.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "RewardedStatus.resetsAt",
+          "name": "resetsAt",
+          "anchor": "rewardedstatus-resetsat",
+          "group": "ads",
+          "url": "https://gemarcade.com/developer/api/game#rewardedstatus-resetsat",
+          "signature": "readonly resetsAt?: number",
+          "documented": true,
+          "summary": "When the daily count resets — the next 00:00 UTC — in epoch milliseconds.\nTake it from here rather than computing midnight in game code.\n\nABSENT when the platform gave no answer: no play token yet, a read that\nfailed or took longer than ten seconds, or a platform that does not serve\nthis read. Then the rest of the status reads not declared and not\ngrantable, and the reason went to your `onError` handler.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "AnalyticsValue",
           "name": "AnalyticsValue",
@@ -6104,6 +6276,30 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "GemFrame.showPortraitBorders",
+          "name": "showPortraitBorders",
+          "anchor": "gemframe-showportraitborders",
+          "group": "frame",
+          "url": "https://gemarcade.com/developer/api/game#gemframe-showportraitborders",
+          "signature": "showPortraitBorders(name: string | null): boolean",
+          "documented": true,
+          "summary": "Tell the arcade which of your store page's portrait borders to paint beside\nyour game, or `null` for none.\n\nPrefer `gem.showPortraitBorders`, which holds your choice until the bridge\nis up and paces a burst of changes for you. This one sends every call it\naccepts, only while connected, and only to an arcade that paints borders.",
+          "deprecated": null,
+          "params": [
+            {
+              "name": "name",
+              "type": "string | null",
+              "optional": false,
+              "summary": null
+            }
+          ],
+          "returns": "whether the message left the frame — `false` for a string that is\n  not a border name (with a console warning), before the bridge is up, for\n  an arcade that paints no borders, and past this frame's own limit.",
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "GemFrame.setWalletVisible",
           "name": "setWalletVisible",
@@ -6387,7 +6583,7 @@
           "url": "https://gemarcade.com/developer/api/game#friend-badges",
           "signature": "readonly badges: readonly PlayerBadge[]",
           "documented": true,
-          "summary": "The player's equipped badges, in display order. Always a list, and empty\nuntil platform achievements equip any.",
+          "summary": "The player's equipped badges, at most two, in the order the player\narranged them. Always a list — empty when they wear none, or when their\nidentity is withheld — so draw what is there and key on `itemId`.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -8266,7 +8462,7 @@
           "url": "https://gemarcade.com/developer/api/game#gemplayer-badges",
           "signature": "readonly badges: readonly PlayerBadge[]",
           "documented": true,
-          "summary": "The player's equipped badges, in display order. Always a list, and empty\nuntil platform achievements equip any.",
+          "summary": "The player's equipped badges, at most two, in the order the player\narranged them. Always a list — empty when they wear none, or when their\nidentity is withheld — so draw what is there and key on `itemId`.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -9189,7 +9385,7 @@
           "url": "https://gemarcade.com/developer/api/game#gem-ads",
           "signature": "readonly ads: AdsApi",
           "documented": true,
-          "summary": "One full-screen cross-promotion at a natural break in play, rendered by\nthe arcade over your paused game.\n\nAsk at a break the player already expects — a level ending, a round\nfinishing — never mid-input. **The answer is usually no, and that is\nordinary rather than a failure:** carry straight on, and draw no\nplaceholder while you wait.\n\nNothing here rejects. The arcade pauses your game while a panel is up and\nresumes it when the promise settles, so you do not pause anything yourself.\n\n⚠️ `shown` **grants nothing.** It is not a receipt and not an entitlement,\nand a reward must never be handed out on the strength of it.\n\nYou are told no reason for a no, and there is nothing to infer from one.",
+          "summary": "One full-screen cross-promotion at a natural break in play, rendered by\nthe arcade over your paused game.\n\nAsk at a break the player already expects — a level ending, a round\nfinishing — never mid-input. **The answer is usually no, and that is\nordinary rather than a failure:** carry straight on, and draw no\nplaceholder while you wait.\n\nNothing here rejects. The arcade pauses your game while a panel is up and\nresumes it when the promise settles, so you do not pause anything yourself.\n\n⚠️ `shown` **grants nothing.** It is not a receipt and not an entitlement,\nand a reward must never be handed out on the strength of it.\n\nYou are told no reason for a no, and there is nothing to infer from one\nabout the player. What you can read is your own economy:\n`rewardedStatus(placement)` says whether a rewarded placement could pay\nright now under your own declared caps — never whether an ad will play.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -9544,6 +9740,30 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "Gem.showPortraitBorders",
+          "name": "showPortraitBorders",
+          "anchor": "gem-showportraitborders",
+          "group": "start",
+          "url": "https://gemarcade.com/developer/api/game#gem-showportraitborders",
+          "signature": "showPortraitBorders(name: string | null): void",
+          "documented": true,
+          "summary": "Choose which of your store page's **portrait borders** the arcade paints on\neither side of your game, or `null` for none.\n\nOn a desktop browser, the arcade's desktop app or a television, the arcade\nshows a portrait-only game as a centred portrait column. With borders\ndeclared on your store page (`media.portrait_borders`), it paints one of\nthose images beside the column instead of its own bars. Call this at\nstart-up and on every theme change, with the border that goes with what is\non screen:\n\n```js\nconst BORDERS = new Set(['meadow', 'alpine']); // the names your store page declares\n\nfunction applyTheme(id) {\n  document.body.dataset.theme = id;\n  gem.showPortraitBorders(BORDERS.has(id) ? id : null); // null: a theme with no art\n}\n```\n\nUntil your first call the arcade shows the page's first border. Whether\nyour game is letterboxed at all is decided by your store page's\n`orientations`, never by this call, so call it unconditionally: before the\nconnection exists your choice is held and sent when it connects, a burst of\nchanges (a picker previewing on hover) reaches the arcade as its final\nvalue, and an arcade that paints no borders is simply not told. The arcade\nowns the change itself — when and how the image swaps — and sends no\nacknowledgement.\n\nA name is 1 to 40 characters of `a-z`, `0-9`, `_` and `-`, starting with a\nletter or digit — the store page's own rule. Anything else is refused with\na console warning and never sent; a valid name your page does not declare\nis ignored by the arcade, which keeps the image it is showing.",
+          "deprecated": null,
+          "params": [
+            {
+              "name": "name",
+              "type": "string | null",
+              "optional": false,
+              "summary": null
+            }
+          ],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "Gem.cueReward",
           "name": "cueReward",
@@ -10789,7 +11009,7 @@
           "url": "https://gemarcade.com/developer/api/game#playerbadge",
           "signature": "interface PlayerBadge",
           "documented": true,
-          "summary": "One badge a player has equipped — an icon the platform shows beside their\nname.\n\nAlways an empty list today; platform achievements fill it with at most two.",
+          "summary": "One badge a player has equipped — an icon the platform shows beside their\nname.\n\nA player wears at most two, in the order they arranged them. Each is an icon\nthey own — an achievement in any game may have awarded it.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -10959,7 +11179,7 @@
           "url": "https://gemarcade.com/developer/api/game#playeridentity-badges",
           "signature": "readonly badges: readonly PlayerBadge[]",
           "documented": true,
-          "summary": "The player's equipped badges, in display order. Always a list, and empty\nuntil platform achievements equip any.",
+          "summary": "The player's equipped badges, at most two, in the order the player\narranged them. Always a list — empty when they wear none, or when their\nidentity is withheld — so draw what is there and key on `itemId`.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -13886,7 +14106,7 @@
           "url": "https://gemarcade.com/developer/api/game#leaderboardentry-badges",
           "signature": "readonly badges: readonly PlayerBadge[]",
           "documented": true,
-          "summary": "The player's equipped badges, in display order. Always a list, and empty\nuntil platform achievements equip any.",
+          "summary": "The player's equipped badges, at most two, in the order the player\narranged them. Always a list — empty when they wear none, or when their\nidentity is withheld — so draw what is there and key on `itemId`.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -15759,7 +15979,7 @@
           "url": "https://gemarcade.com/developer/api/game#playerprofile-badges",
           "signature": "readonly badges: readonly PlayerBadge[]",
           "documented": true,
-          "summary": "The player's equipped badges, in display order. Always a list, and empty\nuntil platform achievements equip any.",
+          "summary": "The player's equipped badges, at most two, in the order the player\narranged them. Always a list — empty when they wear none, or when their\nidentity is withheld — so draw what is there and key on `itemId`.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -18454,7 +18674,7 @@
           "url": "https://gemarcade.com/developer/api/game#roommember-badges",
           "signature": "readonly badges: readonly PlayerBadge[]",
           "documented": true,
-          "summary": "The player's equipped badges, in display order. Always a list, and empty\nuntil platform achievements equip any.",
+          "summary": "The player's equipped badges, at most two, in the order the player\narranged them. Always a list — empty when they wear none, or when their\nidentity is withheld — so draw what is there and key on `itemId`.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -19605,7 +19825,7 @@
           "url": "https://gemarcade.com/developer/api/game#showcasefriendentry-badges",
           "signature": "readonly badges: readonly PlayerBadge[]",
           "documented": true,
-          "summary": "The player's equipped badges, in display order. Always a list, and empty\nuntil platform achievements equip any.",
+          "summary": "The player's equipped badges, at most two, in the order the player\narranged them. Always a list — empty when they wear none, or when their\nidentity is withheld — so draw what is there and key on `itemId`.",
           "deprecated": null,
           "params": [],
           "returns": null,

package/docs/changelog.md

@@ -16,6 +16,21 @@ Its entries are grouped under up to five headings:
 - **Rebuild**: a type changed. Recompile against the new version; code that compiles today keeps compiling unless the entry says otherwise.
 - **New capability**: something a game can now do. Nothing changes unless you use it.
 
+## 8.1.0
+
+Upgrading from 8.0.0. Impact: required.
+
+### Rebuild
+
+- The list of messages a frame sends to its parent, the FrameMessage type and the GemCapability type each gained a portrait borders member. Recompiling is enough for most games. If your code handles every FrameMessage or GemCapability member exhaustively, add a case for the new one so it keeps compiling.
+
+### New capability
+
+- A game can now ask whether a rewarded placement could pay right now, before it draws its reward button, by calling AdsApi.rewardedStatus with the placement. The answer is a RewardedStatus saying whether the placement is declared, whether it is grantable now, how many grants remain today, when it is next eligible, whether the held limit is reached, and when the allowance resets. Times are in epoch milliseconds. The call never rejects. A failed read, a missing play token or a bad placement resolves as not declared and not grantable, and the read gives up after ten seconds. A placement only counts as grantable when the Arcade you run in supports ads. Failures are reported once per kind through your error handler.
+- A game can now choose which border image from its store page the Arcade paints beside it in portrait by calling Gem.showPortraitBorders with the image's name. The name is a plain string of at most 40 characters, and one that fails the store page's naming rule is refused whole with a console warning. The choice is held until the bridge connects, sent at most once a second with the latest choice winning, and not resent if it matches what was last posted. If the Arcade does not advertise the portraitBorders capability, nothing is sent and nothing is raised.
+- If you embed a game in your own frame, GemFrame.showPortraitBorders lets you send the same border choice, or clear it. It sends only while connected and only to a parent that advertised the portraitBorders capability, and it applies the same name rule as the game side.
+- If you host games, you can now pass onPortraitBorders in your host options to receive the border name a game chose. The new GemPortraitBorders message carries it, and validateGemPortraitBorders checks a message you receive. The host re-checks the name on receipt and drops one that no store page could declare before your callback sees it.
+
 ## 8.0.0
 
 *Written from the API facts alone; no summary was generated for this release.*

package/docs/cross-promotion.md

@@ -13,8 +13,8 @@ const { outcome } = await gem.ads.requestAd({
 startNextLevel();
 ```
 
-That is the whole surface. The rest of this page is the four things a game gets wrong when nobody
-tells it.
+That is the whole surface, apart from one read that tells a rewarded button whether it could pay
+(§3). The rest of this page is the four things a game gets wrong when nobody tells it.
 
 ## 1. The answer is usually no, and no is ordinary
 
@@ -80,6 +80,36 @@ your player is already sitting in, and it is the whole of what changes on the da
 rebuild. [`inventory-and-catalogs.md` §6](inventory-and-catalogs.md#6-when-to-re-read) is the
 general form of this.
 
+**Whether a rewarded button could pay right now.** A rewarded placement is a button the player
+presses, so you need to know whether to draw it. `gem.ads.rewardedStatus(placement)` reads one
+placement's state from **your own** `rewarded_placements` config — its daily cap, cooldown and
+`max_held` — applied to this player's use of it:
+
+```js
+const status = await gem.ads.rewardedStatus('run-banked');
+bankButton.disabled = !status.grantable;
+```
+
+| field | what it says |
+|---|---|
+| `declared` | the config promoted to the channel being played names this placement |
+| `grantable` | pressing the button could pay right now — **not** that an ad will play |
+| `remainingToday` | grants left today under the daily cap; absent when the placement has none |
+| `nextEligibleAt` | when a running cooldown ends, in epoch milliseconds; absent when none runs |
+| `heldLimitReached` | the player already holds the placement's `max_held` — spend one first |
+| `resetsAt` | when today's count resets, the next 00:00 UTC, in epoch milliseconds |
+
+**`grantable` is not a promise.** A player can press a `grantable` button and get `no_ad`, for
+reasons your game is not told. Read that `no_ad` like any other (§1) — never guess a reason — and
+re-read your inventory whatever the ask settled as. The status grants nothing and reserves
+nothing.
+
+It never rejects, like the rest of `gem.ads`. Without a play token, when the read fails or takes
+longer than ten seconds, or for a placement outside the grammar below, it answers not declared and
+not grantable with no `resetsAt`, and the reason goes to your `onError` handler. It is a read of
+the platform, so call it when you draw the button — on a results or death screen — and not every
+frame, and draw the rest of the screen first rather than holding it on the answer.
+
 ## 4. The Arcade pauses your game for you
 
 While a panel is up, your game is paused the same way it is paused when a player switches tabs —
@@ -130,6 +160,12 @@ schedule that does not depend on which branch produced it, so there is nothing i
 read either. (`shown` is not held back — how long that one takes is how long your player spent
 looking at a panel.)
 
+The one thing you can read is your own economy, and never from the answer:
+`gem.ads.rewardedStatus` reports **your own declared** rewarded caps as the platform holds them —
+the platform can hold a placement's daily cap below what you declared, never above — so you can
+tell when a rewarded `no_ad` was your own cap. It never reports anything about the player, the
+platform's spacing between offers, or any limit that spans games.
+
 ## If you do nothing
 
 Nothing happens. A game that never calls `gem.ads.requestAd` is never interrupted, and the call is

package/docs/getting-started.md

@@ -50,7 +50,7 @@ either way.
 ```jsonc
 // package.json
 "dependencies": {
-  "@indiegems/gem-web-sdk": "8.0.0"
+  "@indiegems/gem-web-sdk": "8.1.0"
 }
 ```
 
@@ -355,7 +355,8 @@ What reaches the frame:
   only keys the arcade keeps for itself; it never interprets yours:
   - Store and play-page switches: `play`, `channel`, `purchase`, and `build`, which pins one
     of your own builds when you play it from your Builds page.
-  - Platform switches: `devtools`, `devLocale`.
+  - Platform switches: `devtools`, `devLocale`, and `gem_test_ads`, the mode of the arcade's
+    rewarded TEST ads.
   - The arcade's own sign-in return marker: `social`.
   - Attribution and campaign keys, which the arcade keeps out of every game: `_s`, `utm_*`
     (every key with that prefix, matched case-sensitively, so UTM_X and utmost are yours),

package/docs/manifest.json

@@ -8,8 +8,8 @@
   "documents": [
     {
       "file": "achievements.md",
-      "sha256": "e67bc5d0e6abd9ff842be46fa82bf5117fce74b2eb9d28a3954919ddc8a11c73",
-      "updated": "2026-10-02T23:09:37Z"
+      "sha256": "adc8bfaa769fbb283a53de1190ed85cdf4c1c9753e8cf78335b4595e98f8fad4",
+      "updated": "2026-10-06T22:14:30Z"
     },
     {
       "file": "analytics.md",
@@ -33,13 +33,13 @@
     },
     {
       "file": "changelog.md",
-      "sha256": "37bae4170e89587ee8c498891fa2dac008f09fb01fcfbcf87b1310340d2cfc62",
-      "updated": "2026-10-06T19:43:21Z"
+      "sha256": "f13808374edf0988e0aef58b857c82298702a67d450962522a532b4827b74c91",
+      "updated": "2026-10-07T16:20:42Z"
     },
     {
       "file": "cross-promotion.md",
-      "sha256": "3a8121a9c973e4a1bfed076a3226d139f8b4e38a173a06ea9f08000c72bca4b4",
-      "updated": "2026-09-29T17:32:40Z"
+      "sha256": "289cb4826a56b4e7423160e4187af65f4167c80218c2792ca0c01fbd977ecfec",
+      "updated": "2026-10-06T18:49:36Z"
     },
     {
       "file": "daily-challenges.md",
@@ -68,8 +68,8 @@
     },
     {
       "file": "getting-started.md",
-      "sha256": "77ce7b2223d18267ac3ca2f49e09481752539f2674910e2cb12832825c945000",
-      "updated": "2026-10-06T19:43:21Z"
+      "sha256": "222dcf81a2ed6d8fc8ffc37d5f7ef146dcf80c4b76f84fd9b8dd53ea1cbce23b",
+      "updated": "2026-10-07T16:20:42Z"
     },
     {
       "file": "inventory-and-catalogs.md",
@@ -118,8 +118,8 @@
     },
     {
       "file": "server-bundles.md",
-      "sha256": "49f51b37e969b6120d2df6cf6d2f33d2856c1602fd7504a7b308a9ea21c9b502",
-      "updated": "2026-10-06T19:43:21Z"
+      "sha256": "ffc7ec338f3436f73b16f8ba92a54de93e55bd5e9adbe562647e27b4867e4619",
+      "updated": "2026-10-07T16:20:42Z"
     },
     {
       "file": "serverless-functions-js.md",
@@ -143,8 +143,8 @@
     },
     {
       "file": "what-a-game-must-do.md",
-      "sha256": "436a8b61c46a3de6c7d5db65293bdcd17426412742dffd21f976bf87d1418d88",
-      "updated": "2026-10-06T17:36:25Z"
+      "sha256": "3d3ed15c93368a03b11c0e4e1924797e2638aff5be264a799a259ee065d2dbfc",
+      "updated": "2026-10-06T23:08:59Z"
     }
   ]
 }

package/docs/server-bundles.md

@@ -80,8 +80,8 @@ To check the download yourself: the package npm serves is, byte for byte, the fi
 also publishes on its download host, with the hash beside it:
 
 ```bash
-curl -fsSL -O https://downloads.gemarcade.com/sdk/v8.0.0/gem-web-sdk.tgz
-curl -fsSL https://downloads.gemarcade.com/sdk/v8.0.0/gem-web-sdk.tgz.sri
+curl -fsSL -O https://downloads.gemarcade.com/sdk/v8.1.0/gem-web-sdk.tgz
+curl -fsSL https://downloads.gemarcade.com/sdk/v8.1.0/gem-web-sdk.tgz.sri
 openssl dgst -sha384 -binary gem-web-sdk.tgz | openssl base64 -A
 ```