@indiegems/gem-web-sdk 7.5.0 → 7.6.0

package/docs/getting-started.md

@@ -50,7 +50,7 @@ either way.
 ```jsonc
 // package.json
 "dependencies": {
-  "@indiegems/gem-web-sdk": "7.5.0"
+  "@indiegems/gem-web-sdk": "7.6.0"
 }
 ```
 
@@ -157,11 +157,13 @@ your reports arrive with no picture. Two-dimensional canvas games need nothing h
 covers overriding the capture and attaching your own debug state, which is the part actually
 worth spending effort on.
 
-**There is no offline mode.** A game must be framed by an arcade page to reach the platform:
-unframed it still constructs and runs, but the bridge never connects and anything needing a
-token waits forever. To run framed without publishing, open your served build in the Gem
-Arcade app (step 6 below), or use the SDK repository's `examples/dev-harness/` — a local
-parent page that frames your dev server and completes a real handshake.
+**There is no offline mode.** A game must be framed by a page that speaks the bridge: opened
+at the top level, `createGem` throws `GemUnframedError`, which says how to run it. To run framed
+without publishing, use the Gem dev host, signed in to `gemctl`: `npm run dev` in a project the
+Gem tools scaffolded (`gemctl serve start . --dev`, your vite server with hot reload), or
+`gemctl serve start .` for a build. The Gem Editor's Play frames it too, and the SDK
+repository's `examples/dev-harness/` is a local parent page that frames your dev server. Never
+open the dev server's own address.
 
 ## 5. Tell the arcade when you are ready
 

package/docs/manifest.json

@@ -13,8 +13,8 @@
     },
     {
       "file": "analytics.md",
-      "sha256": "4d6b9e5c2cbc47c527c0437329c7b3d7ebc61136a8c384f4e0a640f9fd4ed226",
-      "updated": "2026-10-02T01:09:38Z"
+      "sha256": "57fb07c3d649c2758a35660707d31b05164b363e9a425156978aed394d086339",
+      "updated": "2026-10-02T14:04:37Z"
     },
     {
       "file": "arcade-economy.md",
@@ -31,6 +31,11 @@
       "sha256": "cf54939a0fcee1f5a6e11b9de52b5ed498ec8c373683e92aa5bc6654b12eb0ab",
       "updated": "2026-10-01T03:49:20Z"
     },
+    {
+      "file": "changelog.md",
+      "sha256": "02083c9ed1d62baed5a297ca71b602608afa90320afb73a21ff03187da11346f",
+      "updated": "2026-10-02T04:41:46Z"
+    },
     {
       "file": "cross-promotion.md",
       "sha256": "3a8121a9c973e4a1bfed076a3226d139f8b4e38a173a06ea9f08000c72bca4b4",
@@ -63,8 +68,8 @@
     },
     {
       "file": "getting-started.md",
-      "sha256": "678670383df1f4df16253616869d9c2d1aceaf3e2464f7499c6ff50cee70a82b",
-      "updated": "2026-10-02T01:21:17Z"
+      "sha256": "fd859a01988ecf57c857dcfba9958a8a32a65ff2a8ecfaf55f33f9045d368180",
+      "updated": "2026-10-02T17:28:15Z"
     },
     {
       "file": "inventory-and-catalogs.md",
@@ -113,8 +118,13 @@
     },
     {
       "file": "server-bundles.md",
-      "sha256": "abc87cf6bf86bd7c0538a983aa8681460f8c8d82fbee7bb78515ce5f97fb2e3f",
-      "updated": "2026-10-02T01:21:17Z"
+      "sha256": "8190da0484b7e1ae6f636068b06a43729f3ef132488f5a0cfd2fc5c2988bc55b",
+      "updated": "2026-10-02T17:28:15Z"
+    },
+    {
+      "file": "serverless-functions-js.md",
+      "sha256": "86b0f9f0b742a662ebb78b1538cbbc399309725faf22f46f613b63b5e0864082",
+      "updated": "2026-10-02T17:17:29Z"
     },
     {
       "file": "serverless-functions.md",
@@ -128,8 +138,8 @@
     },
     {
       "file": "what-a-game-must-do.md",
-      "sha256": "25ea532aa4f0a2b2f3139fc52516bdc869e3ada921935337462b6655de2b0938",
-      "updated": "2026-10-02T01:09:38Z"
+      "sha256": "a0a2952a2b16b43b0af831ff58ad8fabe47b414f57fccd2cb2d866861a65465e",
+      "updated": "2026-10-02T14:04:37Z"
     }
   ]
 }

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

