@indiegems/gem-web-sdk 16.0.1 → 16.2.0

package/docs/api/reference.json

@@ -2,7 +2,7 @@
   "schema_version": 2,
   "source": {
     "repo": "IndieGems/gem-web-sdk",
-    "version": "16.0.1"
+    "version": "16.2.0"
   },
   "entries": [
     {
@@ -2805,7 +2805,7 @@
           "group": "saves",
           "signature": "readonly etag: string",
           "documented": true,
-          "summary": "This save's version, which changes whenever the save does.\n\nNOT something to pass back on a write — a write pins the version it is\nreplacing on its own. This is how a game holding a copy tells whether the\nstored save is still the one it has.",
+          "summary": "This save's version, which changes whenever the save does.\n\nNOT something to pass back on a write — the SDK remembers the version of\neach slot you last loaded or wrote and sends it for you, so a write that\nwould replace a save you never saw is refused as `save_conflict`. This is\nhow a game holding a copy tells whether the stored save is still the one\nit has.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -2936,9 +2936,9 @@
           "name": "reason",
           "anchor": "gemsaveerror-reason",
           "group": "failures",
-          "signature": "readonly reason: \"upload_failed\" | \"download_failed\" | \"save_timeout\" | \"save_malformed\"",
+          "signature": "readonly reason: \"upload_failed\" | \"download_failed\" | \"save_timeout\" | \"save_malformed\" | \"save_conflict\" | \"load_failed\"",
           "documented": true,
-          "summary": "Which part failed.\n\n- `upload_failed` — the bytes could not be written to storage.\n- `download_failed` — the stored bytes could not be fetched.\n- `save_timeout` — a hop did not finish in the time the call allows.\n- `save_malformed` — the answer, or the stored payload, was not what it\n  claims to be.\n\n`save_timeout`, and a one-off `upload_failed` or `download_failed`, are\nworth one retry. `save_malformed` is not: the same bytes will fail the\nsame way.\n\nAn `upload_failed` that repeats on EVERY save, for every player, is not\ntransient either — it is a platform-side misconfiguration, and retrying\nis a loop rather than a recovery. See the saves guide.",
+          "summary": "Which part failed.\n\n- `upload_failed` — the bytes could not be written to storage.\n- `download_failed` — the stored bytes could not be fetched.\n- `save_timeout` — a hop did not finish in the time the call allows.\n- `save_malformed` — the answer, or the stored payload, was not what it\n  claims to be.\n- `save_conflict` — a write was refused because the stored save changed\n  since this game last loaded or wrote it: another device or tab saved\n  in between. Nothing was written.\n- `load_failed` — a write was refused before anything was sent, because\n  the last load of this slot failed, so what the write would replace is\n  unknown — it could be the player's real progress.\n\n`save_timeout`, and a one-off `upload_failed` or `download_failed`, are\nworth one retry. `save_malformed` is not: the same bytes will fail the\nsame way.\n\nNeither is `save_conflict` or `load_failed`: resending the same write\nfails the same way. Load the slot again and decide what to write from\nwhat is stored — merge, or ask the player. Pass `overwrite: true` only to\nreplace whatever is stored on purpose.\n\nAn `upload_failed` that repeats on EVERY save, for every player, is not\ntransient either — it is a platform-side misconfiguration, and retrying\nis a loop rather than a recovery. See the saves guide.\n\nA RATE LIMIT IS NOT ONE OF THESE. Refused for the rate on any leg — the\nplatform, the upload, the download — a save or load rejects as\n`GemApiError` reason `rate_limited`, with `retryAfterSeconds` when a wait\nwas named.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -2991,7 +2991,7 @@
           "group": "saves",
           "signature": "readonly signal?: AbortSignal",
           "documented": true,
-          "summary": "Cancel the write.\n\nA save is several hops, so a cancelled write can land after the platform\nhas already agreed to it. Re-read rather than assuming nothing was stored.",
+          "summary": "Cancel the write.\n\nA save is several hops, so a cancelled write can land after the platform\nhas already agreed to it. Re-read rather than assuming nothing was stored.\n\nA write that replaced earlier ones still waiting on its slot carries them,\nso cancelling it before it goes out cancels them too. Cancelling a write\nthat a later one replaced rejects only this call; the later write goes on.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -3007,7 +3007,39 @@
           "group": "saves",
           "signature": "readonly timeoutMs?: number",
           "documented": true,
-          "summary": "How long this whole save may take, every hop together. Overrides the 30\nsecond default.\n\nSET THIS WHEN YOU ARE RACING A CLOCK YOU DO NOT CONTROL — above all when\nsaving from [GemTerminationNotice](api-reference-game.md#gemterminationnotice), whose `graceMs` can be shorter\nthan the default. Left at the default in that case a save is killed\nmid-flight: the promise never settles, nothing is logged, and the player\nloses progress silently. Set it to the budget you actually have and a save\nthat will not make it rejects as `save_timeout` while there is still time\nto do something about it.\n\nIt does not make a save faster. Three round trips plus the payload is what\na save costs; this only decides when to stop waiting.",
+          "summary": "How long this whole save may take, every hop together. Overrides the 30\nsecond default.\n\nSET THIS WHEN YOU ARE RACING A CLOCK YOU DO NOT CONTROL — above all when\nsaving from [GemTerminationNotice](api-reference-game.md#gemterminationnotice), whose `graceMs` can be shorter\nthan the default. Left at the default in that case a save is killed\nmid-flight: the promise never settles, nothing is logged, and the player\nloses progress silently. Set it to the budget you actually have and a save\nthat will not make it rejects as `save_timeout` while there is still time\nto do something about it.\n\nIt does not make a save faster. Three round trips plus the payload is what\na save costs; this only decides when to stop waiting.\n\nIt counts from the call, so a write waiting for the one before it on the\nsame slot spends it waiting. A rate limit whose wait it will not cover\nrejects at once as `GemApiError` reason `rate_limited`, not as\n`save_timeout`.\n\nIt stays this call's when a later write replaces this one: running out\nrejects only this call, and the later write goes on. The write that is\nsent runs on the newest call's `timeoutMs`, and running out of that rejects\nevery call it carries.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "PutSaveOptions.teardown",
+          "name": "teardown",
+          "anchor": "putsaveoptions-teardown",
+          "group": "saves",
+          "signature": "readonly teardown?: boolean",
+          "documented": true,
+          "summary": "This is the last write before the page goes away: send it without waiting\nfor the spacing between writes to one slot.\n\nWrites to one slot go out a few seconds apart, and a write made sooner\nwaits its turn. Set this on the write you make from\n[GemTerminationNotice](api-reference-game.md#gemterminationnotice) or `pagehide`, with a `timeoutMs` inside the\ntime you have.\n\nIT STILL WAITS FOR A WRITE ALREADY IN FLIGHT to the same slot, and it\nstill honours a rate-limit hold: when the hold outlasts `timeoutMs` the\nwrite rejects at once as `rate_limited`, and nothing is sent. Not for\nordinary saves — the spacing is what keeps a save loop from spending the\nrate limit.\n\nA later write that replaces this one while it waits keeps it: the write\nthat goes out skips the spacing when any call it carries set `teardown`.\nNot across a player change: a call replaced after the signed-in player\nchanged is refused as `save_conflict`, and its `teardown` goes with it.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "PutSaveOptions.overwrite",
+          "name": "overwrite",
+          "anchor": "putsaveoptions-overwrite",
+          "group": "saves",
+          "signature": "readonly overwrite?: boolean",
+          "documented": true,
+          "summary": "Write even if it replaces a save this game has not loaded.\n\nWithout it, a write to a slot whose last load FAILED is refused as\n`load_failed`, and a write is refused as `save_conflict` when the stored\nsave changed since you last loaded or wrote it. Both refusals protect the\nplayer's real progress from a game that started from defaults.\n\nSet it only when replacing whatever is stored is what you mean — a \"new\ngame\" the player confirmed, or the player choosing this device's progress\nafter a conflict. Never set it to get past a failed load.\n\nA later write that replaces this one while it waits keeps it: the write\nthat goes out overwrites when any call it carries set `overwrite`. A call\nthat gives up first (its `signal` or `timeoutMs`) takes it back, and so\ndoes one replaced after the signed-in player changed: it is refused as\n`save_conflict`, so one player's \"new game\" never overwrites the next's.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -3060,7 +3092,7 @@
           "group": "saves",
           "signature": "readonly signal?: AbortSignal",
           "documented": true,
-          "summary": "Cancel the write.\n\nA save is several hops, so a cancelled write can land after the platform\nhas already agreed to it. Re-read rather than assuming nothing was stored.",
+          "summary": "Cancel the write.\n\nA save is several hops, so a cancelled write can land after the platform\nhas already agreed to it. Re-read rather than assuming nothing was stored.\n\nA write that replaced earlier ones still waiting on its slot carries them,\nso cancelling it before it goes out cancels them too. Cancelling a write\nthat a later one replaced rejects only this call; the later write goes on.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -3076,7 +3108,39 @@
           "group": "saves",
           "signature": "readonly timeoutMs?: number",
           "documented": true,
-          "summary": "How long this whole save may take, every hop together. Overrides the 30\nsecond default.\n\nSET THIS WHEN YOU ARE RACING A CLOCK YOU DO NOT CONTROL — above all when\nsaving from [GemTerminationNotice](api-reference-game.md#gemterminationnotice), whose `graceMs` can be shorter\nthan the default. Left at the default in that case a save is killed\nmid-flight: the promise never settles, nothing is logged, and the player\nloses progress silently. Set it to the budget you actually have and a save\nthat will not make it rejects as `save_timeout` while there is still time\nto do something about it.\n\nIt does not make a save faster. Three round trips plus the payload is what\na save costs; this only decides when to stop waiting.",
+          "summary": "How long this whole save may take, every hop together. Overrides the 30\nsecond default.\n\nSET THIS WHEN YOU ARE RACING A CLOCK YOU DO NOT CONTROL — above all when\nsaving from [GemTerminationNotice](api-reference-game.md#gemterminationnotice), whose `graceMs` can be shorter\nthan the default. Left at the default in that case a save is killed\nmid-flight: the promise never settles, nothing is logged, and the player\nloses progress silently. Set it to the budget you actually have and a save\nthat will not make it rejects as `save_timeout` while there is still time\nto do something about it.\n\nIt does not make a save faster. Three round trips plus the payload is what\na save costs; this only decides when to stop waiting.\n\nIt counts from the call, so a write waiting for the one before it on the\nsame slot spends it waiting. A rate limit whose wait it will not cover\nrejects at once as `GemApiError` reason `rate_limited`, not as\n`save_timeout`.\n\nIt stays this call's when a later write replaces this one: running out\nrejects only this call, and the later write goes on. The write that is\nsent runs on the newest call's `timeoutMs`, and running out of that rejects\nevery call it carries.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "PutBytesOptions.teardown",
+          "name": "teardown",
+          "anchor": "putbytesoptions-teardown",
+          "group": "saves",
+          "signature": "readonly teardown?: boolean",
+          "documented": true,
+          "summary": "This is the last write before the page goes away: send it without waiting\nfor the spacing between writes to one slot.\n\nWrites to one slot go out a few seconds apart, and a write made sooner\nwaits its turn. Set this on the write you make from\n[GemTerminationNotice](api-reference-game.md#gemterminationnotice) or `pagehide`, with a `timeoutMs` inside the\ntime you have.\n\nIT STILL WAITS FOR A WRITE ALREADY IN FLIGHT to the same slot, and it\nstill honours a rate-limit hold: when the hold outlasts `timeoutMs` the\nwrite rejects at once as `rate_limited`, and nothing is sent. Not for\nordinary saves — the spacing is what keeps a save loop from spending the\nrate limit.\n\nA later write that replaces this one while it waits keeps it: the write\nthat goes out skips the spacing when any call it carries set `teardown`.\nNot across a player change: a call replaced after the signed-in player\nchanged is refused as `save_conflict`, and its `teardown` goes with it.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "PutBytesOptions.overwrite",
+          "name": "overwrite",
+          "anchor": "putbytesoptions-overwrite",
+          "group": "saves",
+          "signature": "readonly overwrite?: boolean",
+          "documented": true,
+          "summary": "Write even if it replaces a save this game has not loaded.\n\nWithout it, a write to a slot whose last load FAILED is refused as\n`load_failed`, and a write is refused as `save_conflict` when the stored\nsave changed since you last loaded or wrote it. Both refusals protect the\nplayer's real progress from a game that started from defaults.\n\nSet it only when replacing whatever is stored is what you mean — a \"new\ngame\" the player confirmed, or the player choosing this device's progress\nafter a conflict. Never set it to get past a failed load.\n\nA later write that replaces this one while it waits keeps it: the write\nthat goes out overwrites when any call it carries set `overwrite`. A call\nthat gives up first (its `signal` or `timeoutMs`) takes it back, and so\ndoes one replaced after the signed-in player changed: it is refused as\n`save_conflict`, so one player's \"new game\" never overwrites the next's.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -3108,7 +3172,7 @@
           "group": "saves",
           "signature": "class SavesApi",
           "documented": true,
-          "summary": "A player's saved progress — write it, read it, list it, delete it.\n\nReached as `gem.me.saves`, and on a character as\n`gem.characters.get(id).saves`.\n\nA SAVE GOES IN A SLOT YOU DECLARED. Slots live in your game config, published\nwith `gemctl`, next to your room templates. Writing to a slot that was never\ndeclared fails as `not_found` naming the key, on the first call and every\nretry — that is the wall almost everyone hits first, and it is a config\nproblem rather than a code one.\n\n```js\nawait gem.me.saves.put('slot1', { level: 7, checkpoint: 'bridge' });\nconst state = await gem.me.saves.get('slot1');\n```\n\nWHAT IS DELIBERATELY NOT HERE: no autosave timer, no save format, no\nmigration. Those are your game's, and a platform that guessed at them would\nguess wrong.",
+          "summary": "A player's saved progress — write it, read it, list it, delete it.\n\nReached as `gem.me.saves`, and on a character as\n`gem.characters.get(id).saves`.\n\nA SAVE GOES IN A SLOT YOU DECLARED. Slots live in your game config, published\nwith `gemctl`, next to your room templates. Writing to a slot that was never\ndeclared fails as `not_found` naming the key, on the first call and every\nretry — that is the wall almost everyone hits first, and it is a config\nproblem rather than a code one.\n\n```js\nawait gem.me.saves.put('slot1', { level: 7, checkpoint: 'bridge' });\nconst state = await gem.me.saves.get('slot1');\n```\n\nLOAD BEFORE YOU SAVE. Each write carries the version of the slot your last\nload or write found, so a write that would replace a save this game has not\nseen — another device's, or the player's real progress after a load that\nfailed — is refused as `save_conflict` or `load_failed` rather than stored.\nAfter a failed load, play on without saving and load again later; pass\n`overwrite: true` only when the player chose to start over.\n\nONE WRITE PER SLOT AT A TIME. A write made while another to the same slot is\nin flight waits for it, and a later one replaces it: the newest value is the\none sent, and every caller it replaced resolves with it, keeping its own\n`signal`, `timeoutMs`, `teardown` and `overwrite`. Writes to one slot\ngo out a few seconds apart (`teardown: true` skips that), and after a\n`rate_limited` answer none goes out until the wait it named is over.\n\nWHAT IS DELIBERATELY NOT HERE: no autosave timer, no save format, no\nmigration. Those are your game's, and a platform that guessed at them would\nguess wrong.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -14198,6 +14262,22 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "MomentSignal.wall",
+          "name": "wall",
+          "anchor": "momentsignal-wall",
+          "group": "moments",
+          "signature": "wall?: boolean",
+          "documented": true,
+          "summary": "Optional: `true` says your game accepts that the arcade may show its **app\nwall** at this break — a panel that may leave the player no way on in this\nbrowser. Set it only at a break where the player's progress is already\nsaved and stopping there is acceptable. Absent or `false` is an ordinary\nbreak. It is an acceptance, not an ask: the arcade still decides, and\nusually shows nothing. An older arcade ignores it and treats the break as\nordinary.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "MomentResult",
           "name": "MomentResult",
@@ -14253,14 +14333,14 @@
           "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`.",
+          "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\nAdd `wall: true` only at a break where the player's progress is saved and\nyour game accepts that the arcade may show its app wall there.\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 `wall` that is not a boolean, a call before\n`gem.frame.ready()`, a call while another is in flight, a call within 10\nseconds 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."
+              "summary": "Which kind of break, your screen's name, and whether a wall is acceptable."
             }
           ],
           "returns": "Whether the arcade showed anything. Always resolves; never rejects.",
