@indiegems/gem-web-sdk 21.1.1 → 23.0.0

package/docs/api/api-reference-function.md

@@ -1,6 +1,6 @@
 # The function surface — API reference
 
-Generated from `@indiegems/gem-web-sdk/function` v21.1.1, the version of the package this file ships in. Every symbol below carries an explicit anchor, its `anchor` in `reference.json` beside this file.
+Generated from `@indiegems/gem-web-sdk/function` v23.0.0, the version of the package this file ships in. Every symbol below carries an explicit anchor, its `anchor` in `reference.json` beside this file.
 
 `@indiegems/gem-web-sdk/function` exports exactly the symbols on this page and nothing else.
 
@@ -2039,8 +2039,9 @@ Throw away what is cached, so the next [InventoryApi.snapshot](#inventoryapi-sna
 asks.
 
 For when something you did not do changed the inventory — a purchase on
-another device, a grant from a server. The SDK already drops the cache
-itself after any change it made.
+another device, a grant from a server — and nothing told you. The SDK
+already drops the cache itself after any change it made, and on an
+Arcade's hint that this game's inventory changed on the server.
 
 <a id="inventoryapi-onchanged"></a>
 
@@ -2053,12 +2054,17 @@ onChanged(listener: () => void): () => void
 Run something whenever this inventory changes, and get back a function that
 stops listening.
 
-⚠️ LOCAL CHANGES ONLY — this fires for changes THIS game made through this
-SDK. It does NOT fire when an inventory changes anywhere else: another
-device, a game server, an admin tool, or a gift from another player. Do not
-build "keep the bag live" on it; use it to react to your own writes, and
-call [InventoryApi.refresh](#inventoryapi-refresh) when you have reason to think something
-else moved.
+Fires for every change THIS game made through this SDK, and — on an Arcade
+that relays it — for any change to this game's inventory on the server: a
+grant from your function or server, a purchase, a gift accepted, a support
+grant, another device. It is a cue to re-read, not a receipt: it carries
+nothing, so call [InventoryApi.snapshot](#inventoryapi-snapshot) for what changed. After your
+own function's grant, show the function's answer and let this redraw.
+
+An older Arcade sends no hint, and there it fires for your own writes
+only. Keep a fallback that does not depend on it: refresh on
+`visibilitychange` to `visible` and after any action that could involve
+another player. Do not poll.
 
 | Parameter | Type |
 | --- | --- |
@@ -5030,6 +5036,31 @@ readonly configVersion?: number
 On `template_not_on_channel`, when a config version is promoted to that
 channel: the version the template is missing from.
 
+<a id="playinviterequest"></a>
+
+## PlayInviteRequest
+
+```ts
+interface PlayInviteRequest
+```
+
+What `gem.friends.inviteToPlay` takes.
+
+<a id="playinviterequest-params"></a>
+
+## PlayInviteRequest.params
+
+```ts
+readonly params?: Readonly<Record<string, string>>
+```
+
+Your own launch parameters for what the Arcade's link and invites open —
+`{ room: joinCode }` for a room joined by code — exactly as they should
+reach your game, on `gem.share.request`'s rules: at most 16, keys a letter
+then up to 63 letters, digits, `_` or `-`, string values of at most 512
+characters. For this one opening, they replace what
+`gem.friends.setInviteParams` declared. Omit it to use that declaration.
+
 <a id="friendsapi"></a>
 
 ## FriendsApi
@@ -5144,6 +5175,95 @@ challengeButton.onclick = async () => {
 };
 ```
 
+<a id="friendsapi-invitetoplay"></a>
+
+## FriendsApi.inviteToPlay
+
+```ts
+inviteToPlay(request?: PlayInviteRequest): Promise<boolean>
+```
+
+Ask the Arcade to open ITS invite sheet, so the player can invite friends
+to come and play this game with them.
+
+The Arcade lists the player's friends in its own chrome and sends an
+invite only when the player presses Invite there. A friend who accepts is
+opened into this game by the Arcade, and their quick-join seats them in
+the player's room when there is a seat: your game makes no call for it,
+and reads them as a room member who shares the player's `groupId`. Your
+game names nobody and writes no text.
+
+An Arcade that does not offer the sheet answers `false` at once, and asks
+nothing. Hide the button on `gem.frame.parentSupports('playInvites')`
+rather than letting a player press one that cannot work.
+
+⚠️ **Call it ONLY from a player's press**, never on a timer or as a screen
+opens. The Arcade answers an ask with no press behind it `false`, and
+shows nothing.
+
+RESOLVES `true` when the Arcade opened its sheet, and `false` when it did
+not: outside the Arcade, without `playInvites`, with another sheet
+already open, without a press, or when no answer arrived. **That is all it
+says** — never whom the player invited, how many, or whether any invite
+was sent — so never gate a reward on it. Never rejects.
+
+Calls made while an ask is open share its answer.
+
+**The window's share link and its invites are one system.** Pass
+`params` — your own launch parameters, `{ room: joinCode }` for a room
+joined by code — and a friend who accepts and anyone who opens the link
+arrive with them, on `gem.share.request`'s rules. Omitted, the window uses
+what [FriendsApi.setInviteParams](#friendsapi-setinviteparams) declared. A param those rules
+refuse is said on the console and nothing is asked: the call resolves
+`false`.
+
+| Parameter | Type |
+| --- | --- |
+| `request` | `PlayInviteRequest` |
+
+```ts
+inviteButton.onclick = async () => {
+  const shown = await gem.friends.inviteToPlay({ params: { room: joinCode } });
+  if (!shown) showJoinCode(); // the Arcade's sheet did not open: your own fallback
+};
+```
+
+<a id="friendsapi-setinviteparams"></a>
+
+## FriendsApi.setInviteParams
+
+```ts
+setInviteParams(params: Readonly<Record<string, string>> | null): boolean
+```
+
+Say what the Arcade's Friends window opens when the PLAYER opens it from
+the Arcade's own menu over your game: your launch parameters, carried by
+its share link and its friend invites alike, on `gem.share.request`'s
+rules. Pass `null` to clear.
+
+Call it when the player enters a room joined by code —
+`setInviteParams({ room: joinCode })` — and `setInviteParams(null)` when
+they leave it, so the window never invites anyone into a room that is
+gone. The latest call stands until the next; the SDK holds it and says it
+again after a reconnect. An explicit `inviteToPlay({ params })` wins for
+that one opening. Nothing comes back, and nothing changes on screen.
+
+| Parameter | Type |
+| --- | --- |
+| `params` | `Readonly<Record<string, string>> \| null` |
+
+**Returns.** whether the declaration reached the Arcade now. `false` outside
+  the Arcade, without `playInvites`, before the bridge is up (it is sent on
+  connect) and for params the share rules refuse, which are said on the
+  console; the last declaration then stands.
+
+```ts
+// On entering a room joined by code:
+gem.friends.setInviteParams({ room: joinCode });
+// ...and on leaving it:
+gem.friends.setInviteParams(null);
+```
+
 <a id="friendsapi-inbox"></a>
 
 ## FriendsApi.inbox

package/docs/api/api-reference-game.md

@@ -1,6 +1,6 @@
 # The browser surface — API reference
 
-Generated from `@indiegems/gem-web-sdk/sdk` v21.1.1, the version of the package this file ships in. Every symbol below carries an explicit anchor, its `anchor` in `reference.json` beside this file.
+Generated from `@indiegems/gem-web-sdk/sdk` v23.0.0, the version of the package this file ships in. Every symbol below carries an explicit anchor, its `anchor` in `reference.json` beside this file.
 
 `@indiegems/gem-web-sdk/sdk` is the one import a game writes, wherever its code runs. `@indiegems/gem-web-sdk/game` exports exactly the symbols on this page and nothing else, for a build that wants only this half.
 
@@ -907,8 +907,9 @@ Throw away what is cached, so the next [InventoryApi.snapshot](#inventoryapi-sna
 asks.
 
 For when something you did not do changed the inventory — a purchase on
-another device, a grant from a server. The SDK already drops the cache
-itself after any change it made.
+another device, a grant from a server — and nothing told you. The SDK
+already drops the cache itself after any change it made, and on an
+Arcade's hint that this game's inventory changed on the server.
 
 <a id="inventoryapi-onchanged"></a>
 
@@ -921,12 +922,17 @@ onChanged(listener: () => void): () => void
 Run something whenever this inventory changes, and get back a function that
 stops listening.
 
-⚠️ LOCAL CHANGES ONLY — this fires for changes THIS game made through this
-SDK. It does NOT fire when an inventory changes anywhere else: another
-device, a game server, an admin tool, or a gift from another player. Do not
-build "keep the bag live" on it; use it to react to your own writes, and
-call [InventoryApi.refresh](#inventoryapi-refresh) when you have reason to think something
-else moved.
+Fires for every change THIS game made through this SDK, and — on an Arcade
+that relays it — for any change to this game's inventory on the server: a
+grant from your function or server, a purchase, a gift accepted, a support
+grant, another device. It is a cue to re-read, not a receipt: it carries
+nothing, so call [InventoryApi.snapshot](#inventoryapi-snapshot) for what changed. After your
+own function's grant, show the function's answer and let this redraw.
+
+An older Arcade sends no hint, and there it fires for your own writes
+only. Keep a fallback that does not depend on it: refresh on
+`visibilitychange` to `visible` and after any action that could involve
+another player. Do not poll.
 
 | Parameter | Type |
 | --- | --- |
@@ -7180,6 +7186,24 @@ The platform currency's slug, as `gem.platform.currencies.get()` lists it —
 `GEMS` or `ARCADE_TICKETS`. It decides what flies — gems or coins — and
 which of the player's totals the payout moves.
 
+<a id="rewardcue-cueid"></a>
+
+## RewardCue.cueId
+
+```ts
+cueId?: string
+```
+
+Your id for this award, so the arcade flies it once. Make one per award
+with `crypto.randomUUID()` and pass the same one as the `cueId` of the
+`gem.functions.invoke` that pays it; then the cue and the payout may reach
+the arcade in either order. 1 to 64 letters, digits, `_` or `-`; anything
+else is left out (with a console warning, from `gem.cueReward`), and the
+cue still goes.
+
+For animation only: it moves no balance. Leave it out and the arcade pairs
+the cue with the payout by currency and timing.
+
 <a id="rewardcue-expected"></a>
 
 ## RewardCue.expected
@@ -7238,6 +7262,18 @@ A corner of your frame, for `gem.setGemCorner`: where you would like the
 arcade's Gem button to sit. `'top-left'` is where it sits unless you ask.
 Physical corners: `'top-left'` is the top-left in every language.
 
+<a id="rewardpresentation"></a>
+
+## RewardPresentation
+
+```ts
+type RewardPresentation = "arcade" | "game"
+```
+
+Who decides when your platform-currency payouts are shown landing, for
+`gem.setRewardPresentation`: `'arcade'`, the default, or `'game'`, when each
+payout waits for your `gem.cueReward`.
+
 <a id="menustyle"></a>
 
 ## MenuStyle
@@ -7646,6 +7682,29 @@ its control.
   up, for an arcade that cannot move its control, for a value that is not
   one of the four corners, and past this frame's own limit.
 
+<a id="gemframe-setrewardpresentation"></a>
+
+## GemFrame.setRewardPresentation
+
+```ts
+setRewardPresentation(mode: RewardPresentation): boolean
+```
+
+Tell the arcade who decides when your platform-currency payouts are shown
+landing: the whole answer each time, the latest one winning.
+
+Prefer `gem.setRewardPresentation`, which holds the answer across a
+reconnect. This one sends only while connected, and only to an arcade
+that can hold a payout for your cue.
+
+| Parameter | Type |
+| --- | --- |
+| `mode` | `RewardPresentation` |
+
+**Returns.** whether the message left the frame: `false` before the bridge is
+  up, for an arcade that cannot hold a payout, for a value that is neither
+  `'arcade'` nor `'game'`, and past this frame's own limit.
+
 <a id="gemframe-setmenustyle"></a>
 
 ## GemFrame.setMenuStyle
@@ -8475,6 +8534,31 @@ readonly configVersion?: number
 On `template_not_on_channel`, when a config version is promoted to that
 channel: the version the template is missing from.
 
+<a id="playinviterequest"></a>
+
+## PlayInviteRequest
+
+```ts
+interface PlayInviteRequest
+```
+
+What `gem.friends.inviteToPlay` takes.
+
+<a id="playinviterequest-params"></a>
+
+## PlayInviteRequest.params
+
+```ts
+readonly params?: Readonly<Record<string, string>>
+```
+
+Your own launch parameters for what the Arcade's link and invites open —
+`{ room: joinCode }` for a room joined by code — exactly as they should
+reach your game, on `gem.share.request`'s rules: at most 16, keys a letter
+then up to 63 letters, digits, `_` or `-`, string values of at most 512
+characters. For this one opening, they replace what
+`gem.friends.setInviteParams` declared. Omit it to use that declaration.
+
 <a id="friendsapi"></a>
 
 ## FriendsApi
@@ -8589,6 +8673,95 @@ challengeButton.onclick = async () => {
 };
 ```
 
+<a id="friendsapi-invitetoplay"></a>
+
+## FriendsApi.inviteToPlay
+
+```ts
+inviteToPlay(request?: PlayInviteRequest): Promise<boolean>
+```
+
+Ask the Arcade to open ITS invite sheet, so the player can invite friends
+to come and play this game with them.
+
+The Arcade lists the player's friends in its own chrome and sends an
+invite only when the player presses Invite there. A friend who accepts is
+opened into this game by the Arcade, and their quick-join seats them in
+the player's room when there is a seat: your game makes no call for it,
+and reads them as a room member who shares the player's `groupId`. Your
+game names nobody and writes no text.
+
+An Arcade that does not offer the sheet answers `false` at once, and asks
+nothing. Hide the button on `gem.frame.parentSupports('playInvites')`
+rather than letting a player press one that cannot work.
+
+⚠️ **Call it ONLY from a player's press**, never on a timer or as a screen
+opens. The Arcade answers an ask with no press behind it `false`, and
+shows nothing.
+
+RESOLVES `true` when the Arcade opened its sheet, and `false` when it did
+not: outside the Arcade, without `playInvites`, with another sheet
+already open, without a press, or when no answer arrived. **That is all it
+says** — never whom the player invited, how many, or whether any invite
+was sent — so never gate a reward on it. Never rejects.
+
+Calls made while an ask is open share its answer.
+
+**The window's share link and its invites are one system.** Pass
+`params` — your own launch parameters, `{ room: joinCode }` for a room
+joined by code — and a friend who accepts and anyone who opens the link
+arrive with them, on `gem.share.request`'s rules. Omitted, the window uses
+what [FriendsApi.setInviteParams](#friendsapi-setinviteparams) declared. A param those rules
+refuse is said on the console and nothing is asked: the call resolves
+`false`.
+
+| Parameter | Type |
+| --- | --- |
+| `request` | `PlayInviteRequest` |
+
+```ts
+inviteButton.onclick = async () => {
+  const shown = await gem.friends.inviteToPlay({ params: { room: joinCode } });
+  if (!shown) showJoinCode(); // the Arcade's sheet did not open: your own fallback
+};
+```
+
+<a id="friendsapi-setinviteparams"></a>
+
+## FriendsApi.setInviteParams
+
+```ts
+setInviteParams(params: Readonly<Record<string, string>> | null): boolean
+```
+
+Say what the Arcade's Friends window opens when the PLAYER opens it from
+the Arcade's own menu over your game: your launch parameters, carried by
+its share link and its friend invites alike, on `gem.share.request`'s
+rules. Pass `null` to clear.
+
+Call it when the player enters a room joined by code —
+`setInviteParams({ room: joinCode })` — and `setInviteParams(null)` when
+they leave it, so the window never invites anyone into a room that is
+gone. The latest call stands until the next; the SDK holds it and says it
+again after a reconnect. An explicit `inviteToPlay({ params })` wins for
+that one opening. Nothing comes back, and nothing changes on screen.
+
+| Parameter | Type |
+| --- | --- |
+| `params` | `Readonly<Record<string, string>> \| null` |
+
+**Returns.** whether the declaration reached the Arcade now. `false` outside
+  the Arcade, without `playInvites`, before the bridge is up (it is sent on
+  connect) and for params the share rules refuse, which are said on the
+  console; the last declaration then stands.
+
+```ts
+// On entering a room joined by code:
+gem.friends.setInviteParams({ room: joinCode });
+// ...and on leaving it:
+gem.friends.setInviteParams(null);
+```
+
 <a id="friendsapi-inbox"></a>
 
 ## FriendsApi.inbox
@@ -8726,6 +8899,24 @@ readonly signal?: AbortSignal
 
 Cancel the call. A call already cancelled sends nothing.
 
+<a id="functioninvokeoptions-cueid"></a>
+
+## FunctionInvokeOptions.cueId
+
+```ts
+readonly cueId?: string
+```
+
+The id of the reward this call pays, so the Gem Arcade flies it once:
+the same `cueId` you pass to `gem.cueReward` for it, one
+`crypto.randomUUID()` per award. The platform hands it back on the payout
+it shows the arcade, and nowhere else: your function never sees it, and
+neither the answer nor a receipt carries it.
+
+1 to 64 letters, digits, `_` or `-`. Anything else is left out with a
+console warning, and the call still goes: it decides an animation, never
+whether the call pays.
+
 <a id="functionresult"></a>
 
 ## FunctionResult
@@ -9004,11 +9195,26 @@ The call is made once. It is never repeated for you, because your function
 may have granted or written something: see [GemFunctionError.retryable](#gemfunctionerror-retryable)
 for whether repeating it could help.
 
+The answer is the receipt: when this resolves, what your function says it
+granted has been written. A game shows it at once and re-reads the
+inventory in the background (`gem.me.inventory.refresh()`, then
+`snapshot()`, or on `gem.me.inventory.onChanged`); never hold the player on
+a loop that re-reads until the grant shows.
+
 ```js
 const result = await gem.functions.invoke({ v: 2, runId, finishMs });
 const { accepted, why } = result.json();
 ```
 
+When the call pays a reward the player sees, pass the reward's `cueId`, the
+same one the page gives `gem.cueReward` for it, and the Gem Arcade flies it
+once:
+
+```js
+const cueId = crypto.randomUUID(); // one per award, also passed to the cue
+await gem.functions.invoke({ claim: 'daily' }, { cueId });
+```
+
 | Parameter | Type | Description |
 | --- | --- | --- |
 | `input` | `unknown` | Bytes, or a value to send as JSON. |
@@ -11935,10 +12141,12 @@ readonly friends: FriendsApi
 ```
 
 The signed-in player's accepted friends — display identity only,
-read-only, paginated — and the one ask that reaches past them:
+read-only, paginated — and the asks that reach past them:
 [FriendsApi.challenge](#friendsapi-challenge), which asks the Arcade to send a friend a
-challenge after the player confirms it in the Arcade's own sheet. The
-receiving side reads the challenges this player holds in this game:
+challenge after the player confirms it in the Arcade's own sheet, and
+[FriendsApi.inviteToPlay](#friendsapi-invitetoplay), which asks the Arcade to open its own
+invite-to-play sheet. The receiving side reads the challenges this player
+holds in this game:
 [FriendsApi.launchedChallenge](#friendsapi-launchedchallenge) for the one this frame was launched
 with, [FriendsApi.inbox](#friendsapi-inbox) for all of them, and
 [FriendsApi.markAnswered](#friendsapi-markanswered) once one has been played.
@@ -12231,6 +12439,30 @@ gem.cueReward({
 });
 ```
 
+**When your function pays it, give both calls one `cueId`.** Make one per
+award with `crypto.randomUUID()`, pass it here and to the
+`gem.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();
+const result = await gem.functions.invoke({ claim: 'daily' }, { cueId });
+gem.cueReward({ currencySlug: 'GEMS', expected: 15, origin, cueId });
+```
+
+A payout that is not a function call (your own game server's) has no id
+to share: cue it with none, and the arcade pairs the two by currency and
+timing.
+
+**When is up to the arcade unless you say otherwise.** By default the cue
+is paired with its payout only within about half a second either side of
+your server's write; a payout with no cue by then flies from the middle of
+your frame, and a cue that comes later adds nothing. To show the payout at
+a later moment of your own, such as a Claim tap on the win card or the
+screen the player returns to, call `gem.setRewardPresentation('game')` once
+at boot: each payout then waits for your cue.
+
 **This is the platform-currency animation, and the only one.** The display
 of every platform currency — Gems and Coins alike — belongs to the
 arcade: a game draws no flight or celebration of its own for one and keeps
@@ -12252,6 +12484,53 @@ landed — which it does on every channel, dev and test included.
   before the bridge is up, or under an embedder with no wallet. On `false`
   the game does nothing: it draws no animation of its own in its place.
 
+<a id="gem-setrewardpresentation"></a>
+
+## Gem.setRewardPresentation
+
+```ts
+setRewardPresentation(mode: RewardPresentation): boolean
+```
+
+Say who decides when your platform-currency payouts are shown landing: the
+arcade (`'arcade'`, the default) or your game (`'game'`). Call it once at
+boot when your reward moment comes after your server pays, such as a Claim
+tap on the win card or the next screen the player sees.
+
+```js
+gem.setRewardPresentation('game'); // at boot
+// ...the server pays when the board is won; later, on Claim:
+gem.cueReward({ currencySlug: 'ARCADE_TICKETS', expected: 20, origin });
+```
+
+**With `'game'`, your cue supplies the moment and the payout supplies the
+number.** The arcade holds each payout's presentation for its currency
+rather than flying it from the middle of your frame. Each `cueReward`
+releases up to its `expected` of what is held (all of it when it names no
+amount) and flies it from its `origin`, and the arcade's wallet chip over
+your game counts up as the marks land. A cue that finds nothing held waits
+for the next payout of its currency, so cue before or after the write, in
+either order.
+
+**It delays the show, never the money.** What is paid, when, and every
+ceiling are unchanged, and the arcade's menu and every purchase see the
+player's true total at once. A payout no cue releases within five minutes
+lands quietly, with no flight, so a game can never hide one.
+
+**It is screen state, not a toggle**, held before the bridge is up and
+re-sent after every reconnect. Switching back to `'arcade'` lands whatever
+is held. A value that is neither is ignored, with a warning on the console,
+and changes nothing.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `mode` | `RewardPresentation` | `'game'` to present each payout on your cue, `'arcade'` for the default. |
+
+**Returns.** `true` when the arcade was told now; `false` before the bridge is
+  up (the answer is held and sent when it connects), under an embedder
+  that presents every payout its own way, and for a value that is neither.
+  On `false` from an embedder, keep cueing as usual: nothing else changes.
+
 <a id="gem-setwalletvisible"></a>
 
 ## Gem.setWalletVisible
@@ -19951,7 +20230,7 @@ readonly playWith: PlayWithOutcome | null
 
 What the last [RoomManager.quickJoin](#roommanager-quickjoin) did when the Arcade opened
 your game to play with someone — a friend whose Join the player pressed,
-or their party's leader. Read-only.
+a friend's invite, or their party's leader. Read-only.
 
 - `'joined'` — the player was seated in that person's room, as a member
   sharing their `groupId`.

package/docs/api/api-reference-server.md

@@ -1,6 +1,6 @@
 # The server surface — API reference
 
-Generated from `@indiegems/gem-web-sdk/sdk` v21.1.1, the version of the package this file ships in. Every symbol below carries an explicit anchor, its `anchor` in `reference.json` beside this file.
+Generated from `@indiegems/gem-web-sdk/sdk` v23.0.0, the version of the package this file ships in. Every symbol below carries an explicit anchor, its `anchor` in `reference.json` beside this file.
 
 `@indiegems/gem-web-sdk/sdk` is the one import a game writes, wherever its code runs. `@indiegems/gem-web-sdk/server` exports exactly the symbols on this page and nothing else, for a build that wants only this half.
 
@@ -1489,6 +1489,24 @@ readonly signal?: AbortSignal
 
 Cancel the call. A call already cancelled sends nothing.
 
+<a id="functioninvokeoptions-cueid"></a>
+
+## FunctionInvokeOptions.cueId
+
+```ts
+readonly cueId?: string
+```
+
+The id of the reward this call pays, so the Gem Arcade flies it once:
+the same `cueId` you pass to `gem.cueReward` for it, one
+`crypto.randomUUID()` per award. The platform hands it back on the payout
+it shows the arcade, and nowhere else: your function never sees it, and
+neither the answer nor a receipt carries it.
+
+1 to 64 letters, digits, `_` or `-`. Anything else is left out with a
+console warning, and the call still goes: it decides an animation, never
+whether the call pays.
+
 <a id="functionresult"></a>
 
 ## FunctionResult
@@ -1767,11 +1785,26 @@ The call is made once. It is never repeated for you, because your function
 may have granted or written something: see [GemFunctionError.retryable](#gemfunctionerror-retryable)
 for whether repeating it could help.
 
+The answer is the receipt: when this resolves, what your function says it
+granted has been written. A game shows it at once and re-reads the
+inventory in the background (`gem.me.inventory.refresh()`, then
+`snapshot()`, or on `gem.me.inventory.onChanged`); never hold the player on
+a loop that re-reads until the grant shows.
+
 ```js
 const result = await gem.functions.invoke({ v: 2, runId, finishMs });
 const { accepted, why } = result.json();
 ```
 
+When the call pays a reward the player sees, pass the reward's `cueId`, the
+same one the page gives `gem.cueReward` for it, and the Gem Arcade flies it
+once:
+
+```js
+const cueId = crypto.randomUUID(); // one per award, also passed to the cue
+await gem.functions.invoke({ claim: 'daily' }, { cueId });
+```
+
 | Parameter | Type | Description |
 | --- | --- | --- |
 | `input` | `unknown` | Bytes, or a value to send as JSON. |