package/docs/serverless-functions-js.md

@@ -0,0 +1,139 @@
+# Serverless functions in JavaScript
+
+<!-- gem-web: unpublished — the platform does not run JavaScript functions yet -->
+
+A serverless function can be written in JavaScript or TypeScript instead of Rust: the language your
+game is already written in, so the verification code in your browser game moves into a function
+with no change beyond bundling. You upload one bundled ES module, and the platform runs it on a
+JavaScript engine of its own.
+
+Everything [serverless-functions.md](serverless-functions.md) says about what a function is for,
+what it may change, its limits, channels, and calling it from your game holds here unchanged. This
+page covers only what is different: how you write one, how the SDK behaves inside it, and how
+publishing checks it.
+
+## 1. The contract
+
+The same as a component's: bytes in, bytes out, one fresh instance per call, nothing kept between
+calls. Your module exports **exactly one** of two functions, and which one decides how the bytes
+are read and written:
+
+| Export              | Input                                                 | Return                                                                                                    |
+| ------------------- | ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| `handle(input)`     | `Uint8Array`: the request body, byte for byte         | `Uint8Array`, `ArrayBuffer` or `string` (sent as UTF-8); anything else is an error                        |
+| `handleJson(input)` | the body parsed as JSON; an empty body is `undefined` | any JSON-serializable value, sent as its JSON text; `undefined` is sent as `null`; a `BigInt` is an error |
+
+Either may be `async`; the platform waits for the promise. Exporting neither, or both, is refused
+when you upload. A caller cannot tell which kind of function answered: `gem.functions.invoke`, the
+limits and the refusals in serverless-functions.md are identical for both.
+
+**A thrown exception is `Err`.** The call fails with `function_error`, and `err.functionMessage` is
+the exception's `name: message` (a thrown value that is not an `Error` is its `String()`). The
+message and the stack go to the platform's log for the invocation, never to the caller. A
+`handleJson` whose input is not JSON, or whose return value JSON cannot carry, fails the same way.
+
+**`console.*` reaches the invocation's log** at the matching level (`debug`, `info`, `warn`,
+`error`); `console.log` and every other method log at `info`. As with a component's `log`, nothing
+reads it back to you: the invocation id is what you quote about one call.
+
+## 2. Writing one
+
+```bash
+gemctl function init --lang js functions/score-check
+cd functions/score-check && npm install && npm run build
+gemctl function upload dist/function.js
+```
+
+**`init --lang js`** writes a `package.json` whose `build` script type-checks and then bundles to
+one ES module, a TypeScript starter handler and a `tsconfig.json`. gemctl runs neither step:
+`npm run build` is yours, the way `cargo build` is for a component.
+
+A handler looks like this:
+
+```ts
+import { createGem } from '@indiegems/gem-web-sdk/function';
+
+export async function handleJson(claim: { level: number }) {
+  const gem = createGem();
+  console.info(`level ${claim.level} claimed by ${gem.identity?.playerId ?? 'a game server'}`);
+  // Decide from what the player cannot forge, and make any write through `gem`
+  // here, before answering: the answer itself is only advice to the browser.
+  return { accepted: false };
+}
+```
+
+The package is the one your game already depends on, installed as
+[getting-started.md](getting-started.md) shows. What makes a check worth running is
+serverless-functions.md section 1, and it applies unchanged: a save or a setting the player's own
+browser can write is the player's claim, not evidence.
+
+**Imports.** The module may import the SDK and nothing else, under any of the three names a game
+already uses: `@indiegems/gem-web-sdk/function`, `@indiegems/gem-web-sdk/sdk`, or
+`@indiegems/gem-web-sdk/game`. Inside a function all three are the same module, the function
+entry, so shared code keeps its import. A name that module does not export, such as
+`defineServer`, fails every call with `function_error`. Everything else your code needs is bundled
+in, which is what the starter's build does. An `import()` at runtime is refused at upload.
+Top-level `await` is allowed and runs on every call.
+
+**What the engine gives you.** `Date`, `performance`, `Math.random`, `crypto.getRandomValues`,
+`crypto.randomUUID`, `TextEncoder`, `URL` and `fetch` all work. `fetch` reaches only the platform
+API, through the SDK, and the save links the platform hands you; any other URL is refused. A timer
+waits at most 10 ms: a function has no reason to sleep, and a long one would run out the wall
+clock.
+
+**The SDK version your function runs is the one the platform bundles**, not the one in your
+`package.json`; the starter pins the matching version. A method added in a newer SDK reaches a
+function when the platform's engine picks that version up.
+
+## 3. The SDK inside a function
+
+`createGem()` from `@indiegems/gem-web-sdk/function` is synchronous, `awaitBridge()` and
+`awaitIdentity()` resolve at once, and `gem.me` is the player who called. So a game's boot sequence
+runs unchanged, and the same `gem.me.saves.get`, `gem.leaderboards.get` and `gem.profiles.of` calls
+work, with the same types and the same errors. The function's game and channel come from the call;
+nothing you write names them. `gem.context` is who called, for which game and channel, and
+`gem.identity` is the same three fields a browser game reads from its own `gem.identity`.
+
+What a browser game has that is backed by the page or the arcade (ads, purchases, rooms, device
+settings, sharing) is not on `gem` inside a function. Four more differences, each following from
+how a function reaches the platform:
+
+- **`gem.me` is the invoker.** When a game server invoked the function there is no player, and
+  reading `gem.me` or `gem.transfers` throws saying so; `gem.identity` is `null`. Which writes a
+  player-invoked function may make is unchanged (serverless-functions.md section 2).
+- **No conditional requests, and no retries.** The platform call a function makes carries no
+  headers, so an `ifMatch` or `ifNoneMatch` cannot travel. A call carrying one is refused with
+  `TransportRefusal` naming the option, rather than sent as an overwrite that checks nothing.
+  Nothing is retried either: a retry is another platform call and a wait is your function's wall
+  clock, so your code decides.
+- **`gem.functions` is absent.** A function may not invoke a function.
+- **`gem.gameConfig` is absent.** The config document is not reachable from a function, so
+  `gem.me.currencies.get()` takes a currency id rather than a slug.
+
+`gem.friends.challenge()` answers `unavailable` without asking anything, because there is nobody in
+front of a screen to confirm it, and `gem.platform.earnAllowance.on()` never fires.
+
+⚠️ **Flush analytics before you return.** A page flushes on a timer and as it closes; a function
+ends the moment your handler settles, so `await gem.analytics.flush()` before you return, or the
+events may be lost.
+
+## 4. Check before you upload
+
+```bash
+gemctl function check dist/function.js
+```
+
+`check` runs the platform's publish-time validation for JavaScript on your machine, and an upload
+answers `400 source_invalid` with the same `details.reason`:
+
+| Reason             | What it usually is                                                        | What to change                                    |
+| ------------------ | ------------------------------------------------------------------------- | ------------------------------------------------- |
+| `not_a_module`     | A parse error, with its line and column, or a file that is not UTF-8      | Fix the syntax; bundle to ES2022                  |
+| `forbidden_import` | An `import` or `export … from` of anything but the SDK, or an `import()`  | Bundle the dependency in; drop the dynamic import |
+| `missing_handle`   | Neither `handle` nor `handleJson` is exported (`export *` does not count) | Export one of them from the module itself         |
+| `ambiguous_handle` | Both are exported                                                         | Keep one                                          |
+| `too_large`        | Over the size limit, the same one a component has                         | Bundle less; check what your build pulled in      |
+
+An upload also answers `source_invalid`, rather than `component_invalid`, for `not_uploaded`,
+`size_mismatch` and `sha256_mismatch`: upload again. Promoting, channels and invoking are the same
+as for a component (serverless-functions.md sections 4 to 7).

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

