@indiegems/gem-web-sdk 16.3.1 → 18.0.0

package/docs/manifest.json

@@ -18,8 +18,8 @@
     },
     {
       "file": "arcade-and-store.md",
-      "sha256": "e055b2b1ec540da9fae8f41c025de99b0faec29cef8fca35285ee34e23120941",
-      "updated": "2026-10-29T23:35:13Z"
+      "sha256": "7320826529435d290159c8b0707f69819124607d1b38160dbc85f63b385fdea9",
+      "updated": "2026-10-30T13:36:37Z"
     },
     {
       "file": "arcade-avatars.md",
@@ -28,8 +28,8 @@
     },
     {
       "file": "arcade-economy.md",
-      "sha256": "f0bdc98d765fa4794090fc035d2c32d9c125cbdae58ba89fb5e76fcf1fb9da94",
-      "updated": "2026-10-29T23:35:13Z"
+      "sha256": "b72474b4694842a1fda030ab9df79987d2906f7a8c922e8630622d747a4b2c3c",
+      "updated": "2026-10-30T13:36:37Z"
     },
     {
       "file": "async-opponents.md",
@@ -48,8 +48,8 @@
     },
     {
       "file": "changelog.md",
-      "sha256": "e66efedcc9662bea610d3d4edc4e0125f3078e2b49059770f4553d57f37368b3",
-      "updated": "2026-10-29T23:50:25Z"
+      "sha256": "bd5cfd2b2d1d1989a8407e147ce29165caada49f78bcd0d708ded1babe98fc09",
+      "updated": "2026-10-30T15:46:14Z"
     },
     {
       "file": "daily-challenges.md",
@@ -78,13 +78,13 @@
     },
     {
       "file": "getting-started.md",
-      "sha256": "5f6b7c1e3763cb647379ccc96fc8eb4e5f22551f60cfe56bc6a957312f431fe3",
-      "updated": "2026-10-29T23:50:25Z"
+      "sha256": "67a444eb6e1cbf0bbf9af6309db48ae44e9c03a692df60a35c12e604cb646065",
+      "updated": "2026-10-30T15:46:14Z"
     },
     {
       "file": "inventory-and-catalogs.md",
-      "sha256": "032b911f515a7c81b0bcee6065300049651fef8b2108e7930e1d1354eada7a87",
-      "updated": "2026-10-29T23:35:13Z"
+      "sha256": "9c898355af92ab7e17035bad964dce57b26e64624b18e83149b88ae10b96fd9c",
+      "updated": "2026-10-30T13:36:37Z"
     },
     {
       "file": "leaderboards.md",
@@ -138,8 +138,8 @@
     },
     {
       "file": "server-bundles.md",
-      "sha256": "387d213d3770f21dccb32c94aac57b5af32bcac8bbe5ca9a6c3c2d8d51e5a2a2",
-      "updated": "2026-10-29T23:50:25Z"
+      "sha256": "8c2ff15c97a0eb09c9a50ae78b5e728635a478ee879a8aa788b82ca7de387eee",
+      "updated": "2026-10-30T15:46:14Z"
     },
     {
       "file": "serverless-functions-js.md",
@@ -163,8 +163,8 @@
     },
     {
       "file": "what-a-game-must-do.md",
-      "sha256": "9d6f2121306bfee8b886d9555a644faa843d16f0c5200e257698336d747136b1",
-      "updated": "2026-10-29T21:40:17Z"
+      "sha256": "8faa9ef2cef2a5eb73cf95d7c52af914325c2bc26834625c9cb4b5748eecc616",
+      "updated": "2026-10-30T14:09:09Z"
     }
   ]
 }

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.3.1/gem-web-sdk.tgz
-curl -fsSL https://downloads.gemarcade.com/sdk/v16.3.1/gem-web-sdk.tgz.sri
+curl -fsSL -O https://downloads.gemarcade.com/sdk/v18.0.0/gem-web-sdk.tgz
+curl -fsSL https://downloads.gemarcade.com/sdk/v18.0.0/gem-web-sdk.tgz.sri
 openssl dgst -sha384 -binary gem-web-sdk.tgz | openssl base64 -A
 ```
 

package/docs/what-a-game-must-do.md

@@ -971,6 +971,35 @@ read the rectangles, so the arcade sends it none and instead raises `insets.top`
 `--gem-safe-top` — past the bottom of the row. That game keeps working, at the cost of a full-width
 band; upgrading gives the band back.
 
+### Matching the Arcade to your game: `gem.setMenuStyle`
+
+The burger button and everything the Arcade draws over your game wear the player's Arcade style
+until you say otherwise. To make them match your game, give the Arcade two colours:
+
+```js
+gem.setMenuStyle({ ground: '#1b2a4a', accent: '#ffb300' }); // at boot, with your first screen
+gem.setMenuStyle(null); // back to the player's own style
+```
+
+- **Colours only.** `ground` is what the Arcade's surfaces are built on and `accent` is its one
+  highlight. The Arcade works out the text, rims, button shapes and fonts, so its screens stay
+  readable on any ground.
+- **What the Arcade refuses.** Each colour must be exactly `#rrggbb`, and `accent` must reach 3:1
+  contrast against `ground`. Anything else is ignored, with a warning on the console giving the
+  measured ratio: the last colours stand, nothing is sent, and the call returns `false`.
+- **What wears your colours.** The burger button, the Gem menu and its pages, and every Arcade
+  pop-up over your running game, purchase sheets included. They do not reach the Arcade's other
+  screens.
+- **Your colours win while your game runs.** They replace the style the player chose, and that
+  style comes back when your game ends.
+- **It is screen state, not a toggle**: each call is the whole answer, held before the Arcade
+  connects and sent again after any reconnect, so you may change it between levels. A change the
+  Arcade receives while its menu or a pop-up is open waits until that closes.
+
+`gem.setMenuStyle` returns `true` when the Arcade was told, and `false` before it connects, under an
+embedder that cannot wear your colours, and for colours it would refuse. On `false` from an embedder
+there is nothing else to do: never draw a look-alike of its menu.
+
 ## Which store-page experiment brought this player in: cohorts
 
 **You need this only if you run an A/B experiment on your store page and want the game to match

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indiegems/gem-web-sdk",
-  "version": "16.3.1",
+  "version": "18.0.0",
   "description": "postMessage bridge contract between gem-web and browser-playable games",
   "license": "UNLICENSED",
   "type": "module",

