@indiegems/gem-web-sdk 16.1.0 → 16.2.0

package/docs/api/reference.json

@@ -2,7 +2,7 @@
   "schema_version": 2,
   "source": {
     "repo": "IndieGems/gem-web-sdk",
-    "version": "16.1.0"
+    "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,
@@ -32521,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,
@@ -32652,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,
@@ -32707,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,
@@ -32723,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,
@@ -32776,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,
@@ -32792,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,
@@ -32824,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,24 @@ 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.

package/docs/getting-started.md

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

package/docs/manifest.json

@@ -43,8 +43,8 @@
     },
     {
       "file": "changelog.md",
-      "sha256": "085828e2eb6fdb752c8e2fd65e8110d31cdf1322e210a199f85a2e8bb17ba4d3",
-      "updated": "2026-10-29T18:42:12Z"
+      "sha256": "b2791239b695b7830c97ccb7ef1370c317b92070a9a3f17d8488d02d78965094",
+      "updated": "2026-10-29T20:57:56Z"
     },
     {
       "file": "daily-challenges.md",
@@ -73,8 +73,8 @@
     },
     {
       "file": "getting-started.md",
-      "sha256": "4344ccdf72a10cf7dddf2323d528240638bc88a14f742840a571ed347df5cb92",
-      "updated": "2026-10-29T18:42:12Z"
+      "sha256": "0699d1d9283ec251416a8068a6d1dfa050d795c58c55656cc5ce83f98e5bf132",
+      "updated": "2026-10-29T20:57:56Z"
     },
     {
       "file": "inventory-and-catalogs.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": "ec3ce51e73941a55ad4bd66daa832b85a9688f6011493c1347c51e8f0a1dbfd4",
-      "updated": "2026-10-29T18:42:12Z"
+      "sha256": "3d628942136f6dbf2dc0dd25a825f4520fe9b54ffc88a62e2d9fed11039a5151",
+      "updated": "2026-10-29T20:57:56Z"
     },
     {
       "file": "serverless-functions-js.md",

package/docs/saving-player-progress.md

@@ -150,6 +150,163 @@ silently. Use `putBytes` and `getBytes`, and name the content type you are actua
 `saves` exactly like the player's, scoped to that character — the same declared slots, separate
 stored saves. Most browser games have no characters and can ignore this.
 
+## Handling the common cases
+
+The one failure that does real harm is a game that could not load the player's save, started
+from defaults, and then saved — over the player's real progress. Everything in this section is
+about never doing that, and about not hammering the platform while you avoid it.
+
+### Load before you save
+
+**Load a slot with `get` (or `getBytes`) before you first write it.** The SDK remembers, per
+slot, the version that load found, and sends it with every write. The platform then refuses any
+write that would replace a save you have not seen: one another device or tab wrote since your
+load. Each successful write updates the version, so you never pass it yourself.
+
+What the SDK knows about a slot decides what a write to it does:
+
+| The slot's last load or write here | What a write sends                       | It is refused when                    |
+| ---------------------------------- | ---------------------------------------- | ------------------------------------- |
+| found a save, or wrote one         | that save's version                      | the stored save is a different one    |
+| found no save, or deleted it       | "only if there is still no save"         | a save has appeared since             |
+| **failed**                         | nothing — the SDK refuses it before that | always, until a load succeeds         |
+| never happened in this session     | no condition, as before                  | never; a write here replaces anything |
+
+`describe` and `list` do not count as a load: they read records, not your progress.
+
+### When the load fails
+
+A failed load (a `rate_limited` answer, a timeout, the player offline) means you do not know
+what is stored. **Never write defaults over an unknown save.** Instead:
+
+- keep the game playable, but do not save, and say so if the player would expect it to;
+- retry the load later, with a backoff, and resume saving once one succeeds;
+- if the player chooses to start over, write with `overwrite: true` — the only way past it.
+
+A write to a slot whose last load failed is refused with `GemSaveError` reason `load_failed`
+before anything is sent. It is your safety net, not the plan: check the load's result instead.
+
+```js
+let canSave = false;
+let state = defaults();
+
+async function load() {
+  try {
+    const saved = await gem.me.saves.get('campaign', { timeoutMs: 5000 });
+    if (saved) state = saved;
+    canSave = true; // a null means a new player, and saving is safe
+  } catch {
+    setTimeout(load, 30_000); // play on, unsaved, and try again later
+  }
+}
+```
+
+A load that fails after an earlier one succeeded keeps the earlier version: you still hold that
+copy, and a write conditioned on it is as safe as it was.
+
+### Don't let the boot read hold the game
+
+Give the boot read a short `timeoutMs`, a few seconds, and if it fails start the game anyway in
+the unsaved state above, rather than holding the loading screen. A load that meets a rate limit
+whose wait will not fit in that `timeoutMs` does not sleep through it: it rejects at once as
+`rate_limited` (below), so the loading screen is not held either way.
+
+### When a save conflicts
+
+A write refused because the stored save changed rejects as `GemSaveError` reason
+`save_conflict`. Nothing was written. Resending the same write fails the same way, so:
+
+1. load the slot again (`get`), which learns the new version;
+2. decide what to write: merge the two, keep the stored one, or ask the player which to keep;
+3. write the result, which now replaces the version you just loaded.
+
+To keep this device's progress after asking the player, write with `overwrite: true`.
+
+### Save on events, and debounce
+
+Save when something worth keeping happens — a level cleared, a purchase, a run ended — never on
+a frame timer or on every change. When changes come fast, wait until they stop for a few
+seconds, then write once.
+
+**The SDK keeps one write per slot in flight, and spaces them.** A `put` made while another to
+the same slot is in flight waits for it, and a later `put` replaces the one waiting: the newest
+value is the one sent, and every call it replaced resolves with the same record. Writes to one
+slot go out at least five seconds apart; a write made sooner waits its turn, though never past
+half its own `timeoutMs`. This is a floor under your game, not a debounce: it keeps a runaway save
+loop to a few writes a minute, but your own debounce is still what decides how often you save.
+
+A replaced call keeps its own options. Its `signal` and `timeoutMs` still reject that call alone,
+without cancelling the newer write; the write that goes out runs on the newest call's. Its
+`teardown` and `overwrite` still apply to that write: an autosave that lands behind your teardown
+flush does not make it wait out the spacing, and one that lands behind a confirmed "new game"
+still overwrites. A call that gives up first takes its `teardown` and `overwrite` with it. So
+does a call replaced after the signed-in player changed: it is refused as `save_conflict`, so one
+player's "new game" never overwrites the next player's save.
+
+**Do not re-save immediately because the state changed while a write was in flight.** That loop
+writes back to back, defeats any debounce, and spends the rate limit every other player behind
+the same network address shares. The spacing above limits the damage; it does not make the loop
+right. Wait out the debounce again.
+
+```js
+let dirty = false;
+let writing = null;
+let timer = null;
+
+function changed() {
+  dirty = true;
+  clearTimeout(timer);
+  timer = setTimeout(flush, 5000);
+}
+
+async function flush() {
+  if (writing || !dirty || !canSave) return;
+  dirty = false;
+  writing = gem.me.saves.put('campaign', state).catch(onSaveError);
+  await writing;
+  writing = null;
+  if (dirty) changed(); // wait the debounce again, never write at once
+}
+```
+
+### On a 429, back off
+
+A save or load refused for the rate rejects as `GemApiError` reason `rate_limited`, with
+`retryAfterSeconds` when the platform named a wait. **That is the one shape, whichever leg was
+refused**: the platform's checks, the upload or download of the bytes, or a wait the platform
+asked for that your call's `timeoutMs` will not cover, which rejects at once instead of
+sleeping. So one test covers every save loop:
+
+```js
+function onSaveError(err) {
+  if (err instanceof GemApiError && err.reason === 'rate_limited') {
+    holdSavesFor(err.retryAfterSeconds ?? 60); // keep the state dirty
+  }
+}
+```
+
+**Never retry at once.** Hold every write for at least `retryAfterSeconds` (a minute if it is
+absent), keep the state dirty, and write once when the wait is over. A rate-limited load is the
+"load fails" case above.
+
+The SDK holds too. After a `rate_limited` answer on any leg, it sends no write for the wait the
+answer named: a write made meanwhile waits for it, or, when the wait outlasts its `timeoutMs`,
+rejects at once as `rate_limited` without being sent.
+
+In earlier releases of this SDK, the same refusal could also arrive as a `save_timeout` from a call whose `timeoutMs`
+ran out while it waited out a rate limit, or as an `upload_failed` whose message named a 429. A
+game that matched on either can drop it.
+
+### Saving on teardown
+
+`onWillTerminate` gives you `graceMs`, and Back, a closed tab or a reload give you nothing. Keep
+your last save recent, and in the callback flush only what changed, with a `timeoutMs` inside the
+grace and `teardown: true` — see [Saving against a deadline](#saving-against-a-deadline).
+`teardown` sends the write without waiting for the spacing between writes; it still waits for a
+write already in flight to that slot, and still honours a rate-limit hold, rejecting at once as
+`rate_limited` when the hold outlasts the grace. Skip the flush when the slot cannot be saved (its
+load failed) or your own rate-limit hold is active.
+
 ## Showcase slots: a little progress your friends can read
 
 Everything above is the player's own document, read back by the same player. A **showcase
@@ -285,7 +442,10 @@ const gem = createGem({
     // The parent told you how long it will wait. Spend a little less than that,
     // so a failure still has somewhere to be handled.
     gem.me.saves
-      .put('campaign', state, { timeoutMs: Math.max(1000, notice.graceMs - 500) })
+      .put('campaign', state, {
+        timeoutMs: Math.max(1000, notice.graceMs - 500),
+        teardown: true, // skip the spacing between writes; see "Saving on teardown"
+      })
       .catch(report);
   },
 });
@@ -293,9 +453,11 @@ const gem = createGem({
 
 `timeoutMs` is on `put`, `putBytes`, `get` and `getBytes`; it covers every hop together, and it
 is a ceiling rather than a target — it does not make a save faster, it decides when to stop
-waiting for one. A save that misses it rejects as `GemSaveError` with reason `save_timeout`,
+waiting for one. It counts from the call, so a write waiting for the one before it on the same
+slot spends it waiting. A save that misses it rejects as `GemSaveError` with reason `save_timeout`,
 naming the budget you gave it rather than the default, so a log tells you which of the two you
-were running under.
+were running under. A rate limit whose wait it will not cover is not a miss: that rejects at once
+as `rate_limited`.
 
 **The save that fits a teardown window is a small one.** Nothing here turns three round trips
 into fewer, so the durable answer is not to be holding a megabyte of unsaved progress when the
@@ -310,7 +472,7 @@ clock starts — save on the events that matter, and let the teardown flush be a
 | `precondition_failed` | something else saved this slot while yours was in flight                                                         | re-read, rebuild, save again — **never** retry the same payload                              |
 | `too_large`           | the payload is over the slot's ceiling, or this player's or this game's save storage is full — `code` says which | **do not retry.** Store less or raise `max_size_bytes`; or delete a save, or tell the player |
 | `forbidden`           | the player's session ended while the save was in flight                                                          | a fresh session, not a retry                                                                 |
-| `rate_limited`        | too many save calls from this network address                                                                    | back off by what it tells you; then save less often                                          |
+| `rate_limited`        | too many save calls from this network address, refused on any leg of the save or load                            | back off by what it tells you; then save less often                                          |
 | `GemSaveError`        | the payload could not be pushed to or pulled from storage                                                        | see below                                                                                    |
 
 **`too_large` is the one to get right.** It used to reach game code labelled as a retryable
@@ -323,7 +485,11 @@ loop to enter.
 **`GemSaveError` is the half that does not go through the API.** Your payload travels to and
 from storage over a short-lived signed link, so a failure there is not an API error and cannot
 be classified as one. It carries `reason`: `upload_failed`, `download_failed`, `save_timeout`,
-or `save_malformed` for a payload that is not what it claims.
+or `save_malformed` for a payload that is not what it claims. Two more refuse a write to keep
+the player's progress safe, and neither is worth retrying as it stands: `save_conflict`, the
+stored save changed since you loaded it, and `load_failed`, the slot's last load failed. See
+[Handling the common cases](#handling-the-common-cases). A rate limit on the storage leg is not a
+`GemSaveError`: it is `GemApiError` reason `rate_limited`, like every other leg's.
 
 **If you see `upload_failed` on every save, from every player, in a browser** — that is not a
 transient fault and no amount of retrying moves it. Two causes have that shape, both platform

package/docs/server-bundles.md

@@ -80,8 +80,8 @@ To check the download yourself: the package npm serves is, byte for byte, the fi
 also publishes on its download host, with the hash beside it:
 
 ```bash
-curl -fsSL -O https://downloads.gemarcade.com/sdk/v16.1.0/gem-web-sdk.tgz
-curl -fsSL https://downloads.gemarcade.com/sdk/v16.1.0/gem-web-sdk.tgz.sri
+curl -fsSL -O https://downloads.gemarcade.com/sdk/v16.2.0/gem-web-sdk.tgz
+curl -fsSL https://downloads.gemarcade.com/sdk/v16.2.0/gem-web-sdk.tgz.sri
 openssl dgst -sha384 -binary gem-web-sdk.tgz | openssl base64 -A
 ```
 

package/package.json

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