@@ -187,9 +187,9 @@ try {
 
 `awaitBridge()` resolves when the bridge leaves `waiting` — connected, refused or closed — or at a
 bounded timeout (default 10s), with the state it settled on. **Proceed on every outcome.**
-`connected` is the Arcade; anything else is a boot without a parent, which your game must survive
-anyway. The wait costs nothing when the handshake is quick: it settles the moment the frame
-connects. Unframed it is never answered, because no parent ever pushes one.
+`connected` is a Gem host listening; anything else is a boot with no session, which your game must
+survive anyway. The wait costs nothing when the handshake is quick: it settles the moment the frame
+connects, and at once when the page that framed it is refused.
 
 The measured stakes, from the first game to hit this on an iPhone: listener up at ~300ms, then a
 main-thread block — the parent's offer, queued behind the block, was delivered twenty seconds later
@@ -515,8 +515,8 @@ them**, so the whole migration for a stylesheet is one declaration per edge:
 ```
 
 The `env()` fallback is not decoration. Under a parent that has not sent the message — an older
-arcade, a third-party embedder, your game opened in a plain tab during development — the
-properties are never set and the browser's own answer stands, which is what your game did before.
+arcade or dev host, a third-party embedder — the properties are never set and the browser's own
+answer stands, which is what your game did before.
 Under a parent that has, the variable wins. One line, correct in both worlds. The four names are
 `--gem-safe-top`, `--gem-safe-right`, `--gem-safe-bottom` and `--gem-safe-left`.
 
@@ -538,17 +538,21 @@ the `var()` above, or read `gem.viewport`. The release checklist looks for the b
 
 ### The arcade's own controls: reserved areas
 
-On a phone your game is full-bleed, and the arcade keeps one cluster of its own on top of it, in the
-**top-left corner** of your frame: a small **Back** tab — the Gem Arcade wordmark — and, beside it,
-the player's wallets (Gems, Tickets, their achievement score) while they are
-[shown](#the-arcades-wallet-show-it-never-draw-it). The cluster stays in the top-left and runs along
-the top row at most about three quarters of the way across on the narrowest phone — but do not
-hard-code a size: read it, as below. Those rectangles of your frame are **reserved**: keep essential
-UI and every touch target out of them.
+On a phone your game is full-bleed, and the arcade keeps one row of its own across the top of it,
+with the middle left open for a centred camera:
 
-**The arcade never takes the right side.** Put your own settings, pause or menu button **top-right**
-— that corner is yours. And **do not put a back arrow of your own top-left**: it would sit under the
-arcade's Back tab, which leaves the game, while yours would mean something else.
+- **Top-left: the Back tab** — the Gem Arcade wordmark, always there. **Do not put a back arrow of
+  your own top-left**: it would sit under the arcade's tab, which leaves the game, while yours would
+  mean something else.
+- **Top-right: the player's wallets** (Gems, Tickets, their achievement score) while your screen
+  [shows them](#the-arcades-wallet-show-it-never-draw-it). Put your own settings, pause or menu
+  button top-right **below** them, at `top: var(--gem-reserved-tr-height, …)` — and when gameplay
+  hides the wallets with `gem.setWalletVisible(false)`, that rectangle shrinks to nothing and your
+  button moves up into the corner on its own.
+
+Those rectangles of your frame are **reserved**: keep essential UI and every touch target out of
+them. **Never hard-code their size or height.** They differ by phone, and in native fullscreen the
+whole row may rise into the camera band — read them, as below.
 
 An inset cannot say that — as a top inset, a tab a few dozen pixels wide would take your whole top
 strip. So `gem.viewport` also carries the rectangles, in the same CSS pixels of your frame, measured
@@ -567,13 +571,21 @@ from its top-left corner:
 reserved rectangles reach in from its two edges. Push the corner's UI clear of it:
 
 ```css
-/* a score in the top-left corner, below the cluster */
+/* settings in the top-right corner, below the wallets — and up in the corner when they are hidden */
+#settings {
+  top: max(var(--gem-safe-top, env(safe-area-inset-top, 0px)), var(--gem-reserved-tr-height, 0px));
+  right: var(--gem-safe-right, 0px);
+}
+/* a score in the top-left corner, below the tab */
 #score {
   top: max(var(--gem-safe-top, env(safe-area-inset-top, 0px)), var(--gem-reserved-tl-height, 0px));
   left: var(--gem-safe-left, 0px);
 }
