@indiegems/gem-web-sdk 13.1.0 → 13.2.1

package/docs/api/reference.json

@@ -2,7 +2,7 @@
   "schema_version": 2,
   "source": {
     "repo": "IndieGems/gem-web-sdk",
-    "version": "13.1.0"
+    "version": "13.2.1"
   },
   "entries": [
     {
@@ -53,9 +53,13 @@
           "key": "deviceSettings",
           "title": "Settings kept on this device"
         },
+        {
+          "key": "moments",
+          "title": "Platform moments"
+        },
         {
           "key": "ads",
-          "title": "Cross-promotion"
+          "title": "Rewarded ads, and the deprecated interstitial"
         },
         {
           "key": "account",
@@ -382,7 +386,7 @@
           "defaultValue": null,
           "guides": [
             {
-              "slug": "cross-promotion",
+              "slug": "rewarded-ads",
               "anchor": null
             }
           ]
@@ -3767,7 +3771,7 @@
           "group": "ads",
           "signature": "type AdFormat = \"interstitial\" | \"rewarded\"",
           "documented": true,
-          "summary": "Which kind of break this is.\n\n`interstitial` is a panel the player dismisses and nothing follows from.\n\n`rewarded` is a button the player pressed for a reward, such as a revive or\nan extra attempt, that your game config declares for the placement in\n`rewarded_placements`. The press is the player's opt-in, and the arcade\nstarts the ad straight away, so ask from the button's own handler (see\n[AdsApi.requestAd](api-reference-game.md#adsapi-requestad)). It is served where this arcade serves it, and\nanswered `no_ad` where it does not. ⚠️ The outcome grants nothing: the\nplatform grants the reward, against its own record, never your game reading\n`shown`. It arrives on your game's inventory for this player, written by the\nplatform, so re-read `gem.me.inventory` after a `rewarded` ask settles rather\nthan waiting for a signal on this pair; there will not be one.",
+          "summary": "Which kind of break this is.\n\n`interstitial` is a panel the player dismisses and nothing follows from.\n**Deprecated:** signal a platform moment with `gem.moments.signal` instead.\nIt keeps working — the arcade treats it as a platform moment — and `14.0.0`\nis the earliest release that may remove it (`docs/deprecation-policy.md`).\n\n`rewarded` is a button the player pressed for a reward, such as a revive or\nan extra attempt, that your game config declares for the placement in\n`rewarded_placements`. The press is the player's opt-in, and the arcade\nstarts the ad straight away, so ask from the button's own handler (see\n[AdsApi.requestAd](api-reference-game.md#adsapi-requestad)). It is served where this arcade serves it, and\nanswered `no_ad` where it does not. ⚠️ The outcome grants nothing: the\nplatform grants the reward, against its own record, never your game reading\n`shown`. It arrives on your game's inventory for this player, written by the\nplatform, so re-read `gem.me.inventory` after a `rewarded` ask settles rather\nthan waiting for a signal on this pair; there will not be one.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -3884,7 +3888,7 @@
           "group": "ads",
           "signature": "interface AdsApi",
           "documented": true,
-          "summary": "The cross-promotion surface. `gem.ads` is one of these.",
+          "summary": "Rewarded ads, and the deprecated interstitial ask. `gem.ads` is one of these.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -3900,7 +3904,7 @@
           "group": "ads",
           "signature": "requestAd(req: AdRequest): Promise<AdOutcome>",
           "documented": true,
-          "summary": "Ask whether the arcade has anything to show at this break in play.\n\nNOTHING REJECTS, and the answer is usually `no_ad`. Every local refusal —\nan arcade that does not do this at all, a call while another is still in\nflight, a `placement` this module will not send — resolves `no_ad` rather\nthan throwing, so a game needs exactly one branch. Only \"no answer ever\narrived\" resolves `unavailable`.\n\nThe arcade pauses your game while a panel is up and resumes it when this\nsettles, so you do not need to pause anything yourself.\n\n⚠️ `shown` grants nothing. Never hand out a reward, an unlock or a currency\non the strength of it. A `rewarded` placement's reward is granted by the\nplatform into your game's inventory; re-read `gem.me.inventory` once this\nsettles, whatever it settled as.\n\n**A `rewarded` ask must come from the player's press.** The press is the\nplayer's opt-in, and the arcade starts the ad as soon as the ask arrives.\nCall this from your button's `click`, `pointerup`, `touchend` or `keydown`\nhandler, before anything that can outlast the press, such as a slow\n`await` or a timer. **Not from `pointerdown` or `touchstart`:** on a\ntouchscreen they run before the browser counts the tap, so the ask is\nrefused on a phone while the same code works at a desk with a mouse. A\ncontroller press counts when the ask follows it within a second, so ask\nfrom the frame of your input loop that saw the button go down. Where the\nbrowser reports user activation (`navigator.userActivation`), the frame\nholds none, and no controller was used in the last second, this answers\n`no_ad` without asking. It also calls your `onError` handler with\ncode `'internal'` and a message that begins\n`rewarded_requires_user_gesture`, and writes one `[gem]` line a session\nthrough your `log`. Where the browser has no such API, the ask goes ahead.\nAn `interstitial` needs no press.",
+          "summary": "Ask whether the arcade has anything to show at this break in play.\n\n**For a break in play, signal a platform moment with\n`gem.moments.signal` instead: `format: 'interstitial'` is deprecated.** It\nkeeps working until at least `14.0.0`. A `rewarded` ask is unchanged.\n\nNOTHING REJECTS, and the answer is usually `no_ad`. Every local refusal —\nan arcade that does not do this at all, a call while another is still in\nflight, a `placement` this module will not send — resolves `no_ad` rather\nthan throwing, so a game needs exactly one branch. Only \"no answer ever\narrived\" resolves `unavailable`.\n\nThe arcade pauses your game while a panel is up and resumes it when this\nsettles, so you do not need to pause anything yourself.\n\n⚠️ `shown` grants nothing. Never hand out a reward, an unlock or a currency\non the strength of it. A `rewarded` placement's reward is granted by the\nplatform into your game's inventory; re-read `gem.me.inventory` once this\nsettles, whatever it settled as.\n\n**A `rewarded` ask must come from the player's press.** The press is the\nplayer's opt-in, and the arcade starts the ad as soon as the ask arrives.\nCall this from your button's `click`, `pointerup`, `touchend` or `keydown`\nhandler, before anything that can outlast the press, such as a slow\n`await` or a timer. **Not from `pointerdown` or `touchstart`:** on a\ntouchscreen they run before the browser counts the tap, so the ask is\nrefused on a phone while the same code works at a desk with a mouse. A\ncontroller press counts when the ask follows it within a second, so ask\nfrom the frame of your input loop that saw the button go down. Where the\nbrowser reports user activation (`navigator.userActivation`), the frame\nholds none, and no controller was used in the last second, this answers\n`no_ad` without asking. It also calls your `onError` handler with\ncode `'internal'` and a message that begins\n`rewarded_requires_user_gesture`, and writes one `[gem]` line a session\nthrough your `log`. Where the browser has no such API, the ask goes ahead.\nAn `interstitial` needs no press.",
           "deprecated": null,
           "params": [
             {
@@ -3912,7 +3916,7 @@
           ],
           "returns": "The arcade's answer. Always resolves; never rejects.",
           "throws": null,
-          "example": "```ts\nconst { outcome } = await gem.ads.requestAd({\n  placement: 'level-complete',\n  format: 'interstitial',\n});\n// `no_ad` is the ordinary answer. There is nothing to show and nothing\n// to draw; carry straight on to the next level.\nstartNextLevel();\n```\n\n```ts\n// A rewarded ask, from the button's own click: the ask comes first, and\n// the inventory read comes after it.\nwatchAdButton.addEventListener('click', async () => {\n  watchAdButton.disabled = true; // only between the press and the answer\n  await gem.ads.requestAd({ placement: 'dice_rolls', format: 'rewarded' });\n  gem.me.inventory.refresh();\n  try {\n    showDice(await gem.me.inventory.snapshot());\n  } finally {\n    watchAdButton.disabled = false;\n  }\n});\n```",
+          "example": "```ts\n// A rewarded ask, from the button's own click: the ask comes first, and\n// the inventory read comes after it.\nwatchAdButton.addEventListener('click', async () => {\n  watchAdButton.disabled = true; // only between the press and the answer\n  await gem.ads.requestAd({ placement: 'dice_rolls', format: 'rewarded' });\n  gem.me.inventory.refresh();\n  try {\n    showDice(await gem.me.inventory.snapshot());\n  } finally {\n    watchAdButton.disabled = false;\n  }\n});\n```",
           "defaultValue": null,
           "guides": []
         },
@@ -3939,7 +3943,7 @@
           "defaultValue": null,
           "guides": [
             {
-              "slug": "cross-promotion",
+              "slug": "rewarded-ads",
               "anchor": null
             }
           ]
@@ -4319,7 +4323,7 @@
           "group": "analytics",
           "signature": "class AnalyticsApi",
           "documented": true,
-          "summary": "Your game's own analytics — the events you declared in your game config,\nplus the `gem_*` session and match events the SDK emits for you.\n\nReached as `gem.analytics`. [AnalyticsApi.track](api-reference-game.md#analyticsapi-track) is synchronous, never\nthrows and never rejects: it puts an event on an in-memory queue, and the\nSDK posts that queue on its own timer, when it reaches 50 events, and on the\nway out of the page.\n\n```js\ngem.analytics.setContext({ build: 'v1.4.2' });\n\ngem.analytics.track('level_completed', {\n  outcome: 'win',        // a dimension — a declared, closed set\n  difficulty: 'normal',  // a dimension\n  duration_ms: 48_120,   // a measure — summed, averaged, min and max\n  score: 3_100,          // a measure\n});\n```\n\n⚠️ **Every key has to be declared.** `analytics_events` in your game config\nis what says which events exist, which dimensions each has and which values\neach dimension may take. An undeclared name or key is not stored — it comes\nback as a rejection, which the SDK prints to the console during development.\n\n⚠️ **Detail older than 30 days is gone.** Raw events live 30 days; the daily\ncounters live 400. Anything you want to be able to ask about a year from now\nhas to be a declared dimension today.\n\n⚠️ **These are your numbers, not the platform's.** Client events are\ngame-asserted browser facts. They feed your analytics and nothing the\nplatform treats as authoritative — not rewards, not dailies, not store\nranking.",
+          "summary": "Your game's own analytics — the events you declared in your game config,\nplus the `gem_*` session and match events the SDK emits for you.\n\nReached as `gem.analytics`. [AnalyticsApi.track](api-reference-game.md#analyticsapi-track) is synchronous, never\nthrows and never rejects: it puts an event on an in-memory queue, and the\nSDK posts that queue on its own timer, when it reaches 50 events, and on the\nway out of the page.\n\n```js\ngem.analytics.setContext({ build: 'v1.4.2' });\n\ngem.analytics.track('level_completed', {\n  outcome: 'win',        // a dimension — a declared, closed set\n  difficulty: 'normal',  // a dimension\n  duration_ms: 48_120,   // a measure — summed, averaged, min and max\n  score: 3_100,          // a measure\n});\n```\n\n⚠️ **Every key has to be declared.** `analytics_events` in your game config\nis what says which events exist, which dimensions each has and which values\neach dimension may take. An undeclared name or key is not stored — it comes\nback as a rejection, which the SDK prints to the console during development.\n\n⚠️ **Detail older than 60 days is gone.** Raw events live 60 days; the daily\ncounters live 400. Anything you want to be able to ask about a year from now\nhas to be a declared dimension today.\n\n⚠️ **These are your numbers, not the platform's.** Client events are\ngame-asserted browser facts. They feed your analytics and nothing the\nplatform treats as authoritative — not rewards, not dailies, not store\nranking.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -4408,7 +4412,7 @@
           "group": "analytics",
           "signature": "flush(options?: AnalyticsFlushOptions): Promise<AnalyticsFlushResult>",
           "documented": true,
-          "summary": "Send what is queued now, and find out what happened to it.\n\nResolves with the platform's own answer, INCLUDING per-event rejections, which\narrive inside a 200 — see [AnalyticsFlushResult.rejected](api-reference-game.md#analyticsflushresult-rejected). You do\nnot have to call this: the SDK flushes on its own, and on the way out of\nthe page.\n\nA refusal that could clear on its own — a 429 from the rate limiter, a 503\nwhile the platform's idempotency store is unreachable — KEEPS the queue\nand rejects, so the next flush sends the same events rather than losing\nthem. A refusal that cannot clear discards the batch it was sent for,\nbecause resending it can only fail identically.",
+          "summary": "Send what is queued now, and find out what happened to it.\n\nResolves with the platform's own answer, INCLUDING per-event rejections, which\narrive inside a 200 — see [AnalyticsFlushResult.rejected](api-reference-game.md#analyticsflushresult-rejected). You do\nnot have to call this: the SDK flushes on its own, and on the way out of\nthe page.\n\nA refusal that could clear on its own — a 429 from the rate limiter, a 503\nwhile the platform's idempotency store is unreachable — KEEPS the queue\nand rejects, so the next flush sends the same events rather than losing\nthem. The SDK's own flushes then hold off for the longer of the server's\n`Retry-After` and a cooldown that doubles from 10 seconds, up to five\nminutes. A refusal that cannot clear discards the batch it was sent for,\nbecause resending it can only fail identically.\n\nOne flush at a time: called while another is still on the wire, this\nresolves at once with nothing sent, and what is queued goes out after it.",
           "deprecated": null,
           "params": [
             {
@@ -8338,7 +8342,7 @@
           "group": "start",
           "signature": "ARCADE_EMBEDDERS: readonly string[]",
           "documented": true,
-          "summary": "The origins the platform embeds a game from, which every game accepts\nwithout naming them: the Gem Arcade website, the Meme Games website, and\nthe Gem Arcade app.\n\nYou do not pass these. They are always allowed, and\n[GemOptions.allowedEmbedders](api-reference-game.md#gemoptions-allowedembedders) adds to them rather than replacing them.",
+          "summary": "The origins the Gem Arcade embeds a game from, which every game accepts\nwithout naming them: the website, and the Gem Arcade app.\n\nYou do not pass these. They are always allowed, and\n[GemOptions.allowedEmbedders](api-reference-game.md#gemoptions-allowedembedders) adds to them rather than replacing them.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -8370,7 +8374,7 @@
           "group": "start",
           "signature": "readonly allowedEmbedders?: readonly string[]",
           "documented": true,
-          "summary": "Extra origins allowed to embed your game, **added to** the ones the Gem\nArcade uses. Most games leave this out.\n\nThe platform's websites and the Gem Arcade app are always allowed — see\n[ARCADE_EMBEDDERS](api-reference-game.md#arcade_embedders) — so do not list them. Set this only when a site\nof your own embeds your game.\n\n```js\ncreateGem({ allowedEmbedders: ['https://my-own-site.example'] })\n```\n\nA page whose origin is not allowed gets no connection, and — deliberately —\nis told nothing about why. That means a typo here looks exactly like a\nhandshake that has not arrived: pass [GemOptions.onRefused](api-reference-game.md#gemoptions-onrefused) while you\nare integrating, because it is the only place the difference shows.\n\n⚠️ **Bake these in. Never build them from anything the page can\ninfluence** — not `location`, not a query parameter, not\n`document.referrer`. A value the embedder supplies is a check that can never\nfail. Do not add a `localhost:<port>` entry for your dev host either; the\nSDK admits one on your own machine by rule.",
+          "summary": "Extra origins allowed to embed your game, **added to** the ones the Gem\nArcade uses. Most games leave this out.\n\nThe website and the Gem Arcade app are always allowed — see\n[ARCADE_EMBEDDERS](api-reference-game.md#arcade_embedders) — so do not list them. Set this only when a site\nof your own embeds your game.\n\n```js\ncreateGem({ allowedEmbedders: ['https://my-own-site.example'] })\n```\n\nA page whose origin is not allowed gets no connection, and — deliberately —\nis told nothing about why. That means a typo here looks exactly like a\nhandshake that has not arrived: pass [GemOptions.onRefused](api-reference-game.md#gemoptions-onrefused) while you\nare integrating, because it is the only place the difference shows.\n\n⚠️ **Bake these in. Never build them from anything the page can\ninfluence** — not `location`, not a query parameter, not\n`document.referrer`. A value the embedder supplies is a check that can never\nfail. Do not add a `localhost:<port>` entry for your dev host either; the\nSDK admits one on your own machine by rule.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -10107,6 +10111,27 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "Gem.moments",
+          "name": "moments",
+          "anchor": "gem-moments",
+          "group": "start",
+          "signature": "readonly moments: MomentsApi",
+          "documented": true,
+          "summary": "Platform moments — **every game, at every break.** Signal one from the\nplayer's press that leaves a natural break in play (Next, Retry, Back to\nmenu), and the arcade may show one of its own offers over your paused\ngame. It usually shows nothing.\n\nRequired by the release checklist at every important break, whether or\nnot your game has a shop of its own. Never resolves a reason, never\nrejects, and `shown` grants nothing.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": [
+            {
+              "slug": "platform-moments",
+              "anchor": null
+            }
+          ]
+        },
         {
           "id": "Gem.ads",
           "name": "ads",
@@ -10114,7 +10139,7 @@
           "group": "start",
           "signature": "readonly ads: AdsApi",
           "documented": true,
-          "summary": "One full-screen cross-promotion at a natural break in play, rendered by\nthe arcade over your paused game.\n\nAsk at a break the player already expects — a level ending, a round\nfinishing — never mid-input. **The answer is usually no, and that is\nordinary rather than a failure:** carry straight on, and draw no\nplaceholder while you wait.\n\nNothing here rejects. The arcade pauses your game while a panel is up and\nresumes it when the promise settles, so you do not pause anything yourself.\n\n⚠️ `shown` **grants nothing.** It is not a receipt and not an entitlement,\nand a reward must never be handed out on the strength of it.\n\nYou are told no reason for a no, and there is nothing to infer from one\nabout the player. What you can read is your own economy:\n`rewardedStatus(placement)` says whether a rewarded placement could pay\nright now under your own declared caps — never whether an ad will play.",
+          "summary": "Rewarded ads, and the deprecated interstitial ask.\n\n**`format: 'interstitial'` is deprecated: signal a platform moment with\n`gem.moments.signal` instead.** It keeps working until at least `14.0.0`\n(`docs/deprecation-policy.md`); the arcade treats it as a platform moment.\n\nA rewarded ask comes from the player's press on your own button. **The\nanswer is usually no, and that is ordinary rather than a failure:** carry\nstraight on, and draw no placeholder while you wait.\n\nNothing here rejects. The arcade pauses your game while a panel is up and\nresumes it when the promise settles, so you do not pause anything yourself.\n\n⚠️ `shown` **grants nothing.** It is not a receipt and not an entitlement,\nand a reward must never be handed out on the strength of it.\n\nYou are told no reason for a no, and there is nothing to infer from one\nabout the player. What you can read is your own economy:\n`rewardedStatus(placement)` says whether a rewarded placement could pay\nright now under your own declared caps — never whether an ad will play.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -10123,7 +10148,7 @@
           "defaultValue": null,
           "guides": [
             {
-              "slug": "cross-promotion",
+              "slug": "rewarded-ads",
               "anchor": null
             }
           ]
@@ -12122,6 +12147,151 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "MomentKind",
+          "name": "MomentKind",
+          "anchor": "momentkind",
+          "group": "moments",
+          "signature": "type MomentKind = \"level_end\" | \"run_end\" | \"match_end\" | \"menu_return\" | \"other_break\"",
+          "documented": true,
+          "summary": "Which kind of break a platform moment is. A closed set — there will not be a\nsixth:\n\n- `level_end` — a level, stage, wave or puzzle finished, won or lost.\n- `run_end` — game over, death, or a run banked, in an endless, arcade or\n  roguelike game.\n- `match_end` — a multiplayer round or match finished and the player is\n  leaving its results.\n- `menu_return` — the player chose to go back to the title, a main menu or\n  level select. A return, never the first arrival.\n- `other_break` — any other natural stop: a story chapter, a between-waves\n  shop.\n\nIt is a label, for the arcade's analytics, the dev host's log and the release\nchecklist. It never changes what the arcade decides for your game.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": [
+            {
+              "slug": "platform-moments",
+              "anchor": null
+            }
+          ]
+        },
+        {
+          "id": "MomentSignal",
+          "name": "MomentSignal",
+          "anchor": "momentsignal",
+          "group": "moments",
+          "signature": "interface MomentSignal",
+          "documented": true,
+          "summary": "A platform moment: which kind of break the player is leaving, and optionally\nyour own name for the screen.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "MomentSignal.kind",
+          "name": "kind",
+          "anchor": "momentsignal-kind",
+          "group": "moments",
+          "signature": "kind: MomentKind",
+          "documented": true,
+          "summary": "Which kind of break this is. Required.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "MomentSignal.placement",
+          "name": "placement",
+          "anchor": "momentsignal-placement",
+          "group": "moments",
+          "signature": "placement?: string",
+          "documented": true,
+          "summary": "Optional: your own name for the screen the player is leaving —\n`world-1-3`, `results`. **1 to 32 characters of `a-z`, `0-9`, `-` and\n`_`.** It appears only in the dev host's log, so a reviewer can map each\nmoment to a screen. It is never sent to the platform, never stored, never\nshown to a player and never sent to an ad network.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "MomentResult",
+          "name": "MomentResult",
+          "anchor": "momentresult",
+          "group": "moments",
+          "signature": "interface MomentResult",
+          "documented": true,
+          "summary": "What the arcade answers at a platform moment.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "MomentResult.shown",
+          "name": "shown",
+          "anchor": "momentresult-shown",
+          "group": "moments",
+          "signature": "readonly shown: boolean",
+          "documented": true,
+          "summary": "Whether the arcade showed anything of its own at this break. Usually\n`false`. Either way, carry on exactly as you would have. **It grants\nnothing**, and it never says what was shown or why nothing was.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "MomentsApi",
+          "name": "MomentsApi",
+          "anchor": "momentsapi",
+          "group": "moments",
+          "signature": "interface MomentsApi",
+          "documented": true,
+          "summary": "Platform moments. `gem.moments` is one of these.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "MomentsApi.signal",
+          "name": "signal",
+          "anchor": "momentsapi-signal",
+          "group": "moments",
+          "signature": "signal(moment: MomentSignal): Promise<MomentResult>",
+          "documented": true,
+          "summary": "Signal a platform moment: the player is leaving a natural break in play.\nThe arcade may show one of its own offers over your paused game, and\nusually shows nothing.\n\n**Call it from the player's press that LEAVES the break** — Next, Retry,\nBack to menu — once per break. Start your own transition in parallel, and\nstart play when this settles. **Never** mid-input, during a timed\nsequence, on a timer, on boot or the first arrival at the title, or from a\nplayer-opened pause menu (choosing Quit to menu from it is a\n`menu_return`). No press is required by the SDK; the rule is about when a\nbreak really is one.\n\nNOTHING REJECTS. It resolves `{ shown: false }` without asking for an\narcade that does not do platform moments, a `kind` or `placement` outside\nthe grammar, a call before `gem.frame.ready()`, a call while another is in\nflight, a call within 10 seconds of the last answer, or no answer within\nthree minutes — and each of those, except an arcade that does not do it\n(said once a session), is reported to your `onError` handler with code\n`'internal'` and a message beginning with a stable token:\n`moments_unsupported`, `moments_invalid_argument`, `moments_before_ready`,\n`moments_in_flight`, `moments_called_repeatedly` or `moments_timeout`.\n\nThe arcade pauses and resumes your game through the ordinary\n`gem.pause`, so you do not pause anything yourself.\n\n⚠️ `shown` grants nothing. Never hand out a reward, an unlock or a currency\non it, and never pop your own offer at a break that settled `shown: true`.",
+          "deprecated": null,
+          "params": [
+            {
+              "name": "moment",
+              "type": "MomentSignal",
+              "optional": false,
+              "summary": "Which kind of break, and optionally your name for the screen."
+            }
+          ],
+          "returns": "Whether the arcade showed anything. Always resolves; never rejects.",
+          "throws": null,
+          "example": "```ts\n// From the press that LEAVES the break — Next, Retry, Back to menu.\nasync function onNextPressed() {\n  startLevelTransition(); // your fade or loading beat, in parallel\n  await gem.moments.signal({ kind: 'level_end', placement: 'world-1-3' });\n  startNextLevel(); // settled either way; never grant anything on `shown`\n}\n```",
+          "defaultValue": null,
+          "guides": [
+            {
+              "slug": "platform-moments",
+              "anchor": null
+            }
+          ]
+        },
         {
           "id": "DedicatedServerFailure",
           "name": "DedicatedServerFailure",
@@ -21802,6 +21972,22 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "RequestOptions.retryRateLimited",
+          "name": "retryRateLimited",
+          "anchor": "requestoptions-retryratelimited",
+          "group": "calls",
+          "signature": "readonly retryRateLimited?: boolean",
+          "documented": true,
+          "summary": "Set `false` to make a 429 final for this call instead of waiting out\n`Retry-After` and trying again.\n\nFor a caller that keeps its own queue and its own cooldown, such as a\nbatch sender on a timer: retrying inside the call only spends more of the\nsame limit, and holds the caller's queue while it does. Every other\nfailure is retried exactly as before. Defaults to `true`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "VersionedGetOptions",
           "name": "VersionedGetOptions",
@@ -23984,7 +24170,7 @@
           "group": "analytics",
           "signature": "flush(signal?: AbortSignal): Promise<AnalyticsFlushResult>",
           "documented": true,
-          "summary": "Send what is queued now, and find out what happened to it.\n\nResolves with the platform's own answer, INCLUDING per-event rejections, which\narrive inside a 200 rather than as an error. A refusal that could clear on\nits own — a 429, a 503 — keeps the queue and rejects; one that cannot\ndiscards the batch, because resending it can only fail the same way.",
+          "summary": "Send what is queued now, and find out what happened to it.\n\nResolves with the platform's own answer, INCLUDING per-event rejections, which\narrive inside a 200 rather than as an error. A refusal that could clear on\nits own — a 429, a 503 — keeps the queue and rejects, and the SDK's own\nflushes then hold off for the longer of the server's `Retry-After` and a\ncooldown that doubles from 10 seconds, up to five minutes; one that cannot\ndiscards the batch, because resending it can only fail the same way.\n\nOne flush at a time: called while another is on the wire, this waits for\nit and then sends what is left.",
           "deprecated": null,
           "params": [
             {
@@ -26539,7 +26725,7 @@
       "usageRoots": [
         "GemFunction"
       ],
-      "install": "A function imports the same package your game already depends on, written out in [getting-started](../getting-started.md#3-add-the-sdk) — the only place the install is written out. Your function’s build bundles this module, so the version your function runs is the one your `package.json` names: pin the version your game pins. A function published importing the SDK from the engine runs the engine’s built-in copy instead; [serverless-functions-js](../serverless-functions-js.md) says what that means.",
+      "install": "⚠️ **JavaScript functions are disabled for now, due to performance issues.** Uploading a new JavaScript function is refused with `400 js_functions_disabled`: write a new function in Rust, as [serverless-functions](../serverless-functions.md#3-writing-one) shows. A JavaScript function already published keeps running, and this page is what it imports.\n\nA function imports the same package your game already depends on, written out in [getting-started](../getting-started.md#3-add-the-sdk) — the only place the install is written out. Your function’s build bundles this module, so the version your function runs is the one your `package.json` names: pin the version your game pins. A function published importing the SDK from the engine runs the engine’s built-in copy instead; [serverless-functions-js](../serverless-functions-js.md) says what that means.",
       "entrySymbol": "createGem",
       "groups": [
         {
@@ -26859,7 +27045,7 @@
           "group": "analytics",
           "signature": "class AnalyticsApi",
           "documented": true,
-          "summary": "Your game's own analytics — the events you declared in your game config,\nplus the `gem_*` session and match events the SDK emits for you.\n\nReached as `gem.analytics`. [AnalyticsApi.track](api-reference-function.md#analyticsapi-track) is synchronous, never\nthrows and never rejects: it puts an event on an in-memory queue, and the\nSDK posts that queue on its own timer, when it reaches 50 events, and on the\nway out of the page.\n\n```js\ngem.analytics.setContext({ build: 'v1.4.2' });\n\ngem.analytics.track('level_completed', {\n  outcome: 'win',        // a dimension — a declared, closed set\n  difficulty: 'normal',  // a dimension\n  duration_ms: 48_120,   // a measure — summed, averaged, min and max\n  score: 3_100,          // a measure\n});\n```\n\n⚠️ **Every key has to be declared.** `analytics_events` in your game config\nis what says which events exist, which dimensions each has and which values\neach dimension may take. An undeclared name or key is not stored — it comes\nback as a rejection, which the SDK prints to the console during development.\n\n⚠️ **Detail older than 30 days is gone.** Raw events live 30 days; the daily\ncounters live 400. Anything you want to be able to ask about a year from now\nhas to be a declared dimension today.\n\n⚠️ **These are your numbers, not the platform's.** Client events are\ngame-asserted browser facts. They feed your analytics and nothing the\nplatform treats as authoritative — not rewards, not dailies, not store\nranking.",
+          "summary": "Your game's own analytics — the events you declared in your game config,\nplus the `gem_*` session and match events the SDK emits for you.\n\nReached as `gem.analytics`. [AnalyticsApi.track](api-reference-function.md#analyticsapi-track) is synchronous, never\nthrows and never rejects: it puts an event on an in-memory queue, and the\nSDK posts that queue on its own timer, when it reaches 50 events, and on the\nway out of the page.\n\n```js\ngem.analytics.setContext({ build: 'v1.4.2' });\n\ngem.analytics.track('level_completed', {\n  outcome: 'win',        // a dimension — a declared, closed set\n  difficulty: 'normal',  // a dimension\n  duration_ms: 48_120,   // a measure — summed, averaged, min and max\n  score: 3_100,          // a measure\n});\n```\n\n⚠️ **Every key has to be declared.** `analytics_events` in your game config\nis what says which events exist, which dimensions each has and which values\neach dimension may take. An undeclared name or key is not stored — it comes\nback as a rejection, which the SDK prints to the console during development.\n\n⚠️ **Detail older than 60 days is gone.** Raw events live 60 days; the daily\ncounters live 400. Anything you want to be able to ask about a year from now\nhas to be a declared dimension today.\n\n⚠️ **These are your numbers, not the platform's.** Client events are\ngame-asserted browser facts. They feed your analytics and nothing the\nplatform treats as authoritative — not rewards, not dailies, not store\nranking.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -26948,7 +27134,7 @@
           "group": "analytics",
           "signature": "flush(options?: AnalyticsFlushOptions): Promise<AnalyticsFlushResult>",
           "documented": true,
-          "summary": "Send what is queued now, and find out what happened to it.\n\nResolves with the platform's own answer, INCLUDING per-event rejections, which\narrive inside a 200 — see [AnalyticsFlushResult.rejected](api-reference-function.md#analyticsflushresult-rejected). You do\nnot have to call this: the SDK flushes on its own, and on the way out of\nthe page.\n\nA refusal that could clear on its own — a 429 from the rate limiter, a 503\nwhile the platform's idempotency store is unreachable — KEEPS the queue\nand rejects, so the next flush sends the same events rather than losing\nthem. A refusal that cannot clear discards the batch it was sent for,\nbecause resending it can only fail identically.",
+          "summary": "Send what is queued now, and find out what happened to it.\n\nResolves with the platform's own answer, INCLUDING per-event rejections, which\narrive inside a 200 — see [AnalyticsFlushResult.rejected](api-reference-function.md#analyticsflushresult-rejected). You do\nnot have to call this: the SDK flushes on its own, and on the way out of\nthe page.\n\nA refusal that could clear on its own — a 429 from the rate limiter, a 503\nwhile the platform's idempotency store is unreachable — KEEPS the queue\nand rejects, so the next flush sends the same events rather than losing\nthem. The SDK's own flushes then hold off for the longer of the server's\n`Retry-After` and a cooldown that doubles from 10 seconds, up to five\nminutes. A refusal that cannot clear discards the batch it was sent for,\nbecause resending it can only fail identically.\n\nOne flush at a time: called while another is still on the wire, this\nresolves at once with nothing sent, and what is queued goes out after it.",
           "deprecated": null,
           "params": [
             {
@@ -27252,6 +27438,22 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "RequestOptions.retryRateLimited",
+          "name": "retryRateLimited",
+          "anchor": "requestoptions-retryratelimited",
+          "group": "calls",
+          "signature": "readonly retryRateLimited?: boolean",
+          "documented": true,
+          "summary": "Set `false` to make a 429 final for this call instead of waiting out\n`Retry-After` and trying again.\n\nFor a caller that keeps its own queue and its own cooldown, such as a\nbatch sender on a timer: retrying inside the call only spends more of the\nsame limit, and holds the caller's queue while it does. Every other\nfailure is retried exactly as before. Defaults to `true`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "VersionedGetOptions",
           "name": "VersionedGetOptions",

package/docs/changelog.md

@@ -16,6 +16,28 @@ Its entries are grouped under up to five headings:
 - **Rebuild**: a type changed. Recompile against the new version; code that compiles today keeps compiling unless the entry says otherwise.
 - **New capability**: something a game can now do. Nothing changes unless you use it.
 
+## 13.2.1
+
+Upgrading from 13.2.0. Impact: none.
+
+Nothing in this release asks anything of a game.
+
+## 13.2.0
+
+Upgrading from 13.1.0. Impact: required.
+
+### Rebuild
+
+- The message-type lists and unions between game and Arcade gained the moment request and moment result messages, and the capability type gained moments. Recompiling is enough. If your code switches exhaustively over frame messages, parent messages or capabilities, add handling for the new members so it still compiles.
+
+### New capability
+
+- A game can now signal a platform moment at a natural break through Gem.moments. You pass one of a fixed set of moment kinds and an optional placement, and the answer says whether a moment was shown. The call never rejects. If the SDK refuses locally, for example because the host does not support moments, the argument is invalid, ready has not been called, a request is already in flight, or the call was repeated or timed out, the answer is not shown. Check the moments capability before relying on it. Rate limits and the settle time are the same as for ad requests.
+- On the frame side, GemFrame gains signalMoment for sending a moment request to the Arcade, and readyCalled so you can tell whether ready has been reported yet. Signalling before ready is refused. Frame options and callbacks gain onMomentResult to receive the answer.
+- If you build a host that embeds games, for example a development host, you can now receive moment requests through onSignalMoment in the host options and callbacks, and answer them with answerMoment. The new moment request and result message types come with validators for incoming messages.
+- The package now ships a JSON schema describing the log line that development hosts write for moments. Use it if your tooling reads or checks those log lines.
+- Request options gain retryRateLimited, which defaults to true so existing behaviour is unchanged. Set it to false on a call if you want a rate-limit response handed straight back instead of being retried by the transport. Other failures are still retried. This applies in the browser SDK and the server package.
+
 ## 13.1.0
 
 Upgrading from 13.0.0. Impact: required.

package/docs/deprecation-policy.md

@@ -99,12 +99,18 @@ deprecated.
 | `MatchHosting.stop` | `MatchHosting.end` when the match is over, `MatchHosting.leave` to hand it to another host | `5.0.0` | Package API surface |
 | `GemPlayer.displayHandle` | `PlayerIdentity.displayTag` — the same value | `7.0.0` | Package API surface |
 | `GemPlayer.avatarUrl` | `PlayerIdentity.avatarIconUrl` — the same value | `7.0.0` | Package API surface |
+| `AdRequest.format: 'interstitial'` | `gem.moments.signal` — a platform moment at the same break, from the press that leaves it | `14.0.0` | Package API surface |
 | `profile(playerId)` | The room read's per-member display identity | Not a package release | Runtime delivery only |
 
 **"For the member" is the split from section 3**, and it is the row's real answer: `4.0.0` is
 the earliest release that may take the property off the type, and it says nothing about when a
 server stops putting a value in it.
 
+**The interstitial row is one value of a field, not a whole symbol.** `format: 'rewarded'` is
+not deprecated, so the reference cannot mark `AdRequest.format` itself; the notice is in the
+field's description and in [`platform-moments.md`](platform-moments.md#12-moving-off-format-interstitial).
+It is still package surface, and section 2 governs it unchanged.
+
 The last row is the one that is only a guide's. `profile(playerId)` is marked deprecated in
 [`server-bundles.md`](server-bundles.md) and carries no mark in the generated reference, so
 there is no package release to name for it and section 3 is its whole rule.

package/docs/getting-started.md

@@ -50,7 +50,7 @@ either way.
 ```jsonc
 // package.json
 "dependencies": {
-  "@indiegems/gem-web-sdk": "13.1.0"
+  "@indiegems/gem-web-sdk": "13.2.1"
 }
 ```
 
@@ -67,9 +67,12 @@ is involved, and nothing is built when you install.
 dedicated server bundle and a listen host all import the same path and the same names.
 `.`, `/game` and `/server` stay published as narrow doors over the same modules — a game
 wants none of them unless it knows why. `/function` is the fourth door, for code that runs as
-a serverless function ([serverless-functions-js.md](serverless-functions-js.md)). The function
-starter's build resolves `/sdk` and `/game` to it, so verification code shared with your game
-keeps its import.
+a serverless function written in JavaScript
+([serverless-functions-js.md](serverless-functions-js.md)). JavaScript functions are disabled
+for now, due to performance issues: write a new function in Rust
+([serverless-functions.md](serverless-functions.md)). A JavaScript function already published
+keeps running, and its build resolves `/sdk` and `/game` to `/function`, so verification code
+shared with your game keeps its import.
 
 **`dependencies`, not `devDependencies`.** The SDK is part of what your game ships — your
 bundler compiles it into the browser build and into the server bundle — so a `--production`

package/docs/manifest.json

@@ -13,8 +13,8 @@
     },
     {
       "file": "analytics.md",
-      "sha256": "57fb07c3d649c2758a35660707d31b05164b363e9a425156978aed394d086339",
-      "updated": "2026-10-02T14:04:37Z"
+      "sha256": "06bc70771dec1fe04451b93f1c55643759edb389927227fae67f246e0b147af6",
+      "updated": "2026-10-15T00:02:19Z"
     },
     {
       "file": "arcade-avatars.md",
@@ -38,13 +38,8 @@
     },
     {
       "file": "changelog.md",
-      "sha256": "3041e5a29aec35ed4a1d299410d9a0795a7c48958f314a6497ca2b567ccaf000",
-      "updated": "2026-10-14T22:00:06Z"
-    },
-    {
-      "file": "cross-promotion.md",
-      "sha256": "92d4a1ffe19ceaaae1812bfdb77ebbdc04a7eca878ff28995eb6c388c7e876b3",
-      "updated": "2026-10-08T16:19:25Z"
+      "sha256": "474618b1fbfa9d43ae4cb797019f6c799e1ad2de9fad8fa66875f428c7fe599d",
+      "updated": "2026-10-15T15:43:44Z"
     },
     {
       "file": "daily-challenges.md",
@@ -58,8 +53,8 @@
     },
     {
       "file": "deprecation-policy.md",
-      "sha256": "2923c4af22f266bb545e0218efb3ffb3c7cc7184ea538e431b6b87352c6b9e51",
-      "updated": "2026-09-24T16:41:50Z"
+      "sha256": "8134d5463e2737116ed23341bf177c51cede4bd86dabec54d76a82c5bfdfade1",
+      "updated": "2026-10-14T22:38:02Z"
     },
     {
       "file": "friends.md",
@@ -73,8 +68,8 @@
     },
     {
       "file": "getting-started.md",
-      "sha256": "651392ad1b3bb28bd43cfb0a0df0a88b3d8c2e46a4bbb1cb9fcbbe762459f22e",
-      "updated": "2026-10-14T22:00:06Z"
+      "sha256": "b3617f6056165a881a786f331a809f200d79ed8151d06cb26acba544a9c3dde9",
+      "updated": "2026-10-15T15:43:44Z"
     },
     {
       "file": "inventory-and-catalogs.md",
@@ -96,6 +91,11 @@
       "sha256": "3887bc706d098014cefab84e9b8bd5b964841888c242a7ccb1f799a9b9723fc0",
       "updated": "2026-09-24T01:00:22Z"
     },
+    {
+      "file": "platform-moments.md",
+      "sha256": "c9909452a49fe50bac2266e56e5a44ad6495b8464ce1b5c889d0be39604bbff0",
+      "updated": "2026-10-14T22:43:26Z"
+    },
     {
       "file": "platform-rules.md",
       "sha256": "b259bcebc6ae12b1db9c7279a6e2adb174af9d60090bf31001e23616f6423fbf",
@@ -108,8 +108,8 @@
     },
     {
       "file": "rewarded-ads.md",
-      "sha256": "f1f88f7d3aab2b1a1df2cecab59846625907e0391542291f1fbba56ea98d6476",
-      "updated": "2026-10-08T16:19:25Z"
+      "sha256": "ab1096ca610b8f009f0aeb17c573a17fbd2ce6567963285f7b2f73c072170dc2",
+      "updated": "2026-10-14T22:38:02Z"
     },
     {
       "file": "room-shapes.md",
@@ -128,18 +128,18 @@
     },
     {
       "file": "server-bundles.md",
-      "sha256": "c83325c8471f0ea2578f3476660751ad7f4fd96a51eb902336e57d7553ec5e46",
-      "updated": "2026-10-14T22:00:06Z"
+      "sha256": "3ec75df469f44b3f299c45e237fabc74ede5a42444a14f0b35e068198109558d",
+      "updated": "2026-10-15T15:43:44Z"
     },
     {
       "file": "serverless-functions-js.md",
-      "sha256": "3904704418f9c6c246c8e1fa83f96901f6e493a3f4499b16fd6845620515e57d",
-      "updated": "2026-10-12T17:39:05Z"
+      "sha256": "0436dafdc5dcb036d45073ea9c9d4cbebdb5880decc7db8012e04c3b2cfc1016",
+      "updated": "2026-10-14T23:28:53Z"
     },
     {
       "file": "serverless-functions.md",
-      "sha256": "84881bcc40c6203c731ebf9092be575158d0ad3b3a65120321b695ae6558f63f",
-      "updated": "2026-10-12T17:39:05Z"
+      "sha256": "eef5fa14dced0bca39b4f4b9d6688d4f81d6c4d2441ec3497380c21b7482022a",
+      "updated": "2026-10-15T14:37:57Z"
     },
     {
       "file": "trading-and-gifting.md",
@@ -153,8 +153,8 @@
     },
     {
       "file": "what-a-game-must-do.md",
-      "sha256": "7006e2e2900d71417002937d51a8d10ad9bcfdf02cd1b27f0f923e4cbe4ee79b",
-      "updated": "2026-10-14T21:18:16Z"
+      "sha256": "439683ca206b2230e48ab46d5eb9a945964fb6f2e308ffcc8ec1e1b9423fc5e8",
+      "updated": "2026-10-15T13:34:34Z"
     }
   ]
 }