@indiegems/gem-web-sdk 16.2.0 → 16.3.0

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.0"
   },
   "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"
@@ -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",
@@ -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",

package/docs/arcade-and-store.md

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