@indiegems/gem-web-sdk 7.8.0 → 7.9.0

package/docs/achievements.md

@@ -2,7 +2,7 @@
 
 An **achievement** is a platform-wide recognition a player earns in your game: a name, a
 description and some **achievement points**. The arcade lists your achievements on your store page, shows each player what they have unlocked, and
-adds their points to their **Achievement Score**, a total that spans every game they play (§5).
+adds their points to their **Achievement Score**, a total that spans every game they play (§6).
 
 There is no achievements API to call. An achievement sits on a **progression threshold your game
 already has**, and it unlocks when your server, or a serverless function the player called, moves
@@ -194,7 +194,8 @@ first write, list them from your own game config.
 
 The client caches what it reads, and an unlock happens on your server, so the client does not see
 it by itself. When your server tells the game a player unlocked something, call
-`gem.me.inventory.refresh()` before reading the progression again.
+`gem.me.inventory.refresh()` before reading the progression again. Celebrating that unlock is your
+game's job: [§5](#5-celebrating-an-unlock-is-your-games-job) says how the game learns it happened.
 
 **This read is for display.** Never send it to your server as proof that a player holds something;
 a modified client can report anything. Your server reads the standing itself.
@@ -203,7 +204,102 @@ a modified client can report anything. Your server reads the standing itself.
 threshold — it is in your config. The arcade hides its name and description from players until they
 unlock it; if your game shows its own achievement list, do the same.
 
-## 5. Points are prestige: the Achievement Score
+## 5. Celebrating an unlock is your game's job
+
+By default the arcade draws **no** card when a player unlocks one of your game's achievements — not
+during play, and not when they leave the game. Your game celebrates the unlock, in its own frame, in
+its own art and sound. The arcade's record is the same either way: the unlock is recorded, its
+points count toward the Achievement Score (§6), and the arcade's achievement lists show it. Only the
+card over your game depends on what you declare.
+
+### If your game has no celebration of its own
+
+Declare the arcade's card on your store page instead, and the arcade draws it for every unlock of
+one of your game's achievements:
+
+```yaml
+unlock_celebration: arcade
+```
+
+- **Values are `game` and `arcade`.** `game` is the default, and leaving the line out means `game`.
+  Any other value is refused when the store page is uploaded.
+- **It is one line, on any store page you already have.** It is optional in every store-page
+  `schema_version`, so adding it needs no `schema_version` change.
+- **Only the store page on the `release` channel is read**, and the setting takes effect when that
+  store page is promoted to `release` — the same channel achievements unlock on (§2). A store page
+  on another channel, and an experiment variant, are accepted but never read.
+- **It governs the card for your game's achievements only**, and it is display-only: it changes no
+  unlock, no points and no reward.
+- **Not both.** A game that draws its own celebration and declares `arcade` shows the player two,
+  one over the other.
+
+### Platform milestones are always the arcade's
+
+Platform milestones — the tiers of the player's Achievement Score, which belong to no game — always
+get the arcade's card, whatever your store page declares. That includes a milestone an unlock in
+your game reaches, and one reached in the same moment as an unlock the arcade does not show. Your
+game neither celebrates nor suppresses a milestone. A reward one of your achievements grants gets no
+arcade card of its own while your store page says `game`.
+
+### Knowing an unlock happened
+
+There is no unlock message from the arcade to your game. Your game learns of an unlock one of two
+ways.
+
+**On your server — the reliable path.** The order your server gets back says what it unlocked
+(§3). For each `unlocked` receipt, tell your game client over your game's own channel — the response
+to the request the client made, or a match message — and celebrate it there:
+
+```js
+const unlocked = achievementReceipts(order)
+  .filter((r) => r.outcome === 'unlocked')
+  .map((r) => ({ id: r.achievementId, points: r.points }));
+// Send `unlocked` back in your own response; the client celebrates each one.
+```
+
+**In the game — the compare.** Read the progression, and compare which achievements carry an
+`unlockedAt` with what the game held at its last read: one that is newly present was just unlocked.
+Read once when the game starts, before any write — that first read only records what the player
+already holds, and celebrates nothing. Then run the compare after **every** response from your
+game's own server that may have written the progression, not only after one that reported an
+unlock, because the case it exists for is the report that never arrived:
+
+```js
+let held = null; // ids the game has seen unlocked; null until the first good read
+
+async function checkUnlocks() {
+  gem.me.inventory.refresh(); // drops the cache; it returns nothing to wait for
+  const p = await gem.me.progressions.get('boards_cleared');
+  if (p?.achievementsUnavailable) return; // this read says nothing: keep the last snapshot
+  const now = (p?.achievements ?? []).filter((a) => a.unlockedAt !== undefined && !a.revoked);
+  if (!held) { held = new Set(now.map((a) => a.id)); return; } // the seed celebrates nothing
+  for (const a of now) if (!held.has(a.id)) { held.add(a.id); celebrate(a); }
+}
+
+// After each response from your server. A failed read is caught by the next check.
+checkUnlocks().catch(() => {});
+```
+
+Keep one snapshot per progression that carries achievements. Only add to the snapshot, never replace
+it, so a read that finishes late cannot bring back an unlock already celebrated. When
+`achievementsUnavailable` is true the read says nothing about which achievements are unlocked, so it
+is never a change. A start-up read that is unavailable does not seed: the first good read seeds, so
+an unlock in that gap is not celebrated. The unlock is still recorded.
+
+**When it can miss.** A receipt is a report, not a trigger (§3): a retried or replayed order reports
+nothing, so a celebration keyed only on an `unlocked` receipt is missed whenever the first response
+never arrived. The client compare catches that case. A missed celebration loses nothing else — the
+unlock, its points and its rewards are already recorded.
+
+### What the celebration shows
+
+- **The unlock is yours; a platform-currency payout is not.** Any Gems or Tickets the same moment
+  pays still go through `gem.cueReward`, with no Gems or Tickets flight, counter or count-up of your
+  own — [arcade-economy.md](arcade-economy.md) has that display rule.
+- **The achievement's own `points` are yours to show.** The player's Achievement Score is not: your
+  game never computes or restates it (§6).
+
+## 6. Points are prestige: the Achievement Score
 
 Achievement points are a player's permanent standing on the arcade. They are **never spent,
 bought, boosted, decayed or expired**, and they are **removed only for fraud or moderation**.

