@indiegems/gem-web-sdk 22.0.0 → 23.0.1

package/docs/api/reference.json

@@ -2,7 +2,7 @@
   "schema_version": 2,
   "source": {
     "repo": "IndieGems/gem-web-sdk",
-    "version": "22.0.0"
+    "version": "23.0.1"
   },
   "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": [
             {
@@ -10095,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",
@@ -10157,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",
@@ -10553,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```\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```",
+          "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": [
             {
@@ -13554,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,
@@ -22499,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,
@@ -27110,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```\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```",
+          "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": [
             {
@@ -32511,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,
@@ -32527,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": [
             {
@@ -36279,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",
@@ -36341,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/changelog.md

@@ -16,6 +16,59 @@ 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.1
+
+Upgrading from 23.0.0. Impact: none.
+
+Nothing in this release asks anything of a game.
+
+## 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.

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": "22.0.0"
+  "@indiegems/gem-web-sdk": "23.0.1"
 }
 ```
 
@@ -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
@@ -386,9 +392,10 @@ the arcade applies:
     the sign-in return marker.
   - Attribution and campaign keys: `_s`, `utm_*` (every key with that prefix, matched
     case-sensitively, so UTM_X and utmost are yours), `fbclid`, `ttclid`, `gclid`, `gbraid`,
-    `wbraid`, `msclkid`. The arcade strips the visitor's own campaign and click ids, but a link
-    a game shares, or one anyone writes by hand, can still put `utm_*` and the click ids into
-    your frame, restored from their escaped form.
+    `wbraid`, `msclkid`, and `gem_link`, a search ad's link code on your store page. The arcade
+    strips the visitor's own campaign and click ids, but a link a game shares, or one anyone
+    writes by hand, can still put `utm_*` and the click ids into your frame, restored from their
+    escaped form.
 
   A link your game shares can still carry most of them: see
   [Sharing a reserved key](#sharing-a-reserved-key) below.