@@ -32505,7 +32585,7 @@
           "group": "player",
           "signature": "readonly etag: string",
           "documented": true,
-          "summary": "This save's version, which changes whenever the save does.\n\nNOT something to pass back on a write — a write pins the version it is\nreplacing on its own. This is how a game holding a copy tells whether the\nstored save is still the one it has.",
+          "summary": "This save's version, which changes whenever the save does.\n\nNOT something to pass back on a write — the SDK remembers the version of\neach slot you last loaded or wrote and sends it for you, so a write that\nwould replace a save you never saw is refused as `save_conflict`. This is\nhow a game holding a copy tells whether the stored save is still the one\nit has.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -32636,9 +32716,9 @@
           "name": "reason",
           "anchor": "gemsaveerror-reason",
           "group": "errors",
-          "signature": "readonly reason: \"upload_failed\" | \"download_failed\" | \"save_timeout\" | \"save_malformed\"",
+          "signature": "readonly reason: \"upload_failed\" | \"download_failed\" | \"save_timeout\" | \"save_malformed\" | \"save_conflict\" | \"load_failed\"",
           "documented": true,
-          "summary": "Which part failed.\n\n- `upload_failed` — the bytes could not be written to storage.\n- `download_failed` — the stored bytes could not be fetched.\n- `save_timeout` — a hop did not finish in the time the call allows.\n- `save_malformed` — the answer, or the stored payload, was not what it\n  claims to be.\n\n`save_timeout`, and a one-off `upload_failed` or `download_failed`, are\nworth one retry. `save_malformed` is not: the same bytes will fail the\nsame way.\n\nAn `upload_failed` that repeats on EVERY save, for every player, is not\ntransient either — it is a platform-side misconfiguration, and retrying\nis a loop rather than a recovery. See the saves guide.",
+          "summary": "Which part failed.\n\n- `upload_failed` — the bytes could not be written to storage.\n- `download_failed` — the stored bytes could not be fetched.\n- `save_timeout` — a hop did not finish in the time the call allows.\n- `save_malformed` — the answer, or the stored payload, was not what it\n  claims to be.\n- `save_conflict` — a write was refused because the stored save changed\n  since this game last loaded or wrote it: another device or tab saved\n  in between. Nothing was written.\n- `load_failed` — a write was refused before anything was sent, because\n  the last load of this slot failed, so what the write would replace is\n  unknown — it could be the player's real progress.\n\n`save_timeout`, and a one-off `upload_failed` or `download_failed`, are\nworth one retry. `save_malformed` is not: the same bytes will fail the\nsame way.\n\nNeither is `save_conflict` or `load_failed`: resending the same write\nfails the same way. Load the slot again and decide what to write from\nwhat is stored — merge, or ask the player. Pass `overwrite: true` only to\nreplace whatever is stored on purpose.\n\nAn `upload_failed` that repeats on EVERY save, for every player, is not\ntransient either — it is a platform-side misconfiguration, and retrying\nis a loop rather than a recovery. See the saves guide.\n\nA RATE LIMIT IS NOT ONE OF THESE. Refused for the rate on any leg — the\nplatform, the upload, the download — a save or load rejects as\n`GemApiError` reason `rate_limited`, with `retryAfterSeconds` when a wait\nwas named.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -32691,7 +32771,7 @@
           "group": "player",
           "signature": "readonly signal?: AbortSignal",
           "documented": true,
