@indiegems/gem-web-sdk 16.1.0 → 16.3.0

package/docs/api/api-reference-game.md

@@ -1,6 +1,6 @@
 # The browser surface — API reference
 
-Generated from `@indiegems/gem-web-sdk/sdk` v16.1.0, the version of the package this file ships in. Every symbol below carries an explicit anchor, its `anchor` in `reference.json` beside this file.
+Generated from `@indiegems/gem-web-sdk/sdk` v16.3.0, the version of the package this file ships in. Every symbol below carries an explicit anchor, its `anchor` in `reference.json` beside this file.
 
 `@indiegems/gem-web-sdk/sdk` is the one import a game writes, wherever its code runs. `@indiegems/gem-web-sdk/game` exports exactly the symbols on this page and nothing else, for a build that wants only this half.
 
@@ -2085,9 +2085,11 @@ readonly etag: string
 
 This save's version, which changes whenever the save does.
 
-NOT something to pass back on a write — a write pins the version it is
-replacing on its own. This is how a game holding a copy tells whether the
-stored save is still the one it has.
+NOT something to pass back on a write — the SDK remembers the version of
+each slot you last loaded or wrote and sends it for you, so a write that
+would replace a save you never saw is refused as `save_conflict`. This is
+how a game holding a copy tells whether the stored save is still the one
+it has.
 
 <a id="saverecord-metadata"></a>
 
@@ -2180,7 +2182,7 @@ has already agreed to the write. Re-read before assuming what is stored.
 ## GemSaveError.reason
 
 ```ts
-readonly reason: "upload_failed" | "download_failed" | "save_timeout" | "save_malformed"
+readonly reason: "upload_failed" | "download_failed" | "save_timeout" | "save_malformed" | "save_conflict" | "load_failed"
 ```
 
 Which part failed.
@@ -2190,15 +2192,31 @@ Which part failed.
 - `save_timeout` — a hop did not finish in the time the call allows.
 - `save_malformed` — the answer, or the stored payload, was not what it
   claims to be.
+- `save_conflict` — a write was refused because the stored save changed
+  since this game last loaded or wrote it: another device or tab saved
+  in between. Nothing was written.
+- `load_failed` — a write was refused before anything was sent, because
+  the last load of this slot failed, so what the write would replace is
+  unknown — it could be the player's real progress.
 
 `save_timeout`, and a one-off `upload_failed` or `download_failed`, are
 worth one retry. `save_malformed` is not: the same bytes will fail the
 same way.
 
+Neither is `save_conflict` or `load_failed`: resending the same write
+fails the same way. Load the slot again and decide what to write from
+what is stored — merge, or ask the player. Pass `overwrite: true` only to
+replace whatever is stored on purpose.
+
 An `upload_failed` that repeats on EVERY save, for every player, is not
 transient either — it is a platform-side misconfiguration, and retrying
 is a loop rather than a recovery. See the saves guide.
 
+A RATE LIMIT IS NOT ONE OF THESE. Refused for the rate on any leg — the
+platform, the upload, the download — a save or load rejects as
+`GemApiError` reason `rate_limited`, with `retryAfterSeconds` when a wait
+was named.
+
 <a id="putsaveoptions"></a>
 
 ## PutSaveOptions
@@ -2239,6 +2257,10 @@ Cancel the write.
 A save is several hops, so a cancelled write can land after the platform
 has already agreed to it. Re-read rather than assuming nothing was stored.
 
+A write that replaced earlier ones still waiting on its slot carries them,
+so cancelling it before it goes out cancels them too. Cancelling a write
+that a later one replaced rejects only this call; the later write goes on.
+
 <a id="putsaveoptions-timeoutms"></a>
 
 ## PutSaveOptions.timeoutMs
@@ -2261,6 +2283,68 @@ to do something about it.
 It does not make a save faster. Three round trips plus the payload is what
 a save costs; this only decides when to stop waiting.
 
