@indiegems/gem-web-sdk 24.0.2 → 24.1.0

package/docs/arcade-and-store.md

@@ -318,9 +318,8 @@ game never names a SKU ([below](#a-pass-by-its-slug-showpass)). `showOffer(skuId
 sheet for any other SKU, such as a bundle.
 
 `showOffer(skuId)` asks the Arcade to draw one SKU from `offers()` in its own sheet, over your paused
-and hidden game. The Arcade draws the art, what the player gets, a sale if one is running, and, for a
-pass the player already holds, how long it has left. The sheet's Buy opens the same checkout
-`purchase` opens.
+and hidden game. The Arcade draws the art, what the player gets and a sale if one is running. The
+sheet's Buy opens the same checkout `purchase` opens.
 
 Pick by who can say what the offer is:
 
@@ -330,20 +329,24 @@ Pick by who can say what the offer is:
 | Your button     | says what it buys and shows `priceDisplay`           | says what it opens, such as "Get VIP"                           |
 | The press opens | the checkout, straight away                          | the Arcade's sheet, then the checkout if the player presses Buy |
 | Perks and sales | not available to you                                 | always current, in the player's language                        |
-| A holder sees   | the same Buy button                                  | what they already have, and how to add time                     |
+| A held pass     | your button cannot tell                              | the Arcade decides whether the holder is offered it again       |
 
 - **Never write an offer's perks into your game.** They change without a new build of your game, and
   yours would go stale. Your button only needs the offer's name.
 - **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`.
-- **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)).
+- **The sheet does not tell you what the player holds.** To change your own screen for a holder,
+  read `gem.me.passes` ([§11](#11-what-the-player-holds-and-a-vip-door)).
+- **A player who already holds a pass may or may not be offered it again.** The Arcade decides,
+  and your game must not assume either. `passOnSale` answers for a holder as it does for anyone:
+  where it is `false`, `showPass` answers `unavailable` / `not_found` and opens nothing.
 - **Hide the button when the pass is not on sale.** `passOnSale(slug)` says so, and is `false`
-  where the store is off, for a player the platform won't sell it to, once the player has declined
-  its sheet twice today, and on an older Arcade. A pass that is not on sale answers
-  `unavailable` / `not_found`, and the player would have pressed a button that does nothing.
+  where the store is off, for a player the platform won't sell it to, and on an older Arcade. A
+  player closing its sheet never takes it off sale. A pass that is not on sale answers
+  `unavailable` / `not_found`, and the player would have pressed a button that does nothing. To
+  test as a VIP holder before VIP is on sale, give yourself VIP with gemctl
+  ([§11](#testing-what-a-vip-player-sees)).
 - **Read `showOfferAvailable`, not `available`.** An older Arcade can sell through `purchase` and
   still not draw this sheet. It answers `unavailable` / `unsupported` and sends nothing. Hide the
   button there.
@@ -351,9 +354,10 @@ Pick by who can say what the offer is:
 Every rule of `purchase` holds ([§9](#9-buying-from-the-arcade-store)), and the answers are the
 same, with one addition. `declined` / `cancelled` also covers the player leaving the sheet without
 pressing Buy, and you are not told which of the two they closed. Nothing backs off: the player's
-next press on either button opens it again. A pass is the exception: after the player declines its
-sheet **twice in a day**, the Arcade stops offering it to them until tomorrow, and `passOnSale`
-answers `false`. Your game cannot reset that count.
+next press on either button opens it again. That holds for a pass too: **there is no limit on how
+often your game opens a pass's sheet**, and a player closing it any number of times leaves
+`passOnSale` and `upsells` as they were. The Arcade records how often each pass sheet is opened in
+your game and how long it stays open, for reporting; it never uses that to stop an offer.
 
 ### A pass, by its slug: `showPass`
 
@@ -376,7 +380,8 @@ something:
   answers `ok` like anyone else.
 - **After a paid sheet it waits a little.** It reads `gem.me.passes` for about ten seconds before it
   settles for `pending`, because the payment provider's notice can trail the checkout.
-- **A player who already holds the pass** sees how long they have left and can add time.
+- **A player who already holds the pass** may or may not be offered it again. Where they are not,
+  the answer is `unavailable` / `not_found`, as for any pass that is not on sale to the player.
 
 ### At a reward: the VIP extra roll
 
@@ -393,7 +398,7 @@ openButton.onclick = async () => {
   const upsell = preview.upsells[0];
   if (upsell) {
     // "VIP: +1 roll, 45 Coins" — upsell.name, and the extras locked, never what a roll would land on.
-    const choice = await vipCard.ask(upsell); // Get VIP and Continue, with equal weight
+    const choice = await vipCard.ask(upsell); // Get VIP, or Continue
     if (choice === 'get') await gem.store.showPass(upsell.pass);
     openButton.focus(); // focus goes back where it was
   }
@@ -403,11 +408,11 @@ openButton.onclick = async () => {
 ```
 
 `upsells` is already empty wherever no upsell may be shown: for a minor, a store that is off, a pass
-the player declined twice today or already holds, and a claim no pass would change. So an empty
-list means draw no card. **Upsell only before the grant**, once per reward moment: the platform
-holds nothing back, so a pass bought afterwards cannot reach a chest already opened.
+the player already holds, and a claim no pass would change. A player declining a pass's sheet does
+not empty it. So an empty list means draw no card. **The offer comes before the grant**: the
+platform holds nothing back, so a pass bought afterwards cannot reach a chest already opened.
 [inventory-and-catalogs.md](inventory-and-catalogs.md#offering-vip-before-a-reward-the-upsell) has
-the rest of the rules, every one a must, and `bonuses` in full.
+how the upsell works, the one rule for it (disclose a bonus roll's odds), and `bonuses` in full.
 
 ## 11. What the player holds, and a VIP door
 
@@ -416,7 +421,7 @@ const passes = await gem.me.passes.list();
 // [{ pass: 'vip', held: true, daysLeft: 7, endsAt: '2026-11-29T12:34:56Z' }]
 
 const vip = await gem.me.passes.get('vip'); // one pass by its slug
-if (vip.held) drawVipBadge(vip.daysLeft === 7 ? '7+ days left' : `${vip.daysLeft} days left`);
+if (vip.held) drawVipBadge(vip.daysLeft < 7 ? `VIP · ${vip.daysLeft} days left` : 'VIP');
 ```
 
 `gem.me.passes` says which store passes the player holds. **VIP is the pass `vip`**, its offering
@@ -428,8 +433,9 @@ slug. Key on the slug, which is stable and not localized, and never on a display
 - **A pass is a slug, whether it is held, and how many days it has left.** No price, no name, no
   perks, nothing about how the player got it, and nothing about a pass that has ended.
 - **`daysLeft` is whole days, rounded up and capped at 7**: `7` means "7 or more", and is also what
-  a pass held with no end reads (support can grant one). `0` when it is not held. Show `7` as
-  "7+ days left", never as a date.
+  a pass held with no end reads (support can grant one). `0` when it is not held. **`7` is not a
+  week's notice:** a pass can read `7` for as long as it is held, and a lower count can rise again.
+  Show a count only below `7`, or show `7` as "7+ days left". Never show a date.
 - **`endsAt` is deprecated.** It is the exact end, to the second, and two games could match that
   value to link one player's accounts, so the platform will stop sending it. Use `daysLeft`.
 - **A guest holds nothing.** When the Arcade says the player is a guest, every pass reads
@@ -579,6 +585,26 @@ export default defineServer((gem) => ({
 `gem.match.playerBoost(playerId)` reads the player's Boost for **display** — "2x Coins" on a results
 screen — never for a decision.
 
+### Testing what a VIP player sees
+
+VIP may not be on sale where you test yet, so `passOnSale('vip')` reads `false` and you cannot buy
+it to test your door, badge or upsell. Give it instead, for 1 to 30 days, with gemctl:
+
+```sh
+gemctl org test-accounts pass grant <org-id> me vip --days 7            # your own account
+gemctl org test-accounts pass grant <org-id> "Playtest 3" vip --days 7  # one of the org's test accounts
+```
+
+- **You need the Contributor role or above** in the organization. `me` reaches your own account and
+  no one else's; any other name is one of the organization's test accounts.
+- **It is not a purchase.** VIP held this way reads like a bought one in `gem.me.passes`,
+  `gem.match.playerPasses` and a `holds_pass` requirement, but no purchase is recorded, it is never
+  revenue, and nothing renews it: it ends after the days you gave.
+- **One VIP at a time per account.** An account that already holds VIP, granted or bought, is
+  refused until it ends. The organization's audit log records every grant.
+- **A personal access token is refused:** sign in to gemctl as yourself.
+  `gemctl org test-accounts pass grant --help` has the rest.
+
 ## 12. Outcomes and reasons
 
 | Call              | `ok`                      | `declined`          | `unavailable`                                                                                                 |

package/docs/changelog.md

@@ -17,6 +17,30 @@ A release opens with a short summary of what it is about, and its entries are gr
 - **New capability**: something a game can now do. Nothing changes unless you use it.
 - **Fixes and improvements**: bugs fixed and behaviour improved without a change to the API. Nothing to change in your game.
 
+## 24.1.0
+
+Upgrading from 24.0.2. Impact: required.
+
+Declining a pass's sheet no longer takes the pass off sale, so a game may open a pass's sheet as often as it likes. A held pass may or may not be offered again, so a game should follow `passOnSale` and assume neither. The only API change is the parent conformance kit version, which moves from 9 to 10 and asks a game to change nothing beyond a rebuild.
+
+### Rebuild
+
+- `PARENT_CONFORMANCE_VERSION` is now `10` instead of `9`. This constant belongs to the parent conformance kit, which Arcade parents use. A game does not use it, and no message, field, outcome or offer kind was added. Recompiling is enough, and no adapter member is new. A parent that passed kit 9 passes kit 10 unchanged.
+
+  Only code that compares this constant to the literal `9` needs updating:
+
+  ```ts
+  // before
+  if (PARENT_CONFORMANCE_VERSION === 9) { /* ... */ }
+  // after
+  if (PARENT_CONFORMANCE_VERSION === 10) { /* ... */ }
+  ```
+
+### Fixes and improvements
+
+- Declining a pass's sheet no longer takes the pass off sale. `passOnSale` and the reward preview's `upsells` no longer change after declines, and there is no daily limit on pass offers. The Arcade now records how often a sheet is opened and how long it stays open, for reporting only. Remove any game logic that assumed a pass would stop being offered after two declines.
+- Whether a player who already holds a pass is offered it again is the parent's decision. A pass left out of the holder's listing answers `gem.requestStoreOfferSheet` with one `unavailable` and shows nothing. A pass in the listing opens exactly one sheet. Follow `passOnSale` for a holder as you would for anyone. Do not keep a "Get VIP" button up for a holder on the assumption that its sheet will open, and do not assume a pass lasts 30 days.
+
 ## 24.0.2
 
 Upgrading from 24.0.1. Impact: none.

package/docs/getting-started.md

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

package/docs/inventory-and-catalogs.md

@@ -1208,23 +1208,36 @@ now without the bonus. `declined` or `unavailable` means run it as it is — and
 `error` may still mean the player paid, so read `gem.me.passes` again rather than telling them
 they did not.
 
-`upsells` is empty for a minor, a store that is off, a pass the player declined twice today or
-already holds, and anywhere the store sells no pass: draw nothing then. A guest **does** get
+`upsells` is empty for a minor, a store that is off, a pass the player already holds, and anywhere
+the store sells no pass: draw nothing then. Declining a pass's sheet does not empty it: there is no
+limit on how often a game offers a pass. A guest **does** get
 upsells, and buying takes them through sign-up first.
 
-**The rules, every one a must:**
-
-- **Upsell only before granting**, and at most once per reward moment. Never after.
-- **Give Get VIP and Continue equal weight.** Neither is the default, the larger or the brighter.
-- **Never show the outcome of a locked roll.** Show "+1 roll", never what it would land on.
-- **Disclose the odds** for a bonus roll, as for any roll ([§12](#12-loot-tables-and-odds)).
-- **No countdowns, no "expires" pressure, and no price** in your game. The Arcade's sheet shows the
-  price.
-- **Show a lock as an icon plus text**, never colour alone.
-- **Return focus to the button** that opened the sheet when it closes.
-- **Announce an applied bonus in a polite live region** (`aria-live="polite"`).
-- **Use the preview's numbers and `upsell.name`**, never your own copy of them, and never a
-  literal `'vip'`: pass `upsell.pass` straight to `showPass`.
+**How it works:**
+
+- **The offer comes before the grant.** That is the point of the upsell: a bonus applies only if the
+  player holds VIP when the claim runs, and the platform holds nothing back, so a pass bought after
+  the grant cannot reach a reward already given.
+- **The numbers and the name come from the preview.** Show the preview's numbers and `upsell.name`
+  rather than your own copy of them, and pass `upsell.pass` straight to `showPass` rather than a
+  literal `'vip'`: what is on sale, and what it adds, can change without a release of your game.
+- **The price comes from the Arcade's sheet.** It varies by player and by sale, so your game does not
+  hard-code one; the sheet shows it.
+- **A locked roll shows as "+1 roll", not what it would land on.** The roll has not happened: it
+  happens when the recipe runs.
+
+**The one rule: disclose the odds** for a bonus roll, as for any roll
+([§12](#12-loot-tables-and-odds)). Store rules require it for a paid random item (Apple's App Store
+Review Guideline 3.1.1 among them).
+
+**Recommended, for accessibility:**
+
+- Show a lock as an icon plus text, not colour alone.
+- Return focus to the button that opened the sheet when it closes.
+- Announce an applied bonus in a polite live region (`aria-live="polite"`).
+
+The card itself is your game's design: how it looks, which button leads and when it appears. The
+platform sets no rule on them.
 
 ### Reading the player's balance
 

package/docs/manifest.json

@@ -18,8 +18,8 @@
     },
     {
       "file": "arcade-and-store.md",
-      "sha256": "73e77f3bd0124f69d53b42714fb24c7d128dd1be97e203fc3a353a8eb4e3c05a",
-      "updated": "2026-11-11T01:56:34Z"
+      "sha256": "d5b3d7753bf00b87d39f16741e743605214059d4b4a499a69b3a5e7350ec288f",
+      "updated": "2026-11-13T00:22:09Z"
     },
     {
       "file": "arcade-avatars.md",
@@ -48,8 +48,8 @@
     },
     {
       "file": "changelog.md",
-      "sha256": "ccf9d26452dc123e538db582efb0b9103b675f41f0411e8b337180066d903ffe",
-      "updated": "2026-11-11T23:12:40Z"
+      "sha256": "8339a777114f7d8ad7acfcc61d47af25b3e027dc3bdc42c092e9064bd578f78e",
+      "updated": "2026-11-13T03:35:34Z"
     },
     {
       "file": "daily-challenges.md",
@@ -78,8 +78,8 @@
     },
     {
       "file": "getting-started.md",
-      "sha256": "b383f4297e9ca5218c8baff9c9cec499a898bee69298072617dcc75caf4bab9e",
-      "updated": "2026-11-11T23:12:40Z"
+      "sha256": "35401b63060f02364bad539eef2718c5907e8e418b0456582759b65e2313bbe2",
+      "updated": "2026-11-13T03:35:34Z"
     },
     {
       "file": "graphics-route.md",
@@ -88,8 +88,8 @@
     },
     {
       "file": "inventory-and-catalogs.md",
-      "sha256": "22998fb3ff26d4f9f29d2a73ce6db0ccf42ca2b635f171023a2e2214bbea4b1a",
-      "updated": "2026-11-11T01:56:34Z"
+      "sha256": "f32ea4291e47763e7ec664f1c1fee71e0cd1b443f4c617194ab3d27f556aec79",
+      "updated": "2026-11-13T00:16:49Z"
     },
     {
       "file": "leaderboards.md",
@@ -113,8 +113,8 @@
     },
     {
       "file": "platform-rules.md",
-      "sha256": "e9cb3cf1945002d182d917b0f3f7cfdf26f41de9ec9cd34a47c487cb4c615152",
-      "updated": "2026-11-11T01:56:34Z"
+      "sha256": "ba07fc48837dce46500478ae958e03394e7af9650f8314a1868d30e4c3b70354",
+      "updated": "2026-11-12T20:29:05Z"
     },
     {
       "file": "player-sign-in.md",
@@ -143,8 +143,8 @@
     },
     {
       "file": "server-bundles.md",
-      "sha256": "82553b28eeb8290771fb39afee1906465350a7be123c21aba3a047261f800b64",
-      "updated": "2026-11-11T23:12:40Z"
+      "sha256": "4eca8bb4a1b9018257bb9411ecaf3e65cdef472d8b0cc5653b49ab991680eb6c",
+      "updated": "2026-11-13T03:35:34Z"
     },
     {
       "file": "serverless-functions-js.md",

package/docs/platform-rules.md

@@ -357,8 +357,9 @@ A game **must not gate** anything on the multiplier:
 `requires: [{ kind: 'holds_pass', pass: 'vip' }]` on the item, recipe, bonus or track, which the
 platform checks when it runs; or a decision your function or server makes from its pass read
 (`gem.me.passes` in a function, `gem.match.playerPasses` on a server). The browser's
-`gem.me.passes` draws the door; it never opens it. Offer VIP only before a reward, by the rules in
-[inventory-and-catalogs.md](inventory-and-catalogs.md#offering-vip-before-a-reward-the-upsell).
+`gem.me.passes` draws the door; it never opens it. To offer VIP at a reward, offer it before the
+grant, as [inventory-and-catalogs.md](inventory-and-catalogs.md#offering-vip-before-a-reward-the-upsell)
+describes.
 
 Three reasons not to gate on the multiplier, any one of which would be enough. It is **advisory**:
 the browser value is pushed on connect and on change, so it can lag, and the platform's own figure

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/v24.0.2/gem-web-sdk.tgz
-curl -fsSL https://downloads.gemarcade.com/sdk/v24.0.2/gem-web-sdk.tgz.sri
+curl -fsSL -O https://downloads.gemarcade.com/sdk/v24.1.0/gem-web-sdk.tgz
+curl -fsSL https://downloads.gemarcade.com/sdk/v24.1.0/gem-web-sdk.tgz.sri
 openssl dgst -sha384 -binary gem-web-sdk.tgz | openssl base64 -A
 ```
 

package/package.json

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

package/schema/bridge.v1.json

@@ -6099,11 +6099,15 @@
         "multipliers it carries in `earnMultipliers`, so a game can find VIP by",
         "slug and preview what it would add without naming a SKU or a number.",
         "A parent lists a pass only where it would open that pass's sheet: an",
-        "offering with `visible_to_games`, to a player who has not declined",
-        "its sheet twice today. For a KNOWN MINOR it leaves the pass out",
+        "offering with `visible_to_games`. A player declining its sheet never",
+        "takes it out of the listing. For a KNOWN MINOR it leaves the pass out",
         "exactly as if it were not on sale - the same `ok`, the same other",
         "offers, no reason - so a game can never tell a minor from a pass that",
-        "is not sold here. A holder still sees it: the sheet adds time.",
+        "is not sold here. A HOLDER may be listed the pass or not, as the",
+        "parent's store decides, and a frame must not assume either. The rule",
+        "is only that the sheet follows the listing: a listed pass opens its",
+        "sheet, and gem.requestStoreOfferSheet for a pass that is not listed is",
+        "answered `unavailable` with nothing shown.",
         "",
         "COIN PACKS ARE `gem_pack`. The kind enum is closed (a fifth value",
         "would be refused whole by an N-1 frame), so a pack of any platform",