@indiegems/gem-web-sdk 8.0.0 → 8.1.0

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

@@ -353,6 +353,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 +540,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 +1129,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.

package/package.json

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

package/schema/bridge.v1.json

@@ -590,7 +590,7 @@
           "kind": "array",
           "maxItems": 2,
           "optional": true,
-          "$comment": "Equipped badges in display order — empty until platform achievements equip any, and never more than two. Each is an item id and a thumbnail URL, the same pin caveat as `avatarIconUrl`.",
+          "$comment": "Equipped badges in the order the player arranged them — never more than two, and empty when the player wears none. Each is an item id and a thumbnail URL, the same pin caveat as `avatarIconUrl`.",
           "items": {
             "kind": "object",
             "fields": {
@@ -2715,6 +2715,47 @@
       "rateLimit": { "perMinute": 120 }
     },
 
+    {
+      "type": "gem.portraitBorders",
+      "direction": "frameToParent",
+      "transport": "port",
+      "$comment": [
+        "Which of the store page's portrait borders the parent paints beside the",
+        "game while it letterboxes a portrait game on a wide screen. `name` is one",
+        "of the names the page declares under `media.portrait_borders`; absent",
+        "means clear the sides to the parent's own bars, for a theme with no art.",
+        "",
+        "A KEY INTO PUBLISHED ART, NEVER THE ART. The images are the store page's,",
+        "served and reviewed like every other store image; the frame chooses only",
+        "which one and when. The parent looks `name` up by exact match in the list",
+        "the page it is showing declares, and never renders it as text or builds a",
+        "URL from it. A name that list does not hold is ignored and the current",
+        "image stays. Transitions, their timing and any minimum dwell are the",
+        "parent's, swaps wait while a trusted overlay is up, and the frame gets no",
+        "acknowledgement.",
+        "",
+        "`name` is a plain bounded string with no format: a border name may carry",
+        "digits and hyphens, which the `code` format refuses. The SDK sends only",
+        "names matching `^[a-z0-9][a-z0-9_-]{0,39}$`, the store page's own rule, and",
+        "a parent checks the same rule on receipt.",
+        "",
+        "STATE, NOT A MOMENT. The SDK holds the game's latest choice until the",
+        "bridge connects and sends at most one a second, latest wins, so a burst",
+        "(a theme picker previewing on hover) delivers its final value well inside",
+        "the limit below.",
+        "",
+        "Gated by `portraitBorders`, which a parent that paints borders advertises",
+        "to EVERY game on every device, whether or not the game declares borders or",
+        "is letterboxed right now. It is never a signal of form factor or letterbox",
+        "state, and the parent answers nothing, so the frame learns nothing about",
+        "how it is being shown."
+      ],
+      "fields": {
+        "name": { "kind": "string", "maxLength": 40, "optional": true }
+      },
+      "rateLimit": { "perMinute": 60 }
+    },
+
     {
       "type": "gem.error",
       "direction": "both",

package/schema/capabilities.public.json

@@ -123,6 +123,12 @@
         "gem.frameStats"
       ]
     },
+    "portraitBorders": {
+      "implemented": true,
+      "gates": [
+        "gem.portraitBorders"
+      ]
+    },
     "engagement": {
       "implemented": true,
       "gates": [