feat: add lobby creation time tracking to GameStartInfo

[abdallahbahrawi1]

Description:

Tracking lobby fill time by including lobby creation timestamp in GameStartInfo schema. This prepares the foundation for implementing lobby fill time statistics as requested in #1806.

• fixes Track the time to lobby fill in stats #1806

Please complete the following:

• I have added screenshots for all UI updates
• I process any text displayed to the user through translateText() and I've added it to the en.json file
• I have added relevant tests to the test directory
• I confirm I have thoroughly tested these changes and take full responsibility for any bugs introduced

Please put your Discord username so you can be contacted if a bug or regression is found:

abodcraft1

[coderabbitai]

Walkthrough

Adds lobbyCreatedAt to game start info and propagates it through client/server flows. Extends game record creation to accept lobbyCreatedAt, normalizes it, and computes lobbyFillTime. Updates archiving to store these fields. Schema types updated accordingly.

Changes

Cohort / File(s)	Summary
Core Schemas src/core/Schemas.ts	Add lobbyCreatedAt to GameStartInfoSchema; add lobbyFillTime to GameEndInfoSchema; update exported types accordingly.
Core Utilities src/core/Util.ts	Update createGameRecord signature to include lobbyCreatedAt (defaulting to start); normalize value; compute and store lobbyFillTime; include lobbyCreatedAt and lobbyFillTime in returned record.
Server Start/Archive src/server/GameServer.ts	Include lobbyCreatedAt in GameStartInfo payload (from createdAt); pass lobbyCreatedAt to createGameRecord during archive.
Client Start (UI/Event) src/client/SinglePlayerModal.ts	Include lobbyCreatedAt: Date.now() in join-lobby gameStartInfo payload; update related event typing.
Client Save Flow src/client/ClientGameRunner.ts	Pass lobbyCreatedAt to createGameRecord in saveGame.
Local Server Save Flow src/client/LocalServer.ts	Pass lobbyCreatedAt to createGameRecord in endGame.

Sequence Diagram(s)

sequenceDiagram
  autonumber
  participant U as User
  participant C as Client (Modal/Runner)
  participant S as Server (GameServer)
  participant Util as createGameRecord
  participant Arch as Archive

  U->>C: Start single-player
  Note right of C: Set lobbyCreatedAt = Date.now()
  C->>S: join-lobby(gameStartInfo + lobbyCreatedAt)
  S-->>C: start(gameStartInfo + lobbyCreatedAt)

  rect rgba(230,245,255,0.5)
    Note over C,S: Gameplay
  end

  C->>Util: createGameRecord(..., start, end, winner, serverConfig, lobbyCreatedAt)
  Util-->>C: GameRecord(info includes lobbyCreatedAt, lobbyFillTime)

  C->>S: endGame(GameRecord)
  S->>Arch: archive(GameRecord with lobbyCreatedAt, lobbyFillTime)
  Arch-->>S: done

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Assessment against linked issues

