@indiegems/gem-web-sdk 7.6.0 → 7.7.0

package/docs/api/reference.json

@@ -2,7 +2,7 @@
   "schema_version": 1,
   "source": {
     "repo": "IndieGems/gem-web-sdk",
-    "version": "7.6.0"
+    "version": "7.7.0"
   },
   "entries": [
     {
@@ -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",
@@ -12997,6 +13031,125 @@
           "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",
@@ -13141,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,
@@ -13354,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",
@@ -13379,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,
@@ -13430,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,
@@ -13677,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",
@@ -13745,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",
@@ -13804,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": [
             {
@@ -13821,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": []
@@ -13834,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": [
             {
@@ -13851,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": []
@@ -13864,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": [
             {

package/docs/daily-challenges.md

@@ -64,8 +64,10 @@ reset_schedule: { type: daily, boundary: UTC, reset_time: '04:00' }
 
 - **`boundary`** — `local`, the default, is each player's own time zone. An IANA zone name such as
   `UTC` or `Asia/Tokyo` puts every player on that one calendar instead, so everybody's day turns
-  over at the same instant: what a daily leaderboard, or a server that works out "today" for
-  itself, needs.
+  over at the same instant: what a strictly fair daily leaderboard, or a server that works out
+  "today" for itself, needs. A daily leaderboard works on `local` too, with players on the same
+  date sharing a board — [section 10](#10-what-your-game-can-read-back) has the read, and
+  [leaderboards.md](leaderboards.md#one-day-many-time-zones) what the choice costs.
 - **`reset_time`** — the clock time, `HH:MM` in that zone, at which a period begins. The default is
   `00:00`; `'04:00'` lets a late-night player finish the day they started. Quote it: some YAML
   parsers read an unquoted `04:00` as a number.
@@ -563,6 +565,16 @@ server reads the same list for one player with `gem.challenges.list({ playerId }
 **How the player is doing in THIS period — yes**, through the ordinary progression read
 (section 3): `currentValue` and `isCompleted` are this period's, and reset with it.
 
+**How everybody did in THIS period — yes, if you declare a board for it.** A leaderboard can be
+scoped to this challenge's periods: today's standings, which start empty each day and close when
+the day does. Name the challenge on the board's run type and set `per_period` on the board; the
+board then takes this challenge's schedule, boundary and reset time, and
+`gem.leaderboards.get('daily')` answers for the player's current period. It needs no
+`platform_display` and no stored content. When your function or server records the run, send the
+`periodLocalDate` you read here as the run's `period_id`, so a run finished just before midnight
+counts for the day it was played. [A board for each day](leaderboards.md#a-board-for-each-day-period-boards)
+is the page.
+
 **Their per-period history and their streak — no.** There is no history read and no streak read in
 the SDK. The arcade is what displays those — the marker on your game's card, and the player's own
 progress, history and streak on platform surfaces. Your game does not have to render any of it.

package/docs/getting-started.md

@@ -50,7 +50,7 @@ either way.
 ```jsonc
 // package.json
 "dependencies": {
-  "@indiegems/gem-web-sdk": "7.6.0"
+  "@indiegems/gem-web-sdk": "7.7.0"
 }
 ```