@indiegems/gem-web-sdk 7.5.0 → 7.6.0

package/docs/api/reference.json

@@ -2,7 +2,7 @@
   "schema_version": 1,
   "source": {
     "repo": "IndieGems/gem-web-sdk",
-    "version": "7.5.0"
+    "version": "7.6.0"
   },
   "entries": [
     {
@@ -5836,7 +5836,7 @@
           "url": "https://gemarcade.com/developer/api/game#framestate",
           "signature": "type FrameState = \"waiting\" | \"connected\" | \"refused\" | \"closed\"",
           "documented": true,
-          "summary": "Where the bridge to the arcade stands.\n\n`waiting` is the state a game boots in and the one it may sit in forever —\noutside the arcade there is no parent to answer, and that is not an error.\n`connected` is the only state in which the arcade is listening. `refused`\nmeans a page tried to embed this game and its origin was not in\n`allowedEmbedders`; `closed` means a connection existed and ended.\n\nReceived by `onStateChange` and resolved by `awaitBridge`, both of which are\ndocumented — so without a name for this union a game could observe the value\nand not be able to declare a variable holding it.",
+          "summary": "Where the bridge to the arcade stands.\n\n`waiting` is the state a game boots in: framed, and its parent has not\nanswered yet. `connected` is the only state in which the arcade is\nlistening. `refused` is final: the page that framed this game is not one it\naccepts (its origin is not in `allowedEmbedders`), or it speaks no protocol\nversion in common. `closed` means a connection existed and ended.\n\nReceived by `onStateChange` and resolved by `awaitBridge`, both of which are\ndocumented — so without a name for this union a game could observe the value\nand not be able to declare a variable holding it.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -5876,7 +5876,7 @@
           "url": "https://gemarcade.com/developer/api/game#gemframe-currentstate",
           "signature": "get currentState(): FrameState",
           "documented": true,
-          "summary": "Where the bridge is right now, without waiting.\n\n- `waiting` — the arcade has not connected yet. Normal at startup.\n- `connected` — the bridge is up and everything works.\n- `refused` — the arcade declined the connection.\n- `closed` — the session has ended.\n\nA snapshot, so it can change immediately after you read it. To wait for the\nquestion to be settled once, use [GemFrame.settled](https://gemarcade.com/developer/api/game#gemframe-settled).\n\nA game outside the arcade — opened directly during development — stays\n`waiting` forever, which is the case worth handling: boot anyway, without a\nbridge.",
+          "summary": "Where the bridge is right now, without waiting.\n\n- `waiting` — the arcade has not connected yet. Normal at startup.\n- `connected` — the bridge is up and everything works.\n- `refused` — final: the page that framed the game is not one it accepts,\n  or no protocol version is shared.\n- `closed` — the session has ended.\n\nA snapshot, so it can change immediately after you read it. To wait for the\nquestion to be settled once, use [GemFrame.settled](https://gemarcade.com/developer/api/game#gemframe-settled).\n\nA page that frames the game and never answers leaves it `waiting`, which\nis the case worth handling: boot anyway, and say there is no session.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -5934,7 +5934,7 @@
           "url": "https://gemarcade.com/developer/api/game#gemframe-settled",
           "signature": "settled(timeoutMs?: number): Promise<FrameState>",
           "documented": true,
-          "summary": "Wait until it is known whether there is a bridge, then carry on either way.\n\nResolves as soon as the connection is settled — connected, refused or\nclosed — or when the timeout runs out, with whichever state it is in.\n\nTHE GATE TO AWAIT BEFORE LOADING A HEAVY BUNDLE. The connection offer is\ndelivered to your game rather than polled, so if your main thread is busy\nparsing several megabytes of JavaScript, the offer waits behind that work —\nand by the time it arrives the connection it carried may already be gone.\nAwaiting this first keeps the thread free long enough to accept.\n\nTHE WAIT IS BOUNDED ON PURPOSE, because an embedder is optional: your game\nmust still start when nothing ever answers, just without a bridge. Proceed\non either outcome and read the resolved state to know which kind of boot\nthis is.\n\n```js\nconst state = await gem.frame.settled();\nconst game = await import('./game-engine.js');\ngame.start({ online: state === 'connected' });\n```",
+          "summary": "Wait until it is known whether there is a bridge, then carry on either way.\n\nResolves as soon as the connection is settled — connected, refused or\nclosed — or when the timeout runs out, with whichever state it is in.\n\nTHE GATE TO AWAIT BEFORE LOADING A HEAVY BUNDLE. The connection offer is\ndelivered to your game rather than polled, so if your main thread is busy\nparsing several megabytes of JavaScript, the offer waits behind that work —\nand by the time it arrives the connection it carried may already be gone.\nAwaiting this first keeps the thread free long enough to accept.\n\nTHE WAIT IS BOUNDED ON PURPOSE, because the page framing your game may\nnever answer, and your game must still start and say so. Proceed on either\noutcome and read the resolved state to know which kind of boot this is.\n\n```js\nconst state = await gem.frame.settled();\nconst game = await import('./game-engine.js');\ngame.start({ online: state === 'connected' });\n```",
           "deprecated": null,
           "params": [
             {
@@ -8171,7 +8171,7 @@
           "url": "https://gemarcade.com/developer/api/game#gemviewport-reserved",
           "signature": "readonly reserved: readonly GemReservedArea[]",
           "documented": true,
-          "summary": "Rectangles of your frame the arcade's own controls cover — its Back tab in\nthe top-left corner, and the wallets beside it while they are shown (see\n`setWalletVisible`). Keep essential UI and touch targets out of them. Empty\nwhen the arcade covers nothing.\n\nA stylesheet reads the per-corner custom properties the SDK stamps from\nthese instead — `--gem-reserved-tl-height` and friends.",
+          "summary": "Rectangles of your frame the arcade's own controls cover — its Back tab in\nthe top-left corner, and the wallets in the top-right while they are shown (see\n`setWalletVisible`). Keep essential UI and touch targets out of them. Empty\nwhen the arcade covers nothing.\n\nA stylesheet reads the per-corner custom properties the SDK stamps from\nthese instead — `--gem-reserved-tl-height` and friends.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -8495,7 +8495,7 @@
           "url": "https://gemarcade.com/developer/api/game#gem-awaitidentity",
           "signature": "awaitIdentity(timeoutMs?: number): Promise<GemIdentity>",
           "documented": true,
-          "summary": "The player's identity, waiting for sign-in if it has not finished.\n\nAwait this when you need the ids themselves. Rooms are scoped to your game,\nand your game's id comes from sign-in — but a room call made before it\nlands performs this same wait on your behalf, so awaiting it first is a\nchoice rather than a requirement. In a real session the wait is normally a\nsingle round trip to the page hosting your game.\n\nRejects rather than resolving `null` if the wait runs out: a session that\ncannot sign in cannot do anything else either, and a `null` you might not\ncheck is how a game carries on into a failure it could have reported.",
+          "summary": "The player's identity, waiting for sign-in if it has not finished.\n\nAwait this when you need the ids themselves. Rooms are scoped to your game,\nand your game's id comes from sign-in — but a room call made before it\nlands performs this same wait on your behalf, so awaiting it first is a\nchoice rather than a requirement. In a real session the wait is normally a\nsingle round trip to the page hosting your game.\n\nRejects rather than resolving `null` if the wait runs out: a session that\ncannot sign in cannot do anything else either, and a `null` you might not\ncheck is how a game carries on into a failure it could have reported. It\nrejects at once, without waiting, when the page that framed the game was\nrefused: no token can arrive from it.",
           "deprecated": null,
           "params": [
             {
@@ -8519,7 +8519,7 @@
           "url": "https://gemarcade.com/developer/api/game#gem-awaitbridge",
           "signature": "awaitBridge(timeoutMs?: number): Promise<FrameState | null>",
           "documented": true,
-          "summary": "Waits for the connection to the arcade to settle, one way or the other.\n\nResolves with the state it settled into — connected, refused or closed — or\nwith whatever it had reached by `timeoutMs`, which defaults to 10 seconds.\n\nOUTSIDE THE ARCADE IT WAITS THE FULL TIMEOUT and then resolves `waiting`,\nbecause nothing ever answers. It does not return early. That is ten seconds\non every local run, so pass a shorter `timeoutMs` during development if the\nwait gets in your way.\n\n**Await this in your boot entry before importing your main bundle.** The\narcade hands your game its connection as a one-off delivery rather than\nsomething you can ask for later, so if the browser's main thread is busy\nparsing several megabytes of JavaScript when it arrives, your game can miss\nit. Awaiting this keeps the thread free through that window; the moment it\nresolves, load everything.\n\nCarry on whatever it resolves to. `connected` means you are in the arcade;\nanything else means you are running without it, which your game has to\nsurvive anyway — during local development, that is the normal case.",
+          "summary": "Waits for the connection to the arcade to settle, one way or the other.\n\nResolves with the state it settled into — connected, refused or closed — or\nwith whatever it had reached by `timeoutMs`, which defaults to 10 seconds.\n\nA game is always framed (`createGem` throws [GemUnframedError](https://gemarcade.com/developer/api/game#gemunframederror)\notherwise), so this normally resolves `connected` within a moment. It\nresolves `refused` at once when the page that framed the game is not one it\naccepts, and `waiting` only when the page framing it never answers.\n\n**Await this in your boot entry before importing your main bundle.** The\narcade hands your game its connection as a one-off delivery rather than\nsomething you can ask for later, so if the browser's main thread is busy\nparsing several megabytes of JavaScript when it arrives, your game can miss\nit. Awaiting this keeps the thread free through that window; the moment it\nresolves, load everything.\n\nCarry on whatever it resolves to. `connected` means a Gem host is\nlistening — the Arcade, the Editor or the dev host on your machine;\nanything else means no session, which your game has to survive with a\nmessage rather than a hang.",
           "deprecated": null,
           "params": [
             {
@@ -8543,7 +8543,7 @@
           "url": "https://gemarcade.com/developer/api/game#gem-player",
           "signature": "readonly player: GemPlayer | null",
           "documented": true,
-          "summary": "The player's display identity — the name, handle and avatar you show them.\n\n`null` until the arcade sends it, and always `null` outside the arcade.\nNothing obliges it to be sent at all, so treat its absence as normal and\nhave a fallback: a game with no display name is fine, a game that waits\nforever for one is not.\n\nThe name and handle are player-authored, so they arrive wrapped rather than\nas plain strings — assigning one to `innerHTML` will not compile. Unwrap at\nthe point you render.\n\nThis is distinct from [Gem.identity](https://gemarcade.com/developer/api/game#gem-identity), which is who the platform says\nthey are, and from [Gem.me](https://gemarcade.com/developer/api/game#gem-me), which is their data in your game.",
+          "summary": "The player's display identity — the name, handle and avatar you show them.\n\n`null` until the arcade sends it. Nothing obliges it to be sent at all, so treat its absence as normal and\nhave a fallback: a game with no display name is fine, a game that waits\nforever for one is not.\n\nThe name and handle are player-authored, so they arrive wrapped rather than\nas plain strings — assigning one to `innerHTML` will not compile. Unwrap at\nthe point you render.\n\nThis is distinct from [Gem.identity](https://gemarcade.com/developer/api/game#gem-identity), which is who the platform says\nthey are, and from [Gem.me](https://gemarcade.com/developer/api/game#gem-me), which is their data in your game.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -8960,7 +8960,7 @@
           "url": "https://gemarcade.com/developer/api/game#gem-awaitcohorts",
           "signature": "awaitCohorts(timeoutMs?: number): Promise<GemCohorts | null>",
           "documented": true,
-          "summary": "The experiment cohorts, waiting up to `timeoutMs` for them.\n\nResolves `null` rather than rejecting — outside the arcade too, once the\nwait is out, because no parent is there to answer. Use it at the ONE point\nyour game branches on a cohort — typically\nthe first run's opening — and give it a short budget: the answer normally\narrives within the first second, and a player kept on a splash screen for a\nvalue that changes a tutorial's wording has been made to pay for an\nexperiment they cannot see.",
+          "summary": "The experiment cohorts, waiting up to `timeoutMs` for them.\n\nResolves `null` rather than rejecting once the wait is out, or at once if\nthe page that framed the game was refused. Use it at the ONE point\nyour game branches on a cohort — typically\nthe first run's opening — and give it a short budget: the answer normally\narrives within the first second, and a player kept on a splash screen for a\nvalue that changes a tutorial's wording has been made to pay for an\nexperiment they cannot see.",
           "deprecated": null,
           "params": [
             {
@@ -9032,7 +9032,7 @@
           "url": "https://gemarcade.com/developer/api/game#gem-setwalletvisible",
           "signature": "setWalletVisible(visible: boolean, options?: WalletVisibleOptions): boolean",
           "documented": true,
-          "summary": "Show or hide the player's wallets — Gems, Tickets, the achievement score —\nthat the arcade draws over your game. **They are shown until you say\notherwise**: hide them during gameplay, show them again on your menus.\n\n```js\nlevel.onStart = () => gem.setWalletVisible(false);\nmenu.onOpen = () => gem.setWalletVisible(true);\n// A screen that sells in one currency may narrow it:\nticketStore.onOpen = () => gem.setWalletVisible(true, { only: ['ARCADE_TICKETS'] });\n```\n\n**It is screen state, not a toggle.** Each call is the whole answer and\nreplaces the last. While hidden, the arcade still pops a wallet up for a\nmoment when something happens to it — a reward you cued, a spend, a\nlanding — and your state never cancels that. Shown wallets cover part of\nyour frame beside the Back tab, which arrives as a rectangle in\n`gem.viewport.reserved`; hiding them gives that space back. A wallet the\narcade pops up for a moment floats over your game and moves nothing.\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": "Show or hide the player's wallets — Gems, Tickets, the achievement score —\nthat the arcade draws over your game. **They are shown until you say\notherwise**: hide them during gameplay, show them again on your menus.\n\n```js\nlevel.onStart = () => gem.setWalletVisible(false);\nmenu.onOpen = () => gem.setWalletVisible(true);\n// A screen that sells in one currency may narrow it:\nticketStore.onOpen = () => gem.setWalletVisible(true, { only: ['ARCADE_TICKETS'] });\n```\n\n**It is screen state, not a toggle.** Each call is the whole answer and\nreplaces the last. While hidden, the arcade still pops a wallet up for a\nmoment when something happens to it — a reward you cued, a spend, a\nlanding — and your state never cancels that. Shown wallets cover part of\nyour frame's top-right corner, which arrives as a rectangle in\n`gem.viewport.reserved`; hiding them gives that space back. A wallet the\narcade pops up for a moment floats over your game and moves nothing.\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": [
             {
@@ -9103,7 +9103,7 @@
           "url": "https://gemarcade.com/developer/api/game#gem-frame",
           "signature": "readonly frame: GemFrame",
           "documented": true,
-          "summary": "Your game's connection to the arcade.\n\nALWAYS PRESENT, even when nothing is on the other end. Running outside the\narcade does not make this `null` — the frame simply stays in `waiting`\nforever, which is the state to read when you want to know whether anyone\never answered. Do not write a `=== null` branch; it can never run.\n\n**This is where the loading contract lives.** Call `progress()` as your\ngame loads and `ready()` when it is playable, so the arcade can show a real\nloading state instead of a blank frame. Both are on the platform's release\nchecklist.",
+          "summary": "Your game's connection to the arcade.\n\nALWAYS PRESENT, even when nothing is on the other end yet: a page that\nnever answers leaves the frame in `waiting`, and a refused one ends it in\n`refused`, which is the state to read when you want to know whether anyone\never answered. Do not write a `=== null` branch; it can never run.\n\n**This is where the loading contract lives.** Call `progress()` as your\ngame loads and `ready()` when it is playable, so the arcade can show a real\nloading state instead of a blank frame. Both are on the platform's release\nchecklist.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -9241,7 +9241,7 @@
           "url": "https://gemarcade.com/developer/api/game#creategem",
           "signature": "function createGem(options?: GemOptions): Gem",
           "documented": true,
-          "summary": "Connect your game to the Gem Arcade. This is the one call every game makes.\n\nIt assembles everything and connects to the arcade that framed your game. The\nsame code runs on your machine and in production without a flag — but it needs\na parent either way: run it framed, and until one answers the SDK says so\nrather than letting you assume a session you do not have.\n\nOne dependency, imported like anything else. The install is at\nhttps://gemarcade.com/developer/docs/getting-started#3-add-the-sdk\n\n```js\nimport { createGem } from '@indiegems/gem-web-sdk/sdk';\n\nconst gem = createGem();\n\nawait gem.awaitBridge();      // before loading your main bundle\nconst me = await gem.awaitIdentity();  // who is playing, once sign-in completes\n```\n\nNo options are needed. The Gem Arcade's website and app are always allowed to\nembed your game ([ARCADE_EMBEDDERS](https://gemarcade.com/developer/api/game#arcade_embedders)), and the arcade tells your game\nwhich build it is.\n\nA dev host on your own machine (`gemctl serve`, the Gem Editor) needs no\nentry either: it frames a locally-served game from a loopback origin whose\nport changes every run, and the SDK admits it by rule — only while the game\nitself is served from loopback, so nothing changes once you publish.\n\nPass `allowedEmbedders` only when a site of your own frames your game. It\nadds to the arcade's origins; see [GemOptions.allowedEmbedders](https://gemarcade.com/developer/api/game#gemoptions-allowedembedders).",
+          "summary": "Connect your game to the Gem Arcade. This is the one call every game makes.\n\nIt assembles everything and connects to the arcade that framed your game. The\nsame code runs on your machine and in production without a flag — but it needs\na frame either way. Opened at the top level it throws\n[GemUnframedError](https://gemarcade.com/developer/api/game#gemunframederror), which says how to run it: in the Arcade, the Editor,\nor the Gem dev host on your machine (`npm run dev`, signed in to `gemctl`).\n\nOne dependency, imported like anything else. The install is at\nhttps://gemarcade.com/developer/docs/getting-started#3-add-the-sdk\n\n```js\nimport { createGem } from '@indiegems/gem-web-sdk/sdk';\n\nconst gem = createGem();\n\nawait gem.awaitBridge();      // before loading your main bundle\nconst me = await gem.awaitIdentity();  // who is playing, once sign-in completes\n```\n\nNo options are needed. The Gem Arcade's website and app are always allowed to\nembed your game ([ARCADE_EMBEDDERS](https://gemarcade.com/developer/api/game#arcade_embedders)), and the arcade tells your game\nwhich build it is.\n\nA dev host on your own machine (`gemctl serve`, the Gem Editor) needs no\nentry either: it frames a locally-served game from a loopback origin whose\nport changes every run, and the SDK admits it by rule — only while the game\nitself is served from loopback, so nothing changes once you publish.\n\nPass `allowedEmbedders` only when a site of your own frames your game. It\nadds to the arcade's origins; see [GemOptions.allowedEmbedders](https://gemarcade.com/developer/api/game#gemoptions-allowedembedders).",
           "deprecated": null,
           "params": [
             {
@@ -12980,6 +12980,23 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "GemUnframedError",
+          "name": "GemUnframedError",
+          "anchor": "gemunframederror",
+          "group": "failures",
+          "url": "https://gemarcade.com/developer/api/game#gemunframederror",
+          "signature": "class GemUnframedError",
+          "documented": true,
+          "summary": "Your game was opened without a Gem frame around it.\n\nThrown by `createGem` when the page is the top-level document: nothing\nframed it, so nothing can hand it a player, saves, config or rooms. The SDK\nneeds that frame — the Gem Arcade, the Gem Editor, or the Gem dev host on\nyour own machine — and refuses to start without one rather than running a\ngame that silently has no player.\n\nYou do not construct this. Run the game framed instead: `npm run dev`\n(`gemctl serve start . --dev`) while you edit, `gemctl serve start .` for a\nbuild, signed in to `gemctl` either way. Never open the address the dev\nserver itself prints.\n\nA unit test that constructs the SDK in a simulated DOM has to give its\nwindow a parent of its own, because a simulated top-level window is exactly\nwhat this refuses.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "LeaderboardEntry.playerId",
           "name": "playerId",