@indiegems/gem-web-sdk 7.5.0 → 7.7.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.7.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": [
             {
@@ -9399,6 +9399,40 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "LeaderboardPeriod",
+          "name": "LeaderboardPeriod",
+          "anchor": "leaderboardperiod",
+          "group": "leaderboards",
+          "url": "https://gemarcade.com/developer/api/game#leaderboardperiod",
+          "signature": "interface LeaderboardPeriod",
+          "documented": true,
+          "summary": "Which period a `per_period` board's result is for.\n\nA board whose config sets `per_period: true` exists once per period of the\nchallenge its run type names: one board for each day of a daily challenge,\neach week of a weekly one. Present on a result exactly when the board is one\nof those; absent — not `null` — on an ordinary board.\n\n⚠️ **Players on the same date share a board, whatever their time zone.** On\na challenge that follows each player's own time zone (the default), a date\nbegins for each player at their own midnight, so one day's board is open for\nabout 50 hours worldwide and the standings can still change after YOUR day\nhas ended. [LeaderboardPeriod.final](https://gemarcade.com/developer/api/game#leaderboardperiod-final) says when they no longer can.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "PeriodOptions",
+          "name": "PeriodOptions",
+          "anchor": "periodoptions",
+          "group": "leaderboards",
+          "url": "https://gemarcade.com/developer/api/game#periodoptions",
+          "signature": "interface PeriodOptions",
+          "documented": true,
+          "summary": "Which period of a `per_period` board to read. Shared by every read.\n\nName at most one of [PeriodOptions.periodsBack](https://gemarcade.com/developer/api/game#periodoptions-periodsback) and\n[PeriodOptions.period](https://gemarcade.com/developer/api/game#periodoptions-period); with neither, the read answers for the current\nperiod. On a board that is not `per_period` both are refused with `invalid`\nrather than ignored — asking an all-time board for yesterday and being\nhanded all time would be a different answer with nothing saying so.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "ShowcaseApi",
           "name": "ShowcaseApi",
@@ -12980,6 +13014,142 @@
           "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": "LeaderboardPeriod.id",
+          "name": "id",
+          "anchor": "leaderboardperiod-id",
+          "group": "leaderboards",
+          "url": "https://gemarcade.com/developer/api/game#leaderboardperiod-id",
+          "signature": "readonly id: string",
+          "documented": true,
+          "summary": "The period this board is for: the date for a daily challenge, the Monday\nfor a weekly, the 1st for a monthly (`2026-10-02`), or a cron challenge's\nstart as `2026-10-02T06:00:00Z`.\n\n**This is the board's identity.** Pass it back as\n[GetLeaderboardOptions.period](https://gemarcade.com/developer/api/game#getleaderboardoptions-period) to read this same board again later —\nfrom a shared link, or a history screen — and key any cache on it.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "LeaderboardPeriod.localDate",
+          "name": "localDate",
+          "anchor": "leaderboardperiod-localdate",
+          "group": "leaderboards",
+          "url": "https://gemarcade.com/developer/api/game#leaderboardperiod-localdate",
+          "signature": "readonly localDate?: string",
+          "documented": true,
+          "summary": "The period's calendar date, `YYYY-MM-DD` — the same value\n`gem.challenges.list()` gives as `periodLocalDate` for the challenge, so\nthe two can be compared. Absent for a cron challenge, which has no date.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "LeaderboardPeriod.startAt",
+          "name": "startAt",
+          "anchor": "leaderboardperiod-startat",
+          "group": "leaderboards",
+          "url": "https://gemarcade.com/developer/api/game#leaderboardperiod-startat",
+          "signature": "readonly startAt?: number",
+          "documented": true,
+          "summary": "When this period began for the player the read answered for, in Unix\nseconds. Absent when the read answered for no player — a server or a\nfunction that named none — on a challenge that follows each player's own\ntime zone.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "LeaderboardPeriod.endsAt",
+          "name": "endsAt",
+          "anchor": "leaderboardperiod-endsat",
+          "group": "leaderboards",
+          "url": "https://gemarcade.com/developer/api/game#leaderboardperiod-endsat",
+          "signature": "readonly endsAt?: number",
+          "documented": true,
+          "summary": "When this period ends for that player, in Unix seconds: their own runs stop\ncounting towards this board then.\n\n⚠️ **Not when the board stops changing.** Players in later time zones are\nstill on this date after it; see [LeaderboardPeriod.closesAt](https://gemarcade.com/developer/api/game#leaderboardperiod-closesat) and\n[LeaderboardPeriod.final](https://gemarcade.com/developer/api/game#leaderboardperiod-final). Absent exactly when\n[LeaderboardPeriod.startAt](https://gemarcade.com/developer/api/game#leaderboardperiod-startat) is.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "LeaderboardPeriod.opensAt",
+          "name": "opensAt",
+          "anchor": "leaderboardperiod-opensat",
+          "group": "leaderboards",
+          "url": "https://gemarcade.com/developer/api/game#leaderboardperiod-opensat",
+          "signature": "readonly opensAt: number",
+          "documented": true,
+          "summary": "When this board started accepting runs from anyone, in Unix seconds. `0`\nwhen the platform sent something this SDK could not read.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "LeaderboardPeriod.closesAt",
+          "name": "closesAt",
+          "anchor": "leaderboardperiod-closesat",
+          "group": "leaderboards",
+          "url": "https://gemarcade.com/developer/api/game#leaderboardperiod-closesat",
+          "signature": "readonly closesAt: number",
+          "documented": true,
+          "summary": "When this board stops accepting runs from anyone, in Unix seconds. `0`\nwhen the platform sent something this SDK could not read.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "LeaderboardPeriod.final",
+          "name": "final",
+          "anchor": "leaderboardperiod-final",
+          "group": "leaderboards",
+          "url": "https://gemarcade.com/developer/api/game#leaderboardperiod-final",
+          "signature": "readonly final: boolean",
+          "documented": true,
+          "summary": "`true` once no run can still arrive, so the standings will not change\nagain — stop polling, and say \"final\" if your screen says anything.\n\nWhile it is `false` the standings may change, **including after the\nviewer's own period has ended**: a \"you finished 3rd today\" shown at the\nplayer's midnight can be wrong an hour later. Say \"so far\" until this is\n`true`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "LeaderboardEntry.playerId",
           "name": "playerId",
@@ -13124,7 +13294,7 @@
           "url": "https://gemarcade.com/developer/api/game#leaderboardentry-occurredat",
           "signature": "readonly occurredAt: number",
           "documented": true,
-          "summary": "When the ranked run occurred — Unix seconds.",
+          "summary": "When the ranked run occurred — Unix seconds.\n\n⚠️ **`0` on a `per_period` board whose challenge follows each player's own\ntime zone** (the default `local` boundary). The platform serves no time\nthere: beside the board's date, the time of a run would show which time\nzones its player could be in. Render no time for `0` rather than 1970.\nRanks are unaffected — ties are still broken by the real time.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -13337,6 +13507,23 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "Leaderboard.period",
+          "name": "period",
+          "anchor": "leaderboard-period",
+          "group": "leaderboards",
+          "url": "https://gemarcade.com/developer/api/game#leaderboard-period",
+          "signature": "readonly period?: LeaderboardPeriod",
+          "documented": true,
+          "summary": "Which period this result is for, on a board whose config sets\n`per_period`. Absent on an ordinary board, which ranks every run.\n\nOnce `period.final` is `true` the board no longer changes and need not be\npolled.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "RankedRow.rank",
           "name": "rank",
@@ -13362,7 +13549,7 @@
           "url": "https://gemarcade.com/developer/api/game#rankedrow-occurredat",
           "signature": "readonly occurredAt: number",
           "documented": true,
-          "summary": "When the ranked run occurred — Unix seconds.",
+          "summary": "When the ranked run occurred — Unix seconds. `0` on a `per_period` board\nwhose challenge follows each player's own time zone, where the platform\nserves no time; render nothing for it.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -13413,7 +13600,7 @@
           "url": "https://gemarcade.com/developer/api/game#entityleaderboardentry-occurredat",
           "signature": "readonly occurredAt: number",
           "documented": true,
-          "summary": "When the ranked run occurred — Unix seconds.",
+          "summary": "When the ranked run occurred — Unix seconds. `0` on a `per_period` board\nwhose challenge follows each player's own time zone, where the platform\nserves no time; render nothing for it.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -13660,6 +13847,125 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "EntityLeaderboard.period",
+          "name": "period",
+          "anchor": "entityleaderboard-period",
+          "group": "leaderboards",
+          "url": "https://gemarcade.com/developer/api/game#entityleaderboard-period",
+          "signature": "readonly period?: LeaderboardPeriod",
+          "documented": true,
+          "summary": "Which period these runs are from, on a board whose config sets\n`per_period`: `entries`, `personalBest` and `totalRuns`\nare then that ONE period's, not the entity's whole history. Absent on an\nordinary board.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "PeriodOptions.periodsBack",
+          "name": "periodsBack",
+          "anchor": "periodoptions-periodsback",
+          "group": "leaderboards",
+          "url": "https://gemarcade.com/developer/api/game#periodoptions-periodsback",
+          "signature": "readonly periodsBack?: number",
+          "documented": true,
+          "summary": "How many periods back to read. `0` — the default — is the current period;\n`1` is yesterday's board for a daily challenge, last week's for a weekly.\n\nAn integer from 0 to 400. Anything else is a `TypeError` before the\nrequest is made.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "PeriodOptions.period",
+          "name": "period",
+          "anchor": "periodoptions-period",
+          "group": "leaderboards",
+          "url": "https://gemarcade.com/developer/api/game#periodoptions-period",
+          "signature": "readonly period?: string",
+          "documented": true,
+          "summary": "The period to read, as an earlier result's [LeaderboardPeriod.id](https://gemarcade.com/developer/api/game#leaderboardperiod-id) —\nfor a board reached from a shared link or a history screen. At most 400\nperiods back.\n\n⚠️ A period that has not begun for the player is refused, even when it has\nalready begun for players in time zones ahead of theirs.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "PeriodOptions.playerId",
+          "name": "playerId",
+          "anchor": "periodoptions-playerid",
+          "group": "leaderboards",
+          "url": "https://gemarcade.com/developer/api/game#periodoptions-playerid",
+          "signature": "readonly playerId?: string",
+          "documented": true,
+          "summary": "For a serverless function or a dedicated server: the player whose period\nto answer for. Their credential names no player, so without this a\n`per_period` board on each player's own time zone is answered in UTC,\nwhich is not that player's day.\n\nIgnored in the browser, where the read is always for the signed-in player.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "EntityLeaderboardOptions.periodsBack",
+          "name": "periodsBack",
+          "anchor": "entityleaderboardoptions-periodsback",
+          "group": "leaderboards",
+          "url": "https://gemarcade.com/developer/api/game#entityleaderboardoptions-periodsback",
+          "signature": "readonly periodsBack?: number",
+          "documented": true,
+          "summary": "How many periods back to read. `0` — the default — is the current period;\n`1` is yesterday's board for a daily challenge, last week's for a weekly.\n\nAn integer from 0 to 400. Anything else is a `TypeError` before the\nrequest is made.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "EntityLeaderboardOptions.period",
+          "name": "period",
+          "anchor": "entityleaderboardoptions-period",
+          "group": "leaderboards",
+          "url": "https://gemarcade.com/developer/api/game#entityleaderboardoptions-period",
+          "signature": "readonly period?: string",
+          "documented": true,
+          "summary": "The period to read, as an earlier result's [LeaderboardPeriod.id](https://gemarcade.com/developer/api/game#leaderboardperiod-id) —\nfor a board reached from a shared link or a history screen. At most 400\nperiods back.\n\n⚠️ A period that has not begun for the player is refused, even when it has\nalready begun for players in time zones ahead of theirs.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "EntityLeaderboardOptions.playerId",
+          "name": "playerId",
+          "anchor": "entityleaderboardoptions-playerid",
+          "group": "leaderboards",
+          "url": "https://gemarcade.com/developer/api/game#entityleaderboardoptions-playerid",
+          "signature": "readonly playerId?: string",
+          "documented": true,
+          "summary": "For a serverless function or a dedicated server: the player whose period\nto answer for. Their credential names no player, so without this a\n`per_period` board on each player's own time zone is answered in UTC,\nwhich is not that player's day.\n\nIgnored in the browser, where the read is always for the signed-in player.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "EntityLeaderboardOptions.bucket1",
           "name": "bucket1",
@@ -13728,6 +14034,57 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "GetLeaderboardOptions.periodsBack",
+          "name": "periodsBack",
+          "anchor": "getleaderboardoptions-periodsback",
+          "group": "leaderboards",
+          "url": "https://gemarcade.com/developer/api/game#getleaderboardoptions-periodsback",
+          "signature": "readonly periodsBack?: number",
+          "documented": true,
+          "summary": "How many periods back to read. `0` — the default — is the current period;\n`1` is yesterday's board for a daily challenge, last week's for a weekly.\n\nAn integer from 0 to 400. Anything else is a `TypeError` before the\nrequest is made.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GetLeaderboardOptions.period",
+          "name": "period",
+          "anchor": "getleaderboardoptions-period",
+          "group": "leaderboards",
+          "url": "https://gemarcade.com/developer/api/game#getleaderboardoptions-period",
+          "signature": "readonly period?: string",
+          "documented": true,
+          "summary": "The period to read, as an earlier result's [LeaderboardPeriod.id](https://gemarcade.com/developer/api/game#leaderboardperiod-id) —\nfor a board reached from a shared link or a history screen. At most 400\nperiods back.\n\n⚠️ A period that has not begun for the player is refused, even when it has\nalready begun for players in time zones ahead of theirs.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GetLeaderboardOptions.playerId",
+          "name": "playerId",
+          "anchor": "getleaderboardoptions-playerid",
+          "group": "leaderboards",
+          "url": "https://gemarcade.com/developer/api/game#getleaderboardoptions-playerid",
+          "signature": "readonly playerId?: string",
+          "documented": true,
+          "summary": "For a serverless function or a dedicated server: the player whose period\nto answer for. Their credential names no player, so without this a\n`per_period` board on each player's own time zone is answered in UTC,\nwhich is not that player's day.\n\nIgnored in the browser, where the read is always for the signed-in player.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "GetLeaderboardOptions.bucket1",
           "name": "bucket1",
@@ -13787,7 +14144,7 @@
           "url": "https://gemarcade.com/developer/api/game#leaderboardsapi-get",
           "signature": "get(leaderboardType: string, options?: GetLeaderboardOptions): Promise<Leaderboard>",
           "documented": true,
-          "summary": "Read one board, whole.\n\nA bucketed board (config `bucket_by`) needs exactly its bucket values —\n`get('weekly', { bucket1: 'na' })` — and refuses a mismatch. Poll no\nfaster than the result's `updateFrequencySeconds`; the server regenerates\nat that cadence and faster polling re-reads the same rendering.",
+          "summary": "Read one board, whole.\n\nA bucketed board (config `bucket_by`) needs exactly its bucket values —\n`get('weekly', { bucket1: 'na' })` — and refuses a mismatch. Poll no\nfaster than the result's `updateFrequencySeconds`; the server regenerates\nat that cadence and faster polling re-reads the same rendering.\n\nA `per_period` board answers for one period — the current one by default:\n\n```js\nconst today = await gem.leaderboards.get('daily');\nconst yesterday = await gem.leaderboards.get('daily', { periodsBack: 1 });\nlabel(today.period.final ? 'Final standings' : 'Standings so far');\n```",
           "deprecated": null,
           "params": [
             {
@@ -13804,7 +14161,7 @@
             }
           ],
           "returns": null,
-          "throws": "`not_found` when no board with this id is in the channel's active\n  config, `invalid` when bucket values do not match the board's\n  `bucket_by`.",
+          "throws": "`TypeError` when `periodsBack` is not an integer from 0 to 400,\n  `period` is not a period id, or both are passed — refused before the\n  request.\n\n`not_found` when no board with this id is in the channel's active\n  config, `invalid` when bucket values do not match the board's\n  `bucket_by`, when a period is asked of a board that is not `per_period`\n  (`code` `invalid_period`), or when the period has not begun for the\n  player (`code` `period_not_begun`).",
           "example": null,
           "defaultValue": null,
           "guides": []
@@ -13817,7 +14174,7 @@
           "url": "https://gemarcade.com/developer/api/game#leaderboardsapi-friends",
           "signature": "friends(leaderboardType: string, options?: GetLeaderboardOptions): Promise<Leaderboard>",
           "documented": true,
-          "summary": "The same board, ranked over you and your accepted friends only.\n\nSame run type, ordering, buckets and `maxSize` as `get`, and the\nsame cached cadence — but ranks are positions **within this restricted\nboard**, not global ones. Your own rows carry\n[LeaderboardEntry.isViewer](https://gemarcade.com/developer/api/game#leaderboardentry-isviewer), which is what lets a standings screen\nmark \"you\"; on `get` that field is absent rather than false, because\na global board does not answer the question at all.\n\nA player with no friends gets a board of one — their own rows — not an\nerror. Character-owned runs are never on a friend board: friendship is a\nplayer-to-player relation.\n\n```js\nconst board = await gem.leaderboards.friends('time-trial');\nfor (const row of board.entries) {\n  const name = row.displayTag ? text.toPlain(row.displayTag) : 'Anonymous player';\n  render(row.rank, name, { you: row.isViewer });\n}\n```",
+          "summary": "The same board, ranked over you and your accepted friends only.\n\nSame run type, ordering, buckets and `maxSize` as `get`, and the\nsame cached cadence — but ranks are positions **within this restricted\nboard**, not global ones. Your own rows carry\n[LeaderboardEntry.isViewer](https://gemarcade.com/developer/api/game#leaderboardentry-isviewer), which is what lets a standings screen\nmark \"you\"; on `get` that field is absent rather than false, because\na global board does not answer the question at all.\n\nA player with no friends gets a board of one — their own rows — not an\nerror. Character-owned runs are never on a friend board: friendship is a\nplayer-to-player relation.\n\n```js\nconst board = await gem.leaderboards.friends('time-trial');\nfor (const row of board.entries) {\n  const name = row.displayTag ? text.toPlain(row.displayTag) : 'Anonymous player';\n  render(row.rank, name, { you: row.isViewer });\n}\n```\n\nOn a `per_period` board this takes the same `periodsBack` and `period` as\n`get`. A friend in another time zone who is on the same date is on\nthe same board.",
           "deprecated": null,
           "params": [
             {
@@ -13834,7 +14191,7 @@
             }
           ],
           "returns": null,
-          "throws": "`not_found` when no board with this id is in the channel's active\n  config, `invalid` when bucket values do not match the board's\n  `bucket_by`, and `forbidden` in a context with no player — the friend\n  view is a player surface, and a game server has no friends. (The global\n  `get` declares no such refusal: it needs no viewer.)",
+          "throws": "`not_found` when no board with this id is in the channel's active\n  config, `invalid` when bucket values or a period do not match the board\n  (as on `get`), and `forbidden` in a context with no player — the\n  friend view is a player surface, and a game server has no friends. (The\n  global `get` declares no such refusal: it needs no viewer.)",
           "example": null,
           "defaultValue": null,
           "guides": []
@@ -13847,7 +14204,7 @@
           "url": "https://gemarcade.com/developer/api/game#leaderboardsapi-mine",
           "signature": "mine(leaderboardType: string, options?: EntityLeaderboardOptions): Promise<EntityLeaderboard>",
           "documented": true,
-          "summary": "Your own runs on a board, best first, with your personal best.\n\nThis is the read for \"New personal best!\" and for a run-history panel. It\nis **not** a slice of the global board: `rank` is your position among your\nown runs, so `rank: 1` is your best — which is the number most games\nactually want and the one the global board cannot give you unless you\nhappen to be on it.\n\n```js\nconst mine = await gem.leaderboards.mine('time-trial');\nif (mine.personalBest) show(mine.personalBest.stats?.finish_ms);\n```\n\n**When to call it.** Not on a timer — there is no cadence to poll at, and\ndeliberately no `updateFrequencySeconds` on the result. Call it once a run\nhas been reported. ⚠️ Reporting a run is your dedicated server's job, or\nyour serverless function's, and your client has no happens-after edge with\na server: a read fired the instant a match ends can legitimately miss the\nrun just played. Read it when your server has told your client the run\nlanded, or once the function that recorded it has answered.\n\nAn empty result is the ordinary state of a player who has not played yet —\na `200` with no entries, not an error. If it is *always* empty, see\n[LeaderboardsApi](https://gemarcade.com/developer/api/game#leaderboardsapi) on where runs come from: a browser cannot submit\none.",
+          "summary": "Your own runs on a board, best first, with your personal best.\n\nThis is the read for \"New personal best!\" and for a run-history panel. It\nis **not** a slice of the global board: `rank` is your position among your\nown runs, so `rank: 1` is your best — which is the number most games\nactually want and the one the global board cannot give you unless you\nhappen to be on it.\n\n```js\nconst mine = await gem.leaderboards.mine('time-trial');\nif (mine.personalBest) show(mine.personalBest.stats?.finish_ms);\n```\n\n**When to call it.** Not on a timer — there is no cadence to poll at, and\ndeliberately no `updateFrequencySeconds` on the result. Call it once a run\nhas been reported. ⚠️ Reporting a run is your dedicated server's job, or\nyour serverless function's, and your client has no happens-after edge with\na server: a read fired the instant a match ends can legitimately miss the\nrun just played. Read it when your server has told your client the run\nlanded, or once the function that recorded it has answered.\n\nAn empty result is the ordinary state of a player who has not played yet —\na `200` with no entries, not an error. If it is *always* empty, see\n[LeaderboardsApi](https://gemarcade.com/developer/api/game#leaderboardsapi) on where runs come from: a browser cannot submit\none.\n\nOn a `per_period` board the runs, the personal best and the total are ONE\nperiod's — the current one unless `periodsBack` or `period` names another\n— so `personalBest` is \"your best today\", and an empty result at the start\nof a day is the ordinary state.",
           "deprecated": null,
           "params": [
             {