@indiegems/gem-web-sdk 23.2.0 → 23.3.0

package/docs/api/reference.json

@@ -2,7 +2,7 @@
   "schema_version": 2,
   "source": {
     "repo": "IndieGems/gem-web-sdk",
-    "version": "23.2.0"
+    "version": "23.3.0"
   },
   "entries": [
     {
@@ -3929,7 +3929,7 @@
           "group": "account",
           "signature": "type SignInOutcomeKind = \"signed_in\" | \"declined\" | \"unavailable\"",
           "documented": true,
-          "summary": "The complete vocabulary of answers. Three values, and there will not be a\nfourth.\n\n- `signed_in` — the player is signed in, and [Gem.identity](api-reference-game.md#gem-identity),\n  [Gem.player](api-reference-game.md#gem-player) and [Gem.me](api-reference-game.md#gem-me) already answer for their account.\n  Re-read anything you loaded before asking. Also the answer for a player who\n  was signed in all along.\n- `declined` — the player closed the prompt, or the arcade chose not to show\n  one. Return to the game silently.\n- `unavailable` — the arcade could not offer sign-in, or never answered.\n\nNo reason is given for a `declined`, and one will never be added: why a\nsign-in did not happen is a fact about the player's account, and the arcade\nis the one that explains those.",
+          "summary": "The complete vocabulary of answers. Three values, and there will not be a\nfourth.\n\n- `signed_in` — the player is signed in, and [Gem.identity](api-reference-game.md#gem-identity),\n  [Gem.player](api-reference-game.md#gem-player) and [Gem.me](api-reference-game.md#gem-me) already answer for their account.\n  Re-read anything you loaded before asking. Also the answer for a player who\n  was signed in all along.\n- `declined` — the player closed the prompt, or the arcade chose not to show\n  one. Return to the game silently.\n- `unavailable` — the arcade could not offer sign-in, or never answered.\n  [AccountApi.signInAvailable](api-reference-game.md#accountapi-signinavailable) says so before you draw the button.\n\nNo reason is given for a `declined`, and one will never be added: why a\nsign-in did not happen is a fact about the player's account, and the arcade\nis the one that explains those.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -3986,6 +3986,50 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "AccountApi.signInAvailable",
+          "name": "signInAvailable",
+          "anchor": "accountapi-signinavailable",
+          "group": "account",
+          "signature": "readonly signInAvailable: boolean",
+          "documented": true,
+          "summary": "Whether [AccountApi.requestSignIn](api-reference-game.md#accountapi-requestsignin) can show this player a sign-in\nhere. Read it before you draw a \"Sign in to claim\" button, and hide the\noffer when it is `false`.\n\n- `true` — a guest the arcade can offer sign-up to. An ask may still\n  answer `declined` at a busy moment.\n- `false` — an ask would show nothing. The player is already signed in\n  (it answers `signed_in` at once; every player in a current Gem Arcade\n  app build, v3.33.174 and later, is), or there is no Arcade sign-in here\n  (it answers `unavailable`). Also `false` until the player is known.\n\nOn an arcade older than this signal it reads `true` for every player, a\nfull account included, as before it existed. So gate a sign-up gift on it\nand on the guest test you use today; see docs/player-sign-in.md.\n[AccountApi.onSignInAvailableChange](api-reference-game.md#accountapi-onsigninavailablechange) tells you when it changes.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": "```ts\nconst draw = (available: boolean) => {\n  signInButton.hidden = !available;\n};\ndraw(gem.account.signInAvailable);\ngem.account.onSignInAvailableChange(draw);\n```",
+          "defaultValue": null,
+          "guides": [
+            {
+              "slug": "player-sign-in",
+              "anchor": null
+            }
+          ]
+        },
+        {
+          "id": "AccountApi.onSignInAvailableChange",
+          "name": "onSignInAvailableChange",
+          "anchor": "accountapi-onsigninavailablechange",
+          "group": "account",
+          "signature": "onSignInAvailableChange(listener: (available: boolean) => void): () => void",
+          "documented": true,
+          "summary": "Runs `listener` whenever [AccountApi.signInAvailable](api-reference-game.md#accountapi-signinavailable) changes: when\nthe player arrives, when the arcade changes its answer (a guest who signs\nup), and when the connection closes. Not on a re-sent player with the same\nanswer.",
+          "deprecated": null,
+          "params": [
+            {
+              "name": "listener",
+              "type": "(available: boolean) => void",
+              "optional": false,
+              "summary": null
+            }
+          ],
+          "returns": "A function that stops the listener.",
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "AccountApi.requestSignIn",
           "name": "requestSignIn",
@@ -4735,7 +4779,7 @@
           "group": "analytics",
           "signature": "experiment(key: string, count: number): Promise<number>",
           "documented": true,
-          "summary": "Which arm of one of your experiments this player gets — the same answer on\nevery call, every refresh and every device. Use it wherever you would have\npicked an arm with `Math.random()`, which deals a player a new arm on each\nvisit and makes the test unreadable.\n\nPass a COUNT and get an index, `0` to `count - 1`; pass a LIST of strings\nand get one of them. A string listed twice is twice as likely.\n\n```js\nconst tutorial = await gem.analytics.experiment('tutorial_length', ['short', 'long']);\nconst layout = await gem.analytics.experiment('shop_layout', 3); // 0, 1 or 2\n```\n\nThe selection is a hash of the key and the signed-in player's id — FNV-1a\n32-bit over `\"<key>:<playerId>\"`, then MurmurHash3's 32-bit finalizer, mod\nthe arm count; see\n[experimentSelection](api-reference-game.md#experimentselection), which computes the same answer for an id you\nhold. Hashing the key in is what keeps your experiments independent: the\nplayers in one experiment's first arm are not the same players in every\nother experiment's first arm.\n\n⚠️ **Keep the key and the arms fixed for the life of the experiment.** A new\ncount or list re-deals every player. To start over on purpose, use a new\nkey.\n\n⚠️ **NOTHING IS RECORDED FOR YOU.** The selection is not sent anywhere, and\nthe SDK does not add it to your events. To analyse an experiment, declare a\ndimension for it on the events you want to break down, with the arms as its\nvalues, named after the experiment, and pass the selection there yourself:\n`gem.analytics.track('tutorial_finished', { tutorial_length: tutorial })`.\nNever the platform's `variant` field, which belongs to store-page\nexperiments.\n\nWAITS FOR THE PLAYER. The id arrives with the first play token, so a call\nduring boot waits for it, and rejects as [Gem.awaitIdentity](api-reference-game.md#gem-awaitidentity) does\nwhen none arrives — outside the Arcade, the Gem Editor or the dev host.\nThere is no random fallback: catch the rejection and play your control arm.\nA guest is selected by their guest id, which is stable for as long as their\nguest account lasts; once they sign in to an account they are that\naccount's player, and its selection applies.\n\nIn a serverless function it selects for the player who invoked it, with\nno wait, and rejects when a game server invoked it.\n\nWorks with analytics turned off: it reads no setting and sends nothing.",
+          "summary": "Which arm of one of your experiments this player gets — the same answer on\nevery call, every refresh and every device. Use it wherever you would have\npicked an arm with `Math.random()`, which deals a player a new arm on each\nvisit and makes the test unreadable.\n\nPass a COUNT and get an index, `0` to `count - 1`; pass a LIST of strings\nand get one of them. A string listed twice is twice as likely.\n\n```js\nconst tutorial = await gem.analytics.experiment('tutorial_length', ['short', 'long']);\nconst layout = await gem.analytics.experiment('shop_layout', 3); // 0, 1 or 2\n```\n\nThe selection is a hash of the key and the signed-in player's id — FNV-1a\n32-bit over `\"<key>:<playerId>\"`, then MurmurHash3's 32-bit finalizer, mod\nthe arm count; see\n[experimentSelection](api-reference-game.md#experimentselection), which computes the same answer for an id you\nhold. Hashing the key in is what keeps your experiments independent: the\nplayers in one experiment's first arm are not the same players in every\nother experiment's first arm.\n\n⚠️ **Keep the key and the arms fixed for the life of the experiment.** A new\ncount or list re-deals every player. To start over on purpose, use a new\nkey.\n\n⚠️ **NOTHING IS RECORDED FOR YOU.** The selection is not sent anywhere, and\nthe SDK does not add it to your events. To analyse an experiment, declare a\ndimension for it on the events you want to break down, with the arms as its\nvalues, named after the experiment, and pass the selection there yourself:\n`gem.analytics.track('tutorial_finished', { tutorial_length: tutorial })`.\nNever the platform's `variant` field, which belongs to store-page\nexperiments. For the platform's results to show the test, also declare it\nunder `analytics_tests` in your game config (see docs/analytics.md).\n\nWAITS FOR THE PLAYER. The id arrives with the first play token, so a call\nduring boot waits for it, and rejects as [Gem.awaitIdentity](api-reference-game.md#gem-awaitidentity) does\nwhen none arrives — outside the Arcade, the Gem Editor or the dev host.\nThere is no random fallback: catch the rejection and play your control arm.\nA guest is selected by their guest id, which is stable for as long as their\nguest account lasts; once they sign in to an account they are that\naccount's player, and its selection applies.\n\nIn a serverless function it selects for the player who invoked it, with\nno wait, and rejects when a game server invoked it.\n\nWorks with analytics turned off: it reads no setting and sends nothing.",
           "deprecated": null,
           "params": [
             {
@@ -31018,7 +31062,7 @@
           "group": "analytics",
           "signature": "experiment(key: string, count: number): Promise<number>",
           "documented": true,
-          "summary": "Which arm of one of your experiments this player gets — the same answer on\nevery call, every refresh and every device. Use it wherever you would have\npicked an arm with `Math.random()`, which deals a player a new arm on each\nvisit and makes the test unreadable.\n\nPass a COUNT and get an index, `0` to `count - 1`; pass a LIST of strings\nand get one of them. A string listed twice is twice as likely.\n\n```js\nconst tutorial = await gem.analytics.experiment('tutorial_length', ['short', 'long']);\nconst layout = await gem.analytics.experiment('shop_layout', 3); // 0, 1 or 2\n```\n\nThe selection is a hash of the key and the signed-in player's id — FNV-1a\n32-bit over `\"<key>:<playerId>\"`, then MurmurHash3's 32-bit finalizer, mod\nthe arm count; see\n`experimentSelection`, which computes the same answer for an id you\nhold. Hashing the key in is what keeps your experiments independent: the\nplayers in one experiment's first arm are not the same players in every\nother experiment's first arm.\n\n⚠️ **Keep the key and the arms fixed for the life of the experiment.** A new\ncount or list re-deals every player. To start over on purpose, use a new\nkey.\n\n⚠️ **NOTHING IS RECORDED FOR YOU.** The selection is not sent anywhere, and\nthe SDK does not add it to your events. To analyse an experiment, declare a\ndimension for it on the events you want to break down, with the arms as its\nvalues, named after the experiment, and pass the selection there yourself:\n`gem.analytics.track('tutorial_finished', { tutorial_length: tutorial })`.\nNever the platform's `variant` field, which belongs to store-page\nexperiments.\n\nWAITS FOR THE PLAYER. The id arrives with the first play token, so a call\nduring boot waits for it, and rejects as `Gem.awaitIdentity` does\nwhen none arrives — outside the Arcade, the Gem Editor or the dev host.\nThere is no random fallback: catch the rejection and play your control arm.\nA guest is selected by their guest id, which is stable for as long as their\nguest account lasts; once they sign in to an account they are that\naccount's player, and its selection applies.\n\nIn a serverless function it selects for the player who invoked it, with\nno wait, and rejects when a game server invoked it.\n\nWorks with analytics turned off: it reads no setting and sends nothing.",
+          "summary": "Which arm of one of your experiments this player gets — the same answer on\nevery call, every refresh and every device. Use it wherever you would have\npicked an arm with `Math.random()`, which deals a player a new arm on each\nvisit and makes the test unreadable.\n\nPass a COUNT and get an index, `0` to `count - 1`; pass a LIST of strings\nand get one of them. A string listed twice is twice as likely.\n\n```js\nconst tutorial = await gem.analytics.experiment('tutorial_length', ['short', 'long']);\nconst layout = await gem.analytics.experiment('shop_layout', 3); // 0, 1 or 2\n```\n\nThe selection is a hash of the key and the signed-in player's id — FNV-1a\n32-bit over `\"<key>:<playerId>\"`, then MurmurHash3's 32-bit finalizer, mod\nthe arm count; see\n`experimentSelection`, which computes the same answer for an id you\nhold. Hashing the key in is what keeps your experiments independent: the\nplayers in one experiment's first arm are not the same players in every\nother experiment's first arm.\n\n⚠️ **Keep the key and the arms fixed for the life of the experiment.** A new\ncount or list re-deals every player. To start over on purpose, use a new\nkey.\n\n⚠️ **NOTHING IS RECORDED FOR YOU.** The selection is not sent anywhere, and\nthe SDK does not add it to your events. To analyse an experiment, declare a\ndimension for it on the events you want to break down, with the arms as its\nvalues, named after the experiment, and pass the selection there yourself:\n`gem.analytics.track('tutorial_finished', { tutorial_length: tutorial })`.\nNever the platform's `variant` field, which belongs to store-page\nexperiments. For the platform's results to show the test, also declare it\nunder `analytics_tests` in your game config (see docs/analytics.md).\n\nWAITS FOR THE PLAYER. The id arrives with the first play token, so a call\nduring boot waits for it, and rejects as `Gem.awaitIdentity` does\nwhen none arrives — outside the Arcade, the Gem Editor or the dev host.\nThere is no random fallback: catch the rejection and play your control arm.\nA guest is selected by their guest id, which is stable for as long as their\nguest account lasts; once they sign in to an account they are that\naccount's player, and its selection applies.\n\nIn a serverless function it selects for the player who invoked it, with\nno wait, and rejects when a game server invoked it.\n\nWorks with analytics turned off: it reads no setting and sends nothing.",
           "deprecated": null,
           "params": [
             {

package/docs/arcade-and-store.md

@@ -223,7 +223,8 @@ policy refused. Allow that host rather than a wildcard.
 
 ```js
 const { outcome, reason, offers } = await gem.store.offers();
-if (outcome === 'unavailable' && reason === 'sign_in_required') showSignInButton(); // gem.account.requestSignIn
+if (outcome === 'unavailable' && reason === 'sign_in_required' && gem.account.signInAvailable)
+  showSignInButton(); // gem.account.requestSignIn
 for (const offer of offers) drawOffer(offer);
 ```
 
@@ -443,7 +444,8 @@ player, and the route refuses it with `403`. The body is `{ pass, held, ends_at
   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.
+  `unavailable` / `sign_in_required`, so offer `gem.account.requestSignIn` instead of the button,
+  when `gem.account.signInAvailable` says the Arcade can show them a sign-in.
 
 ### When the door moves by itself
 

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.
 
+## 23.3.0
+
+*Written from the API facts alone; no summary was generated for this release.*
+
+Upgrading from 23.2.0. Impact: required.
+
+### Must change
+
+- FrameCallbacks.onPlayer changed its signature.
+- FrameOptions.onPlayer changed its signature.
+
+### New capability
+
+- AccountApi.onSignInAvailableChange was added.
+- AccountApi.signInAvailable was added.
+- GemPlayer.signInAvailable was added.
+- SendPlayerInput.signInAvailable was added.
+
 ## 23.2.0
 
 *Written from the API facts alone; no summary was generated for this release.*

package/docs/getting-started.md

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

package/docs/manifest.json

@@ -13,13 +13,13 @@
     },
     {
       "file": "analytics.md",
-      "sha256": "5814655859e3d6b223f94b71f1b064783b0f242d409c3ec3078089cb4b7c8ec5",
-      "updated": "2026-11-04T17:17:14Z"
+      "sha256": "3f81025a763f96d0ca17f57377042a3e3890797983265cdb1721902b700aa3a6",
+      "updated": "2026-11-09T18:54:26Z"
     },
     {
       "file": "arcade-and-store.md",
-      "sha256": "79bd7829d5a6577d3619d7fd831b74065df883e11eadd1b8153754d97a88474a",
-      "updated": "2026-11-02T18:42:37Z"
+      "sha256": "5b880e515ce0d65ffff77b97c93844dbcc14d7ab55d89edabaa54f4858376216",
+      "updated": "2026-11-09T16:45:36Z"
     },
     {
       "file": "arcade-avatars.md",
@@ -48,8 +48,8 @@
     },
     {
       "file": "changelog.md",
-      "sha256": "819160e36c0258c34aa3e8b06ea0f1e26a50bcc83c5919780de2b33f4fac1cd9",
-      "updated": "2026-11-09T16:19:51Z"
+      "sha256": "85e888011b15aa2e9ebb56d938b9a8165489167bcebda236cba9e4f09937044f",
+      "updated": "2026-11-10T15:57:23Z"
     },
     {
       "file": "daily-challenges.md",
@@ -78,8 +78,8 @@
     },
     {
       "file": "getting-started.md",
-      "sha256": "763113c6da4ae1d154ba655e44e87f32912a66ea7db40a61dca9c17f51fcc234",
-      "updated": "2026-11-09T16:19:51Z"
+      "sha256": "bdadeee9b46529d4ef9543a2be61cd096e6b200c20dbe2ab1b361d23139d3e64",
+      "updated": "2026-11-10T15:57:23Z"
     },
     {
       "file": "graphics-route.md",
@@ -118,13 +118,13 @@
     },
     {
       "file": "player-sign-in.md",
-      "sha256": "22c798ff32ee15dda88f08f6701146f83fe92568c737d9321edd3e2550cb2df9",
-      "updated": "2026-11-09T02:37:14Z"
+      "sha256": "f5066f2382bac9336c697d3646843f546295686a959726e877431ec7dc2daea3",
+      "updated": "2026-11-09T18:39:56Z"
     },
     {
       "file": "rewarded-ads.md",
-      "sha256": "f632d54aa605b34dc071b59d49e7ecfd35ab95eb6f601885ceb0d3d6fc41a949",
-      "updated": "2026-11-09T15:28:20Z"
+      "sha256": "36394d5faee67f3907139b1fe8c8210a6074a6eac593bc070b567625e71c6129",
+      "updated": "2026-11-09T19:34:44Z"
     },
     {
       "file": "room-shapes.md",
@@ -143,8 +143,8 @@
     },
     {
       "file": "server-bundles.md",
-      "sha256": "b712e407e79482f1edc596ebcaab00852429fbaacebb05d04a2a2f9cbe1f5b9c",
-      "updated": "2026-11-09T16:19:51Z"
+      "sha256": "921591332e0a9fc52d36e3372af26a5ea808768e1bbd49826d765b7e4615ab53",
+      "updated": "2026-11-10T15:57:23Z"
     },
     {
       "file": "serverless-functions-js.md",
@@ -168,8 +168,8 @@
     },
     {
       "file": "what-a-game-must-do.md",
-      "sha256": "f70fe9fad67c6b386bddc53f1f876bb78f6a5e11c35f565bb93e925d65a99874",
-      "updated": "2026-11-06T22:48:07Z"
+      "sha256": "c5400f43a1218de0d2838d4332dce4c05afe21ff04e352d2e201ef5bb4268bed",
+      "updated": "2026-11-09T18:39:56Z"
     }
   ]
 }

package/docs/player-sign-in.md

@@ -17,8 +17,56 @@ signInButton.onclick = async () => {
 };
 ```
 
-That is the whole surface. Your game never draws a sign-in form and never handles a password; it
-could not be trusted with either, and it does not need to be.
+That is almost the whole surface. Your game never draws a sign-in form and never handles a
+password; it could not be trusted with either, and it does not need to be.
+
+## Before you draw the button
+
+Not every player can be shown a sign-in. Before you draw "Sign in to claim", read
+`gem.account.signInAvailable`, and listen for it to change:
+
+```js
+const drawUpsell = (available) => {
+  signInButton.hidden = !available;
+};
+drawUpsell(gem.account.signInAvailable);
+gem.account.onSignInAvailableChange(drawUpsell);
+```
+
+- **`true`**: pressing the button will normally put the Arcade's sign-in up for this player. It can
+  still answer `declined` at a busy moment, such as while the Arcade has a sheet or a menu open.
+- **`false`**: pressing it would show nothing. Don't draw the offer. Either the player is already
+  signed in (an ask answers `signed_in` at once), or nothing can be shown here (it answers
+  `unavailable`). It is also `false` until the player is known, and again once the game is
+  disconnected.
+
+**In current Gem Arcade app builds (v3.33.174 and later), every player is already signed in.** The
+app signs each player in to a full account: a device account, Play Games or Game Center, or another
+sign-in. So `signInAvailable` is `false` there, and an ask answers `signed_in` at once, with nothing
+shown. Don't draw a sign-in offer in the app. Older app builds run an older Arcade, where the next
+paragraph applies: `signInAvailable` reads `true` there.
+
+On an Arcade older than this signal, `signInAvailable` reads `true` for every player, a full
+account included. That is how a sign-in ask behaved before the signal existed. So a game that reads
+it keeps its button there, and a player who is already signed in and presses it gets `signed_in`
+at once, with nothing shown. Keep handling every answer quietly (section 3).
+
+`onSignInAvailableChange` runs only when the answer changes: when the player arrives, when a guest
+signs up in place, and when the game is disconnected. It returns a function that stops it.
+
+### Gating a sign-up gift
+
+If your game gives a gift for signing up, offer it only while `signInAvailable` is `true`. That
+means a guest the Arcade can sign up here, so you don't need to work out who is a guest from
+`gem.store.offers()` answering `unavailable` / `sign_in_required`.
+
+On an older Arcade the signal can't do that job alone. It reads `true` for every player there, so a
+gift gated on it alone is offered to players who already have an account. Pressing it answers
+`signed_in` at once, which a player who was signed in all along gets too, so that answer is no
+proof of a sign-up either. Your game can't tell which kind of Arcade it is running in, so for now
+gate the gift on both: `signInAvailable` is `true` **and** the guest test you use today, such as
+`offers()` answering `sign_in_required`. On a current Arcade the two agree for a guest. On an older
+one, the second keeps the gift from players who are already signed in.
 
 ## 1. Save before you ask
 
@@ -56,7 +104,7 @@ and nothing has changed; hide the upsell.
 |---|---|---|
 | `signed_in` | the player is signed in | re-read, then hide the upsell |
 | `declined` | the player closed the prompt, or the Arcade chose not to show one | return to the game silently |
-| `unavailable` | the Arcade does not offer this here, or never answered | return to the game silently |
+| `unavailable` | the Arcade does not offer this here, or never answered | return to the game silently; `signInAvailable` was `false` for most of these |
 
 `requestSignIn` always resolves when it resolves at all. There is no error branch and no
 `try`/`catch` to write.

package/docs/rewarded-ads.md

@@ -226,6 +226,37 @@ for a placement yet.** Until then your prices are not offered, the placement unl
 alone, `ad: false` included, and `rewardedStatus` carries no `options` (§5). Nothing in your game
 needs to change when it goes live: draw the button from `rewardedStatus` and it follows.
 
+### A placement or the store?
+
+Now that a placement can take Coins and Gems, pick by what the player is buying:
+
+- **A single-reward button** (a hint, an extra life, a skip) is a **rewarded placement**, with
+  `platform_prices` for Coins and Gems. Whether it offers the ad, Coins, Gems or any mix is then a
+  config switch (`ad` and `platform_prices`), not code: the button and its `requestAd` stay the
+  same, and the Arcade shows the player the choices.
+- **A real shop** (several items, quantities, locked items) is **store items and recipes** with
+  `platform_prices`
+  ([`inventory-and-catalogs.md`](inventory-and-catalogs.md#16-selling-for-a-platform-currency)).
+  A placement grants one fixed reward per press: it has no list of items, no quantity, and no
+  prerequisite to lock anything behind.
+
+A hint button the player can unlock with an ad or 2 Gems:
+
+```yaml
+rewarded_placements:
+  - placement: hint # exactly the string your game passes
+    grants:
+      - { type: item_grant, item_definition_slug: hint_token, quantity: 1 }
+    max_per_day: 5 # limits the ad only
+    platform_prices:
+      - { currency: GEMS, price: 2 }
+```
+
+Add `{ currency: ARCADE_TICKETS, price: 20 }` beside it for Coins where Coins' spend scope lets
+them price a hint (above), and `ad: false` to drop the ad. Do not also sell `hint_token` in your
+shop: the reward then counts as sold for a platform currency (§1), the upload warns, and outside
+test ads its ad is only served where the platform verifies completion with the ad provider.
+
 ## 3. Ask from the press, then re-read
 
 ```js

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/v23.2.0/gem-web-sdk.tgz
-curl -fsSL https://downloads.gemarcade.com/sdk/v23.2.0/gem-web-sdk.tgz.sri
+curl -fsSL -O https://downloads.gemarcade.com/sdk/v23.3.0/gem-web-sdk.tgz
+curl -fsSL https://downloads.gemarcade.com/sdk/v23.3.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

@@ -2404,10 +2404,13 @@ Not on the list above either. When a player reaches for something only an accoun
 `gem.account.requestSignIn` asks the Arcade to sign them in, in its own chrome. Your game draws no
 form and passes nothing.
 
-Two things before you reach for it: **save first**, because the Arcade may sign the player in by
-taking the whole page away, and your game then starts again rather than hearing an answer; and on
-`signed_in`, **re-read what you loaded**, because the player underneath your game may not be the
-one who was there a moment ago. [`player-sign-in.md`](player-sign-in.md) is the page.
+Draw the offer only while `gem.account.signInAvailable` is `true`: it is `false` for a player
+already signed in (every player in a current Gem Arcade app build, v3.33.174 and later, is), and
+wherever nothing can be shown. Two
+things before you reach for it: **save first**, because the Arcade may sign the player in by taking
+the whole page away, and your game then starts again rather than hearing an answer; and on `signed_in`, **re-read what you loaded**, because the player
+underneath your game may not be the one who was there a moment ago.
+[`player-sign-in.md`](player-sign-in.md) is the page.
 
 ## A Share button, if your game has something worth sending a friend
 

package/package.json

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

package/schema/bridge.v1.json

@@ -840,6 +840,47 @@
               ]
             }
           }
+        },
+        "signInAvailable": {
+          "kind": "boolean",
+          "optional": true,
+          "$comment": [
+            "Whether a `gem.requestSignIn` from a player's press would put the",
+            "Arcade's sign-in prompt up for THIS player HERE.",
+            "The SDK reads it as `gem.account.signInAvailable`, so a game hides a",
+            "\"Sign in to claim\" offer that could show nothing.",
+            "",
+            "`true`: a browser guest on a surface that offers sign-up. An ask can",
+            "still answer `declined` at a busy moment (a sheet, a menu, a parked",
+            "game, a second ask); those holds are momentary and not part of this",
+            "field. `false`: an ask shows nothing — it answers `signed_in` at once",
+            "(a full account, which every player in the Gem Arcade app is) or",
+            "`unavailable` (a garden that offers no sign-up, a surface with no",
+            "sign-in). A parent",
+            "that knows sends it on EVERY `gem.player`, `false` included, and",
+            "re-sends the message when it changes (a guest who signs up in place).",
+            "",
+            "ABSENT means an older parent, and a frame reads it as `true`, which is",
+            "what `gem.requestSignIn` did there before this field: a game that adopts",
+            "it keeps its button on an old host. So a parent must never omit it to",
+            "mean `false`.",
+            "",
+            "A BOOLEAN, NEVER AN ENUM. A new enum value is breaking here: an N-1",
+            "frame's validator would refuse the whole message and cost the game its",
+            "player's name.",
+            "",
+            "Platform-assigned, so it sits outside `untrusted`. Ungated like the rest",
+            "of `gem.player`; it means something only beside the `signIn`",
+            "capability, without which the SDK reads `false` whatever it says.",
+            "",
+            "DISCLOSURE. `true` tells a game \"this is a browser guest\": the fact",
+            "`gem.requestSignIn` already discloses, since a",
+            "full account answers `signed_in` at once and a guest's answer follows a",
+            "person. `false` reveals less: it does not tell a signed-in player from",
+            "a surface with no sign-in. And `gem.player` is withheld until the launch is",
+            "confirmed, so an unconfirmed launch learns nothing. It carries no",
+            "sanction, session or age band."
+          ]
         }
       },
       "rateLimit": { "perMinute": 12 }