@indiegems/gem-web-sdk 21.1.1 → 22.0.0

package/docs/inventory-and-catalogs.md

@@ -629,8 +629,32 @@ no fallback celebration.
 `false` means the arcade will not show it here — the bridge is not up, or the embedder has no wallet
 — and your game does not draw one of its own in its place.
 
-Call it when your server moves the mapped progression — just before or just after the write, it does
-not matter; the arcade reconciles. Three things to know:
+Call it when your game decides to award, right beside the call that pays.
+
+**When your serverless function pays it, give the cue and the call one `cueId`.** The platform's
+event can reach the arcade before your `gem.functions.invoke` call even returns, so a cue sent after
+it would otherwise look like a second reward. Make one id per award with `crypto.randomUUID()`, pass
+it to `cueReward` and as the `cueId` of the `functions.invoke` that pays, and the arcade flies that
+reward once, whichever reaches it first, so you may cue before the call or after it returns:
+
+```js
+const cueId = crypto.randomUUID(); // one per award, never reused
+const result = await gem.functions.invoke({ claim: 'daily' }, { cueId });
+gem.cueReward({ currencySlug: 'GEMS', expected: 15, origin, cueId });
+```
+
+A payout that pays Gems and Coins in one call cues each currency with the same `cueId`. The id is
+yours and opaque: 1 to 64 letters, digits, `_` or `-`, and the SDK leaves out anything else with a
+console warning rather than fail the cue or the call. It is for the animation only. It moves no
+balance, your function never sees it, and no receipt or order carries it.
+
+**A payout with no id** (your own game server's write, or a build that passes none) is paired by
+currency and timing: cue it just before the write, or within about half a second after it.
+
+**Either way, the arcade decides when the payout is shown.** A payout no cue has met within about
+half a second flies from the middle of your frame, and a cue that comes after it adds nothing. If
+your reward moment comes after your server pays, present the payouts yourself (below). Three things
+to know either way:
 
 - **The arcade never takes your word for the amount.** What lands, and the player's new total, come
   from the platform's own event, sent only after the grant committed. `expected` is drawn as
@@ -648,6 +672,37 @@ not matter; the arcade reconciles. Three things to know:
 - **This is presentation, not permission.** It grants nothing, spends nothing and reveals nothing,
   and a reduced-motion player sees the total change without the flight.
 
+#### Showing the payout at a moment of your own: `gem.setRewardPresentation('game')`
+
+Your server pays when the reward is decided (the board is won, the run is verified), because that
+is when the result is checked and the progress saved. Your reward moment can come seconds or minutes
+later: the player taps **Claim** on the win card, or the coins fly on the screen they return to. Say
+so once, at boot, and each payout waits for your cue:
+
+```js
+gem.setRewardPresentation('game'); // at boot
+// ...your server pays when the board is won. Later, when the player taps Claim:
+gem.cueReward({ currencySlug: 'ARCADE_TICKETS', expected: 20, origin: claimCoinCentre });
+```
+
+- **The payout supplies the number; your cue supplies the moment.** The arcade holds what each
+  payout paid for its currency instead of flying it from the middle of your frame. Each
+  `cueReward` releases up to its `expected` of what is held (all of it when you give no amount) and
+  flies it from its `origin`; the wallet chip over your game, when you show one
+  (`setWalletVisible`), counts up as the marks land.
+- **Either order, any number.** A cue that finds nothing held waits for the next payout of its
+  currency, as it always has, and three payouts at the end of a level can be three cues, one cue,
+  or a cue per screen.
+- **It delays the show, never the money.** What is paid, when, and every ceiling are unchanged; the
+  arcade's menu, its header and every purchase see the player's true total the moment the platform
+  pays. Only the chip over your game shows the total minus what is still held.
+- **Nothing stays hidden.** Whatever part of a payout no cue releases within five minutes lands
+  quietly, with no flight. A player who quits on the win screen keeps every coin.
+- **Screen state, held across a reconnect.** `gem.setRewardPresentation('arcade')` goes back to the
+  default and lands whatever is held. It returns `true` when the arcade was told, and `false` before
+  the bridge is up (held and sent on connect) and under an embedder that presents every payout its
+  own way; there, keep cueing as usual and nothing else changes.
+
 To draw the Gem on your own screen, use the platform's art, which ships in the package — the Gems
 **icon** beside an amount or price, the **hero** only on a reward presentation where the gem is the
 subject. [brand-art.md](brand-art.md) has both, how to draw them, and the rest of the rules.

package/docs/manifest.json

@@ -28,8 +28,8 @@
     },
     {
       "file": "arcade-economy.md",
-      "sha256": "c0f25495a536d5facdbb63cbcd89acf558e2fe79d44f3a99d35284de1937fc42",
-      "updated": "2026-11-04T17:09:56Z"
+      "sha256": "108b3225a45dce776907344f8a3865b99b6e16598c6f70ddf0e8b923cf330a7e",
+      "updated": "2026-11-04T21:50:20Z"
     },
     {
       "file": "async-opponents.md",
@@ -48,13 +48,13 @@
     },
     {
       "file": "changelog.md",
-      "sha256": "e0cdfb5efc261694e3cca35e23a1e62768db192468cafeae9144835ea7ac99b3",
-      "updated": "2026-11-04T20:17:46Z"
+      "sha256": "8d83b78666b70888b6ecd2ffc6877956787daca3698eff5844e86f724699ce52",
+      "updated": "2026-11-04T23:21:33Z"
     },
     {
       "file": "daily-challenges.md",
-      "sha256": "fd1c44a923b8f7b82a52b958481e82ba5d62dc27de6a196a0776b0d34563ec54",
-      "updated": "2026-10-21T19:36:16Z"
+      "sha256": "8bc76d80cf419c196fbdb052785c4a768408118389c311537df4229be6129366",
+      "updated": "2026-11-04T21:50:20Z"
     },
     {
       "file": "dedicated-server-flow.md",
@@ -78,8 +78,8 @@
     },
     {
       "file": "getting-started.md",
-      "sha256": "7d2cbe5cf8e26e102f52c8dac279998d11a67d82042b7e6051d1e4fb1548b0a5",
-      "updated": "2026-11-04T20:17:46Z"
+      "sha256": "9cf851ec0894fd27350d492ce412ff025c86e17e2c9ecf900da7276868732540",
+      "updated": "2026-11-04T23:21:33Z"
     },
     {
       "file": "graphics-route.md",
@@ -88,8 +88,8 @@
     },
     {
       "file": "inventory-and-catalogs.md",
-      "sha256": "2094c555eb5a1a3d817a597ac07b2b193077f92176eb9596c2ba3ed461363bb6",
-      "updated": "2026-11-04T16:43:14Z"
+      "sha256": "eea98a531d814113474ab381b1e404a0c0c30c8c770ebe5c68da853eab85564d",
+      "updated": "2026-11-04T23:07:19Z"
     },
     {
       "file": "leaderboards.md",
@@ -143,8 +143,8 @@
     },
     {
       "file": "server-bundles.md",
-      "sha256": "31eeb1f555faf35123c4f22d072960448ef03f5ac4e76cc8c09748e127a88524",
-      "updated": "2026-11-04T20:17:46Z"
+      "sha256": "0f74e07ded6c9fb339c3bafa26e4af5153ce0bf20476fdb70444dcad2070766e",
+      "updated": "2026-11-04T23:21:33Z"
     },
     {
       "file": "serverless-functions-js.md",
@@ -153,8 +153,8 @@
     },
     {
       "file": "serverless-functions.md",
-      "sha256": "9a33e93c90c963fd82e4848d403f27134ec15636428f6cf896488089fec3ede1",
-      "updated": "2026-10-21T19:36:16Z"
+      "sha256": "4c38d374fd80424be8ce774916e82253e68d8878d8b20558b815feec80ff4ee7",
+      "updated": "2026-11-04T21:50:20Z"
     },
     {
       "file": "trading-and-gifting.md",
@@ -168,8 +168,8 @@
     },
     {
       "file": "what-a-game-must-do.md",
-      "sha256": "523886cf799570ab3631bbc9db11e03554d2ad403a1083d94038a48acd4fb611",
-      "updated": "2026-11-04T18:23:48Z"
+      "sha256": "e79c10bf3a06b7d9d85b5d6ba06a7a1cddf7a27f02d26b4bb4399ebf0d5a0644",
+      "updated": "2026-11-04T23:07:19Z"
     }
   ]
 }

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/v21.1.1/gem-web-sdk.tgz
-curl -fsSL https://downloads.gemarcade.com/sdk/v21.1.1/gem-web-sdk.tgz.sri
+curl -fsSL -O https://downloads.gemarcade.com/sdk/v22.0.0/gem-web-sdk.tgz
+curl -fsSL https://downloads.gemarcade.com/sdk/v22.0.0/gem-web-sdk.tgz.sri
 openssl dgst -sha384 -binary gem-web-sdk.tgz | openssl base64 -A
 ```
 

package/docs/serverless-functions.md

@@ -716,6 +716,22 @@ try {
 }
 ```
 
