@indiegems/gem-web-sdk 21.1.1 → 23.0.0

package/docs/friends.md

@@ -11,8 +11,9 @@ for (const friend of page.friends) {
 }
 ```
 
-That read, one ask — [sending a friend a challenge](#friend-challenges), which the Arcade
-confirms with the player and sends itself — and [reading the challenges the player
+That read, two asks — [sending a friend a challenge](#friend-challenges), which the Arcade
+confirms with the player and sends itself, and [inviting friends to play](#inviting-a-friend-to-play),
+which opens the Arcade's own invite sheet — and [reading the challenges the player
 received](#reading-the-challenges-a-player-received) in your game are the whole surface. The
 boundary around them is the thing to understand before you design against it.
 
@@ -36,8 +37,10 @@ Everything else about the friend graph stays on the Arcade, by design:
   answered (`gem.friends.markAnswered`), which records that they played it and tells nobody.
 - **No states.** Pending requests, blocks and relationship history do not appear. An accepted
   friend appears; everyone else does not exist on this surface.
-- **No presence, no invites.** Nothing here says who is online or delivers an invite — an invite
-  is something happening *in* the graph, and it is rendered where the graph lives. See the
+- **No presence, and no invites delivered to your game.** Nothing here says who is online, and an
+  invite is something happening _in_ the graph, so it is rendered where the graph lives. Your game
+  may [ask the Arcade to open its own invite sheet](#inviting-a-friend-to-play), and that is the
+  whole of it: the Arcade picks no one for you, and tells you nothing back. See the
   deliberate-absence notes in [`rooms-and-matches.md`](rooms-and-matches.md). A friend challenge
   is not an invite to play together: it is a card in the friend's Arcade inbox, written by the
   platform from your template, that launches your game when they tap it — whenever they next open
@@ -46,7 +49,7 @@ Everything else about the friend graph stays on the Arcade, by design:
 Two properties worth designing around rather than discovering:
 
 - **Every accepted friend appears, whether or not they have played your game.** That is the
-  point, not an oversight — an invite-a-friend flow needs exactly the friends who have *not*
+  point, not an oversight — an invite-a-friend flow needs exactly the friends who have _not_
   played it. If you only want friends with progress in your game, join the list against your own
   data (a friend's `playerId` is the same id leaderboard rows and transfers carry).
 - **It is a player surface only.** On a dedicated server there is no `gem.friends`, and the route
@@ -132,12 +135,12 @@ the card already says who sent it, and a name in a param is one nobody checked.
 `challenge()` resolves for every answer the player or the platform gives, and none of them
 carries a reason:
 
-| outcome | what happened | what to show |
-|---|---|---|
-| `accepted` | the player pressed Send and the platform took it | "Challenge sent", or nothing — the Arcade already said so |
-| `cancelled` | the player closed the sheet, or another prompt already held the screen | **nothing** |
-| `refused` | the platform will not send this one — a guest or signed out, not friends with that player, or no access to this channel | **nothing** |
-| `unavailable` | the Arcade could not offer this, or no answer arrived | **nothing**, and never retry it on your own |
+| outcome       | what happened                                                                                                           | what to show                                              |
+| ------------- | ----------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
+| `accepted`    | the player pressed Send and the platform took it                                                                        | "Challenge sent", or nothing — the Arcade already said so |
+| `cancelled`   | the player closed the sheet, or another prompt already held the screen                                                  | **nothing**                                               |
+| `refused`     | the platform will not send this one — a guest or signed out, not friends with that player, or no access to this channel | **nothing**                                               |
+| `unavailable` | the Arcade could not offer this, or no answer arrived                                                                   | **nothing**, and never retry it on your own               |
 
 ⚠️ **`accepted` is not a delivery receipt.** The platform may decide not to deliver a challenge
 — the friend muted your game, has had enough challenges today, or cannot receive them — and
@@ -171,6 +174,7 @@ existing `instanceof GemApiError` handling keeps working:
   digits, `_` and `-`, a plain object of strings and integers, at most 8 keys — so most of these
   reach you before anything is shown to the player. `detail` is the platform's sentence, for your
   console, never for a player.
+
 - **`rate_limited`** — the player has sent too many. `retryAfterSeconds` is the earliest a fresh
   press could succeed, and it can be up to a day.
 
@@ -199,9 +203,10 @@ const challenge = await gem.friends.launchedChallenge();
 if (challenge?.template === 'beat_code_jar') {
   // Check every param before it does anything, as you would a launch key: the template
   // constrained it when it was sent, but your config may have changed since.
-  const jar = typeof challenge.params.jar === 'string' && /^[A-Z0-9]{7}$/.test(challenge.params.jar)
-    ? challenge.params.jar
-    : null;
+  const jar =
+    typeof challenge.params.jar === 'string' && /^[A-Z0-9]{7}$/.test(challenge.params.jar)
+      ? challenge.params.jar
+      : null;
   if (jar) {
     startJar(jar, {
       from: challenge.from, // who sent it, from the platform's records
@@ -273,6 +278,106 @@ while (page.nextCursor) {
 
 For the challenge this launch carried, use `launchedChallenge()` rather than searching the inbox.
 
+## Inviting a friend to play
+
+Your game may ask the Arcade to open **its own invite sheet**, where the player picks friends to
+invite to come and play your game with them, now:
+
+```js
+inviteButton.hidden = !gem.frame.parentSupports('playInvites');
+inviteButton.onclick = async () => {
+  const shown = await gem.friends.inviteToPlay();
+  if (!shown) showJoinCode(); // the sheet did not open: offer your own way in
+};
+```
+
+The Arcade lists the player's friends in its own chrome, pauses your game while the sheet is
+open, and sends an invite each time the player presses Invite there. A friend who accepts is
+opened into your game by the Arcade, and their own quick-join seats them in the player's room
+when it has a seat — your game makes no call for it, is not told who is coming, and finds them in
+the room as a member who shares the player's `groupId`. [Landing in a friend's
+room](rooms-and-matches.md#5e-landing-in-a-friends-room-play-with) is how they arrive.
+
+An invite is live, unlike a challenge: it reaches a friend who is on the Arcade now, and nothing
+waits in an inbox. For "beat my score whenever you next play", send a
+[friend challenge](#friend-challenges) instead.
+
+### Invites and share links are one window
+
+The sheet is the Arcade's **Friends window**. The player also opens it from the Arcade's own menu
+over your game, without your game asking. It holds the friends to invite **and** a link to share
+with anyone else, and both open your game the same way: with **your launch parameters**, on
+exactly [`gem.share.request`'s rules](getting-started.md#linking-to-your-game). So a game whose
+rooms are joined by a code says the code once, and a friend who accepts an invite and a stranger
+who opens the shared link both arrive with it.
+
+There are two ways to say it, for the window's two ways in:
+
+- **`gem.friends.setInviteParams(params)`** — a standing declaration, for the window the PLAYER
+  opens from the Arcade's menu. Call it when the player enters a room joined by code, and
+  `setInviteParams(null)` when they leave it, so the window never invites anyone into a room that
+  is gone. The latest call stands; the SDK holds it and says it again after a reconnect.
+- **`gem.friends.inviteToPlay({ params })`** — from your own Invite button, for that one opening.
+  It wins over the declaration. Omit `params` to use the declaration.
+
+A room joined by code, end to end:
+
+```js
+// The host makes the room and says what the window should open.
+const room = await gem.rooms.create({/* your template */});
+gem.friends.setInviteParams({ room: room.joinCode });
+
+// Your own Invite button, if you draw one, needs nothing more:
+inviteButton.onclick = () => gem.friends.inviteToPlay();
+
+// Leaving the room clears it.
+gem.friends.setInviteParams(null);
+
+// Arrival is unchanged: whoever opens the link or accepts the invite launches your game
+// with ?room=<code>, and you join as you already do for a shared link.
+const code = new URLSearchParams(location.search).get('room');
+if (code) await gem.rooms.joinByCode(code);
+```
+
+The params name what a link opens and never a person, so they tell the Arcade nothing about the
+player's friends, and nothing about who was invited comes back. A param the share rules refuse —
+a reserved key, more than 16, a bad key or value — is said on the console and nothing is sent:
+`inviteToPlay` resolves `false`, and `setInviteParams` returns `false` and leaves the last
+declaration standing. A game with a quick-join hub needs no params at all: the friend's
+quick-join already seats them in the player's room (above).
+
+### One answer, and nothing else
+
+`inviteToPlay()` resolves one boolean. It never rejects.
+
+| resolves | what happened                                                                                                                                                                                                                 |
+| -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `true`   | the Arcade opened its invite sheet                                                                                                                                                                                            |
+| `false`  | it did not: outside the Arcade or without `playInvites` (answered at once, with nothing asked), no press behind the ask, another sheet or prompt already open, a player the Arcade offers no invites to, or no answer arrived |
+
+**What your game never learns:** whom the player invited, how many, whether any invite was sent,
+delivered or accepted, or why the sheet did not open. Who a player invites is a fact about the
+people they know, and whether an invite landed is a fact about somebody else's settings; neither
+is your game's. `true` means a sheet opened, not that anybody was invited.
+
+**Your game names nobody and writes nothing.** No player, no text: the friends on the sheet are
+the Arcade's own list, and the words on the sheet and on the invite are the Arcade's. Your launch
+params say what the link opens, as a share's do, and nothing else.
+
+### Rules that are not optional
+
+- **Call it only from a player's press.** The Arcade answers an ask with no press behind it
+  `false`, and shows nothing. Never on a timer, as a screen opens, or after a long `await`.
+- **Never gate progress or a reward on it.** You cannot tell whether anyone was invited, by
+  design, so a reward for it is a reward for pressing a button.
+- **Never retry it on your own.** `false` is an answer: offer your own way in instead, such as a
+  join code or a [share link](getting-started.md#linking-to-your-game).
+- **One sheet at a time.** Calls made while an ask is open share its answer, and an ask that
+  arrives while the Arcade already shows a sheet is answered `false`.
+- **Hide the button where it cannot work.** `gem.frame.parentSupports('playInvites')` is false
+  outside the Arcade — a local dev host included — and `inviteToPlay()` answers `false` there at
+  once, asking nothing. Try the real flow on your game's dev channel in the Arcade.
+
 ## Inspecting a player: game profiles
 
 The "inspect this player" screen — tap a roster row, a leaderboard entry or a friend, see who
@@ -296,7 +401,7 @@ profile. Entries arrive ordered by key, each naming its slot's declared `visibil
 
 Three properties to design around:
 
