@indiegems/gem-web-sdk 22.0.0 → 23.0.0

package/docs/manifest.json

@@ -48,8 +48,8 @@
     },
     {
       "file": "changelog.md",
-      "sha256": "8d83b78666b70888b6ecd2ffc6877956787daca3698eff5844e86f724699ce52",
-      "updated": "2026-11-04T23:21:33Z"
+      "sha256": "20215a4410087dd6076afd787bcfd4ee29bc5bf50e56562563e32a060cd74cc4",
+      "updated": "2026-11-05T00:34:54Z"
     },
     {
       "file": "daily-challenges.md",
@@ -68,8 +68,8 @@
     },
     {
       "file": "friends.md",
-      "sha256": "d8e1f07a10ebe5743a1d56d615731cc6e5965e1a380490d2a1362dc6c1263d2d",
-      "updated": "2026-10-12T16:40:39Z"
+      "sha256": "fd6db8da391647677568c0d2257dc5c92cbfe311759191b5e28fa3f66747aee6",
+      "updated": "2026-11-04T23:46:11Z"
     },
     {
       "file": "game-economy-tutorial.md",
@@ -78,8 +78,8 @@
     },
     {
       "file": "getting-started.md",
-      "sha256": "9cf851ec0894fd27350d492ce412ff025c86e17e2c9ecf900da7276868732540",
-      "updated": "2026-11-04T23:21:33Z"
+      "sha256": "c2f0c4fe33cc3e34120773a606179a4254963b957ab39cdda746c2f01db493d4",
+      "updated": "2026-11-05T00:34:54Z"
     },
     {
       "file": "graphics-route.md",
@@ -88,8 +88,8 @@
     },
     {
       "file": "inventory-and-catalogs.md",
-      "sha256": "eea98a531d814113474ab381b1e404a0c0c30c8c770ebe5c68da853eab85564d",
-      "updated": "2026-11-04T23:07:19Z"
+      "sha256": "f5aa4e405989da098317ca704b4dd8b996a1369c78ef0515ed7442886aee85fc",
+      "updated": "2026-11-04T23:38:54Z"
     },
     {
       "file": "leaderboards.md",
@@ -133,8 +133,8 @@
     },
     {
       "file": "rooms-and-matches.md",
-      "sha256": "4c1c32c5523eca1a8e3a2e06b42dab3ec4c70e8bd77496614aca909732485da4",
-      "updated": "2026-10-21T19:51:32Z"
+      "sha256": "dcbd9dda741656e5e346c2fea3240331ac19d055aede0ff27d706a63efb35500",
+      "updated": "2026-11-04T23:26:42Z"
     },
     {
       "file": "saving-player-progress.md",
@@ -143,8 +143,8 @@
     },
     {
       "file": "server-bundles.md",
-      "sha256": "0f74e07ded6c9fb339c3bafa26e4af5153ce0bf20476fdb70444dcad2070766e",
-      "updated": "2026-11-04T23:21:33Z"
+      "sha256": "fe9e5ced6e2e6bc4d583697c5f206f2f0431af8926eab7d8076f7f46e42864c9",
+      "updated": "2026-11-05T00:34:54Z"
     },
     {
       "file": "serverless-functions-js.md",
@@ -153,13 +153,13 @@
     },
     {
       "file": "serverless-functions.md",
-      "sha256": "4c38d374fd80424be8ce774916e82253e68d8878d8b20558b815feec80ff4ee7",
-      "updated": "2026-11-04T21:50:20Z"
+      "sha256": "fa1d161689e30d2300ab2ec7de3f3a5c9147966f559f7272b9e9b91852ecbeb4",
+      "updated": "2026-11-04T23:38:54Z"
     },
     {
       "file": "trading-and-gifting.md",
-      "sha256": "e5a77bcae4243fbf69a34fa6440114677401255b40ee9825c15b87c6570e5030",
-      "updated": "2026-10-21T19:36:16Z"
+      "sha256": "24ff7ebfc10b5186527cc51b49d8f2f556b43e6ff37b06db20ce3c7efd87855a",
+      "updated": "2026-11-04T23:38:54Z"
     },
     {
       "file": "vibration.md",

package/docs/rooms-and-matches.md

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

package/docs/server-bundles.md

@@ -80,8 +80,8 @@ To check the download yourself: the package npm serves is, byte for byte, the fi
 also publishes on its download host, with the hash beside it:
 
 ```bash
-curl -fsSL -O https://downloads.gemarcade.com/sdk/v22.0.0/gem-web-sdk.tgz
-curl -fsSL https://downloads.gemarcade.com/sdk/v22.0.0/gem-web-sdk.tgz.sri
+curl -fsSL -O https://downloads.gemarcade.com/sdk/v23.0.0/gem-web-sdk.tgz
+curl -fsSL https://downloads.gemarcade.com/sdk/v23.0.0/gem-web-sdk.tgz.sri
 openssl dgst -sha384 -binary gem-web-sdk.tgz | openssl base64 -A
 ```
 

package/docs/serverless-functions.md

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

package/docs/trading-and-gifting.md

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

package/package.json

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

package/schema/bridge.v1.json

@@ -1222,6 +1222,44 @@
       "rateLimit": { "perMinute": 30 }
     },
 