+**A call that pays a reward the player sees takes a `cueId`.** Pass the same id to
+`gem.cueReward` for that reward, one `crypto.randomUUID()` per award, and the Gem Arcade flies it
+once whichever of the two reaches it first:
+
+```js
+const cueId = crypto.randomUUID();
+const result = await gem.functions.invoke(claim, { cueId });
+gem.cueReward({ currencySlug: 'GEMS', expected: 15, origin, cueId });
+```
+
+The platform carries it to the payout event it shows the arcade and nowhere else: your function
+never sees it, and neither the answer nor a receipt carries it. It is 1 to 64 letters, digits, `_`
+or `-`; the SDK leaves out anything else with a console warning and still makes the call.
+[inventory-and-catalogs.md](inventory-and-catalogs.md#showing-the-reward-land-in-the-arcades-wallet)
+has the cue itself.
+
 ⚠️ **A lost connection is `retryable` and tells you nothing about whether your function ran.** The
 call left, and no answer came back. If your function grants or writes, make it safe to call twice
 with the same input, for instance by keying what it writes on an id the caller sends.
@@ -882,6 +898,7 @@ the last column: it is `true` exactly where this table says to retry.
 | `422 function_failed`                                      | It did not finish. `err.failure` is `trap`, `memory_exceeded`, `cpu_budget_exceeded`, `host_call_limit`, `output_too_large` or `argument_too_large` | A bug or a limit in the function. Reproduce with the same input        |
 | `504 function_timeout`                                     | It ran past the wall clock                                                                                                                          | Do not retry: the same input takes as long again                       |
 | `404 function_not_published`                               | Nothing is promoted on the caller's channel                                                                                                         | `gemctl function promote <version> --channel <channel>`                |
+| `400 invalid_cue_id`                                       | The `cue_id` query parameter is not 1 to 64 letters, digits, `_` or `-`. `gem.functions.invoke` leaves a bad `cueId` out, so only a hand-written call meets it | Fix the hand-written call                                              |
 | `413 function_input_too_large`                             | The input is over 256 KiB                                                                                                                           | Send a request, not a file                                             |
 | `429 rate_limited`                                         | This caller's per-minute budget is spent                                                                                                            | Wait `err.retryAfterSeconds`                                           |
 | `503 function_capacity_unavailable`                        | The platform was too busy to run it. Your function is not known to be broken                                                                        | Retry after `err.retryAfterSeconds`                                    |

package/docs/what-a-game-must-do.md

@@ -1785,7 +1785,9 @@ opens the Gem menu — the Gem button, in whichever corner it sits — to see th
 achievement score, and every payout
 [`gem.cueReward`](inventory-and-catalogs.md#showing-the-reward-land-in-the-arcades-wallet) announces
 flies into the Gem button. A payout you do not cue flies too, from the middle of your frame, so cue
-the ones the player earns on screen and the flight starts where they are looking.
+the ones the player earns on screen and the flight starts where they are looking. A payout your
+serverless function makes takes the same `cueId` on the cue and on `gem.functions.invoke`, so it
+flies once.
 
 **A game that wants them on screen asks** (the owner, 2026-10-29):
 
@@ -1804,6 +1806,25 @@ gem.setWalletVisible(true, { only: ['GEMS', 'ARCADE_TICKETS'] }); // add 'score'
 - **An Arcade from before this change ignores the call**: nothing breaks, and the wallets stay in
   the Gem menu. Another embedder that draws wallets over games honours it the same way.
 
+### When a payout is shown: `gem.setRewardPresentation`
+
+By default the Arcade decides when a payout is shown: a cue within about half a second of your
+server's write flies it from the cue's `origin`, and a payout with no cue by then flies from the
+middle of your frame. **If your reward moment comes after your server pays** — a Claim button on
+the win card, or the screen the player returns to — say so once, at boot:
+
+```js
+gem.setRewardPresentation('game');
+```
+
+Each payout then waits for your `gem.cueReward`, which releases up to its `expected` and flies it
+from its `origin`, in either order and at any moment within five minutes; whatever no cue releases
+by then lands quietly, with no flight. The money never waits: what is paid and when is unchanged,
+and the Gem menu and every purchase see the player's true total at once. `'arcade'` goes back to
+the default.
+[inventory-and-catalogs.md](inventory-and-catalogs.md#showing-the-payout-at-a-moment-of-your-own-gemsetrewardpresentationgame)
+has the detail.
+
 ## No accidental text selection
 
 **You write nothing for this.** A long press on a phone, a double-click on a button, a drag across

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indiegems/gem-web-sdk",
-  "version": "21.1.1",
+  "version": "22.0.0",
   "description": "postMessage bridge contract between gem-web and browser-playable games",
   "license": "UNLICENSED",
   "type": "module",

package/schema/bridge.v1.json

@@ -2947,10 +2947,24 @@
         "creator's ruling, 2026-09-24), so a game draws no Gems flight, counter or",
         "celebration of its own. The same holds for Coins (`ARCADE_TICKETS`):",
         "`currencySlug` decides what flies and which total moves. `origin` is the",
-        "centre of the game's icon for that currency — its gem, or its coin."
+        "centre of the game's icon for that currency — its gem, or its coin.",
+        "",
+        "`cueId` ties this cue to the grant it announces, so the arcade flies that",
+        "reward ONCE whichever of the two reaches it first. The game chooses it —",
+        "one `crypto.randomUUID()` per award — and passes the same one to the",
+        "`gem.functions.invoke` that pays, which carries it to gem-api as the",
+        "`cue_id` query parameter; gem-api echoes it as `cue_id` on every",
+        "`platform_grant_fired` that invocation's grants send. Opaque and for",
+        "animation only: it moves no balance, never names an order, and is never",
+        "rendered. The SDK sends only 1 to 64 letters, digits, `_` or `-`; the",
+        "wire bounds the length alone (no `format`, so a parent need not learn",
+        "one), and a parent that compares it rechecks the characters itself and",
+        "drops a malformed one, keeping the cue. Absent, the arcade pairs the cue",
+        "and the grant by currency and timing, as before."
       ],
       "fields": {
         "currencySlug": { "kind": "string", "maxLength": 32 },
+        "cueId": { "kind": "string", "maxLength": 64, "optional": true },
         "expected": { "kind": "int", "min": 1, "max": 1000000000, "optional": true },
         "origin": {
           "kind": "object",
@@ -2964,6 +2978,59 @@
       "rateLimit": { "perMinute": 60 }
     },
 
+    {
+      "type": "gem.rewardPresentation",
+      "direction": "frameToParent",
+      "transport": "port",
+      "$comment": [
+        "Who decides WHEN a platform-currency payout from this game is shown landing:",
+        "the arcade (`arcade`, what a parent does with no message at all) or the game",
+        "(`game`). It changes the presentation only. What is paid, when the server pays",
+        "it, the receipt, every ceiling and the player's ledger are the same either way.",
+        "",
+        "`arcade`: a payout the game cues within a beat of it flies from the cue's",
+        "`origin`, and one it does not flies from the middle of the frame. A cue that",
+        "arrives after its payout was already shown adds nothing.",
+        "",
+        "`game`: the game's cue supplies the moment and the payout supplies the number.",
+        "A parent adds each payout to an amount it HOLDS for that currency instead of",
+        "showing it, and its own wallet readout over the game shows the true total",
+        "minus what it still holds, so a spend or a payout from anywhere else still",
+        "moves it at once. A `gem.rewardCue` releases up to its `expected` of the held",
+        "amount, or all of it when it names none, flying from its `origin`. A cue that",
+        "finds nothing held waits for the next payout of its currency, as in `arcade`.",
+        "So payouts and cues meet in either order and several at once need no pairing.",
+        "Whatever part of a payout no cue has released within five minutes of its",
+        "arrival lands quietly, with no flight: a game can delay its payout's",
+        "presentation, never hide it.",
+        "",
+        "A cue still adds nothing to a wallet: what lands is always the payout's own",
+        "figure. The parent's other surfaces (its menu, its header, every purchase)",
+        "read the true total the moment the payout lands, so a held readout never stops",
+        "a player spending what they have.",
+        "",
+        "SCREEN STATE, NOT A TOGGLE, like `gem.gemCorner`. Each message is the whole",
+        "answer and the latest one wins. The SDK holds it from before the bridge is up",
+        "and re-sends it after every handshake, so a parent that reconnects presents",
+        "the way the game had asked. A switch back to `arcade` lands what is held.",
+        "",
+        "A PRESENTATION REQUEST ONLY, and not an authorization control. Cosmetic:",
+        "nothing may key a trust decision on it.",
+        "",
+        "Gated by `rewardPresentation`: sent only to a parent that advertised it. To",
+        "any other, `gem.setRewardPresentation` returns false, and that parent presents",
+        "every payout the `arcade` way."
+      ],
+      "fields": {
+        "mode": {
+          "kind": "enum",
+          "values": ["arcade", "game"],
+          "$comment": "`game` holds each payout's presentation for the game's cue; `arcade` is the default, for a parent that has had no message."
+        }
+      },
+      "rateLimit": { "perMinute": 12 }
+    },
+
     {
       "type": "gem.walletDisplay",
       "direction": "frameToParent",

package/schema/capabilities.public.json

@@ -141,6 +141,12 @@
         "gem.rewardCue"
       ]
     },
+    "rewardPresentation": {
+      "implemented": true,
+      "gates": [
+        "gem.rewardPresentation"
+      ]
+    },
     "frameStats": {
       "implemented": true,
       "gates": [