@indiegems/gem-web-sdk 7.6.0 → 7.8.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.8.0"
   },
   "entries": [
     {
@@ -7572,6 +7572,23 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "GemOptions.selectableText",
+          "name": "selectableText",
+          "anchor": "gemoptions-selectabletext",
+          "group": "start",
+          "url": "https://gemarcade.com/developer/api/game#gemoptions-selectabletext",
+          "signature": "readonly selectableText?: boolean",
+          "documented": true,
+          "summary": "Leave your page's text selectable. Default `false`: the SDK stops\naccidental text selection, the long-press copy menu and the tap highlight\nacross your document, because in a game every one of them is a press the\nplayer did not mean.\n\nYour own CSS always wins — the SDK's rule has zero specificity — so to make\none element copyable, give it `user-select: text` (and\n`-webkit-user-select: text`). Inputs, text areas and editable content stay\ntypeable and selectable without anything from you. Set this to `true` only\nif your game is mostly text a player should be able to copy.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "GemOptions.onPause",
           "name": "onPause",
@@ -9399,6 +9416,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 +13048,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 +13311,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 +13524,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 +13566,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 +13617,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 +13864,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 +14051,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 +14161,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 +14178,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 +14191,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 +14208,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 +14221,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": [
             {
@@ -17900,6 +18257,23 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "Room.selfHosted",
+          "name": "selfHosted",
+          "anchor": "room-selfhosted",
+          "group": "rooms",
+          "url": "https://gemarcade.com/developer/api/game#room-selfhosted",
+          "signature": "readonly selfHosted: boolean",
+          "documented": true,
+          "summary": "Whether this room's matches are served from the developer's own machine\nrather than by the platform.\n\nTrue only inside a development tool that runs your game's server locally\n(the Gem Editor's play surface). The SDK asks for such a room on your\nbehalf — there is no option for a game to set — and the platform keeps it\nto its host: no other player can join it, quick-join never matches into\nit, and the server browser never lists it. False on every room a player in\nthe Arcade is in.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "Room.matchId",
           "name": "matchId",

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/dedicated-server-flow.md

@@ -849,20 +849,29 @@ the same thing and a regression on either would be silent.
 Inside a development tool that can host — it advertises the `localHost` capability, which no
 player-facing embedder carries — the platform can dispatch a dedicated match to a server running
 on the developer's own machine instead of allocating one from the fleet. **Your game's source does
-not participate.** Immediately before starting a match, the SDK asks the embedder for a server for
-the room; the tool spawns your game's own server bundle, registers it with the platform, and the
-match that follows is dispatched to it. A game published to players never runs inside such an
-embedder, so there is nothing to gate and nothing to remove before shipping.
-
-Three things are worth knowing while you develop this way:
-
-- **The ask happens before the match starts, and a refusal arrives as `startMatch()` rejecting —
-  never as a hang.** The two failure shapes are deliberately different. A platform refusal (you are
-  not signed in as a developer on this game, or the room is not on a development channel) is
-  terminal, and retrying sends the same request to the same refusal. A machine that merely could
-  not start the process is retryable, and your tool has the log. Silence is bounded too: an
-  embedder that never answers is given thirty seconds, then the rejection says so. However many
-  times a racing Start button asks, one server is started per room.
+not participate.** Every room the SDK creates there — by `create()` or `quickJoin()` — is a
+*self-hosted* room (`room.selfHosted` is `true`), and the moment the SDK holds one it asks the
+embedder for a server for it; the tool spawns your game's own server bundle and registers it with
+the platform. A self-hosted room's match is dispatched to that server and never to the fleet: a
+template with `auto_start_host` waits for the registration and then starts by itself, and a start
+your game makes waits for the server first. A game published to players never runs inside such
+an embedder, so there is nothing to gate and nothing to remove before shipping.
+
+Four things are worth knowing while you develop this way:
+
+- **A self-hosted room is yours alone.** Nobody else can join it, `quickJoin()` makes a fresh one
+  rather than joining another player's room, and the server browser never lists it. The build you
+  are running does not need to be published on the channel: the platform skips its published-build
+  check for these rooms, though a blacklisted build is still refused. A room created with a party
+  is an ordinary room.
+
+- **A refusal arrives as `startMatch()` rejecting — never as a hang.** The two failure shapes are
+  deliberately different. A platform refusal (you are not signed in as a developer on this game,
+  or the room is not on a development channel) is terminal, and retrying sends the same request
+  to the same refusal. A machine that merely could not start the process is retryable, and your
+  tool has the log. Silence is bounded too: an embedder that never answers is given thirty
+  seconds, then the rejection says so. However many times a racing Start button asks, one server
+  is started per room.
 
 - **The winning transport is usually WebSocket, so take the negotiated path.** A locally run server
   typically offers no WebTransport certificate chain and no WebRTC signaling; the ladder works

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.8.0"
 }
 ```