@indiegems/gem-web-sdk 21.1.1 → 23.0.0

package/docs/api/reference.json

@@ -2,7 +2,7 @@
   "schema_version": 2,
   "source": {
     "repo": "IndieGems/gem-web-sdk",
-    "version": "21.1.1"
+    "version": "23.0.0"
   },
   "entries": [
     {
@@ -1155,7 +1155,7 @@
           "group": "saves",
           "signature": "refresh(): void",
           "documented": true,
-          "summary": "Throw away what is cached, so the next [InventoryApi.snapshot](api-reference-game.md#inventoryapi-snapshot) really\nasks.\n\nFor when something you did not do changed the inventory — a purchase on\nanother device, a grant from a server. The SDK already drops the cache\nitself after any change it made.",
+          "summary": "Throw away what is cached, so the next [InventoryApi.snapshot](api-reference-game.md#inventoryapi-snapshot) really\nasks.\n\nFor when something you did not do changed the inventory — a purchase on\nanother device, a grant from a server — and nothing told you. The SDK\nalready drops the cache itself after any change it made, and on an\nArcade's hint that this game's inventory changed on the server.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -1171,7 +1171,7 @@
           "group": "saves",
           "signature": "onChanged(listener: () => void): () => void",
           "documented": true,
-          "summary": "Run something whenever this inventory changes, and get back a function that\nstops listening.\n\n⚠️ LOCAL CHANGES ONLY — this fires for changes THIS game made through this\nSDK. It does NOT fire when an inventory changes anywhere else: another\ndevice, a game server, an admin tool, or a gift from another player. Do not\nbuild \"keep the bag live\" on it; use it to react to your own writes, and\ncall [InventoryApi.refresh](api-reference-game.md#inventoryapi-refresh) when you have reason to think something\nelse moved.",
+          "summary": "Run something whenever this inventory changes, and get back a function that\nstops listening.\n\nFires for every change THIS game made through this SDK, and — on an Arcade\nthat relays it — for any change to this game's inventory on the server: a\ngrant from your function or server, a purchase, a gift accepted, a support\ngrant, another device. It is a cue to re-read, not a receipt: it carries\nnothing, so call [InventoryApi.snapshot](api-reference-game.md#inventoryapi-snapshot) for what changed. After your\nown function's grant, show the function's answer and let this redraw.\n\nAn older Arcade sends no hint, and there it fires for your own writes\nonly. Keep a fallback that does not depend on it: refresh on\n`visibilitychange` to `visible` and after any action that could involve\nanother player. Do not poll.",
           "deprecated": null,
           "params": [
             {
@@ -8556,6 +8556,22 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "RewardCue.cueId",
+          "name": "cueId",
+          "anchor": "rewardcue-cueid",
+          "group": "platform",
+          "signature": "cueId?: string",
+          "documented": true,
+          "summary": "Your id for this award, so the arcade flies it once. Make one per award\nwith `crypto.randomUUID()` and pass the same one as the `cueId` of the\n`gem.functions.invoke` that pays it; then the cue and the payout may reach\nthe arcade in either order. 1 to 64 letters, digits, `_` or `-`; anything\nelse is left out (with a console warning, from `gem.cueReward`), and the\ncue still goes.\n\nFor animation only: it moves no balance. Leave it out and the arcade pairs\nthe cue with the payout by currency and timing.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "RewardCue.expected",
           "name": "expected",
@@ -8636,6 +8652,22 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "RewardPresentation",
+          "name": "RewardPresentation",
+          "anchor": "rewardpresentation",
+          "group": "platform",
+          "signature": "type RewardPresentation = \"arcade\" | \"game\"",
+          "documented": true,
+          "summary": "Who decides when your platform-currency payouts are shown landing, for\n`gem.setRewardPresentation`: `'arcade'`, the default, or `'game'`, when each\npayout waits for your `gem.cueReward`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "MenuStyle",
           "name": "MenuStyle",
@@ -9064,6 +9096,29 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "GemFrame.setRewardPresentation",
+          "name": "setRewardPresentation",
+          "anchor": "gemframe-setrewardpresentation",
+          "group": "frame",
+          "signature": "setRewardPresentation(mode: RewardPresentation): boolean",
+          "documented": true,
+          "summary": "Tell the arcade who decides when your platform-currency payouts are shown\nlanding: the whole answer each time, the latest one winning.\n\nPrefer `gem.setRewardPresentation`, which holds the answer across a\nreconnect. This one sends only while connected, and only to an arcade\nthat can hold a payout for your cue.",
+          "deprecated": null,
+          "params": [
+            {
+              "name": "mode",
+              "type": "RewardPresentation",
+              "optional": false,
+              "summary": null
+            }
+          ],
+          "returns": "whether the message left the frame: `false` before the bridge is\n  up, for an arcade that cannot hold a payout, for a value that is neither\n  `'arcade'` nor `'game'`, and past this frame's own limit.",
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "GemFrame.setMenuStyle",
           "name": "setMenuStyle",
@@ -10040,6 +10095,38 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "PlayInviteRequest",
+          "name": "PlayInviteRequest",
+          "anchor": "playinviterequest",
+          "group": "friends",
+          "signature": "interface PlayInviteRequest",
+          "documented": true,
+          "summary": "What `gem.friends.inviteToPlay` takes.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "PlayInviteRequest.params",
+          "name": "params",
+          "anchor": "playinviterequest-params",
+          "group": "friends",
+          "signature": "readonly params?: Readonly<Record<string, string>>",
+          "documented": true,
+          "summary": "Your own launch parameters for what the Arcade's link and invites open —\n`{ room: joinCode }` for a room joined by code — exactly as they should\nreach your game, on `gem.share.request`'s rules: at most 16, keys a letter\nthen up to 63 letters, digits, `_` or `-`, string values of at most 512\ncharacters. For this one opening, they replace what\n`gem.friends.setInviteParams` declared. Omit it to use that declaration.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "FriendsApi",
           "name": "FriendsApi",
@@ -10102,6 +10189,52 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "FriendsApi.inviteToPlay",
+          "name": "inviteToPlay",
+          "anchor": "friendsapi-invitetoplay",
+          "group": "friends",
+          "signature": "inviteToPlay(request?: PlayInviteRequest): Promise<boolean>",
+          "documented": true,
+          "summary": "Ask the Arcade to open ITS invite sheet, so the player can invite friends\nto come and play this game with them.\n\nThe Arcade lists the player's friends in its own chrome and sends an\ninvite only when the player presses Invite there. A friend who accepts is\nopened into this game by the Arcade, and their quick-join seats them in\nthe player's room when there is a seat: your game makes no call for it,\nand reads them as a room member who shares the player's `groupId`. Your\ngame names nobody and writes no text.\n\nAn Arcade that does not offer the sheet answers `false` at once, and asks\nnothing. Hide the button on `gem.frame.parentSupports('playInvites')`\nrather than letting a player press one that cannot work.\n\n⚠️ **Call it ONLY from a player's press**, never on a timer or as a screen\nopens. The Arcade answers an ask with no press behind it `false`, and\nshows nothing.\n\nRESOLVES `true` when the Arcade opened its sheet, and `false` when it did\nnot: outside the Arcade, without `playInvites`, with another sheet\nalready open, without a press, or when no answer arrived. **That is all it\nsays** — never whom the player invited, how many, or whether any invite\nwas sent — so never gate a reward on it. Never rejects.\n\nCalls made while an ask is open share its answer.\n\n**The window's share link and its invites are one system.** Pass\n`params` — your own launch parameters, `{ room: joinCode }` for a room\njoined by code — and a friend who accepts and anyone who opens the link\narrive with them, on `gem.share.request`'s rules. Omitted, the window uses\nwhat [FriendsApi.setInviteParams](api-reference-game.md#friendsapi-setinviteparams) declared. A param those rules\nrefuse is said on the console and nothing is asked: the call resolves\n`false`.",
+          "deprecated": null,
+          "params": [
+            {
+              "name": "request",
+              "type": "PlayInviteRequest",
+              "optional": true,
+              "summary": null
+            }
+          ],
+          "returns": null,
+          "throws": null,
+          "example": "```ts\ninviteButton.onclick = async () => {\n  const shown = await gem.friends.inviteToPlay({ params: { room: joinCode } });\n  if (!shown) showJoinCode(); // the Arcade's sheet did not open: your own fallback\n};\n```",
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "FriendsApi.setInviteParams",
+          "name": "setInviteParams",
+          "anchor": "friendsapi-setinviteparams",
+          "group": "friends",
+          "signature": "setInviteParams(params: Readonly<Record<string, string>> | null): boolean",
+          "documented": true,
+          "summary": "Say what the Arcade's Friends window opens when the PLAYER opens it from\nthe Arcade's own menu over your game: your launch parameters, carried by\nits share link and its friend invites alike, on `gem.share.request`'s\nrules. Pass `null` to clear.\n\nCall it when the player enters a room joined by code —\n`setInviteParams({ room: joinCode })` — and `setInviteParams(null)` when\nthey leave it, so the window never invites anyone into a room that is\ngone. The latest call stands until the next; the SDK holds it and says it\nagain after a reconnect. An explicit `inviteToPlay({ params })` wins for\nthat one opening. Nothing comes back, and nothing changes on screen.",
+          "deprecated": null,
+          "params": [
+            {
+              "name": "params",
+              "type": "Readonly<Record<string, string>> | null",
+              "optional": false,
+              "summary": null
+            }
+          ],
+          "returns": "whether the declaration reached the Arcade now. `false` outside\n  the Arcade, without `playInvites`, before the bridge is up (it is sent on\n  connect) and for params the share rules refuse, which are said on the\n  console; the last declaration then stands.",
+          "throws": null,
+          "example": "```ts\n// On entering a room joined by code:\ngem.friends.setInviteParams({ room: joinCode });\n// ...and on leaving it:\ngem.friends.setInviteParams(null);\n```",
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "FriendsApi.inbox",
           "name": "inbox",
@@ -10203,6 +10336,22 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "FunctionInvokeOptions.cueId",
+          "name": "cueId",
+          "anchor": "functioninvokeoptions-cueid",
+          "group": "functions",
+          "signature": "readonly cueId?: string",
+          "documented": true,
+          "summary": "The id of the reward this call pays, so the Gem Arcade flies it once:\nthe same `cueId` you pass to `gem.cueReward` for it, one\n`crypto.randomUUID()` per award. The platform hands it back on the payout\nit shows the arcade, and nowhere else: your function never sees it, and\nneither the answer nor a receipt carries it.\n\n1 to 64 letters, digits, `_` or `-`. Anything else is left out with a\nconsole warning, and the call still goes: it decides an animation, never\nwhether the call pays.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "FunctionResult",
           "name": "FunctionResult",
@@ -10482,7 +10631,7 @@
           "group": "functions",
           "signature": "invoke(input: unknown, options?: FunctionInvokeOptions): Promise<FunctionResult>",
           "documented": true,
-          "summary": "Call the function published on your channel, and get its answer.\n\nThe input is sent as your function's `input`, byte for byte. Pass a\n`Uint8Array`, an `ArrayBuffer` or another typed array to send bytes as they\nare. Pass anything else and it is sent as its JSON text — a string too, so\n`'ping'` arrives as `\"ping\"` with its quotes.\n\nThe call is made once. It is never repeated for you, because your function\nmay have granted or written something: see [GemFunctionError.retryable](api-reference-game.md#gemfunctionerror-retryable)\nfor whether repeating it could help.\n\n```js\nconst result = await gem.functions.invoke({ v: 2, runId, finishMs });\nconst { accepted, why } = result.json();\n```",
+          "summary": "Call the function published on your channel, and get its answer.\n\nThe input is sent as your function's `input`, byte for byte. Pass a\n`Uint8Array`, an `ArrayBuffer` or another typed array to send bytes as they\nare. Pass anything else and it is sent as its JSON text — a string too, so\n`'ping'` arrives as `\"ping\"` with its quotes.\n\nThe call is made once. It is never repeated for you, because your function\nmay have granted or written something: see [GemFunctionError.retryable](api-reference-game.md#gemfunctionerror-retryable)\nfor whether repeating it could help.\n\nThe answer is the receipt: when this resolves, what your function says it\ngranted has been written. A game shows it at once and re-reads the\ninventory in the background (`gem.me.inventory.refresh()`, then\n`snapshot()`, or on `gem.me.inventory.onChanged`); never hold the player on\na loop that re-reads until the grant shows.\n\n```js\nconst result = await gem.functions.invoke({ v: 2, runId, finishMs });\nconst { accepted, why } = result.json();\n```\n\nWhen the call pays a reward the player sees, pass the reward's `cueId`, the\nsame one the page gives `gem.cueReward` for it, and the Gem Arcade flies it\nonce:\n\n```js\nconst cueId = crypto.randomUUID(); // one per award, also passed to the cue\nawait gem.functions.invoke({ claim: 'daily' }, { cueId });\n```",
           "deprecated": null,
           "params": [
             {
@@ -13483,7 +13632,7 @@
           "group": "start",
           "signature": "readonly friends: FriendsApi",
           "documented": true,
-          "summary": "The signed-in player's accepted friends — display identity only,\nread-only, paginated — and the one ask that reaches past them:\n[FriendsApi.challenge](api-reference-game.md#friendsapi-challenge), which asks the Arcade to send a friend a\nchallenge after the player confirms it in the Arcade's own sheet. The\nreceiving side reads the challenges this player holds in this game:\n[FriendsApi.launchedChallenge](api-reference-game.md#friendsapi-launchedchallenge) for the one this frame was launched\nwith, [FriendsApi.inbox](api-reference-game.md#friendsapi-inbox) for all of them, and\n[FriendsApi.markAnswered](api-reference-game.md#friendsapi-markanswered) once one has been played.\n\nEvery accepted friend appears whether or not they have played this game;\nan invite-a-friend flow needs exactly the ones who have not. The graph\nitself — requests, accepts, blocks, presence — stays on the Arcade: there\nis nothing here to mutate but a challenge's own answered mark, and nothing\nthat says who is online.\n\nA player surface only. In a context with no player — a game server — the\nplatform refuses the read; a server has no friend list.",
+          "summary": "The signed-in player's accepted friends — display identity only,\nread-only, paginated — and the asks that reach past them:\n[FriendsApi.challenge](api-reference-game.md#friendsapi-challenge), which asks the Arcade to send a friend a\nchallenge after the player confirms it in the Arcade's own sheet, and\n[FriendsApi.inviteToPlay](api-reference-game.md#friendsapi-invitetoplay), which asks the Arcade to open its own\ninvite-to-play sheet. The receiving side reads the challenges this player\nholds in this game:\n[FriendsApi.launchedChallenge](api-reference-game.md#friendsapi-launchedchallenge) for the one this frame was launched\nwith, [FriendsApi.inbox](api-reference-game.md#friendsapi-inbox) for all of them, and\n[FriendsApi.markAnswered](api-reference-game.md#friendsapi-markanswered) once one has been played.\n\nEvery accepted friend appears whether or not they have played this game;\nan invite-a-friend flow needs exactly the ones who have not. The graph\nitself — requests, accepts, blocks, presence — stays on the Arcade: there\nis nothing here to mutate but a challenge's own answered mark, and nothing\nthat says who is online.\n\nA player surface only. In a context with no player — a game server — the\nplatform refuses the read; a server has no friend list.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -13703,7 +13852,7 @@
           "group": "start",
           "signature": "cueReward(cue: RewardCue): boolean",
           "documented": true,
-          "summary": "Tell the arcade a platform-currency reward is on its way, so it **shows it\nlanding**: in the Gem Arcade the currency flies from `origin` into the Gem\nbutton, wherever on your frame it sits, which pops as each mark lands, and\nthe player's total moves once the platform confirms the grant. The Gem\nArcade draws no wallet over your game unless you ask (`setWalletVisible`):\nthe player sees their Gems and Coins in the Gem menu. A payout you do not\ncue still flies, from the middle of your frame, so cue the ones the player\nearns on screen.\n\nCall it the moment your game decides to award — when your server has moved\n(or is about to move) the progression mapped onto a platform currency —\nand pass the centre of that currency's icon (or hero) on your screen, so\nthe flight starts from the mark the player is looking at:\n\n```js\nconst { x, y, width, height } = rewardGem.getBoundingClientRect(); // the gem's own box\ngem.cueReward({\n  currencySlug: 'GEMS', // or 'ARCADE_TICKETS', from the coin\n  expected: 15,\n  origin: { x: x + width / 2, y: y + height / 2 },\n});\n```\n\n**This is the platform-currency animation, and the only one.** The display\nof every platform currency — Gems and Coins alike — belongs to the\narcade: a game draws no flight or celebration of its own for one and keeps\nno counter of one. **If this returns `false`, do nothing** — there is no\nfallback celebration.\n\n**The arcade never takes your word for the amount.** What lands, and the\nplayer's new total, come from the platform itself; `expected` is drawn as\nprovisional, and a cue the platform never confirms fades on its own — a\ngrant clamped to zero, say, or one the receipt reports `suppressed`. So\nthe cue can only ever make the wallet move for a reward that really\nlanded — which it does on every channel, dev and test included.",
+          "summary": "Tell the arcade a platform-currency reward is on its way, so it **shows it\nlanding**: in the Gem Arcade the currency flies from `origin` into the Gem\nbutton, wherever on your frame it sits, which pops as each mark lands, and\nthe player's total moves once the platform confirms the grant. The Gem\nArcade draws no wallet over your game unless you ask (`setWalletVisible`):\nthe player sees their Gems and Coins in the Gem menu. A payout you do not\ncue still flies, from the middle of your frame, so cue the ones the player\nearns on screen.\n\nCall it the moment your game decides to award — when your server has moved\n(or is about to move) the progression mapped onto a platform currency —\nand pass the centre of that currency's icon (or hero) on your screen, so\nthe flight starts from the mark the player is looking at:\n\n```js\nconst { x, y, width, height } = rewardGem.getBoundingClientRect(); // the gem's own box\ngem.cueReward({\n  currencySlug: 'GEMS', // or 'ARCADE_TICKETS', from the coin\n  expected: 15,\n  origin: { x: x + width / 2, y: y + height / 2 },\n});\n```\n\n**When your function pays it, give both calls one `cueId`.** Make one per\naward with `crypto.randomUUID()`, pass it here and to the\n`gem.functions.invoke` that pays, and the arcade flies that reward once,\nwhichever reaches it first — so you may cue before the call or after it\nreturns:\n\n```js\nconst cueId = crypto.randomUUID();\nconst result = await gem.functions.invoke({ claim: 'daily' }, { cueId });\ngem.cueReward({ currencySlug: 'GEMS', expected: 15, origin, cueId });\n```\n\nA payout that is not a function call (your own game server's) has no id\nto share: cue it with none, and the arcade pairs the two by currency and\ntiming.\n\n**When is up to the arcade unless you say otherwise.** By default the cue\nis paired with its payout only within about half a second either side of\nyour server's write; a payout with no cue by then flies from the middle of\nyour frame, and a cue that comes later adds nothing. To show the payout at\na later moment of your own, such as a Claim tap on the win card or the\nscreen the player returns to, call `gem.setRewardPresentation('game')` once\nat boot: each payout then waits for your cue.\n\n**This is the platform-currency animation, and the only one.** The display\nof every platform currency — Gems and Coins alike — belongs to the\narcade: a game draws no flight or celebration of its own for one and keeps\nno counter of one. **If this returns `false`, do nothing** — there is no\nfallback celebration.\n\n**The arcade never takes your word for the amount.** What lands, and the\nplayer's new total, come from the platform itself; `expected` is drawn as\nprovisional, and a cue the platform never confirms fades on its own — a\ngrant clamped to zero, say, or one the receipt reports `suppressed`. So\nthe cue can only ever make the wallet move for a reward that really\nlanded — which it does on every channel, dev and test included.",
           "deprecated": null,
           "params": [
             {
@@ -13719,6 +13868,29 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "Gem.setRewardPresentation",
+          "name": "setRewardPresentation",
+          "anchor": "gem-setrewardpresentation",
+          "group": "start",
+          "signature": "setRewardPresentation(mode: RewardPresentation): boolean",
+          "documented": true,
+          "summary": "Say who decides when your platform-currency payouts are shown landing: the\narcade (`'arcade'`, the default) or your game (`'game'`). Call it once at\nboot when your reward moment comes after your server pays, such as a Claim\ntap on the win card or the next screen the player sees.\n\n```js\ngem.setRewardPresentation('game'); // at boot\n// ...the server pays when the board is won; later, on Claim:\ngem.cueReward({ currencySlug: 'ARCADE_TICKETS', expected: 20, origin });\n```\n\n**With `'game'`, your cue supplies the moment and the payout supplies the\nnumber.** The arcade holds each payout's presentation for its currency\nrather than flying it from the middle of your frame. Each `cueReward`\nreleases up to its `expected` of what is held (all of it when it names no\namount) and flies it from its `origin`, and the arcade's wallet chip over\nyour game counts up as the marks land. A cue that finds nothing held waits\nfor the next payout of its currency, so cue before or after the write, in\neither order.\n\n**It delays the show, never the money.** What is paid, when, and every\nceiling are unchanged, and the arcade's menu and every purchase see the\nplayer's true total at once. A payout no cue releases within five minutes\nlands quietly, with no flight, so a game can never hide one.\n\n**It is screen state, not a toggle**, held before the bridge is up and\nre-sent after every reconnect. Switching back to `'arcade'` lands whatever\nis held. A value that is neither is ignored, with a warning on the console,\nand changes nothing.",
+          "deprecated": null,
+          "params": [
+            {
+              "name": "mode",
+              "type": "RewardPresentation",
+              "optional": false,
+              "summary": "`'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\n  up (the answer is held and sent when it connects), under an embedder\n  that presents every payout its own way, and for a value that is neither.\n  On `false` from an embedder, keep cueing as usual: nothing else changes.",
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "Gem.setWalletVisible",
           "name": "setWalletVisible",
@@ -22405,7 +22577,7 @@
           "group": "rooms",
           "signature": "readonly playWith: PlayWithOutcome | null",
           "documented": true,
-          "summary": "What the last [RoomManager.quickJoin](api-reference-game.md#roommanager-quickjoin) did when the Arcade opened\nyour game to play with someone — a friend whose Join the player pressed,\nor their party's leader. Read-only.\n\n- `'joined'` — the player was seated in that person's room, as a member\n  sharing their `groupId`.\n- `'unavailable'` — that room could not be joined (no seat, a match that\n  admits nobody late, another mode), so the quick-join went on as it\n  always does. No reason is given.\n- `null` — no quick-join has asked: the Arcade did not open the game to\n  play with anyone, or nothing has quick-joined yet.\n\nYour game makes no call for this, names nobody and is told nobody's name:\nthe Arcade adds a launch key of its own, an opaque ticket, and every\n`quickJoin` passes it on. Nothing else\nchanges — the room is the one `quickJoin` answers with, `joined` fires as\nfor any quick-join, and no `seated` follows, because your own call made\nthe seat. Use it for a line of text (\"You joined your friend's game\") or\nto skip a mode picker, never to decide anything of value.",
+          "summary": "What the last [RoomManager.quickJoin](api-reference-game.md#roommanager-quickjoin) did when the Arcade opened\nyour game to play with someone — a friend whose Join the player pressed,\na friend's invite, or their party's leader. Read-only.\n\n- `'joined'` — the player was seated in that person's room, as a member\n  sharing their `groupId`.\n- `'unavailable'` — that room could not be joined (no seat, a match that\n  admits nobody late, another mode), so the quick-join went on as it\n  always does. No reason is given.\n- `null` — no quick-join has asked: the Arcade did not open the game to\n  play with anyone, or nothing has quick-joined yet.\n\nYour game makes no call for this, names nobody and is told nobody's name:\nthe Arcade adds a launch key of its own, an opaque ticket, and every\n`quickJoin` passes it on. Nothing else\nchanges — the room is the one `quickJoin` answers with, `joined` fires as\nfor any quick-join, and no `seated` follows, because your own call made\nthe seat. Use it for a line of text (\"You joined your friend's game\") or\nto skip a mode picker, never to decide anything of value.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -26721,6 +26893,22 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "FunctionInvokeOptions.cueId",
+          "name": "cueId",
+          "anchor": "functioninvokeoptions-cueid",
+          "group": "functions",
+          "signature": "readonly cueId?: string",
+          "documented": true,
+          "summary": "The id of the reward this call pays, so the Gem Arcade flies it once:\nthe same `cueId` you pass to `gem.cueReward` for it, one\n`crypto.randomUUID()` per award. The platform hands it back on the payout\nit shows the arcade, and nowhere else: your function never sees it, and\nneither the answer nor a receipt carries it.\n\n1 to 64 letters, digits, `_` or `-`. Anything else is left out with a\nconsole warning, and the call still goes: it decides an animation, never\nwhether the call pays.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "FunctionResult",
           "name": "FunctionResult",
@@ -27000,7 +27188,7 @@
           "group": "functions",
           "signature": "invoke(input: unknown, options?: FunctionInvokeOptions): Promise<FunctionResult>",
           "documented": true,
-          "summary": "Call the function published on your channel, and get its answer.\n\nThe input is sent as your function's `input`, byte for byte. Pass a\n`Uint8Array`, an `ArrayBuffer` or another typed array to send bytes as they\nare. Pass anything else and it is sent as its JSON text — a string too, so\n`'ping'` arrives as `\"ping\"` with its quotes.\n\nThe call is made once. It is never repeated for you, because your function\nmay have granted or written something: see [GemFunctionError.retryable](api-reference-server.md#gemfunctionerror-retryable)\nfor whether repeating it could help.\n\n```js\nconst result = await gem.functions.invoke({ v: 2, runId, finishMs });\nconst { accepted, why } = result.json();\n```",
+          "summary": "Call the function published on your channel, and get its answer.\n\nThe input is sent as your function's `input`, byte for byte. Pass a\n`Uint8Array`, an `ArrayBuffer` or another typed array to send bytes as they\nare. Pass anything else and it is sent as its JSON text — a string too, so\n`'ping'` arrives as `\"ping\"` with its quotes.\n\nThe call is made once. It is never repeated for you, because your function\nmay have granted or written something: see [GemFunctionError.retryable](api-reference-server.md#gemfunctionerror-retryable)\nfor whether repeating it could help.\n\nThe answer is the receipt: when this resolves, what your function says it\ngranted has been written. A game shows it at once and re-reads the\ninventory in the background (`gem.me.inventory.refresh()`, then\n`snapshot()`, or on `gem.me.inventory.onChanged`); never hold the player on\na loop that re-reads until the grant shows.\n\n```js\nconst result = await gem.functions.invoke({ v: 2, runId, finishMs });\nconst { accepted, why } = result.json();\n```\n\nWhen the call pays a reward the player sees, pass the reward's `cueId`, the\nsame one the page gives `gem.cueReward` for it, and the Gem Arcade flies it\nonce:\n\n```js\nconst cueId = crypto.randomUUID(); // one per award, also passed to the cue\nawait gem.functions.invoke({ claim: 'daily' }, { cueId });\n```",
           "deprecated": null,
           "params": [
             {
@@ -32401,7 +32589,7 @@
           "group": "inventory",
           "signature": "refresh(): void",
           "documented": true,
-          "summary": "Throw away what is cached, so the next [InventoryApi.snapshot](api-reference-function.md#inventoryapi-snapshot) really\nasks.\n\nFor when something you did not do changed the inventory — a purchase on\nanother device, a grant from a server. The SDK already drops the cache\nitself after any change it made.",
+          "summary": "Throw away what is cached, so the next [InventoryApi.snapshot](api-reference-function.md#inventoryapi-snapshot) really\nasks.\n\nFor when something you did not do changed the inventory — a purchase on\nanother device, a grant from a server — and nothing told you. The SDK\nalready drops the cache itself after any change it made, and on an\nArcade's hint that this game's inventory changed on the server.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -32417,7 +32605,7 @@
           "group": "inventory",
           "signature": "onChanged(listener: () => void): () => void",
           "documented": true,
-          "summary": "Run something whenever this inventory changes, and get back a function that\nstops listening.\n\n⚠️ LOCAL CHANGES ONLY — this fires for changes THIS game made through this\nSDK. It does NOT fire when an inventory changes anywhere else: another\ndevice, a game server, an admin tool, or a gift from another player. Do not\nbuild \"keep the bag live\" on it; use it to react to your own writes, and\ncall [InventoryApi.refresh](api-reference-function.md#inventoryapi-refresh) when you have reason to think something\nelse moved.",
+          "summary": "Run something whenever this inventory changes, and get back a function that\nstops listening.\n\nFires for every change THIS game made through this SDK, and — on an Arcade\nthat relays it — for any change to this game's inventory on the server: a\ngrant from your function or server, a purchase, a gift accepted, a support\ngrant, another device. It is a cue to re-read, not a receipt: it carries\nnothing, so call [InventoryApi.snapshot](api-reference-function.md#inventoryapi-snapshot) for what changed. After your\nown function's grant, show the function's answer and let this redraw.\n\nAn older Arcade sends no hint, and there it fires for your own writes\nonly. Keep a fallback that does not depend on it: refresh on\n`visibilitychange` to `visible` and after any action that could involve\nanother player. Do not poll.",
           "deprecated": null,
           "params": [
             {
@@ -36169,6 +36357,38 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "PlayInviteRequest",
+          "name": "PlayInviteRequest",
+          "anchor": "playinviterequest",
+          "group": "friends",
+          "signature": "interface PlayInviteRequest",
+          "documented": true,
+          "summary": "What `gem.friends.inviteToPlay` takes.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "PlayInviteRequest.params",
+          "name": "params",
+          "anchor": "playinviterequest-params",
+          "group": "friends",
+          "signature": "readonly params?: Readonly<Record<string, string>>",
+          "documented": true,
+          "summary": "Your own launch parameters for what the Arcade's link and invites open —\n`{ room: joinCode }` for a room joined by code — exactly as they should\nreach your game, on `gem.share.request`'s rules: at most 16, keys a letter\nthen up to 63 letters, digits, `_` or `-`, string values of at most 512\ncharacters. For this one opening, they replace what\n`gem.friends.setInviteParams` declared. Omit it to use that declaration.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "FriendsApi",
           "name": "FriendsApi",
@@ -36231,6 +36451,52 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "FriendsApi.inviteToPlay",
+          "name": "inviteToPlay",
+          "anchor": "friendsapi-invitetoplay",
+          "group": "friends",
+          "signature": "inviteToPlay(request?: PlayInviteRequest): Promise<boolean>",
+          "documented": true,
+          "summary": "Ask the Arcade to open ITS invite sheet, so the player can invite friends\nto come and play this game with them.\n\nThe Arcade lists the player's friends in its own chrome and sends an\ninvite only when the player presses Invite there. A friend who accepts is\nopened into this game by the Arcade, and their quick-join seats them in\nthe player's room when there is a seat: your game makes no call for it,\nand reads them as a room member who shares the player's `groupId`. Your\ngame names nobody and writes no text.\n\nAn Arcade that does not offer the sheet answers `false` at once, and asks\nnothing. Hide the button on `gem.frame.parentSupports('playInvites')`\nrather than letting a player press one that cannot work.\n\n⚠️ **Call it ONLY from a player's press**, never on a timer or as a screen\nopens. The Arcade answers an ask with no press behind it `false`, and\nshows nothing.\n\nRESOLVES `true` when the Arcade opened its sheet, and `false` when it did\nnot: outside the Arcade, without `playInvites`, with another sheet\nalready open, without a press, or when no answer arrived. **That is all it\nsays** — never whom the player invited, how many, or whether any invite\nwas sent — so never gate a reward on it. Never rejects.\n\nCalls made while an ask is open share its answer.\n\n**The window's share link and its invites are one system.** Pass\n`params` — your own launch parameters, `{ room: joinCode }` for a room\njoined by code — and a friend who accepts and anyone who opens the link\narrive with them, on `gem.share.request`'s rules. Omitted, the window uses\nwhat [FriendsApi.setInviteParams](api-reference-function.md#friendsapi-setinviteparams) declared. A param those rules\nrefuse is said on the console and nothing is asked: the call resolves\n`false`.",
+          "deprecated": null,
+          "params": [
+            {
+              "name": "request",
+              "type": "PlayInviteRequest",
+              "optional": true,
+              "summary": null
+            }
+          ],
+          "returns": null,
+          "throws": null,
+          "example": "```ts\ninviteButton.onclick = async () => {\n  const shown = await gem.friends.inviteToPlay({ params: { room: joinCode } });\n  if (!shown) showJoinCode(); // the Arcade's sheet did not open: your own fallback\n};\n```",
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "FriendsApi.setInviteParams",
+          "name": "setInviteParams",
+          "anchor": "friendsapi-setinviteparams",
+          "group": "friends",
+          "signature": "setInviteParams(params: Readonly<Record<string, string>> | null): boolean",
+          "documented": true,
+          "summary": "Say what the Arcade's Friends window opens when the PLAYER opens it from\nthe Arcade's own menu over your game: your launch parameters, carried by\nits share link and its friend invites alike, on `gem.share.request`'s\nrules. Pass `null` to clear.\n\nCall it when the player enters a room joined by code —\n`setInviteParams({ room: joinCode })` — and `setInviteParams(null)` when\nthey leave it, so the window never invites anyone into a room that is\ngone. The latest call stands until the next; the SDK holds it and says it\nagain after a reconnect. An explicit `inviteToPlay({ params })` wins for\nthat one opening. Nothing comes back, and nothing changes on screen.",
+          "deprecated": null,
+          "params": [
+            {
+              "name": "params",
+              "type": "Readonly<Record<string, string>> | null",
+              "optional": false,
+              "summary": null
+            }
+          ],
+          "returns": "whether the declaration reached the Arcade now. `false` outside\n  the Arcade, without `playInvites`, before the bridge is up (it is sent on\n  connect) and for params the share rules refuse, which are said on the\n  console; the last declaration then stands.",
+          "throws": null,
+          "example": "```ts\n// On entering a room joined by code:\ngem.friends.setInviteParams({ room: joinCode });\n// ...and on leaving it:\ngem.friends.setInviteParams(null);\n```",
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "FriendsApi.inbox",
           "name": "inbox",

package/docs/arcade-economy.md

@@ -237,7 +237,9 @@ animates every payout into the right total. Gems and Coins follow the same rules
   `onPause(false)` if you keep anything worked out from it, such as a greyed-out Buy button.
 - **No celebration of your own.** At a payout, cue the arcade's wallet with `gem.cueReward`, naming
   the currency that paid — `currencySlug: 'GEMS'` from the gem on your reward screen,
-  `'ARCADE_TICKETS'` from the coin. If it returns `false`, do nothing
+  `'ARCADE_TICKETS'` from the coin. If it returns `false`, do nothing. When your serverless function
+  pays it, pass one `cueId` (a `crypto.randomUUID()`) to both the cue and the `gem.functions.invoke`
+  call, and the reward flies once
   ([inventory-and-catalogs.md](inventory-and-catalogs.md#showing-the-reward-land-in-the-arcades-wallet)).
 - **No "daily max" of your own making.** Your game cannot see what every other game paid the player,
   and must not compute a maximum. To show how much more your game can pay, read

package/docs/changelog.md

@@ -16,6 +16,67 @@ 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.
 
+## 23.0.0
+
+*Written from the API facts alone; no summary was generated for this release.*
+
+Upgrading from 22.0.0. Impact: required.
+
+### Must change
+
+- PARENT_CONFORMANCE_VERSION changed its signature.
+- GemFrame.requestArcade changed its signature.
+- FRAME_TO_PARENT changed its signature.
+- FrameMessage changed its signature.
+- GemCapability changed its signature.
+- PARENT_TO_FRAME changed its signature.
+- ParentMessage changed its signature.
+
+### New capability
+
+- ParentFixture.channel was added.
+- ParentFixture.gameId was added.
+- ParentUnderTest.deliverSocket was added.
+- CharactersApi.refreshHeld was added.
+- FriendsApi.inviteToPlay was added.
+- FriendsApi.setInviteParams was added.
+- FriendsApiDependencies.inviteToPlay was added.
+- FriendsApiDependencies.setInviteParams was added.
+- PlayInviteRequest was added.
+- FrameCallbacks.onInventoryChanged was added.
+- FrameCallbacks.onPlayInviteResult was added.
+- FrameOptions.onInventoryChanged was added.
+- FrameOptions.onPlayInviteResult was added.
+- GemHost.answerPlayInvite was added.
+- GemHost.relayInventoryEvent was added.
+- GemHost.sendInventoryChanged was added.
+- GemInventoryChanged was added.
+- GemInviteParams was added.
+- GemPlayInviteResult was added.
+- GemRequestPlayInvite was added.
+- HostCallbacks.onInviteParams was added.
+- HostCallbacks.onRequestPlayInvite was added.
+- HostOptions.onInviteParams was added.
+- HostOptions.onRequestPlayInvite was added.
+- validateGemInventoryChanged was added.
+- validateGemInviteParams was added.
+- validateGemPlayInviteResult was added.
+- validateGemRequestPlayInvite was added.
+
+## 22.0.0
+
+Upgrading from 21.1.1. Impact: required.
+
+### Rebuild
+
+- The function invoke options gained an optional cueId field, which changes the signatures of the functions API constructor, the server API invoke function member and the standalone invoke function. Nothing is required of existing calls; recompiling is enough.
+- The frame message union, the list of frame-to-parent messages and the capability type each gained a reward presentation entry. Recompiling is enough, unless your code switches exhaustively over these types, in which case add a case for the new entry.
+
+### New capability
+
+- A game can now make one id per award and pass it to both the reward cue call and the function invoke call, so the Arcade pairs the cue with its payout and the reward flies once. An id that is malformed is left out with a console warning and never throws. Passing an id is optional and existing calls behave as before.
+- A server-paid game whose reward moment comes after the payout can now declare that its own reward cue decides when the payout is shown, instead of leaving the timing to the Arcade. Under the game choice the Arcade holds each payout's presentation until a cue releases it, and a payout that no cue releases within a limited time lands quietly. Only the presentation changes; what is paid, when it is paid, and every limit stay the same. The declaration is remembered until the Arcade connection is ready and sent again after each reconnect, and it takes effect only when the Arcade offers the matching capability.
+
 ## 21.1.1
 
 Upgrading from 21.1.0. Impact: none.

package/docs/daily-challenges.md

@@ -324,7 +324,9 @@ Four things to know before you ship one:
 player's Gems and Coins in its own chrome, and without a cue a payout flies from the middle of
 your frame, not from the payout the player is looking at. At the moment your game shows the challenge complete, call
 `gem.cueReward` with the currency that paid (`GEMS` or `ARCADE_TICKETS`) and the centre of its icon
-beside the payout on your completion screen, and the payout flies from there into the Gem button:
+beside the payout on your completion screen, and the payout flies from there into the Gem button.
+When a serverless function pays it, give the cue and the `gem.functions.invoke` call one `cueId`
+so it flies once:
 [inventory-and-catalogs.md](inventory-and-catalogs.md#showing-the-reward-land-in-the-arcades-wallet).
 **If it returns `false`, do nothing** — no celebration of your own, no counter, no flight;
 platform-currency display belongs to the arcade, and a game not connected to it shows no