+    {
+      "type": "gem.inventoryChanged",
+      "direction": "parentToFrame",
+      "transport": "port",
+      "$comment": [
+        "Something in this player's inventory for THIS game and channel MAY have",
+        "changed on the server, so the frame should re-read it with its own",
+        "token if it shows it. Gated on `inventoryChanged`: a parent sends it",
+        "only when `frameSupports('inventoryChanged')`.",
+        "",
+        "NO FIELDS, AND IT SHOULD STAY THAT WAY. The frame re-reads its own",
+        "scope from gem-api, the authority, so the bridge never becomes a second",
+        "source of truth for a balance or an item. This message never carries",
+        "an item, a quantity, a balance, an order, an entity, a source or any",
+        "game's id: it says only that a change happened, around now.",
+        "",
+        "WHEN A PARENT MAY SEND IT: on gem-api's `game_inventory_changed` socket",
+        "event, only when its `game_id` is the game this session's token was",
+        "granted for and its `channel` is that token's channel, and only after",
+        "that token was sent. NEVER for another game's scope, another channel's,",
+        "or the platform wallet (`platform_grant_fired` and the other wallet",
+        "events): that send would tell this game, to the second, when another",
+        "game or the platform paid the player -- a timing oracle for payouts",
+        "this game is otherwise never shown. Nothing from the socket event's",
+        "payload is copied. It should coalesce a burst -- one send now, then at",
+        "most one trailing send every two seconds -- so a function that grants",
+        "in a loop stays inside the limit.",
+        "",
+        "A HINT, NOT A RECEIPT. A game that granted through its own function",
+        "already has the function's answer, which is the receipt; this is the",
+        "cue to redraw from a fresh read. An embedder that never sends it is not",
+        "defective. The SDK drops its cached reads of the game's inventory and",
+        "makes no request because of it."
+      ],
+      "fields": {},
+      "rateLimit": { "perMinute": 30 }
+    },
+
     {
       "type": "gem.viewport",
       "direction": "parentToFrame",
@@ -5282,6 +5320,193 @@
       },
       "rateLimit": { "perMinute": 30 }
     },