-          "summary": "Cancel the write.\n\nA save is several hops, so a cancelled write can land after the platform\nhas already agreed to it. Re-read rather than assuming nothing was stored.",
+          "summary": "Cancel the write.\n\nA save is several hops, so a cancelled write can land after the platform\nhas already agreed to it. Re-read rather than assuming nothing was stored.\n\nA write that replaced earlier ones still waiting on its slot carries them,\nso cancelling it before it goes out cancels them too. Cancelling a write\nthat a later one replaced rejects only this call; the later write goes on.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -32707,7 +32787,39 @@
           "group": "player",
           "signature": "readonly timeoutMs?: number",
           "documented": true,
-          "summary": "How long this whole save may take, every hop together. Overrides the 30\nsecond default.\n\nSET THIS WHEN YOU ARE RACING A CLOCK YOU DO NOT CONTROL — above all when\nsaving from `GemTerminationNotice`, whose `graceMs` can be shorter\nthan the default. Left at the default in that case a save is killed\nmid-flight: the promise never settles, nothing is logged, and the player\nloses progress silently. Set it to the budget you actually have and a save\nthat will not make it rejects as `save_timeout` while there is still time\nto do something about it.\n\nIt does not make a save faster. Three round trips plus the payload is what\na save costs; this only decides when to stop waiting.",
+          "summary": "How long this whole save may take, every hop together. Overrides the 30\nsecond default.\n\nSET THIS WHEN YOU ARE RACING A CLOCK YOU DO NOT CONTROL — above all when\nsaving from `GemTerminationNotice`, whose `graceMs` can be shorter\nthan the default. Left at the default in that case a save is killed\nmid-flight: the promise never settles, nothing is logged, and the player\nloses progress silently. Set it to the budget you actually have and a save\nthat will not make it rejects as `save_timeout` while there is still time\nto do something about it.\n\nIt does not make a save faster. Three round trips plus the payload is what\na save costs; this only decides when to stop waiting.\n\nIt counts from the call, so a write waiting for the one before it on the\nsame slot spends it waiting. A rate limit whose wait it will not cover\nrejects at once as `GemApiError` reason `rate_limited`, not as\n`save_timeout`.\n\nIt stays this call's when a later write replaces this one: running out\nrejects only this call, and the later write goes on. The write that is\nsent runs on the newest call's `timeoutMs`, and running out of that rejects\nevery call it carries.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "PutSaveOptions.teardown",
+          "name": "teardown",
+          "anchor": "putsaveoptions-teardown",
+          "group": "player",
+          "signature": "readonly teardown?: boolean",
+          "documented": true,
+          "summary": "This is the last write before the page goes away: send it without waiting\nfor the spacing between writes to one slot.\n\nWrites to one slot go out a few seconds apart, and a write made sooner\nwaits its turn. Set this on the write you make from\n`GemTerminationNotice` or `pagehide`, with a `timeoutMs` inside the\ntime you have.\n\nIT STILL WAITS FOR A WRITE ALREADY IN FLIGHT to the same slot, and it\nstill honours a rate-limit hold: when the hold outlasts `timeoutMs` the\nwrite rejects at once as `rate_limited`, and nothing is sent. Not for\nordinary saves — the spacing is what keeps a save loop from spending the\nrate limit.\n\nA later write that replaces this one while it waits keeps it: the write\nthat goes out skips the spacing when any call it carries set `teardown`.\nNot across a player change: a call replaced after the signed-in player\nchanged is refused as `save_conflict`, and its `teardown` goes with it.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "PutSaveOptions.overwrite",
+          "name": "overwrite",
+          "anchor": "putsaveoptions-overwrite",
+          "group": "player",
+          "signature": "readonly overwrite?: boolean",
+          "documented": true,
+          "summary": "Write even if it replaces a save this game has not loaded.\n\nWithout it, a write to a slot whose last load FAILED is refused as\n`load_failed`, and a write is refused as `save_conflict` when the stored\nsave changed since you last loaded or wrote it. Both refusals protect the\nplayer's real progress from a game that started from defaults.\n\nSet it only when replacing whatever is stored is what you mean — a \"new\ngame\" the player confirmed, or the player choosing this device's progress\nafter a conflict. Never set it to get past a failed load.\n\nA later write that replaces this one while it waits keeps it: the write\nthat goes out overwrites when any call it carries set `overwrite`. A call\nthat gives up first (its `signal` or `timeoutMs`) takes it back, and so\ndoes one replaced after the signed-in player changed: it is refused as\n`save_conflict`, so one player's \"new game\" never overwrites the next's.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -32760,7 +32872,7 @@
           "group": "player",
           "signature": "readonly signal?: AbortSignal",
           "documented": true,
