@indiegems/gem-web-sdk 7.3.1 → 7.4.1

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

@@ -0,0 +1,1231 @@
+# What a game still has to do for itself
+
+The SDK's promise is that a browser game reaches a dedicated multiplayer match without implementing
+WebRTC, server allocation, gem-api auth, or the platform's own handshakes. This page is the other
+half of that promise: **what is left**, stated plainly, so nobody has to discover it during an
+integration.
+
+It is written from two audits, one from each direction. The first game to complete this path in
+production hand-rolled the whole platform layer in a single 854-line file; what that file did which
+every game needs now lives in the SDK. A second game then audited its own platform layer against
+this SDK **row by row, measured in a browser**, and two more things moved here because of it: the
+early-handshake capture, and the backend routing. That audit's "checked and clean" list — what a game
+correctly does _not_ delegate — is the last section of this page, because the half of an ownership
+audit that is easy to skip is the half that says where the line was drawn correctly.
+
+Its companion is [`platform-rules.md`](platform-rules.md): what the _platform_ does that no client-side
+signature states — how a match is sized, when a room disappears, where a room's seats come from and why
+a create cannot ask for its own, how the compatibility line derives from your version number. This page
+is what you own; that one is what is done to you.
+
+## The shortest correct integration
+
+Nothing goes in your HTML. The SDK is a dependency your game bundles — see
+[getting-started](getting-started.md#3-add-the-sdk), which owns the install.
+
+```ts
+import { createGem, text } from '@indiegems/gem-web-sdk/sdk';
+import server from './server.js'; // your server bundle's default export — the one you publish
+
+const gem = createGem({
+  onPlayer: (player) => showName(text.toPlain(player.displayName)),
+});
+
+gem.frame.ready(); // held until the bridge is up, then delivered
+await gem.awaitIdentity(); // the play token, which everything is scoped by
+await gem.rooms.quickJoin({ templateSlug: 'skirmish' });
+await gem.match.serve(server); // your server bundle's default export; runs HERE only if this seat hosts
+const link = await gem.match.connect(); // one link to the authority, whoever the template made that
+// The server has already accepted this player. Start playing. `connect()` dials the
+// transports the room template lists, in its order — no transport is named here;
+// `gem.dedicatedServer` and `gem.p2p` stay underneath for a game that wants their
+// specifics — dedicated-server-flow.md, p2p-and-parties.md.
+```
+
+No `baseUrl`. The Arcade names the backend on every token and the SDK routes there — see
+"which backend" below.
+
+## The five things that are yours
+
+### 1. The embedder allowlist
+
+**This one is done for you, and most games write nothing.** A page may embed your game and hand it
+tokens only if its origin is allowed, and the pages that matter are always allowed without a word
+from you:
+
+- **the Gem Arcade website and app** — the SDK carries their origins as `ARCADE_EMBEDDERS`, on every
+  platform the app runs on;
+- **a dev host on your own machine** — `gemctl serve` and the Gem Editor frame a locally-served game
+  from a loopback origin whose port changes every run, and the SDK admits that shape by rule, only
+  while your game itself is served from loopback. Once published, nothing about the rule applies.
+
+`allowedEmbedders` is for a page **beyond** those, and what you list is **added** to the arcade's
+origins — you cannot drop the arcade by writing your own list:
+
+```ts
+// Only when a site of your own frames your game.
+const gem = createGem({ allowedEmbedders: ['https://my-own-site.example'] });
+```
+
+Name the whole origin — scheme, host and optional port, with nothing after it. `createGem` throws on
+an entry that is not one (a trailing slash, a path, a bare hostname), and on `undefined`, which is
+what `[import.meta.env.VITE_EMBEDDER]` becomes when nothing is set. A well-formed origin that is
+simply wrong fails at the handshake instead, silently on the wire by design: the refusal reaches
+`onRefused` and the SDK warns on the console after eight seconds naming this as one of three causes.
+
+**Bake entries in. Never read them from the URL**: `?embedder=` hands the frame the allowlist that was
+supposed to constrain it. Do not add a `localhost:<port>` entry for a dev host either; the rule above
+already covers it, and an older SDK that refuses that page is fixed by upgrading, not by an entry.
+
+### 2. Your version number, which you no longer declare
+
+**Which number you publish under is yours. Telling the SDK what it is stopped being.** The arcade
+routed this player to one of your builds, so the arcade knows its version, and it now says so over
+the bridge. Every room and match call reports that answer. Pass nothing.
+
+What is still yours is deciding when to bump it, because it is what keeps incompatible builds out of
+one another's matches: bump when you ship something that changes what a match expects.
+
+`clientVersion.gameVersion` is **deprecated** and still accepted. It is the only answer available
+from an arcade too old to send one, so a build that has to run under an older arcade may still pass
+it — and where both exist, the platform's wins and nothing in your running game says so.
+[The deprecation policy](deprecation-policy.md) is how long it has.
+
+Why it went: the number in your source had to be kept in step by hand with the number the build was
+uploaded under, and a live game shipped with the two disagreeing. Every room call was refused for a
+version that named no published build, the refusal landed somewhere that only warns, and for three
+days players earned nothing while the win screen kept promising rewards that were never granted.
+Both halves of the upload agreed with each other, so everything that checks an upload looked correct.
+
+Do not supply `engineVersion`. A browser game is not an engine export and has none; the SDK reports
+one, and a plausible-looking value derives an engine line that matches no fleet and fails at
+allocation — long after the call that decided it, and as a capacity refusal that will never clear.
+[`dedicated-server-flow.md`](dedicated-server-flow.md#two-version-lines-two-derivation-rules-and-a-refusal-that-names-neither)
+is how to tell that one from a fleet that is genuinely full.
+
+Publishing a new version also starts a clock on the one it replaces, and retiring a bad build is
+something you do rather than something the SDK does.
+[`rooms-and-matches.md`](rooms-and-matches.md#what-ages-a-version-out-and-the-three-levers-the-games-owner-has)
+has the expiry window, the blacklist, how a rollback is performed, and what a player's client is
+told when their build ages out.
+
+### 3. The handshake is caught, not awaited
+
+The handshake is **parent-initiated**, and `postMessage` queues for nobody: an offer is delivered to
+the listeners that exist at that instant. **The Arcade re-offers on a steady cadence — one offer
+every two seconds — for as long as the page holds your frame, and never gives up.** So a game that
+boots through a module graph attaches its listener after some offers have passed and connects on the
+next one: usually well under a second, and up to about two in the worst case. That wait is normal
+and is not a retry.
+
+An embedder that is not the Arcade need not behave this way — one that posts a single offer and
+stops is a parent a late listener can miss entirely. `gem-web-sdk.capture.js`, loaded first in the
+document, holds offers that arrive before your bundle does; it is an **optional latency
+optimisation** against the Arcade and insurance against a one-shot parent. It is not part of any
+install, and you do not need it to ship. Where one is used it holds offers untouched until
+`createGem` adopts it — newest first, because an old offer's port may already be superseded and
+answering it wedges the frame.
+
+Either way `createGem` can be called whenever your code is ready, and `ready()` can go wherever it
+reads best; it is held and delivered on connect.
+
+Once it does connect, [the developer panel](getting-started.md#the-developer-panel) will confirm
+it from your side — the bridge's state, the negotiated protocol version and what the parent
+advertised. It cannot help you while the handshake is failing, though: the panel is opened by a
+token grant, and there is no grant without a bridge. A frame that never connects has nothing to
+open.
+
+**What you own is the boot phase, below.** With the parent re-offering, keeping the event loop free
+is the whole of what decides how fast your game connects — a main thread blocked through boot delays
+delivery of an offer that already arrived, and every second of that is a second the player spends
+watching the Arcade's loading state.
+
+### 4. Everything on the channel after the welcome
+
+The platform's envelope is two message types and it is finished before `connect()` resolves. What
+goes on the channel afterwards — JSON, binary, a schema of your own — is opaque to everything above
+the transport, and nothing above the transport bounds its size either, which is a reason for your
+server to bound what it will accept. See [`server-bundles.md`](server-bundles.md).
+
+### 5. What to do about the failures the SDK reports
+
+The SDK reports; it does not decide. A stale build (`versionUpdateAvailable`), a match that failed to
+allocate, a token the parent refused — what a game does about each is a game decision, and a platform
+layer that acted would be making it for you.
+
+## The boot phase: settle the bridge before the heavy bundle
+
+The invariant, stated plainly, because it is the hardest-won lesson in this document:
+
+> **Offers are delivered, not polled — and delivery needs the event loop.** Registering a listener
+> early is worthless if the main thread then executes your application bundle. The offer sits queued
+> behind that work, and by the time it dispatches, the port it carried may already be dead. The
+> parent's re-offer solves the _listening_ half — it keeps offering until you answer. The _delivery_
+> half is yours, and with the capture gone from the default path it is the whole of what you own
+> here: keep the event loop idle until the bridge settles.
+
+The pattern is a two-file boot. The real entry stays small — `createGem` and your splash, nothing
+heavy — and everything expensive sits behind a dynamic import that is not issued until the bridge
+has settled:
+
+```ts
+// boot.ts — the real entry point. Do not add imports here without asking what they pull in.
+import { createGem } from '@indiegems/gem-web-sdk/sdk';
+
+const gem = createGem();
+
+try {
+  await gem.awaitBridge(); // the loop is idle through the offer window
+  gem.frame?.progress(1, 4);
+  const { runApp } = await import('./app.ts'); // NOW fetch, parse and execute the megabytes
+  gem.frame?.progress(2, 4);
+  await runApp(gem);
+} finally {
+  gem.frame?.ready(); // even on failure — see the loading contract
+}
+```
+
+`awaitBridge()` resolves when the bridge leaves `waiting` — connected, refused or closed — or at a
+bounded timeout (default 10s), with the state it settled on. **Proceed on every outcome.**
+`connected` is the Arcade; anything else is a boot without a parent, which your game must survive
+anyway. The wait costs nothing when the handshake is quick: it settles the moment the frame
+connects. Unframed it is never answered, because no parent ever pushes one.
+
+The measured stakes, from the first game to hit this on an iPhone: listener up at ~300ms, then a
+main-thread block — the parent's offer, queued behind the block, was delivered twenty seconds later
+into a port closed ten seconds earlier. Same page, connect or time out, decided by nothing but
+whether the loop was idle. The entry split also buys the listening half for free: a boot module of
+"params + SDK" registers at ~300ms where a full bundle takes seconds.
+
+## The loading contract
+
+The parent shows its loading state until your frame says otherwise. The whole contract is four
+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.
+- **`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
+  above safe to write.
+- **Send it even when the boot failed.** A frame that never says ready sits behind the parent's
+  loading state forever, with your error message underneath where nobody can read it. The `finally`
+  is not decoration.
+- **`progress(n, total)` at coarse milestones** — bridge, app module, engine, world is plenty. It is
+  rate-limited per message type like everything else on the bridge; a per-asset progress loop will
+  be throttled, and a progress call after `ready` is meaningless to a parent that has already
+  unveiled you.
+
+## Boot diagnostics: where the seconds went
+
+`gem.boot` is a timeline of named marks, one greppable line out of `gem.boot.timeline()`:
+
+```
+document parsed@294ms → sdk created@336ms (+42ms) → bridge connected@388ms (+52ms) →
+token requested@389ms (+1ms) → token ready@913ms (+524ms) → room joined@1109ms (+196ms) → …
+```
+
+The SDK marks what it owns — `document parsed`, `sdk created`, `bridge connected`,
+`token requested`, `token ready`/`token lost`, `room created`/`room joined`, `allocation started`,
+`match ready`/`match failed`, `welcome` — so the platform's share of a slow boot is individually
+attributable in any player's console capture. Mark the steps you own (`gem.boot.mark('world
+ready')`) and both halves land in the same line. A name marks once; boot happens once.
+
+Two lines print themselves: at the eight-second mark the SDK logs the boot report — connected or
+not — because **field captures attach to a frame's console late, and boot-time logs never appear in
+them**; and when a connection completes — the dedicated-server welcome, or a P2P peer reaching a
+usable state — the finished line prints once. Both respect `log: null`. Every timing mystery in the
+incident that motivated this instrument was solved the day the numbers existed; when a player
+capture lands on your desk, this line is the first thing to grep for.
+
+The arcade will also render this timeline for you, over a running game, without a capture and
+without any code — see
+[the developer panel](getting-started.md#the-developer-panel).
+
+### The two multiplayer journeys report differently, because they are different
+
+Everything above the match is shared. After it the paths have nothing in common — there is no
+allocation to wait for on a P2P match, no server the platform vouches for, and "ready" means
+something different at each end of the star — so the marks name what actually happens rather than
+being forced into one vocabulary:
+
+```
+… → match ready@1250ms (+50ms) → turn leased@1402ms (+152ms) → signaling joined@1421ms (+19ms) →
+signaling hello@1502ms (+81ms) → offer sent@1530ms (+28ms) → answer received@1655ms (+125ms) →
+credential ready@3702ms (+2047ms) → host verified@3703ms (+1ms) → channel open@3980ms (+277ms) →
+admitted@4020ms (+40ms)
+```
+
+- **`turn leased`, `turn lease failed` or `turn skipped`** — whether this peer got a relay. The
+  connection proceeds either way, which is why this is worth a mark: without one, peers on the same
+  network connect fine and peers behind a symmetric NAT never do. A network that blocks direct
+  connections outright is a known gap, and this is what makes it legible in a capture.
+- **`signaling joined`, then `signaling hello`** — the join went to the parent, and the platform
+  answered with who this peer is, who the host is and at what epoch. A line that ends at the first
+  is a parent not putting frames on the socket, which is a different problem from a connection that
+  failed to form.
+- **A joiner** then marks `offer sent`, `answer received`, `credential ready`, `host verified`,
+  `channel open` and `admitted`. The answer and the credential race by design, in either order, and
+  `host verified` waits on whichever lands second — the first credential request is refused until
+  the host has answered somebody, so a multi-second gap before `credential ready` is that refusal
+  being retried, not a slow network.
+- **A host** marks `host listening` and stops: it is usable before anyone has arrived. What follows
+  — `offer received`, `answer sent`, `channel open`, `peer admitted` — is the first joiner's
+  arrival, which may be minutes later and is the only thing in a host's own capture that says
+  somebody got through.
+
+A line that stops at `host verified` with nothing after it is ICE and DTLS never completing: the
+peers could not reach each other directly, and either no relay was leased or the relay could not
+help. That is the shape a corporate or campus network produces.
+
+## The environment your game actually runs in
+
+Facts about the Arcade's runtime that are invisible locally and expensive to discover in
+production:
+
+- **A game frame is never cross-origin isolated**, so `performance.now()` is coarsened to about a
+  millisecond. Anything that spin-waits on clock transitions multiplies its cost by the coarsening:
+  the probe that motivated this list demanded 20,000 transitions, cost 100ms on an isolated page,
+  and froze the Arcade's main thread for **twenty seconds** — which blocked delivery of every
+  handshake offer and was the root cause of the outage the boot-phase section exists to prevent.
+  Naive timer-granularity probes and some engine FPS limiters have this shape.
+  Bound such loops by wall-clock time, never by transition count alone.
+- **WebKit persists no compiled-WASM cache.** Your engine recompiles on every load, warm or cold.
+  Keep WASM modules small; do not attribute the cost to the network.
+- **The edge serves the whole bundle with revalidation** (`Cache-Control: no-cache` semantics). Warm
+  loads still pay a conditional request per asset — fine, but hash your assets so those requests
+  can answer 304.
+- **Game origins carry no `script-src` policy**, so build the page the ordinary way: inline
+  `<script>`, import maps, a CDN-hosted engine and `new Worker(blobURL)` all run. Worth stating
+  because a `script-src` of `'self'` refuses `<script type="importmap">` for **being** inline script
+  whatever URLs it names, which leaves an entry module resolving no imports and nothing rendering —
+  so a game that assumes one and works around it is working around a rule that is not there. What
+  _is_ enforced is `frame-ancestors`, and the containment the whole decision rests on is that **every
+  game is served on its own origin**. The SDK's embedder allowlist is the frame's side of that same
+  header; [the embedder allowlist](#1-the-embedder-allowlist) above says what it admits and when you
+  would add to it.
+
+## Which way the device is held — declare it, do not draw it
+
+A phone and a tablet get held two ways round, and the Arcade tells the player when
+they are holding it a way your game cannot use. **That message is the platform's,
+not yours.** Do not ship a full-screen "please rotate your device" screen of your
+own: it will not be translated into the twelve Arcade locales, it cannot pause the
+Arcade's chrome around it, and it will say something different from every other
+game on the storefront.
+
+What you do instead is declare it on your store page, per device, both keys:
+
+```yaml
+orientations:
+  phone:
+    portrait: full
+    landscape: none
+  tablet:
+    portrait: full
+    landscape: partial
+```
+
+| Value | What the player gets |
+| --- | --- |
+| `full` | nothing — the game plays this way round |
+| `partial` | a dismissible hint, once, if the other way is `full` |
+| `none` | a panel over the paused game asking them to rotate, with "play anyway" |
+
+Three consequences worth knowing before you hit them:
+
+- **The panel reaches your game as `onPause(true)`**, exactly like any other Arcade
+  dialog, and unpauses when the player rotates or chooses "play anyway". If you
+  already honour pause on both edges — [the pause contract](#what-the-parent-says-about-the-session-prefs-pause-and-terminate) — there is no
+  code to write for this at all.
+- **"Play anyway" always exists**, so a `none` declaration is not a guarantee your
+  game will never be rendered that way. A player whose device is in a mount or whose
+  rotation lock is on can decline, and your game still has to not crash.
+- **Declaring nothing means no message**, which is what every game did before this
+  existed. It is not a neutral state so much as an invisible one: a portrait-only
+  game with no declaration reads, to a player, exactly like a game that plays fine
+  sideways.
+
+The Arcade also holds the orientation for the player where the browser allows it —
+one refused orientation, in fullscreen, once they are already the right way round.
+That is best effort (iOS does not implement it, and the native app's webview declines
+it), which is why the panel exists and why it always offers a way past.
+
+## A television, if a player puts you on one
+
+The Arcade runs in TV browsers and on TV hardware, so a game can find itself ten feet from its
+player, driven by a remote — and **nothing tells you that it happened**. No form-factor signal
+crosses the bridge; that is an owner decision, not an oversight. Form factor is fungible, so a game
+does the best it can from its own signals — its viewport geometry, `devicePixelRatio`, pointer
+coarseness, and the arrival of gamepad or keyboard-class input — rather than branch on a
+classification the parent declared. The bar below is written to be satisfiable with no parent signal
+at all.
+
+It is also the meaning of your store page's **`form_factors.tv`** declaration: `full` claims this
+bar, `partial` claims it with limitations the page says out loud, and `none` says the game is not
+for a television. `form_factors` declares all four of `phone` / `tablet` / `desktop` / `tv`,
+because which devices a game is built for cannot be inferred from anything else you publish. There
+is no floor: `none` is a perfectly good answer, and a deliberate `none` is far better for a player
+than a `full` you did not earn.
+
+**Adding it is one block, on any store page you already have.** Every schema version accepts
+`form_factors`; the newest one requires it, which is the whole difference between v2 and v3. So
+there is nothing to migrate and no `schema_version` to change — `gemctl store init` writes that
+field, and it is a fact about the backend you publish to rather than a statement about your game.
+
+A page that has not declared it is served as `none` on every factor. That shows **no device
+badges** — it is the platform declining to claim on your behalf, not a statement that your game
+works nowhere — so there is no rush and nothing degrades. It does mean a TV-ready game gets no
+credit for it until you say so.
+
+- **Legibility at ten feet.** Effective body and HUD text at least ~24px at 1080p, and nothing
+  informational below ~18px effective. The practical shape is a UI driven by rem or a single scale
+  factor, so one root multiplier — 1.5x is the number the Arcade's own TV mode uses — rescales the
+  whole interface instead of needing a per-screen audit. A 14px HUD that reads fine on a monitor is
+  decoration from a couch, and there is no zoom to rescue it.
+- **Gamepad-complete menus, with a focus state visible at distance.** Every menu, pause screen,
+  inventory and dialog operable on the standard gamepad mapping with the pointer unused, and a focus
+  cue thicker than a hairline — a 1px outline disappears at ten feet. TV remotes arrive as
+  **keyboard-class events** (arrows, Enter, Back), so a game that calls itself a keyboard game is a
+  D-pad game on a TV whether it planned to be or not.
+- **Title-safe layout.** HUD and critical UI inset at least ~5% of the frame — roughly 48–96px at
+  1080p. `env(safe-area-inset-*)` resolves to **0 on every TV**: overscan is a hardware crop the
+  browser cannot see, so no platform can hand you the number and your game must apply its own
+  margin. The arcade's safe-area insets (`gem.viewport`, below) are **also 0 on a TV**, by
+  design — they carry the cutouts the browser can see, never the overscan allowance, so they do
+  not double with the margin you apply here. Keep both: `max(your margin, var(--gem-safe-top))`.
+- **No hover-only affordances, and no pointer-precision dependencies.** There may be no pointer at
+  all. Anything that only reveals on hover, or demands accurate pointing, is simply absent on a TV.
+- **Text entry the on-screen keyboard can serve.** Focusing a field summons the TV's OSK, so keep
+  entry fields few and ordinary — and never gate first play behind one. A player made to type on a
+  remote before they may play mostly does not.
+- **A TV performance budget.** TV-browser SoCs are weak next to any desktop: ship a player-settable
+  render-scale option (render at DPR 1 and upscale), bound memory, assume a fixed 16:9 frame — there
+  is no `orientationchange` rescue coming — and keep your heights `dvh`-safe.
+- **Reduced motion.** TV browsers rarely expose `prefers-reduced-motion`, so the pushed
+  `gem.prefs.reducedMotion` is the only signal a TV player has; honor it. It arrives with
+  [the prefs the parent pushes](#what-the-parent-says-about-the-session-prefs-pause-and-terminate)
+  below.
+
+## What the parent says about the session: prefs, pause and terminate
+
+Five messages arrive that a game cannot ask for — the parent pushes them on its own schedule, and
+there is no route by which the frame could request one. `createGem` forwards all five:
+
+- **`onPrefs`** — `reducedMotion`, `muted`, `locale`, `showFrameStats`, sent once after the
+  handshake and again on every change. Also **held**, as `gem.prefs`, because a component mounted
+  after the push would otherwise have missed it and cannot ask again. Read it where you need it
+  rather than caching it — the locale changes mid-session. `muted` is the Arcade's mute: the SDK
+  silences your page itself, and your own mute control follows it — see
+  [sound](#sound-your-own-mute-control-and-the-arcades) below. `showFrameStats` you need not act
+  on: the SDK counts your frames itself — see [the Arcade's FPS overlay](#the-arcades-fps-overlay). See the language section for how to combine
+  `locale` with your own detection.
+- **`onPause`** — **pause gameplay and release the cursor.** Cooperative; nothing enforces it.
+
+  ```js
+  onPause: (paused) => {
+    if (paused) document.exitPointerLock();
+    // ...stop your loop
+  };
+  ```
+
+  Releasing the cursor is yours to do: pointer lock belongs to the document that took it, so the
+  arcade cannot release yours from outside the frame. Keep it captured and the player cannot click
+  the dialog sitting on top of your game.
+
+  **Save on pause.** When the player taps the Arcade's Back tab, your game is **parked**, not closed:
+  it receives `onPause(true)` and stays loaded while the player browses. They may come back and
+  press Continue — `onPause(false)`, and play resumes where it stopped — or the parked game may be
+  ended up to five minutes later. That end usually comes with `onWillTerminate` first, **but not
+  always**: a player who leaves the Arcade page while your game is parked takes it down with
+  nothing after the pause. So the pause edge is your last guaranteed moment. Write anything the
+  player would mind losing there, and never hold it back for a terminate warning that may not come.
+
+- **`onWillTerminate`** — persist now. `graceMs` is a promise about how long the parent will wait.
+- **`onViewport`** — where your frame's own edges are under a cutout. **Most games need no
+  handler**: the SDK has already written the same numbers to `--gem-safe-top` and friends on your
+  document root before this fires. Held as `gem.viewport`. The next section is the whole story.
+- **`onDeviceSettings`** — the settings the Arcade keeps for your game **on this device**, or
+  `null` when it keeps none. Sent once per session. Held as `gem.deviceSettings.current`, and
+  written back with `gem.deviceSettings.put`. [Device settings](#device-settings-what-this-device-remembers-about-your-game)
+  below says what belongs there and, more importantly, what does not.
+
+Neither `onPause` nor `onWillTerminate` touches a match. A match whose link dropped while the phone was locked
+comes back through the SDK's own reconnect on the next visible edge, and one that ended meanwhile
+raises `matchEnded` on the same edge — [match-session.md](match-session.md) §7. Pause the loop
+on `onPause`; do not leave the room.
+
+🔴 **The assembly used to drop all three.** `GemFrame` parsed them and `createGem` wired none, so a
+game built the one-call way could not hear them — and could not add a handler afterwards either,
+because the frame's callbacks are fixed at construction and `gem.frame` hands back the one already
+built. A game that wanted them had to assemble the parts itself.
+
+✅ **The Arcade now sends all three.** `gem.prefs` on connect and on every change,
+`gem.pause` on tab visibility and when the player taps Back — both edges, and on connect into an
+already-backgrounded tab — and `gem.willTerminate` before a teardown the page itself decides,
+followed by an actual wait for the grace it promised — including the end of a **parked** game (the
+player tapped Back) when its five minutes run out. Some endings get no warning. A player who leaves
+the Arcade page while your game is parked ends it with nothing after the pause it already had —
+save on that pause, as above. And browser Back, a closing tab and a reload cannot be warned about
+at all: the page hears about them only once the frame is already going, and a port message posted
+then is queued into a document that is destroyed before it can be delivered.
+
+⚠️ **Other embedders may still send none of them.** The native Arcade app has no preferences sender
+today, and a third-party embedder need not have one either. So these handlers must be correct when
+they never fire: a game that blocks on `gem.prefs` renders nothing on those surfaces. Treat every one
+of the three as an upgrade to behaviour that already works without it.
+
+## Where your edges are unsafe: the arcade's safe-area insets
+
+A phone has a camera cutout at the top and a home indicator at the bottom, and inside the arcade
+your frame may or may not start where the phone's screen does: on a phone your game fills the
+screen, edge to edge, while on a tablet or a desktop it sits inside the arcade's page. The arcade
+also floats a small control of its own over your game — see
+[reserved areas](#the-arcades-own-controls-reserved-areas) below. The question "how far from my top
+edge is it safe to draw?" has a different answer in each of those layouts, and **your frame cannot
+find it out from the browser.**
+
+`env(safe-area-inset-*)` inside an iframe is unspecified and wrong in both directions
+([w3c/csswg-drafts#4670](https://github.com/w3c/csswg-drafts/issues/4670)): Chrome resolves it to
+**0** in an embedded document, and WebKit hands the frame **the whole phone's values**, unadjusted
+for where the frame sits. So a HUD padded by `env(safe-area-inset-top)` lands under the cutout on
+Android and, wherever the arcade's page already cleared the notch above your frame, sits **twice**
+as far from it as it should. Every game that followed the old advice had exactly this bug, and none
+could fix it locally.
+
+**The arcade measures your frame and tells you.** `gem.viewport` arrives once after the handshake
+and again on every change — a rotation, a fullscreen transition, the controls hiding or showing —
+with four integers in CSS pixels, measured from **your frame's** edges:
+
+```json
+{ "insets": { "top": 0, "right": 0, "bottom": 34, "left": 0 } }
+```
+
+**The SDK writes them to your document root as custom properties before anything else hears
+them**, so the whole migration for a stylesheet is one declaration per edge:
+
+```css
+/* before */
+#hud { top: env(safe-area-inset-top, 0px); }
+
+/* after — right in the arcade, and unchanged everywhere else */
+#hud { top: var(--gem-safe-top, env(safe-area-inset-top, 0px)); }
+```
+
+The `env()` fallback is not decoration. Under a parent that has not sent the message — an older
+arcade, a third-party embedder, your game opened in a plain tab during development — the
+properties are never set and the browser's own answer stands, which is what your game did before.
+Under a parent that has, the variable wins. One line, correct in both worlds. The four names are
+`--gem-safe-top`, `--gem-safe-right`, `--gem-safe-bottom` and `--gem-safe-left`.
+
+**For a HUD you position from script** — a canvas you draw into, an engine's own UI layer — read
+`gem.viewport.insets` at the moment you lay out, or take `onViewport` to re-lay out when it
+changes. It is `null` until the arcade has said, and stays `null` under an embedder that never
+does; treat that as "use `env()`", exactly as the stylesheet fallback does. Do not wait for it
+before drawing the first frame.
+
+**What it is not.** It is not the TV overscan margin — `env()` is 0 on every television and so is
+this; the title-safe margin in the section above is still yours to apply, and the two compose with
+`max()`. It carries no form factor, no orientation and nothing about what the arcade's chrome is
+doing: you learn that part of your box is unusable, not why. And it does not move anything — where
+your HUD sits is still your business; this is the arcade telling you where the edge is, not
+drawing a border.
+
+**Never read `env(safe-area-inset-*)` on its own in a game that runs in the arcade.** Wrap it in
+the `var()` above, or read `gem.viewport`. The release checklist looks for the bare form.
+
+### The arcade's own controls: reserved areas
+
+On a phone your game is full-bleed, and the arcade keeps one cluster of its own on top of it, in the
+**top-left corner** of your frame: a small **Back** tab — the Gem Arcade wordmark — and, beside it,
+the player's wallets (Gems, Tickets, their achievement score) while they are
+[shown](#the-arcades-wallet-show-it-never-draw-it). The cluster stays in the top-left and runs along
+the top row at most about three quarters of the way across on the narrowest phone — but do not
+hard-code a size: read it, as below. Those rectangles of your frame are **reserved**: keep essential
+UI and every touch target out of them.
+
+**The arcade never takes the right side.** Put your own settings, pause or menu button **top-right**
+— that corner is yours. And **do not put a back arrow of your own top-left**: it would sit under the
+arcade's Back tab, which leaves the game, while yours would mean something else.
+
+An inset cannot say that — as a top inset, a tab a few dozen pixels wide would take your whole top
+strip. So `gem.viewport` also carries the rectangles, in the same CSS pixels of your frame, measured
+from its top-left corner:
+
+```json
+{
+  "insets": { "top": 47, "right": 0, "bottom": 34, "left": 0 },
+  "reserved": [{ "x": 8, "y": 51, "width": 104, "height": 34 }]
+}
+```
+
+**The SDK turns them into one pair of custom properties per corner**, written beside
+`--gem-safe-*` before anything else hears the push: `--gem-reserved-tl-width` and
+`--gem-reserved-tl-height`, and the same pair for `tr`, `bl` and `br` — how far that corner's
+reserved rectangles reach in from its two edges. Push the corner's UI clear of it:
+
+```css
+/* a score in the top-left corner, below the cluster */
+#score {
+  top: max(var(--gem-safe-top, env(safe-area-inset-top, 0px)), var(--gem-reserved-tl-height, 0px));
+  left: var(--gem-safe-left, 0px);
+}
+/* or a row along the top, starting after it */
+#top-bar { padding-left: var(--gem-reserved-tl-width, 0px); }
+```
+
+All eight are written on every push, `0px` for a clear corner, so a rotation never leaves a stale
+value; they are never set under an embedder that sends no viewport, which is what the `0px`
+fallback is for. A rectangle belongs to the corner its centre lies nearest to. For a HUD laid out
+from script, read `gem.viewport.reserved` — `[]` when nothing is covered.
+
+**Lay out against it whenever it changes.** Shown wallets widen the reserved area beside the tab;
+hiding them shrinks it back to the tab alone. A wallet the arcade pops up for a moment while they
+are hidden never reserves anything — it floats over your game and moves nothing.
+
+**Older SDKs get it folded into the top inset.** A game on an SDK from before reserved areas cannot
+read the rectangles, so the arcade sends it none and instead raises `insets.top` — and so
+`--gem-safe-top` — past the bottom of the tab. That game keeps working, at the cost of a full-width
+band; upgrading gives the band back.
+
+## Which store-page experiment brought this player in: cohorts
+
+**You need this only if you run an A/B experiment on your store page and want the game to match
+it.** The Arcade can show two versions of a game's store page — a different title, tagline or key
+art — and split new players between them. The game inside never sees the page, so a "cozy farm"
+page can lead straight into a first run that opens on a boss fight. `gem.cohorts` is how the game
+learns which page this player came through.
+
+It is a fourth message the parent pushes and the frame cannot ask for, and it follows the same rules
+as the three above. `createGem` forwards it as `onCohorts` and **holds** it as `gem.cohorts`;
+`gem.awaitCohorts()` waits for it, with a bound.
+
+```js
+const gem = createGem({
+  onCohorts: (cohorts) => {
+    /* on connect, and again if it changes */
+  },
+});
+
+// At the one point you branch — the first run's opening. Short budget.
+const cohorts = await gem.awaitCohorts(1_500); // GemCohorts | null
+const variant = cohorts?.find((c) => c.experimentId === COZY_EXPERIMENT)?.variantKey;
+startFirstRun(variant === 'cozy' ? 'orchard' : 'arena');
+```
+
+What the value means, and the two absences that are not the same thing:
+
+- **Each entry is `{ experimentId, variantKey }`, and both are opaque.** The id is the one the
+  store-page tooling showed you when you created the experiment; the key is the variant name you gave
+  it (`control`, `cozy`). Compare against the ones you set up, and nothing else — the message does
+  not say how the split was made, what the other variants are, or which one is winning.
+- **An empty array is an answer: this player is in no experiment.** The Arcade sends
+  `{ cohorts: [] }` on connect whenever that is so.
+- **`null` is not an answer.** `gem.cohorts` is `null` until the message arrives, and stays `null`
+  under an embedder that never sends one. `awaitCohorts()` resolves `null` rather than rejecting,
+  exactly as `awaitPlayer()` does.
+- **The list converges to empty.** When you conclude an experiment its entry stops arriving — a
+  returning player sees `[]` next session, whichever variant they were in. If the variant decided
+  something durable, record it yourself at the time (a save, a setting) rather than reading the cohort
+  again later and expecting the same answer.
+
+⚠️ **Never block your first frame on it.** Other embedders may send none of these messages, and a
+game that waits for `gem.cohorts` before rendering renders nothing there. Branch at the one point your
+game differs, with a short budget, and let `null` take the default path — a player who missed the
+experiment sees a game, and a player who was in it sees the experiment. **The default branch must be
+a complete game**, because it is what every player outside the experiment plays.
+
+## Device settings: what this device remembers about your game
+
+**You need this only if your game has settings that are about the device rather than the player** —
+a volume, a graphics quality, a resolution scale, a dismissed tip. Your game cannot keep those in
+its own browser storage across builds: every build of a web game runs on its own origin, so a value
+in `localStorage` is gone the moment you publish again. The Arcade keeps one small object for your
+game on the device instead, and the bridge carries it both ways.
+
+It is a fifth message the parent pushes and the frame cannot ask for, plus one the frame sends.
+`createGem` forwards the push as `onDeviceSettings`, **holds** it as `gem.deviceSettings.current`,
+waits for it with `gem.deviceSettings.wait()`, and writes with `gem.deviceSettings.put()`.
+
+```js
+// On boot. Short budget; `null` means "use your defaults" and is the common case.
+const stored = (await gem.deviceSettings.wait(1_500)) ?? {};
+audio.setMasterVolume(stored.volume ?? 1);
+
+// When the player moves the slider: the WHOLE object, every time, debounced.
+await gem.deviceSettings.put({ v: 1, volume: 0.4, quality: 'high' });
+```
+
+What the value means, and what it is not:
+
+- **It is a plain JSON object of your own design**, read back after one JSON round trip. Version it
+  (`v: 1`) so a newer build reads what an older one wrote, and treat any shape as possible on read.
+- **`null` means "nothing stored" and "the embedder never said" alike.** Both take your defaults.
+  `wait()` resolves at once on the first and only at its deadline on the second, and never
+  rejects — like `awaitCohorts()`.
+- **You never name the game or the channel.** The Arcade files the object by the game and channel
+  it is running, so a `dev` build's settings never reach the `release` build of the same game.
+- **`put` resolves for every outcome** — `stored`, `too_large` (over 16 KiB; nothing stored), or
+  `unavailable` (the Arcade could not store it just now; nothing stored). None is an error to a
+  game. Keep running on what you hold.
+
+⚠️ **This is not a save, and progression must never go here.** It does not follow the player to
+another device or browser, every account on the device shares it, and it can vanish at any time —
+cleared site data, a private window, the Arcade evicting it. Anything a player would mind losing,
+and anything that must follow them, is a save or `gem.me.settings`:
+[saving-player-progress.md](saving-player-progress.md#device-settings-local-to-this-device-and-only-that)
+draws the line in full. Never block your first frame on it either: apply defaults, then apply what
+arrives.
+
+## Sound: your own mute control, and the Arcade's
+
+**Every game needs its own mute control**, in its settings or its pause menu, because on a phone
+the Arcade shows **no** mute button: your game fills the screen and the Arcade's only control over
+it is the Back tab. A player on a phone who wants silence has your control and nothing else.
+
+Wire it both ways, so the player has one mute rather than two that disagree:
+
+```js
+const gem = createGem({
+  // ...
+  // The Arcade's mute changed (desktop, tablet, TV): follow it.
+  onPrefs: (prefs) => sound.setMuted(prefs.muted),
+});
+
+// Tell the Arcade what you saved, and every change the player makes.
+gem.reportMuted(sound.muted);
+muteButton.onclick = () => {
+  sound.setMuted(!sound.muted);
+  gem.reportMuted(sound.muted);
+};
+```
+
+`gem.reportMuted` is safe to call at any time. Before the connection exists the value is held and
+sent when the Arcade connects; an embedder with no mute button is simply not told; and calling it from
+`onPrefs` is fine, because a report that matches what the Arcade just said is not sent.
+
+**Do both halves.** A game that reports its mute but ignores `prefs.muted` leaves the Arcade's
+button saying one thing while the game does the other; a game that follows `prefs.muted` but never
+reports leaves the Arcade's button stale after the player uses yours.
+
+### The Arcade's mute button, where there is one
+
+On a desktop, a tablet and a television the Arcade does keep a mute button beside your game, for
+games whose SDK can honour it — an SDK that silences your game says so when it connects, and a game
+built on an older one gets no button rather than one that does nothing. When the player presses it,
+`gem.prefs.muted` arrives as `true` and the SDK silences your page itself — every Web Audio graph and
+every `<audio>`/`<video>` element — then gives the sound back when they press it again. With the two
+calls above, the Arcade's button and yours stay in step whichever the player uses.
+
+- **It turns the volume down; it does not stop your clock.** Your `AudioContext` keeps running, so
+  anything scheduled against `currentTime` stays in time. Do not answer a mute with `ctx.suspend()` in
+  your own code, for the same reason.
+- **It leaves your own settings alone.** Your own volume is exactly where you left it when the
+  Arcade unmutes: the SDK sits after everything you built.
+- **Create your audio after `createGem`.** The SDK reaches sound connected to the speakers after it
+  starts, and nothing earlier. The boot order on this page already does that; an `AudioContext` made
+  in a module that runs before `createGem` is out of reach.
+
+### Starting silent: your game may start before the player touches it
+
+On a desktop the Arcade may start your game on its own information page, before the player has
+clicked anything in it. Browsers keep a frame's audio off until the player interacts with that
+frame, so **your game must cope with starting silent**: an `AudioContext` created then is
+`suspended`, and a `play()` on a media element rejects.
+
+```js
+const resume = () => {
+  if (ctx.state === 'suspended') void ctx.resume();
+};
+window.addEventListener('pointerdown', resume);
+window.addEventListener('keydown', resume);
+```
+
+Resume on the first input and carry on — never block the first frame on audio, never show an error
+for it, and do not ask the player to "click to start" just to unlock sound.
+
+### Doing it yourself instead
+
+`createGem({ manageAudio: false })` turns the SDK's silencing off — for a game that would rather fade
+its music out than cut it, say. The Arcade still shows its button for your game where it shows one,
+so this is a promise: your `onPrefs` handler must go quiet on `muted: true` and come back on `false`,
+and the release checklist checks that it does.
+
+## The Arcade's wallet: show it, never draw it
+
+The player's platform balances — Gems, Tickets (`ARCADE_TICKETS`) and their achievement score —
+belong to the Arcade. **Your game never draws one**, and never shows a pending state for one: the
+Arcade takes every figure from the platform and draws the wallets itself, beside its Back tab.
+
+**They are shown unless your game hides them.** A game that does nothing has every wallet on show
+the whole time. The one rule: **hide them during gameplay, show them on your menus.**
+
+```js
+level.onStart = () => gem.setWalletVisible(false);
+pauseMenu.onOpen = () => gem.setWalletVisible(true);
+```
+
+- **While hidden, the Arcade still pops a wallet up** for a moment when something happens to it —
+  a reward you cued with `gem.cueReward`, a spend, a landing, a daily-maximum note, a score change
+  — then hides it again. Your state never cancels that, so a reward mid-level still shows.
+- **It is screen state, not a toggle.** Each call is the whole answer and replaces the last. Call it
+  as often as you like: before the Arcade connects the state is held and sent when it does, and
+  again after any reconnect; a repeat of the current state is not re-sent.
+- **Shown wallets take space; a pop does not.** Shown, they widen the
+  [reserved area](#the-arcades-own-controls-reserved-areas) beside the Back tab, so lay your menu
+  out against `--gem-reserved-tl-*`; hidden, it shrinks back to the tab. A pop floats over your game
+  and never moves its layout.
+- **Narrowing is optional.** On a screen that sells in one currency — a ticket store — you may show
+  only that one: `gem.setWalletVisible(true, { only: ['ARCADE_TICKETS'] })`, with `'score'` for the
+  achievement score. Use it only there; leaving it out shows every wallet, which is always safe.
+- **Where the Arcade docks its wallets beside your frame** — a desktop page — they are always on
+  show, and this changes nothing. Call it anyway; the same code is right everywhere.
+- **`false` means nobody is listening** — no connection yet, or an embedder that draws no wallet.
+  Do nothing in its place.
+
+## The Arcade's FPS overlay
+
+The Arcade has a frame-rate toggle beside your game, and **you do not have to write anything for it
+to work**. When a player switches it on, `gem.prefs` arrives with `showFrameStats: true`, the SDK
+starts counting the frames the browser delivers to your
+document, and about once a second it reports the rate and the 95th-percentile frame time to the
+Arcade, which draws a small readout in its own chrome. **Your game draws nothing.**
+
+- **It costs you nothing until a player asks.** No `requestAnimationFrame` is registered and nothing
+  is sent until `showFrameStats` arrives `true`; the counter stops when it goes `false`, while the
+  Arcade has your game paused (`onPause`), and when the bridge closes. A game whose player never
+  presses the toggle never runs any of it.
+- **What the number measures.** The `requestAnimationFrame` ticks the browser delivers to your
+  game's document. That is exactly your render rate if you render on that callback — three.js,
+  Phaser and Babylon.js do, and so does any engine's web export — and it is measured inside your
+  frame on purpose:
+  the Arcade page cannot count your frames from outside, because a cross-origin iframe renders on
+  its own schedule, and a page-side counter would read a steady 60 over a game hitching at 25.
+- **If you render in a worker.** A game that draws through an `OffscreenCanvas` in a worker is
+  timed on its main thread here, which is not its renderer. There is no hook yet for such a game to
+  report its own figure; if you need one, ask.
+- **Do not draw an FPS counter of your own over the Arcade's.** Two readouts that disagree — and
+  they will, since they count different things — teach a player that one of them is lying. A debug
+  overlay in your own builds is fine; keep it off in an Arcade build, or at least off by default.
+- **The toggle appears only for games that support it.** An SDK that can count says so when it
+  connects, and a game built on an older one gets no toggle rather than a readout that never moves.
+  Upgrading the SDK is the whole of what a game has to do.
+
+`showFrameStats` is also on `gem.prefs` for you to read, held like the rest, but the only reason to
+read it is to know the Arcade is already showing one.
+
+## The player's language: prefer what the page sends, detect the rest
+
+**`gem.prefs.locale` is the language the Arcade page is RENDERING in.** That is the one fact a frame
+cannot obtain for itself — `<html lang>` inside the frame answers for what your game shipped, and
+nothing in a cross-origin iframe can see the parent's state. Honour it and your strings match the
+page around them; ignore it and a player reading the Arcade in Japanese clicks Play and lands in
+English.
+
+**It is not the only source, and it is not always the best one.** `navigator.languages` is readable
+inside a cross-origin iframe exactly as it is on a top-level page, and the Arcade's value is
+**clamped to the dozen languages the Arcade itself ships** — so a game that has a Dutch bundle would
+be told `en`, because the Arcade has no Dutch. Prefer the page's locale when you ship that language;
+otherwise fall back to your own detection.
+
+```js
+const supported = ['en', 'fr', 'ja']; // what YOU ship
+const wanted = gem.prefs?.locale; // what the page is rendering in
+const lng = wanted && supported.includes(wanted) ? wanted : undefined;
+// `undefined` -> let your detector read navigator.languages
+```
+
+**Do not wait for it.** `gem.prefs` is parent-initiated and not every embedder sends one — the native
+Arcade app does not today. A game whose string loading blocks on it renders nothing on those
+surfaces. Start from detection, and re-render when the message arrives.
+
+Whichever path you take, set **`supportedLngs`** to the languages you actually ship and
+**`fallbackLng`** to your default. Detection on its own hands you `en-GB`, which matches no bundle if
+you shipped `en` — the single most common locale bug in shipped games, and the reason this sentence
+is here rather than left as an exercise. Do **not** reach for `nonExplicitSupportedLngs` or
+`load: 'languageOnly'` to fix it: measured against i18next 26, both collapse every region- or
+script-qualified locale you ship (`pt-BR`, `zh-Hans`) to the fallback, because they test membership
+on the language part alone. `supportedLngs` already resolves `en-GB` to `en`.
+
+## Showing a player: one identity on every surface
+
+Every surface that shows a player hands you **the same fields, under the same names**: the signed-in
+player (`gem.player`), room members, leaderboard rows, friends, profiles, showcase rows — and an
+async opponent you read through the raw client, once you pass the row through `mapIdentity`. One
+renderer serves all of them.
+
+| Field | What it is | Type |
+| ----- | ---------- | ---- |
+| `playerId` | The player's id. **Absent on an anonymous row** | `string` |
+| `displayName` | The name the player chose | `PlayerText` |
+| `discriminator` | The digits that tell two same-named players apart — `0001`, no `#` | `string` |
+| `displayTag` | The precomposed `Name#0001` | `PlayerText` |
+| `avatarIconId` | The portrait item's id | `string` |
+| `avatarIconUrl` | The portrait's thumbnail | `string` |
+| `badges` | Equipped badges in display order, each `{ itemId, iconUrl }` — always a list, empty for now | array |
+
+**The name and the tag are player-authored, so both are `PlayerText`** on every surface, not only
+some. Convert with `text.toPlain()` where you render, never before.
+
+**Show the discriminator beside the name, and never drop it to make a name fit.** Two players may
+choose the same name, and the digits are what keeps one from passing as the other. Truncate the
+name, not the digits.
+
+**A row with no `playerId` is an anonymous player** — erased, or on a board that shows no players.
+It keeps its rank, so render it as "Anonymous player" rather than skipping it.
+
+**A row with a `playerId` but no name** is a player who has not chosen one, or one whose identity
+is withheld from you (a player who blocked you, say). The id stays because it keys a seat, a
+friendship or an opponent you already hold; the name, tag and portrait are absent. Render it as
+"Player", and never fall back to showing the id.
+
+**Put an icon URL through `platformIconUrl` before it reaches an `<img>`.** Loading an image is a
+request that carries your page's address and the moment it happened, so an icon from anywhere but
+the platform's own image host would be a beacon on your player. `platformIconUrl` answers the URL
+only when the platform serves it, and `undefined` otherwise — draw your placeholder, as for a
+player with no portrait.
+
+```js
+import { mapIdentity, platformIconUrl, text } from '@indiegems/gem-web-sdk/sdk';
+
+function renderPlayer(el, who) {
+  const name = el.querySelector('.name');
+  const digits = el.querySelector('.digits');
+  name.textContent = who.displayName ? text.toPlain(who.displayName) : 'Anonymous player';
+  digits.textContent = who.discriminator ? `#${who.discriminator}` : '';
+  const src = platformIconUrl(who.avatarIconUrl);
+  if (src) el.querySelector('img').src = src;
+}
+
+for (const member of gem.rooms.currentRoom?.members ?? []) renderPlayer(rowFor(member), member);
+for (const row of opponents) renderPlayer(rowFor(row), mapIdentity(row)); // a raw-client row
+```
+
+**What changed, if your game was written before these fields.** `gem.player.displayTag` used to be
+the discriminator digits and is now the whole `Name#0001` as `PlayerText`, the same as a room
+member's; the digits are `gem.player.discriminator`. The names on friends, leaderboard, profile
+and showcase rows used to be plain strings and are now `PlayerText`, as they already were on room
+members. `gem.player.displayHandle` and `gem.player.avatarUrl` still work, and are
+[deprecated](deprecation-policy.md) in favour of `displayTag` and `avatarIconUrl`.
+
+### The signed-in player's Boost: show it, never gate on it
+
+`gem.player` also carries **`boost`** — the player's Boost, the Arcade's one real-money product.
+While it lasts the player earns Gems and Tickets faster (never achievement points), and the
+platform raises their earning limits to match. The platform does all of that on its own side when
+it pays; your game does nothing to make a boost work.
+
+| Field | What it is | Type |
+| ----- | ---------- | ---- |
+| `boost.active` | Whether any currency earns faster than 1× right now | `boolean` |
+| `boost.multipliers` | One `{ currencyId, currencySlug, multiplier }` per boostable currency — `multiplier` is `2` for 2×, `1` when not boosted; a currency not listed is 1× | array |
+| `boost.expiresInDays` | Whole days until the soonest boosted currency drops back, rounded up and **capped at 7** — `7` means "7 or more"; absent when nothing is boosted | `number` |
+
+`boost` is always present on `gem.player`. When the Arcade has not said — an older Arcade, a
+backend without boosts, a read that has not landed yet — it reads as **not boosted**, exactly like a
+player who has no boost.
+
+```js
+const tickets = gem.player?.boost.multipliers.find((m) => m.currencySlug === 'ARCADE_TICKETS');
+if (tickets && tickets.multiplier > 1) rewardScreen.showBadge(`${tickets.multiplier}× Tickets`);
+```
+
+⚠️ **It is for display, and only for display** — a "2×" badge on a reward screen. Never gate
+content, difficulty, matchmaking, prices or power on it: it is advisory, it may lag (it is pushed on
+connect and when it changes, not on the instant a boost starts or ends), and it can be forged inside
+your own page. It carries a day count and never a date, and nothing about what the player paid.
+This is a platform rule, not advice — see
+[platform rules §8](platform-rules.md#8-a-players-boost-is-for-display-never-a-gate).
+
+## Which backend — no longer yours, and what the override is for
+
+The Arcade names the API root on every `gem.token`, and the SDK sends there. Your game never types
+an API address and never has to know which one it is running against; if the token says nothing, the
+SDK uses `https://api.gemarcade.com`.
+
+Two things the SDK refuses rather than working around, because both are silent when they go wrong:
+
+- **An address it cannot use** — one carrying a query string, a fragment, credentials, or plaintext
+  `http` anywhere but your own machine. The whole token is refused and the reason reaches `onError`.
+- **An address that changes mid-session.** The first token of a session fixes where requests go, and
+  a later one naming somewhere else is refused. Nothing legitimate moves it, so a game that ever
+  sees this has an embedder problem rather than a game problem.
+
+`baseUrl` survives as a **developer override** for hosts the Arcade cannot name — a tunnel, a staging
+rig, a LAN address a phone can reach. It pins the transport, and what the token says stops moving it
+(the token's value is still checked, and a bad one still refuses the token). Do not use it to choose
+a backend: that is the Arcade's job, and a hand-configured value is how a game ships pointing at the
+wrong one and reads the result as authentication failures.
+
+## Saving a player's progress — if your game has any
+
+Games do not need saves, so this is not on the list above. It is a capability, and it has a page
+of its own: [`saving-player-progress.md`](saving-player-progress.md).
+
+Read it if your game has progress worth keeping, because the shape is not the one most games
+assume. There are **two roles**: you declare a save slot once, in your game config, the way you
+declare a room template; then your game's running code writes and reads that player's save with
+`gem.me.saves`. Game code cannot create a slot, and a save against one you never declared is
+refused every time.
+
+## An economy — if your game has one
+
+Currencies, items, shops and loot are not on the list above either, for the same reason: a game
+without them is complete. If yours has any, they have their own pages:
+[`inventory-and-catalogs.md`](inventory-and-catalogs.md) for the concepts, and
+[`game-economy-tutorial.md`](game-economy-tutorial.md) to build a shop step by step.
+
+The shape rhymes with saves. There are **two roles**: you author the definitions — the currencies,
+items and shops that exist — once, in your game config; then your game's running code reads and
+changes what a player holds. The one thing to carry away before you read further: a **recipe**,
+run on the server, is the only path a modified client cannot rewrite, so anything of value goes
+through one.
+
+## Async opponents — if your game has nobody live to play against
+
+Not on the list above either: a game with no competitive mode is complete without one. If yours
+wants one and has no server of its own to run a live match on, the platform will hold a snapshot of
+one player's run — a deck, a build, a ghost lap — and hand it to a different player's game hours
+later, with nothing live between them.
+
+The shape is a loop rather than two roles: your game pushes a record after a match, draws a few at
+the next match's start, and fetches the full data for the one your player picks.
+[`async-opponents.md`](async-opponents.md) is the page — read it before you conclude that a game
+running entirely in the browser cannot offer competition, and read
+[its safety rule](async-opponents.md#7-draw-a-set-at-match-start) before you render anything a
+drawn record carries, because those strings were typed by another player.
+
+## A break in play, if you want one to be worth something
+
+Not on the list above either, and a game that never asks is never interrupted. If yours wants a
+break to carry a promotion for another game on the Arcade, `gem.ads.requestAd` asks for one and the
+Arcade draws it in its own chrome over your paused game.
+
+Three things before you reach for it: the answer is **usually no**, and no is the ordinary path
+rather than a failure; nothing rejects, so there is no error branch to write; and `shown` grants
+nothing, so a reward must never be handed out on the strength of it.
+[`cross-promotion.md`](cross-promotion.md) is the page.
+
+## An account upsell, if your game has something to offer one
+
+Not on the list above either. When a player reaches for something only an account gives them,
+`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.
+
+## A Share button, if your game has something worth sending a friend
+
+Not on the list above either. If a player can hand a friend a link to a puzzle, a board or a
+level, `gem.share.request` asks the Arcade to share it: the Arcade builds the link, which unfurls
+with your game's card, and shares it through its own sheet, copy or Share panel. Show the button
+only where `gem.share.available` is true.
+
+Two things before you reach for it: **call it from the click**, synchronously, never from a timer
+or after an `await`; and **never gate a reward on it**, because your game is told nothing back,
+not even whether the player shared.
+[Linking to your game](getting-started.md#linking-to-your-game) is the section.
+
+## A decision the player must not make, if your game has one
+
+Not on the list above either: most games trust the browser with everything they do and lose nothing
+by it. If yours has a decision a player must not be able to fake, such as a run that earns a reward
+or a claim only your game's rules can judge, and no server of yours running to make it, the platform
+will run a small piece of your code for it, out of the player's reach, one call at a time.
+
+Two things before you reach for it. A verdict the function **returns** to the browser is still
+advice to a client you do not trust, so whatever it decides it must also carry out itself. And
+spending currency or granting an item is a recipe, which the platform already runs where a client
+cannot change it. [`serverless-functions.md`](serverless-functions.md) is the page.
+
+## Bug reports players send you, and the one WebGL flag that decides them
+
+The arcade has a **Feedback** control. A player taps it, the platform asks your game for a picture
+of itself, the player draws on it and writes what happened, and it arrives on your game's feedback
+list. You get this for nothing — there is no option to set.
+
+There is one thing to get right, and it is easy to miss because getting it wrong produces no error
+anywhere.
+
+### ⚠️ WebGL games: `preserveDrawingBuffer: true`
+
+```js
+const gl = canvas.getContext('webgl2', { preserveDrawingBuffer: true });
+```
+
+Without it the browser is free to clear your drawing buffer once the frame is composited. Read it
+after that and you get **a fully black image and no error** — `createImageBitmap` resolves, the
+transfer succeeds, every layer reports success.
+
+The SDK checks the flag before it captures and **refuses** rather than sending you black. That is
+deliberate: a black screenshot costs the player their whole report and costs you the time to work
+out why the platform sent you a rectangle of nothing. The refusal reaches you instead, as
+`unsupported` in the report's diagnostics.
+
+The flag has a real cost — it can stop the browser discarding the buffer after compositing — so it
+is your call. But the default is to get no screenshots, silently, which is rarely what anyone wants.
+
+2D canvas games need nothing. `OffscreenCanvas` games need `onScreenshot`, below.
+
+### When the default capture is not right
+
+By default the SDK captures your largest visible canvas. Override it when that cannot work — an
+`OffscreenCanvas` driven from a worker, several layered canvases you want composited — or when you
+want a say per moment:
+
+```js
+createGem({
+  onScreenshot: async ({ maxWidth, maxHeight }) => {
+    if (inCutscene) return null; // decline; the report still sends
+    return createImageBitmap(myCanvas);
+  },
+});
+```
+
+`null` is a normal answer, not an error — for a cutscene, for art you may not redistribute, or to
+opt out of screenshots entirely. Fit the caps if you can; the SDK downscales if you overshoot.
+
+### Attach your own debug state
+
+This is the part worth spending effort on, because it is the difference between _"the boss is stuck
+in the wall"_ and a report you can act on without a reproduction:
+
+```js
+createGem({
+  onFeedbackContext: () => ({
+    level: currentLevel.id,
+    seed: currentLevel.seed,
+    build: BUILD_ID,
+    entities: world.entities.length,
+    recentEvents: eventLog.slice(-20),
+  }),
+});
+```
+
+**Called once, when a player actually files a report** — never on a timer, never in the background.
+So the expensive gather is fine here: dump what you would actually want to read. May be `async`;
+return `null` to add nothing.
+
+**Answer promptly.** You get about a second, then the report is sent without you — a player waiting
+to file a bug is not made to wait on the game they are filing it about. If your dump is genuinely
+slow, keep a cheap snapshot updated and return that.
+
+The platform never tells your game what the report says, what category the player chose, or whether
+they went on to send it. That is on purpose.
+
+### What must not go in it
+
+⚠️ **Nothing about a person.** No other player's name, no chat text, no email, no account id.
+
+The player filing the report does not write this and cannot see it, and both your team and platform
+support read it, for 180 days. It is also not a telemetry channel: it runs only when a player
+chooses to send a report, and nothing is uploaded on your behalf at any other time.
+
+## Still open, and worth knowing before you hit it
+
+- **A quick-join that hands back a live room whose match is dead.** The SDK now leaves the room on
+  unload and clears leftover memberships that refuse a quick-join, which removes the common cause.
+  What it does not do is abandon a room it is _in_ and quick-join a fresh one when the connect fails
+  — that spans matchmaking policy the SDK does not own, and the same recovery is wrong for a game
+  with a lobby, where the player chose the room. If you quick-join and you see a match status 404,
+  this is the shape: leave, quick-join again, and do it **once**, and not at all for a room your own
+  attempt just created — a brand-new room cannot fix a backend that will not allocate.
+- **Who starts the match.** `connect()` allocates when this player is the host and the room shows no
+  match. If your room template sets `auto_start_host`, both are true for the instant after
+  `quickJoin` returns, so the client wins the race — harmlessly, because gem-api's `start_match` is
+  idempotent per room and returns the existing match. If you would rather the template always be the
+  one that starts it, `await rooms.awaitMatch()` before connecting.
+- **Starting a match can wait for a server to exist.** A Start pressed when no server is available is
+  refused until the platform has one. `startMatch()` and `connect()` absorb that inside a
+  **30-second** budget and report each wait as **`matchStartWaiting`**; render it, or your Start
+  button stalls silently for half a minute. That budget is the longest a player is expected to
+  tolerate rather than the longest the platform might take, so it will sometimes give up on a start that
+  a longer wait would have caught — `retry: { budgetMs }` raises it if your players will wait, and
+  `0` hands the refusal straight to you. If the budget runs out the error is `no_server_ready`, which
+  says how long it waited and is not the same thing as a request gem-api refused. See
+  [`rooms-and-matches.md`](rooms-and-matches.md) §4.4.
+- **A peer-to-peer room does not wait at all.** There is no server being allocated for it, so a
+  refusal there means the platform has no P2P rather than no capacity, and it arrives immediately as
+  `p2p_unavailable`. Nothing to render and nothing to retry: it is a platform configuration, and the
+  message carries what gem-api said.
+- **Cluster targets.** The parent measures the regions and the SDK fills them in: a room is created
+  in this player's best cluster, quick-join puts players only in rooms in clusters they can all play
+  well in, and a match starts where its room is. A game that wants to move a room passes
+  `clusterTargetId` to `startMatch()`. The measurement is a browser measurement — the page times the
+  STUN probes gem-api publishes per region for exactly that purpose — and it stays on the page for
+  three reasons: `GET /v1/regions` takes an account-scoped token the frame does not hold; the page
+  measures once per player session and every game it loads inherits the answer, where the frame would
+  repeat it per game and per reload; and the per-region round-trip vector is coarse geolocation plus a
+  network fingerprint, so what crosses the bridge is at most three ids, never a timing. See
+  [`dedicated-server-flow.md`](dedicated-server-flow.md) §5.
+- **An automatic start can be refused, and the host's SDK then starts it.** A template that starts
+  the match when the room fills tells the host's game through `matchAutoStartFailed` when the platform
+  could not, and the room stays open. For a region the platform stopped running, or no server free,
+  the SDK starts the match from the host's game itself — once per room until a match begins in it —
+  and the event says `handled: true`. `handled: false` is yours to act on, and
+  `createGem({ retryAutoStart: false })` leaves every one to you; calling `startMatch()` from the
+  handler is then the usual answer. The SDK's 5.11.0 and 5.12.0 releases started nothing, so a game
+  written for them that holds the start back for the host to decide needs that switch.
+  [rooms-and-matches.md](rooms-and-matches.md) §4.4.
+- **Reconnect.** Since the SDK's 4.0.0 release (2026-09-10) a dropped link is the SDK's to get
+  back: it suspends the match, raises `matchSuspended`, and retries on its own — bounded, backed
+  off, parked while the page is hidden — with `matchReconnecting` and `matchReconnected` as the
+  render hooks. `connect()` again on a suspended session _rejoins the held match_; it never
+  reallocates. A new match is allocated only after `matchEnded`, and only by the host. What the
+  player sees while it happens is the game's; whether to reconnect is yours only if you turn the
+  policy off (`autoReconnect: false`). [match-session.md](match-session.md) §4.
+- **Letting go when the match ends.** The SDK closes the peer connection when the platform says the
+  match is over, and does _not_ suspend the match — there is nothing to reconnect to. It has to: a
+  browser sitting on a finished match keeps answering ICE consent checks, which the server cannot
+  distinguish from a player still there, and a tab nobody closed used to hold its game-server pod for
+  two hours. What the game decides is what the player sees, via the room's `matchEnded` event or
+  `connect({ onMatchEnded })` — on `gem.match` and `gem.dedicatedServer` alike, on every seat —
+  the distinction those carry is "the match ended" versus "the connection dropped", which are the
+  same `onClose` otherwise. The reason vocabulary and what each means to the player:
+  [match-session.md](match-session.md) §3.
+
+## What the SDK will not do, on purpose
+
+- **Guess when you have disconnected.** `visibilitychange` fires when a player alt-tabs to read a
+  wiki. Only the data channel closing is unambiguous, and only that is wired.
+- **Act on a stale-build push.** It is forwarded and nothing else, which is also what a native game
+  observes for the same event.
+- **Invent a display name.** `awaitPlayer()` resolves null rather than
+  burning your timeout: there is no parent, so `gem.player` can never arrive.
+
+## What a game correctly keeps — the other half of the audit
+
+The game that audited its platform layer row by row also recorded what it deliberately does **not**
+delegate, so nobody spends that trip again. Each of these looked like possible duplication of the
+SDK and is not:
+
+- **Your per-tick wire budget.** A budget your game puts on its own data-channel traffic is yours
+  and does not conflict with the platform's 16 KB cap on a **signaling** frame — different paths,
+  different owners. Do not copy the platform's number into game code; hold your own.
+- **Player saves are the exception on this list, and an earlier version of it said otherwise.**
+  Progress a player would be upset to lose does not belong in browser storage, which they lose by
+  changing device or browser; the platform holds it, and
+  [`saving-player-progress.md`](saving-player-progress.md) is how. Something genuinely local still
+  belongs in the browser — a keybinding, which device this is, a cached asset.
+- **`openExternal` and fullscreen.** The bridge carries both requests, and the parent decides. If
+  your game opens no links and never goes fullscreen, there is nothing to route — absence of these
+  calls in a game is not a gap.
+- **An offline stub, if you want one.** The SDK no longer ships a seeded mock — it was a quarter
+  of the bundle every player downloaded, and a game must be framed to reach
+  the platform at all. A game may keep its own offline
+  rooms implementation — the audited game argues a stub that is merely convenient lets the game
+  pass offline and fail online — but that is a choice about test honesty, and it drifts with the
+  SDK's room semantics; know that you are signing up to track them.
+- **Debug affordances in your own vocabulary.** Per-step logging, a `?cluster=` override aimed at
+  one region — a developer override outranks a platform-measured value _because a person typed it_,
+  and those belong to the game. Ship nothing with one set.
+- **Capability advertising is not yours to tune.** `createGem` advertises what the SDK
+  _implements_, not what your game intends to use — an unused capability costs nothing, because the
+  parent only relays what its socket delivers. A game assembling the parts by hand instead inherits
+  the duty to advertise only what it wired: a capability advertised and not wired makes the page do
+  its half and drop the answer, silently, one document above you.