Expose MaiaChess clock state for electronic chessboards

[Tortue95]

Expose MaiaChess clock state for electronic chessboards

Why this PR

Our goal is to provide an experience that feels as close as possible to a real over-the-board chess game.

To support that, this PR adds a small integration point on the MaiaChess side so external applications, such as ChessConnect, can synchronize a physical chess clock when the game is played on an electronic chessboard.

Today, ChessConnect can already track the MaiaChess board and send moves to a connected board. However, the clock times cannot currently be retrieved in a reliable way.

One possible solution would be to read the displayed clock values directly from the DOM, but that approach is fragile. The HTML elements that display the MaiaChess clocks do not have explicit names or attributes indicating which div represents which clock, or which player it belongs to. An integration would therefore have to infer that information from the visual structure of the page, which is complex, and unreliable over time: a layout or CSS class change could break the integration without any functional change to the clock itself.

This PR therefore exposes an explicit clock state from MaiaChess, instead of requiring external integrations to guess that state from the rendered HTML.

What this PR adds

This PR exposes the current MaiaChess clock state through a neutral global object:

window.__MaiaClockState

This object contains the information needed to drive an external clock:

{
  whiteRemainingMs: number
  blackRemainingMs: number
  whiteInitialMs: number
  blackInitialMs: number
  remainingAtMs: number
  turnColor: 'white' | 'black' | null
  activeColor: 'white' | 'black' | null
  lifecycle: 'not_started' | 'ongoing' | 'finished'
  result: 'white_wins' | 'black_wins' | 'draw' | null
}

Details

• turnColor indicates whose turn it is, even when no clock is running.
• activeColor only indicates the color whose clock should be counting down.
• activeColor is null for games without a time limit.
• activeColor is also null until the game has actually started.
• remainingAtMs allows consumers to recalculate the current remaining time without requiring continuous React updates.
• lifecycle allows an external integration to distinguish between a game that has not started, a game in progress, and a finished game.
• result allows the final game state to be propagated correctly to a clock or connected device.

A big thank you to the maintainers!

I am fully aware that this modification has no direct utility for the MaiaChess website when used as a standalone platform. However, it opens the door to wonderful possibilities for the over-the-board (OTB) chess community.

I wanted to warmly thank you for the time you will spend reviewing this PR and, more generally, for all your work on this project.

To keep the application clean and avoid any bloat, I made sure this integration is as lightweight and non-intrusive as possible. If you would like me to adjust anything to align perfectly with your standards, please don't hesitate to let me know!

[vercel]

Someone is attempting to deploy a commit to the Maia Platform Team on Vercel.

A member of the Team first needs to authorize it.