@indiegems/gem-web-sdk 8.0.0 → 9.0.0

package/docs/api/reference.json

@@ -2,7 +2,7 @@
   "schema_version": 1,
   "source": {
     "repo": "IndieGems/gem-web-sdk",
-    "version": "8.0.0"
+    "version": "9.0.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",
@@ -3955,14 +3978,20 @@
           "url": "https://gemarcade.com/developer/api/game#adformat",
           "signature": "type AdFormat = \"interstitial\" | \"rewarded\"",
           "documented": true,
-          "summary": "Which kind of break this is.\n\n`interstitial` is a panel the player dismisses and nothing follows from.\n\n⚠️ `rewarded` is part of the vocabulary and is answered `no_ad` today. It is\nhere so a game's own analytics can distinguish the two kinds of break, and so\nthis request has the shape an ad request has everywhere. Even when it is\nserved, the outcome grants nothing — a reward is granted by the platform,\nagainst its own record, never by your game reading `shown`. It arrives on\nyour game's inventory for this player, written by the platform, so re-read\n`gem.me.inventory` after a `rewarded` ask settles rather than waiting for a\nsignal on this pair; there will not be one.",
+          "summary": "Which kind of break this is.\n\n`interstitial` is a panel the player dismisses and nothing follows from.\n\n`rewarded` is a button the player pressed for a reward — a revive, an extra\nattempt — that your game config declares for the placement in\n`rewarded_placements`. It is served where this arcade serves it, and answered\n`no_ad` where it does not. ⚠️ The outcome grants nothing: the platform grants\nthe reward, against its own record, never your game reading `shown`. It\narrives on your game's inventory for this player, written by the platform,\nso re-read `gem.me.inventory` after a `rewarded` ask settles rather than\nwaiting for a signal on this pair; there will not be one.",
           "deprecated": null,
           "params": [],
           "returns": null,
           "throws": null,
           "example": null,
           "defaultValue": null,
-          "guides": []
+          "guides": [
+            {
+              "slug": "rewarded-ads",
+              "anchor": null,
+              "url": "https://gemarcade.com/developer/docs/rewarded-ads"
+            }
+          ]
         },
         {
           "id": "AdRequest",
@@ -3989,7 +4018,7 @@
           "url": "https://gemarcade.com/developer/api/game#adrequest-placement",
           "signature": "placement: string",
           "documented": true,
-          "summary": "Your own name for the break — `level-complete`, `between-rounds`.\n\n**1 to 32 characters of `a-z`, `0-9`, `-` and `_`.** Lowercase, no spaces,\nno accents: `'Boss Fight'` is not a placement, `'boss-fight'` is. The\ngrammar is the platform's own, and it is narrow deliberately — this is the\nfield an ad unit is keyed by, so a name that does not fit it is a name that\nwould stop working later rather than now. A placement outside it is\nanswered `no_ad` and reported to your `onError` handler.\n\nThe platform matches it against nothing today and never shows it to a\nplayer. It is for your own telemetry, so two break points in your game can\nbe told apart.",
+          "summary": "Your own name for the break — `level-complete`, `between-rounds`.\n\n**1 to 32 characters of `a-z`, `0-9`, `-` and `_`.** Lowercase, no spaces,\nno accents: `'Boss Fight'` is not a placement, `'boss-fight'` is. The\ngrammar is the platform's own, and the SDK enforces it so a name that does\nnot fit is refused at your keyboard rather than in the field. A placement\noutside it is answered `no_ad` and reported to your `onError` handler.\n\nFor `rewarded`, it names the reward your game config declares in\n`rewarded_placements`: the platform matches it against that config, and a\nplacement the config does not declare is answered `no_ad`. For\n`interstitial`, the platform matches it against nothing; there it is for\nyour own telemetry, so two break points in your game can be told apart.\nEither way it is never shown to a player and **never sent to an ad\nnetwork**.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -4023,7 +4052,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. After a `rewarded` ask the reward may still\n  have landed, with no ad, so re-read your inventory either way.\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,
@@ -4091,7 +4120,7 @@
           "url": "https://gemarcade.com/developer/api/game#adsapi-requestad",
           "signature": "requestAd(req: AdRequest): Promise<AdOutcome>",
           "documented": true,
-          "summary": "Ask whether the arcade has anything to show at this break in play.\n\nNOTHING REJECTS, and the answer is usually `no_ad`. Every local refusal —\nan arcade that does not do this at all, a call while another is still in\nflight, a `placement` this module will not send — resolves `no_ad` rather\nthan throwing, so a game needs exactly one branch. Only \"no answer ever\narrived\" resolves `unavailable`.\n\nThe arcade pauses your game while a panel is up and resumes it when this\nsettles, so you do not need to pause anything yourself.\n\n⚠️ `shown` grants nothing. Never hand out a reward, an unlock or a currency\non the strength of it.",
+          "summary": "Ask whether the arcade has anything to show at this break in play.\n\nNOTHING REJECTS, and the answer is usually `no_ad`. Every local refusal —\nan arcade that does not do this at all, a call while another is still in\nflight, a `placement` this module will not send — resolves `no_ad` rather\nthan throwing, so a game needs exactly one branch. Only \"no answer ever\narrived\" resolves `unavailable`.\n\nThe arcade pauses your game while a panel is up and resumes it when this\nsettles, so you do not need to pause anything yourself.\n\n⚠️ `shown` grants nothing. Never hand out a reward, an unlock or a currency\non the strength of it. A `rewarded` placement's reward is granted by the\nplatform into your game's inventory; re-read `gem.me.inventory` once this\nsettles, whatever it settled as.",
           "deprecated": null,
           "params": [
             {
@@ -4105,6 +4134,30 @@
           "throws": null,
           "example": "```ts\nconst { outcome } = await gem.ads.requestAd({\n  placement: 'level-complete',\n  format: 'interstitial',\n});\n// `no_ad` is the ordinary answer. There is nothing to show and nothing\n// to draw; carry straight on to the next level.\nstartNextLevel();\n```",
           "defaultValue": null,
+          "guides": []
+        },
+        {
+          "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",
@@ -4113,6 +4166,125 @@
             }
           ]
         },