package/docs/api/api-reference-game.md

@@ -1,6 +1,6 @@
 # The browser surface — API reference
 
-Generated from `@indiegems/gem-web-sdk/sdk` v7.8.0. Every symbol below links to its page on the Gem Arcade developer site.
+Generated from `@indiegems/gem-web-sdk/sdk` v7.9.0. Every symbol below links to its page on the Gem Arcade developer site.
 
 `@indiegems/gem-web-sdk/sdk` is the one import a game writes, wherever its code runs. `@indiegems/gem-web-sdk/game` exports exactly the symbols on this page and nothing else, for a build that wants only this half.
 
@@ -4886,6 +4886,30 @@ wallet.
 **Returns.** whether the message left the frame — `false` before the bridge is
   up, for an arcade with no wallet, and past this frame's own limit.
 
+## GemFrame.setMenu
+
+[GemFrame.setMenu](https://gemarcade.com/developer/api/game#gemframe-setmenu)
+
+```ts
+setMenu(settings: boolean, items?: readonly { id: string; label: string }[]): boolean
+```
+
+Tell the arcade what your game adds to its menu: whether it has a settings
+screen, and up to four entries of its own — the whole answer each time, the
+latest one winning.
+
+Prefer `gem.setMenu`, which holds the state across a reconnect and calls
+your handlers when the player chooses an entry. This one sends only while
+connected, and only to an arcade that draws a menu.
+
+| Parameter | Type |
+| --- | --- |
+| `settings` | `boolean` |
+| `items` | `readonly { id: string; label: string }[]` |
+
+**Returns.** whether the message left the frame — `false` before the bridge is
+  up, for an arcade with no menu, and past this frame's own limit.
+
 ## GemFrame.requestShare
 
 [GemFrame.requestShare](https://gemarcade.com/developer/api/game#gemframe-requestshare)
@@ -6769,8 +6793,8 @@ The unsafe margin on each edge of your frame.
 readonly reserved: readonly GemReservedArea[]
 ```
 
-Rectangles of your frame the arcade's own controls cover — its Back tab in
-the top-left corner, and the wallets in the top-right while they are shown (see
+Rectangles of your frame the arcade's own controls cover — its menu button
+in the top-right corner, and the wallets beside it while they are shown (see
 `setWalletVisible`). Keep essential UI and touch targets out of them. Empty
 when the arcade covers nothing.
 
@@ -6853,6 +6877,83 @@ matched exactly, and the literal `'score'` for the achievement score. Only
 for a screen about one currency, such as a ticket store; leave it out and
 every wallet shows, which is always safe.
 
+## GameMenuItem
+
+[GameMenuItem](https://gemarcade.com/developer/api/game#gamemenuitem)
+
+```ts
+interface GameMenuItem
+```
+
+One entry of your own in the arcade's menu.
+
+## GameMenuItem.id
+
+[GameMenuItem.id](https://gemarcade.com/developer/api/game#gamemenuitem-id)
+
+```ts
+readonly id: string
+```
+
+Your own name for the entry, 1 to 32 characters, unique among your items.
+An entry with an empty or longer id is left out.
+
+## GameMenuItem.label
+
+[GameMenuItem.label](https://gemarcade.com/developer/api/game#gamemenuitem-label)
+
+```ts
+readonly label: string
+```
+
+What the player reads, **already in the player's language**
+(`gem.prefs.locale`) — the arcade does not translate it. Keep it short:
+anything past 40 characters is cut, and the arcade may shorten it further
+to fit.
+
+## GameMenuItem.onSelect
+
+[GameMenuItem.onSelect](https://gemarcade.com/developer/api/game#gamemenuitem-onselect)
+
+```ts
+readonly onSelect: () => void
+```
+
+Called when the player chooses this entry. The arcade has closed its menu
+and your game is running again by the time this fires.
+
+## GameMenu
+
+[GameMenu](https://gemarcade.com/developer/api/game#gamemenu)
+
+```ts
+interface GameMenu
+```
+
+What your game adds to the arcade's menu — see `gem.setMenu`.
+
+## GameMenu.onSettings
+
+[GameMenu.onSettings](https://gemarcade.com/developer/api/game#gamemenu-onsettings)
+
+```ts
+readonly onSettings?: () => void
+```
+
+Open your settings screen. Give this and the arcade's menu gains a
+Settings entry that calls it; leave it out and there is no such entry.
+
+## GameMenu.items
+
+[GameMenu.items](https://gemarcade.com/developer/api/game#gamemenu-items)
+
+```ts
+readonly items?: readonly GameMenuItem[]
+```
+
+Up to four entries of your own, shown in this order below the arcade's.
+A fifth and later are left out.
+
 ## GemTerminationNotice
 
 [GemTerminationNotice](https://gemarcade.com/developer/api/game#gemterminationnotice)
@@ -7566,12 +7667,13 @@ reportMuted(muted: boolean): void
 ```
 
 Tell the arcade the player muted or unmuted **inside your game**, so the
-arcade's own mute button shows the same thing.
+arcade's own mute entry shows the same thing.
 
-**Every game needs its own mute control**: on a phone the arcade shows no
-mute button at all, so yours is the player's only one. Call it once at start-up with the
+**Every game needs its own mute control**, in its settings: the arcade's
+menu has a mute entry, and under an embedder with no menu yours is the
+player's only one. Call it once at start-up with the
 setting you saved, and again every time the player changes it — and pair it
-with `onPrefs`, because a press of the arcade's button arrives there as
+with `onPrefs`, because a press of the arcade's entry arrives there as
 `prefs.muted`, and your own control should follow it. With both halves the
 player has one mute instead of two that disagree.
 
@@ -7667,8 +7769,9 @@ ticketStore.onOpen = () => gem.setWalletVisible(true, { only: ['ARCADE_TICKETS']
 replaces the last. While hidden, the arcade still pops a wallet up for a
 moment when something happens to it — a reward you cued, a spend, a
 landing — and your state never cancels that. Shown wallets cover part of
-your frame's top-right corner, which arrives as a rectangle in
-`gem.viewport.reserved`; hiding them gives that space back. A wallet the
+your frame's top-right corner, beside the arcade's menu button, which
+arrives as a rectangle in `gem.viewport.reserved`; hiding them gives that
+space back. A wallet the
 arcade pops up for a moment floats over your game and moves nothing.
 
 **Never draw a platform balance yourself**, and never show a pending state
@@ -7684,6 +7787,52 @@ for one: the arcade takes every figure from the platform. If this returns
   up (the state is held and sent when it connects) and under an embedder
   that draws no wallet.
 
+## Gem.setMenu
+
+[Gem.setMenu](https://gemarcade.com/developer/api/game#gem-setmenu)
+
+```ts
+setMenu(menu: GameMenu): boolean
+```
+
+Put your settings, and up to four entries of your own, in the arcade's
+menu. The arcade keeps one menu button over your game, in the top-right
+corner: it is how a player leaves, mutes, goes fullscreen and reports a
+problem — and, once you call this, how they open **your** settings.
+
+```js
+const inArcadeMenu = gem.setMenu({
+  onSettings: () => settingsScreen.open(),
+  items: [{ id: 'how-to-play', label: t('How to play'), onSelect: () => help.open() }],
+});
+ownSettingsButton.hidden = inArcadeMenu;
+```
+
+**Do not draw a settings button of your own while this returns `true`** —
+the arcade's menu is the one place a player looks, in every game. Draw
+your own only when it returns `false` once the bridge has settled
+(`await gem.awaitBridge()`): an embedder with no menu, or no embedder at
+all. The top-left corner is yours, for a back or home button that moves
+around inside your game.
+
+**It is screen state, not a toggle.** Each call is the whole answer and
+replaces the last, so call it again when the entries change — a new
+language, a screen with different options. `gem.setMenu({})` takes
+everything of yours back out. The arcade's own entries are not yours to
+change, and Return to the Arcade is always among them.
+
+**The arcade pauses your game while its menu is open** (`onPause`), and
+resumes it before a handler of yours runs. A handler opens a screen; it
+should not assume the game was paused by you.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `menu` | `GameMenu` | Your settings handler and your own entries. |
+
+**Returns.** `true` when the arcade was told now; `false` before the bridge is
+  up (the menu is held and sent when it connects) and under an embedder
+  that draws no menu.
+
 ## Gem.exit
 
 [Gem.exit](https://gemarcade.com/developer/api/game#gem-exit)

package/docs/api/api-reference-server.md

@@ -1,6 +1,6 @@
 # The server surface — API reference
 
-Generated from `@indiegems/gem-web-sdk/sdk` v7.8.0. Every symbol below links to its page on the Gem Arcade developer site.
+Generated from `@indiegems/gem-web-sdk/sdk` v7.9.0. Every symbol below links to its page on the Gem Arcade developer site.
 
 `@indiegems/gem-web-sdk/sdk` is the one import a game writes, wherever its code runs. `@indiegems/gem-web-sdk/server` exports exactly the symbols on this page and nothing else, for a build that wants only this half.
 

package/docs/api/reference.json

@@ -2,7 +2,7 @@
   "schema_version": 1,
   "source": {
     "repo": "IndieGems/gem-web-sdk",
-    "version": "7.8.0"
+    "version": "7.9.0"
   },
   "entries": [
     {
@@ -6130,6 +6130,36 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "GemFrame.setMenu",
+          "name": "setMenu",
+          "anchor": "gemframe-setmenu",
+          "group": "frame",
+          "url": "https://gemarcade.com/developer/api/game#gemframe-setmenu",
+          "signature": "setMenu(settings: boolean, items?: readonly { id: string; label: string }[]): boolean",
+          "documented": true,
+          "summary": "Tell the arcade what your game adds to its menu: whether it has a settings\nscreen, and up to four entries of its own — the whole answer each time, the\nlatest one winning.\n\nPrefer `gem.setMenu`, which holds the state across a reconnect and calls\nyour handlers when the player chooses an entry. This one sends only while\nconnected, and only to an arcade that draws a menu.",
+          "deprecated": null,
+          "params": [
+            {
+              "name": "settings",
+              "type": "boolean",
+              "optional": false,
+              "summary": null
+            },
+            {
+              "name": "items",
+              "type": "readonly { id: string; label: string }[]",
+              "optional": true,
+              "summary": null
+            }
+          ],
+          "returns": "whether the message left the frame — `false` before the bridge is\n  up, for an arcade with no menu, and past this frame's own limit.",
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "GemFrame.requestShare",
           "name": "requestShare",
@@ -8188,7 +8218,7 @@
           "url": "https://gemarcade.com/developer/api/game#gemviewport-reserved",
           "signature": "readonly reserved: readonly GemReservedArea[]",
           "documented": true,
-          "summary": "Rectangles of your frame the arcade's own controls cover — its Back tab in\nthe top-left corner, and the wallets in the top-right while they are shown (see\n`setWalletVisible`). Keep essential UI and touch targets out of them. Empty\nwhen the arcade covers nothing.\n\nA stylesheet reads the per-corner custom properties the SDK stamps from\nthese instead — `--gem-reserved-tl-height` and friends.",
+          "summary": "Rectangles of your frame the arcade's own controls cover — its menu button\nin the top-right corner, and the wallets beside it while they are shown (see\n`setWalletVisible`). Keep essential UI and touch targets out of them. Empty\nwhen the arcade covers nothing.\n\nA stylesheet reads the per-corner custom properties the SDK stamps from\nthese instead — `--gem-reserved-tl-height` and friends.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -8316,6 +8346,125 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "GameMenuItem",
+          "name": "GameMenuItem",
+          "anchor": "gamemenuitem",
+          "group": "frame",
+          "url": "https://gemarcade.com/developer/api/game#gamemenuitem",
+          "signature": "interface GameMenuItem",
+          "documented": true,
+          "summary": "One entry of your own in the arcade's menu.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GameMenuItem.id",
+          "name": "id",
+          "anchor": "gamemenuitem-id",
+          "group": "frame",
+          "url": "https://gemarcade.com/developer/api/game#gamemenuitem-id",
+          "signature": "readonly id: string",
+          "documented": true,
+          "summary": "Your own name for the entry, 1 to 32 characters, unique among your items.\nAn entry with an empty or longer id is left out.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GameMenuItem.label",
+          "name": "label",
+          "anchor": "gamemenuitem-label",
+          "group": "frame",
+          "url": "https://gemarcade.com/developer/api/game#gamemenuitem-label",
+          "signature": "readonly label: string",
+          "documented": true,
+          "summary": "What the player reads, **already in the player's language**\n(`gem.prefs.locale`) — the arcade does not translate it. Keep it short:\nanything past 40 characters is cut, and the arcade may shorten it further\nto fit.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GameMenuItem.onSelect",
+          "name": "onSelect",
+          "anchor": "gamemenuitem-onselect",
+          "group": "frame",
+          "url": "https://gemarcade.com/developer/api/game#gamemenuitem-onselect",
+          "signature": "readonly onSelect: () => void",
+          "documented": true,
+          "summary": "Called when the player chooses this entry. The arcade has closed its menu\nand your game is running again by the time this fires.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GameMenu",
+          "name": "GameMenu",
+          "anchor": "gamemenu",
+          "group": "frame",
+          "url": "https://gemarcade.com/developer/api/game#gamemenu",
+          "signature": "interface GameMenu",
+          "documented": true,
+          "summary": "What your game adds to the arcade's menu — see `gem.setMenu`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GameMenu.onSettings",
+          "name": "onSettings",
+          "anchor": "gamemenu-onsettings",
+          "group": "frame",
+          "url": "https://gemarcade.com/developer/api/game#gamemenu-onsettings",
+          "signature": "readonly onSettings?: () => void",
+          "documented": true,
+          "summary": "Open your settings screen. Give this and the arcade's menu gains a\nSettings entry that calls it; leave it out and there is no such entry.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GameMenu.items",
+          "name": "items",
+          "anchor": "gamemenu-items",
+          "group": "frame",
+          "url": "https://gemarcade.com/developer/api/game#gamemenu-items",
+          "signature": "readonly items?: readonly GameMenuItem[]",
+          "documented": true,
+          "summary": "Up to four entries of your own, shown in this order below the arcade's.\nA fifth and later are left out.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "GemTerminationNotice",
           "name": "GemTerminationNotice",
@@ -9001,7 +9150,7 @@
           "url": "https://gemarcade.com/developer/api/game#gem-reportmuted",
           "signature": "reportMuted(muted: boolean): void",
           "documented": true,
-          "summary": "Tell the arcade the player muted or unmuted **inside your game**, so the\narcade's own mute button shows the same thing.\n\n**Every game needs its own mute control**: on a phone the arcade shows no\nmute button at all, so yours is the player's only one. Call it once at start-up with the\nsetting you saved, and again every time the player changes it — and pair it\nwith `onPrefs`, because a press of the arcade's button arrives there as\n`prefs.muted`, and your own control should follow it. With both halves the\nplayer has one mute instead of two that disagree.\n\n```js\nconst gem = createGem({\n  // ...\n  onPrefs: (prefs) => sound.setMuted(prefs.muted),\n});\ngem.reportMuted(sound.muted); // at start-up, with the saved setting\nmuteButton.onclick = () => {\n  sound.setMuted(!sound.muted);\n  gem.reportMuted(sound.muted); // and on every change\n};\n```\n\nSafe to call at any time. Before the bridge is up the value is held and sent\nwhen it connects; an arcade that does not mirror a game's mute is simply not\ntold; and calling it from `onPrefs` is fine — a report that matches what the\narcade just said is not sent.",
+          "summary": "Tell the arcade the player muted or unmuted **inside your game**, so the\narcade's own mute entry shows the same thing.\n\n**Every game needs its own mute control**, in its settings: the arcade's\nmenu has a mute entry, and under an embedder with no menu yours is the\nplayer's only one. Call it once at start-up with the\nsetting you saved, and again every time the player changes it — and pair it\nwith `onPrefs`, because a press of the arcade's entry arrives there as\n`prefs.muted`, and your own control should follow it. With both halves the\nplayer has one mute instead of two that disagree.\n\n```js\nconst gem = createGem({\n  // ...\n  onPrefs: (prefs) => sound.setMuted(prefs.muted),\n});\ngem.reportMuted(sound.muted); // at start-up, with the saved setting\nmuteButton.onclick = () => {\n  sound.setMuted(!sound.muted);\n  gem.reportMuted(sound.muted); // and on every change\n};\n```\n\nSafe to call at any time. Before the bridge is up the value is held and sent\nwhen it connects; an arcade that does not mirror a game's mute is simply not\ntold; and calling it from `onPrefs` is fine — a report that matches what the\narcade just said is not sent.",
           "deprecated": null,
           "params": [
             {
@@ -9049,7 +9198,7 @@
           "url": "https://gemarcade.com/developer/api/game#gem-setwalletvisible",
           "signature": "setWalletVisible(visible: boolean, options?: WalletVisibleOptions): boolean",
           "documented": true,
-          "summary": "Show or hide the player's wallets — Gems, Tickets, the achievement score —\nthat the arcade draws over your game. **They are shown until you say\notherwise**: hide them during gameplay, show them again on your menus.\n\n```js\nlevel.onStart = () => gem.setWalletVisible(false);\nmenu.onOpen = () => gem.setWalletVisible(true);\n// A screen that sells in one currency may narrow it:\nticketStore.onOpen = () => gem.setWalletVisible(true, { only: ['ARCADE_TICKETS'] });\n```\n\n**It is screen state, not a toggle.** Each call is the whole answer and\nreplaces the last. While hidden, the arcade still pops a wallet up for a\nmoment when something happens to it — a reward you cued, a spend, a\nlanding — and your state never cancels that. Shown wallets cover part of\nyour frame's top-right corner, which arrives as a rectangle in\n`gem.viewport.reserved`; hiding them gives that space back. A wallet the\narcade pops up for a moment floats over your game and moves nothing.\n\n**Never draw a platform balance yourself**, and never show a pending state\nfor one: the arcade takes every figure from the platform. If this returns\n`false`, do nothing in its place.",
+          "summary": "Show or hide the player's wallets — Gems, Tickets, the achievement score —\nthat the arcade draws over your game. **They are shown until you say\notherwise**: hide them during gameplay, show them again on your menus.\n\n```js\nlevel.onStart = () => gem.setWalletVisible(false);\nmenu.onOpen = () => gem.setWalletVisible(true);\n// A screen that sells in one currency may narrow it:\nticketStore.onOpen = () => gem.setWalletVisible(true, { only: ['ARCADE_TICKETS'] });\n```\n\n**It is screen state, not a toggle.** Each call is the whole answer and\nreplaces the last. While hidden, the arcade still pops a wallet up for a\nmoment when something happens to it — a reward you cued, a spend, a\nlanding — and your state never cancels that. Shown wallets cover part of\nyour frame's top-right corner, beside the arcade's menu button, which\narrives as a rectangle in `gem.viewport.reserved`; hiding them gives that\nspace back. A wallet the\narcade pops up for a moment floats over your game and moves nothing.\n\n**Never draw a platform balance yourself**, and never show a pending state\nfor one: the arcade takes every figure from the platform. If this returns\n`false`, do nothing in its place.",
           "deprecated": null,
           "params": [
             {
@@ -9071,6 +9220,30 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "Gem.setMenu",
+          "name": "setMenu",
+          "anchor": "gem-setmenu",
+          "group": "start",
+          "url": "https://gemarcade.com/developer/api/game#gem-setmenu",
+          "signature": "setMenu(menu: GameMenu): boolean",
+          "documented": true,
+          "summary": "Put your settings, and up to four entries of your own, in the arcade's\nmenu. The arcade keeps one menu button over your game, in the top-right\ncorner: it is how a player leaves, mutes, goes fullscreen and reports a\nproblem — and, once you call this, how they open **your** settings.\n\n```js\nconst inArcadeMenu = gem.setMenu({\n  onSettings: () => settingsScreen.open(),\n  items: [{ id: 'how-to-play', label: t('How to play'), onSelect: () => help.open() }],\n});\nownSettingsButton.hidden = inArcadeMenu;\n```\n\n**Do not draw a settings button of your own while this returns `true`** —\nthe arcade's menu is the one place a player looks, in every game. Draw\nyour own only when it returns `false` once the bridge has settled\n(`await gem.awaitBridge()`): an embedder with no menu, or no embedder at\nall. The top-left corner is yours, for a back or home button that moves\naround inside your game.\n\n**It is screen state, not a toggle.** Each call is the whole answer and\nreplaces the last, so call it again when the entries change — a new\nlanguage, a screen with different options. `gem.setMenu({})` takes\neverything of yours back out. The arcade's own entries are not yours to\nchange, and Return to the Arcade is always among them.\n\n**The arcade pauses your game while its menu is open** (`onPause`), and\nresumes it before a handler of yours runs. A handler opens a screen; it\nshould not assume the game was paused by you.",
+          "deprecated": null,
+          "params": [
+            {
+              "name": "menu",
+              "type": "GameMenu",
+              "optional": false,
+              "summary": "Your settings handler and your own entries."
+            }
+          ],
+          "returns": "`true` when the arcade was told now; `false` before the bridge is\n  up (the menu is held and sent when it connects) and under an embedder\n  that draws no menu.",
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "Gem.exit",
           "name": "exit",

package/docs/changelog.md

@@ -47,7 +47,7 @@ Upgrading from 7.3.1. Impact: required.
 ### Must change
 
 - The Arcade shows its wallets, Gems, Tickets and the Achievement Score, over your game by default. Call gem.setWalletVisible(false) when gameplay starts and gem.setWalletVisible(true) on your menus. On a screen that sells in one currency, show just that wallet by passing its slug in the only option.
-- On phones the Arcade's Back tab and wallets sit in the frame's top-left corner, and gem.viewport now reports that corner in reserved instead of folding it into the top inset. Keep the corner clear by reading gem.viewport.reserved or the --gem-reserved-tl-width and --gem-reserved-tl-height CSS variables. Put your settings top-right, and draw no back arrow of your own top-left.
+- On phones the Arcade's Back tab and wallets sit in the frame's top-left corner, and gem.viewport now reports that corner in reserved instead of folding it into the top inset. Keep the corner clear by reading gem.viewport.reserved or the --gem-reserved-tl-width and --gem-reserved-tl-height CSS variables. Put your settings top-right.
 - GemFunctionError's retryAfterSeconds is now read-only. Code that assigns to it no longer compiles.
 
 ### Rebuild

package/docs/daily-challenges.md

@@ -246,14 +246,13 @@ you almost certainly do not want to:
 | Storefront marker, My Games  | yes                                           | yes                                      |
 | Rewards, platform grants     | yes                                           | yes                                      |
 | The platform-wide **streak** | yes                                           | **no** — a streak of its own, on your store page |
-| The player's history calendar| yes                                           | no                                       |
 | Label in the arcade          | localised in every language the arcade speaks | generic                                  |
 | Period length                | a day, a week, a month                        | must be between **1 and 31 days**        |
 
 A streak spans games, which only works when every game agrees on what the player's "today" is. A
 custom cron period is yours alone and cannot be compared with anything, so a cron challenge is
 **game-local**: it shows progress, pays and keeps its own streak, and it never joins the
-platform-wide streak or a history.
+platform-wide streak.
 
 **If you wrote `0 0 * * *`, write `daily`.** The upload stores it as `daily` either way — which puts
 it on each player's own calendar, not on UTC midnight. Reach for a custom cron only when the period
@@ -542,10 +541,11 @@ Three things to know before you build a mechanic on it:
 - **One completion is a day.** A player who finishes three of your challenges advances their streak
   once, the same as a player who finishes one. A streak measures days the player showed up, not how
   much a game offered.
-- **A streak is the platform's, and it is shown on platform surfaces.** Your game reports progress
-  and does not read the streak back — see below.
-- **Whether a player's streak is shown at all can depend on who they are.** Some players do not see
-  streak surfaces. Do not design a mechanic whose fairness depends on every player seeing one.
+- **A streak is the platform's.** Your game reports progress and does not read the streak back —
+  see below.
+- **The arcade does not display the platform-wide streak.** The platform counts it, but no arcade
+  surface shows it to the player today. Do not tell players about it, and do not design a mechanic
+  that depends on a player seeing it.
 
 Challenges on a custom cron are game-local: each keeps a streak of its own, shown on your game's
 store page, and none advances the platform-wide one ([section 5a](#5a-use-daily-weekly-or-monthly-avoid-cron-for-a-challenge)).
@@ -576,8 +576,9 @@ counts for the day it was played. [A board for each day](leaderboards.md#a-board
 is the page.
 
 **Their per-period history and their streak — no.** There is no history read and no streak read in
-the SDK. The arcade is what displays those — the marker on your game's card, and the player's own
-progress, history and streak on platform surfaces. Your game does not have to render any of it.
+the SDK, and the arcade has no history calendar either. What the arcade displays is the marker on
+your game's card and the player's progress in the current period — plus, for a cron challenge, its
+own streak on your store page. Your game does not have to render any of it.
 
 ## 11. When an upload is refused
 

package/docs/game-economy-tutorial.md

@@ -209,8 +209,9 @@ the one you attempted, rather than resending the purchase.
 
 Your shop can also sell for the arcade's own currencies, and the platform draws one line through
 them: **Tickets buy cosmetics, Gems buy anything.** Each platform currency has a spend scope — Tickets'
-is `cosmetic_only`, Gems' is `any`. Mark a cosmetic in the
-config, and price it in `ARCADE_TICKETS`:
+is `cosmetic_only`, Gems' is `any`. Which currencies your game may price in, and what each may buy,
+is `gemctl platform config`'s answer. Mark a cosmetic in the config, and price it in
+`ARCADE_TICKETS`:
 
 ```yaml
 items: