@indiegems/gem-web-sdk 8.0.0 → 9.0.0

package/docs/room-shapes.md

@@ -1,12 +1,14 @@
-# Room shapes — the four things a game room is for
+# Room shapes — the three 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.
+A game room is one mechanism with three 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 three; 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.
+A room is for players who share something live. A game with no real-time match that still needs
+something a browser cannot be trusted to do — a run verified, a score checked before it counts, a
+reward granted — does not need a room or a game server. That is a serverless function:
+[serverless-functions.md](serverless-functions.md).
 
 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
@@ -16,14 +18,12 @@ you know which shape you want.
 
 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?** →
+1. **Does one player decide when a round starts, and with what settings?** → **custom**.
+2. **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**.
+3. Otherwise a lobby fills and plays one match → **match**.
 
-## The four
+## The three
 
 ### Match
 
@@ -53,31 +53,6 @@ A hub is **served** or **unserved**, and `match_type` decides which:
 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
@@ -91,16 +66,16 @@ from a list hard-coded in your client — then the config can add a mode without
 
 ## 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             |
+|                          | Match             | Hub                   | Custom                |
+| ------------------------ | ----------------- | --------------------- | --------------------- |
+| `match_type`             | `dedicated`/`p2p` | `dedicated` or `none` | `dedicated`/`p2p`     |
+| `auto_start_host`        | `true`            | `true`                | **`false`**           |
+| `min_players`            | the match size    | `1`                   | `1`                   |
+| `allow_join_in_progress` | for backfill      | **`true`**            | `false`               |
+| `show_in_browser`        | `false`           | `true`                | when public           |
+| `transports`             | the ladder        | the ladder            | the ladder            |
+| How a player gets in     | `quickJoin`       | `quickJoin`           | `create`/`joinByCode` |
+| What starts the match    | `min_players`     | `min_players`         | 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
@@ -119,8 +94,7 @@ 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.
+Four limits bind every shape.
 
 **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
@@ -130,7 +104,7 @@ 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
+`match_ended` push and the server is released. **Nothing here runs forever.** A hub 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
@@ -150,37 +124,39 @@ server per player.
 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.
+## What a server in a room owes you
 
 **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
+That is needed by an ordinary match server writing results — and it means a server that acts
+because a client asked it to must read the roster and check the requesting player against it
+first; not against an id the client sent.
+
+**It should hold no player state between joins.** Each join is a session, not an identity. 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.
+
+## When you do not need a room
+
+A room, and the server behind it, is for a real-time match: the server is the authority, corrects
+what players do, and replicates the state of the game to everyone in it. Such a server can also
+verify results and grant progression and rewards for the match it ran.
+
+Everything else that must happen out of the player's reach is a **serverless function**:
+confirming a single-player run really was finished and to the score claimed, checking a score
+before it reaches a leaderboard, anti-cheat, updating progression, granting a reward whose
+condition only your game code can evaluate. A function needs no room, no seat and no connection,
+costs less and scales further. See [serverless-functions.md](serverless-functions.md).
+
+Two things are not a function's job either. Spending a currency and granting an item is a
+**recipe**, already evaluated on the platform's side where a modified client cannot change the
+arithmetic — see [inventory-and-catalogs.md](inventory-and-catalogs.md); a function that has
+decided a player earned something still makes the grant itself a recipe or an order. And a result
+against a daily's board is checked against the platform's copy of that period's content, never the
+client's — [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
@@ -193,3 +169,5 @@ hundreds of others in between.
 - [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.
+- [serverless-functions.md](serverless-functions.md) — your own check out of the player's reach,
+  with no room and no game server.

package/docs/rooms-and-matches.md

@@ -6,9 +6,8 @@ carrying the engine's model should transfer with no friction, and where the web
 engine this document says why.
 
 > **Which SHAPE of room you want is decided first, on
-> [`room-shapes.md`](room-shapes.md)** — a match, a hub players drift through, a custom lobby one
-> player owns, or an authoritative worker whose server runs no match at all. This page is the
-> mechanism underneath all four.
+> [`room-shapes.md`](room-shapes.md)** — a match, a hub players drift through, or a custom lobby one
+> player owns. This page is the mechanism underneath all three.
 
 > **This page is the SDK's model. The platform's own rules are
 > [`platform-rules.md`](platform-rules.md)** — what gem-api enforces underneath, none of which is

package/docs/server-bundles.md

@@ -80,8 +80,8 @@ To check the download yourself: the package npm serves is, byte for byte, the fi
 also publishes on its download host, with the hash beside it:
 
 ```bash
-curl -fsSL -O https://downloads.gemarcade.com/sdk/v8.0.0/gem-web-sdk.tgz
-curl -fsSL https://downloads.gemarcade.com/sdk/v8.0.0/gem-web-sdk.tgz.sri
+curl -fsSL -O https://downloads.gemarcade.com/sdk/v9.0.0/gem-web-sdk.tgz
+curl -fsSL https://downloads.gemarcade.com/sdk/v9.0.0/gem-web-sdk.tgz.sri
 openssl dgst -sha384 -binary gem-web-sdk.tgz | openssl base64 -A
 ```
 

package/docs/serverless-functions.md

@@ -35,10 +35,11 @@ Two cases look like a function and are not:
   a dedicated server, and [server-bundles.md](server-bundles.md) is how you write one. A function
   holds nothing between calls.
 
-A function is also the smaller answer to a need [room-shapes.md](room-shapes.md#authoritative-worker)
-meets with an **authoritative worker** room. If you were going to allocate a worker room only to
-run your own check out of the player's reach, a function does the same job with no room, no seat
-and no connection to open, and each call is its own run.
+A function is the answer whenever your own check has to run out of the player's reach and no
+real-time match is running: verifying a run or a score, anti-cheat, updating progression, granting
+a reward. It needs no room, no seat and no connection to open, and each call is its own run. A game
+with no multiplayer does not need a game server for any of this.
+[room-shapes.md](room-shapes.md#when-you-do-not-need-a-room) draws the line from the other side.
 
 ⚠️ **A verdict you return to the browser is advice to the client you do not trust.** If your
 function decides a player earned something and returns `{ "ok": true }`, a modified client can skip
@@ -440,18 +441,22 @@ on every request your function makes.
 
 ### The limits on one call
 
-These are the platform's limits, the same for every game, and a game cannot raise its own.
-
-| Limit                                               | Value                                  |
-| --------------------------------------------------- | -------------------------------------- |
-| Wall clock                                          | 5 seconds                              |
-| CPU                                                 | 1 second of that 5                     |
-| Memory                                              | 64 MiB                                 |
-| `call-api`, `download-link` and `upload-link` calls | 32, all three together                 |
-| Input                                               | 256 KiB                                |
-| Output                                              | 1 MiB                                  |
-| Component size                                      | 32 MiB                                 |
-| Calls, per caller per minute                        | 30 for a player, 120 for a game server |
+These are the platform's limits, the same for every game, and a game cannot raise its own. If your
+game needs more memory, CPU, time or calls than they allow, ask for the limit to be raised: the
+platform raises a function's limits so the game can stay on a function. Reaching one is never a
+reason to move the work to a game server.
+
+| Limit                                                                          | Value                                  |
+| ------------------------------------------------------------------------------ | -------------------------------------- |
+| Wall clock                                                                     | 5 seconds                              |
+| CPU                                                                            | 1 second of that 5                     |
+| Memory                                                                         | 64 MiB                                 |
+| `call-api`, `download-link` and `upload-link` calls                            | 32, all three together                 |
+| A value handed to one `log`, `call-api`, `download-link` or `upload-link` call | 16 MiB                                 |
+| Input                                                                          | 256 KiB                                |
+| Output                                                                         | 1 MiB                                  |
+| Component size                                                                 | 32 MiB                                 |
+| Calls, per caller per minute                                                   | 30 for a player, 120 for a game server |
 
 **The per-minute budget belongs to the caller, not to your game.** A player who spends theirs is
 refused and nobody else is affected. Thirty a minute is also why a function call belongs at a
@@ -767,7 +772,9 @@ or `game_server`:
 - **A line your function logged**: its `level` and its `message`.
 - **The closing line**: `outcome` is `ok`, `error`, `timeout`, `cpu_exceeded` or `failed`, with the
   call's `wall_ms` and `cpu_ms`. On `error`, `message` is your `Err` text. On `failed`, `reason`
-  says what ended the call, and when your own code trapped, `message` is the trap's message.
+  says what ended the call, and when your own code trapped, `message` is the trap's message. When
+  `reason` is `output_too_large` or `argument_too_large`, `detail` names the limit the call
+  exceeded. The platform writes it and never copies your function's data into it.
 
 Newest first means a call's closing line comes before what it logged. **A call's logging is
 capped**: once it reaches its per-call log limit, that `log` call and every later one go
@@ -795,24 +802,27 @@ Every answer from a call that reached your function carries an invocation id: su
 refused before that point never became an invocation and carries none. `err.retryable` agrees with
 the last column: it is `true` exactly where this table says to retry.
 
-| What you get                                               | What happened                                                                                             | What to do                                                             |
-| ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
-| `422 function_error`                                       | Your `handle` returned `Err`. The text is `err.functionMessage`                                           | Fix your code or the input. Return verdicts in `Ok`                    |
-| `422 function_failed`                                      | It did not finish. `err.failure` is `trap`, `memory_exceeded`, `cpu_budget_exceeded` or `host_call_limit` | A bug or a limit in the function. Reproduce with the same input        |
-| `504 function_timeout`                                     | It ran past the wall clock                                                                                | Do not retry: the same input takes as long again                       |
-| `404 function_not_published`                               | Nothing is promoted on the caller's channel                                                               | `gemctl function promote <version> --channel <channel>`                |
-| `413 function_input_too_large`                             | The input is over 256 KiB                                                                                 | Send a request, not a file                                             |
-| `429 rate_limited`                                         | This caller's per-minute budget is spent                                                                  | Wait `err.retryAfterSeconds`                                           |
-| `503 function_capacity_unavailable`                        | The platform was too busy to run it. Your function is not known to be broken                              | Retry after `err.retryAfterSeconds`                                    |
-| `503 function_host_unreachable`, `503 function_host_error` | The platform could not run it. Nothing about your function                                                | Retry shortly. Quote the invocation id if it persists                  |
-| `503 service_unavailable`                                  | The platform could not check the caller's budget, so it refused the call. The function did not run        | Retry shortly                                                          |
-| `503 functions_not_configured`                             | Functions are switched off on the backend you called                                                      | Do not retry. Nothing about your function or your game                 |
-| `403 forbidden`                                            | The call carried an account sign-in rather than a game-scoped or game-server token                        | Call from your game or its server, or through `gemctl function invoke` |
+| What you get                                               | What happened                                                                                                                                       | What to do                                                             |
+| ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| `422 function_error`                                       | Your `handle` returned `Err`. The text is `err.functionMessage`                                                                                     | Fix your code or the input. Return verdicts in `Ok`                    |
+| `422 function_failed`                                      | It did not finish. `err.failure` is `trap`, `memory_exceeded`, `cpu_budget_exceeded`, `host_call_limit`, `output_too_large` or `argument_too_large` | A bug or a limit in the function. Reproduce with the same input        |
+| `504 function_timeout`                                     | It ran past the wall clock                                                                                                                          | Do not retry: the same input takes as long again                       |
+| `404 function_not_published`                               | Nothing is promoted on the caller's channel                                                                                                         | `gemctl function promote <version> --channel <channel>`                |
+| `413 function_input_too_large`                             | The input is over 256 KiB                                                                                                                           | Send a request, not a file                                             |
+| `429 rate_limited`                                         | This caller's per-minute budget is spent                                                                                                            | Wait `err.retryAfterSeconds`                                           |
+| `503 function_capacity_unavailable`                        | The platform was too busy to run it. Your function is not known to be broken                                                                        | Retry after `err.retryAfterSeconds`                                    |
+| `503 function_host_unreachable`, `503 function_host_error` | The platform could not run it. Nothing about your function                                                                                          | Retry shortly. Quote the invocation id if it persists                  |
+| `503 service_unavailable`                                  | The platform could not check the caller's budget, so it refused the call. The function did not run                                                  | Retry shortly                                                          |
+| `503 functions_not_configured`                             | Functions are switched off on the backend you called                                                                                                | Do not retry. Nothing about your function or your game                 |
+| `403 forbidden`                                            | The call carried an account sign-in rather than a game-scoped or game-server token                                                                  | Call from your game or its server, or through `gemctl function invoke` |
 
 A `trap` is a panic, an `unreachable`, an out-of-bounds access or a stack overflow, and no stack
 trace comes back with it. On `dev`, the call's closing line in `gemctl function logs` carries the
-trap's message when your own code trapped (section 7). The other three reasons are the limits in
-section 2.
+trap's message when your own code trapped (section 7). The other five reasons are the limits in
+section 2. Two of them are about size: `output_too_large` is a result over the 1 MiB output cap,
+and `argument_too_large` is a value your function handed to `log`, `call-api`, `download-link` or
+`upload-link` that was over the 16 MiB one call accepts. On `dev`, the closing line of either
+carries `detail`, naming the limit the call exceeded.
 
 Publishing has its own refusals, and nothing is stored when one happens:
 

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

@@ -53,8 +53,9 @@ No `baseUrl`. The Arcade names the backend on every token and the SDK routes the
 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;
+- **the platform's websites (Gem Arcade and Meme Games) and the Gem Arcade app** — the SDK carries
+  their origins as `ARCADE_EMBEDDERS`, on every platform the app runs on. Your game is listed on
+  one of the websites, but it accepts every origin in that list;
 - **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.
@@ -353,6 +354,117 @@ one refused orientation, in fullscreen, once they are already the right way roun
 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.
 
+**The same declaration decides how a computer or a television shows your game.** Neither is held
+two ways round, so the Arcade reads your phone and tablet rows instead and, for a portrait-only
+game, draws a centred portrait column.
+[Art beside a portrait game](#art-beside-a-portrait-game-on-a-wide-screen-portrait-borders) below
+has the exact rule, and the art you can put beside that column.
+
+## Art beside a portrait game on a wide screen: portrait borders
+
+**You need this only if your game is portrait-only and you want your own art beside it on a
+computer or a television.** On a desktop browser, the Arcade's desktop app or a TV, the Arcade
+draws a portrait-only game as a centred 9:16 column and fills the space either side with its own
+bars. Portrait borders put your art there instead: you publish a named set of images with your
+store page, and your game says which one goes with what is on screen.
+
+### When the Arcade letterboxes a game
+
+**Your store page's `orientations` decide it, and nothing else does.** Declaring borders never
+turns the letterbox on, and there is no desktop orientation to declare. The rule:
+
+1. Take `tablet` if you declared both its `portrait` and its `landscape`; otherwise `phone` if you
+   declared both of its; otherwise stop, and the game is not letterboxed.
+2. The game is letterboxed to portrait when, on that device, `portrait` is `full` or `partial` and
+   `landscape` is `none`.
+
+| `orientations`, each pair portrait / landscape | Letterboxed on a computer or TV |
+| ---------------------------------------------- | ------------------------------- |
+| nothing declared                               | no                              |
+| tablet `full` / `none`                         | yes                             |
+| phone `full` / `none`, no tablet               | yes                             |
+| phone `partial` / `none`, no tablet            | yes                             |
+| phone `full` / `none`, tablet `full` / `full`  | no — the tablet decides         |
+| phone `full` / `none`, tablet `none` / `full`  | no — the tablet decides         |
+| tablet `none` / `full`                         | no                              |
+| tablet `partial` / `partial`                   | no                              |
+| tablet `full` / `partial`                      | no                              |
+
+A phone or a tablet is never letterboxed: it gets the rotate panel from the section above. On a
+computer or TV, a game the rule does not letterbox fills the play area and its borders never show.
+**A store page with borders and orientations that never letterbox uploads with a
+`portrait_borders_unused` warning** — the page is accepted, and the art will not appear anywhere.
+
+### Declaring the borders
+
+Add them to your store page's `media`, one entry per image:
+
+```yaml
+media:
+  portrait_borders:
+    - name: meadow # the first entry is the default
+      src: borders/meadow.jpg
+    - name: alpine
+      src: borders/alpine.jpg
+```
+
+- **Up to 16 entries**, each with a `name` and a `src`. A name is 1 to 40 characters of `a-z`,
+  `0-9`, `_` and `-`, starts with a letter or digit, and is unique on the page.
+- **The first entry is the default.** The Arcade shows it the moment play starts, before your game
+  has said anything, so put first the one most players should see.
+- **16:9, at least 1920×1080; 2560×1440 is ideal.** PNG, JPEG or WebP. An AVIF, GIF or SVG uploads
+  without complaint and then fails the page's processing.
+- **Opaque.** A transparent area shows the Arcade's own bars through it.
+- **Keep the interesting part away from the middle.** The image is scaled to cover the whole play
+  area and centred, and your game covers the centre. How much shows either side changes with the
+  shape of the player's screen — in a window narrower than the column, the art shows above and
+  below instead — so nothing in the art can line up with your game's edge.
+- **Upload with a current `gemctl`.** An older one refuses `portrait_borders` as an unknown key.
+
+### Choosing one from your game
+
+Call `gem.showPortraitBorders` at start-up and on every theme change, with the name of the border
+that goes with what is on screen, and `null` for a theme that has no art:
+
+```js
+const BORDERS = new Set(['meadow', 'alpine']); // the names your store page declares
+
+function applyTheme(id) {
+  document.body.dataset.theme = id;
+  gem.showPortraitBorders(BORDERS.has(id) ? id : null); // null: the Arcade's own bars show again
+}
+```
+
+- **Call it unconditionally.** On a phone, or on a screen where your game is not letterboxed, the
+  Arcade keeps your choice and shows nothing, and nothing tells your game which case it is in — do
+  not look for a signal. `gem.frame.parentSupports('portraitBorders')` says whether this Arcade can
+  paint borders at all, never whether it is painting them now.
+- **It is safe at any time.** Before the connection exists your choice is held and sent when the
+  Arcade connects. A burst of calls — a theme picker previewing on hover — reaches the Arcade as
+  its final value, at most one a second, so it never trips a rate limit. An embedder that paints
+  no borders is not told, and nothing is raised.
+- **The Arcade owns the change.** When and how the image swaps is the Arcade's; you get no
+  acknowledgement and no say in the timing. A game that restores a saved theme just after it
+  starts shows the default for a moment, then its own.
+- **It shows only while your game is playing** — not before play starts, and not while your key
+  art covers the play area.
+- **A string that is not a valid name is refused on your side**, with a console warning, and never
+  sent. The SDK does not trim it, lower-case it or shorten it.
+- **A valid name your page does not declare is ignored**, and the Arcade keeps what it is showing.
+  On the dev and test channels the Arcade's own page logs a console warning naming the value, the
+  channel whose page it looked in, and the names that page declares; on release it says nothing.
+
+### Publishing order and experiments
+
+- **Publish the store page before, or together with, the build that uses a new name.** A build
+  asking for a name its page does not carry yet keeps the current image until the page arrives.
+  Rolling a build back is harmless; rolling the page back can remove a name, and the Arcade then
+  keeps showing what it has.
+- **Every arm of a store-page experiment must carry every name your build uses.** The set comes
+  from the page the player opened, so an arm without a name falls under the rule above.
+- **The borders come from the store page on screen.** To see your dev-channel borders, open your
+  game's store page on the dev channel. `gemctl serve` does not letterbox and shows no borders.
+
 ## An achievement unlock — celebrate it yourself, or declare the Arcade's
 
 By default the Arcade draws no card when a player unlocks one of your game's
@@ -429,8 +541,10 @@ credit for it until you say so.
   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.
+  render-scale option (render at DPR 1 and upscale), bound memory, assume a fixed frame — 16:9, or
+  a centred 9:16 column when your store page makes you
+  [a letterboxed portrait game](#art-beside-a-portrait-game-on-a-wide-screen-portrait-borders) —
+  with 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)
@@ -1016,7 +1130,15 @@ renderer serves all of them.
 | `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        |
+| `badges`        | Equipped badges, at most two, in the player's order, each `{ itemId, iconUrl }`             | array        |
+
+**A player chooses what they wear**: a portrait and up to two badges, each an icon they own — one
+an achievement in your game or any other may have awarded them ([achievements.md](achievements.md)
+§1). The portrait arrives as `avatarIconId` and `avatarIconUrl`, and the badges as `badges`, in the
+order the player put them in. `badges` is always a list — empty for a player who wears none, and on
+a row whose identity is withheld — so draw what is there, never pad it to two, and key on `itemId`,
+never on a position. A player can also equip a title, and colours and animations for their name and
+title. The SDK's identity does not carry those, so draw the name in your own style.
 
 **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.
@@ -1160,6 +1282,11 @@ rather than a failure; nothing rejects, so there is no error branch to write; an
 nothing, so a reward must never be handed out on the strength of it.
 [`cross-promotion.md`](cross-promotion.md) is the page.
 
+A button the player presses for a reward — a revive, an extra attempt — is the same call with
+`format: 'rewarded'`. Your game config declares what each such button grants, the platform writes
+the reward into your game's inventory, and your game reads it there rather than from the answer.
+[`rewarded-ads.md`](rewarded-ads.md) is that 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,

package/package.json

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