@indiegems/gem-web-sdk 15.3.2 → 16.0.0

package/docs/arcade-and-store.md

@@ -0,0 +1,289 @@
+# Arcade features and the Arcade Store
+
+Your game can reach a few things the Arcade owns: its own app and yours in the app stores, another
+game, games like yours, and the **Arcade Store**, which sells Gem packs, Boosts, passes and
+bundles for real money.
+
+```js
+// From the press on your own "More games like this" card.
+async function onCardPressed(card) {
+  await saveNow(); // the Arcade gives you a short grace, not a long one
+  const { outcome } = await gem.arcade.openGame(card.gameId);
+  if (outcome !== 'ok') showCardAsUnavailable(card);
+}
+
+// From the press on your own "Get Gems" button.
+async function onBuyPressed(offer) {
+  const { outcome, reason } = await gem.store.purchase(offer.skuId);
+  // Read through gem.me; nothing here carries an amount. `error` is "outcome unknown" (§9).
+  if (outcome === 'ok' || reason === 'error') await refreshBalances();
+}
+```
+
+**Your game asks; the Arcade decides.** Nothing your game sends carries a URL, a price or a card
+field. The Arcade builds every link, reads every price, draws every purchase sheet and takes the
+payment itself. You get an outcome.
+
+- [1. Two surfaces, and which one is real money](#1-two-surfaces-and-which-one-is-real-money)
+- [2. Nothing rejects](#2-nothing-rejects)
+- [3. What is available here](#3-what-is-available-here)
+- [4. Call the acting ones from a press](#4-call-the-acting-ones-from-a-press)
+- [5. App links](#5-app-links)
+- [6. Opening another game](#6-opening-another-game)
+- [7. Similar games, as cards](#7-similar-games-as-cards)
+- [8. The Arcade Store's offers](#8-the-arcade-stores-offers)
+- [9. Buying from the Arcade Store](#9-buying-from-the-arcade-store)
+- [10. Outcomes and reasons](#10-outcomes-and-reasons)
+
+## 1. Two surfaces, and which one is real money
+
+|              | **`gem.arcade`**                                 | **`gem.store`**                                 |
+| ------------ | ------------------------------------------------ | ----------------------------------------------- |
+| What it does | app-store listings, another game, similar games  | the Arcade Store's own SKUs                     |
+| Money        | none                                             | **real money**, through the Arcade's own sheet  |
+| Who draws it | the Arcade (a new tab, a QR code, the next game) | the Arcade Store's sheet, over your paused game |
+
+`gem.store` is not `gem.purchases`. **`gem.purchases` spends Gems or Coins on your game's own
+items** ([`inventory-and-catalogs.md`](inventory-and-catalogs.md)). **`gem.store` sells the Arcade
+Store's own SKUs for the player's money.** A game that wants a "Get Gems" button uses `gem.store`;
+a game selling a sword for 50 Gems uses `gem.purchases`.
+
+## 2. Nothing rejects
+
+Every call resolves `{ outcome, reason? , ... }`, and none of them ever rejects. `outcome` is one of
+three and never grows:
+
+- `ok`: it happened.
+- `declined`: it did not, because of a choice or a rule (the player said no, or another sheet was
+  open).
+- `unavailable`: it cannot happen here.
+
+`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 [§10](#10-outcomes-and-reasons).
+
+## 3. What is available here
+
+An Arcade that does not offer a feature answers every call for it at once with `unavailable` /
+`unsupported`, and sends nothing. Read availability before you draw a button for it:
+
+```js
+if (gem.arcade.available.openGame) showMoreGamesSection();
+if (gem.arcade.available.appLinks) showGetTheAppButton();
+if (gem.store.available) showGetGemsButton();
+```
+
+`gem.arcade.available` is `{ appLinks, openGame }`, and `gem.store.available` is one boolean. All of
+them are synchronous and `false` until the bridge is up. A feature can be off for reasons you
+cannot see from inside the frame: a TV, an in-app browser that cannot take payment, an app build
+where it is withheld. Do not guess; read it.
+
+## 4. Call the acting ones from a press
+
+Three calls put something in front of the player: `gem.arcade.openApp`, `gem.arcade.openGame` and
+`gem.store.purchase`. **Call each one from the player's own press handler**, in the same turn as the
+press. The Arcade checks that a person pressed, and refuses an ask nobody pressed for with
+`declined` / `busy`, showing nothing.
+
+- **Controllers count.** A gamepad press the Arcade sees counts as a press. Do not add a keyboard or
+  pointer workaround for pad players.
+- **One at a time.** Only one of these is open at once, across both surfaces and the Arcade's other
+  sheets (a Gem purchase, a share, a friend challenge). A second ask while one is open is
+  `declined` / `busy`. The SDK answers it for you without sending.
+- **Never on a timer, never on load, never in a retry loop.** None of them would have a press, so
+  all of them would be refused.
+
+The reads (`appLinks`, `similarGames`, `offers`) need no press. A second call while one is open
+shares the first one's answer.
+
+## 5. App links
+
+```js
+const links = await gem.arcade.appLinks();
+if (links.outcome === 'ok') {
+  if (links.arcade) drawStoreBadge('arcade', links.arcade.store); // 'app_store' | 'google_play'
+  if (links.game) drawStoreBadge('game', links.game.store);
+}
+
+// From the badge's press:
+const { outcome, reason } = await gem.arcade.openApp('arcade'); // or 'game'
+```
+
+`appLinks()` tells you which listings the Arcade can open from here, **by store, never by URL**, so
+you can draw the right badge. `arcade` is the Gem Arcade app; `game` is your game's own app, when
+one is registered for it. Either may be missing; draw only what is there.
+
+`openApp(target)` opens one. It answers `ok` when the listing opened, `ok` / `handed_off` when the
+Arcade showed a QR code for a phone instead (on a TV, say), and `unavailable` / `already_in_app`
+when the player is already in that app.
+
+The answer comes **at the hand-off**: as the listing opens, or as the QR sheet goes up. It never
+waits for the player to close the sheet, and you are not told when they do. While the sheet is up
+it still counts as the open acting ask, so another `openApp`, `openGame` or `store.purchase` is
+`declined` / `busy` until the player closes it.
+
+## 6. Opening another game
+
+```js
+const { outcome, reason } = await gem.arcade.openGame('star-hopper'); // a game id or its web address
+```
+
+`ref` is a game's id or its web-address slug, lower-case letters, digits and hyphens. The Arcade
+looks the game up, answers `ok`, and then **your game is closing**: it gets the same short save
+grace as any exit, and the next game starts.
+
+- **Save ahead of time.** The grace is 250 ms, and your game also gets the usual termination
+  notice. Autosave before you call `openGame`, not after.
+- `unavailable` / `not_found` covers a game that does not exist, is hidden, or cannot run here. The
+  Arcade does not say which.
+- `declined` / `same_game` is your own game.
+- **Back** in the Arcade takes the player to your game's page, with Play. It never relaunches your
+  game by itself.
+
+## 7. Similar games, as cards
+
+```js
+const { outcome, games } = await gem.arcade.similarGames({ limit: 6 }); // 1..24, default 12
+if (outcome !== 'ok' || games.length === 0) hideMoreGamesSection();
+for (const game of games) drawCard(game);
+```
+
+Each card carries the game's `gameId` and, when it has one, its `slug`; its `name`, `tagline`,
+`shortDescription` and `tags`; and art: `iconUrl`, `capsuleLandscapeUrl`, `capsulePortraitUrl`,
+and, when the Arcade judges a clip is welcome here, `previewVideoUrl` with `previewPosterUrl`.
+Pass `gameId` to `openGame` when the card is pressed.
+
+**Hide the section when there are no results.** An empty "More games" row is worse than none.
+
+### The text is not yours
+
+`name`, `tagline`, `shortDescription` and each tag are `PlayerText`, as a player's name is: another
+developer wrote them. **Render them as text only**: `text.toPlain(game.name)` into `textContent`,
+never into `innerHTML`, never into a template that parses markup. A name may legitimately contain
+`<` or `&`.
+
+### Drawing a card the way the Arcade does
+
+Cards in your game should behave like the tiles on the Arcade's home page:
+
+- **The clip starts after 450 ms of hover, or of keyboard or pad focus. Never on touch.** One card
+  plays at a time.
+- **The `<video>` exists only while it plays.** Create it when the clip starts and remove it when it
+  stops. It is `muted`, `playsinline`, has no `controls`, shows `previewPosterUrl` until it plays,
+  and stops on blur or when the pointer leaves.
+- **No `previewVideoUrl` means no clip.** The Arcade leaves it out under reduced motion, data saver
+  and on phones, which your frame cannot always see. Show the poster or the capsule.
+- **The accessible name is "{name}, opens game"**, with `{name}` from `text.toPlain(game.name)`.
+- **Your page's Content-Security-Policy must allow the hosts the Arcade's art comes from**, in
+  `img-src` and `media-src`, or every card is blank. See [the media hosts](#the-media-hosts). Load
+  the art with `crossOrigin = 'anonymous'` if a WebGL game draws it into a canvas.
+
+### The media hosts
+
+Card art, preview clips and posters, and an offer's `imageUrl` are URLs the platform hands you.
+Allow the hosts it returns. On the Arcade, today, those are two:
+
+- **`https://downloads.gemarcade.com`, the public copy.** An offer's `imageUrl` is always on it,
+  and released card art and clips move there once the platform has published a public copy.
+- **`https://gemsprodeastus2a.blob.core.windows.net`, signed art**: a card's art and clip before
+  the public copy lands.
+
+Similar games are released games, so their cards come from these two hosts wherever your game
+talks to the Arcade: `gemctl serve` and the Project Editor too, when they are signed in to it.
+
+**Name each host exactly. Never allow `https://*.blob.core.windows.net`**: that wildcard is every
+Azure customer's storage, not the Arcade's.
+
+A non-production backend serves its art from hosts of its own. These hosts are infrastructure, and
+they can change: art that will not load is the sign, and the browser's console names the host your
+policy refused. Allow that host rather than a wildcard.
+
+## 8. The Arcade Store's offers
+
+```js
+const { outcome, reason, offers } = await gem.store.offers();
+if (outcome === 'unavailable' && reason === 'sign_in_required') showSignInButton(); // gem.account.requestSignIn
+for (const offer of offers) drawOffer(offer);
+```
+
+`offers()` lists what the Arcade Store sells this player, here, right now: Gem packs, Boosts,
+passes and bundles. Each offer has a `skuId`, a `kind` (`gem_pack`, `boost`, `pass` or `bundle`),
+the store's own `name` and `description`, an optional `imageUrl`, a `priceDisplay`, and, for a
+Gem pack, a `grant` naming the currency and amount.
+
+- **Show `priceDisplay` exactly as given.** It is the payment rail's own price in the player's
+  currency, already formatted. Never parse it, compare two of them, or compute a discount from it.
+  There is no numeric price.
+- **Re-read offers when your game resumes.** What is on sale can change while the player is away.
+- **Do not imitate the Arcade's chrome.** Your offer list is yours to style; the sheet that takes
+  the money is the Arcade's, and a game that draws something that looks like it confuses players
+  about which one is real.
+- `unavailable` / `store_off` means the store is not offered here (a TV, an in-app browser that
+  cannot take payment, a build where it is withheld). Hide your store button.
+
+## 9. Buying from the Arcade Store
+
+```js
+// From the press on your offer's Buy button.
+const { outcome, reason } = await gem.store.purchase(offer.skuId);
+```
+
+`purchase(skuId)` asks the Arcade to open its store's sheet for one SKU from `offers()`. The Arcade
+pauses your game, shows the offer with its own price, and takes the payment on the provider's page
+or the operating system's purchase sheet. Your game is resumed before the answer arrives, so your
+own celebration is visible.
+
+- **Call it from the press** ([§4](#4-call-the-acting-ones-from-a-press)).
+- **It has no timeout.** A payment takes as long as it takes, so the call waits for as long as the
+  Arcade is connected.
+- `ok`: the player paid. **Read balances and inventory through `gem.me`**; the answer carries no
+  amount.
+- `ok` / `pending`: the player paid and the provider has not settled yet. Listen with
+  `gem.store.onSettled`, and also re-read balances when your game resumes, because a purchase can
+  settle while your game is not running:
+
+  ```js
+  const stop = gem.store.onSettled(({ skuId }) => refreshBalances());
+  ```
+
+- `declined` / `cancelled`: the player closed the sheet. Return to your screen quietly and **do not
+  ask again unprompted**: the Arcade backs off after a dismissal, and the next ask is
+  `declined` / `busy` for a while.
+- `unavailable` with `store_off`, `sign_in_required` or `not_found` (a SKU that is not in
+  `offers()` right now), or with a payment provider's own failure code: nothing was bought. The
+  first three show nothing.
+- `unavailable` / `error`: **the outcome is unknown, and the player may have paid.** You get it
+  when the bridge to the Arcade closes while the sheet is open, which can happen after the payment
+  went through, and when the Arcade has no reliable answer. Never tell the player nothing was
+  bought. Re-read balances and inventory through `gem.me`, keep your `gem.store.onSettled`
+  listener, and re-read again when your game resumes:
+
+  ```js
+  if (outcome === 'unavailable' && reason === 'error') await refreshBalances(); // not "nothing bought"
+  ```
+
+## 10. Outcomes and reasons
+
+| Call             | `ok`                      | `declined`          | `unavailable`                                                                                                 |
+| ---------------- | ------------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `appLinks`       | listings to draw          |                     | `unsupported`, `error`                                                                                        |
+| `openApp`        | opened, or `handed_off`   | `busy`              | `already_in_app`, `unsupported`, `error`                                                                      |
+| `openGame`       | the next game is starting | `busy`, `same_game` | `not_found`, `unsupported`, `error`                                                                           |
+| `similarGames`   | cards, possibly none      |                     | `unsupported`, `error`                                                                                        |
+| `store.offers`   | offers, possibly none     |                     | `sign_in_required`, `store_off`, `unsupported`, `error`                                                       |
+| `store.purchase` | paid, or `pending`        | `cancelled`, `busy` | `sign_in_required`, `store_off`, `not_found`, the provider's reason, `unsupported`, `error` (outcome unknown) |
+
+Every reason is a short code of lower-case letters and underscores. The Arcade turns a payment
+provider's own code into that shape before it reaches you.
+
+Four reasons come from the SDK itself rather than the Arcade:
+
+- `unsupported`: this Arcade does not offer the feature. Nothing was sent.
+- `invalid_argument`: the SDK refused the argument (an unknown `target`, a `ref` that is not an id
+  or a web address, a `limit` outside 1–24, an empty `skuId`). Nothing was sent.
+- `busy`: another acting ask from your game is still open. Nothing was sent.
+- `error`: no reliable answer arrived. The ask could not be sent, a read or an open waited out its
+  timeout (30 seconds for a read, two minutes for `openApp` and `openGame`), the bridge closed
+  before the answer came, or the Arcade said it had no reliable answer. For a read, try again
+  later. For `store.purchase` it means **the outcome is unknown**, never "nothing was bought"
+  ([§9](#9-buying-from-the-arcade-store)).

package/docs/arcade-economy.md

@@ -203,10 +203,11 @@ player got.
 
 Nothing sells Coins or achievement points, alone or in a bundle. The arcade's own store sells
 Gems, and the Gems a player bought there spend in your game exactly as the ones they earned do: your
-game cannot tell the two apart and prices nothing differently for either. Your game sells neither,
-and never sends a player to the store. The real-money
-product that changes what your game pays is a **Boost**, which a player buys from the arcade, never
-from your game:
+game cannot tell the two apart and prices nothing differently for either. Your game never sells
+either itself. It may put the arcade store's own Gem packs and Boosts in front of a player from a
+button of its own, through `gem.store`, and the arcade prices them, shows its own sheet and takes
+the money ([arcade-and-store.md](arcade-and-store.md)). The real-money product that changes what
+your game pays is a **Boost**, which a player always buys on the arcade's own sheet:
 
 - **It multiplies what Gems and Coins grants pay, and the ceilings with them.** A player on a 2×
   Boost earns twice as much per grant, may earn twice as much per window and per day, and may hold
@@ -242,11 +243,14 @@ animates every payout into the right total. Gems and Coins follow the same rules
   and must not compute a maximum. To show how much more your game can pay, read
   `gem.platform.earnAllowance.get()` (one consolidated figure, display only); the arcade still tells
   the player when they reach the maximum.
-- **No top-up or payment screen of your own.** Never draw a "get more Gems" or "buy Coins" offer,
-  a checkout, a wallet top-up, or anything shaped like the arcade's purchase sheet: a game screen
-  that looks like platform payment chrome is an imitation of it, and players cannot tell the two
-  apart. Your shop's own Buy button is yours. When a purchase is refused for
-  `insufficient_funds`, say so in your shop's own words ("Not enough Coins") and stop there.
+- **No top-up or payment screen of your own.** Never draw a "buy Coins" offer, a checkout, a
+  wallet top-up, or anything shaped like the arcade's purchase sheet: a game screen that looks like
+  platform payment chrome is an imitation of it, and players cannot tell the two apart. Your shop's
+  own Buy button is yours, and so is a "Get Gems" button that calls `gem.store.purchase` from the
+  player's press: the sheet it opens is the arcade store's own
+  ([arcade-and-store.md](arcade-and-store.md)). When a purchase is refused for
+  `insufficient_funds`, say so in your shop's own words ("Not enough Coins") and stop there: a
+  refusal never opens the store by itself.
 - **No amount at all when you are not connected to the arcade.** Hide every platform price and
   reward unless `gem.awaitBridge()` settled `connected`.
 - **Draw a currency with the art the SDK ships**: the icon beside an amount, the hero only on a

package/docs/changelog.md

@@ -16,6 +16,32 @@ 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.
 
+## 16.0.0
+
+Upgrading from 15.3.3. Impact: required.
+
+### Must change
+
+- If you run the parent conformance kit against your own parent, it now reports version 2. Update your test fixture to provide the new userActivation and reportError members. A parent that advertises the new app links, open game or store capabilities must also expose surfacesShown and dismiss so the new cases can run. Cases for capabilities the parent does not advertise pass vacuously, but the check that an unadvertised capability is refused always runs.
+
+### Rebuild
+
+- The lists and unions of messages sent between game and parent each gained entries for app links, opening an app or game, similar games and the store. Recompiling is enough. If your code switches exhaustively over these message types, add cases for the new ones or let them fall through to your default handling.
+- The capability type gained three new names: appLinks, openGame and store. Recompiling is enough. If you keep an exhaustive mapping over capabilities, add entries for these three.
+- The size check for raw messages now takes an optional cap argument. Existing calls compile and behave as before, so recompiling is enough.
+
+### New capability
+
+- Games can now use Gem.arcade to ask the Arcade for app-store links, to open an app listing, to open another game, and to fetch similar games as cards. An availability check tells you whether the Arcade supports each feature. Every call resolves with an outcome of ok, declined or unavailable plus a reason, and never rejects. If the Arcade does not advertise the capability, the call resolves unavailable without sending anything. Calls that act on the player need a real press from the player, and only one such call can be open at a time. Draw cards the way the Arcade draws its tiles, and treat card text as player text.
+- Games can now use Gem.store to read the platform store's offers, start a purchase, and listen for purchases that settle later. Calls resolve with an outcome and never reject, and a store that is not advertised resolves as unavailable without sending anything. A purchase needs a real press from the player, and only one can be open at a time. If a purchase comes back without success, treat the result as unknown rather than as proof that nothing was bought, because the connection can close after the player has paid. Re-read the player's holdings and keep your settlement listener attached. Show prices exactly as given.
+- If you embed a game with the frame class, you can now send any of the new Arcade or store asks through a single requestArcade call. It is gated on the capability the message belongs to. Answers to those asks are delivered to a new onArcadeAnswer callback that you can pass in the frame options.
+
+## 15.3.3
+
+Upgrading from 15.3.2. Impact: none.
+
+Nothing in this release asks anything of a game.
+
 ## 15.3.2
 
 Upgrading from 15.3.1. Impact: none.

package/docs/getting-started.md

@@ -50,7 +50,7 @@ either way.
 ```jsonc
 // package.json
 "dependencies": {
-  "@indiegems/gem-web-sdk": "15.3.2"
+  "@indiegems/gem-web-sdk": "16.0.0"
 }
 ```
 
@@ -166,8 +166,10 @@ open the dev server's own address.
 
 ## 5. Tell the arcade when you are ready
 
-The arcade shows a loading state until your game says it is playable. If you never say so, a
-player watches a spinner over a game that is already running.
+The arcade covers your game with its own loading screen until your game says it is playable. If
+you never say so, a player watches that cover over a game that is already running. A game that
+paints its own loading screen can show it instead, with one line on its store page
+([the loading contract](what-a-game-must-do.md#a-game-that-paints-its-own-loading-screen)).
 
 ```js
 gem.frame.progress(loaded, total); // while assets load

package/docs/inventory-and-catalogs.md

@@ -824,10 +824,12 @@ the same strings.
 Reasons are for your shop's state and your logs. Branch money on `outcome` and on a re-read of
 inventory, never on a reason, and do not retry because of one.
 
-⚠️ **Never draw a top-up or payment screen of your own** — no "get more Gems", no checkout, nothing
+⚠️ **Never draw a top-up or payment screen of your own** — no checkout, no wallet top-up, nothing
 that looks like the arcade's purchase sheet or wallet. A game screen shaped like platform payment
-chrome is an imitation of it. Your Buy button is yours; asking a player to add currency or pay is
-the arcade's alone.
+chrome is an imitation of it. Your Buy button is yours, and taking a player's money is the
+arcade's alone: a "Get Gems" button of yours calls `gem.store.purchase` from the player's press,
+and the arcade store's own sheet does the rest ([arcade-and-store.md](arcade-and-store.md)). An
+`insufficient_funds` refusal never opens it by itself.
 
 ### What Coins and Gems may buy: the spend scope
 
@@ -1039,7 +1041,9 @@ remove it. A player spends it through the platform, by choosing to.
 
 **You cannot sell for real money here.** A platform currency a player _earns_ is what this surface
 reaches. Charging actual money is a separate platform capability and is not something a game config
-grants itself.
+grants itself. What a game _can_ do is offer the arcade store's own Gem packs, Boosts, passes and
+bundles from a button of its own, through `gem.store`
+([arcade-and-store.md](arcade-and-store.md)): the arcade prices them and takes the money.
 
 ## Errors
 

package/docs/manifest.json

@@ -16,6 +16,11 @@
       "sha256": "afced8f94514818eca6de3e72bdd988b2cee10925086c3bfa47c0a8ec8967454",
       "updated": "2026-10-23T00:13:14Z"
     },
+    {
+      "file": "arcade-and-store.md",
+      "sha256": "35d71f81775c0e7b05c84626bbe8365b624a60fb751abe2a2b3126ba554f33ab",
+      "updated": "2026-10-28T21:07:26Z"
+    },
     {
       "file": "arcade-avatars.md",
       "sha256": "e02e435d91e389f9cc2025945ebc0ac11882bac85a4e6d5d74278f11e38fee91",
@@ -23,8 +28,8 @@
     },
     {
       "file": "arcade-economy.md",
-      "sha256": "1ebae3aeff2480722b09bc15d8a997656238133e757c9588a0eaa9479b990270",
-      "updated": "2026-10-25T19:46:22Z"
+      "sha256": "aca343bf98c0e111bca7d27f504bf71b43802b98e5cd649792dfd7c5f30b1b16",
+      "updated": "2026-10-28T18:37:42Z"
     },
     {
       "file": "async-opponents.md",
@@ -38,8 +43,8 @@
     },
     {
       "file": "changelog.md",
-      "sha256": "82f8ae669046bd8ffed7700156bad11941485aa463711baaf7de8ccb8ffa4001",
-      "updated": "2026-10-26T19:26:21Z"
+      "sha256": "739709af2b5a0918ea7041f6f3d50142c3182aca892bc388dee51ad1a0f64c41",
+      "updated": "2026-10-28T21:16:25Z"
     },
     {
       "file": "daily-challenges.md",
@@ -68,13 +73,13 @@
     },
     {
       "file": "getting-started.md",
-      "sha256": "e30a7fbe2872cf242dce30b1d0bd5b22b0bbd30e47615b8f7c18125febd0dbef",
-      "updated": "2026-10-26T19:26:21Z"
+      "sha256": "b3c215882b2ea836e79e37553277b97914f6947e8e3bbeb10e2a2e0667d2fb86",
+      "updated": "2026-10-28T21:16:25Z"
     },
     {
       "file": "inventory-and-catalogs.md",
-      "sha256": "4295b4a12770584a80d94a94d95e464553569d7318229413cdfbb604b6e1f9d8",
-      "updated": "2026-10-25T19:46:22Z"
+      "sha256": "e7bf9f38bf4ede778fdaca200186b782870f409949743e4e85f22f9c919cd19c",
+      "updated": "2026-10-28T18:37:42Z"
     },
     {
       "file": "leaderboards.md",
@@ -128,8 +133,8 @@
     },
     {
       "file": "server-bundles.md",
-      "sha256": "1042da92cef0807c7d3810b4efeba4a74cc2efeff1d963809bacb25cb308ad21",
-      "updated": "2026-10-26T19:26:21Z"
+      "sha256": "b4a7918f6b10b754976937f216ee8679260166a0377dcb0448fd42d65bdb2f31",
+      "updated": "2026-10-28T21:16:25Z"
     },
     {
       "file": "serverless-functions-js.md",
@@ -153,8 +158,8 @@
     },
     {
       "file": "what-a-game-must-do.md",
-      "sha256": "c449db410f2d7d9b1c7cfb305754103a1f4f03fb62781d9a1dc1e7dfb3fa459c",
-      "updated": "2026-10-23T22:49:46Z"
+      "sha256": "e020dca72e597dae0bfa1a71e3263dbb3234f9515d464944e66d7f89612f8db1",
+      "updated": "2026-10-28T00:47:43Z"
     }
   ]
 }

package/docs/player-text-fields.json

@@ -1,9 +1,10 @@
 {
   "$comment": [
-    "The published fields whose value is PlayerText (player-authored text), and the",
-    "first release from which each has been PlayerText in that entry. String(), a",
-    "template literal or JSON.stringify on one shows \"[gem: use gem.text.toPlain()]\";",
-    "convert it with text.toPlain(). `entry` is the package export (`sdk` is",
+    "The published fields whose value is PlayerText (player-authored text) or a list",
+    "of it, and the first release from which each has been that in that entry.",
+    "String(), a template literal or JSON.stringify on one shows",
+    "\"[gem: use gem.text.toPlain()]\"; convert it, or each element of a list, with",
+    "text.toPlain(). `entry` is the package export (`sdk` is",
     "@indiegems/gem-web-sdk/sdk), `field` is <Type>.<property>, and `since` is null",
     "for a field no release has shipped yet. Written by",
     "`node scripts/player-text-fields.mjs`."
@@ -75,6 +76,26 @@
       "field": "Friend.displayTag",
       "since": "5.11.0"
     },
+    {
+      "entry": "game",
+      "field": "GameCard.name",
+      "since": "16.0.0"
+    },
+    {
+      "entry": "game",
+      "field": "GameCard.shortDescription",
+      "since": "16.0.0"
+    },
+    {
+      "entry": "game",
+      "field": "GameCard.tagline",
+      "since": "16.0.0"
+    },
+    {
+      "entry": "game",
+      "field": "GameCard.tags",
+      "since": "16.0.0"
+    },
     {
       "entry": "game",
       "field": "GemPlayer.displayHandle",
@@ -140,6 +161,26 @@
       "field": "Friend.displayTag",
       "since": "5.11.0"
     },
+    {
+      "entry": "sdk",
+      "field": "GameCard.name",
+      "since": "16.0.0"
+    },
+    {
+      "entry": "sdk",
+      "field": "GameCard.shortDescription",
+      "since": "16.0.0"
+    },
+    {
+      "entry": "sdk",
+      "field": "GameCard.tagline",
+      "since": "16.0.0"
+    },
+    {
+      "entry": "sdk",
+      "field": "GameCard.tags",
+      "since": "16.0.0"
+    },
     {
       "entry": "sdk",
       "field": "GemPlayer.displayHandle",

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

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

@@ -227,9 +227,10 @@ The parent shows its loading state until your frame says otherwise. The whole co
 sentences:
 
 - **`ready()` means "there is something worth looking at"** — your boot screen, not your
-  world-ready. Measured on the Arcade: the parent's loading state is a plain page it abandons after
-  ~10s regardless, so holding `ready` until world-ready hides your own, more informative screen and
-  buys nothing.
+  world-ready. On the Arcade the parent's loading state is a cover of your game's key art over the
+  whole frame, and it stays until `ready()` arrives or your frame has gone quiet for the handshake
+  wait (10s, re-armed by every `progress`). Holding `ready` until world-ready hides your own, more
+  informative screen behind that cover and buys nothing.
 - **`ready()` is sent exactly once per session, and the SDK enforces it.** It is held while the
   bridge is down and delivered on connect, so call order cannot lose it; a call after one has gone
   out is suppressed and reported through `onDropped`. This is what makes the `finally` backstop
@@ -242,6 +243,38 @@ sentences:
   be throttled, and a progress call after `ready` is meaningless to a parent that has already
   unveiled you.
 
+### A game that paints its own loading screen
+
+A game whose page paints its own loading screen from its very first paint can show that screen
+instead of the Arcade's cover. Declare it on your store page:
+
+```yaml
+loading_screen: game
+```
+
+`arcade` is the default, and it is what an absent line means. With `game`, the Arcade still covers
+everything up to your frame's `load` event — its own lookup and start, and your page while it
+loads — and then lifts its cover at once, so your screen shows.
+
+- **Your `index.html` must paint a full-screen loading screen in static HTML and CSS, before any
+  script runs** — a background that fills the frame, and something on it: your title, your logo, a
+  bar. Never white, and never the browser's default background, which is white. At `load` the
+  player sees whatever your document has painted, and a screen your script or engine draws may not
+  have drawn yet on a slow phone. Declare `game` only when that static screen is in place.
+- **`load` waits for everything your document loads up front** — its stylesheets, images and
+  scripts. Keep `index.html` small, as
+  [the boot phase](#the-boot-phase-settle-the-bridge-before-the-heavy-bundle) already asks, or the
+  cover stays up while it downloads.
+- **`ready()` is still required, and the rules above still hold.** Only the cover goes early. The
+  Arcade does not count the play until `ready()` arrives, or until the quiet deadline above passes
+  for a game that never sends it.
+- **Values are `arcade` and `game`.** Any other value is refused when the store page is uploaded. A
+  `gemctl` that predates the field refuses it as an unknown field.
+- **The store page on the channel being played is read**: dev's when you play on dev, release's on
+  release, so you can try it on dev before you promote it. An experiment variant is never read.
+- **`gemctl serve` and the Gem Editor keep the Arcade's cover**, because they have no store page.
+  To see your own screen as players will, open your game's store page on the dev channel.
+
 ## Boot diagnostics: where the seconds went
 
 `gem.boot` is a timeline of named marks, one greppable line out of `gem.boot.timeline()`:

package/package.json

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