@indiegems/gem-web-sdk 13.0.0 → 13.2.0

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

@@ -45,7 +45,7 @@ const link = await gem.match.connect(); // one link to the authority, whoever th
 No `baseUrl`. The Arcade names the backend on every token and the SDK routes there — see
 "which backend" below.
 
-## The five things that are yours
+## The things that are yours
 
 ### 1. The embedder allowlist
 
@@ -154,6 +154,28 @@ The SDK reports; it does not decide. A stale build (`versionUpdateAvailable`), a
 allocate, a token the parent refused — what a game does about each is a game decision, and a platform
 layer that acted would be making it for you.
 
+### 6. A platform moment at every break
+
+**Every game signals a platform moment from every press that leaves a natural break** — Next on a
+level-complete screen, Retry on a game-over screen, Continue on a match's results, Back to menu —
+whether or not it has a shop of its own. The Arcade decides whether to show one of its own offers
+over your paused game, and usually shows nothing:
+
+```js
+async function onNextPressed() {
+  startLevelTransition(); // your own fade, in parallel
+  await gem.moments.signal({ kind: 'level_end' });
+  startNextLevel(); // settled either way; `shown` grants nothing
+}
+```
+
+The SDK cannot place this call for you, because only your game knows where its breaks are. **The
+release checklist requires it** at every important break (MOM-01), and never at the wrong time —
+on boot, on a timer, mid-input or twice at one break (MOM-02). The platform does not enforce it:
+nothing refuses to publish or run a game without one. Nothing rejects either, so there is no error
+branch to write. It is the platform's moment, never your own offer: your shop and your rewarded
+buttons stay yours. [`platform-moments.md`](platform-moments.md) is the page.
+
 ## The boot phase: settle the bridge before the heavy bundle
 
 The invariant, stated plainly, because it is the hardest-won lesson in this document:
@@ -708,46 +730,54 @@ the `var()` above, or read `gem.viewport`. The release checklist looks for the b
 The Arcade keeps **one control of its own over every game**, on every device — a phone's full-bleed
 game, a framed or full-window game on a desktop, a tablet or a TV in native fullscreen:
 