-          "summary": "Cancel the write.\n\nA save is several hops, so a cancelled write can land after the platform\nhas already agreed to it. Re-read rather than assuming nothing was stored.",
+          "summary": "Cancel the write.\n\nA save is several hops, so a cancelled write can land after the platform\nhas already agreed to it. Re-read rather than assuming nothing was stored.\n\nA write that replaced earlier ones still waiting on its slot carries them,\nso cancelling it before it goes out cancels them too. Cancelling a write\nthat a later one replaced rejects only this call; the later write goes on.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -32776,7 +32888,39 @@
           "group": "player",
           "signature": "readonly timeoutMs?: number",
           "documented": true,
-          "summary": "How long this whole save may take, every hop together. Overrides the 30\nsecond default.\n\nSET THIS WHEN YOU ARE RACING A CLOCK YOU DO NOT CONTROL — above all when\nsaving from `GemTerminationNotice`, whose `graceMs` can be shorter\nthan the default. Left at the default in that case a save is killed\nmid-flight: the promise never settles, nothing is logged, and the player\nloses progress silently. Set it to the budget you actually have and a save\nthat will not make it rejects as `save_timeout` while there is still time\nto do something about it.\n\nIt does not make a save faster. Three round trips plus the payload is what\na save costs; this only decides when to stop waiting.",
+          "summary": "How long this whole save may take, every hop together. Overrides the 30\nsecond default.\n\nSET THIS WHEN YOU ARE RACING A CLOCK YOU DO NOT CONTROL — above all when\nsaving from `GemTerminationNotice`, whose `graceMs` can be shorter\nthan the default. Left at the default in that case a save is killed\nmid-flight: the promise never settles, nothing is logged, and the player\nloses progress silently. Set it to the budget you actually have and a save\nthat will not make it rejects as `save_timeout` while there is still time\nto do something about it.\n\nIt does not make a save faster. Three round trips plus the payload is what\na save costs; this only decides when to stop waiting.\n\nIt counts from the call, so a write waiting for the one before it on the\nsame slot spends it waiting. A rate limit whose wait it will not cover\nrejects at once as `GemApiError` reason `rate_limited`, not as\n`save_timeout`.\n\nIt stays this call's when a later write replaces this one: running out\nrejects only this call, and the later write goes on. The write that is\nsent runs on the newest call's `timeoutMs`, and running out of that rejects\nevery call it carries.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "PutBytesOptions.teardown",
+          "name": "teardown",
+          "anchor": "putbytesoptions-teardown",
+          "group": "player",
+          "signature": "readonly teardown?: boolean",
+          "documented": true,
+          "summary": "This is the last write before the page goes away: send it without waiting\nfor the spacing between writes to one slot.\n\nWrites to one slot go out a few seconds apart, and a write made sooner\nwaits its turn. Set this on the write you make from\n`GemTerminationNotice` or `pagehide`, with a `timeoutMs` inside the\ntime you have.\n\nIT STILL WAITS FOR A WRITE ALREADY IN FLIGHT to the same slot, and it\nstill honours a rate-limit hold: when the hold outlasts `timeoutMs` the\nwrite rejects at once as `rate_limited`, and nothing is sent. Not for\nordinary saves — the spacing is what keeps a save loop from spending the\nrate limit.\n\nA later write that replaces this one while it waits keeps it: the write\nthat goes out skips the spacing when any call it carries set `teardown`.\nNot across a player change: a call replaced after the signed-in player\nchanged is refused as `save_conflict`, and its `teardown` goes with it.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "PutBytesOptions.overwrite",
+          "name": "overwrite",
+          "anchor": "putbytesoptions-overwrite",
+          "group": "player",
+          "signature": "readonly overwrite?: boolean",
+          "documented": true,
+          "summary": "Write even if it replaces a save this game has not loaded.\n\nWithout it, a write to a slot whose last load FAILED is refused as\n`load_failed`, and a write is refused as `save_conflict` when the stored\nsave changed since you last loaded or wrote it. Both refusals protect the\nplayer's real progress from a game that started from defaults.\n\nSet it only when replacing whatever is stored is what you mean — a \"new\ngame\" the player confirmed, or the player choosing this device's progress\nafter a conflict. Never set it to get past a failed load.\n\nA later write that replaces this one while it waits keeps it: the write\nthat goes out overwrites when any call it carries set `overwrite`. A call\nthat gives up first (its `signal` or `timeoutMs`) takes it back, and so\ndoes one replaced after the signed-in player changed: it is refused as\n`save_conflict`, so one player's \"new game\" never overwrites the next's.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -32808,7 +32952,7 @@
           "group": "player",
           "signature": "class SavesApi",
           "documented": true,