Objective	Addressed	Explanation
Track lobby creation timestamp in start info and flows (#1806)	✅
Compute lobbyFillTime from lobbyCreatedAt and start (#1806)	✅
Persist lobbyCreatedAt and lobbyFillTime in archived game records (#1806)	✅

Possibly related PRs

• Add domain, subdomain to GameRecord #1370 — Also extends createGameRecord API (adds serverConfig); similar call-site updates.
• Combine analytics and game types #839 — Changes game record schema and createGameRecord with call-site updates across client/server.
• Fix all strict errors in /client #1489 — Touches join-lobby/SinglePlayerModal typings; related to adding fields in start payloads.

Suggested labels

Feature - Frontend

Suggested reviewers

• scottanderson
• evanpelle

Poem

A lobby starts, the clock does chime,
We mark its birth, we measure time.
From wait to play, the seconds fill,
Now stats can tell the patient thrill.
Ticks to turns, the record sings—
Data lands on measured wings.

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

💡 Knowledge Base configuration:

• MCP integration is disabled by default for public repositories
• Jira integration is disabled by default for public repositories
• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between 63c9dde and 6cc0157.

📒 Files selected for processing (1)

• src/server/GameServer.ts (2 hunks)

🚧 Files skipped from review as they are similar to previous changes (1)

• src/server/GameServer.ts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

• Review comments: Directly reply to a review comment made by CodeRabbit. Example:
  • I pushed a fix in commit <commit_id>, please review it.
  • Open a follow-up GitHub issue for this discussion.
• Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query.
• PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
  • @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
  • @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.

Support

Need help? Create a ticket on our support page for assistance with any issues or questions.

CodeRabbit Commands (Invoked using PR/Issue comments)

Type @coderabbitai help to get the list of available commands.

Other keywords and placeholders

• Add @coderabbitai ignore or @coderabbit ignore anywhere in the PR description to prevent this PR from being reviewed.
• Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
• Add @coderabbitai anywhere in the PR title to generate the title automatically.

CodeRabbit Configuration File (.coderabbit.yaml)

• You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
• Please see the configuration documentation for more information.
• If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

Status, Documentation and Community

• Visit our Status Page to check the current availability of CodeRabbit.
• Visit our Documentation for detailed information on how to use CodeRabbit.
• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[coderabbitai]

Actionable comments posted: 1

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

src/server/GameServer.ts (1)

334-340: Remove duplicate top-level lobbyCreatedAt in start payload and schema

Delete the redundant lobbyCreatedAt from the server start-game JSON and from its schema—it's already carried inside gameStartInfo.

src/server/GameServer.ts
@@ -335,7 +335,6 @@
           gameStartInfo: this.gameStartInfo,
-          lobbyCreatedAt: this.createdAt,
           turns: this.turns.slice(lastTurn),
           type: "start",

src/core/Schemas.ts
@@ -450,7 +450,6 @@
   gameStartInfo: GameStartInfoSchema,
   // Turns the client missed if they are late to the game.
-  lobbyCreatedAt: z.number(),
   turns: TurnSchema.array(),
   type: z.literal("start"),

🧹 Nitpick comments (4)

src/core/GameRunner.ts (1)

92-97: Revert spacing to match formatter rules

Constructor closes as ") { }". Most formatters (Prettier) collapse this to ") {}". Please run the formatter or revert to keep diffs clean.

-  ) { }
+  ) {}

src/core/Schemas.ts (2)

416-421: Stronger validation for timestamp

If this is Date.now() ms, constrain to int and nonnegative for clarity and defense.

-  lobbyCreatedAt: z.number(),
+  lobbyCreatedAt: z.number().int().nonnegative(),

---

449-455: Avoid duplicating lobbyCreatedAt; keep a single source of truth

lobbyCreatedAt is already inside gameStartInfo. Duplicating it at the top level invites drift and increases payload size. Recommend removing the top-level field. Bonus: the “Turns the client missed …” comment currently sits above lobbyCreatedAt by accident; removing this line restores the comment to the turns field.

 export const ServerStartGameMessageSchema = z.object({
   gameStartInfo: GameStartInfoSchema,
-  // Turns the client missed if they are late to the game.
-  lobbyCreatedAt: z.number(),
+  // Turns the client missed if they are late to the game.
   turns: TurnSchema.array(),
   type: z.literal("start"),
 });

src/server/GameServer.ts (1)

296-306: Populate lobbyCreatedAt only inside gameStartInfo

Server already sends createdAt inside gameStartInfo. Keep a single source of truth and drop the extra top-level field in the start message for consistency with the schema change above.

     const result = GameStartInfoSchema.safeParse({
       config: this.gameConfig,
       gameID: this.id,
-      lobbyCreatedAt: this.createdAt,
+      lobbyCreatedAt: this.createdAt,
       players: this.activeClients.map((c) => ({
         clientID: c.clientID,
         flag: c.flag,
         pattern: c.pattern,
         username: c.username,
       })),
     });

(Left-hand side unchanged; shown for context.)

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

💡 Knowledge Base configuration:

• MCP integration is disabled by default for public repositories
• Jira integration is disabled by default for public repositories
• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between 2094249 and bd2cc1c.

📒 Files selected for processing (4)

• src/core/GameRunner.ts (1 hunks)
• src/core/Schemas.ts (2 hunks)
• src/core/game/Stats.ts (1 hunks)
• src/server/GameServer.ts (2 hunks)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)

• GitHub Check: Has Milestone

[coderabbitai]

Actionable comments posted: 0

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (2)

src/core/Util.ts (2)

155-193: Bug: lobbyCreatedAt should not be Date.now() at record creation

This records the time when the record is built, not when the lobby was created. It will skew “lobby fill time” and can even be greater than start/end. Pass the true lobbyCreatedAt into this function and store it as-is. Keep server as the source of truth.

