@indiegems/gem-web-sdk 18.1.1 → 19.0.1

package/docs/arcade-and-store.md

@@ -40,7 +40,8 @@ itself. You get an outcome.
 - [8. The Arcade Store's offers](#8-the-arcade-stores-offers)
 - [9. Buying from the Arcade Store](#9-buying-from-the-arcade-store)
 - [10. Letting the Arcade show one offer](#10-letting-the-arcade-show-one-offer)
-- [11. Outcomes and reasons](#11-outcomes-and-reasons)
+- [11. What the player holds, and a VIP door](#11-what-the-player-holds-and-a-vip-door)
+- [12. Outcomes and reasons](#12-outcomes-and-reasons)
 
 ## 1. Two surfaces, and which one is real money
 
@@ -67,7 +68,7 @@ three and never grows:
 
 `reason` is a short code that says why. The set is open: a new Arcade build may send a reason your
 game has never seen, so branch on `outcome` and treat `reason` as a hint. The codes in use today are
-in [§11](#11-outcomes-and-reasons).
+in [§12](#12-outcomes-and-reasons).
 
 ## 3. What is available here
 
@@ -316,9 +317,9 @@ Pick by who can say what the offer is:
 - **Do not show a price on the button.** The sheet shows the right one for this player, which a
   sale or a pass can change, and `priceDisplay` does not say either of those. If you want a price on
   screen, draw the offer yourself and use `purchase`.
-- **You cannot tell whether the player holds a pass.** The Arcade keeps that to itself, and the
-  sheet tells the player. So the button stays up for a holder, and that is fine: the sheet is what
-  they see, and they choose from there.
+- **The sheet does not tell you what the player holds.** It tells the player, so a button that
+  stays up for a holder is fine: they see what they already have, and choose from there. To change
+  your own screen for a holder, read `gem.me.passes` ([§11](#11-what-the-player-holds-and-a-vip-door)).
 - **Hide the button when the SKU is not in `offers()`.** A SKU that is not on sale here answers
   `unavailable` / `not_found`, and the player would have pressed a button that does nothing.
 - **Read `showOfferAvailable`, not `available`.** An older Arcade can sell through `purchase` and
@@ -332,7 +333,145 @@ closed checkout, shared with `purchase`: the next ask of either kind is `decline
 while. The press shows nothing during a back-off, so give the player something else to do on that
 screen.
 
-## 11. Outcomes and reasons
+## 11. What the player holds, and a VIP door
+
+```js
+const passes = await gem.me.passes.list();
+// [{ pass: 'vip', held: true, endsAt: '2026-11-29T12:34:56Z' }]
+
+const vip = await gem.me.passes.get('vip'); // one pass by its slug
+if (vip.held) drawVipBadge();
+```
+
+`gem.me.passes` says which store passes the player holds. **VIP is the pass `vip`**, its offering
+slug. Key on the slug, which is stable and not localized, and never on a display name.
+
+- **It lists every pass games may see, held or not.** An admin marks a pass as visible to games, and
+  the list has one entry for each, so its shape never says what the player bought. A pass that is not
+  marked is left out, and `get` reads a pass that is not listed as not held.
+- **A pass is a slug, whether it is held, and when it ends.** No price, no name, no perks, nothing
+  about how the player got it, and nothing about a pass that has ended.
+- **`endsAt` is the exact end,** grace and any queued period included, and `null` when the pass is not
+  held or is held with no end, which support can grant. Read `held` first: `null` alone never means
+  ended.
+- **A guest reads as not holding.** Every pass is `held: false`, and that is no error.
+- **A read that fails rejects with a `GemApiError`, as every `gem.me` read does.** That is unknown,
+  not "not held", so keep what you drew. It is the one call on this page that rejects.
+- **It is a read over your play token,** not an ask of the Arcade. It needs no press, and works
+  wherever your game has a token, including where the store is off: holding a pass is not buying one.
+  Each call goes to the platform, so read when you draw and do not poll.
+
+### The browser draws, the server decides
+
+**Never decide anything from `gem.me.passes`.** It runs in the player's browser, and a player can
+make any answer come back. It is for drawing the door. What is behind the door comes from your
+function, which asks the platform and answers with the contents. A level that ships in your build is
+not behind a door at all, because a player can open it by editing the page.
+
+```js
+// 1. DRAWING. Open or shut. Nothing here unlocks anything.
+function drawVipDoor(passes) {
+  door.drawOpen(passes.some((p) => p.pass === 'vip' && p.held));
+}
+
+await gem.awaitBridge();
+try {
+  drawVipDoor(await gem.me.passes.list());
+} catch {
+  door.drawShut(); // unknown: the press below still asks the function
+}
+gem.me.passes.on('changed', drawVipDoor); // opens after a purchase, locks when VIP ends
+
+// 2. DECIDING. The press asks the function. The browser's reading is not part of the call.
+door.onPress = async () => {
+  let answer;
+  try {
+    answer = (await gem.functions.invoke({ door: 'vip-lounge' })).json();
+  } catch {
+    showDoorIsStuck(); // nothing decided: not "you need VIP"
+    return;
+  }
+  if (answer.allowed) enterLounge(answer.lounge);
+  else showHowToGetVip();
+};
+
+// 3. BUYING. From the press on your own "How to get VIP" button.
+howToGetVipButton.onclick = () => gem.store.showOffer(VIP_SKU);
+```
+
+The function, in Rust, because only the platform's answer counts:
+
+```rust
+use gem::functions::host::{self, ApiRequest, Caller};
+
+// The input says which door. It never says who is asking, or what they hold.
+let context = host::get_context();
+let Caller::Player(_) = context.caller else {
+    return Err("expected a player's call".into());
+};
+let read = host::call_api(&ApiRequest {
+    method: "GET".into(),
+    path: format!("/v1/games/{}/players/me/passes", context.game_id),
+    body: Vec::new(),
+})?;
+if read.status != 200 {
+    return Err(format!("the pass read answered {}", read.status)); // decides nothing
+}
+let body: serde_json::Value = serde_json::from_slice(&read.body).map_err(|e| e.to_string())?;
+let vip = body["passes"]
+    .as_array()
+    .into_iter()
+    .flatten()
+    .any(|pass| pass["pass"] == "vip" && pass["held"] == true);
+let answer = if vip {
+    serde_json::json!({ "allowed": true, "lounge": lounge_contents() })
+} else {
+    serde_json::json!({ "allowed": false })
+};
+Ok(answer.to_string().into_bytes())
+```
+
+"Me" on that route is the player who invoked the function. A function your server invoked has no
+player, and the route refuses it with `403`. The body is `{ pass, held, ends_at }` for each pass.
+
+- **If the door and the function disagree, the function is right.** The player sees "How to get VIP"
+  or the lounge, and either way nobody got in by editing the page. Redraw the door when the function
+  says no.
+- **A guest has no VIP and cannot buy it from here.** Their door is shut, and `offers()` answers
+  `unavailable` / `sign_in_required`, so offer `gem.account.requestSignIn` instead of the button.
+
+### When the door moves by itself
+
+While something listens to `on('changed')`, the SDK reads again at each of these, and calls you only
+if the answer differs:
+
+| Moment                                                    | Why you cannot rely on something else                                      |
+| --------------------------------------------------------- | -------------------------------------------------------------------------- |
+| `store.purchase` or `store.showOffer` answers `ok`        | `onSettled` does not fire after a plain `ok`                               |
+| Either answers `unavailable` / `error`                    | The outcome is unknown, and the player may have paid                       |
+| `gem.store.onSettled` fires                               | `ok` / `pending` still reads as not held                                   |
+| Your game resumes                                         | A purchase in the Arcade's own store, from the Gem menu, sends no event at all |
+| The player signs in                                       | A guest who signs in may hold VIP                                          |
+| A held pass reaches `endsAt`                              | VIP does not renew, so the door has to lock by itself                      |
+
+A read that fails changes nothing, and is tried again later. A read that was already on its way when
+a purchase ended is never reused, so a stale answer cannot shut the door on the buyer. If you read
+without a listener, call `list()` yourself at those moments; it is always fresh.
+
+`on` never fires in a function, which has none of those moments.
+
+### On a dedicated server
+
+The platform has a read for this,
+`GET /v1/games/{game_id}/matches/{match_id}/players/{player_id}/passes`, with the same body, for a
+player in your live match. **A server bundle cannot call it yet**, and the SDK has no method for it,
+because it needs the allocation nonce: the route requires `X-Alloc-Nonce`, which the platform's
+runtime holds and never hands to your bundle. The boost read has the same limit. Reaching it takes a
+hook in the runtime, like the one behind `gem.match.end()`.
+
+Until then, decide in a function, or leave a VIP door out of a dedicated-server match.
+
+## 12. Outcomes and reasons
 
 | Call             | `ok`                      | `declined`          | `unavailable`                                                                                                 |
 | ---------------- | ------------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------- |

package/docs/changelog.md

@@ -16,6 +16,24 @@ 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.
 
+## 19.0.1
+
+Upgrading from 19.0.0. Impact: none.
+
+Nothing in this release asks anything of a game.
+
+## 19.0.0
+
+Upgrading from 18.1.1. Impact: required.
+
+### Rebuild
+
+- The player scope on the game object is now typed as PlayerScope instead of EntityScope. Recompile your game. If you annotated that value, or passed it to code that expects EntityScope, change the annotation to PlayerScope. Otherwise nothing else needs to change.
+
+### New capability
+
+- A game can now read which passes its player holds. Every pass the Arcade marks as visible to games is reported, held or not, with the time it ends. The read is exposed through PassesApi on PlayerScope, and it is not available on EntityScope because a character holds no pass. The result only tells you who holds a pass; your game still decides what the pass unlocks. PassesEvent lets you listen for changes, and the SDK re-reads after a store purchase completes, on resume, after a sign-in, and when a held pass ends, so a buyer's doors open without a reload. GamePass describes one entry in the result.
+
 ## 18.1.1
 
 Upgrading from 18.1.0. Impact: none.

package/docs/getting-started.md

@@ -50,7 +50,7 @@ either way.
 ```jsonc
 // package.json
 "dependencies": {
-  "@indiegems/gem-web-sdk": "18.1.1"
+  "@indiegems/gem-web-sdk": "19.0.1"
 }
 ```
 

package/docs/inventory-and-catalogs.md

@@ -198,6 +198,19 @@ Read every instance of a definition without walking the whole bag:
 const swords = await gem.me.inventory.instances('iron-sword');
 ```
 
+⚠️ **`instanceId` is never a key on its own.** A fungible item has one row per definition, and every
+one of those rows carries the same placeholder, `__stack__`, so all of a player's fungible items
+share one `instanceId`. A live game removed repeated rows while paging the bag by `instanceId`
+alone: only the last fungible item survived, every other look the player had bought read as not
+owned, and the game offered them for sale again. Key a row by its definition and instance
+together, and answer "does the player hold this?" from `itemDefinitionId` and `quantity`:
+
+```js
+const rowKey = (item) => `${item.itemDefinitionId}:${item.instanceId}`;
+const holds = (bag, itemDefinitionId) =>
+  bag.items.data.some((item) => item.itemDefinitionId === itemDefinitionId && item.quantity > 0);
+```
+
 ⚠️ **An item's `properties` and `customData` are untrusted, and rendering them wrong is a
 cross-player attack.** They are typed `unknown` **because the platform does not validate their
 contents** — every read of them is a parse, not a trusted object. And a transfer moves an instance

package/docs/manifest.json

@@ -18,8 +18,8 @@
     },
     {
       "file": "arcade-and-store.md",
-      "sha256": "7320826529435d290159c8b0707f69819124607d1b38160dbc85f63b385fdea9",
-      "updated": "2026-10-30T13:36:37Z"
+      "sha256": "aee6e00fa7e0f463cb09174a9afdffe10d66ed1036546e584b341e4c11bb1e27",
+      "updated": "2026-10-31T19:43:30Z"
     },
     {
       "file": "arcade-avatars.md",
@@ -48,8 +48,8 @@
     },
     {
       "file": "changelog.md",
-      "sha256": "1d0fa00863bff3d03f1670d7408e6b5133e2af0e0e945a384cb790ae59b57f59",
-      "updated": "2026-10-30T20:53:10Z"
+      "sha256": "069554f114dab51df5461c7b4e7b65339886bc0bc1c455baad83688aad3ee4fa",
+      "updated": "2026-11-02T15:26:17Z"
     },
     {
       "file": "daily-challenges.md",
@@ -78,13 +78,13 @@
     },
     {
       "file": "getting-started.md",
-      "sha256": "46d4c308ae9c44c480924c692e6c6bb172d3f5cd33d222fc4d6227c540049ffa",
-      "updated": "2026-10-30T20:53:10Z"
+      "sha256": "1175cae0795051d2b2f0d736c49e60ba455197273bcb09c3e2c565ab529be4b6",
+      "updated": "2026-11-02T15:26:17Z"
     },
     {
       "file": "inventory-and-catalogs.md",
-      "sha256": "9c898355af92ab7e17035bad964dce57b26e64624b18e83149b88ae10b96fd9c",
-      "updated": "2026-10-30T13:36:37Z"
+      "sha256": "a4763fe2418c0e24639ca58c27f30ffc416f07528857402a6f9ab3fee147f4f6",
+      "updated": "2026-11-01T21:49:36Z"
     },
     {
       "file": "leaderboards.md",
@@ -138,8 +138,8 @@
     },
     {
       "file": "server-bundles.md",
-      "sha256": "37c9b544d3c2d7aca21ef1319f385188971975a133f306cea20aedf110f5244a",
-      "updated": "2026-10-30T20:53:10Z"
+      "sha256": "e3e49043fa4c6744df9c7f4c5e901511a4e9832d7f46f6880f1995648bacbf09",
+      "updated": "2026-11-02T15:26:17Z"
     },
     {
       "file": "serverless-functions-js.md",
@@ -163,8 +163,8 @@
     },
     {
       "file": "what-a-game-must-do.md",
-      "sha256": "8faa9ef2cef2a5eb73cf95d7c52af914325c2bc26834625c9cb4b5748eecc616",
-      "updated": "2026-10-30T14:09:09Z"
+      "sha256": "17df2ebdafe56ac5eafdf4eba783c97025ddd9e0ee88b7b43d25718908496b2a",
+      "updated": "2026-11-02T14:57:41Z"
     }
   ]
 }

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/v18.1.1/gem-web-sdk.tgz
-curl -fsSL https://downloads.gemarcade.com/sdk/v18.1.1/gem-web-sdk.tgz.sri
+curl -fsSL -O https://downloads.gemarcade.com/sdk/v19.0.1/gem-web-sdk.tgz
+curl -fsSL https://downloads.gemarcade.com/sdk/v19.0.1/gem-web-sdk.tgz.sri
 openssl dgst -sha384 -binary gem-web-sdk.tgz | openssl base64 -A
 ```
 
@@ -829,6 +829,12 @@ The short version: the browser half is what a player's **session** can do, and t
 what a **match** can do. `gem.rooms.join()` has no meaning to a process that exists because a match
 was already allocated.
 
+**`gem.me.passes` is browser and function only**, and that is a limit rather than a principle. The
+platform has a match read of which passes a player in your match holds, but your bundle cannot call
+it: it requires the allocation nonce, which the runtime never hands to a bundle, as the boost read
+does, and it answers `403` to every caller until game servers are granted `passes.read`.
+[arcade-and-store.md](arcade-and-store.md#on-a-dedicated-server) has what to do instead.
+
 **Rooms are the case where those two answers differ**, so they are worth stating separately rather
 than filed under "browser-only". `gem.rooms` — join, leave, ready up, quick-join — is a player
 acting on their own membership, and your server has none. Reading and administering the room your

package/docs/what-a-game-must-do.md

@@ -1687,7 +1687,8 @@ startMusic(ctx); // start it now: it plays at once where sound is allowed, and f
 // context say when it is running rather than deciding from the first read.
 const LIFTS = ['pointerup', 'touchend', 'click', 'keydown'];
 const unlock = () => {
-  if (ctx.state === 'suspended') void ctx.resume();
+  // 'interrupted' is how some WebKit versions report a context iOS is holding.
+  if (ctx.state === 'suspended' || ctx.state === 'interrupted') void ctx.resume();
 };
 const settled = () => {
   if (ctx.state !== 'running') return;
@@ -1703,6 +1704,26 @@ if (ctx.state !== 'running') {
 A `<audio>` or `<video>` element works the same way. Call `play()` straight away, and only if it
 rejects, call it again from the first lift.
 
+**Coming back from the background is the SDK's.** On an iPhone, a player who swipes your game away
+and comes back finds its sound cut off: iOS leaves the `AudioContext` `suspended` or `interrupted`,
+stops your media elements, and restarts neither. The snippet above has stopped listening by then, so
+the SDK does this part for you. After the page was hidden, or a context left `running` without your
+asking, it listens again for the player's next lift in your frame, resumes the contexts that were
+running and replays the elements that were playing when the sound was cut off, then stops
+listening. You write nothing for it. It stays out of your way:
+
+- **A context you `suspend()` yourself is left alone** until you call `resume()`. If you pause your
+  audio when the page is hidden and resume it when it comes back, keep doing that: the SDK steps in
+  only when your own resume did not take, which on iOS it often does not without a tap.
+- **An element you `pause()` is not replayed**, and nothing is restarted while the Arcade has your
+  game paused: your `onPause(false)` handler decides what plays when the menu closes.
+- **The Arcade's mute still holds.** A context the SDK resumes is still silent while the player has
+  the Arcade muted.
+
+It reaches the audio the mute does: created after `createGem`, with `manageAudio` left on. With
+`manageAudio: false` it is yours: listen for the lift again on `visibilitychange` and on the
+context's `statechange`, rather than once.
+
 Never block the first frame on audio, never show an error for it, and do not ask the player to "tap
 to start" just to unlock sound.
 

package/package.json

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