-          "summary": "A player's saved progress — write it, read it, list it, delete it.\n\nReached as `gem.me.saves`, and on a character as\n`gem.characters.get(id).saves`.\n\nA SAVE GOES IN A SLOT YOU DECLARED. Slots live in your game config, published\nwith `gemctl`, next to your room templates. Writing to a slot that was never\ndeclared fails as `not_found` naming the key, on the first call and every\nretry — that is the wall almost everyone hits first, and it is a config\nproblem rather than a code one.\n\n```js\nawait gem.me.saves.put('slot1', { level: 7, checkpoint: 'bridge' });\nconst state = await gem.me.saves.get('slot1');\n```\n\nWHAT IS DELIBERATELY NOT HERE: no autosave timer, no save format, no\nmigration. Those are your game's, and a platform that guessed at them would\nguess wrong.",
+          "summary": "A player's saved progress — write it, read it, list it, delete it.\n\nReached as `gem.me.saves`, and on a character as\n`gem.characters.get(id).saves`.\n\nA SAVE GOES IN A SLOT YOU DECLARED. Slots live in your game config, published\nwith `gemctl`, next to your room templates. Writing to a slot that was never\ndeclared fails as `not_found` naming the key, on the first call and every\nretry — that is the wall almost everyone hits first, and it is a config\nproblem rather than a code one.\n\n```js\nawait gem.me.saves.put('slot1', { level: 7, checkpoint: 'bridge' });\nconst state = await gem.me.saves.get('slot1');\n```\n\nLOAD BEFORE YOU SAVE. Each write carries the version of the slot your last\nload or write found, so a write that would replace a save this game has not\nseen — another device's, or the player's real progress after a load that\nfailed — is refused as `save_conflict` or `load_failed` rather than stored.\nAfter a failed load, play on without saving and load again later; pass\n`overwrite: true` only when the player chose to start over.\n\nONE WRITE PER SLOT AT A TIME. A write made while another to the same slot is\nin flight waits for it, and a later one replaces it: the newest value is the\none sent, and every caller it replaced resolves with it, keeping its own\n`signal`, `timeoutMs`, `teardown` and `overwrite`. Writes to one slot\ngo out a few seconds apart (`teardown: true` skips that), and after a\n`rate_limited` answer none goes out until the wait it named is over.\n\nWHAT IS DELIBERATELY NOT HERE: no autosave timer, no save format, no\nmigration. Those are your game's, and a platform that guessed at them would\nguess wrong.",
           "deprecated": null,
           "params": [],
           "returns": null,

