@indiegems/gem-web-sdk 16.2.0 → 16.3.1

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

@@ -1,6 +1,6 @@
 # The browser surface — API reference
 
-Generated from `@indiegems/gem-web-sdk/sdk` v16.2.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.1, 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.
 
@@ -4590,7 +4590,7 @@ interface StoreApi
 ```
 
 **Real money.** The Arcade Store's own Gem packs, Boosts, passes and bundles,
-bought with the player's money through the arcade's own purchase sheet.
+bought with the player's money through the Arcade Store's own checkout.
 `gem.store` is one of these. To spend Gems or Coins on your game's own items,
 use `gem.purchases`.
 
@@ -4628,20 +4628,24 @@ is withheld. Re-read on resume: what is on sale can change.
 purchase(skuId: string): Promise<ArcadeOutcome>
 ```
 
-Ask the arcade to open its store's purchase sheet for one SKU from
-[StoreApi.offers](#storeapi-offers). **Call it from the player's press handler** — the
+Ask the arcade to open checkout for one SKU from [StoreApi.offers](#storeapi-offers):
+the payment provider's page on the web, the app store's purchase sheet in
+the Arcade's apps, straight away, with no confirmation screen of the
+arcade's own first. **Call it from the player's press handler** — the
 arcade refuses an ask no person pressed for, `declined` / `busy`.
 
 - `ok` — the player paid. Re-read balances and inventory through `gem.me`;
   nothing here carries an amount. With `reason: 'pending'`, the provider
   has not settled yet: [StoreApi.onSettled](#storeapi-onsettled) hears when it does.
-- `declined` — nothing was bought: `cancelled` (the player said no) or
-  `busy`. Return to your screen silently, and do not ask again unprompted.
+- `declined` — nothing was bought: `cancelled` (the player closed the
+  checkout, or the offer cannot be bought again yet) or `busy` (after a
+  closed checkout the arcade refuses the next ask for a while). Return to
+  your screen silently, and do not ask again unprompted.
 - `unavailable` with `store_off`, `sign_in_required`, `not_found`,
   `unsupported`, `invalid_argument` or a payment provider's failure code —
   nothing was bought.
 - `unavailable` / `error` — **the outcome is unknown, and the player may
-  have paid.** It is what you get when the bridge closes while the sheet
+  have paid.** It is what you get when the bridge closes while checkout
   is open, or the arcade has no reliable answer. Never tell the player
   nothing was bought: re-read balances and inventory through `gem.me`,
   and keep listening with [StoreApi.onSettled](#storeapi-onsettled).
@@ -5587,6 +5591,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
@@ -10078,9 +10482,9 @@ readonly reserved: readonly GemReservedArea[]
 ```
 
 Rectangles of your frame the arcade's own controls cover — in the Gem
-Arcade, its Gem button in whichever corner it sits, and the frame-rate readout
-beside it while the player shows it; an embedder that draws wallets over
-your game adds theirs (see `setWalletVisible`). Keep essential UI and touch
+Arcade, its Gem button in whichever corner it sits, the frame-rate readout
+beside it while the player shows it, and the wallets beside it while your
+game asks for them (see `setWalletVisible`). Keep essential UI and touch
 targets out of them. Empty when the arcade covers nothing.
 
 Each is a keep-out area, grown out to the frame edges it sits nearest — not
@@ -10229,10 +10633,10 @@ readonly only?: readonly string[]
 
 While shown, show ONLY these: platform currency slugs as
 `gem.platform.currencies.get()` lists them (`GEMS`, `ARCADE_TICKETS`),
-matched exactly, and the literal `'score'` for the achievement score. Only
-for a screen about one currency, such as a Coins store; leave it out and
-every wallet shows, which is always safe. The Gem Arcade draws no wallet
-over a game, so it has nothing to narrow and ignores it.
+matched exactly, and the literal `'score'` for the achievement score. Leave
+it out and every wallet shows, the achievement score's included. The Gem
+Arcade honours it: `{ only: ['GEMS', 'ARCADE_TICKETS'] }` shows those two
+and no achievement score; a slug the platform does not serve names nothing.
 
 <a id="gamemenuitem"></a>
 
@@ -10288,7 +10692,8 @@ interface GameMenu
 ```
 
 What your game adds to the arcade's menu — see `gem.setMenu`. Your settings
-are not part of it: they open from your own settings button.
+screen is not part of it: it opens from your own settings button. An action
+on that screen (Replay the tutorial, How to play) may also be an entry here.
 
 <a id="gamemenu-items"></a>
 
@@ -10816,6 +11221,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
@@ -11371,9 +11801,10 @@ Tell the arcade a platform-currency reward is on its way, so it **shows it
 landing**: in the Gem Arcade the currency flies from `origin` into the Gem
 button, wherever on your frame it sits, which pops as each mark lands, and
 the player's total moves once the platform confirms the grant. The Gem
-Arcade draws no wallet over your game: the player sees their Gems and
-Coins in the Gem menu. A payout you do not cue still flies, from the
-middle of your frame, so cue the ones the player earns on screen.
+Arcade draws no wallet over your game unless you ask (`setWalletVisible`):
+the player sees their Gems and Coins in the Gem menu. A payout you do not
+cue still flies, from the middle of your frame, so cue the ones the player
+earns on screen.
 
 Call it the moment your game decides to award — when your server has moved
 (or is about to move) the progression mapped onto a platform currency —
@@ -11418,26 +11849,25 @@ landed — which it does on every channel, dev and test included.
 setWalletVisible(visible: boolean, options?: WalletVisibleOptions): boolean
 ```
 
-Show or hide the player's wallets — Gems, Coins, the achievement score —
-that an embedder draws over your game.
+Ask the arcade to show, or stop showing, the player's wallets — Gems,
+Coins, the achievement score — over your game.
 
-**The Gem Arcade draws no wallet over a game** (since 2026-10-11): the
-player sees their balances in the Gem menu, and payouts fly into the Gem
-button. So under the Gem Arcade this changes nothing on screen — it is
-accepted and harmless, and a game that already calls it keeps working.
-Call it for an embedder that does draw wallets over your game: hide them
-while you play, show them on your menus.
+**The Gem Arcade draws them on request** (the owner, 2026-10-29): a game
+that says nothing gets no wallet over it, as since 2026-10-11, and the
+player sees their balances in the Gem menu; a game that asks gets them
+drawn beside the Gem, from the platform's own figures. An Arcade from
+before that ignores the call, harmlessly.
 
 ```js
-level.onStart = () => gem.setWalletVisible(false);
-menu.onOpen = () => gem.setWalletVisible(true);
+gem.setWalletVisible(true, { only: ['GEMS', 'ARCADE_TICKETS'] }); // every screen
+level.onStart = () => gem.setWalletVisible(false); // or put them away during play
 ```
 
 **It is screen state, not a toggle.** Each call is the whole answer and
-replaces the last. Where an embedder draws wallets, shown ones arrive as
-rectangles in `gem.viewport.reserved` and hiding them gives that space
-back; the Gem Arcade sends none for wallets. `only` narrows what shows,
-where an embedder honours it; the Gem Arcade does not.
+replaces the last. Shown wallets arrive as rectangles in
+`gem.viewport.reserved` (and widen the Gem's corner in the
+`--gem-reserved-*` variables), and hiding them gives that space back.
+`only` narrows what shows.
 
 **Never draw a platform balance yourself**, and never show a pending state
 for one: the arcade takes every figure from the platform. If this returns
@@ -11470,10 +11900,14 @@ gem.setMenu({
 });
 ```
 
-**Your settings are not in it: draw your own settings button, always** —
+**Your settings screen is not in it: draw your own settings button** —
 top-right, with your Back button just to its left, clear of
 `gem.viewport.reserved`. The Arcade's menu never opens your settings
-screen.
+screen. Inside the Gem Arcade you may leave the button out while this
+returns `true`, when every setting on your screen is declared with
+`gem.settings` and every action on it is one of these entries; it returns
+`false` before the bridge is up and under an embedder with no menu, and the
+button stays there.
 
 **It is screen state, not a toggle.** Each call is the whole answer and
 replaces the last, so call it again when the entries change — a new

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

@@ -1,6 +1,6 @@
 # The server surface — API reference
 
-Generated from `@indiegems/gem-web-sdk/sdk` v16.2.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.1, 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.