@indiegems/gem-web-sdk 7.4.0 → 7.4.2

package/docs/platform-rules.md

@@ -0,0 +1,372 @@
+# The platform rules a game has to find out for itself
+
+Every other page here describes **this SDK**. This one describes the **platform underneath it** — the
+rules gem-api enforces that no client-side type signature states, that mostly produce no error when you
+get them wrong, and that each cost a working developer a day to reconstruct from behaviour.
+
+Each rule below was read out of gem-api's source on **2026-08-06** rather than inferred from the API
+surface, because the whole point of the list is that the surface does not say these things. Rule 3 was
+re-read on **2026-08-10**, when the platform changed it, and it is the exception to the silence above:
+it refuses outright rather than letting you get it wrong quietly. Where a rule is an **implementation
+fact** rather than a contract — true today, not promised — it is marked 🔧. Do not build on a 🔧
+without saying so in your own code.
+
+- [1. A match is sized by who is in the room when it starts](#1-a-match-is-sized-by-who-is-in-the-room-when-it-starts)
+- [2. Room lifecycle: when one goes away, and what a leftover does to you](#2-room-lifecycle-when-one-goes-away-and-what-a-leftover-does-to-you)
+- [3. A room's seats come from its template, and a create cannot ask for its own](#3-a-rooms-seats-come-from-its-template-and-a-create-cannot-ask-for-its-own)
+- [4. The compatibility line](#4-the-compatibility-line)
+- [5. `templateSlug`: what it resolves against, and what you can pass today](#5-templateslug-what-it-resolves-against-and-what-you-can-pass-today)
+- [6. The demos that already exist](#6-the-demos-that-already-exist)
+- [7. A dedicated match does not run forever, and neither does its server](#7-a-dedicated-match-does-not-run-forever-and-neither-does-its-server)
+- [8. A player's Boost is for display, never a gate](#8-a-players-boost-is-for-display-never-a-gate)
+
+---
+
+## 1. A match is sized by who is in the room when it starts
+
+**`startMatch()` reads the room's member list at that instant, and that list is the match.** The
+room's seat count is never consulted. It bounds who may **join the room**; it says nothing about who
+is **in the match**.
+
+Start with two of eight seats filled and you have a two-player match. The other six seats reserve
+nothing, wait for nobody, and are not communicated to the server.
+
+This is the fact that costs days, because every wrong theory it produces is plausible: that the
+platform waits for a full room, that the seat count is a target the matchmaker fills, that a match
+started early will be topped up. None of that exists. **Holding players until you have enough of them
+is your game's job**, and the room is where you hold them.
+
+Three consequences worth having in writing:
+
+- **Nothing enforces a minimum on a manual start.** A template's `min_players` is read by exactly one
+  feature — `auto_start_host`, where the server itself starts the match the moment membership reaches
+  that number. A game that calls `startMatch()` by hand can start a match with one member in the
+  room, and gem-api will allocate for it.
+- **What happens to somebody who arrives _after_ the start depends on the match type**, and the two
+  are not alike:
+  - **Dedicated** — they are admitted, and **whatever membership your server last read may not
+    mention them yet**. Admission is not decided by any list: the platform issues a join credential
+    to any member of the room, including one who joined after the start, and your server is obliged
+    to honour it. A bundle that treats its copy of the membership as a guest list rejects real
+    players, _after_ their connection is already up, which presents to them as your game being
+    broken — an unknown arrival means "re-read the room", never "reject". See
+    [`server-bundles.md`](server-bundles.md#membership-is-not-a-guest-list).
+  - **P2P** — the roster is frozen when the match starts, and here it _is_ the gate. A room member
+    who is not on it is added when they first reach signaling **only if the room's template sets
+    `allow_join_in_progress`**; otherwise the platform refuses them with `not_match_member`, and the
+    symptom in your game is a peer that joined the room fine and can never connect.
+- **The server's size is not sized from the room at all.** Which machine class a dedicated match gets
+  comes from the `server_size` declared on the published server build. A bigger room does not get a
+  bigger server, and a room of two on a build that declares no size fails the start with 422
+  `server_size_not_configured` regardless of how many players are present.
+
+## 2. Room lifecycle: when one goes away, and what a leftover does to you
+
+### An empty room is deleted immediately
+
+When the last member leaves, gem-api deletes the room and its memberships in the same transaction.
+Not closed, not archived — **gone**, and the next read of it is a 404.
+
+🔧 **`auto_close_when_empty` does not change this.** The flag is stored on a template, returned by the
+template endpoints, and read by nothing: the delete is unconditional. The built-in `hub` template sets
+it to `false` and still loses its room when the last player leaves. Treat the flag as inert rather
+than as a lever you can pull.
+
+### A room with members in it expires four hours after its last activity
+
+🔧 Every mutation refreshes that four hours, and so does a read taken within two hours of expiry. A
+room explicitly closed by its host gets a day instead. Expired rows are swept on a five-minute cycle,
+so "expired" and "gone" are up to five minutes apart.
+
+🔧 `game_room_ttl_seconds` and `idle_timeout_seconds` on a template are carried and never read. The
+interval is fixed. Nobody notices the first of those because the default template value is `14400`,
+which is the same four hours by coincidence rather than by wiring.
+
+### A membership that outlives its page is the one that bites
+
+A tab that closes without leaving leaves the player in the room. The room is not empty, so it is not
+deleted, and the player is **still in it** on their next visit — with nothing in their new page's
+state that knows about it.
+
+What that does to the next session:
+
+| What you call                                                        | What you get                                                                                                            |
+| -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `quickJoin()` on a template matching the leftover                    | 409 `already_in_matching_room` — gem-api refuses to quick-join a player already in a joinable room of that type         |
+| Creating or joining, once the player holds **10** rooms in this game | 409 `game_room_limit_per_game` — the cap is checked before the call, so the tenth membership is the last one that works |
+| …or **25** rooms across the whole platform                           | 409 `game_room_limit_global`                                                                                            |
+
+The 409 is the good case. It is loud, and this SDK recovers from it: `quickJoin()` clears the
+memberships and retries **once** by default, which `createGem({ recoverStaleMembership: false })`
+turns off. The bad
+case is a leftover the guard does not match — it keys on room type and channel — where the player is
+simply back in a room whose match died with the tab that started it.
+
+**How to clear one.** `rooms.myRooms()` is the only thing that can see a leftover, because your
+manager holds no room and `leave()` therefore has nothing to act on. `rooms.leaveAll()` leaves every
+room this player still holds, best-effort per room — one room that refuses is simply absent from the
+ids it answers with. If the listing itself fails, it **rejects** rather than answering with an empty
+list a caller cannot tell apart from "held nothing". Both take the game-scoped token the frame
+already has.
+
+**The platform's own clean-shutdown route is not reachable from a game.** `POST
+/v1/players/me/client-shutdown` does exactly this fanout server-side, honouring
+`auto_leave_on_client_shutdown` per template — but it lives on the `/v1/players/me/` surface and takes
+a **player** token, which a frame does not hold and should not. On web the mechanism is this SDK's
+`pagehide` leave; see [`rooms-and-matches.md` §4.3a](rooms-and-matches.md).
+
+## 3. A room's seats come from its template, and a create cannot ask for its own
+
+**You do not choose a room's size when you create it.** The seat count comes from the room template —
+the block of room settings you publish in your game config — and a create whose body carries a seat
+count is **refused**: `400 max_players_not_settable`, with the value you sent echoed back so you can
+tell which of your calls carried one.
+
+A room created without naming a template seats **8**, and there is no way to ask for a different
+number on that path either.
+
+**Quick-join never had a seats field**, and a body that invents one is refused the same way — before
+it looks for a room to join, so the answer never depends on whether one was found.
+
+**This SDK does not send it.** `CreateRoomOptions.maxPlayers` is deprecated: setting it logs a warning
+naming the replacement, and the field is dropped before the request goes out, so an old call site
+still creates a room rather than starting to 400. Delete it when you see the warning. The field
+keeps working for the rest of `3.x`, and `4.0.0` is the earliest release that may remove it —
+[the deprecation policy](deprecation-policy.md#2-the-rule-for-the-packages-api-surface).
+
+**The one way to set a seat count is to resize a room that already exists** — `update({ maxPlayers })`,
+host-only, and never accepting a value below the room's current member count. Mind the bound: 🔧 **that
+route validates 2–64 whatever the room's template allows**, while a template may declare up to 10,000.
+So the `hub` template's 500 seats cannot be reached through it at all, and a templated room can only be
+patched _into_ the 2–64 range, never within its own.
+
+**Why it is a refusal and not a shrug.** Until 2026-08-10 a seat count was accepted and then quietly
+discarded whenever a template resolved: no warning, no 400, nothing in the response saying it had
+happened, and a room that was simply a different size than the one you asked for. The platform now
+refuses the field instead. It costs you a visible error on a call that used to look like it worked,
+which is the point — a size that silently was not honoured is the failure it replaced.
+
+## 4. The compatibility line
+
+A **line** is the compatibility group two builds must share to meet. It is derived, never declared —
+from the version the build was published under, which the arcade reports to your game rather than
+asking it to say:
+
+| Published version  | Line                                                    |
+| ------------------ | ------------------------------------------------------- |
+| `1.4.2`            | `1` — major version, for anything ≥ 1.0.0               |
+| `0.5.3`            | `0.5` — major _and_ minor, while you are pre-1.0        |
+| `1.2.0-beta.1`     | `1-beta.1` — a prerelease is its own line, tag included |
+| `1.2.3+nightly`    | `1` — build metadata is ignored                         |
+| `1.2`              | 400 — it is parsed as strict semver or refused          |
+
+**While you are on `0.x`, every minor bump is a new line.** `0.5.9` and `0.6.0` cannot play together.
+That surprises people, and it is the single most common way to split a player base by accident.
+
+Three rules follow from it:
+
+1. **A room is pinned to its creator's line, and joiners must match.** Join a room on the wrong line
+   and you get 409 `version_mismatch`, naming the expected line and yours.
+2. **Quick-join does not fail on a line mismatch — it silently creates a second room.** Rooms on other
+   lines are filtered out as non-candidates, so the create fallback runs. Two versions of your game
+   quick-joining at the same moment do not collide and do not error; they end up in separate rooms and
+   each player sees an empty lobby. This is the failure that looks like "matchmaking is broken".
+3. **Both halves ship together.** Starting a dedicated match resolves the highest playable **server**
+   build whose own version derives to the room's line. Nothing in that line means 409
+   `no_compatible_server`, with a reason that names the remedy: `none_on_channel` (no servable server
+   build at all), `none_in_line` (server builds exist, none in this line) or `expired` (the build that
+   served this line aged out). A client release without its matching server release is a game that
+   cannot start a match.
+
+**Drift _within_ a line is silent, and that is deliberate.** Any client versions in the same line share
+a room without complaint, and the match takes the highest playable server build in that line. Nothing
+checks that they are the same number. Your protocol compatibility inside a line is yours to keep.
+
+**Do not send a version at all.** The arcade routed this player to one of your builds and tells your
+game which one; that is the version every room and match call reports, and it is the number the line
+above is derived from. `clientVersion.gameVersion` is deprecated and still read, which is what keeps a
+build working under an arcade too old to send one.
+
+**Do not send `engineVersion` either.** A browser game is not an engine export and has none; the SDK
+reports one for you, and a value you supply derives an engine line that matches no fleet and fails at
+allocation, long after the call that decided it. Rooms enforce engine-line agreement the same way they
+enforce the game line.
+
+## 5. `templateSlug`: what it resolves against, and what you can pass today
+
+A slug is resolved in two steps: **your game's config for that channel first, then the platform's
+built-in globals.** An id resolves the same way. An unknown slug is a 400; an unknown id is a 404.
+
+There are exactly two built-in templates, and their properties decide what a game with no config of
+its own can do:
+
+| Slug       | Seats | Match type | Notes                                                |
+| ---------- | ----- | ---------- | ---------------------------------------------------- |
+| `standard` | 20    | dedicated  | public, late join allowed, min 2                     |
+| `hub`      | 500   | **none**   | public, late join allowed, notifications server-only |
+
+**`hub` starts no matches.** Its match type is "no match" and `startMatch()` on a `hub` room is a 400
+`match_type_not_supported`. It is a place to put players, not a way to play.
+
+**No built-in slug gives you a P2P match.** `standard` is dedicated, `hub` starts nothing. A browser
+game that wants peer-to-peer play needs a **game-specific** room template, which comes from your game's
+config.
+
+### Authoring your own
+
+Room templates are a section of the game config, read from the published JSON Schema on **2026-08-09**
+and re-read on **2026-08-11** — which is a later reading than the gem-api source date at the top of
+this page, and a different source. The schema endpoints are **public**: no credential, so anything
+below can be checked in a browser.
+
+`GET /v1/schemas/game-config/v1/schema.json` declares `game_room_templates` as one of the config's
+top-level sections.
+
+**The `v1` in that path is not the document's identity.** There is a
+`GET /v1/schemas/game-config/versions`, and it does not answer the question worth asking: every
+backend reports `v1` as both the only version and the latest one, and goes on reporting exactly that
+while the document behind the path is replaced by a deploy. So a consumer that pins to `v1` has
+pinned to a path and not to a document — it validates against whatever the backend it last fetched
+from is serving today, and finds out when a field it relies on is not there.
+
+Two things identify the document, and both travel on the document you fetched:
+
+- **`$id`** is stamped from the origin that served it. Fetch from the API origin your game actually
+  talks to and compare the two: a `$id` naming anywhere else means what you are holding is not what
+  that backend validates your config against.
+- **`ETag`**, alongside `Cache-Control`, with `If-None-Match` answered by a `304` and no body. That is
+  the staleness check — keep the ETag beside the copy you vendored, send it back, and a `304` means
+  your copy is still live. It is per document, so it changes when the document changes, which is the
+  thing a version number stamped once does not do.
+
+**`match_type` accepts `dedicated`, `p2p` or `none`** (default `dedicated`), so a P2P match is a
+template with `match_type: p2p`.
+
+A template is config, so it ships the way config ships — no new build, versioned, rollback-able:
+
+```bash
+gemctl config schema                                # the authoritative field list
+gemctl config init                                  # scaffolds a config from it
+gemctl config upload --wait                         # registers a version; validation is ASYNC
+gemctl config promote <version> --channel <channel> # this is what makes it live
+```
+
+**Uploading is not shipping.** `upload` registers a version with `validation_status: pending`; the
+version exists and is not usable, and a channel cannot point at one that has not validated — hence
+`--wait`. Until a `promote` puts it on the channel your game is running, the slug resolves against the
+globals only, and `quickJoin` on your own slug is a 400. That matches the resolution rule at the top of
+this section: your game's config **for that channel** first.
+
+Five things worth knowing before you write one, none of which the field list makes obvious:
+
+- 🔧 **Declaring a slug that already exists as a global shadows it for your game.** Resolution prefers
+  a config template over a global one sharing its slug, so `slug: standard` replaces the platform
+  default _for this game_ rather than colliding with it. That is the intended way to override a
+  built-in — and it means `quickJoin({ templateSlug: 'standard' })` in a game that later declares its
+  own `standard` silently starts resolving somewhere else, with no client change.
+- **`slug` is NOT required, and a template without one is unreachable from a game.** Only `id`, `name`
+  and `game_room_type` are required. Every client call names a template by `templateSlug`, and the
+  shadowing rule above is keyed on the slug, so a template authored with the required fields alone
+  exists and can never be selected.
+- **`id` is required and is yours to generate** — a UUID. 🔧 The schema asks that it not be the
+  all-zero UUID reserved for the globals, but declares no constraint that enforces it; the rejection,
+  if any, is server-side.
+- **`game_room_type` is `^[A-Za-z0-9 ]+$`, max 64** — alphanumerics and spaces only, unlike `slug`. A
+  `team-deathmatch` copied across from the slug fails validation. It is also what the stale-membership
+  guard keys on; see §2.
+- **`max_players` runs 2–10000 (default 20); `min_players` floors at 1.** There is no one-seat _room_,
+  but solo play is supported and intended — the schema's own note on `min_players` is "set to 1 to
+  allow solo play and solo testing", so `max_players: 2, min_players: 1` is the solo shape. Note that
+  `min_players` only bites when `auto_start_host` is set; a manual `startMatch()` can already start
+  with one member in the room, per §1.
+
+⚠️ **Four fields the schema accepts will not do what they say.** `auto_close_when_empty`,
+`game_room_ttl_seconds` and `idle_timeout_seconds` are carried and never read;
+`auto_leave_on_client_shutdown` _is_ read, but only on a route a browser game cannot reach. All of it
+is in §2 above. The schema describes all four as if live. Authoring them is not an error; expecting
+them to do something is.
+
+> Do not re-derive the field list from this page. `gemctl config schema` is versioned and
+> authoritative, and a list copied into prose goes stale where nobody is looking. The per-field facts
+> above are the ones the field list does not tell you.
+
+## 6. The demos that already exist
+
+Both of these are working code in this repository. Neither was linked from anywhere until this page
+existed, which is how integrators end up rebuilding them.
+
+- **[`examples/e2e/`](../examples/e2e/README.md) — the bridge, end to end, in a real browser.** A real
+  parent page and a real game frame, served from two different origins, exchanging a real
+  `MessagePort`. `pnpm e2e` builds the artifacts and serves it. This is the thing to run when a
+  handshake is not landing and you need to know whether the problem is the SDK or your page:
+  `?sandbox=strict` reproduces the sandbox failure on demand.
+- **[`examples/server-bundle/echo.mjs`](../examples/server-bundle/echo.mjs) — a complete dedicated
+  server for a match, in one file.** The lifecycle a bundle implements and the first message on the
+  channel, running. Its contract is [`server-bundles.md`](server-bundles.md).
+
+## 7. A dedicated match does not run forever, and neither does its server
+
+Read on **2026-08-13**, which is later than the date at the top of this page and covers this rule
+only.
+
+Nothing in the client surface says how long a match may last, so the assumption people arrive with is
+that it lasts until somebody ends it. It does not. **Every dedicated match has a maximum duration**,
+declared per room template in your published config — 30 minutes to 48 hours, and **six hours if the
+template declares nothing**. Reaching it ends the match the way your own server ending it would, so
+the members get the `match_ended` push they already handle and the room reopens.
+
+That is a backstop rather than a schedule: a game that ends its own matches never meets it. The one
+that does is the match nobody ended, which is common enough to be worth the rule — a finished match
+whose last tab stayed open looks, from the server, exactly like a player taking their time.
+
+The **server's** half of this is separate and easier to get wrong, because the budget it gets to wind
+down in depends on why it is stopping, and the two budgets are nothing like each other — minutes in
+one case, hours in the other. Both, and the reason a bundle never sees the signal that starts the
+longer one, are in [`server-bundles.md`](server-bundles.md#how-long-your-server-lives).
+
+## 8. A player's Boost is for display, never a gate
+
+Decided by the platform on **2026-09-26**, and a contract rather than an implementation fact.
+
+The **Boost** is the only thing the Arcade sells for real money. While a player has one, they earn
+**Gems and Tickets** faster — every grant is multiplied — and their earning limits and holdings cap
+are raised by the same tier. It **never** touches achievement points. The platform applies all of
+it on its own side, when it pays: a game does nothing to make a boost work, and cannot make one
+work harder.
+
+A game **may show** it. `gem.player.boost` carries each boostable currency's multiplier and the
+whole days left, so a reward screen can say "2× Tickets"; see
+[what a game must do](what-a-game-must-do.md#the-signed-in-players-boost-show-it-never-gate-on-it).
+A dedicated server can read the same effective boost for a player in its match, and the same rule
+holds there.
+
+A game **must not gate** anything on it:
+
+- **No content or power behind it.** No level, item, character, mode, stat, difficulty setting or
+  extra attempt may depend on whether the player is boosted. A boosted and an unboosted player play
+  the same game.
+- **No prices that depend on it**, and no discount or surcharge keyed on boost status.
+- **No matchmaking on it.** Never exclude, separate or wait on a player because of their boost.
+- **No nagging.** No "you're not boosted" loops, interstitials or countdown pressure. The Arcade owns
+  the Boost store; a game does not sell or advertise boosts.
+
+Three reasons, any one of which would be enough. It is **advisory**: the browser value is pushed on
+connect and on change, so it can lag a boost that just started or ended, and the platform's own
+figure is what pays. It is **forgeable** inside your page, so a gate on it is a gate anyone can
+open. And gating on it turns a faster faucet into pay-to-win, which is the line the Arcade's economy
+is drawn on.
+
+It carries **a day count, never an instant — and capped at 7**, so `7` means "7 or more" — and
+nothing about the tier, the price or whether the player paid at all: free and paid boosts look
+identical to a game. A second-precision expiry would be a near-unique value per player that two
+games could join on, and an exact day count would jump by a purchase's term the moment the player
+paid. Show `7` as "7+ days", never as an end date.
+
+## Where the rest of it is
+
+- [`what-a-game-must-do.md`](what-a-game-must-do.md) — what the SDK does not do for you, and the boot
+  sequence that decides whether the handshake lands at all.
+- [`rooms-and-matches.md`](rooms-and-matches.md) — the SDK's room and match model, and why it is
+  shaped like the engine's.
+- [`dedicated-server-flow.md`](dedicated-server-flow.md) and [`p2p-and-parties.md`](p2p-and-parties.md)
+  — getting onto a server, and getting onto a peer.

package/docs/player-sign-in.md

@@ -0,0 +1,89 @@
+# Asking the player to sign in
+
+Some of what your game offers is only worth something to a player with an account — progress that
+follows them to another device, a name on a leaderboard, friends. When a player reaches for one of
+those, your game can ask the Arcade to sign them in. The Arcade shows sign-in in its own chrome, the
+player decides, and the Arcade tells you how it went.
+
+```js
+signInButton.onclick = async () => {
+  await saveProgress(); // see section 1
+  const { outcome } = await gem.account.requestSignIn();
+  if (outcome === 'signed_in') {
+    await reloadProgress(); // see section 2
+    hideUpsell();
+  }
+  // `declined` and `unavailable`: carry on, and say nothing.
+};
+```
+
+That is the whole surface. Your game never draws a sign-in form and never handles a password; it
+could not be trusted with either, and it does not need to be.
+
+## 1. Save before you ask
+
+The Arcade may sign the player in **by taking the whole page to its sign-in screen**. When it does:
+
+- your game is unloaded, and `requestSignIn` never settles — there is nothing left to settle it;
+- `onWillTerminate` fires first, with a short grace period, exactly as it does for every other
+  teardown;
+- after signing in, the player lands back in your game, which starts again from the top under
+  their account.
+
+So anything the player would mind losing has to be saved **before** the call. The example above
+awaits its save first for that reason. Do not rely on the code after the `await` running at all.
+
+## 2. On `signed_in`, the player may have changed
+
+When the Arcade signs the player in without unloading your game, the promise resolves `signed_in` —
+and by then `gem.identity`, `gem.player` and `gem.me` already answer for the account. The SDK has
+also dropped everything it cached for whoever was playing before.
+
+Your own variables are yours to refresh. A player who signs in to an account they already had is a
+different player from the one your game loaded for, with their own saves and their own inventory.
+So on `signed_in`:
+
+- re-read `gem.identity` rather than keeping an id you read earlier;
+- reload what you loaded from `gem.me` — saves, settings, inventory, currencies;
+- leave and re-join any room you were holding a seat in under the old identity.
+
+`signed_in` is also the answer when the player was signed in all along. Nothing is shown to them,
+and nothing has changed; hide the upsell.
+
+## 3. The three answers, and nothing rejects
+
+| outcome | what happened | what your game does |
+|---|---|---|
+| `signed_in` | the player is signed in | re-read, then hide the upsell |
+| `declined` | the player closed the prompt, or the Arcade chose not to show one | return to the game silently |
+| `unavailable` | the Arcade does not offer this here, or never answered | return to the game silently |
+
+`requestSignIn` always resolves when it resolves at all. There is no error branch and no
+`try`/`catch` to write.
+
+- **Say nothing on `declined`.** The player saw the prompt and closed it. A "sign-in failed"
+  message after a deliberate Cancel reads as a bug.
+- **You are told no reason**, and one will not be added. Why a sign-in did not happen is between
+  the player and the Arcade.
+- **`unavailable` is ordinary**, not a fault. It is what every call returns outside the Arcade, and
+  anywhere the Arcade has no sign-in to offer. Never retry it on a timer; only a fresh press from
+  the player may ask again.
+
+## 4. Ask from a button, and only from a button
+
+Call `requestSignIn` from something the player pressed — never at start-up, never on a timer, and
+never as the price of continuing to play. The Arcade decides whether a prompt appears at all, shows
+one at a time, and is free to answer `declined` without showing anything to a game that asks too
+often.
+
+Pressing two upsell buttons does not open two prompts. A second call made while the first is still
+open joins it, and both resolve with the same answer.
+
+## 5. You pass nothing, deliberately
+
+There is no message to customise and no address to return to. The words on a sign-in screen are
+the Arcade's, so a player can trust them whichever game they came from; and the Arcade already
+knows which game to bring the player back to.
+
+Say what the account is *for* in your own game, on your own button — "Sign in to keep this run" —
+before the player presses it.

package/docs/room-shapes.md

@@ -0,0 +1,195 @@
+# Room shapes — the four things a game room is for
+
+A game room is one mechanism with four useful shapes. The same browser surface (`gem.rooms` to get
+in, `gem.match.connect()` to reach the authority) and the same server entry point (`defineServer`)
+serve all four; what differs is the room template and what the hosting server chooses to do with
+its time.
+
+Only three of the four need a second player. The fourth is for a game that has no multiplayer at
+all and still needs something a browser cannot be trusted to do.
+
+This page is the decision. [rooms-and-matches.md](rooms-and-matches.md) is the mechanism behind
+it — the room state machine, the event stream, room args, reconnection — and is what to read once
+you know which shape you want.
+
+## Pick a shape
+
+Answer in this order. The first yes wins.
+
+1. **Does the server need to run a match at all**, or only answer requests from clients who are
+   not playing each other? Only answer requests → **authoritative worker**.
+2. **Does one player decide when a round starts, and with what settings?** → **custom**.
+3. **Do players arrive and leave continuously, with the world outliving any one of them?** →
+   **hub**.
+4. Otherwise a lobby fills and plays one match → **match**.
+
+## The four
+
+### Match
+
+The ordinary shape. Players are matchmade into a room, the room fills, a match starts, the match
+ends. One lobby, one match — what most competitive and co-op games want.
+
+The join that brings membership to `min_players` starts the match, so nobody has to press a
+button labelled "go". **A match is sized by who is in the room the instant it starts**, and
+nothing tops it up afterwards; if you want late joiners, that is `allow_join_in_progress`, and it
+is a genuinely different game to write — the server has to place a player mid-match and hand them
+current state rather than a start-of-match snapshot.
+
+### Hub
+
+A shared world that outlives any one player. Members arrive and leave continuously and the world
+does not restart around them: a persistent zone, a town, a social lobby players visit between
+games.
+
+A hub is **served** or **unserved**, and `match_type` decides which:
+
+- `dedicated` with `allow_join_in_progress: true` — a server runs the world, players see each
+  other move, the server is the authority.
+- `none` — the room starts no match at all. It is a place to be rather than a world to simulate:
+  somewhere players gather, see a roster, agree on something through room args, and leave for a
+  real match. No allocation, no server bundle, no duration ceiling.
+
+Reach for `none` when nothing needs simulating. A lobby that needs a member list and a settings
+object does not need a server, and a served hub costs one.
+
+### Authoritative worker
+
+A room whose server **runs no match**. It accepts no player input, replicates no world state,
+simulates nothing. It answers requests from members who are not playing each other, and each
+member's session is unrelated to every other member's.
+
+This is how a browser game reaches an execution context a modified client cannot rewrite. Use it
+when something must be decided on your behalf rather than the player's, and the platform has no
+built-in rule for it:
+
+- Confirming an offline, single-player run really was finished, and to the score claimed.
+- Granting an award whose condition is game state — level reached, boss defeated, run completed
+  under a time — that only your game code can evaluate.
+- Checking a score before it counts.
+
+**A game with no multiplayer can need this shape.** The room is not a lobby; it is a way to get
+your own code running somewhere the player does not control.
+
+If a check out of the player's reach is all you want the room for, a serverless function is the
+smaller tool: no room, no seat and no connection, one call at a time. See
+[serverless-functions.md](serverless-functions.md).
+
+Two things decide whether you need it at all. See
+[what a worker owes you, and what it does not](#what-a-worker-owes-you-and-what-it-does-not).
+
+### Custom
+
+A room one player owns, where a group gathers and plays round after round. The owner picks the
+settings, members see what was picked, the owner starts. When the match ends everyone comes back
+to the room and does it again, possibly with different settings.
+
+The room outlives each match, which is what separates it from a match room. Players arrive by
+join code or, if the room is public, from the room browser. What the owner may choose is declared
+by the template's room-args schema, so a settings menu should render from that schema rather than
+from a list hard-coded in your client — then the config can add a mode without a new build.
+
+## The settings that produce each
+
+|                          | Match             | Hub                   | Worker      | Custom                |
+| ------------------------ | ----------------- | --------------------- | ----------- | --------------------- |
+| `match_type`             | `dedicated`/`p2p` | `dedicated` or `none` | `dedicated` | `dedicated`/`p2p`     |
+| `auto_start_host`        | `true`            | `true`                | `true`      | **`false`**           |
+| `min_players`            | the match size    | `1`                   | `1`         | `1`                   |
+| `allow_join_in_progress` | for backfill      | **`true`**            | **`true`**  | `false`               |
+| `show_in_browser`        | `false`           | `true`                | `false`     | when public           |
+| `transports`             | the ladder        | the ladder            | the ladder  | the ladder            |
+| How a player gets in     | `quickJoin`       | `quickJoin`           | `quickJoin` | `create`/`joinByCode` |
+| What starts the match    | `min_players`     | `min_players`         | first join  | the owner             |
+
+Templates live in your game config under `game_room_templates`, and are uploaded and promoted per
+channel like the rest of it. `transports` is the same on every shape because it is orthogonal to
+shape: the list of wires a match may be played over, most preferred first — `webtransport`,
+`webrtc`, `websocket` — which the SDK dials from and the host offers from, so no game names a
+transport in code. Leave it out for the platform ladder (all three, in that order); a `p2p`
+template may name only `webrtc`. `dedicated-server-flow.md` has the whole story. One template field is deliberately absent from the table:
+`auto_close_when_empty` is carried and returned, and read by nothing — an empty room is deleted
+whichever way it is set ([platform-rules.md](platform-rules.md#2-room-lifecycle-when-one-goes-away-and-what-a-leftover-does-to-you)).
+
+Two entries in that table do most of the work. **`auto_start_host: false` is what makes a custom
+room** — with it true, the room starts a match the moment membership reaches `min_players` and the
+owner never gets to choose anything. **`allow_join_in_progress` is what makes a hub** — without
+it, a player who quick-joins while a match runs starts a _new_ room, and your shared world
+quietly becomes one world per player.
+
+## What the platform decides for you
+
+Four limits bind every shape, and three of the four shapes exist partly to work around one of
+them.
+
+**Seats belong to the template, not to the room.** A create request carrying its own
+`max_players` is refused rather than having the field ignored. The template's count is not
+confined to a lobby-sized number. What _is_ bounded 2–64 is resizing a room that already exists,
+and that resize is refused below the room's current member count. Choose a served room's seats
+from what one process can carry.
+
+**A match has a maximum duration.** `max_match_duration_seconds` defaults to 21600 — six hours —
+after which the platform ends the match the way any end happens: members get the ordinary
+`match_ended` push and the server is released. **Nothing here runs forever.** A hub or a worker is
+recycled, not permanent, and has to be written that way: durable state belongs in player save
+data or your own store, written as it changes rather than at shutdown, and the client re-enters
+on the room's `matchEnded` event (reason `expired`, `roomReopened: true`) rather than treating it
+as a crash. Since the SDK's 4.0.0 release (2026-09-10) re-entering is a start, not a join: the
+room is open again with the same members, `auto_start_host` fires only when a room first reaches
+`min_players` and does not fire again for a reopened one, so the member `gem.rooms.isHost` names
+calls `gem.rooms.startMatch()` and every member then receives `matchAllocationStarted` and
+connects as before. Leaving and quick-joining again is not the re-entry — the player is still a
+member of the reopened room. [match-session.md](match-session.md) §5 is the sequence.
+
+**Concurrent matches are capped per player.** Starting one allocates real infrastructure. The cap
+counts only that player's own matches — nothing another player does can refuse you — and it clears
+when one of yours ends. A shape that gives every player a private room spends this budget and one
+server per player.
+
+**Starting a match is idempotent.** Repeated starts on the same room return the same match,
+behind a shared fence, so an `auto_start_host` template and a client that also calls start cannot
+race into two matches.
+
+## What a worker owes you, and what it does not
+
+The worker shape is the one most easily got wrong, in both directions.
+
+**It is not the answer to economy arithmetic.** Spending a currency and granting an item is a
+**recipe**, and a recipe is already evaluated on the platform's side where a modified client
+cannot change the arithmetic — no server of yours, no allocation, no seat. See
+[inventory-and-catalogs.md](inventory-and-catalogs.md). A worker room is for validating game state
+the platform knows nothing about. A worker that grants _after_ validating is doing both: decide
+here, then let the grant itself be a recipe or an order.
+
+**Its server must check its own roster.** A server bundle's credential is scoped to your game and
+channel, not to its match, and the room roster is not a boundary the platform enforces on it. A
+bundle can therefore act on any player of your game, including one who never joined its room.
+That is needed by an ordinary match server writing results — and it means a worker that skips its
+own membership check is an open grant endpoint wearing a room as decoration. Read the roster and
+check the requesting player against it before acting; not against an id the client sent.
+
+**A result against a daily's board is checked against the platform's copy, never the client's.**
+When your studio stores each period's content with the challenge, the worker reads it with
+`gem.challenges.list({ playerId })` — for the player who submitted, whose period is their own, for
+the current period and, with `periodsBack: 1`, the one before, so a run finished just before the
+rollover still verifies — and validates against the entry whose `periodLocalDate` (a cron
+challenge's `seed`) and `dataHash` match what the client submitted, never its `periodStartAt`. No
+match is a rejection. [daily-challenges.md](daily-challenges.md#verifying-a-result-against-the-content) has
+the recipe.
+
+**It should hold nothing between joins.** Each join is an unrelated session. A returning player
+may be in a completely different state than when they left, and the process may have served
+hundreds of others in between.
+
+## Where to go next
+
+- [rooms-and-matches.md](rooms-and-matches.md) — the browser half in full: the room state
+  machine, the event stream, room args, reconnection, and what closing a tab does to a membership.
+- [match-session.md](match-session.md) — the session after the start: its phases, why a match
+  ends, the reconnect policy, and how the next round starts in the same room.
+- [dedicated-server-flow.md](dedicated-server-flow.md) — how a match gets a server, and what the
+  waits mean.
+- [server-bundles.md](server-bundles.md) — writing and publishing the server half.
+- [p2p-and-parties.md](p2p-and-parties.md) — the shapes that run without a server of ours.
+- [inventory-and-catalogs.md](inventory-and-catalogs.md) — what a server calls once it has
+  authority.