+It counts from the call, so a write waiting for the one before it on the
+same slot spends it waiting. A rate limit whose wait it will not cover
+rejects at once as `GemApiError` reason `rate_limited`, not as
+`save_timeout`.
+
+It stays this call's when a later write replaces this one: running out
+rejects only this call, and the later write goes on. The write that is
+sent runs on the newest call's `timeoutMs`, and running out of that rejects
+every call it carries.
+
+<a id="putsaveoptions-teardown"></a>
+
+## PutSaveOptions.teardown
+
+```ts
+readonly teardown?: boolean
+```
+
+This is the last write before the page goes away: send it without waiting
+for the spacing between writes to one slot.
+
+Writes to one slot go out a few seconds apart, and a write made sooner
+waits its turn. Set this on the write you make from
+[GemTerminationNotice](#gemterminationnotice) or `pagehide`, with a `timeoutMs` inside the
+time you have.
+
+IT STILL WAITS FOR A WRITE ALREADY IN FLIGHT to the same slot, and it
+still honours a rate-limit hold: when the hold outlasts `timeoutMs` the
+write rejects at once as `rate_limited`, and nothing is sent. Not for
+ordinary saves — the spacing is what keeps a save loop from spending the
+rate limit.
+
+A later write that replaces this one while it waits keeps it: the write
+that goes out skips the spacing when any call it carries set `teardown`.
+Not across a player change: a call replaced after the signed-in player
+changed is refused as `save_conflict`, and its `teardown` goes with it.
+
+<a id="putsaveoptions-overwrite"></a>
+
+## PutSaveOptions.overwrite
+
+```ts
+readonly overwrite?: boolean
+```
+
+Write even if it replaces a save this game has not loaded.
+
+Without it, a write to a slot whose last load FAILED is refused as
+`load_failed`, and a write is refused as `save_conflict` when the stored
+save changed since you last loaded or wrote it. Both refusals protect the
+player's real progress from a game that started from defaults.
+
+Set it only when replacing whatever is stored is what you mean — a "new
+game" the player confirmed, or the player choosing this device's progress
+after a conflict. Never set it to get past a failed load.
+
+A later write that replaces this one while it waits keeps it: the write
+that goes out overwrites when any call it carries set `overwrite`. A call
+that gives up first (its `signal` or `timeoutMs`) takes it back, and so
+does one replaced after the signed-in player changed: it is refused as
+`save_conflict`, so one player's "new game" never overwrites the next's.
+
 <a id="putbytesoptions"></a>
 
 ## PutBytesOptions
@@ -2304,6 +2388,10 @@ Cancel the write.
 A save is several hops, so a cancelled write can land after the platform
 has already agreed to it. Re-read rather than assuming nothing was stored.
 
+A write that replaced earlier ones still waiting on its slot carries them,
+so cancelling it before it goes out cancels them too. Cancelling a write
+that a later one replaced rejects only this call; the later write goes on.
+
 <a id="putbytesoptions-timeoutms"></a>
 
 ## PutBytesOptions.timeoutMs
@@ -2326,6 +2414,68 @@ to do something about it.
 It does not make a save faster. Three round trips plus the payload is what
 a save costs; this only decides when to stop waiting.
 
+It counts from the call, so a write waiting for the one before it on the
+same slot spends it waiting. A rate limit whose wait it will not cover
+rejects at once as `GemApiError` reason `rate_limited`, not as
+`save_timeout`.
+
+It stays this call's when a later write replaces this one: running out
+rejects only this call, and the later write goes on. The write that is
+sent runs on the newest call's `timeoutMs`, and running out of that rejects
+every call it carries.
+
+<a id="putbytesoptions-teardown"></a>
+
+## PutBytesOptions.teardown
+
+```ts
+readonly teardown?: boolean
+```
+
+This is the last write before the page goes away: send it without waiting
+for the spacing between writes to one slot.
+
+Writes to one slot go out a few seconds apart, and a write made sooner
+waits its turn. Set this on the write you make from
+[GemTerminationNotice](#gemterminationnotice) or `pagehide`, with a `timeoutMs` inside the
+time you have.
+
+IT STILL WAITS FOR A WRITE ALREADY IN FLIGHT to the same slot, and it
+still honours a rate-limit hold: when the hold outlasts `timeoutMs` the
+write rejects at once as `rate_limited`, and nothing is sent. Not for
+ordinary saves — the spacing is what keeps a save loop from spending the
+rate limit.
+
+A later write that replaces this one while it waits keeps it: the write
+that goes out skips the spacing when any call it carries set `teardown`.
+Not across a player change: a call replaced after the signed-in player
+changed is refused as `save_conflict`, and its `teardown` goes with it.
+
+<a id="putbytesoptions-overwrite"></a>
+
+## PutBytesOptions.overwrite
+
+```ts
+readonly overwrite?: boolean
+```
+
+Write even if it replaces a save this game has not loaded.
+
+Without it, a write to a slot whose last load FAILED is refused as
+`load_failed`, and a write is refused as `save_conflict` when the stored
+save changed since you last loaded or wrote it. Both refusals protect the
+player's real progress from a game that started from defaults.
+
+Set it only when replacing whatever is stored is what you mean — a "new
+game" the player confirmed, or the player choosing this device's progress
+after a conflict. Never set it to get past a failed load.
+
+A later write that replaces this one while it waits keeps it: the write
+that goes out overwrites when any call it carries set `overwrite`. A call
+that gives up first (its `signal` or `timeoutMs`) takes it back, and so
+does one replaced after the signed-in player changed: it is refused as
+`save_conflict`, so one player's "new game" never overwrites the next's.
+
 <a id="putbytesoptions-contenttype"></a>
 
 ## PutBytesOptions.contentType
@@ -2368,6 +2518,20 @@ await gem.me.saves.put('slot1', { level: 7, checkpoint: 'bridge' });
 const state = await gem.me.saves.get('slot1');
 ```
 
+LOAD BEFORE YOU SAVE. Each write carries the version of the slot your last
+load or write found, so a write that would replace a save this game has not
+seen — another device's, or the player's real progress after a load that
+failed — is refused as `save_conflict` or `load_failed` rather than stored.
+After a failed load, play on without saving and load again later; pass
+`overwrite: true` only when the player chose to start over.
+
+ONE WRITE PER SLOT AT A TIME. A write made while another to the same slot is
+in flight waits for it, and a later one replaces it: the newest value is the
+one sent, and every caller it replaced resolves with it, keeping its own
+`signal`, `timeoutMs`, `teardown` and `overwrite`. Writes to one slot
+go out a few seconds apart (`teardown: true` skips that), and after a
+`rate_limited` answer none goes out until the wait it named is over.
+
 WHAT IS DELIBERATELY NOT HERE: no autosave timer, no save format, no
 migration. Those are your game's, and a platform that guessed at them would
 guess wrong.
@@ -5423,6 +5587,406 @@ only if you are instrumenting something that runs before the SDK exists.
 | --- | --- |
 | `options` | `BootTimelineOptions` |
 
+<a id="brandingtheme"></a>
+
+## BrandingTheme
+
+```ts
+type BrandingTheme = "light" | "dark"
+```
+
+A theme a variant is drawn for.
+
+<a id="brandingvariant"></a>
+
+## BrandingVariant
+
+```ts
+interface BrandingVariant
+```
+
+One file of a [BrandingAsset](#brandingasset): a render at one size and density, a
+scalable image, or the one file of a sound or a font.
+
+<a id="brandingvariant-url"></a>
+
+## BrandingVariant.url
+
+```ts
+readonly url: string
+```
+
+The file's URL, absolute and on the platform's own host. Content-hashed,
+so a re-render is a new URL: look it up each session rather than storing
+one in a save or your build.
+
+<a id="brandingvariant-type"></a>
+
+## BrandingVariant.type
+
+```ts
+readonly type: string
+```
+
+Its MIME type, such as `image/png` or `image/svg+xml`.
+
+<a id="brandingvariant-bytes"></a>
+
+## BrandingVariant.bytes
+
+```ts
+readonly bytes: number
+```
+
+Its size in bytes.
+
+<a id="brandingvariant-width"></a>
+
+## BrandingVariant.width
+
+```ts
+readonly width?: number
+```
+
+An image's width in pixels (an SVG's in its viewBox units).
+
+<a id="brandingvariant-height"></a>
+
+## BrandingVariant.height
+
+```ts
+readonly height?: number
+```
+
+An image's height in pixels (an SVG's in its viewBox units).
+
+<a id="brandingvariant-size"></a>
+
+## BrandingVariant.size
+
+```ts
+readonly size?: number
+```
+
+The CSS px box this render was made for, with [BrandingVariant.density](#brandingvariant-density).
+Absent on a render meant for any box up to its width.
+
+<a id="brandingvariant-density"></a>
+
+## BrandingVariant.density
+
+```ts
+readonly density?: number
+```
+
+Device pixels per CSS px of a render made for [BrandingVariant.size](#brandingvariant-size).
+
+<a id="brandingvariant-vector"></a>
+
+## BrandingVariant.vector
+
+```ts
+readonly vector?: true
+```
+
+`true` on a scalable image: it draws crisply at any size.
+
+<a id="brandingvariant-theme"></a>
+
+## BrandingVariant.theme
+
+```ts
+readonly theme?: BrandingTheme
+```
+
+The one theme the file is for. Absent: either theme.
+
+<a id="brandingasset"></a>
+
+## BrandingAsset
+
+```ts
+interface BrandingAsset
+```
+
+One asset in the platform's branding manifest.
+
+<a id="brandingasset-id"></a>
+
+## BrandingAsset.id
+
+```ts
+readonly id: string
+```
+
+What a game asks for: `'gem-logo'`, `'gems-mark'`. Never renamed.
+
+<a id="brandingasset-kind"></a>
+
+## BrandingAsset.kind
+
+```ts
+readonly kind: string
+```
+
+`'image'`, `'audio'` or `'font'` today. The platform may add more, so
+compare it rather than switching on it exhaustively.
+
+<a id="brandingasset-variants"></a>
+
+## BrandingAsset.variants
+
+```ts
+readonly variants: readonly BrandingVariant[]
+```
+
+Every file of it, smallest first. Never empty.
+
+<a id="brandinglookup"></a>
+
+## BrandingLookup
+
+```ts
+type BrandingLookup = { outcome: "ok"; url: string; variant: BrandingVariant; asset: BrandingAsset } | { outcome: "not_found" | "unavailable" }
+```
+
+What a branding lookup resolves with. Only `ok` carries a URL.
+
+- `ok`: the platform has it, and `url` is the file picked for what you asked.
+- `not_found`: the manifest was read and has no asset with that id and kind,
+  or none of its files fits the theme you asked for. Draw nothing for it.
+- `unavailable`: the manifest could not be read — offline, a network error,
+  a Content-Security-Policy that leaves out `https://gemarcade.com`. Draw the
+  copy you bundled from the package's `brand/` folder, if there is one.
+
+<a id="brandinglist"></a>
+
+## BrandingList
+
+```ts
+type BrandingList = { outcome: "ok"; assets: readonly BrandingAsset[] } | { outcome: "unavailable" }
+```
+
+What [BrandingApi.list](#brandingapi-list) resolves with.
+
+<a id="brandingimageoptions"></a>
+
+## BrandingImageOptions
+
+```ts
+interface BrandingImageOptions
+```
+
+How to pick one image from an asset's variants.
+
+<a id="brandingimageoptions-size"></a>
+
+## BrandingImageOptions.size
+
+```ts
+readonly size?: number
+```
+
+The CSS px box you draw it in. A render made for exactly that box wins;
+then a scalable image; then the narrowest render wide enough for
+`size × density`. Leave it out for the largest: the scalable image, or
+else the widest render.
+
+<a id="brandingimageoptions-density"></a>
+
+## BrandingImageOptions.density
+
+```ts
+readonly density?: number
+```
+
+Device pixels per CSS px. Defaults to the screen's `devicePixelRatio`;
+pass `3` for a canvas or texture you scale down yourself.
+
+<a id="brandingimageoptions-theme"></a>
+
+## BrandingImageOptions.theme
+
+```ts
+readonly theme?: BrandingTheme
+```
+
+Prefer a file drawn for this theme. Files for the other theme are never picked.
+
+<a id="brandingassetoptions"></a>
+
+## BrandingAssetOptions
+
+```ts
+interface BrandingAssetOptions
+```
+
+What [BrandingApi.get](#brandingapi-get) takes: the asset's kind, and how to pick a file.
+
+<a id="brandingassetoptions-size"></a>
+
+## BrandingAssetOptions.size
+
+```ts
+readonly size?: number
+```
+
+The CSS px box you draw it in. A render made for exactly that box wins;
+then a scalable image; then the narrowest render wide enough for
+`size × density`. Leave it out for the largest: the scalable image, or
+else the widest render.
+
+<a id="brandingassetoptions-density"></a>
+
+## BrandingAssetOptions.density
+
+```ts
+readonly density?: number
+```
+
+Device pixels per CSS px. Defaults to the screen's `devicePixelRatio`;
+pass `3` for a canvas or texture you scale down yourself.
+
+<a id="brandingassetoptions-theme"></a>
+
+## BrandingAssetOptions.theme
+
+```ts
+readonly theme?: BrandingTheme
+```
+
+Prefer a file drawn for this theme. Files for the other theme are never picked.
+
+<a id="brandingassetoptions-kind"></a>
+
+## BrandingAssetOptions.kind
+
+```ts
+readonly kind: string
+```
+
+The kind you expect: `'image'`, `'audio'` or `'font'`. An asset of another
+kind answers `not_found`. `size` and `density` apply to images only; for
+any other kind the first file wins.
+
+<a id="brandingcurrency"></a>
+
+## BrandingCurrency
+
+```ts
+type BrandingCurrency = "GEMS" | "ARCADE_TICKETS"
+```
+
+The platform currencies with a mark: Gems and Coins.
+
+<a id="brandingapi"></a>
+
+## BrandingApi
+
+```ts
+interface BrandingApi
+```
+
+The platform's branding, as the platform serves it now. `gem.branding` is
+one of these. Nothing here rejects but a bad argument.
+
+<a id="brandingapi-get"></a>
+
+## BrandingApi.get
+
+```ts
+get(id: string, options: BrandingAssetOptions): Promise<BrandingLookup>
+```
+
+Any asset in the platform's branding manifest, by id and kind — including
+ones added after this SDK was released.
+
+```js
+const logo = await gem.branding.get('gem-logo', { kind: 'image', size: 64 });
+if (logo.outcome === 'ok') img.src = logo.url;
+```
+
+| Parameter | Type |
+| --- | --- |
+| `id` | `string` |
+| `options` | `BrandingAssetOptions` |
+
+**Returns.** Resolves `ok`, `not_found` or `unavailable`. Rejects only for an
+  argument that is not one (an empty id, a size that is not a positive
+  number).
+
+<a id="brandingapi-logo"></a>
+
+## BrandingApi.logo
+
+```ts
+logo(options?: BrandingImageOptions): Promise<BrandingLookup>
+```
+
+The Indie Gems logo, the brand gem. Scalable: draw it at 32 CSS px or more,
+as served (`docs/branding.md` has the usage rules).
+
+| Parameter | Type |
+| --- | --- |
+| `options` | `BrandingImageOptions` |
+
+<a id="brandingapi-wordmark"></a>
+
+## BrandingApi.wordmark
+
+```ts
+wordmark(options?: BrandingImageOptions): Promise<BrandingLookup>
+```
+
+The Gem Arcade wordmark. Draw it at 60 CSS px wide or more, as served.
+
+| Parameter | Type |
+| --- | --- |
+| `options` | `BrandingImageOptions` |
+
+<a id="brandingapi-currencymark"></a>
+
+## BrandingApi.currencyMark
+
+```ts
+currencyMark(currency: BrandingCurrency, options?: BrandingImageOptions): Promise<BrandingLookup>
+```
+
+The mark of a platform currency, by its slug: `'GEMS'` or
+`'ARCADE_TICKETS'` (Coins). Pass `size: 20` or `32` for the inline icon
+beside an amount, or leave it out for the hero art of a reward screen.
+`docs/brand-art.md` says where each may be drawn.
+
+| Parameter | Type |
+| --- | --- |
+| `currency` | `BrandingCurrency` |
+| `options` | `BrandingImageOptions` |
+
+<a id="brandingapi-trophy"></a>
+
+## BrandingApi.trophy
+
+```ts
+trophy(options?: BrandingImageOptions): Promise<BrandingLookup>
+```
+
+The trophy, for where your game shows what a player has achieved.
+
+| Parameter | Type |
+| --- | --- |
+| `options` | `BrandingImageOptions` |
+
+<a id="brandingapi-list"></a>
+
+## BrandingApi.list
+
+```ts
+list(): Promise<BrandingList>
+```
+
+Every asset the platform serves, or `unavailable` when the manifest could
+not be read.
+
 <a id="listchallengesoptions"></a>
 
 ## ListChallengesOptions
@@ -10652,6 +11216,31 @@ exactly as given, and call `purchase(skuId)` from the player's press. After
 
 **Guides.** [arcade-and-store](../arcade-and-store.md)
 
+<a id="gem-branding"></a>
+
+## Gem.branding
+
+```ts
+readonly branding: BrandingApi
+```
+
+The platform's branding — the Indie Gems logo, the Gem Arcade wordmark,
+the Gems and Coins marks and the trophy — as the platform serves it now,
+so a changed mark reaches your game with no republish.
+
+Look up any asset by id and kind with `get`, or use `logo`, `wordmark`,
+`currencyMark` and `trophy`. Every URL is on the platform's own host.
+Nothing rejects but a bad argument: an asset the platform does not list is
+`not_found`, and a manifest that could not be read is `unavailable`, when
+you draw the copy you bundled from `brand/` instead.
+
+```js
+const logo = await gem.branding.logo();
+if (logo.outcome === 'ok') menuLogo.src = logo.url;
+```
+
+**Guides.** [branding](../branding.md)
+
 <a id="gem-avatarpickeravailable"></a>
 
 ## Gem.avatarPickerAvailable

package/docs/api/api-reference-server.md

@@ -1,6 +1,6 @@
 # The server surface — API reference
 
-Generated from `@indiegems/gem-web-sdk/sdk` v16.1.0, the version of the package this file ships in. Every symbol below carries an explicit anchor, its `anchor` in `reference.json` beside this file.
+Generated from `@indiegems/gem-web-sdk/sdk` v16.3.0, the version of the package this file ships in. Every symbol below carries an explicit anchor, its `anchor` in `reference.json` beside this file.
 
 `@indiegems/gem-web-sdk/sdk` is the one import a game writes, wherever its code runs. `@indiegems/gem-web-sdk/server` exports exactly the symbols on this page and nothing else, for a build that wants only this half.