package/docs/changelog.md

@@ -16,6 +16,36 @@ 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.
 
+## 16.2.0
+
+Upgrading from 16.1.0. Impact: required.
+
+### Must change
+
+- The reason on a save error can now also be save_conflict or load_failed. Any code that switches over the reason exhaustively, or maps it to a message, will stop compiling or fall through, so handle both new values. save_conflict means the write was refused because the saved data changed underneath it, or because the player changed while the write was waiting. Reload the save and decide whether to retry, or pass overwrite when replacing the stored data is intended. load_failed means a save could not be loaded.
+
+### Rebuild
+
+- The save error constructor now accepts the two new reasons, and the saves API constructor takes an optional trailing identity function. Recompiling is enough; existing calls stay valid.
+
+### New capability
+
+- Save and byte writes accept an overwrite option. Set it when a write should replace whatever is stored without the conflict check; otherwise a write that collides with newer saved data is refused as save_conflict.
+- Save and byte writes accept a teardown option. Set it on a final write, such as when the game is closing, so the write skips the spacing between writes and goes out right away.
+- The saves options accept minWriteIntervalMs, which sets the minimum spacing between writes. Tune it if the default spacing does not suit how often your game saves.
+
+## 16.1.0
+
+Upgrading from 16.0.1. Impact: required.
+
+### Rebuild
+
+- The signalMoment method on the frame now accepts an optional fourth parameter, wall, in the game, root and SDK entry points. Existing calls with three arguments keep working unchanged, so recompiling your game against the new types is enough.
+
+### New capability
+
+- A game can now mark a platform moment with wall set to true to say it accepts that the Arcade may show its app wall at that break. Leaving it out or passing false keeps the break ordinary. An older Arcade ignores the field, so it is safe to send everywhere. Only set it where showing the wall at that break is acceptable for your game.
+
 ## 16.0.1
 
 Upgrading from 16.0.0. Impact: none.

