From 20359b7a8f77fcbbfd1641a7b49ad247c764488c Mon Sep 17 00:00:00 2001
From: Halit Aksoy <jhalitaksoy@gmail.com>
Date: Fri, 16 Oct 2026 01:39:36 +0300
Subject: [PATCH] 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.
---
 .../frontend/src/components/GameClockView.tsx | 40 +++++++++++++++++
 apps/frontend/src/components/UserStatus.tsx   |  7 ++-
 apps/frontend/src/hooks/useGameClock.ts       | 27 ++++++++++++
 apps/frontend/src/routes/GamePage.tsx         | 43 +++++++------------
 docs/specs/game-clock/tasks.md                |  2 +-
 packages/core/src/localization/en.ts          |  1 -
 packages/core/src/localization/tr.ts          |  1 -
 packages/core/src/models/GameHistory.ts       |  5 ---
 .../core/src/models/UserConnectionInfo.ts     |  2 -
 9 files changed, 88 insertions(+), 40 deletions(-)
 create mode 100644 apps/frontend/src/components/GameClockView.tsx
 create mode 100644 apps/frontend/src/hooks/useGameClock.ts

diff --git a/apps/frontend/src/components/GameClockView.tsx b/apps/frontend/src/components/GameClockView.tsx
new file mode 100644
index 0000000..72660ff
--- /dev/null
+++ 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;
diff --git a/apps/frontend/src/components/UserStatus.tsx b/apps/frontend/src/components/UserStatus.tsx
index c4f767c..a9ddc98 100644
--- 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};
diff --git a/apps/frontend/src/hooks/useGameClock.ts b/apps/frontend/src/hooks/useGameClock.ts
new file mode 100644
index 0000000..2fdb317
--- /dev/null
+++ 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();
+}
diff --git a/apps/frontend/src/routes/GamePage.tsx b/apps/frontend/src/routes/GamePage.tsx
index cc73552..2fda3da 100644
--- 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}
diff --git a/docs/specs/game-clock/tasks.md b/docs/specs/game-clock/tasks.md
index 911337c..6180fae 100644
--- 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`.
diff --git a/packages/core/src/localization/en.ts b/packages/core/src/localization/en.ts
index 12c08a9..a550224 100644
--- 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."
 }
\ No newline at end of file
diff --git a/packages/core/src/localization/tr.ts b/packages/core/src/localization/tr.ts
index 62631fc..23b40a0 100644
--- 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."
 };
\ No newline at end of file
diff --git a/packages/core/src/models/GameHistory.ts b/packages/core/src/models/GameHistory.ts
index 516ffb0..4f15377 100644
--- 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;
diff --git a/packages/core/src/models/UserConnectionInfo.ts b/packages/core/src/models/UserConnectionInfo.ts
index 7702c25..69e6a87 100644
--- 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;
 }