+        {
+          "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,
@@ -7338,9 +7534,9 @@
           "anchor": "functionfailure",
           "group": "functions",
           "url": "https://gemarcade.com/developer/api/game#functionfailure",
-          "signature": "type FunctionFailure = \"trap\" | \"memory_exceeded\" | \"cpu_budget_exceeded\" | \"host_call_limit\"",
+          "signature": "type FunctionFailure = \"trap\" | \"memory_exceeded\" | \"cpu_budget_exceeded\" | \"host_call_limit\" | \"output_too_large\" | \"argument_too_large\"",
           "documented": true,
-          "summary": "Why a call that reached your function did not finish — carried on\n[GemFunctionError.failure](https://gemarcade.com/developer/api/game#gemfunctionerror-failure).\n\n- `trap` — a panic, an `unreachable`, an out-of-bounds access or a stack\n  overflow. No stack trace comes back.\n- `memory_exceeded` — past the memory limit.\n- `cpu_budget_exceeded` — past the CPU budget.\n- `host_call_limit` — more platform API calls than one invocation may make.",
+          "summary": "Why a call that reached your function did not finish — carried on\n[GemFunctionError.failure](https://gemarcade.com/developer/api/game#gemfunctionerror-failure).\n\n- `trap` — a panic, an `unreachable`, an out-of-bounds access or a stack\n  overflow. No stack trace comes back.\n- `memory_exceeded` — past the memory limit.\n- `cpu_budget_exceeded` — past the CPU budget.\n- `host_call_limit` — more platform API calls than one invocation may make.\n- `output_too_large` — your function's result was over the 1 MiB output cap.\n- `argument_too_large` — a value your function handed to a platform call\n  (`log`, `call-api`, `download-link` or `upload-link`) was over the 16 MiB\n  per-call limit.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -7574,7 +7770,7 @@
           "url": "https://gemarcade.com/developer/api/game#arcade_embedders",
           "signature": "ARCADE_EMBEDDERS: readonly string[]",
           "documented": true,
-          "summary": "The origins the Gem Arcade embeds a game from, which every game accepts\nwithout naming them: the website, and the Gem Arcade app.\n\nYou do not pass these. They are always allowed, and\n[GemOptions.allowedEmbedders](https://gemarcade.com/developer/api/game#gemoptions-allowedembedders) adds to them rather than replacing them.",
+          "summary": "The origins the platform embeds a game from, which every game accepts\nwithout naming them: the Gem Arcade website, the Meme Games website, and\nthe Gem Arcade app.\n\nYou do not pass these. They are always allowed, and\n[GemOptions.allowedEmbedders](https://gemarcade.com/developer/api/game#gemoptions-allowedembedders) adds to them rather than replacing them.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -7608,7 +7804,7 @@
           "url": "https://gemarcade.com/developer/api/game#gemoptions-allowedembedders",
           "signature": "readonly allowedEmbedders?: readonly string[]",
           "documented": true,
-          "summary": "Extra origins allowed to embed your game, **added to** the ones the Gem\nArcade uses. Most games leave this out.\n\nThe website and the Gem Arcade app are always allowed — see\n[ARCADE_EMBEDDERS](https://gemarcade.com/developer/api/game#arcade_embedders) — so do not list them. Set this only when a site\nof your own embeds your game.\n\n```js\ncreateGem({ allowedEmbedders: ['https://my-own-site.example'] })\n```\n\nA page whose origin is not allowed gets no connection, and — deliberately —\nis told nothing about why. That means a typo here looks exactly like a\nhandshake that has not arrived: pass [GemOptions.onRefused](https://gemarcade.com/developer/api/game#gemoptions-onrefused) while you\nare integrating, because it is the only place the difference shows.\n\n⚠️ **Bake these in. Never build them from anything the page can\ninfluence** — not `location`, not a query parameter, not\n`document.referrer`. A value the embedder supplies is a check that can never\nfail. Do not add a `localhost:<port>` entry for your dev host either; the\nSDK admits one on your own machine by rule.",
+          "summary": "Extra origins allowed to embed your game, **added to** the ones the Gem\nArcade uses. Most games leave this out.\n\nThe platform's websites and the Gem Arcade app are always allowed — see\n[ARCADE_EMBEDDERS](https://gemarcade.com/developer/api/game#arcade_embedders) — so do not list them. Set this only when a site\nof your own embeds your game.\n\n```js\ncreateGem({ allowedEmbedders: ['https://my-own-site.example'] })\n```\n\nA page whose origin is not allowed gets no connection, and — deliberately —\nis told nothing about why. That means a typo here looks exactly like a\nhandshake that has not arrived: pass [GemOptions.onRefused](https://gemarcade.com/developer/api/game#gemoptions-onrefused) while you\nare integrating, because it is the only place the difference shows.\n\n⚠️ **Bake these in. Never build them from anything the page can\ninfluence** — not `location`, not a query parameter, not\n`document.referrer`. A value the embedder supplies is a check that can never\nfail. Do not add a `localhost:<port>` entry for your dev host either; the\nSDK admits one on your own machine by rule.",
           "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,
@@ -21731,9 +21951,9 @@
           "anchor": "functionfailure",
           "group": "functions",
           "url": "https://gemarcade.com/developer/api/server#functionfailure",
-          "signature": "type FunctionFailure = \"trap\" | \"memory_exceeded\" | \"cpu_budget_exceeded\" | \"host_call_limit\"",
+          "signature": "type FunctionFailure = \"trap\" | \"memory_exceeded\" | \"cpu_budget_exceeded\" | \"host_call_limit\" | \"output_too_large\" | \"argument_too_large\"",
           "documented": true,
-          "summary": "Why a call that reached your function did not finish — carried on\n[GemFunctionError.failure](https://gemarcade.com/developer/api/server#gemfunctionerror-failure).\n\n- `trap` — a panic, an `unreachable`, an out-of-bounds access or a stack\n  overflow. No stack trace comes back.\n- `memory_exceeded` — past the memory limit.\n- `cpu_budget_exceeded` — past the CPU budget.\n- `host_call_limit` — more platform API calls than one invocation may make.",
+          "summary": "Why a call that reached your function did not finish — carried on\n[GemFunctionError.failure](https://gemarcade.com/developer/api/server#gemfunctionerror-failure).\n\n- `trap` — a panic, an `unreachable`, an out-of-bounds access or a stack\n  overflow. No stack trace comes back.\n- `memory_exceeded` — past the memory limit.\n- `cpu_budget_exceeded` — past the CPU budget.\n- `host_call_limit` — more platform API calls than one invocation may make.\n- `output_too_large` — your function's result was over the 1 MiB output cap.\n- `argument_too_large` — a value your function handed to a platform call\n  (`log`, `call-api`, `download-link` or `upload-link`) was over the 16 MiB\n  per-call limit.",
           "deprecated": null,
           "params": [],
           "returns": null,

package/docs/changelog.md

@@ -16,6 +16,29 @@ 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.
 
+## 9.0.0
+
+Upgrading from 8.1.0. Impact: required.
+
+### Must change
+
+- FunctionFailure now has two more reasons, output_too_large and argument_too_large. A function that returns more than the output cap, or passes a platform call a value over the per-call size limit, used to fail as trap. It now fails with the matching new reason. Update any code that switches on FunctionFailure so it handles both new reasons. An exhaustive check over the old four reasons will stop compiling until you do. If your game treated trap as the sign of an oversized output or argument, handle the new reasons there too. Then rebuild your game against this release.
+
+## 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.*