-/* or a row along the top, starting after it */
-#top-bar { padding-left: var(--gem-reserved-tl-width, 0px); }
+/* or a row along the top, between the two */
+#top-bar {
+  padding-left: var(--gem-reserved-tl-width, 0px);
+  padding-right: var(--gem-reserved-tr-width, 0px);
+}
 ```
 
 All eight are written on every push, `0px` for a clear corner, so a rotation never leaves a stale
@@ -581,9 +593,9 @@ value; they are never set under an embedder that sends no viewport, which is wha
 fallback is for. A rectangle belongs to the corner its centre lies nearest to. For a HUD laid out
 from script, read `gem.viewport.reserved` — `[]` when nothing is covered.
 
-**Lay out against it whenever it changes.** Shown wallets widen the reserved area beside the tab;
-hiding them shrinks it back to the tab alone. A wallet the arcade pops up for a moment while they
-are hidden never reserves anything — it floats over your game and moves nothing.
+**Lay out against it whenever it changes.** Shown wallets reserve the top-right corner; hiding them
+shrinks it to nothing, and only the tab's top-left rectangle is left. A wallet the arcade pops up for
+a moment while they are hidden never reserves anything — it floats over your game and moves nothing.
 
 **Older SDKs get it folded into the top inset.** A game on an SDK from before reserved areas cannot
 read the rectangles, so the arcade sends it none and instead raises `insets.top` — and so
@@ -764,7 +776,8 @@ and the release checklist checks that it does.
 
 The player's platform balances — Gems, Tickets (`ARCADE_TICKETS`) and their achievement score —
 belong to the Arcade. **Your game never draws one**, and never shows a pending state for one: the
-Arcade takes every figure from the platform and draws the wallets itself, beside its Back tab.
+Arcade takes every figure from the platform and draws the wallets itself, in the top-right corner
+of your frame on a phone.
 
 **They are shown unless your game hides them.** A game that does nothing has every wallet on show
 the whole time. The one rule: **hide them during gameplay, show them on your menus.**
@@ -780,10 +793,10 @@ pauseMenu.onOpen = () => gem.setWalletVisible(true);
 - **It is screen state, not a toggle.** Each call is the whole answer and replaces the last. Call it
   as often as you like: before the Arcade connects the state is held and sent when it does, and
   again after any reconnect; a repeat of the current state is not re-sent.
-- **Shown wallets take space; a pop does not.** Shown, they widen the
-  [reserved area](#the-arcades-own-controls-reserved-areas) beside the Back tab, so lay your menu
-  out against `--gem-reserved-tl-*`; hidden, it shrinks back to the tab. A pop floats over your game
-  and never moves its layout.
+- **Shown wallets take space; a pop does not.** Shown, they reserve the top-right
+  [corner](#the-arcades-own-controls-reserved-areas), so lay your menu out against
+  `--gem-reserved-tr-*` — your settings button sits below them; hidden, the corner is yours again and
+  the same `var()` moves the button up. A pop floats over your game and never moves its layout.
 - **Narrowing is optional.** On a screen that sells in one currency — a ticket store — you may show
   only that one: `gem.setWalletVisible(true, { only: ['ARCADE_TICKETS'] })`, with `'score'` for the
   achievement score. Use it only there; leaving it out shows every wallet, which is always safe.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indiegems/gem-web-sdk",
-  "version": "7.5.0",
+  "version": "7.6.0",
   "description": "postMessage bridge contract between gem-web and browser-playable games",
   "license": "UNLICENSED",
   "type": "module",
@@ -31,6 +31,10 @@
       "types": "./dist/server-api.d.ts",
       "import": "./dist/gem-web-sdk.server-api.js"
     },
+    "./function": {
+      "types": "./dist/function.d.ts",
+      "import": "./dist/gem-web-sdk.function.js"
+    },
     "./schema": "./schema/bridge.v1.json",
     "./brand/*": "./brand/*"
   },
@@ -45,6 +49,7 @@
     "docs/*.md",
     "docs/manifest.json",
     "docs/api/*.md",
-    "docs/api/reference.json"
+    "docs/api/reference.json",
+    "CHANGELOG.md"
   ]
 }

package/schema/bridge.v1.json

@@ -894,7 +894,7 @@
         "AMENDED, DELIBERATELY: this message once carried insets only. It now also",
         "carries `reserved`, rectangles of the frame covered by the parent's own",
         "controls floating over the game (a Back tab in a corner, the wallet chips",
-        "shown beside it). An inset can only describe a full-width or full-height band,",
+        "shown in another). An inset can only describe a full-width or full-height band,",
         "and a corner tab expressed as a top inset would take the whole top strip",
         "from a full-bleed game to clear a control a few dozen pixels wide. A",
         "rectangle says exactly which part, and still says nothing about what the",