Apply:

 export function createGameRecord(
   gameID: GameID,
   config: GameConfig,
   // username does not need to be set.
   players: PlayerRecord[],
   allTurns: Turn[],
   start: number,
   end: number,
   winner: Winner,
-  serverConfig: ServerConfig,
+  serverConfig: ServerConfig,
+  // Source-of-truth lobby creation time (ms). Default to `start` for backward compat.
+  lobbyCreatedAt: number = start,
 ): GameRecord {
@@
     info: {
       config,
       duration,
       end,
       gameID,
-      lobbyCreatedAt: Date.now(),
+      lobbyCreatedAt,
       num_turns,
       players,
       start,
       winner,
     },

---

155-193: Refactor createGameRecord to accept lobbyCreatedAt
– In src/core/Util.ts (around lines 155–163), add a lobbyCreatedAt: number parameter (e.g. after config) and use it in info.lobbyCreatedAt instead of Date.now().
– Update all call sites to pass the real timestamp:
• src/server/GameServer.ts at line 594: pass this.gameStartInfo.lobbyCreatedAt as the new arg.
• src/client/LocalServer.ts at line 192: pass this.lobbyConfig.gameStartInfo.lobbyCreatedAt.
• src/client/ClientGameRunner.ts at line 226: pass this.lobby.gameStartInfo.lobbyCreatedAt.

🧹 Nitpick comments (2)

src/core/Util.ts (1)

155-193: Add a quick sanity check (optional)

Guard against bad clocks: ensure lobbyCreatedAt ≤ start ≤ end.

 ): GameRecord {
+  if (lobbyCreatedAt > start) {
+    // Normalize to avoid negative fill times due to clock skew.
+    lobbyCreatedAt = start;
+  }
   const duration = Math.floor((end - start) / 1000);

src/client/SinglePlayerModal.ts (1)

432-466: Client timestamp is fine for single-player; ensure server ignores it for MP

Using Date.now() here is OK for single-player UX. For multiplayer, the server should overwrite/ignore client-provided lobbyCreatedAt to prevent spoofing and clock drift.

If needed, extract a tiny helper for testability:

-            lobbyCreatedAt: Date.now(),
+            lobbyCreatedAt: Date.now(), // ms; server should be authoritative in MP

To verify server authority, confirm GameServer uses its own createdAt and does not trust client values.

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

💡 Knowledge Base configuration:

• MCP integration is disabled by default for public repositories
• Jira integration is disabled by default for public repositories
• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between 2721610 and 8498f18.

📒 Files selected for processing (2)

• src/client/SinglePlayerModal.ts (1 hunks)
• src/core/Util.ts (1 hunks)

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (3)

src/core/Schemas.ts (1)

416-421: Clarify units for lobbyCreatedAt (ms).

Make the time unit explicit to avoid confusion later.

 export const GameStartInfoSchema = z.object({
   config: GameConfigSchema,
   gameID: ID,
-  lobbyCreatedAt: z.number().int().nonnegative(),
+  // Epoch time in milliseconds when the lobby was created.
+  lobbyCreatedAt: z.number().int().nonnegative(),
   players: PlayerSchema.array(),
 });

src/core/Util.ts (2)

165-171: Avoid parameter mutation; harden normalization.

Guard NaN/negative inputs and avoid mutating the parameter for cleaner TS.

-  if (lobbyCreatedAt > start) {
-    // Normalize to avoid negative fill times due to clock skew.
-    lobbyCreatedAt = start;
-  }
+  // Normalize to avoid NaN/negative and future timestamps due to clock skew.
+  const normalizedLobbyCreatedAt =
+    Number.isFinite(lobbyCreatedAt) && lobbyCreatedAt >= 0
+      ? Math.min(Math.trunc(lobbyCreatedAt), start)
+      : start;

---

181-192: Make units explicit and use the normalized value.

Keep ms units clear and wire the normalized timestamp into the record.

-  const lobbyFillTime = Math.max(0, start - lobbyCreatedAt);
+  // Milliseconds between lobby creation and start.
+  const lobbyFillTime = Math.max(0, start - normalizedLobbyCreatedAt);
   const record: GameRecord = {
     domain,
     gitCommit,
     info: {
       config,
       duration,
       end,
       gameID,
-      lobbyCreatedAt,
+      lobbyCreatedAt: normalizedLobbyCreatedAt,
       lobbyFillTime,
       num_turns,
       players,
       start,
       winner,
     },

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

💡 Knowledge Base configuration:

• MCP integration is disabled by default for public repositories
• Jira integration is disabled by default for public repositories
• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between 8498f18 and 86cd484.

📒 Files selected for processing (6)

• src/client/ClientGameRunner.ts (1 hunks)
• src/client/LocalServer.ts (1 hunks)
• src/client/SinglePlayerModal.ts (1 hunks)
• src/core/Schemas.ts (2 hunks)
• src/core/Util.ts (3 hunks)
• src/server/GameServer.ts (2 hunks)

🚧 Files skipped from review as they are similar to previous changes (2)

• src/server/GameServer.ts
• src/client/SinglePlayerModal.ts

🧰 Additional context used

🧬 Code graph analysis (1)

src/core/Util.ts (2)

src/client/ClientGameRunner.ts (1)

• start (241-366)

src/server/GameServer.ts (1)

• start (286-325)

🔇 Additional comments (3)

src/core/Schemas.ts (1)

542-550: Make lobbyCreatedAt and lobbyFillTime optional in GameEndInfoSchema

Omit those fields from the base schema and re-add them as optional in the extend to avoid breaking legacy records.

I didn’t find any v0.0.2 JSON fixtures in the repo; please verify whether archived game data without these fields exist in production or fixtures to ensure backward compatibility.

src/client/LocalServer.ts (1)

201-202: LGTM: passing lobbyCreatedAt through to createGameRecord.

Matches the new signature and ensures archives contain the source timestamp.

src/client/ClientGameRunner.ts (1)

236-237: LGTM: include lobbyCreatedAt when saving.

Call site updated and aligned with Util.createGameRecord.

The merge-base changed after approval.

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you all sign our Contributor License Agreement before we can accept your contribution.
0 out of 2 committers have signed the CLA.

❌ abdallahbahrawi1
❌ scottanderson
_{You have signed the CLA already but the status is still pending? Let us recheck it.}