package/schema/bridge.v1.json

@@ -3145,6 +3145,64 @@
       "rateLimit": { "perMinute": 12 }
     },
 
+    {
+      "type": "gem.menuStyle",
+      "direction": "frameToParent",
+      "transport": "port",
+      "$comment": [
+        "The colours the game would like the arcade's own screens over it to wear,",
+        "so they match the game: in the Gem Arcade, the burger button, the Gem menu",
+        "and its pages, and every Arcade pop-up over the running game. With no",
+        "message at all those screens wear the player's own Arcade style.",
+        "",
+        "TWO COLOURS, BOTH OR NEITHER. `ground` is the colour the arcade's surfaces",
+        "are built on and `accent` its one highlight. A message with neither hands",
+        "the arcade back to the player's own style; a message with only one is",
+        "refused by the parent. The parent works out everything else, text, rims,",
+        "button shapes and fonts, so a game can never make its screens unreadable.",
+        "",
+        "SCREEN STATE, NOT A TOGGLE, like `gem.gemCorner`. Each message is the whole",
+        "answer and the latest one wins, so a game may change it between levels.",
+        "The SDK holds it from before the bridge is up and re-sends it after every",
+        "handshake, so a parent that reconnects wears what the game had asked.",
+        "",
+        "THE PARENT DECIDES, AND IT CHECKS AGAIN. The frame is untrusted, so a",
+        "parent checks both values itself before a byte of them reaches a style:",
+        "exactly `#` and six hexadecimal digits, and at least 3:1 WCAG contrast",
+        "between `accent` and `ground`. On failure it keeps the screens as they",
+        "are and tells the game nothing; the SDK refuses the same values on the",
+        "game's side, where a developer sees why. A format of its own is not used",
+        "for the hex, because a parent built on an older contract refuses a format",
+        "it does not know.",
+        "",
+        "ON THE PARENT'S TERMS. In the Gem Arcade the game's colours win over the",
+        "player's chosen style for as long as that game runs, a change that arrives",
+        "while one of the arcade's surfaces is open waits for it to close, and the",
+        "player's own style comes back when the game ends.",
+        "",
+        "A PRESENTATION REQUEST ONLY, and not an authorization control. Cosmetic:",
+        "nothing may key a trust decision on it.",
+        "",
+        "Gated by `menuStyle`: sent only to a parent that advertised it. To any",
+        "other, `gem.setMenuStyle` returns false."
+      ],
+      "fields": {
+        "ground": {
+          "kind": "string",
+          "maxLength": 7,
+          "optional": true,
+          "$comment": "`#rrggbb`, the colour the arcade's surfaces are built on. Absent with `accent` to clear."
+        },
+        "accent": {
+          "kind": "string",
+          "maxLength": 7,
+          "optional": true,
+          "$comment": "`#rrggbb`, the one highlight, at least 3:1 against `ground`. Absent with `ground` to clear."
+        }
+      },
+      "rateLimit": { "perMinute": 12 }
+    },
+
     {
       "type": "gem.settingsDeclare",
       "direction": "frameToParent",
@@ -5581,6 +5639,114 @@
         }
       },
       "rateLimit": { "perMinute": 30 }
