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.

[Tortue95]

Hi!

I wanted to gently follow up on this PR and ask whether this kind of integration point has a realistic chance of being accepted into the MaiaChess frontend eventually.

I fully understand that this does not directly improve the standalone MaiaChess web experience, so I would totally understand if it is considered out of scope. I’m mainly trying to decide whether I should continue polishing this PR for upstream integration, or whether I should instead support MaiaChess from ChessConnect through a more fragile local workaround, such as DOM inference.

My preference would clearly be the upstream approach, because it keeps the integration explicit, lightweight, and much less likely to break when the UI changes. I’m happy to adapt the API shape, rename the global object, reduce the exposed state, add documentation, split the change, or take any other direction that would make this easier to maintain on your side.

Could you let me know whether this is something you would consider merging in principle?

Thanks again for your time and for the work on MaiaChess.