@indiegems/gem-web-sdk 16.1.0 → 16.3.0

package/docs/arcade-and-store.md

@@ -194,6 +194,12 @@ talks to the Arcade: `gemctl serve` and the Project Editor too, when they are si
 **Name each host exactly. Never allow `https://*.blob.core.windows.net`**: that wildcard is every
 Azure customer's storage, not the Arcade's.
 
+**The platform's branding** (the logo, the wordmark and the currency marks `gem.branding` hands
+you) is served from `https://gemarcade.com`, in every environment. Allow it in `connect-src`, for
+the branding manifest, and in each kind's own directive for the files you draw: `img-src` for
+images, `media-src` for audio, `font-src` for fonts
+([branding.md](branding.md#5-your-pages-content-security-policy)).
+
 A non-production backend serves its art from hosts of its own. These hosts are infrastructure, and
 they can change: art that will not load is the sign, and the browser's console names the host your
 policy refused. Allow that host rather than a wildcard.

package/docs/brand-art.md

@@ -5,6 +5,13 @@ The SDK ships the platform's own art for its two currencies, **Gems** and **Coin
 §1 before you pick a file: each currency has two kinds of art, and which one you use depends on what
 the screen is for.
 
+> **Draw the platform's current marks with `gem.branding`, and keep these files as the fallback.**
+> `gem.branding.currencyMark('GEMS', { size: 20 })` and `gem.branding.trophy()` hand you the same
+> renders, served by the platform, so a changed mark reaches your game with no SDK update and no
+> republish ([branding.md](branding.md)). The files in this package are the marks as they were when
+> this SDK version was released: draw them only when a lookup answers `unavailable`. Every size,
+> role and rule on this page applies to both.
+
 **Currency display belongs to the arcade.** The arcade draws the player's Gems and Coins totals in
 its own chrome while your game runs, and it animates every payout of either into its total. Your game
 draws Gems or Coins only in the three places §5 allows — an amount on offer or just paid, a reward
@@ -142,6 +149,9 @@ and the art softens as it is stretched. Below 64 px, use the icon (§2).
 
 ## 4. Loading and drawing the art
 
+The platform serves every one of these files through `gem.branding` ([branding.md](branding.md)),
+which is what to draw first. The copies below are the fallback for when it answers `unavailable`.
+
 All of it is in the package you already install, under `brand/`, and published beside it on the CDN —
 the same bytes either way, for the version you are on.
 
@@ -264,9 +274,10 @@ The CDN lets any origin read these files, so a canvas or a WebGL texture can use
 path never changes once published, so a URL you ship keeps working, and `artifact-manifest.json` in
 the same version folder lists each file's `sha384` hash under `brand`.
 
-**Prefer copying the file into your build over loading it by URL at play time.** A load at play time
-is one more request that can be slow or fail, and your screen then shows a gap where the art should
-be. If you do load it live, lay the screen out so it reads correctly without the image.
+**Prefer `gem.branding` over a fixed URL here.** A URL in this folder is the art of the version you
+pinned, forever; the platform's is the art as it is now. Either way, a load at play time can be slow
+or fail, so lay the screen out so it reads correctly without the image, and keep a bundled copy for
+`unavailable`.
 
 ### The platform currency's `icon_url`
 

package/docs/branding.md

@@ -0,0 +1,160 @@
+# The platform's branding: the logo, the wordmark and the platform marks
+
+Show the Indie Gems logo on your main menu, the Gem Arcade wordmark on a credits screen, or the Gems
+mark beside a price, with the files **the platform serves now**. `gem.branding` reads them from the
+platform's branding manifest, so when a mark changes, your game draws the new one on its next
+session. You do not update the SDK or republish.
+
+```js
+const logo = await gem.branding.logo();
+if (logo.outcome === 'ok') {
+  menuLogo.src = logo.url;
+} else {
+  menuLogo.hidden = true; // the platform's branding could not be read: draw no logo
+}
+```
+
+- [1. What you can ask for](#1-what-you-can-ask-for)
+- [2. What a lookup answers](#2-what-a-lookup-answers)
+- [3. Picking a file](#3-picking-a-file)
+- [4. When the manifest cannot be read: the bundled copy](#4-when-the-manifest-cannot-be-read-the-bundled-copy)
+- [5. Your page's Content-Security-Policy](#5-your-pages-content-security-policy)
+- [6. Using the logo and the wordmark](#6-using-the-logo-and-the-wordmark)
+
+## 1. What you can ask for
+
+| Call                                          | Asset id       | What it is                                                                                          |
+| --------------------------------------------- | -------------- | --------------------------------------------------------------------------------------------------- |
+| `gem.branding.logo()`                         | `gem-logo`     | The Indie Gems logo, the brand gem. Scalable (SVG).                                                 |
+| `gem.branding.wordmark()`                     | `gem-wordmark` | The Gem Arcade wordmark, 336 and 672 px wide.                                                       |
+| `gem.branding.currencyMark('GEMS')`           | `gems-mark`    | The Gems mark: the 20 and 32 CSS px icons at 1, 1.5, 2 and 3x, and hero renders 128 to 768 px wide. |
+| `gem.branding.currencyMark('ARCADE_TICKETS')` | `ticket-mark`  | The Coins mark, in the same sizes.                                                                  |
+| `gem.branding.trophy()`                       | `trophy-mark`  | The trophy: 20, 28, 56 and 72 CSS px renders and hero renders 128 to 768 px wide.                   |
+
+**Any asset, by id and kind:** `gem.branding.get(id, { kind })`. The named calls are `get` with the
+id filled in. When the platform adds an asset (another image, a sound, a font), you reach it with
+`get` from the SDK you already have:
+
+```js
+// 'arcade-sting' is an example of an id the platform could add; today it answers not_found.
+const sting = await gem.branding.get('arcade-sting', { kind: 'audio' });
+if (sting.outcome === 'ok') new Audio(sting.url).play();
+```
+
+`gem.branding.list()` resolves every asset the platform serves today, each with its `id`, `kind`
+and every file (`variants`). Compare `kind` rather than switching on every value: kinds other than
+`image`, `audio` and `font` may appear.
+
+The currency marks follow the rules in [brand-art.md](brand-art.md): **the icon** (`size: 20` or
+`32`) beside an amount, **the hero** (no size, or a size of 64 CSS px or more) on a reward screen,
+and never a balance of your own.
+
+## 2. What a lookup answers
+
+Every call resolves. None rejects, except for an argument that is not one: an empty id, a `size`
+or `density` that is not a positive number, a `theme` other than `'light'` or `'dark'`, or a
+currency other than `'GEMS'` or `'ARCADE_TICKETS'`.
+
+| `outcome`     | Means                                                                                                             | Do                                       |
+| ------------- | ----------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
+| `ok`          | The platform has it. `url` is the file picked for you, `variant` describes it, and `asset` holds every file.      | Draw `url`.                              |
+| `not_found`   | The manifest was read, and has no asset with that id and kind, or none in the theme you asked for.                | Draw nothing for it.                     |
+| `unavailable` | The manifest could not be read: the player is offline, the request failed, or your page's policy refused it (§5). | Draw your bundled copy (§4), or nothing. |
+
+An id or a kind the SDK does not know is `not_found`, never an error, so a newer platform cannot
+break an older game.
+
+**Every URL is on the platform's own host**, absolute, and content-hashed: a changed mark is a new
+URL. Use it as it is in an `<img src>`, a CSS `background-image` or a texture loader. Look it up
+each session; do not store one in a save or your build.
+
+The SDK reads the manifest once, on your first `gem.branding` call, and every later call shares
+that read. A game that never calls it makes no request. If the read fails, calls answer
+`unavailable` for a minute, then the next call tries again. Call `gem.branding.list()` during
+start-up to have it ready before your menu draws.
+
+## 3. Picking a file
+
+Pass the box you draw in, in CSS px, as `size`. The SDK picks:
+
+1. the file **made for that box**, at the nearest density at or above the screen's
+   `devicePixelRatio` (else the densest there is);
+2. else a **scalable** file (the logo's SVG);
+3. else the **narrowest** file at least `size × density` pixels wide, else the widest.
+
+With no `size`, you get the scalable file, or else the widest. Pass `density` to override the
+screen's ratio, for example `density: 3` for a canvas or a texture you scale down yourself. Pass
+`theme: 'light'` or `'dark'` to prefer a file drawn for that theme; files for the other theme are
+never picked, and a file rendered for your exact `size` still beats one drawn for your theme at
+another size. Every file today serves both.
+
+```js
+// A 20 CSS px Gems icon in an <img>, with every density for the browser to choose from.
+const gems = await gem.branding.currencyMark('GEMS', { size: 20 });
+if (gems.outcome === 'ok') {
+  const files = gems.asset.variants.filter((v) => v.size === 20);
+  icon.src = gems.url;
+  icon.srcset = files.map((v) => `${v.url} ${v.width}w`).join(', ');
+  icon.sizes = '20px';
+}
+```
+
+```js
+// The wordmark on a canvas or a WebGL texture: the platform's host allows any origin to read it.
+const wordmark = await gem.branding.wordmark({ size: 168, density: 3 });
+if (wordmark.outcome === 'ok') {
+  const img = new Image();
+  img.crossOrigin = 'anonymous'; // before src, or the canvas is tainted
+  img.src = wordmark.url;
+  await img.decode();
+  ctx.drawImage(img, x, y, 168, 88);
+}
+```
+
+## 4. When the manifest cannot be read: the bundled copy
+
+The SDK package still ships the Gems, Coins and trophy marks under `brand/`
+([brand-art.md](brand-art.md) §4). **They are the fallback for `unavailable`**, not the art to draw
+first: a file bundled in your build is the mark as it was when you built, and the platform's is the
+mark as it is now.
+
+```js
+import gemsIcon from '@indiegems/gem-web-sdk/brand/gem-icon-20-2x.png';
+
+const gems = await gem.branding.currencyMark('GEMS', { size: 20 });
+if (gems.outcome === 'ok') icon.src = gems.url;
+else if (gems.outcome === 'unavailable') icon.src = gemsIcon; // the platform could not be reached
+```
+
+There is no bundled logo or wordmark. When `logo()` or `wordmark()` is `unavailable`, lay the screen
+out so it reads correctly without it.
+
+## 5. Your page's Content-Security-Policy
+
+The platform does not restrict what your game fetches. If your own page sets a
+Content-Security-Policy (a `<meta>` tag in your `index.html`), allow `https://gemarcade.com`,
+where the manifest and every file it lists are served:
+
+- in **`connect-src`**, for the manifest. Without it every lookup is `unavailable`, and the SDK says
+  so once on the console;
+- in each kind's own directive for the files you draw: **`img-src`** for images, **`media-src`**
+  for audio, **`font-src`** for fonts.
+
+[arcade-and-store.md](arcade-and-store.md#the-media-hosts) lists the hosts the Arcade's card art comes
+from, beside this one.
+
+## 6. Using the logo and the wordmark
+
+- **Draw them as served:** never recoloured, stretched, rotated, cropped, outlined or given effects,
+  and never rebuilt from another font or file.
+- **Keep clear space** around each, at least a quarter of its height, free of text, buttons and
+  other art.
+- **Not smaller than the Arcade draws them:** the wordmark 60 CSS px wide, the gem logo 32 CSS px.
+  Below that the gem's facets blur together.
+- **On a busy background,** put them on a plain panel rather than over art.
+- **The wordmark is the product's name written as a logo.** Never set "Gem Arcade" in a text face
+  beside the gem in its place.
+- **The currency marks stand for the platform's currencies only:** the Gems mark beside a Gems
+  amount, never for your own currency ([brand-art.md](brand-art.md) §5).
+- **Never inside a panel dressed as the Arcade's own screens.** A player must always be able to tell
+  your game from the platform.

package/docs/changelog.md

@@ -16,6 +16,32 @@ 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.3.0
+
+Upgrading from 16.2.0. Impact: none.
+
+### New capability
+
+- Games can now read the platform's branding manifest at run time through Gem.branding. A game can show the platform logo, the Arcade wordmark, the currency marks and the trophy, and a branding change on the platform reaches the game with no SDK update or republish. The manifest is read once on the first call and all callers share that read. A lookup by id and kind resolves to one of three outcomes: ok, with the URL, the chosen variant and the whole asset; not_found, when the manifest does not list that id or kind; or unavailable, when the manifest could not be read. In the unavailable case, draw your bundled brand copy instead. Only a bad argument rejects. A list call resolves every asset. You can pass the size you will draw and an optional theme, and the SDK picks the best-matching variant. Nothing is required of existing games.
+
+## 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.3.0"
 }
 ```
 

package/docs/manifest.json

@@ -18,8 +18,8 @@
     },
     {
       "file": "arcade-and-store.md",
-      "sha256": "35d71f81775c0e7b05c84626bbe8365b624a60fb751abe2a2b3126ba554f33ab",
-      "updated": "2026-10-28T21:07:26Z"
+      "sha256": "d792225c078f9488e3c67f2fe4af1128f7f742ee829173dcd014b03e11eb32f0",
+      "updated": "2026-10-29T20:35:07Z"
     },
     {
       "file": "arcade-avatars.md",
@@ -38,13 +38,18 @@
     },
     {
       "file": "brand-art.md",
-      "sha256": "6d51ae596f6b43fb79058412ab8b10922829dd4e37631ca42f9063d5f43b5029",
-      "updated": "2026-10-25T16:18:07Z"
+      "sha256": "99ef1d5703bca12128b38db8352a102e11444de82903a73973942f074da4fc74",
+      "updated": "2026-10-29T20:35:07Z"
+    },
+    {
+      "file": "branding.md",
+      "sha256": "f22bd82245e6c4a74025884bfda54e35405e990661c84e5857d5e424e182e61d",
+      "updated": "2026-10-29T20:56:53Z"
     },
     {
       "file": "changelog.md",
-      "sha256": "085828e2eb6fdb752c8e2fd65e8110d31cdf1322e210a199f85a2e8bb17ba4d3",
-      "updated": "2026-10-29T18:42:12Z"
+      "sha256": "600e6a0c79c48d4fa82e0993eac822df6629ab737ec6053eafab19c743ea19b8",
+      "updated": "2026-10-29T21:40:20Z"
     },
     {
       "file": "daily-challenges.md",
@@ -73,8 +78,8 @@
     },
     {
       "file": "getting-started.md",
-      "sha256": "4344ccdf72a10cf7dddf2323d528240638bc88a14f742840a571ed347df5cb92",
-      "updated": "2026-10-29T18:42:12Z"
+      "sha256": "50f47be4de5a38a04e49cf1e864f66f8eab4739d8658d6984bb85c61400a0893",
+      "updated": "2026-10-29T21:40:20Z"
     },
     {
       "file": "inventory-and-catalogs.md",
@@ -128,13 +133,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": "721aeb9ac64b9564477a5dffb3b5cc70d6d0c1b222d79ab7090413a0f9b4ef5a",
+      "updated": "2026-10-29T21:40:20Z"
     },
     {
       "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.3.0/gem-web-sdk.tgz
+curl -fsSL https://downloads.gemarcade.com/sdk/v16.3.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.3.0",
   "description": "postMessage bridge contract between gem-web and browser-playable games",
   "license": "UNLICENSED",
   "type": "module",