+    {
+      "type": "gem.requestPlayInvite",
+      "direction": "frameToParent",
+      "transport": "port",
+      "$comment": [
+        "Ask the parent to open ITS OWN invite-to-play sheet for this game, so",
+        "the player can invite friends to come and play it with them - the",
+        "\"Invite friends\" button of a lobby or a hub. Gated by the",
+        "`playInvites` capability. Answered by `gem.playInviteResult`.",
+        "",
+        "A PLATFORM DECISION: DESIGN.md section 10's eighth amendment,",
+        "decided by the platform owner on 2026-11-04, amending its 'no",
+        "invites in the frame'. The sheet is the Arcade's own Friends window,",
+        "the one the player also opens from the Arcade's menu.",
+        "",
+        "WHY THIS CROSSES THE BRIDGE AT ALL. A game knows the moment an invite is",
+        "worth offering - a lobby with an empty seat, a hub the player just",
+        "reached - but an invite puts a notice in front of another person, which",
+        "is an account-session act the game-scoped token is refused by",
+        "construction, and the friends worth inviting are chosen by their",
+        "presence, which never reaches a frame. So the game ASKS, and the parent,",
+        "which holds the account session, renders its own sheet of the player's",
+        "friends and sends an invite only on the player's own press in it.",
+        "",
+        "A CORRELATOR AND, OPTIONALLY, THE GAME'S LAUNCH PARAMS, deliberately",
+        "nothing more. The params say what the window's link and invites open,",
+        "as a share's do, and name nobody. No player id: a game",
+        "that could name the friend would be choosing whom the platform notifies,",
+        "and could learn from the answer whether that friend is reachable. No",
+        "game id and no channel: the parent takes both from what it framed. No",
+        "text: what the sheet and the invite say is the platform's own.",
+        "",
+        "WHAT THE PARENT OWES, none of which this schema can enforce:",
+        "",
+        "  ADVERTISE IT AS A DEPLOYMENT-WIDE FACT, never by account state, and",
+        "  only once the platform has decided it. A guest, or a player with no",
+        "  friends, is the parent's to explain in its own chrome or to answer",
+        "  `shown: false`; a token that blinked with sign-in would move that",
+        "  disclosure into the handshake.",
+        "",
+        "  CHECK ACTIVATION ON RECEIPT. Read `navigator.userActivation.isActive`",
+        "  synchronously when the message arrives, before any `await`, and answer",
+        "  an ask that arrives without it `shown: false` with nothing rendered.",
+        "  The frame chooses the moment it asks; the player's press is what makes",
+        "  a sheet over their game wanted rather than a nag.",
+        "",
+        "  ONE SHEET AT A TIME, AND CAPPED. An ask arriving while this sheet - or",
+        "  any other sheet that holds the stage: a purchase, a sign-in prompt, a",
+        "  friend challenge - is open is answered `shown: false` with nothing",
+        "  rendered, and the open invite sheet holds the stage against those asks",
+        "  too. A short cooldown after the player closes one is the parent's",
+        "  call.",
+        "",
+        "  RENDER ONLY FROM PLATFORM RECORDS. The friends, their presence and the",
+        "  game's name come from the parent's own reads, never from the frame.",
+        "  Each Invite press is one account-session send.",
+        "",
+        "  PAUSE THE GAME while the sheet is open (`gem.pause`) and lift it when",
+        "  the sheet closes, returning focus to the frame.",
+        "",
+        "  ANSWER ONCE, AS THE SHEET OPENS. `shown: true` once it has painted,",
+        "  not when it closes: how long the player browsed, and what they did in",
+        "  it, are theirs.",
+        "",
+        "NOT AN AUTHORIZATION CONTROL. The player's Invite press in the parent's",
+        "chrome is the control, and the platform's account-session send is the",
+        "enforcement: it re-checks the friendship, blocks and every budget,",
+        "whatever reached it."
+      ],
+      "fields": {
+        "requestId": {
+          "kind": "string",
+          "maxLength": 64,
+          "$comment": "Opaque and frame-chosen. The parent treats it as an echo-only correlator, exactly as it does for gem.requestFriendChallenge - it is not unique across tabs or reloads and must never key anything. It may also contain newlines and control characters, so it is not safe to write into a log line unescaped."
+        },
+        "params": {
+          "kind": "array",
+          "maxItems": 16,
+          "optional": true,
+          "$comment": [
+            "The game's own launch parameters for what the invite and the",
+            "window's share link open - `{ room: <join code> }` for a game whose",
+            "rooms are joined by code. The same shape, grammar and reserved-key",
+            "rules as `gem.requestShare.params`: the window's share link and its",
+            "friend invites carry the same params, so a friend who accepts and a",
+            "stranger who opens the link arrive the same way. ABSENT: the parent",
+            "uses the params the game last declared with `gem.inviteParams`, or",
+            "none. PRESENT, even empty: these, for this one opening.",
+            "",
+            "The parent applies the share rules to them and answers `shown:",
+            "false`, rendering nothing, for anything it would refuse. They name",
+            "what the link opens, never a person."
+          ],
+          "items": {
+            "kind": "object",
+            "fields": {
+              "key": { "kind": "string", "maxLength": 64 },
+              "value": { "kind": "string", "maxLength": 512 }
+            }
+          }
+        }
+      },
+      "rateLimit": {
+        "perMinute": 6,
+        "$comment": "Bounds a BUGGY game. NOT a security control: a hostile game posts on the port it holds rather than calling the SDK. What stops a game nagging is the parent's activation check, its one-sheet-at-a-time rule and the player's own Invite press."
+      }
+    },
+    {
+      "type": "gem.playInviteResult",
+      "direction": "parentToFrame",
+      "transport": "port",
+      "$comment": [
+        "The answer to one gem.requestPlayInvite. Gated by the `playInvites`",
+        "capability.",
+        "",
+        "ONE BOOLEAN, AND NOTHING ELSE. `shown: true` - the parent opened its",
+        "invite sheet. `shown: false` - nothing was rendered: no activation,",
+        "another sheet held the stage, a guest, a parent with no sheet to offer.",
+        "",
+        "WHAT THE FRAME NEVER LEARNS, and a parent must not attach: whom the",
+        "player invited, how many, whether any invite was sent, delivered or",
+        "accepted, or why nothing was shown. Who the player invites is a fact",
+        "about the people they know, and whether an invite landed is a fact about",
+        "a stranger's settings; neither is the game's. So `shown: true` grants",
+        "nothing and is no sign anything was sent - a game never gates a reward",
+        "on it. A",
+        "friend who accepts arrives the ordinary way: the Arcade opens the game",
+        "for them, and its own quick-join seats them beside the player.",
+        "",
+        "PERMANENTLY A BOOLEAN. A field reporting the outcome would undo the",
+        "amendment this pair rides on (DESIGN.md section 10, pending the",
+        "platform's decision)."
+      ],
+      "fields": {
+        "requestId": {
+          "kind": "string",
+          "maxLength": 64,
+          "$comment": "Echoes the gem.requestPlayInvite that asked. Echo-only."
+        },
+        "shown": {
+          "kind": "boolean",
+          "$comment": "Whether the parent opened its invite sheet. It grants nothing, and says nothing about whether anyone was invited."
+        }
+      },
+      "rateLimit": { "perMinute": 12 }
+    },
+    {
+      "type": "gem.inviteParams",
+      "direction": "frameToParent",
+      "transport": "port",
+      "$comment": [
+        "A standing declaration: the launch parameters the Arcade's Friends",
+        "window should carry when the PLAYER opens it from the Arcade's own",
+        "menu, over this game - its share link and its friend invites alike.",
+        "Gated by the `playInvites` capability. Nothing answers it.",
+        "",
+        "A game sends it when it enters a room joined by code (`{ room:",
+        "<join code> }`) and clears it - `params` absent - when it leaves. The",
+        "latest one stands until the next, and an explicit",
+        "`gem.requestPlayInvite` carrying `params` wins for that one opening.",
+        "The SDK re-sends the latest on every handshake, so a fresh parent",
+        "holds what the game last said.",
+        "",
+        "THE SAME PARAMS AS A SHARE, on the same rules. They name what a link",
+        "opens and never a person: no player, no game id and no channel",
+        "travel. The parent applies the share rules to them when it uses",
+        "them, and leaves a link it would refuse unbuilt rather than",
+        "carrying it. Sending one changes nothing on screen and tells the",
+        "game nothing."
+      ],
+      "fields": {
+        "params": {
+          "kind": "array",
+          "maxItems": 16,
+          "optional": true,
+          "$comment": "The declared params, in order; the shape, grammar and reserved-key rules of `gem.requestShare.params`. ABSENT clears the declaration.",
+          "items": {
+            "kind": "object",
+            "fields": {
+              "key": { "kind": "string", "maxLength": 64 },
+              "value": { "kind": "string", "maxLength": 512 }
+            }
+          }
+        }
+      },
+      "rateLimit": { "perMinute": 30 }
+    },
     {
       "type": "gem.requestAppLinks",
       "direction": "frameToParent",

package/schema/capabilities.public.json

@@ -46,6 +46,14 @@
         "gem.friendChallengeResult"
       ]
     },
+    "playInvites": {
+      "implemented": true,
+      "gates": [
+        "gem.requestPlayInvite",
+        "gem.playInviteResult",
+        "gem.inviteParams"
+      ]
+    },
     "devtools": {
       "implemented": true,
       "gates": [
@@ -213,6 +221,12 @@
         "gem.earnAllowanceChanged"
       ]
     },
+    "inventoryChanged": {
+      "implemented": true,
+      "gates": [
+        "gem.inventoryChanged"
+      ]
+    },
     "deviceSettings": {
       "implemented": true,
       "gates": [