package/docs/getting-started.md

@@ -50,7 +50,7 @@ either way.
 ```jsonc
 // package.json
 "dependencies": {
-  "@indiegems/gem-web-sdk": "16.0.1"
+  "@indiegems/gem-web-sdk": "16.2.0"
 }
 ```
 

package/docs/manifest.json

@@ -43,8 +43,8 @@
     },
     {
       "file": "changelog.md",
-      "sha256": "dba54ef3b13e6b20bfbcb9d6abb9ff0a922f34731ad1d2ff59f8266ce4ed95eb",
-      "updated": "2026-10-29T14:15:53Z"
+      "sha256": "b2791239b695b7830c97ccb7ef1370c317b92070a9a3f17d8488d02d78965094",
+      "updated": "2026-10-29T20:57:56Z"
     },
     {
       "file": "daily-challenges.md",
@@ -73,8 +73,8 @@
     },
     {
       "file": "getting-started.md",
-      "sha256": "efbc0cf07d1cbfe82a305b15c6aee2b001e42f463815c63e98c6c64b2fd5b85c",
-      "updated": "2026-10-29T14:15:53Z"
+      "sha256": "0699d1d9283ec251416a8068a6d1dfa050d795c58c55656cc5ce83f98e5bf132",
+      "updated": "2026-10-29T20:57:56Z"
     },
     {
       "file": "inventory-and-catalogs.md",
@@ -98,8 +98,8 @@
     },
     {
       "file": "platform-moments.md",
-      "sha256": "c9909452a49fe50bac2266e56e5a44ad6495b8464ce1b5c889d0be39604bbff0",
-      "updated": "2026-10-14T22:43:26Z"
+      "sha256": "2d7a24af647c6820fb6d4b098ce417ca81ceaf131bf4c02a51f3e82e45631e01",
+      "updated": "2026-10-29T16:05:50Z"
     },
     {
       "file": "platform-rules.md",
@@ -128,13 +128,13 @@
     },
     {
       "file": "saving-player-progress.md",
-      "sha256": "2b51c68651b8973531fb1fda4afc4442e1450443871800ca71126605bf4b39db",
-      "updated": "2026-10-21T19:36:16Z"
+      "sha256": "78210e1fec9590a0b8051c16d6adcf685391aa32175d8abe80614f840358c7ec",
+      "updated": "2026-10-29T17:51:52Z"
     },
     {
       "file": "server-bundles.md",
-      "sha256": "6e4c5289bd657cf414f630ea8c38aff3c59d06404241b9c07c820a0d3ce8a599",
-      "updated": "2026-10-29T14:15:53Z"
+      "sha256": "3d628942136f6dbf2dc0dd25a825f4520fe9b54ffc88a62e2d9fed11039a5151",
+      "updated": "2026-10-29T20:57:56Z"
     },
     {
       "file": "serverless-functions-js.md",

package/docs/platform-moments.md

@@ -30,6 +30,7 @@ put the call, where never to, and the few things a game gets wrong when nobody t
 - [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)
+- [13. A break that may be a wall: `wall: true`](#13-a-break-that-may-be-a-wall-wall-true)
 
 ## 1. A platform moment is not your own offer
 
@@ -133,7 +134,7 @@ 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_invalid_argument`  | a `kind` outside the five, a `placement` outside the grammar, or a `wall` that is not a boolean    |
 | `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     |
@@ -264,3 +265,33 @@ 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.
+
+## 13. A break that may be a wall: `wall: true`
+
+`wall` is optional. Set it to `true` at a break where your game **accepts that the Arcade may show
+its app wall**: a panel that asks the player to carry on in the Gem Arcade app, and that may leave
+them no way to keep playing in this browser.
+
+```js
+// From the Next press, after the player's progress is saved.
+await saveProgress();
+await gem.moments.signal({ kind: 'level_end', placement: 'chapter-1-end', wall: true });
+startNextLevel();
+```
+
+- **Absent or `false` is an ordinary break**, exactly as before the flag existed. Leave it off
+  everywhere you would not want a player to stop.
+- **Only where stopping is acceptable, and only after saving.** The end of a level, a chapter or a
+  run, once the player's progress is saved where it follows them
+  ([`saving-player-progress.md`](saving-player-progress.md)) — never mid-run, and never at a break
+  whose progress is lost if the player does not come back to this tab.
+- **An acceptance, not an ask.** The Arcade still decides, on its own servers and under its own
+  settings, whether to show anything at that break, and usually shows nothing. The flag only
+  widens what it may show over your game; it never makes anything appear.
+- **Nothing else changes.** Call it from the same press, once per break (§3). The answer is the
+  same `{ shown }`, it grants nothing (§6), and the Arcade pauses your game the same way while
+  anything is up (§7). If a wall is shown, your game stays paused behind it.
+- **A `wall` that is not a boolean** is refused like any other bad argument: `{ shown: false }`
+  and a `moments_invalid_argument` report (§5).
+- **An older Arcade ignores it** and treats the break as ordinary, so the flag is safe to send
+  everywhere. The dev host's log line (§10) does not carry it.