+    },
+    {
+      "type": "gem.requestStoreOfferSheet",
+      "direction": "frameToParent",
+      "transport": "port",
+      "$comment": [
+        "Ask the parent to SHOW one SKU it listed in gem.storeOffersResult, in",
+        "the Arcade's own one-offer sheet over the paused game - real money, not",
+        "Gems. Gated by the `storeOfferSheet` capability. Answered by",
+        "`gem.storeOfferSheetResult`.",
+        "",
+        "THE ARCADE DRAWS THE OFFER; THE GAME ONLY POINTS AT IT. gem.requestStorePurchase",
+        "is for an offer the game drew itself from gem.storeOffersResult, and goes",
+        "straight to checkout. This is for an offer whose pitch the bridge cannot",
+        "carry: its perks, a sale, what a holder already has. All of that stays",
+        "with the parent, so none of it - least of all whether this player holds",
+        "a pass - crosses to the game. The sheet's Buy opens the same checkout",
+        "gem.requestStorePurchase opens.",
+        "",
+        "EVERY RULE OF gem.requestStorePurchase HOLDS, and it shares them rather",
+        "than having its own: an acting message (a press the parent can see, one",
+        "at a time across all of them, both checked before `skuId` is resolved,",
+        "the answer bound to this frame session); only a SKU the parent would",
+        "list now; an offer cooling down opens nothing and answers `declined` /",
+        "`cancelled`; the SAME back-off, so a game cannot escape one by switching",
+        "message; resume, then answer; evidence, not accounting.",
+        "",
+        "THE SHEET IS NOT A SECOND CONFIRMATION, and it does not change",
+        "gem.requestStorePurchase's straight-to-checkout rule. It is the pitch;",
+        "the checkout is still the confirmation, with its own pay control. The",
+        "player leaving the sheet without pressing Buy is a dismissal, exactly",
+        "as closing a checkout is, and starts the back-off.",
+        "",
+        "A PARENT THAT ADVERTISES `storeOfferSheet` ADVERTISES `store`: the",
+        "game's SKU comes from gem.storeOffersResult, and a purchase that answers",
+        "`ok` / `pending` here is followed by gem.storePurchaseSettled.",
+        "",
+        "Every field is untrusted text: match `skuId` against the offers you",
+        "read, never interpolate it into a path, a query or a log line."
+      ],
+      "fields": {
+        "requestId": {
+          "kind": "string",
+          "maxLength": 64,
+          "$comment": "Opaque and frame-chosen. Echo-only, and never a key on the money path: the parent derives its own request identity."
+        },
+        "skuId": {
+          "kind": "string",
+          "maxLength": 64,
+          "$comment": "One `skuId` from gem.storeOffersResult. Frame-chosen: matched by the parent against the listing it would show now."
+        }
+      },
+      "rateLimit": {
+        "perMinute": 12,
+        "$comment": "gem.requestStorePurchase's limit and its argument: it bounds a BUGGY game, not a hostile one. What bounds the player's experience is the activation check, the one-at-a-time rule and the back-off."
+      }
+    },
+    {
+      "type": "gem.storeOfferSheetResult",
+      "direction": "parentToFrame",
+      "transport": "port",
+      "$comment": [
+        "The answer to one gem.requestStoreOfferSheet, carrying exactly what",
+        "gem.storePurchaseResult carries and meaning the same. Gated by the",
+        "`storeOfferSheet` capability.",
+        "",
+        "  ok          - the player paid. With no reason, fulfilment has",
+        "                settled; with `reason: pending`,",
+        "                gem.storePurchaseSettled follows when it does.",
+        "  declined    - nothing was bought: the player left the sheet or closed",
+        "                the checkout, or the offer is cooling down (`cancelled`);",
+        "                or no press, another acting message open or a back-off",
+        "                running (`busy`).",
+        "  unavailable - no sale the parent can vouch for. With `store_off`,",
+        "                `sign_in_required`, `not_found` or the provider's own",
+        "                failure code, nothing was bought. With `error`, the",
+        "                OUTCOME IS UNKNOWN and the player may have paid. The SDK",
+        "                resolves the same `unavailable` / `error` when the port",
+        "                closes under an open sheet.",
+        "",
+        "`cancelled` DOES NOT SAY WHICH. The game is not told whether the player",
+        "left the sheet or the checkout, and nothing here says what the sheet",
+        "showed.",
+        "",
+        "NO TIMEOUT ON THE GAME'S SIDE while the port is alive: the parent always",
+        "answers, and a player may read a sheet for as long as they like.",
+        "NEVER AUTO-RETRIED. Only a fresh press may ask again."
+      ],
+      "fields": {
+        "requestId": {
+          "kind": "string",
+          "maxLength": 64,
+          "$comment": "Echoes the gem.requestStoreOfferSheet that asked. Echo-only."
+        },
+        "outcome": {
+          "kind": "enum",
+          "values": ["ok", "declined", "unavailable"],
+          "$comment": "Closed at three, as gem.purchaseResult's."
+        },
+        "reason": {
+          "kind": "string",
+          "maxLength": 64,
+          "format": "code",
+          "optional": true,
+          "$comment": "An open code, on any outcome: `pending` with `ok`; `cancelled` or `busy` with `declined`; `store_off`, `sign_in_required`, `not_found`, `error` or the payment provider's own failure code with `unavailable`. Normalized to the code grammar before it is sent, as gem.storePurchaseResult's. A receiver must not fail on a code it does not know."
+        }
+      },
+      "rateLimit": { "perMinute": 30 }
     }
   ],
 

package/schema/capabilities.public.json

@@ -295,6 +295,19 @@
         "gem.storePurchaseResult",
         "gem.storePurchaseSettled"
       ]
+    },
+    "storeOfferSheet": {
+      "implemented": true,
+      "gates": [
+        "gem.requestStoreOfferSheet",
+        "gem.storeOfferSheetResult"
+      ]
+    },
+    "menuStyle": {
+      "implemented": true,
+      "gates": [
+        "gem.menuStyle"
+      ]
     }
   }
 }