@indiegems/gem-web-sdk 13.1.0 → 13.2.0

package/docs/platform-moments.md

@@ -0,0 +1,266 @@
+# Platform moments
+
+At every natural break in play — a level ending, a run over, a match's results, a return to the
+menu — your game signals a **platform moment**. The Arcade then decides, on its own servers,
+whether to show one of **its own** offers over your paused game: a break video, the Arcade app, a
+platform store offer, a subscription, another game. Usually it shows nothing.
+
+```js
+// From the press that LEAVES the break — Next, Retry, Back to menu.
+async function onNextPressed() {
+  startLevelTransition(); // your fade or loading beat, in parallel
+  const { shown } = await gem.moments.signal({ kind: 'level_end' });
+  startNextLevel(); // settled either way; never grant anything on `shown`
+}
+```
+
+**Every game signals a moment at every break**, whether or not it has a shop of its own. The
+release checklist requires it (§11). That is the whole surface; the rest of this page is where to
+put the call, where never to, and the few things a game gets wrong when nobody tells it.
+
+- [1. A platform moment is not your own offer](#1-a-platform-moment-is-not-your-own-offer)
+- [2. The five kinds](#2-the-five-kinds)
+- [3. Where to call it, and where never to](#3-where-to-call-it-and-where-never-to)
+- [4. The answer is usually `false`, and false is ordinary](#4-the-answer-is-usually-false-and-false-is-ordinary)
+- [5. Nothing rejects](#5-nothing-rejects)
+- [6. `shown` grants nothing](#6-shown-grants-nothing)
+- [7. The Arcade pauses your game for you](#7-the-arcade-pauses-your-game-for-you)
+- [8. Multiplayer](#8-multiplayer)
+- [9. What never crosses](#9-what-never-crosses)
+- [10. Testing it in the dev host](#10-testing-it-in-the-dev-host)
+- [11. The release requirement](#11-the-release-requirement)
+- [12. Moving off `format: 'interstitial'`](#12-moving-off-format-interstitial)
+
+## 1. A platform moment is not your own offer
+
+Two kinds of upsell can happen in a game, and they never mix.
+
+|                     | **Platform moment** (this page)                                                                                 | **Your game's own offer**                                     |
+| ------------------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
+| Who decides         | the Arcade, on its servers                                                                                      | your game                                                     |
+| What it shows       | platform things only: break videos, the Arcade app, platform store offers, subscriptions, other games          | your own items, currencies and rewarded buttons               |
+| When                | only at a moment your game signals, paced by the platform                                                       | whenever your game likes, on its own cadence                  |
+| Drawn by            | the Arcade's own chrome, over your paused game                                                                  | your game's own UI                                            |
+| What your game learns | `shown: true` or `false`, nothing else                                                                        | everything — it is yours                                      |
+
+Three rules follow from it:
+
+- **A platform moment never shows your game's own items, and your game never routes its own offer
+  through one.** Your shop, your special offers and your rewarded buttons
+  ([`rewarded-ads.md`](rewarded-ads.md)) stay yours, in your UI, on your schedule.
+- **Signal every natural break, whether or not your game has a shop of its own.** The moment is
+  about the break, not about what your game sells.
+- **No stacking.** When a moment settles `shown: true`, do not also pop your own offer at that
+  break. Your normal results screen and its shop button are fine; a second popup in the same breath
+  is not.
+
+## 2. The five kinds
+
+`kind` is required, and it is one of five. The set is closed and will not grow: a game written
+today never meets a sixth.
+
+| `kind`        | the break                                                                                     | for example                                                              |
+| ------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| `level_end`   | a level, stage, wave or puzzle finished, won or lost                                          | a platformer's stage clear, a puzzle solved, a tower-defence wave beaten |
+| `run_end`     | game over, death, or a run banked                                                             | an endless runner's crash, a roguelike death, an arcade game's last life |
+| `match_end`   | a multiplayer round or match finished, and the player is leaving its results                  | a battle royale's results, a card game's round, a race's podium          |
+| `menu_return` | the player chose to go back to the title, a main menu or level select — a return, never the first arrival | Back to menu on a results screen, Quit to menu from the pause menu       |
+| `other_break` | any other natural stop                                                                        | the end of a story chapter, a between-waves shop                         |
+
+`kind` is a **label**. The Arcade uses it for its own analytics, the dev host prints it (§10), and
+the release checklist reads it (§11). It never changes what the Arcade decides for your game, so
+there is nothing to gain by choosing one kind over another: pick the one that describes the break.
+
+`placement` is optional: your own name for the screen the player is leaving — `world-1-3`,
+`results`, `pause_quit`. It has the grammar every name you hand the SDK has, **1 to 32 characters of
+`a-z`, `0-9`, `-` and `_`**, and it appears in exactly one place: the dev host's log, so a reviewer
+can map each moment to a screen. It is never sent to the platform, never stored, never shown to a
+player and never sent to an ad network.
+
+```js
+await gem.moments.signal({ kind: 'run_end', placement: 'desert-run' });
+```
+
+## 3. Where to call it, and where never to
+
+**From the player's press that leaves the break** — Next, Retry, Continue, Back to menu. The
+results screen stays fully interactive until then: the player reads their score, looks at the
+leaderboard, opens your shop. When they press to leave, your game starts its own transition (a fade,
+a loading beat) and signals at the same moment, in parallel, and starts play when the promise
+settles. Usually nothing was shown and the answer arrives inside your transition, so the player
+never sees a wait.
+
+Once per break. A break with three ways out signals from whichever press the player made, not from
+all three.
+
+**Never:**
+
+- mid-input, or during a timed sequence — a jump, a countdown, a combo;
+- on a timer, or on a schedule of your own;
+- on boot, or on the first arrival at the title screen — a `menu_return` is a **return**;
+- from a pause menu the player opened, just because it opened — choosing **Quit to menu** from it
+  **is** a `menu_return`, signalled from that press;
+- more than once at one break.
+
+No press is required by the SDK: the rule is about when a break really is one, not about user
+activation.
+
+## 4. The answer is usually `false`, and false is ordinary
+
+The promise resolves `{ shown }`, one boolean:
+
+| `shown` | what happened                                                    | what your game does                       |
+| ------- | ---------------------------------------------------------------- | ----------------------------------------- |
+| `false` | nothing was shown                                                | carry on exactly as if you had not asked  |
+| `true`  | the Arcade showed something of its own, and it has closed        | carry on — and grant nothing (§6)         |
+
+**`false` is the common answer**, not an edge case. The Arcade paces what it shows, gives a new
+player time before it shows anything, and has nothing suitable more often than not. You are not told
+which, and there is nothing to infer.
+
+- Do **not** render a placeholder, a spinner or a "nothing right now" message.
+- Do **not** hold your game's flow on a fill. Start your transition, signal, and continue when the
+  promise settles.
+- Do **not** retry on a `false`. A second signal at the same break is refused (§5).
+
+## 5. Nothing rejects
+
+`gem.moments.signal` always resolves. There is no error branch and no `try`/`catch` to write. When
+the SDK refuses a signal itself, it resolves `{ shown: false }` without asking the Arcade, and calls
+your `onError` handler with code `'internal'` and a message that **begins with a stable token**, so
+you find the mistake while you build:
+
+| token                       | when                                                                                               |
+| --------------------------- | -------------------------------------------------------------------------------------------------- |
+| `moments_unsupported`       | the page your game runs in does not do platform moments. Keep the call; it costs nothing. Said once a session |
+| `moments_invalid_argument`  | a `kind` outside the five, or a `placement` outside the grammar                                    |
+| `moments_before_ready`      | a signal before `gem.frame.ready()` — play has not started, so there is no break                   |
+| `moments_in_flight`         | a second signal while the first is still waiting for its answer                                    |
+| `moments_called_repeatedly` | a signal within 10 seconds of the last moment's answer — one break signalled twice, or a timer     |
+| `moments_timeout`           | no answer within three minutes                                                                     |
+
+The 10 seconds count from the last **answer**, not the last call, so a long panel does not eat into
+the next level. A refused signal does not restart the count.
+
+Match on the token, not the rest of the message:
+
+```js
+const gem = createGem({
+  onError: (code, message) => {
+    if (message?.startsWith('moments_') && !message.startsWith('moments_unsupported')) {
+      reportBug('platform moment refused', message); // your own telemetry
+    }
+  },
+});
+```
+
+## 6. `shown` grants nothing
+
+`shown: true` says the Arcade showed something of its own and it has closed. It is **not** a
+receipt, **not** an entitlement, and **not** permission to hand anything out. Nothing on this call
+pays the player, and a game that unlocks a level or grants a currency on the strength of it has an
+unlock any page embedding your game can forge.
+
+If your game wants to give the player something for reaching the end of a level, give it to them
+for reaching the end of the level.
+
+## 7. The Arcade pauses your game for you
+
+While the Arcade shows something, your game is paused the same way it is when a player switches
+tabs — the Arcade sends the pause your game already handles, and lifts it when the panel closes.
+You do not pause anything yourself, and you never resume on a timer: resume when the promise
+settles. If you have not wired the pause yet, that is the thing to fix first;
+[`what-a-game-must-do.md`](what-a-game-must-do.md) covers it.
+
+## 8. Multiplayer
+
+Signal `match_end` as the player leaves a match's results, exactly as a single-player game signals
+`level_end`. What the Arcade may show to a player who is still in a live room or a party about to
+start is the Arcade's decision, made from its own knowledge of the room — never from the `kind`
+your game sent — so there is nothing extra for your game to do, and nothing to hold back. The
+Arcade does not keep a player who is about to play waiting on an offer.
+
+## 9. What never crosses
+
+Your game never learns what was shown — no title, no image, no offer, no id. It receives one
+boolean.
+
+You are also never told **why** nothing was shown. That is deliberate and permanent: the reasons
+include pacing, a new player's grace, the player's account, age and consent, and a reason would
+tell your game something about the player that game code is not told. There will not be a second
+field naming one. The Arcade also settles every `false` on a schedule that does not depend on why,
+so there is nothing in the timing to read either. (`true` is not held back — how long that one
+takes is how long your player spent with a panel.)
+
+## 10. Testing it in the dev host
+
+`gemctl serve` and the Gem Editor's dev host answer moments the way the Arcade does, with a TEST
+panel in place of a real offer. (Both dev hosts gain this in their own releases after the SDK that
+ships `gem.moments`. Until yours has it, a moment there answers `false`, and your `onError`
+handler hears `moments_unsupported` once.)
+
+> **Platform moment · level_end · world-1-3**
+> In the Gem Arcade, an offer of the Arcade's own may appear here. Usually nothing does. Your game
+> is paused until this closes.
+> **[Close]**
+
+Add `?moments=` to the dev host's page to choose what it does:
+
+| mode      | what the dev host does                                                                    |
+| --------- | ----------------------------------------------------------------------------------------- |
+| `none`    | shows nothing, and answers `false` after the same short wait the Arcade holds             |
+| `panel`   | shows the TEST panel at every moment                                                      |
+| `paced`   | shows the panel at most once every three minutes, so you see the real frequency          |
+| `video`   | the longest path: a ten-second break video, then its result                               |
+| `delayed` | paints the panel late, to test a player who presses Continue before it arrives            |
+
+Each moment writes **one log line**, in the same form on every dev host:
+
+```text
+moment kind=level_end placement=world-1-3 since_ready_ms=84210 since_prev_ms=61005 answer=not_shown
+```
+
+`since_ready_ms` is how long after `gem.frame.ready()` the moment arrived, `since_prev_ms` how long
+after the previous one (`-` for the first), and `answer` is `shown` or `not_shown`. A
+`placement` you did not give is `-`, and a deprecated interstitial ask is logged on the same line as
+`kind=legacy`. The grammar of the line is published with the SDK, as
+`@indiegems/gem-web-sdk/schema/moment-log-line.json`.
+
+Play through every break in your game once and read the log: every results, game-over and
+back-to-menu screen should have produced a line, with the `kind` you meant, and none should appear
+on boot, mid-level or seconds apart. That log is what the release checklist reads (§11).
+
+## 11. The release requirement
+
+The release checklist requires platform moments, as a platform requirement every game meets:
+
+- **MOM-01 — every natural break signals a platform moment.** The checklist inventories your
+  breaks from your code and from a play-through under `gemctl serve`, and expects a log line for
+  each. A game with no moments at all does not pass; a break with no signal is a finding to fix.
+- **MOM-02 — never at the wrong time.** No signal right after `ready()`, none on a regular
+  interval, none twice at one break, none mid-input and none from opening a pause menu. The log
+  line is how the first three are checked.
+- **MOM-03 — no stacking** (advisory): no popup of your own at a break that settled
+  `shown: true`.
+
+**The platform itself does not enforce any of this.** Publishing never refuses a game for missing
+moments, the Arcade never refuses to run one, and `gemctl`'s doctor warns rather than fails. The
+checklist is where it is required, and it is required there at every important break.
+
+## 12. Moving off `format: 'interstitial'`
+
+`gem.ads.requestAd({ placement, format: 'interstitial' })` is **deprecated**. It still works, and
+the Arcade treats it as a platform moment, but `14.0.0` is the earliest release that may remove it
+([`deprecation-policy.md`](deprecation-policy.md)). Replace it at the same break, and move the call
+to the press that leaves the break if it was made as the results screen opened:
+
+```js
+// Before
+await gem.ads.requestAd({ placement: 'level-complete', format: 'interstitial' });
+
+// After — from the Next press
+await gem.moments.signal({ kind: 'level_end', placement: 'level-complete' });
+```
+
+`format: 'rewarded'` is not deprecated and does not change: a button the player presses for a
+reward is your game's own offer, and [`rewarded-ads.md`](rewarded-ads.md) is its page.

package/docs/rewarded-ads.md

@@ -204,10 +204,11 @@ cannot tell which input caused the ask: a browser counts any tap in your game fo
 and the SDK counts any controller input for one, so an ask from your jump button's handler, or
 from a death a second after a tap, goes through.
 Making the ask only from the button is yours to get right.
-[`cross-promotion.md`](cross-promotion.md#where-to-put-the-call) has the handler.
 
-The answer is one of the same three outcomes every `requestAd` gets — `shown`, `no_ad` or
-`unavailable` — and for `rewarded` none of them says whether a reward was granted. What can happen
+The answer is one of three outcomes — `shown`, `no_ad` or `unavailable`, the last two read
+identically — and it never rejects: even a `placement` outside the grammar resolves `no_ad`, and
+the mistake goes to your `onError` handler. For `rewarded` none of the three says whether a reward
+was granted. What can happen
 after a press:
 
 | what happened                                                                             | was the reward granted?                                                                                                                             |
@@ -230,7 +231,7 @@ player already holds before asking for another (§5's code does both).
 A granted reward shows in your order history like any other change, as an order the platform made
 with `source` `reward`.
 
-**While the ad plays, your game is paused,** the same way it is for an interstitial: the Arcade
+**While the ad plays, your game is paused,** the same way it is at a [platform moment](platform-moments.md): the Arcade
 sends the pause your game already handles and lifts it when the ad closes. Resume when the promise
 settles, not on a timer. A second `requestAd` while one is still in flight resolves `no_ad` at once,
 so disable the button between the press and the answer.
@@ -301,13 +302,28 @@ a cap is spent, a cooldown runs, the player holds `max_held`, or rewarded is off
 drawing on it never offers a press that is certain to pay nothing. Hide or grey the button out
 otherwise, and say when it is back from `nextEligibleAt` or `resetsAt`. `grantable` is not a
 promise: a press can still pay nothing for reasons the read never reports. The status reserves
-nothing, and it never rejects. See [cross-promotion.md](cross-promotion.md):
+nothing, and it never rejects:
 
 ```js
 const status = await gem.ads.rewardedStatus('classic_revive');
 watchAdButton.hidden = !status.grantable;
 ```
 
+| field              | what it says                                                               |
+| ------------------ | -------------------------------------------------------------------------- |
+| `declared`         | the config promoted to the channel being played names this placement       |
+| `grantable`        | pressing the button could pay right now — **not** that an ad will play     |
+| `remainingToday`   | grants left today under the daily cap; absent when the placement has none  |
+| `nextEligibleAt`   | when a running cooldown ends, in epoch milliseconds; absent when none runs |
+| `heldLimitReached` | the player already holds the placement's `max_held` — spend one first      |
+| `resetsAt`         | when today's count resets, the next 00:00 UTC, in epoch milliseconds       |
+
+Without a play token, when the read fails or takes longer than ten seconds, or for a placement
+outside the grammar, it answers not declared and not grantable with no `resetsAt`, and the reason
+goes to your `onError` handler. It is a read of the platform, so call it when you draw the button
+— on a results or death screen — not every frame, and draw the rest of the screen first rather than
+holding it on the answer.
+
 For a revive, the screen reads what it needs **when it opens**, so the press itself can ask at
 once:
 
@@ -437,10 +453,11 @@ platform sets them all. A rewarded reward is your economy, so the caps are yours
 
 ## 7. Pacing
 
-- **A rewarded ask is never held back by an interstitial.** A player who presses your button is not
-  refused because a promotion played a minute ago, in your game or another.
-- **An ad that starts holds off the next interstitial.** Do not follow a rewarded ad with an
-  interstitial at the same break; that ask answers `no_ad`.
+- **A rewarded ask is never held back by a platform moment.** A player who presses your button is
+  not refused because the Arcade showed something a minute ago, in your game or another.
+- **A rewarded ad does not replace the break's platform moment.** Signal the moment from the press
+  that leaves the break as usual ([`platform-moments.md`](platform-moments.md)); whether the Arcade
+  shows anything then is its decision.
 - **Rewarded has its own spacing:** your placement's `cooldown_seconds`, and the platform's 15
   seconds (§6). An ask inside any of them answers `no_ad` with nothing granted, so do not re-ask on
   a timer. Never ask on a timer at all: the ad would start with no press. The SDK refuses a timer's

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/v13.1.0/gem-web-sdk.tgz
-curl -fsSL https://downloads.gemarcade.com/sdk/v13.1.0/gem-web-sdk.tgz.sri
+curl -fsSL -O https://downloads.gemarcade.com/sdk/v13.2.0/gem-web-sdk.tgz
+curl -fsSL https://downloads.gemarcade.com/sdk/v13.2.0/gem-web-sdk.tgz.sri
 openssl dgst -sha384 -binary gem-web-sdk.tgz | openssl base64 -A
 ```
 

package/docs/serverless-functions-js.md

@@ -1,5 +1,16 @@
 # Serverless functions in JavaScript
 
+⚠️ **JavaScript functions are disabled for now, due to performance issues. Write a new function in
+Rust.** A JavaScript function runs many times slower on the platform than the same function built
+from Rust as a WebAssembly component, too slow to fit a call's CPU limit, so uploading a new
+JavaScript function is refused with `400 js_functions_disabled`: "New JavaScript functions are not
+accepted: build the function as a WebAssembly component from Rust (the gem:functions world, target
+wasm32-unknown-unknown) and finalize it with kind `component`. Versions already published as
+JavaScript keep running." [serverless-functions.md](serverless-functions.md#3-writing-one) shows how
+to write one in Rust. A JavaScript function you have already published keeps running: it is still
+listed, you can still promote it to a channel or roll back to it, and players' calls still reach
+it. This page stays for those functions, and for when JavaScript functions come back.
+
 A serverless function can be written in JavaScript or TypeScript instead of Rust: the language your
 game is already written in, so the verification code in your browser game moves into a function
 with no change beyond bundling. You upload one bundled ES module, and the platform runs it on a
@@ -218,7 +229,9 @@ gemctl function check functions/score-check/dist/function.js
 ```
 
 `check` runs the platform's publish-time validation for JavaScript on your machine, and an upload
-runs it first and answers `400 source_invalid` with the same `details.reason`:
+runs it first and answers `400 source_invalid` with the same `details.reason`. While JavaScript
+functions are disabled (the notice at the top of this page), an upload is refused with
+`400 js_functions_disabled` before any of these checks run.
 
 | Reason             | What it usually is                                                                          | What to change                                    |
 | ------------------ | ------------------------------------------------------------------------------------------- | ------------------------------------------------- |
@@ -234,6 +247,9 @@ JavaScript; it does not accept TypeScript, so upload what your build wrote.
 
 ## 5. Publishing
 
+While JavaScript functions are disabled, a new JavaScript version cannot be uploaded; promoting a
+version you already published, and rolling back to one, work as before.
+
 Uploading, promoting, rolling back and channels are the same as for a component
 (serverless-functions.md sections 4 and 5). On the website, the **Functions** tab of your game's
 **Builds** page promotes a version to a channel, rolls back by promoting an earlier one, and shows

package/docs/serverless-functions.md

@@ -55,10 +55,15 @@ possible.
 
 ## 2. What a function is
 
-A function is one WebAssembly **component** or one JavaScript module per game per channel. A
-JavaScript module is written against the SDK instead, and
-[serverless-functions-js.md](serverless-functions-js.md) covers what differs for one. A component
-is built against the platform's `gem:functions` world, and exports exactly one function:
+A function is one WebAssembly **component** per game per channel, built from Rust.
+
+⚠️ **JavaScript functions are disabled for now, due to performance issues. Write your function in
+Rust.** Uploading a new JavaScript function is refused with `400 js_functions_disabled`. A
+JavaScript function you have already published keeps running, and
+[serverless-functions-js.md](serverless-functions-js.md) still covers it.
+
+A component is built against the platform's `gem:functions` world, and exports exactly one
+function:
 
 ```wit
 export handle: func(input: list<u8>) -> result<list<u8>, string>;
@@ -467,9 +472,9 @@ decision point, such as the end of a run or a claim, and never on a timer or onc
 
 ## 3. Writing one
 
-The reference toolchain for a component is Rust; to write a function in JavaScript or TypeScript,
-see [serverless-functions-js.md](serverless-functions-js.md). gemctl writes the starter crate and
-wraps what your build produces, and the build in between is yours:
+A function is written in Rust and built into a component; JavaScript functions are disabled for
+now, due to performance issues (section 2). gemctl writes the starter crate and wraps what your
+build produces, and the build in between is yours:
 
 ```bash
 gemctl function init functions/score-check
@@ -844,6 +849,7 @@ Publishing has its own refusals, and nothing is stored when one happens:
 | What you get                     | What happened                                                                                                                                        | What to do                                               |
 | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
 | `400 component_invalid`          | The backend's check refused the component. `details.reason` is one of the five in section 3, or `sha256_mismatch`, `size_mismatch` or `not_uploaded` | The five: fix and rebuild. The other three: upload again |
+| `400 js_functions_disabled`      | You uploaded a JavaScript function. JavaScript functions are disabled for now, due to performance issues; versions already published as JavaScript keep running | Write it in Rust and upload the component (section 3) |
 | `409 function_version_exists`    | That version string is taken, perhaps by a deleted version not yet purged                                                                            | Choose another version                                   |
 | `409 function_version_in_use`    | You tried to delete a version a channel still serves                                                                                                 | Promote another version there, or unassign it first      |
 | `404 function_version_not_found` | No such version, or it has been deleted                                                                                                              | `gemctl function list --all --include-deleted`           |

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:
@@ -1651,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.1.0",
+  "version": "13.2.0",
   "description": "postMessage bridge contract between gem-web and browser-playable games",
   "license": "UNLICENSED",
   "type": "module",
@@ -40,6 +40,7 @@
       "import": "./dist/gem-web-sdk.quality.js"
     },
     "./schema": "./schema/bridge.v1.json",
+    "./schema/moment-log-line.json": "./schema/moment-log-line.json",
     "./brand/*": "./brand/*",
     "./rigs/*": "./rigs/*"
   },
@@ -50,6 +51,7 @@
     "!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",

package/schema/bridge.v1.json

@@ -3995,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": {
@@ -4093,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",