-- **A game shapes its profile in the game config, not here.** Profile content *is* the game's
+- **A game shapes its profile in the game config, not here.** Profile content _is_ the game's
   showcase slots — save schemas declared with a `visibility` of `friends` or `public` — and the
   write path is `gem.showcase.set` (or your dedicated server, for values a modified client must
   not forge). There is no profile write on this surface, and identity is the player's own,

package/docs/getting-started.md

@@ -50,7 +50,7 @@ either way.
 ```jsonc
 // package.json
 "dependencies": {
-  "@indiegems/gem-web-sdk": "21.1.1"
+  "@indiegems/gem-web-sdk": "23.0.0"
 }
 ```
 
@@ -308,6 +308,12 @@ whether they shared, cancelled, or closed the panel. Where the arcade handles it
 `gem.share.available` is true; outside the arcade, before the bridge is up, and anywhere the
 arcade does not share your game, it is false.
 
+**The Arcade's Friends window shares the same link.** The player can open it from the Arcade's
+menu over your game to invite friends and share a link, and both carry the launch parameters you
+give `gem.friends.setInviteParams` or `gem.friends.inviteToPlay`, on the rules below. A game whose
+rooms are joined by code declares the code there; see
+[Invites and share links are one window](friends.md#invites-and-share-links-are-one-window).
+
 `request` checks every parameter against the rules below **before** anything is sent, and
 throws on the first one the arcade would refuse, naming it: more than 16, a key that breaks the
 key rule or is one the arcade will not carry, or a value that is not a string, is too long, or

package/docs/inventory-and-catalogs.md

@@ -117,7 +117,8 @@ snap.progressions.data; // progression state
 The snapshot is **cached**. Repeat calls, and reads derived from it — `gem.me.currencies`,
 `gem.me.progressions`, item-instance lookups — serve from the one cached read rather than issuing
 a request each, so a HUD polling a balance does not re-download the whole bag. Any change the SDK
-makes drops the cache; [§6](#6-when-to-re-read) is about the changes it cannot see.
+makes drops the cache, and so does the Arcade's hint that your inventory changed on the server;
+[§6](#6-when-to-re-read) is about both.
 
 Each of the three sections carries its **own cursor**, because any one of them can be large
 independently, and the snapshot carries an **`etag`** — the inventory's version — which
@@ -126,18 +127,35 @@ conditional.
 
 ## 6. When to re-read
 
-**There is no push into a sandboxed frame.** A gift arriving from another player, a grant from
-your dedicated server, a change made on the player's other device — none of these produces an
-event in your game, because the frame has no socket to hear about them. A change your own game
-made through the SDK drops the cache; nothing else does.
+**On an Arcade that relays it, the frame hears about changes to your game's own inventory.** A
+grant from your function or your dedicated server, a purchase, a gift another player sent, a
+support grant, a change made on the player's other device: each one drops the SDK's cached reads
+and fires `gem.me.inventory.onChanged` (and a held character's `inventory.onChanged`). The
+Arcade sends nothing but the fact that something changed, so your listener re-reads:
 
-So the SDK's change event fires for your own writes and no others. Build on that and a port from
-a native engine — which _did_ push external changes — is wrong in exactly the places the engine
-was right.
+```js
+gem.me.inventory.onChanged(async () => {
+  drawBag(await gem.me.inventory.snapshot()); // the cache is already dropped: this really asks
+});
+```
+
+It is a cue to re-read, not a receipt, and it arrives a moment after the change commits. It is
+only ever about **this** game, on the channel you are playing: the Arcade never relays another
+game's changes or the platform wallet's (Gems and Coins have their own hint,
+`gem.platform.earnAllowance.on('changed')`). A burst — a function granting in a loop — reaches
+you as one call now and at most one more every two seconds, and the hint itself makes no request.
+
+**After your own function's grant, don't wait for a read to show it.** When
+`gem.functions.invoke` resolves, what the function says it granted has already been written: the
+function's answer is the receipt. Show it, let the player go on, and re-read in the background
+(see
+[`serverless-functions.md`](serverless-functions.md#6-calling-it-from-your-game)).
+`onChanged` redraws the bag when the fresh read lands.
 
-The remedy is not a poll. **Do not poll**: a fixed-period re-read is a per-session load on the
-backend that scales with your player count and buys staleness you could have designed around.
-Instead:
+**An older Arcade sends no hint.** There, only a change your own game made through the SDK drops
+the cache and fires `onChanged`, so keep a fallback that does not depend on the hint. The remedy
+is not a poll. **Do not poll**: a fixed-period re-read is a per-session load on the backend that
+scales with your player count and buys staleness you could have designed around. Instead:
 
 - Re-read on screen-open. When the tab becomes visible, drop the cache and read again:
 
@@ -629,8 +647,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 +690,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": "20215a4410087dd6076afd787bcfd4ee29bc5bf50e56562563e32a060cd74cc4",
+      "updated": "2026-11-05T00:34:54Z"
     },
     {
       "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",
@@ -68,8 +68,8 @@
     },
     {
       "file": "friends.md",
-      "sha256": "d8e1f07a10ebe5743a1d56d615731cc6e5965e1a380490d2a1362dc6c1263d2d",
-      "updated": "2026-10-12T16:40:39Z"
+      "sha256": "fd6db8da391647677568c0d2257dc5c92cbfe311759191b5e28fa3f66747aee6",
+      "updated": "2026-11-04T23:46:11Z"
     },
     {
       "file": "game-economy-tutorial.md",
@@ -78,8 +78,8 @@
     },
     {
       "file": "getting-started.md",
-      "sha256": "7d2cbe5cf8e26e102f52c8dac279998d11a67d82042b7e6051d1e4fb1548b0a5",
-      "updated": "2026-11-04T20:17:46Z"
+      "sha256": "c2f0c4fe33cc3e34120773a606179a4254963b957ab39cdda746c2f01db493d4",
+      "updated": "2026-11-05T00:34:54Z"
     },
     {
       "file": "graphics-route.md",
@@ -88,8 +88,8 @@
     },
     {
       "file": "inventory-and-catalogs.md",
-      "sha256": "2094c555eb5a1a3d817a597ac07b2b193077f92176eb9596c2ba3ed461363bb6",
-      "updated": "2026-11-04T16:43:14Z"
+      "sha256": "f5aa4e405989da098317ca704b4dd8b996a1369c78ef0515ed7442886aee85fc",
+      "updated": "2026-11-04T23:38:54Z"
     },
     {
       "file": "leaderboards.md",
@@ -133,8 +133,8 @@
     },
     {
       "file": "rooms-and-matches.md",
-      "sha256": "4c1c32c5523eca1a8e3a2e06b42dab3ec4c70e8bd77496614aca909732485da4",
-      "updated": "2026-10-21T19:51:32Z"
+      "sha256": "dcbd9dda741656e5e346c2fea3240331ac19d055aede0ff27d706a63efb35500",
+      "updated": "2026-11-04T23:26:42Z"
     },
     {
       "file": "saving-player-progress.md",
@@ -143,8 +143,8 @@
     },
     {
       "file": "server-bundles.md",
-      "sha256": "31eeb1f555faf35123c4f22d072960448ef03f5ac4e76cc8c09748e127a88524",
-      "updated": "2026-11-04T20:17:46Z"
+      "sha256": "fe9e5ced6e2e6bc4d583697c5f206f2f0431af8926eab7d8076f7f46e42864c9",
+      "updated": "2026-11-05T00:34:54Z"
     },
     {
       "file": "serverless-functions-js.md",
@@ -153,13 +153,13 @@
     },
     {
       "file": "serverless-functions.md",
-      "sha256": "9a33e93c90c963fd82e4848d403f27134ec15636428f6cf896488089fec3ede1",
-      "updated": "2026-10-21T19:36:16Z"
+      "sha256": "fa1d161689e30d2300ab2ec7de3f3a5c9147966f559f7272b9e9b91852ecbeb4",
+      "updated": "2026-11-04T23:38:54Z"
     },
     {
       "file": "trading-and-gifting.md",
-      "sha256": "e5a77bcae4243fbf69a34fa6440114677401255b40ee9825c15b87c6570e5030",
-      "updated": "2026-10-21T19:36:16Z"
+      "sha256": "24ff7ebfc10b5186527cc51b49d8f2f556b43e6ff37b06db20ce3c7efd87855a",
+      "updated": "2026-11-04T23:38:54Z"
     },
     {
       "file": "vibration.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/rooms-and-matches.md

@@ -56,7 +56,9 @@ Two engine signals are deliberately absent, and each absence is a rule rather th
   display identity only, via `gem.friends` ([`friends.md`](friends.md)) — and nothing else about
   the graph crosses the frame. No presence, no pending requests, no invite events, no mutations.
   An invite is something happening *in* the graph, so it is delivered and rendered where the
-  graph lives, on the Arcade. Derived questions also keep being answered where the data lives:
+  graph lives, on the Arcade. A game may ask the Arcade to open its own invite sheet
+  (`gem.friends.inviteToPlay`), and a friend who accepts arrives by quick-join (§5e) — but the
+  invite itself never reaches a game. Derived questions also keep being answered where the data lives:
   the friend view in [`leaderboards.md`](leaderboards.md) re-ranks a board server-side, and a
   party crosses into a room as an opaque grouping.
 - **`ping_results_ready`** — the engine's measurement is a UDP echo, which a browser cannot perform.
@@ -1004,8 +1006,9 @@ but never start short", name the same slugs on `queueForMatch()` instead.
 ## 5e. Landing in a friend's room: play-with
 
 The Arcade can open your game **to play with someone**: when the player presses Join on a friend
-who is playing it, or answers the prompt the Arcade shows a party member when their leader starts
-it. Your game makes no call for this. The Arcade adds a
+who is playing it, accepts an invite a friend sent from inside it
+([`friends.md`](friends.md#inviting-a-friend-to-play)), or answers the prompt the Arcade shows a
+party member when their leader starts it. Your game makes no call for this. The Arcade adds a
 launch key of its own, `gemPlayWith`: an opaque ticket the platform issued for this player, which
 names nobody your game can recognise. The SDK reads it once as `createGem` runs, and every
 `quickJoin()` of the session passes it on: the platform tries the room of the person the ticket

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

package/docs/serverless-functions.md

@@ -150,6 +150,9 @@ fires them only when you opt in:
 - **A function a player called pays that player.** Its `call-api` writes the opted-in progression
   for the player id `get-context` gave it, and the platform grants and unlocks as it does for your
   server's write: currency on every channel, achievements on `release` only.
+- **The function's answer should name what it paid.** The game shows the reward from that answer,
+  at once, rather than reading the inventory until it appears
+  ([section 6](#6-calling-it-from-your-game)).
 - **It pays nobody else.** It cannot write another player at all
   (`403 function_foreign_entity_write`, the previous subsection), so it cannot pay one, directly or
   through anything your config writes on the order's behalf. A character never earns a platform
@@ -683,6 +686,24 @@ A value JSON cannot carry, such as a `BigInt`, is refused before anything is sen
 - `result.text()` reads them as UTF-8, and throws if they are not UTF-8 rather than changing them;
 - `result.bytes` is the bytes themselves, for a function that answers in binary.
 
+**The answer is the receipt.** When `invoke` resolves, what your function says it granted has
+already been written: the write happens inside the function, before it answers, and a refusal is
+its `Err`, so a resolved call is never a "maybe". Show what the answer says and let the player go
+on at once. Re-read in the background, and redraw when the read lands:
+
+```js
+const { granted } = (await gem.functions.invoke(claim)).json();
+showReward(granted); // the function's word: show it now
+gem.me.inventory.refresh(); // drop the cache...
+gem.me.inventory.snapshot().then(drawBag); // ...and redraw from a fresh read, in the background
+```
+
+**Never hold the player on a loop that re-reads until the grant shows.** That wait adds the
+platform's read latency to every reward and buys nothing the answer did not already say. On an
+Arcade that relays it, `gem.me.inventory.onChanged` also fires once the platform has the change
+([inventory-and-catalogs.md](inventory-and-catalogs.md#6-when-to-re-read)), so a listener there can
+do the redraw for you.
+
 **It sends the call once.** The SDK never repeats a function call for you, because your function
 may have granted or written something, and a retry you cannot see is how one grant becomes two.
 Whether repeating it could help is on the error. A repeated call may grant again, and what stops
@@ -716,6 +737,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 +919,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/trading-and-gifting.md

@@ -38,15 +38,18 @@ await gem.transfers.reject(transferId);
 await gem.transfers.cancel(transferId);
 ```
 
-## The recipient is not told
-
-**A transfer produces no event in the recipient's game.** As everywhere else, there is no push
-into a sandboxed frame — the arriving gift is, by definition, a change some _other_ player made,
-which is precisely the kind of change your game cannot be notified of. See
-[`inventory-and-catalogs.md`](inventory-and-catalogs.md#6-when-to-re-read) for the full rule; the
-short version is that the recipient sees the gift the next time their game re-reads its inventory,
-so re-read after any action that could have involved another player, and design so a few seconds
-of not-yet-seeing-it is harmless.
+## How the recipient hears about it
+
+**On an Arcade that relays it, the recipient's game is told its inventory changed.** The gift
+lands in the recipient's inventory for your game, and the Arcade sends that game the same
+field-free hint as for any other change to its own inventory: the SDK drops its cached reads and
+`gem.me.inventory.onChanged` fires, so a listener that re-reads shows the gift. The hint names no
+sender, item or amount; the re-read is what tells you. See
+[`inventory-and-catalogs.md`](inventory-and-catalogs.md#6-when-to-re-read) for the full rule.
+
+**On an older Arcade nothing is pushed.** The recipient sees the gift the next time their game
+re-reads its inventory, so re-read after any action that could have involved another player, and
+design so a few seconds of not-yet-seeing-it is harmless either way.
 
 ## `transfer_policy` is your game's rule, not the platform's
 

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": "23.0.0",
   "description": "postMessage bridge contract between gem-web and browser-playable games",
   "license": "UNLICENSED",
   "type": "module",