@indiegems/gem-web-sdk 16.1.0 → 16.3.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.3.0"
   },
   "entries": [
     {
@@ -77,6 +77,10 @@
           "key": "store",
           "title": "The Arcade Store, for real money"
         },
+        {
+          "key": "branding",
+          "title": "The platform branding: logo, wordmark, currency marks"
+        },
         {
           "key": "vibration",
           "title": "Vibrating the device"
@@ -2805,7 +2809,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 +2940,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 +2995,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 +3011,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 +3096,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 +3112,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 +3176,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,
@@ -6562,6 +6630,597 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "BrandingTheme",
+          "name": "BrandingTheme",
+          "anchor": "brandingtheme",
+          "group": "branding",
+          "signature": "type BrandingTheme = \"light\" | \"dark\"",
+          "documented": true,
+          "summary": "A theme a variant is drawn for.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "BrandingVariant",
+          "name": "BrandingVariant",
+          "anchor": "brandingvariant",
+          "group": "branding",
+          "signature": "interface BrandingVariant",
+          "documented": true,
+          "summary": "One file of a [BrandingAsset](api-reference-game.md#brandingasset): a render at one size and density, a\nscalable image, or the one file of a sound or a font.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "BrandingVariant.url",
+          "name": "url",
+          "anchor": "brandingvariant-url",
+          "group": "branding",
+          "signature": "readonly url: string",
+          "documented": true,
+          "summary": "The file's URL, absolute and on the platform's own host. Content-hashed,\nso a re-render is a new URL: look it up each session rather than storing\none in a save or your build.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "BrandingVariant.type",
+          "name": "type",
+          "anchor": "brandingvariant-type",
+          "group": "branding",
+          "signature": "readonly type: string",
+          "documented": true,
+          "summary": "Its MIME type, such as `image/png` or `image/svg+xml`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "BrandingVariant.bytes",
+          "name": "bytes",
+          "anchor": "brandingvariant-bytes",
+          "group": "branding",
+          "signature": "readonly bytes: number",
+          "documented": true,
+          "summary": "Its size in bytes.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "BrandingVariant.width",
+          "name": "width",
+          "anchor": "brandingvariant-width",
+          "group": "branding",
+          "signature": "readonly width?: number",
+          "documented": true,
+          "summary": "An image's width in pixels (an SVG's in its viewBox units).",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "BrandingVariant.height",
+          "name": "height",
+          "anchor": "brandingvariant-height",
+          "group": "branding",
+          "signature": "readonly height?: number",
+          "documented": true,
+          "summary": "An image's height in pixels (an SVG's in its viewBox units).",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "BrandingVariant.size",
+          "name": "size",
+          "anchor": "brandingvariant-size",
+          "group": "branding",
+          "signature": "readonly size?: number",
+          "documented": true,
+          "summary": "The CSS px box this render was made for, with [BrandingVariant.density](api-reference-game.md#brandingvariant-density).\nAbsent on a render meant for any box up to its width.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "BrandingVariant.density",
+          "name": "density",
+          "anchor": "brandingvariant-density",
+          "group": "branding",
+          "signature": "readonly density?: number",
+          "documented": true,
+          "summary": "Device pixels per CSS px of a render made for [BrandingVariant.size](api-reference-game.md#brandingvariant-size).",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "BrandingVariant.vector",
+          "name": "vector",
+          "anchor": "brandingvariant-vector",
+          "group": "branding",
+          "signature": "readonly vector?: true",
+          "documented": true,
+          "summary": "`true` on a scalable image: it draws crisply at any size.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "BrandingVariant.theme",
+          "name": "theme",
+          "anchor": "brandingvariant-theme",
+          "group": "branding",
+          "signature": "readonly theme?: BrandingTheme",
+          "documented": true,
+          "summary": "The one theme the file is for. Absent: either theme.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "BrandingAsset",
+          "name": "BrandingAsset",
+          "anchor": "brandingasset",
+          "group": "branding",
+          "signature": "interface BrandingAsset",
+          "documented": true,
+          "summary": "One asset in the platform's branding manifest.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "BrandingAsset.id",
+          "name": "id",
+          "anchor": "brandingasset-id",
+          "group": "branding",
+          "signature": "readonly id: string",
+          "documented": true,
+          "summary": "What a game asks for: `'gem-logo'`, `'gems-mark'`. Never renamed.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "BrandingAsset.kind",
+          "name": "kind",
+          "anchor": "brandingasset-kind",
+          "group": "branding",
+          "signature": "readonly kind: string",
+          "documented": true,
+          "summary": "`'image'`, `'audio'` or `'font'` today. The platform may add more, so\ncompare it rather than switching on it exhaustively.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "BrandingAsset.variants",
+          "name": "variants",
+          "anchor": "brandingasset-variants",
+          "group": "branding",
+          "signature": "readonly variants: readonly BrandingVariant[]",
+          "documented": true,
+          "summary": "Every file of it, smallest first. Never empty.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "BrandingLookup",
+          "name": "BrandingLookup",
+          "anchor": "brandinglookup",
+          "group": "branding",
+          "signature": "type BrandingLookup = { outcome: \"ok\"; url: string; variant: BrandingVariant; asset: BrandingAsset } | { outcome: \"not_found\" | \"unavailable\" }",
+          "documented": true,
+          "summary": "What a branding lookup resolves with. Only `ok` carries a URL.\n\n- `ok`: the platform has it, and `url` is the file picked for what you asked.\n- `not_found`: the manifest was read and has no asset with that id and kind,\n  or none of its files fits the theme you asked for. Draw nothing for it.\n- `unavailable`: the manifest could not be read — offline, a network error,\n  a Content-Security-Policy that leaves out `https://gemarcade.com`. Draw the\n  copy you bundled from the package's `brand/` folder, if there is one.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "BrandingList",
+          "name": "BrandingList",
+          "anchor": "brandinglist",
+          "group": "branding",
+          "signature": "type BrandingList = { outcome: \"ok\"; assets: readonly BrandingAsset[] } | { outcome: \"unavailable\" }",
+          "documented": true,
+          "summary": "What [BrandingApi.list](api-reference-game.md#brandingapi-list) resolves with.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "BrandingImageOptions",
+          "name": "BrandingImageOptions",
+          "anchor": "brandingimageoptions",
+          "group": "branding",
+          "signature": "interface BrandingImageOptions",
+          "documented": true,
+          "summary": "How to pick one image from an asset's variants.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "BrandingImageOptions.size",
+          "name": "size",
+          "anchor": "brandingimageoptions-size",
+          "group": "branding",
+          "signature": "readonly size?: number",
+          "documented": true,
+          "summary": "The CSS px box you draw it in. A render made for exactly that box wins;\nthen a scalable image; then the narrowest render wide enough for\n`size × density`. Leave it out for the largest: the scalable image, or\nelse the widest render.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "BrandingImageOptions.density",
+          "name": "density",
+          "anchor": "brandingimageoptions-density",
+          "group": "branding",
+          "signature": "readonly density?: number",
+          "documented": true,
+          "summary": "Device pixels per CSS px. Defaults to the screen's `devicePixelRatio`;\npass `3` for a canvas or texture you scale down yourself.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "BrandingImageOptions.theme",
+          "name": "theme",
+          "anchor": "brandingimageoptions-theme",
+          "group": "branding",
+          "signature": "readonly theme?: BrandingTheme",
+          "documented": true,
+          "summary": "Prefer a file drawn for this theme. Files for the other theme are never picked.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "BrandingAssetOptions",
+          "name": "BrandingAssetOptions",
+          "anchor": "brandingassetoptions",
+          "group": "branding",
+          "signature": "interface BrandingAssetOptions",
+          "documented": true,
+          "summary": "What [BrandingApi.get](api-reference-game.md#brandingapi-get) takes: the asset's kind, and how to pick a file.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "BrandingAssetOptions.size",
+          "name": "size",
+          "anchor": "brandingassetoptions-size",
+          "group": "branding",
+          "signature": "readonly size?: number",
+          "documented": true,
+          "summary": "The CSS px box you draw it in. A render made for exactly that box wins;\nthen a scalable image; then the narrowest render wide enough for\n`size × density`. Leave it out for the largest: the scalable image, or\nelse the widest render.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "BrandingAssetOptions.density",
+          "name": "density",
+          "anchor": "brandingassetoptions-density",
+          "group": "branding",
+          "signature": "readonly density?: number",
+          "documented": true,
+          "summary": "Device pixels per CSS px. Defaults to the screen's `devicePixelRatio`;\npass `3` for a canvas or texture you scale down yourself.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "BrandingAssetOptions.theme",
+          "name": "theme",
+          "anchor": "brandingassetoptions-theme",
+          "group": "branding",
+          "signature": "readonly theme?: BrandingTheme",
+          "documented": true,
+          "summary": "Prefer a file drawn for this theme. Files for the other theme are never picked.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "BrandingAssetOptions.kind",
+          "name": "kind",
+          "anchor": "brandingassetoptions-kind",
+          "group": "branding",
+          "signature": "readonly kind: string",
+          "documented": true,
+          "summary": "The kind you expect: `'image'`, `'audio'` or `'font'`. An asset of another\nkind answers `not_found`. `size` and `density` apply to images only; for\nany other kind the first file wins.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "BrandingCurrency",
+          "name": "BrandingCurrency",
+          "anchor": "brandingcurrency",
+          "group": "branding",
+          "signature": "type BrandingCurrency = \"GEMS\" | \"ARCADE_TICKETS\"",
+          "documented": true,
+          "summary": "The platform currencies with a mark: Gems and Coins.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "BrandingApi",
+          "name": "BrandingApi",
+          "anchor": "brandingapi",
+          "group": "branding",
+          "signature": "interface BrandingApi",
+          "documented": true,
+          "summary": "The platform's branding, as the platform serves it now. `gem.branding` is\none of these. Nothing here rejects but a bad argument.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "BrandingApi.get",
+          "name": "get",
+          "anchor": "brandingapi-get",
+          "group": "branding",
+          "signature": "get(id: string, options: BrandingAssetOptions): Promise<BrandingLookup>",
+          "documented": true,
+          "summary": "Any asset in the platform's branding manifest, by id and kind — including\nones added after this SDK was released.\n\n```js\nconst logo = await gem.branding.get('gem-logo', { kind: 'image', size: 64 });\nif (logo.outcome === 'ok') img.src = logo.url;\n```",
+          "deprecated": null,
+          "params": [
+            {
+              "name": "id",
+              "type": "string",
+              "optional": false,
+              "summary": null
+            },
+            {
+              "name": "options",
+              "type": "BrandingAssetOptions",
+              "optional": false,
+              "summary": null
+            }
+          ],
+          "returns": "Resolves `ok`, `not_found` or `unavailable`. Rejects only for an\n  argument that is not one (an empty id, a size that is not a positive\n  number).",
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "BrandingApi.logo",
+          "name": "logo",
+          "anchor": "brandingapi-logo",
+          "group": "branding",
+          "signature": "logo(options?: BrandingImageOptions): Promise<BrandingLookup>",
+          "documented": true,
+          "summary": "The Indie Gems logo, the brand gem. Scalable: draw it at 32 CSS px or more,\nas served (`docs/branding.md` has the usage rules).",
+          "deprecated": null,
+          "params": [
+            {
+              "name": "options",
+              "type": "BrandingImageOptions",
+              "optional": true,
+              "summary": null
+            }
+          ],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "BrandingApi.wordmark",
+          "name": "wordmark",
+          "anchor": "brandingapi-wordmark",
+          "group": "branding",
+          "signature": "wordmark(options?: BrandingImageOptions): Promise<BrandingLookup>",
+          "documented": true,
+          "summary": "The Gem Arcade wordmark. Draw it at 60 CSS px wide or more, as served.",
+          "deprecated": null,
+          "params": [
+            {
+              "name": "options",
+              "type": "BrandingImageOptions",
+              "optional": true,
+              "summary": null
+            }
+          ],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "BrandingApi.currencyMark",
+          "name": "currencyMark",
+          "anchor": "brandingapi-currencymark",
+          "group": "branding",
+          "signature": "currencyMark(currency: BrandingCurrency, options?: BrandingImageOptions): Promise<BrandingLookup>",
+          "documented": true,
+          "summary": "The mark of a platform currency, by its slug: `'GEMS'` or\n`'ARCADE_TICKETS'` (Coins). Pass `size: 20` or `32` for the inline icon\nbeside an amount, or leave it out for the hero art of a reward screen.\n`docs/brand-art.md` says where each may be drawn.",
+          "deprecated": null,
+          "params": [
+            {
+              "name": "currency",
+              "type": "BrandingCurrency",
+              "optional": false,
+              "summary": null
+            },
+            {
+              "name": "options",
+              "type": "BrandingImageOptions",
+              "optional": true,
+              "summary": null
+            }
+          ],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "BrandingApi.trophy",
+          "name": "trophy",
+          "anchor": "brandingapi-trophy",
+          "group": "branding",
+          "signature": "trophy(options?: BrandingImageOptions): Promise<BrandingLookup>",
+          "documented": true,
+          "summary": "The trophy, for where your game shows what a player has achieved.",
+          "deprecated": null,
+          "params": [
+            {
+              "name": "options",
+              "type": "BrandingImageOptions",
+              "optional": true,
+              "summary": null
+            }
+          ],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "BrandingApi.list",
+          "name": "list",
+          "anchor": "brandingapi-list",
+          "group": "branding",
+          "signature": "list(): Promise<BrandingList>",
+          "documented": true,
+          "summary": "Every asset the platform serves, or `unavailable` when the manifest could\nnot be read.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "ListChallengesOptions",
           "name": "ListChallengesOptions",
@@ -12145,6 +12804,27 @@
             }
           ]
         },
+        {
+          "id": "Gem.branding",
+          "name": "branding",
+          "anchor": "gem-branding",
+          "group": "start",
+          "signature": "readonly branding: BrandingApi",
+          "documented": true,
+          "summary": "The platform's branding — the Indie Gems logo, the Gem Arcade wordmark,\nthe Gems and Coins marks and the trophy — as the platform serves it now,\nso a changed mark reaches your game with no republish.\n\nLook up any asset by id and kind with `get`, or use `logo`, `wordmark`,\n`currencyMark` and `trophy`. Every URL is on the platform's own host.\nNothing rejects but a bad argument: an asset the platform does not list is\n`not_found`, and a manifest that could not be read is `unavailable`, when\nyou draw the copy you bundled from `brand/` instead.\n\n```js\nconst logo = await gem.branding.logo();\nif (logo.outcome === 'ok') menuLogo.src = logo.url;\n```",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": [
+            {
+              "slug": "branding",
+              "anchor": null
+            }
+          ]
+        },
         {
           "id": "Gem.avatarPickerAvailable",
           "name": "avatarPickerAvailable",
@@ -32521,7 +33201,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 +33332,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 +33387,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 +33403,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 +33488,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 +33504,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 +33568,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,