@indiegems/gem-web-sdk 16.2.0 → 16.3.0

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,14 @@ 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.

package/docs/getting-started.md

@@ -50,7 +50,7 @@ either way.
 ```jsonc
 // package.json
 "dependencies": {
-  "@indiegems/gem-web-sdk": "16.2.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": "b2791239b695b7830c97ccb7ef1370c317b92070a9a3f17d8488d02d78965094",
-      "updated": "2026-10-29T20:57:56Z"
+      "sha256": "600e6a0c79c48d4fa82e0993eac822df6629ab737ec6053eafab19c743ea19b8",
+      "updated": "2026-10-29T21:40:20Z"
     },
     {
       "file": "daily-challenges.md",
@@ -73,8 +78,8 @@
     },
     {
       "file": "getting-started.md",
-      "sha256": "0699d1d9283ec251416a8068a6d1dfa050d795c58c55656cc5ce83f98e5bf132",
-      "updated": "2026-10-29T20:57:56Z"
+      "sha256": "50f47be4de5a38a04e49cf1e864f66f8eab4739d8658d6984bb85c61400a0893",
+      "updated": "2026-10-29T21:40:20Z"
     },
     {
       "file": "inventory-and-catalogs.md",
@@ -133,8 +138,8 @@
     },
     {
       "file": "server-bundles.md",
-      "sha256": "3d628942136f6dbf2dc0dd25a825f4520fe9b54ffc88a62e2d9fed11039a5151",
-      "updated": "2026-10-29T20:57:56Z"
+      "sha256": "721aeb9ac64b9564477a5dffb3b5cc70d6d0c1b222d79ab7090413a0f9b4ef5a",
+      "updated": "2026-10-29T21:40:20Z"
     },
     {
       "file": "serverless-functions-js.md",

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.2.0/gem-web-sdk.tgz
-curl -fsSL https://downloads.gemarcade.com/sdk/v16.2.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.2.0",
+  "version": "16.3.0",
   "description": "postMessage bridge contract between gem-web and browser-playable games",
   "license": "UNLICENSED",
   "type": "module",