@indiegems/gem-web-sdk 8.1.0 → 9.1.0

package/docs/api/reference.json

@@ -2,7 +2,7 @@
   "schema_version": 1,
   "source": {
     "repo": "IndieGems/gem-web-sdk",
-    "version": "8.1.0"
+    "version": "9.1.0"
   },
   "entries": [
     {
@@ -3978,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, such as a revive or\nan extra attempt, that your game config declares for the placement in\n`rewarded_placements`. The press is the player's opt-in, and the arcade\nstarts the ad straight away, so ask from the button's own handler (see\n[AdsApi.requestAd](https://gemarcade.com/developer/api/game#adsapi-requestad)). It is served where this arcade serves it, and\nanswered `no_ad` where it does not. ⚠️ The outcome grants nothing: the\nplatform grants the reward, against its own record, never your game reading\n`shown`. It arrives on your game's inventory for this player, written by the\nplatform, so re-read `gem.me.inventory` after a `rewarded` ask settles rather\nthan waiting 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",
@@ -4012,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,
@@ -4046,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.\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.",
+          "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,
@@ -4114,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.\n\n**A `rewarded` ask must come from the player's press.** The press is the\nplayer's opt-in, and the arcade starts the ad as soon as the ask arrives.\nCall this from your button's `click`, `pointerup`, `touchend` or `keydown`\nhandler, before anything that can outlast the press, such as a slow\n`await` or a timer. **Not from `pointerdown` or `touchstart`:** on a\ntouchscreen they run before the browser counts the tap, so the ask is\nrefused on a phone while the same code works at a desk with a mouse. A\ncontroller press counts when the ask follows it within a second, so ask\nfrom the frame of your input loop that saw the button go down. Where the\nbrowser reports user activation (`navigator.userActivation`), the frame\nholds none, and no controller was used in the last second, this answers\n`no_ad` without asking. It also calls your `onError` handler with\ncode `'internal'` and a message that begins\n`rewarded_requires_user_gesture`, and writes one `[gem]` line a session\nthrough your `log`. Where the browser has no such API, the ask goes ahead.\nAn `interstitial` needs no press.",
           "deprecated": null,
           "params": [
             {
@@ -4126,15 +4132,9 @@
           ],
           "returns": "The arcade's answer. Always resolves; never rejects.",
           "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```",
+          "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```\n\n```ts\n// A rewarded ask, from the button's own click: the ask comes first, and\n// the inventory read comes after it.\nwatchAdButton.addEventListener('click', async () => {\n  watchAdButton.disabled = true; // only between the press and the answer\n  await gem.ads.requestAd({ placement: 'dice_rolls', format: 'rewarded' });\n  gem.me.inventory.refresh();\n  try {\n    showDice(await gem.me.inventory.snapshot());\n  } finally {\n    watchAdButton.disabled = false;\n  }\n});\n```",
           "defaultValue": null,
-          "guides": [
-            {
-              "slug": "cross-promotion",
-              "anchor": null,
-              "url": "https://gemarcade.com/developer/docs/cross-promotion"
-            }
-          ]
+          "guides": []
         },
         {
           "id": "AdsApi.rewardedStatus",
@@ -7534,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,
@@ -7770,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,
@@ -7804,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,
@@ -21951,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,20 @@ 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.1.0
+
+Upgrading from 9.0.0. Impact: none.
+
+Nothing in this release asks anything of a game.
+
+## 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.

package/docs/cross-promotion.md

@@ -4,6 +4,11 @@ The Arcade can show a **full-screen panel about another game** at a break in you
 for one; the Arcade decides whether to show anything, draws it in its own chrome over your paused
 game, and tells you when it is done.
 
+The same call with `format: 'rewarded'` is a button the player presses for something your game
+gives — a revive, an extra attempt. That one has its own page,
+[`rewarded-ads.md`](rewarded-ads.md). This page is about the interstitial; where a rule here reads
+differently for a rewarded ask, it says so.
+
 ```js
 const { outcome } = await gem.ads.requestAd({
   placement: 'level-complete',
@@ -20,10 +25,10 @@ That is the whole surface, apart from one read that tells a rewarded button whet
 
 `outcome` is one of exactly three values:
 
-| outcome | what happened | what your game does |
-|---|---|---|
-| `no_ad` | nothing was shown | carry on exactly as if you had not asked |
-| `shown` | a panel was painted and has closed | carry on — and grant nothing |
+| outcome       | what happened                          | what your game does                      |
+| ------------- | -------------------------------------- | ---------------------------------------- |
+| `no_ad`       | nothing was shown                      | carry on exactly as if you had not asked |
+| `shown`       | a panel was painted and has closed     | carry on — and grant nothing             |
 | `unavailable` | the Arcade could not draw one just now | carry on; read it identically to `no_ad` |
 
 **`no_ad` is the common answer**, not an edge case. There may be nothing suitable, the player may
@@ -37,48 +42,59 @@ So write the `no_ad` path as your ordinary path:
 - Do **not** hold up your own flow waiting for a fill. Ask, and continue when the promise settles.
 - Do **not** retry on a no. A second ask at the same break gets the same answer and spends a slot.
 
+**A rewarded ask reads differently, because the player pressed your button and is waiting on it.**
+Its `no_ad` can arrive with the reward already granted (§3), so branch on your inventory, never on
+the outcome; and where nothing landed, a neutral line in your own UI — "No revive this time" — is
+right, with no reason given. (When no ad was available and nothing was granted, the Arcade has
+already shown "No ad available right now" itself.) Draw the button only when
+`gem.ads.rewardedStatus` says it can pay (§3); [`rewarded-ads.md`
+§5](rewarded-ads.md#5-draw-the-button-only-when-it-can-pay) is that button.
+
 ## 2. Nothing rejects
 
 `requestAd` always resolves. There is no error branch and no `try`/`catch` to write. Even a refusal
 of your own arguments — a `placement` outside the grammar below, a `format` outside the two —
-resolves `no_ad`, so your game keeps exactly one branch. (The mistake is still reported to your
-`onError` handler, so you find out in development.)
+resolves `no_ad`, and so does a rewarded ask made without the player's press (see
+[Where to put the call](#where-to-put-the-call)), so your game keeps exactly one branch. (The
+mistake is still reported to your `onError` handler, so you find out in development.)
 
 ## 3. ⚠️ `shown` grants nothing
 
 `shown` says a panel was painted and has closed. It is **not** a receipt, **not** an entitlement,
 and **not** permission to hand anything out.
 
-`format: 'rewarded'` exists in the vocabulary and is answered `no_ad` today. Even when that
-changes, a reward will be granted by the platform against its own record of what was shown — never
-by your game reading an outcome. An outcome travels over the same channel as everything else your
-frame receives, and a game that unlocks a level or grants a currency on the strength of one has an
-unlock that any page embedding your game can forge.
+That holds for `format: 'rewarded'` too, the one format that pays the player. The platform grants a
+rewarded placement's reward itself, against its own record of the ad the Arcade played and how it
+ended — never your game, by reading an outcome. An outcome travels over the same channel as
+everything else your frame receives, and a game that unlocks a level or grants a currency on the
+strength of one has an unlock that any page embedding your game can forge.
 
 Treat a break as a break. If your game wants to give the player something for reaching the end of a
 level, give it to them for reaching the end of the level.
 
-**Where a rewarded grant will arrive, so you can write the code now.** On your game's own inventory
-for this player, written by the platform — never by your game — and read through
-`gem.me.inventory`, the same place a purchase lands, read the same way. (That is the game-scoped
-inventory `gem.me` shows you, not the player's platform wallet.) There will be **no fourth outcome
-and no extra field** on the answer. `outcome` is pinned at three values because a new value would
-break every game bundle already in the field: its validator refuses the whole message. A new field
-would not break anything — validators ignore fields they do not know — but it is not coming either:
-anything on that answer can be forged by the page embedding your game, so a reward carried there
-would be a reward anyone could hand out. If you serve `rewarded`, re-read your snapshot once the ask
-settles, whatever it settled as:
+**Where a rewarded grant arrives.** On your game's own inventory for this player, written by the
+platform — never by your game — and read through `gem.me.inventory`, the same place a purchase
+lands, read the same way. (That is the game-scoped inventory `gem.me` shows you, not the player's
+platform wallet.) There is **no fourth outcome and no extra field** on the answer. `outcome` is
+pinned at three values because a new value would break every game bundle already in the field: its
+validator refuses the whole message. A new field would not break anything — validators ignore
+fields they do not know — but it is not coming either: anything on that answer can be forged by the
+page embedding your game, so a reward carried there would be a reward anyone could hand out. So
+re-read your snapshot once a rewarded ask settles, whatever it settled as:
 
 ```js
 await gem.ads.requestAd({ placement: 'run-banked', format: 'rewarded' });
 gem.me.inventory.refresh(); // drop what is cached
-const snap = await gem.me.inventory.snapshot(); // the grant, if there was one, is here
+const snap = await gem.me.inventory.snapshot(); // a reward granted before the answer is here
 ```
 
-Today that re-read finds nothing new, because nothing is served. It costs one request at a break
-your player is already sitting in, and it is the whole of what changes on the day one is — no
-rebuild. [`inventory-and-catalogs.md` §6](inventory-and-catalogs.md#6-when-to-re-read) is the
-general form of this.
+A `no_ad` can come back with the reward already in that snapshot, because the platform grants
+without an ad in some cases, so branch on the inventory and never on the outcome. And a reward that
+an ad provider confirms from its own server can land after this re-read, so read again when the
+screen that spends it opens; [`inventory-and-catalogs.md`
+§6](inventory-and-catalogs.md#6-when-to-re-read) is the general form of this.
+[`rewarded-ads.md`](rewarded-ads.md) is the rest: declaring what a placement grants, spending it,
+drawing the button, and testing.
 
 **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
@@ -90,14 +106,14 @@ 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 |
+| 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
@@ -126,18 +142,57 @@ At a break **the player already expects**: a level ending, a round finishing, a
 return to a menu. Never mid-input, never during a timed sequence, and never on a screen the player
 reached by accident.
 
-`placement` is your own name for that break — `level-complete`, `run-banked`, `back-to-menu`. The
-platform matches it against nothing today, never shows it to a player, and does not vary its
-decision on it. It exists so your own analytics can tell two break points apart, so name it for
-yourself.
+**A rewarded ask comes from the player's press, and from nowhere else.** Your button is the
+player's opt-in. The Arcade starts the ad as soon as the ask arrives, with no prompt of its own
+first, so an ask the player did not make is an ad they did not choose. Call `requestAd` from the
+button's own `click`, `pointerup`, `touchend` or `keydown` handler, or straight from the
+controller press that chose it. Ask first, before any `await` or timer that could outlast the
+press: a browser counts a tap, click or key press for only a few seconds, and the SDK counts a
+controller press for one.
+
+⚠️ **Not from `pointerdown` or `touchstart`.** On a touchscreen they run before the browser counts
+the tap, so the ask is refused on a phone. With a mouse, `pointerdown` counts, so a desk test passes
+and hides it.
+
+Where the browser reports user activation, your frame holds none, and no controller was used in
+the last second, the SDK answers `no_ad` without asking. It writes a `[gem] rewarded_requires_user_gesture` line to the console once, and
+calls your `onError` handler with code `'internal'` and a message that begins
+`rewarded_requires_user_gesture`, which is the one to match in your own error reporting:
+
+```js
+const gem = createGem({
+  onError: (code, message) => {
+    if (message?.startsWith('rewarded_requires_user_gesture')) {
+      reportBug('rewarded ask outside a press', message); // your own telemetry
+    }
+  },
+});
+```
+
+Where the browser cannot tell, the ask goes ahead. The check is there to catch a mistake while you
+build; it is not a control. It catches an ask with no recent input, and cannot tell which input
+caused the ask, so an ask from another button's handler goes through. An interstitial needs no
+press.
+
+**The button says it is an ad, and names the reward:** "Watch an ad for 3 dice rolls", "Watch an ad
+to revive". Never use a label that hides the ad, or one that reads as the only way forward, such as
+"Tap to continue". [`rewarded-ads.md` §5](rewarded-ads.md#5-draw-the-button-only-when-it-can-pay)
+covers the button.
+
+`placement` is your own name for that break — `level-complete`, `run-banked`, `back-to-menu`. For
+an interstitial, the platform matches it against nothing, never shows it to a player, and does not
+vary its decision on it; it exists so your own analytics can tell two break points apart, so name
+it for yourself. For `format: 'rewarded'`, the placement names the reward your game config declares
+in `rewarded_placements`, and the platform matches it against that config. Either way it **never
+reaches an ad network**, and neither does any other string your game writes.
 
 **It has a grammar, and it is narrow on purpose: 1 to 32 characters of `a-z`, `0-9`, `-` and `_`.**
 Lowercase, no spaces, no accents — `'Boss Fight'` is not a placement, `'boss-fight'` is. Anything
 else resolves `no_ad` and is reported to your `onError` handler, so you meet it while you are
-building rather than later. The reason it is enforced now, while nothing depends on it, is that
-this is the field a promotion is eventually **keyed by**: the Arcade will forward it unchanged, and
-a name that does not fit the platform's grammar would be a name that stopped working after your
-game had shipped. The bound is the platform's, not the SDK's, and the two agree.
+building rather than later. The platform holds the same grammar where it reads the name: for a
+rewarded ask the Arcade forwards the placement unchanged, and a config that declares one outside
+the grammar is refused at upload, so a name that did not fit would be a reward your shipped game
+could never reach. The bound is the platform's, not the SDK's, and the two agree.
 
 ```js
 async function onLevelComplete() {
@@ -153,14 +208,18 @@ async function onLevelComplete() {
 Your game never learns what was shown — no title, no image, no id, nothing about the other game.
 You receive an outcome and nothing else.
 
-You are also never told *why* the answer was no. That is deliberate and permanent: a reason would
+You are also never told _why_ the answer was no. That is deliberate and permanent: a reason would
 tell your game something about the player that game code is not told, and there will not be a
 fourth outcome value naming one. The Arcade also settles every `no_ad` and `unavailable` on a
 schedule that does not depend on which branch produced it, so there is nothing in the timing to
 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:
+A rewarded ask is the one case where something else reaches your game: the reward itself, in your
+own inventory, when one was granted. That is what the ask is for. It says that a reward landed,
+never why, so do not read a reason into it.
+
+The other 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

package/docs/getting-started.md

@@ -50,7 +50,7 @@ either way.
 ```jsonc
 // package.json
 "dependencies": {
-  "@indiegems/gem-web-sdk": "8.1.0"
+  "@indiegems/gem-web-sdk": "9.1.0"
 }
 ```
 

package/docs/manifest.json

@@ -33,13 +33,13 @@
     },
     {
       "file": "changelog.md",
-      "sha256": "f13808374edf0988e0aef58b857c82298702a67d450962522a532b4827b74c91",
-      "updated": "2026-10-07T16:20:42Z"
+      "sha256": "9c99e6e42bd7c1a386bba50f07f3fd9cbcef20bd339a3d3f6f7ca8af1aff0462",
+      "updated": "2026-10-08T20:00:17Z"
     },
     {
       "file": "cross-promotion.md",
-      "sha256": "289cb4826a56b4e7423160e4187af65f4167c80218c2792ca0c01fbd977ecfec",
-      "updated": "2026-10-06T18:49:36Z"
+      "sha256": "92d4a1ffe19ceaaae1812bfdb77ebbdc04a7eca878ff28995eb6c388c7e876b3",
+      "updated": "2026-10-08T16:19:25Z"
     },
     {
       "file": "daily-challenges.md",
@@ -68,8 +68,8 @@
     },
     {
       "file": "getting-started.md",
-      "sha256": "222dcf81a2ed6d8fc8ffc37d5f7ef146dcf80c4b76f84fd9b8dd53ea1cbce23b",
-      "updated": "2026-10-07T16:20:42Z"
+      "sha256": "f622fe75e4d899bbe2bfa00103faa603e7d84f82579e7909dab16462bb2d1f72",
+      "updated": "2026-10-08T20:00:17Z"
     },
     {
       "file": "inventory-and-catalogs.md",
@@ -83,8 +83,8 @@
     },
     {
       "file": "match-session.md",
-      "sha256": "738c54766f5489ba7509f5f31ef1387a2a80ad89f03eaccd52113a18f2765b0d",
-      "updated": "2026-09-25T21:03:24Z"
+      "sha256": "33fdef4edc170cadd2284ff399fcf16455b7691d9aeac52bd09bade24b8b051a",
+      "updated": "2026-10-07T19:27:16Z"
     },
     {
       "file": "p2p-and-parties.md",
@@ -101,15 +101,20 @@
       "sha256": "df1e39628ccba04b6f7bcd0b90381dfa34a4480330a6af041d9b71bcaefddb5f",
       "updated": "2026-09-17T20:51:57Z"
     },
+    {
+      "file": "rewarded-ads.md",
+      "sha256": "f1f88f7d3aab2b1a1df2cecab59846625907e0391542291f1fbba56ea98d6476",
+      "updated": "2026-10-08T16:19:25Z"
+    },
     {
       "file": "room-shapes.md",
-      "sha256": "5aab02d65a7573ac690649b70e5db4fed4f779c3102c35e64a8ced02218410a9",
-      "updated": "2026-09-29T23:14:43Z"
+      "sha256": "78fad1eee7602b10a9b39f100d3daedfed6c313a884f95382233434a3206930b",
+      "updated": "2026-10-07T19:27:16Z"
     },
     {
       "file": "rooms-and-matches.md",
-      "sha256": "d8c397bc3657d7f46dba7ca0af81dcf181148df798dbaced27dfd294889a1da6",
-      "updated": "2026-09-25T02:14:45Z"
+      "sha256": "0abf3717a42c94ec832dfa1310c2d93a9f58236fd75b0aacaab301976bffe286",
+      "updated": "2026-10-07T19:27:16Z"
     },
     {
       "file": "saving-player-progress.md",
@@ -118,8 +123,8 @@
     },
     {
       "file": "server-bundles.md",
-      "sha256": "ffc7ec338f3436f73b16f8ba92a54de93e55bd5e9adbe562647e27b4867e4619",
-      "updated": "2026-10-07T16:20:42Z"
+      "sha256": "df1ec4c93429f286232cc468c4f06ff6a7327491bed72ce4a1a30e2ff8aaa3ad",
+      "updated": "2026-10-08T20:00:17Z"
     },
     {
       "file": "serverless-functions-js.md",
@@ -128,8 +133,8 @@
     },
     {
       "file": "serverless-functions.md",
-      "sha256": "1edaa60a8aaf20499f24d661f169790cacfdb11c26529735a93e5b7b996e5432",
-      "updated": "2026-10-03T00:26:43Z"
+      "sha256": "b1562b4442b69bb6895198def7b00ccd7a8c56133862a939c2cce9b6e9d30290",
+      "updated": "2026-10-07T19:27:16Z"
     },
     {
       "file": "trading-and-gifting.md",
@@ -143,8 +148,8 @@
     },
     {
       "file": "what-a-game-must-do.md",
-      "sha256": "3d3ed15c93368a03b11c0e4e1924797e2638aff5be264a799a259ee065d2dbfc",
-      "updated": "2026-10-06T23:08:59Z"
+      "sha256": "ff4a1d7613adff83ad9ac9b7c6be6266374e7c2bf7245f723f800ea335a4f4cf",
+      "updated": "2026-10-07T21:34:54Z"
     }
   ]
 }

package/docs/match-session.md

@@ -204,7 +204,7 @@ next round is one call:
 
 **A template's `auto_start_host` starts the first match, not the second.** It fires when the room
 reaches `min_players`; a reopened room already has them, and nothing fires again. A shape whose
-first match started itself — a hub, a worker, a matchmade lobby — still needs a client to call
+first match started itself — a hub, a matchmade lobby — still needs a client to call
 `startMatch()` for the next one, and that client is whoever `gem.rooms.isHost` says. Watch
 `hostChanged`: if the host closed their tab during the match, the room has a new host, and the
 start belongs to them now.