@indiegems/gem-web-sdk 16.2.0 → 16.3.1

package/docs/api/reference.json

@@ -2,7 +2,7 @@
   "schema_version": 2,
   "source": {
     "repo": "IndieGems/gem-web-sdk",
-    "version": "16.2.0"
+    "version": "16.3.1"
   },
   "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"
@@ -5508,7 +5512,7 @@
           "group": "store",
           "signature": "interface StoreApi",
           "documented": true,
-          "summary": "**Real money.** The Arcade Store's own Gem packs, Boosts, passes and bundles,\nbought with the player's money through the arcade's own purchase sheet.\n`gem.store` is one of these. To spend Gems or Coins on your game's own items,\nuse `gem.purchases`.",
+          "summary": "**Real money.** The Arcade Store's own Gem packs, Boosts, passes and bundles,\nbought with the player's money through the Arcade Store's own checkout.\n`gem.store` is one of these. To spend Gems or Coins on your game's own items,\nuse `gem.purchases`.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -5556,7 +5560,7 @@
           "group": "store",
           "signature": "purchase(skuId: string): Promise<ArcadeOutcome>",
           "documented": true,
-          "summary": "Ask the arcade to open its store's purchase sheet for one SKU from\n[StoreApi.offers](api-reference-game.md#storeapi-offers). **Call it from the player's press handler** — the\narcade refuses an ask no person pressed for, `declined` / `busy`.\n\n- `ok` — the player paid. Re-read balances and inventory through `gem.me`;\n  nothing here carries an amount. With `reason: 'pending'`, the provider\n  has not settled yet: [StoreApi.onSettled](api-reference-game.md#storeapi-onsettled) hears when it does.\n- `declined` — nothing was bought: `cancelled` (the player said no) or\n  `busy`. Return to your screen silently, and do not ask again unprompted.\n- `unavailable` with `store_off`, `sign_in_required`, `not_found`,\n  `unsupported`, `invalid_argument` or a payment provider's failure code —\n  nothing was bought.\n- `unavailable` / `error` — **the outcome is unknown, and the player may\n  have paid.** It is what you get when the bridge closes while the sheet\n  is open, or the arcade has no reliable answer. Never tell the player\n  nothing was bought: re-read balances and inventory through `gem.me`,\n  and keep listening with [StoreApi.onSettled](api-reference-game.md#storeapi-onsettled).\n\nNO TIMEOUT: it waits for as long as the arcade is connected, because a\npayment takes as long as it takes.",
+          "summary": "Ask the arcade to open checkout for one SKU from [StoreApi.offers](api-reference-game.md#storeapi-offers):\nthe payment provider's page on the web, the app store's purchase sheet in\nthe Arcade's apps, straight away, with no confirmation screen of the\narcade's own first. **Call it from the player's press handler** — the\narcade refuses an ask no person pressed for, `declined` / `busy`.\n\n- `ok` — the player paid. Re-read balances and inventory through `gem.me`;\n  nothing here carries an amount. With `reason: 'pending'`, the provider\n  has not settled yet: [StoreApi.onSettled](api-reference-game.md#storeapi-onsettled) hears when it does.\n- `declined` — nothing was bought: `cancelled` (the player closed the\n  checkout, or the offer cannot be bought again yet) or `busy` (after a\n  closed checkout the arcade refuses the next ask for a while). Return to\n  your screen silently, and do not ask again unprompted.\n- `unavailable` with `store_off`, `sign_in_required`, `not_found`,\n  `unsupported`, `invalid_argument` or a payment provider's failure code —\n  nothing was bought.\n- `unavailable` / `error` — **the outcome is unknown, and the player may\n  have paid.** It is what you get when the bridge closes while checkout\n  is open, or the arcade has no reliable answer. Never tell the player\n  nothing was bought: re-read balances and inventory through `gem.me`,\n  and keep listening with [StoreApi.onSettled](api-reference-game.md#storeapi-onsettled).\n\nNO TIMEOUT: it waits for as long as the arcade is connected, because a\npayment takes as long as it takes.",
           "deprecated": null,
           "params": [
             {
@@ -6626,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",
@@ -11432,7 +12027,7 @@
           "group": "player",
           "signature": "readonly reserved: readonly GemReservedArea[]",
           "documented": true,
-          "summary": "Rectangles of your frame the arcade's own controls cover — in the Gem\nArcade, its Gem button in whichever corner it sits, and the frame-rate readout\nbeside it while the player shows it; an embedder that draws wallets over\nyour game adds theirs (see `setWalletVisible`). Keep essential UI and touch\ntargets out of them. Empty when the arcade covers nothing.\n\nEach is a keep-out area, grown out to the frame edges it sits nearest — not\nthe control's own box, and not something to line anything up with. Where\nthe arcade says, `control` on each is the control itself.\n\nA stylesheet reads the per-corner custom properties the SDK stamps from\nthese instead — `--gem-reserved-tl-height` and friends, and\n`--gem-reserved-tl-center-y` to line a top bar up with the Gem.",
+          "summary": "Rectangles of your frame the arcade's own controls cover — in the Gem\nArcade, its Gem button in whichever corner it sits, the frame-rate readout\nbeside it while the player shows it, and the wallets beside it while your\ngame asks for them (see `setWalletVisible`). Keep essential UI and touch\ntargets out of them. Empty when the arcade covers nothing.\n\nEach is a keep-out area, grown out to the frame edges it sits nearest — not\nthe control's own box, and not something to line anything up with. Where\nthe arcade says, `control` on each is the control itself.\n\nA stylesheet reads the per-corner custom properties the SDK stamps from\nthese instead — `--gem-reserved-tl-height` and friends, and\n`--gem-reserved-tl-center-y` to line a top bar up with the Gem.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -11640,7 +12235,7 @@
           "group": "platform",
           "signature": "readonly only?: readonly string[]",
           "documented": true,
-          "summary": "While shown, show ONLY these: platform currency slugs as\n`gem.platform.currencies.get()` lists them (`GEMS`, `ARCADE_TICKETS`),\nmatched exactly, and the literal `'score'` for the achievement score. Only\nfor a screen about one currency, such as a Coins store; leave it out and\nevery wallet shows, which is always safe. The Gem Arcade draws no wallet\nover a game, so it has nothing to narrow and ignores it.",
+          "summary": "While shown, show ONLY these: platform currency slugs as\n`gem.platform.currencies.get()` lists them (`GEMS`, `ARCADE_TICKETS`),\nmatched exactly, and the literal `'score'` for the achievement score. Leave\nit out and every wallet shows, the achievement score's included. The Gem\nArcade honours it: `{ only: ['GEMS', 'ARCADE_TICKETS'] }` shows those two\nand no achievement score; a slug the platform does not serve names nothing.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -11720,7 +12315,7 @@
           "group": "frame",
           "signature": "interface GameMenu",
           "documented": true,
-          "summary": "What your game adds to the arcade's menu — see `gem.setMenu`. Your settings\nare not part of it: they open from your own settings button.",
+          "summary": "What your game adds to the arcade's menu — see `gem.setMenu`. Your settings\nscreen is not part of it: it opens from your own settings button. An action\non that screen (Replay the tutorial, How to play) may also be an entry here.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -12209,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",
@@ -12618,7 +13234,7 @@
           "group": "start",
           "signature": "cueReward(cue: RewardCue): boolean",
           "documented": true,
-          "summary": "Tell the arcade a platform-currency reward is on its way, so it **shows it\nlanding**: in the Gem Arcade the currency flies from `origin` into the Gem\nbutton, wherever on your frame it sits, which pops as each mark lands, and\nthe player's total moves once the platform confirms the grant. The Gem\nArcade draws no wallet over your game: the player sees their Gems and\nCoins in the Gem menu. A payout you do not cue still flies, from the\nmiddle of your frame, so cue the ones the player earns on screen.\n\nCall it the moment your game decides to award — when your server has moved\n(or is about to move) the progression mapped onto a platform currency —\nand pass the centre of that currency's icon (or hero) on your screen, so\nthe flight starts from the mark the player is looking at:\n\n```js\nconst { x, y, width, height } = rewardGem.getBoundingClientRect(); // the gem's own box\ngem.cueReward({\n  currencySlug: 'GEMS', // or 'ARCADE_TICKETS', from the coin\n  expected: 15,\n  origin: { x: x + width / 2, y: y + height / 2 },\n});\n```\n\n**This is the platform-currency animation, and the only one.** The display\nof every platform currency — Gems and Coins alike — belongs to the\narcade: a game draws no flight or celebration of its own for one and keeps\nno counter of one. **If this returns `false`, do nothing** — there is no\nfallback celebration.\n\n**The arcade never takes your word for the amount.** What lands, and the\nplayer's new total, come from the platform itself; `expected` is drawn as\nprovisional, and a cue the platform never confirms fades on its own — a\ngrant clamped to zero, say, or one the receipt reports `suppressed`. So\nthe cue can only ever make the wallet move for a reward that really\nlanded — which it does on every channel, dev and test included.",
+          "summary": "Tell the arcade a platform-currency reward is on its way, so it **shows it\nlanding**: in the Gem Arcade the currency flies from `origin` into the Gem\nbutton, wherever on your frame it sits, which pops as each mark lands, and\nthe player's total moves once the platform confirms the grant. The Gem\nArcade draws no wallet over your game unless you ask (`setWalletVisible`):\nthe player sees their Gems and Coins in the Gem menu. A payout you do not\ncue still flies, from the middle of your frame, so cue the ones the player\nearns on screen.\n\nCall it the moment your game decides to award — when your server has moved\n(or is about to move) the progression mapped onto a platform currency —\nand pass the centre of that currency's icon (or hero) on your screen, so\nthe flight starts from the mark the player is looking at:\n\n```js\nconst { x, y, width, height } = rewardGem.getBoundingClientRect(); // the gem's own box\ngem.cueReward({\n  currencySlug: 'GEMS', // or 'ARCADE_TICKETS', from the coin\n  expected: 15,\n  origin: { x: x + width / 2, y: y + height / 2 },\n});\n```\n\n**This is the platform-currency animation, and the only one.** The display\nof every platform currency — Gems and Coins alike — belongs to the\narcade: a game draws no flight or celebration of its own for one and keeps\nno counter of one. **If this returns `false`, do nothing** — there is no\nfallback celebration.\n\n**The arcade never takes your word for the amount.** What lands, and the\nplayer's new total, come from the platform itself; `expected` is drawn as\nprovisional, and a cue the platform never confirms fades on its own — a\ngrant clamped to zero, say, or one the receipt reports `suppressed`. So\nthe cue can only ever make the wallet move for a reward that really\nlanded — which it does on every channel, dev and test included.",
           "deprecated": null,
           "params": [
             {
@@ -12641,7 +13257,7 @@
           "group": "start",
           "signature": "setWalletVisible(visible: boolean, options?: WalletVisibleOptions): boolean",
           "documented": true,
-          "summary": "Show or hide the player's wallets — Gems, Coins, the achievement score —\nthat an embedder draws over your game.\n\n**The Gem Arcade draws no wallet over a game** (since 2026-10-11): the\nplayer sees their balances in the Gem menu, and payouts fly into the Gem\nbutton. So under the Gem Arcade this changes nothing on screen — it is\naccepted and harmless, and a game that already calls it keeps working.\nCall it for an embedder that does draw wallets over your game: hide them\nwhile you play, show them on your menus.\n\n```js\nlevel.onStart = () => gem.setWalletVisible(false);\nmenu.onOpen = () => gem.setWalletVisible(true);\n```\n\n**It is screen state, not a toggle.** Each call is the whole answer and\nreplaces the last. Where an embedder draws wallets, shown ones arrive as\nrectangles in `gem.viewport.reserved` and hiding them gives that space\nback; the Gem Arcade sends none for wallets. `only` narrows what shows,\nwhere an embedder honours it; the Gem Arcade does not.\n\n**Never draw a platform balance yourself**, and never show a pending state\nfor one: the arcade takes every figure from the platform. If this returns\n`false`, do nothing in its place.",
+          "summary": "Ask the arcade to show, or stop showing, the player's wallets — Gems,\nCoins, the achievement score — over your game.\n\n**The Gem Arcade draws them on request** (the owner, 2026-10-29): a game\nthat says nothing gets no wallet over it, as since 2026-10-11, and the\nplayer sees their balances in the Gem menu; a game that asks gets them\ndrawn beside the Gem, from the platform's own figures. An Arcade from\nbefore that ignores the call, harmlessly.\n\n```js\ngem.setWalletVisible(true, { only: ['GEMS', 'ARCADE_TICKETS'] }); // every screen\nlevel.onStart = () => gem.setWalletVisible(false); // or put them away during play\n```\n\n**It is screen state, not a toggle.** Each call is the whole answer and\nreplaces the last. Shown wallets arrive as rectangles in\n`gem.viewport.reserved` (and widen the Gem's corner in the\n`--gem-reserved-*` variables), and hiding them gives that space back.\n`only` narrows what shows.\n\n**Never draw a platform balance yourself**, and never show a pending state\nfor one: the arcade takes every figure from the platform. If this returns\n`false`, do nothing in its place.",
           "deprecated": null,
           "params": [
             {
@@ -12670,7 +13286,7 @@
           "group": "start",
           "signature": "setMenu(menu: GameMenu): boolean",
           "documented": true,
-          "summary": "Put up to four entries of your own in the arcade's menu. The arcade keeps\none menu button over your game: it is how a player leaves, mutes, goes\nfullscreen, reports a problem and changes their Arcade-wide settings.\n\n```js\ngem.setMenu({\n  items: [{ id: 'how-to-play', label: t('How to play'), onSelect: () => help.open() }],\n});\n```\n\n**Your settings are not in it: draw your own settings button, always** —\ntop-right, with your Back button just to its left, clear of\n`gem.viewport.reserved`. The Arcade's menu never opens your settings\nscreen.\n\n**It is screen state, not a toggle.** Each call is the whole answer and\nreplaces the last, so call it again when the entries change — a new\nlanguage, a screen with different options. `gem.setMenu({})` takes\neverything of yours back out. The arcade's own entries are not yours to\nchange, and Return to the Arcade is always among them.\n\n**The arcade pauses your game while its menu is open** (`onPause`), and\nresumes it before a handler of yours runs. A handler opens a screen; it\nshould not assume the game was paused by you.",
+          "summary": "Put up to four entries of your own in the arcade's menu. The arcade keeps\none menu button over your game: it is how a player leaves, mutes, goes\nfullscreen, reports a problem and changes their Arcade-wide settings.\n\n```js\ngem.setMenu({\n  items: [{ id: 'how-to-play', label: t('How to play'), onSelect: () => help.open() }],\n});\n```\n\n**Your settings screen is not in it: draw your own settings button** —\ntop-right, with your Back button just to its left, clear of\n`gem.viewport.reserved`. The Arcade's menu never opens your settings\nscreen. Inside the Gem Arcade you may leave the button out while this\nreturns `true`, when every setting on your screen is declared with\n`gem.settings` and every action on it is one of these entries; it returns\n`false` before the bridge is up and under an embedder with no menu, and the\nbutton stays there.\n\n**It is screen state, not a toggle.** Each call is the whole answer and\nreplaces the last, so call it again when the entries change — a new\nlanguage, a screen with different options. `gem.setMenu({})` takes\neverything of yours back out. The arcade's own entries are not yours to\nchange, and Return to the Arcade is always among them.\n\n**The arcade pauses your game while its menu is open** (`onPause`), and\nresumes it before a handler of yours runs. A handler opens a screen; it\nshould not assume the game was paused by you.",
           "deprecated": null,
           "params": [
             {