feat(frontend): show the game clocks in live games

Both clocks sit next to the players' names and count down in server time; the running one is highlighted and turns red under 30 seconds. They replace the offline countdown, so core drops TURN_TIMEOUT_MS, INACTIVE_TIMEOUT_MS, offlineSince and its text. Long info texts wrap on phones.
2026-10-16 01:39:36 +03:00 · 2026-10-16 01:39:36 +03:00 · 20359b7a8f
commit 20359b7a8f
parent c610844e26
9 changed files with 88 additions and 40 deletions
--- a/apps/frontend/src/components/GameClockView.tsx
+++ b/apps/frontend/src/components/GameClockView.tsx
@ -0,0 +1,40 @@
+import * as React from 'react';
+import { FunctionComponent } from 'react';
+import { CLOCK_LOW_TIME_MS, formatClock, getColorByBrightness } from "@mancala/core";
+import { Context } from '../context/context';
+
+// Readable on every theme; the themes have no warning color of their own.
+const LOW_TIME_COLOR = "#b3261e";
+const LOW_TIME_TEXT_COLOR = "#ffffff";
+
+// One player's clock: highlighted while it runs, in a warning color when the running clock is low.
+const GameClockView: FunctionComponent<{
+    context: Context,
+    timeMs: number,
+    running: boolean,
+}> = ({ context, timeMs, running }) => {
+    const theme = context.themeManager.theme;
+    const lowTime = running && timeMs < CLOCK_LOW_TIME_MS;
+    const background = lowTime ? LOW_TIME_COLOR : running ? theme.playerTurnColor : "transparent";
+    const color = lowTime ? LOW_TIME_TEXT_COLOR : running
+        ? getColorByBrightness(theme.playerTurnColor, theme.textColor, theme.textLightColor)
+        : getColorByBrightness(theme.background, theme.textColor, theme.textLightColor);
+    return (
+        <span className="clock" style={{ background, color }} role="timer">
+            {formatClock(timeMs)}
+            <style jsx>{`
+                .clock {
+                    padding: 2px 10px;
+                    border-radius: 30px;
+                    border: 2px solid ${theme.boardColor};
+                    font-weight: bold;
+                    font-variant-numeric: tabular-nums;
+                    white-space: nowrap;
+                    transition: background-color 0.5s, color 0.5s;
+                }
+            `}</style>
+        </span>
+    );
+}
+
+export default GameClockView;
--- a/apps/frontend/src/components/UserStatus.tsx
+++ b/apps/frontend/src/components/UserStatus.tsx
@ -13,8 +13,10 @@ const UserStatus: FunctionComponent<{
    user: User,
    layoutMode: LayoutMode,
    visible?: boolean,
-    style?: React.CSSProperties
-}> = ({ context, user, layoutMode, visible, style }) => {
+    style?: React.CSSProperties,
+    // Shown after the online status, e.g. the player's clock.
+    accessory?: React.ReactNode,
+}> = ({ context, user, layoutMode, visible, style, accessory }) => {
    if (visible === false) return <></>;

    const { t } = useTranslation();
@ -29,6 +31,7 @@ const UserStatus: FunctionComponent<{
            <span style={{color: textColorOnBoard, transition: 'color 0.5s'}} className='text'>{user.isAnonymous ? t("Anonymous") : user.name}</span>
            <Space width='5px' />
            <div className={"circle " + (user.isOnline ? "online" : "offline")}></div>
+            {accessory && <><Space width='8px' />{accessory}</>}
            <style jsx>{`
                .online {
                    background-color: ${context.themeManager.theme.boardColor};
--- a/apps/frontend/src/hooks/useGameClock.ts
+++ b/apps/frontend/src/hooks/useGameClock.ts
@ -0,0 +1,27 @@
+import { useEffect, useRef, useState } from "react";
+import { ClockState, ClockSync, Game, GameEndMessage } from "@mancala/core";
+
+const TICK_MS = 250;
+
+// Both players' clocks in a live game, counting down between the server's messages. Undefined when the server sends
+// no clock.
+export default function useGameClock(game: Game | undefined, gameEnd: GameEndMessage | undefined): ClockState | undefined {
+    const sync = useRef(new ClockSync()).current;
+    const lastGame = useRef<Game>();
+    // Every game message is a new object, so a changed reference means a new message.
+    if (game && game !== lastGame.current) {
+        sync.update(game);
+        lastGame.current = game;
+    }
+    if (gameEnd) sync.stop(gameEnd.clock);
+
+    const [, setTick] = useState(0);
+    const isRunning = sync.isRunning;
+    useEffect(() => {
+        if (!isRunning) return;
+        const timer = setInterval(() => setTick((tick) => tick + 1), TICK_MS);
+        return () => clearInterval(timer);
+    }, [isRunning]);
+
+    return sync.getTimes();
+}
--- a/apps/frontend/src/routes/GamePage.tsx
+++ b/apps/frontend/src/routes/GamePage.tsx
@ -17,7 +17,7 @@ import LoadingComponent from '../components/LoadingComponent';
 import PageContainer from '../components/PageContainer';
 import Row from '../components/Row';
 import UserStatus from '../components/UserStatus';
-import { GameRecord, channel_on_game_update, channel_on_game_crashed, channel_on_game_end, channel_on_game_user_leave, channel_on_user_connection_change, channel_leave_game, channel_game_move, channel_listen_game_events, channel_unlisten_game_events, FinishedGameSummary, GameEndMessage, getBoardAfterMove, PlayedMove, TURN_TIMEOUT_MS } from '@mancala/core';
+import { GameRecord, channel_on_game_update, channel_on_game_crashed, channel_on_game_end, channel_on_game_user_leave, channel_on_user_connection_change, channel_leave_game, channel_game_move, channel_listen_game_events, channel_unlisten_game_events, FinishedGameSummary, GameEndMessage, getBoardAfterMove, getSeat, PlayedMove } from '@mancala/core';
 import { Context } from '../context/context';
 import useWindowDimensions from '../hooks/useWindowDimensions';
 import { GameMove, LoadingState, Game, GameUsersConnectionInfo } from "@mancala/core";
@ -34,8 +34,9 @@ import ReviewBanner from '../components/history/ReviewBanner';
 import useMoveKeys from '../hooks/useMoveKeys';
 import { createBoardViewModel } from '../util/BoardViewModels';
 import { getResultText } from '../util/GameResultText';
-import CircularPanel from '../components/CircularPanel';
 import ReplayView from '../components/history/ReplayView';
+import GameClockView from '../components/GameClockView';
+import useGameClock from '../hooks/useGameClock';

 const GamePage: FunctionComponent<{
    context: Context,
@ -69,9 +70,6 @@ const GamePage: FunctionComponent<{
    // Set when the server says the game ended, for whatever reason.
    const [gameEnd, setGameEnd] = useState<GameEndMessage | undefined>(undefined);

-    // Ticks every second while a countdown is shown.
-    const [now, setNow] = useState<number>(Date.now());
-
    const { height, width } = useWindowDimensions();

    const navigate = useNavigate();
@ -306,21 +304,12 @@ const GamePage: FunctionComponent<{
        } as FinishedGameSummary, isSpectator ? undefined : userKey, t)}`
        : undefined;

-    // Countdown for the waiting player while the opponent is offline on their turn.
-    const opponentInfo = [gameUsersConnectionInfo?.user1ConnectionInfo, gameUsersConnectionInfo?.user2ConnectionInfo]
-        .find((info) => info && info.userId !== userKey);
-    const countdownMs = !isSpectator && !isGameOver && opponentInfo && !opponentInfo.isOnline
-        && opponentInfo.offlineSince !== undefined && mancalaGame?.turnPlayerId === opponentInfo.userId
-        ? Math.max(0, opponentInfo.offlineSince + TURN_TIMEOUT_MS - now)
-        : undefined;
-    React.useEffect(() => {
-        if (countdownMs === undefined) return;
-        const timer = setInterval(() => setNow(Date.now()), 1000);
-        return () => clearInterval(timer);
-    }, [countdownMs === undefined]);
-    const formatCountdown = (ms: number) => {
-        const seconds = Math.ceil(ms / 1000);
-        return `${Math.floor(seconds / 60)}:${String(seconds % 60).padStart(2, "0")}`;
+    const clockTimes = useGameClock(game, gameEnd);
+    const renderClock = (playerId: string) => {
+        const seat = mancalaGame && getSeat(mancalaGame, playerId);
+        if (!clockTimes || !seat) return undefined;
+        const timeMs = seat === "player1" ? clockTimes.player1Ms : clockTimes.player2Ms;
+        return <GameClockView context={context} timeMs={timeMs} running={clockTimes.runningSeat === seat} />;
    };
    const showBoardView = game && boardViewModel && userKey && true;
    const topLocatedUserId = (isSpectator ? mancalaGame?.player2Id : getOpponentId()) || "0";
@ -355,11 +344,6 @@ const GamePage: FunctionComponent<{
            {renderHeaderBar()}
            {renderMobileBoardToolbar()}
            {buildBoardTopToolbar()}
-            {showBoardView && countdownMs !== undefined && (
-                <CircularPanel color={context.themeManager.theme.playerTurnColor} style={{ marginBottom: "0.5rem" }}>
-                    {t("OpponentOfflineCountdown", { time: formatCountdown(countdownMs) })}
-                </CircularPanel>
-            )}
            {showBoardView && isReviewing && (
                <ReviewBanner
                    context={context}
@ -423,19 +407,22 @@ const GamePage: FunctionComponent<{
            <UserStatus style={{
                marginBottom: "0.5rem", marginLeft: "6%", maxWidth: isMobile ? "40vw" : "30vw",
                width: isMobile ? "40vw" : "30vw"
-            }} context={context} layoutMode="left" user={topLocatedUser} visible={showBoardView || false} />
+            }} context={context} layoutMode="left" user={topLocatedUser} visible={showBoardView || false}
+                accessory={renderClock(topLocatedUserId)} />
            {buildInfoPanel({ visible: !isMobile })}
            <UserStatus style={{
                marginBottom: "0.5rem", marginRight: "6%", maxWidth: isMobile ? "40vw" : "30vw",
                width: isMobile ? "40vw" : "30vw"
-            }} context={context} layoutMode="right" user={bottomLocatedUser} visible={showBoardView || false} />
+            }} context={context} layoutMode="right" user={bottomLocatedUser} visible={showBoardView || false}
+                accessory={renderClock(bottomLocatedUserId)} />
        </BoardToolbar>;
    }

    function buildInfoPanel(params: { visible: boolean }) {
        return (
            <InfoPanel
-                style={{ marginTop: "0.5rem", marginBottom: "0.5rem" }}
+                // Long texts such as "Game Ended · You Won · Opponent ran out of time" wrap on phones.
+                style={{ marginTop: "0.5rem", marginBottom: "0.5rem", ...(isMobile && { whiteSpace: "normal", textAlign: "center" }) }}
                context={context}
                game={game}
                currentUser={currentUser}
--- a/docs/specs/game-clock/tasks.md
+++ b/docs/specs/game-clock/tasks.md
@ -12,7 +12,7 @@ Work through the tasks in order; each ends with its tests passing and a commit.
      `checkTimeouts`, the 10-second timer and the backend's `offlineSince`; unit tests.
 - [x] 4. **Restore and saving**: snapshot version 2 and restore of versions 1 and 2, `remainingMs` and
      `clockInitialMs` in game records, migration `002_clock` and the repository; unit and integration tests.
- [ ] 5. **Web app, live game**: `useGameClock`, `GameClockView`, clocks in `GamePage` on desktop and mobile
+- [x] 5. **Web app, live game**: `useGameClock`, `GameClockView`, clocks in `GamePage` on desktop and mobile
      layouts; remove the offline countdown, and with it `TURN_TIMEOUT_MS`, `INACTIVE_TIMEOUT_MS`,
      `UserConnectionInfo.offlineSince` and `OpponentOfflineCountdown` from core (the web app uses them until then).
 - [ ] 6. **Web app, replay**: clocks in `ReplayView` from `getClockAtMove`.
--- a/packages/core/src/localization/en.ts
+++ b/packages/core/src/localization/en.ts
@ -72,5 +72,4 @@ export const en = {
    WatchFromStart: "Watch from start",
    Speed: "Speed",
    Duration: "Duration",
-    OpponentOfflineCountdown: "Opponent is offline. You win in {{time}} if they don't come back."
 }
--- a/packages/core/src/localization/tr.ts
+++ b/packages/core/src/localization/tr.ts
@ -72,5 +72,4 @@ export const tr = {
    WatchFromStart: "Baştan izle",
    Speed: "Hız",
    Duration: "Süre",
-    OpponentOfflineCountdown: "Rakip çevrimdışı. Dönmezse {{time}} içinde kazanırsın."
 };
--- a/packages/core/src/models/GameHistory.ts
+++ b/packages/core/src/models/GameHistory.ts
@ -1,11 +1,6 @@
 import { GameStep } from "mancala.js";
 import { GameClock } from "./GameClock";

-// How long the player whose turn it is may stay offline before the opponent wins.
-export const TURN_TIMEOUT_MS = 5 * 60 * 1000;
-// How long both players may stay offline before the game ends without a winner.
-export const INACTIVE_TIMEOUT_MS = 30 * 60 * 1000;
-
 export interface PlayerSummary {
    userId: string;
    name?: string;
--- a/packages/core/src/models/UserConnectionInfo.ts
+++ b/packages/core/src/models/UserConnectionInfo.ts
@ -4,6 +4,4 @@ export interface UserConnectionInfo {
    // Sent by servers with Keycloak auth; undefined for legacy userKey players.
    name?: string;
    isGuest?: boolean;
-    // Epoch milliseconds since the user has been offline; undefined while online.
-    offlineSince?: number;
 }