-- **The Gem button**, the Gem Arcade's gem, in the **top-left corner**, always there (a touch target, about
-  50px across). It opens [the Arcade's menu](#the-arcades-menu): Return to the Arcade, the player's Gems,
-  Tickets and achievement score, mute, the player's Arcade-wide settings and the rest. Not your
-  settings: those are [your own button](#game-settings).
+- **The Gem button**, the Gem Arcade's gem, always there (a touch target, about 50px across), in
+  the **top-left corner** unless your game [asks for another](#moving-the-gem-gemsetgemcorner). It
+  opens [the Arcade's menu](#the-arcades-menu): Return to the Arcade, the player's Gems, Tickets and
+  achievement score, mute, the player's Arcade-wide settings and the rest. Not your settings: those
+  are [your own button](#game-settings).
 - **Nothing else.** The player's wallets (Gems, Tickets, their achievement score) are **not** drawn
   over your game: the player opens the Gem menu to see them, and every platform-currency payout
   flies into the Gem button ([the Arcade's wallet](#the-arcades-wallet-in-the-gem-menu-never-drawn-by-you)).
   When the player switches the frame-rate readout on, it sits beside the gem and is reserved the
   same way.
 
-**The top of the screen has one layout, in every game:**
+### The top of the screen
 
-| Where                                | Whose        | What goes there                                                                                                                                                                                         |
-| ------------------------------------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Top-left corner**                  | the Arcade's | Its Gem button. Nothing of yours under it.                                                                                                                                                              |
-| **Top-left, right of the Gem**       | yours        | Your **Home / Back** buttons, drawn when a screen needs them, level with the Gem and just to its right. They move around _inside_ your game — back to your level select or title screen — and never leave it. |
-| **Centre of the top row**            | yours        | Your **information**: score, moves, a timer, a level name.                                                                                                                                              |
-| **Top-right**                        | yours        | Your **settings** button ([Game settings](#game-settings)).                                                                                                                                             |
+**The top of the screen has one layout, in every game, wherever the Gem sits.** A player learns
+where "back" and "settings" are once, across every game:
 
-Keep the spot beside the Gem for Home / Back even on a screen that has neither today: a player
-learns where "back" is once, across every game, and information that sits there on one screen
-teaches them the wrong thing on the next.
+| Where                     | Whose        | What goes there                                                                                                                                                                                                        |
+| ------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **The Gem's corner**      | the Arcade's | Its Gem button — top-left unless you [ask for another corner](#moving-the-gem-gemsetgemcorner). Nothing of yours under it.                                                                                             |
+| **Top-right**             | yours        | Your **settings** button ([Game settings](#game-settings)) at the end of the row, and your **Back / Home** button just to its left, level with it and about 16px apart, so a fingertip lands on one and not the other. |
+| **Centre of the top row** | yours        | Your **information**: a title, score, moves, a timer, a level name.                                                                                                                                                    |
 
-**Your settings button goes top-right**, clear of any Arcade control: under the Gem Arcade there is
-none in that corner, but another embedder may keep one there. [Game settings](#game-settings) shows
-how to place it.
+- **Back / Home is drawn when a screen needs it, always in that spot.** It moves around _inside_
+  your game — back to your level select or title screen — and never leaves it: leaving is the
+  Arcade's menu, so a player always knows which control does which.
+- **Whichever of your controls shares the Gem's corner sits level with the Gem, on the side toward
+  the centre.** With the Gem top-left, nothing of yours does. With the Gem top-right, your Back and
+  settings sit just left of it.
+- **Your settings button is there on every screen.** It goes top-right even where no Arcade control
+  is: another embedder may keep one in that corner, so place it from the reserved areas below and it
+  moves aside for whatever is there.
 
-Those rectangles of your frame are **reserved**: keep essential UI and every touch target out of
-them. **Never hard-code their size or position.** They differ by phone, and in native fullscreen the
-gem may rise into the camera band — read them, as below.
+The parts of your frame under the Gem and any other Arcade control are **reserved**: keep
+essential UI and every touch target out of them. **Never hard-code their size or position.** They
+differ by phone, orientation and mode. The Gem sits at the edge of the safe area and never rises
+into the camera band, but that edge is somewhere else on every device — read them, as below.
 
 An inset cannot say that — as a left or top inset, a button a few dozen pixels wide would take a whole
 strip of your screen. So `gem.viewport` also carries the rectangles, in the same CSS pixels of your
 frame, measured from its top-left corner — one for the Gem button, and one for the frame-rate
-readout while the player shows it:
+readout while the player shows it. Each is grown out to the frame edges it sits nearest, because the
+sliver between the Gem and the edge is no place for a button either. On a notched phone in portrait,
+with the Gem top-left:
 
 ```json
 {
   "insets": { "top": 47, "right": 0, "bottom": 34, "left": 0 },
-  "reserved": [{ "x": 8, "y": 55, "width": 52, "height": 52 }]
+  "reserved": [{ "x": 0, "y": 0, "width": 60, "height": 99 }]
 }
 ```
 
@@ -755,35 +785,37 @@ readout while the player shows it:
 `--gem-safe-*` before anything else hears the push: `--gem-reserved-tl-width` and
 `--gem-reserved-tl-height`, and the same pair for `tr`, `bl` and `br` — how far that corner's
 reserved rectangles reach in from its two edges. A rectangle belongs to the corner its centre lies
-nearest to. Under the Gem Arcade the Gem button is a top-left rectangle, so:
+nearest to. Lay the top row out between the two top corners, and it is right wherever the Gem is:
 
 ```css
-/* ONE Home or Back button, level with the Gem, just to its right */
-#back {
+/* The top row: clear of whatever the Arcade reserves in either top corner */
+#top-row {
+  position: absolute;
   top: var(--gem-safe-top, env(safe-area-inset-top, 0px));
   left: max(var(--gem-safe-left, 0px), var(--gem-reserved-tl-width, 0px));
+  right: max(var(--gem-safe-right, 0px), var(--gem-reserved-tr-width, 0px));
+  display: flex;
+  align-items: center;
+  gap: 16px;
 }
-/* your information — score, moves, a timer — clear of every top corner the arcade reserves */
-#info {
-  top: max(
-    var(--gem-safe-top, env(safe-area-inset-top, 0px)),
-    var(--gem-reserved-tr-height, 0px)
-  );
-  left: max(var(--gem-safe-left, 0px), var(--gem-reserved-tl-width, 0px));
-  right: var(--gem-safe-right, 0px);
+/* your information takes the middle; Back, then settings, at the right end */
+#top-row .info {
+  flex: 1;
+  text-align: center;
 }
 ```
 
 The per-corner properties say how far a corner's rectangles reach, not how much room is left beside
-them. To know whether a row of your own buttons fits beside the Gem, read the rectangles from
-script: the room to the right of the top-left ones is the frame's width less the furthest right
-edge among them.
+them. To know whether your top row fits between the Arcade's controls, read the rectangles from
+script: the room is what lies between the top rectangles on the left and those on the right.
 
 ```js
-const reserved = gem.viewport?.reserved ?? [];
-const topLeft = reserved.filter((r) => r.x + r.width / 2 < window.innerWidth / 2);
-const from = topLeft.length ? Math.max(...topLeft.map((r) => r.x + r.width)) : 0;
-nav.classList.toggle('below-arcade-row', window.innerWidth - from < nav.offsetWidth + 8);
+const w = window.innerWidth;
+const top = (gem.viewport?.reserved ?? []).filter((r) => r.y === 0);
+const isLeft = (r) => r.x + r.width / 2 < w / 2;
+const from = Math.max(0, ...top.filter(isLeft).map((r) => r.x + r.width));
+const to = Math.min(w, ...top.filter((r) => !isLeft(r)).map((r) => r.x));
+row.classList.toggle('below-arcade-row', to - from < row.scrollWidth + 8);
 ```
 
 All eight properties are written on every push, `0px` for a clear corner, so a rotation never leaves
@@ -791,8 +823,39 @@ a stale value; they are never set under an embedder that sends no viewport, whic
 fallback is for. `gem.viewport.reserved` is `[]` when nothing is covered.
 
 **Lay out against it whenever it changes.** The Gem button's rectangle is there for the whole
-session, and it moves with a rotation, a resize or the frame-rate readout. Read every corner, not
-only the one this page names today: a layout that honours all four is right under any embedder.
+session, and it moves with a rotation, a resize, the frame-rate readout and a change of corner. Read
+every corner, not only the one you asked for: a layout that honours all four is right under any
+embedder.
+
+### Moving the Gem: `gem.setGemCorner`
+
+**Leave the Gem top-left unless your own HUD needs that corner.** If it does, ask for another:
+
+```js
+// This game's minimap needs the top-left, so the Gem goes bottom-left.
+gem.setGemCorner('bottom-left'); // 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'
+```
+
+- **One corner per game**, at most one per orientation (one in portrait, another in landscape).
+  Call it once at boot, and again on a rotation if the two differ. A Gem that moves from screen to
+  screen is a way out the player has to look for.
+- **In landscape the bottom corners are where a player's thumbs hold the sticks.** Ask for one only
+  if your controls do not live there.
+- **Lay out around the reserved rectangles you receive, never around the corner you asked for.**
+  The Arcade moves the Gem on its own terms: not while the player is using it or its menu is open,
+  no more often than every few seconds, and a corner the player chooses for themselves, should the
+  Arcade ever offer that, wins over yours. The rectangles — and the `--gem-reserved-*` properties —
+  say where the Gem is now; a game that reads them is right whatever the Arcade decided, and a game
+  that assumed its corner is not.
+- **The top row does not change.** Back and settings stay top-right and information top-centre,
+  wherever the Gem goes ([the top of the screen](#the-top-of-the-screen)).
+- **It is screen state, not a toggle**: each call is the whole answer, held before the Arcade
+  connects and sent again after any reconnect. A value that is not one of the four corners is
+  ignored, with a warning on the console.
+
+`gem.setGemCorner` returns `true` when the Arcade was told, and `false` before it connects and
+under an embedder that cannot move its Gem. On `false` the Gem stays where the embedder puts it,
+and the rectangles say where that is: there is nothing else to do.
 
 **Older SDKs get it folded into the top inset.** A game on an SDK from before reserved areas cannot
 read the rectangles, so the arcade sends it none and instead raises `insets.top` — and so
@@ -900,8 +963,8 @@ This is the whole model, and every other page that mentions settings links here:
   them from `gem.prefs.recommended` (and `muted` and `reducedMotion` from `gem.prefs`) and applies
   them again on `onPrefs`. The Arcade never asks your game anything about them, and never shows
   anything your game says.
-- **Every game draws its own settings button, top-right, and its own settings screen.** The
-  Arcade's menu never opens it.
+- **Every game draws its own settings button, top-right ([the top of the
+  screen](#the-top-of-the-screen)), and its own settings screen.** The Arcade's menu never opens it.
 - **A setting starts from `recommended` until the player changes it in your game, and then the
   player's choice in your game wins.** Save only what the player chose, never a recommended value.
 - **Where a choice is kept.** Device configuration — volume, graphics quality, look sensitivity, a
@@ -914,17 +977,15 @@ This is the whole model, and every other page that mentions settings links here:
   while `gem.vibration.available` ([vibration](vibration.md)).
 
 **The button goes in the top-right corner**, the same corner in every game, so a player never has
-to look for it. Place it with the reserved-area properties so it never sits under an Arcade
-control, whatever the Arcade keeps in that corner on this device:
+to look for it, with your Back button just to its left when a screen has one. Place it with the
+reserved-area properties so it never sits under an Arcade control: if the Gem is in that corner, the
+button sits level with it, just inside it.
 
 ```css
 #settings-button {
   position: absolute;
-  top: max(
-    var(--gem-safe-top, env(safe-area-inset-top, 0px)),
-    var(--gem-reserved-tr-height, 0px)
-  );
-  right: var(--gem-safe-right, 0px);
+  top: var(--gem-safe-top, env(safe-area-inset-top, 0px));
+  right: max(var(--gem-safe-right, 0px), var(--gem-reserved-tr-width, 0px));
 }
 ```
 
@@ -1143,7 +1204,8 @@ What it does, so you know what to expect:
 
 ## The Arcade's menu
 
-The Arcade keeps one button over every game, on every device: the Gem, at the top-left. Its menu is
+The Arcade keeps one button over every game, on every device: the Gem, top-left unless your game
+[asks for another corner](#moving-the-gem-gemsetgemcorner). Its menu is
 how a player leaves (**Return to the Arcade**), sees their Gems, Tickets and achievement score, mutes,
 goes fullscreen, reports a problem and changes their Arcade-wide settings — the ones that reach you as [`gem.prefs.recommended`](#game-settings). You can add up to
 four entries of your own:
@@ -1175,9 +1237,9 @@ gem.setMenu({
 settings button is there either way; what such a game also needs is a way out of its own, a control
 that calls `gem.exit()`.
 
-Your own **back or home** button — the one that moves around inside your game — goes **top-left**,
-which the Arcade [leaves clear](#the-arcades-own-controls-reserved-areas). It never leaves the game:
-leaving is the Arcade's menu, so a player always knows which control does which.
+Your own **back or home** button — the one that moves around inside your game — goes **top-right,
+just left of your settings button** ([the top of the screen](#the-top-of-the-screen)). It never
+leaves the game: leaving is the Arcade's menu, so a player always knows which control does which.
 
 ## Sound: your own mute control, and the Arcade's
 
@@ -1267,8 +1329,8 @@ belong to the Arcade. **Your game never draws one**, and never shows a pending s
 Arcade takes every figure from the platform and shows them itself.
 
 **The Gem Arcade draws no wallet over your game** (since 2026-10-11). Nothing of it sits in your top
-row, at rest or when a balance moves. The player opens the Gem menu — the Gem button at the
-top-left — to see their Gems, Tickets and achievement score, and every payout
+row, at rest or when a balance moves. The player opens the Gem menu — the Gem button, in whichever
+corner it sits — to see their Gems, Tickets and achievement score, and every payout
 [`gem.cueReward`](inventory-and-catalogs.md#showing-the-reward-land-in-the-arcades-wallet) announces
 flies into the Gem button. A payout you do not cue flies too, from the middle of your frame, so cue
 the ones the player earns on screen and the flight starts where they are looking.
@@ -1611,20 +1673,14 @@ running entirely in the browser cannot offer competition, and read
 [its safety rule](async-opponents.md#7-draw-a-set-at-match-start) before you render anything a
 drawn record carries, because those strings were typed by another player.
 
-## A break in play, if you want one to be worth something
-
-Not on the list above either, and a game that never asks is never interrupted. If yours wants a
-break to carry a promotion for another game on the Arcade, `gem.ads.requestAd` asks for one and the
-Arcade draws it in its own chrome over your paused game.
+## A rewarded button, if your game has a reward to offer for an ad
 
-Three things before you reach for it: the answer is **usually no**, and no is the ordinary path
-rather than a failure; nothing rejects, so there is no error branch to write; and `shown` grants
-nothing, so a reward must never be handed out on the strength of it.
-[`cross-promotion.md`](cross-promotion.md) is the page.
+Not on the list above either: a game with no rewarded button is complete without one. (A platform
+moment at every break is on it — [§6 above](#6-a-platform-moment-at-every-break).)
 
-A button the player presses for a reward — a revive, an extra attempt — is the same call with
-`format: 'rewarded'`, made from that press itself. The button says it is an ad and names the
-reward, and the Arcade starts the ad as soon as the ask arrives. Your game config declares what
+A button the player presses for a reward — a revive, an extra attempt — is
+`gem.ads.requestAd({ placement, format: 'rewarded' })`, made from that press itself. The button
+says it is an ad and names the reward, and the Arcade starts the ad as soon as the ask arrives. 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indiegems/gem-web-sdk",
-  "version": "13.0.0",
+  "version": "13.2.0",
   "description": "postMessage bridge contract between gem-web and browser-playable games",
   "license": "UNLICENSED",
   "type": "module",
@@ -40,7 +40,9 @@
       "import": "./dist/gem-web-sdk.quality.js"
     },
     "./schema": "./schema/bridge.v1.json",
-    "./brand/*": "./brand/*"
+    "./schema/moment-log-line.json": "./schema/moment-log-line.json",
+    "./brand/*": "./brand/*",
+    "./rigs/*": "./rigs/*"
   },
   "files": [
     "bin",
@@ -49,7 +51,9 @@
     "!dist/gem-web-sdk.devtools.min.js",
     "schema/bridge.v1.json",
     "schema/capabilities.public.json",
+    "schema/moment-log-line.json",
     "brand/*.png",
+    "rigs/*.glb",
     "docs/*.md",
     "docs/manifest.json",
     "docs/api/*.md",

package/schema/bridge.v1.json

@@ -684,9 +684,9 @@
           "optional": true,
           "$comment": [
             "Every 3D character the player WEARS, one per RIG FAMILY (gem-api",
-            "`avatars_3d`). A family is a rig contract —",
-            "`small_human` is the first — and a player wears at most one character",
-            "per family, so a game that accepts several families reads the one it",
+            "`avatars_3d`). A family is a rig contract — `small_human` and",
+            "`adult_human` today — and a player wears at most one character per",
+            "family, so a game that accepts several families reads the one it",
             "draws by `family`.",
             "",
             "THE FLAT FIELDS STAY, AND THEY ARE ONE OF THESE. `avatar3dId`,",
@@ -720,7 +720,7 @@
               "family": {
                 "kind": "string",
                 "maxLength": 32,
-                "$comment": "The rig family (gem-api `family`), e.g. `small_human`. A lowercase code, checked by the frame rather than by a format here, so one family name this frame does not recognise costs the entry and never the message."
+                "$comment": "The rig family (gem-api `family`), e.g. `small_human` or `adult_human`. A lowercase code, checked by the frame rather than by a format here, so one family name this frame does not recognise costs the entry and never the message."
               },
               "id": {
                 "kind": "string",
@@ -2681,8 +2681,8 @@
         "moved (or is about to move) a progression mapped onto a platform currency,",
         "and the game would like the arcade to show it landing: the currency flying",
         "from `origin` into the arcade's chrome — in the Gem Arcade, into its Gem",
-        "button at the frame's top-left — and the total moving when the platform",
-        "confirms the grant.",
+        "button, in whichever corner of the frame it sits — and the total moving",
+        "when the platform confirms the grant.",
         "",
         "A PRESENTATION CUE, NOT A CLAIM. Nothing here is trusted as a number. The",
         "amount that lands and the player's new total reach the parent from gem-api",
@@ -3008,6 +3008,53 @@
       "rateLimit": { "perMinute": 60 }
     },
 
+    {
+      "type": "gem.gemCorner",
+      "direction": "frameToParent",
+      "transport": "port",
+      "$comment": [
+        "The corner of the frame the game would like the arcade's own control",
+        "over it to sit in - in the Gem Arcade, the Gem button that opens its",
+        "menu. With no message at all it sits top-left, which is also the",
+        "recommendation: a game asks for another corner only when its own HUD",
+        "needs that one.",
+        "",
+        "SCREEN STATE, NOT A TOGGLE, like `gem.menu`. Each message is the whole",
+        "answer and the latest one wins. The SDK holds it from before the bridge",
+        "is up and re-sends it after every handshake, so a parent that reconnects",
+        "puts the control where the game had asked.",
+        "",
+        "A REQUEST, APPLIED ON THE PARENT'S TERMS. The parent holds a move while",
+        "the player is using the control or one of its surfaces is open, keeps a",
+        "minimum dwell between moves and applies only the latest request after",
+        "one, and puts a player's own choice of corner, should it ever offer one,",
+        "above the game's. So a game never lays out around the corner it asked",
+        "for: it lays out around the rectangles `gem.viewport` sends in",
+        "`reserved`, which say where the control actually is.",
+        "",
+        "ONE ENUM, AND IT ONLY GROWS. A later anchor is a new value behind a",
+        "capability of its own, sent only to a parent that advertised that",
+        "capability, so `v` does not move; a parent that advertised only",
+        "`gemCorner` is only ever sent these four.",
+        "",
+        "A PRESENTATION REQUEST ONLY, and not an authorization control. The game",
+        "picks one of four places the parent defines, never a coordinate, a size,",
+        "a visibility or a look; the parent's dwell and holds, not this rate",
+        "limit, are what keep a game from making the control run away.",
+        "",
+        "Gated by `gemCorner`: sent only to a parent that advertised it. To any",
+        "other, `gem.setGemCorner` returns false."
+      ],
+      "fields": {
+        "corner": {
+          "kind": "enum",
+          "values": ["top-left", "top-right", "bottom-left", "bottom-right"],
+          "$comment": "Physical, not logical: `left` is the frame's left edge in every language, so a right-to-left locale never mirrors a game's choice."
+        }
+      },
+      "rateLimit": { "perMinute": 12 }
+    },
+
     {
       "type": "gem.requestShare",
       "direction": "frameToParent",
@@ -3948,7 +3995,7 @@
         "format": {
           "kind": "enum",
           "values": ["interstitial", "rewarded"],
-          "$comment": "A closed set, so a typo is refused at the boundary rather than left for the parent to interpret. `rewarded` IS SERVED WHERE THE PARENT SERVES IT, and answered `no_ad` where it does not. Either way a `shown` grants nothing - see gem.adResult's outcome: the platform grants a rewarded placement's reward itself, into the game's own inventory, against its own record. A game that grants a reward on an outcome has a reward any page that can post on this port can forge."
+          "$comment": "A closed set, so a typo is refused at the boundary rather than left for the parent to interpret. `interstitial` IS DEPRECATED in favour of gem.signalMoment: it keeps working, a parent routes it into the same decision as a platform moment and records it as a legacy one, and 14.0.0 is the earliest SDK release that may stop sending it. `rewarded` IS SERVED WHERE THE PARENT SERVES IT, and answered `no_ad` where it does not. Either way a `shown` grants nothing - see gem.adResult's outcome: the platform grants a rewarded placement's reward itself, into the game's own inventory, against its own record. A game that grants a reward on an outcome has a reward any page that can post on this port can forge."
         }
       },
       "rateLimit": {
@@ -4046,6 +4093,112 @@
       },
       "rateLimit": { "perMinute": 12 }
     },
+    {
+      "type": "gem.signalMoment",
+      "direction": "frameToParent",
+      "transport": "port",
+      "$comment": [
+        "The game has reached a natural break in play - a level, a run or a match",
+        "has ended, or the player is going back to a menu - and is leaving it.",
+        "Gated by the `moments` capability.",
+        "",
+        "A SIGNAL, NOT AN ASK FOR ANYTHING. The parent decides, in its own",
+        "server-side arbiter, whether to show one of ITS OWN offers over the paused",
+        "game at this break - a break video, the app, a platform store offer, a",
+        "subscription, another game - and almost always decides to show nothing.",
+        "The game never names what it would like shown, and never routes its own",
+        "offer through this: its own shop and its own rewarded buttons are its own",
+        "business, on its own cadence, in its own UI.",
+        "",
+        "IT SUPERSEDES `gem.requestAd` WITH `format: 'interstitial'`, which keeps",
+        "working through the N-1 window. A parent routes both into the same",
+        "decision and holds ONE single-flight shared by both message types,",
+        "because a hostile frame can post both at once.",
+        "",
+        "WHAT THE PARENT OWES, none of which this schema can enforce. Everything",
+        "gem.requestAd's comment says of an interstitial holds here word for word:",
+        "advertise `moments` as a deployment-wide fact; render in your own chrome",
+        "over the game paused with `gem.pause`; answer every signal exactly once;",
+        "settle every `shown: false` on a schedule that does not depend on which",
+        "branch produced it; and treat every field as untrusted text. Two more:",
+        "",
+        "  `kind` IS A LABEL AND DECIDES NOTHING OF VALUE. It is for analytics,",
+        "  the dev-host log and the release checklist. A frame-to-parent field is",
+        "  routing only (DESIGN.md section 9), so anything that matters - a",
+        "  multiplayer rule, say - is derived from the parent's own state, never",
+        "  from what the game says the break was. Re-validate it yourself: the",
+        "  frame posts on the port directly.",
+        "",
+        "  REFUSE RATHER THAN QUEUE. A signal that arrives while the player has",
+        "  something of the parent's open, or while the parent itself has paused",
+        "  the game, is answered `shown: false`, through the same floor as every",
+        "  other no. It is never held to paint after the player closes something.",
+        "",
+        "THE `perMinute` BELOW BOUNDS A BUGGY GAME, NOT A HOSTILE ONE, for the",
+        "reason gem.requestAd's gives. The SDK also refuses a second signal within",
+        "10 s of the last answer and one before `gem.ready`, which is the sender",
+        "keeping a promise, not a guarantee a parent holds."
+      ],
+      "fields": {
+        "requestId": {
+          "kind": "string",
+          "maxLength": 64,
+          "$comment": "Opaque and frame-chosen, and echo-only, exactly as gem.requestAd's. Never keyed on, and not safe to log unescaped."
+        },
+        "kind": {
+          "kind": "enum",
+          "values": ["level_end", "run_end", "match_end", "menu_return", "other_break"],
+          "$comment": "Which break this is. CLOSED NOW, AND PINNED BY A TEST ON THE SDK SIDE: a new value on a frame-to-parent enum is breaking under DESIGN.md section 9, because an N-1 parent's generated validator refuses the whole message. `level_end` - a level, stage, wave or puzzle finished, won or lost. `run_end` - game over, death, or a run banked. `match_end` - a multiplayer round or match finished and the player is leaving its results. `menu_return` - the player chose to go back to the title, a main menu or level select; a return, never the first arrival. `other_break` - any other natural stop, defined by exclusion. A LABEL ONLY: it never decides anything of value on the platform."
+        },
+        "placement": {
+          "kind": "string",
+          "maxLength": 32,
+          "optional": true,
+          "$comment": "The game's own name for the screen it is leaving - 'world-1-3', 'results'. UNTRUSTED TEXT. Shown ONLY in a development host's log, so a reviewer can map moments to screens. NEVER FORWARDED TO THE PLATFORM, NEVER STORED, NEVER RENDERED TO A PLAYER AND NEVER SENT TO AN AD NETWORK: a game-authored string that fits this grammar fits a dashless UUID too. The SDK sends only `^[a-z0-9_-]{1,32}$`; codegen emits type and length only, so the charset is the sender's to keep and the receiver's to re-check."
+        }
+      },
+      "rateLimit": {
+        "perMinute": 6,
+        "$comment": "As gem.requestAd's: bounds a BUGGY game, not a hostile one. Breaks in play come minutes apart; six a minute is generous for them and mean for a loop."
+      }
+    },
+    {
+      "type": "gem.momentResult",
+      "direction": "parentToFrame",
+      "transport": "port",
+      "$comment": [
+        "The answer to one gem.signalMoment. Gated by the `moments` capability.",
+        "",
+        "ONE BOOLEAN, AND NO REASON. `shown: true` - the parent painted something",
+        "of its own over the paused game and it has closed. `shown: false` -",
+        "nothing was painted, which is the ordinary answer. Either way the game",
+        "carries on exactly as it would have; `shown` GRANTS NOTHING and tells the",
+        "game nothing about what was shown or why nothing was.",
+        "",
+        "NO REASON, EVER, for the reason gem.adResult carries none: a `false`",
+        "absorbs the feature being off, pacing, a new player's grace, an",
+        "entitlement, an age and a consent state, and a reason naming any of them",
+        "hands untrusted game code a fact about a person. The boolean is permanent",
+        "for the same reason the ad pair's three values are.",
+        "",
+        "THE VALUE IS NOT THE WHOLE CHANNEL. As gem.adResult's comment says, a",
+        "parent settles every `shown: false` on a schedule that does not depend on",
+        "which branch produced it. `shown: true` is not delayed: its latency is a",
+        "player reading a panel."
+      ],
+      "fields": {
+        "requestId": {
+          "kind": "string",
+          "maxLength": 64,
+          "$comment": "Echoes the gem.signalMoment that asked. Echo-only."
+        },
+        "shown": {
+          "kind": "boolean",
+          "$comment": "Whether the parent painted anything at this break. It grants nothing, and a game never branches anything of value on it."
+        }
+      },
+      "rateLimit": { "perMinute": 12 }
+    },
     {
       "type": "gem.requestSignIn",
       "direction": "frameToParent",

package/schema/capabilities.public.json

@@ -236,6 +236,22 @@
       "gates": [
         "gem.controlsDeclare"
       ]
+    },
+    "gemCorner": {
+      "implemented": true,
+      "gates": [
+        "gem.gemCorner"
+      ]
+    },
+    "moments": {
+      "implemented": true,
+      "gates": [
+        "gem.signalMoment",
+        "gem.momentResult",
+        {
+          "namespace": "gem.moments"
+        }
+      ]
     }
   }
 }