feat: multiplayer reconnection with 20s grace period on disconnect

Author: tmcarmichael

apps/backend/internal/ws/game.go

@@ -247,6 +247,14 @@ func (h *Hub) HandleMessage(client *Client, msg *ClientMessage) {
 		}
 		h.games.LeaveGame(client, data.GameID)
 
+	case MsgTypeGameReconnect:
+		var data GameReconnectData
+		if err := json.Unmarshal(msg.Data, &data); err != nil {
+			client.SendMessage(NewErrorMessage("INVALID_DATA", "Invalid reconnect data"))
+			return
+		}
+		h.games.HandleReconnect(client, data.GameID)
+
 	case MsgTypeLobbySubscribe:
 		h.SubscribeLobby(client)
 

apps/backend/internal/ws/hub.go

@@ -20,6 +20,9 @@ const (
 	MsgTypeMove   = "MOVE"
 	MsgTypeResign = "RESIGN"
 
+	// Reconnection
+	MsgTypeGameReconnect = "GAME_RECONNECT"
+
 	// Lobby
 	MsgTypeLobbySubscribe   = "LOBBY_SUBSCRIBE"
 	MsgTypeLobbyUnsubscribe = "LOBBY_UNSUBSCRIBE"
@@ -49,6 +52,11 @@ const (
 	MsgTypeOpponentLeft = "OPPONENT_LEFT"
 	MsgTypeTimeUpdate   = "TIME_UPDATE"
 
+	// Reconnection responses
+	MsgTypeGameReconnected      = "GAME_RECONNECTED"
+	MsgTypeOpponentDisconnected = "OPPONENT_DISCONNECTED"
+	MsgTypeOpponentReconnected  = "OPPONENT_RECONNECTED"
+
 	// Lobby responses
 	MsgTypeLobbyList   = "LOBBY_LIST"
 	MsgTypeLobbyUpdate = "LOBBY_UPDATE"
@@ -183,6 +191,24 @@ type ResignData struct {
 	GameID string `json:"gameId"`
 }
 
+// GameReconnectData is sent by client to reconnect to a game
+type GameReconnectData struct {
+	GameID string `json:"gameId"`
+}
+
+// GameReconnectedData is sent to client with full game state on reconnection
+type GameReconnectedData struct {
+	GameID      string       `json:"gameId"`
+	Color       string       `json:"color"`
+	FEN         string       `json:"fen"`
+	MoveHistory []string     `json:"moveHistory"`
+	WhiteTimeMs int          `json:"whiteTimeMs"`
+	BlackTimeMs int          `json:"blackTimeMs"`
+	TimeControl *TimeControl `json:"timeControl,omitempty"`
+	Opponent    PlayerInfo   `json:"opponent"`
+	Rated       bool         `json:"rated"`
+}
+
 // TimeUpdateData is sent periodically to update clocks
 type TimeUpdateData struct {
 	GameID    string `json:"gameId"`

apps/backend/internal/ws/message.go

@@ -1,5 +1,6 @@
 import { useParams, useNavigate, useLocation } from '@solidjs/router';
-import { createEffect, on, Show, type ParentComponent } from 'solid-js';
+import { createEffect, on, onCleanup, Show, type ParentComponent } from 'solid-js';
+import { loadActiveGame, clearActiveGame } from '../../../services/sync/reconnectStore';
 import { PlayGameProvider, usePlayGame } from '../../../store/game/PlayGameContext';
 import { type StartGameOptions, type MultiplayerGameOptions } from '../../../types/game';
 import ChessBoardController from '../../chess/ChessBoardController/ChessBoardController';
@@ -56,7 +57,13 @@ const PlayContainerInner: ParentComponent = () => {
           !multiplayer.state.isWaiting &&
           chess.state.lifecycle !== 'playing'
         ) {
-          actions.joinMultiplayerGame(gameId);
+          const activeGame = loadActiveGame();
+          if (activeGame && activeGame.gameId === gameId) {
+            actions.reconnectToGame(gameId, activeGame.playerColor);
+          } else {
+            clearActiveGame();
+            actions.joinMultiplayerGame(gameId);
+          }
         }
       }
     )
@@ -73,6 +80,15 @@ const PlayContainerInner: ParentComponent = () => {
     )
   );
 
+  const unsub = multiplayer.on('game:error', () => {
+    if (chess.state.lifecycle !== 'playing' && chess.state.lifecycle !== 'ended') {
+      clearActiveGame();
+      actions.exitGame();
+      navigate('/play', { replace: true });
+    }
+  });
+  onCleanup(unsub);
+
   const isIdle = () => chess.state.lifecycle === 'idle' && !params.gameId;
   const isReviewing = () => review.phase() !== 'idle';
 

apps/frontend/src/components/play/PlayContainer/PlayContainer.tsx

@@ -1,3 +1,32 @@
+.disconnectBanner {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: var(--space-sm);
+  width: 100%;
+  padding: var(--space-sm) var(--space-md);
+  background: var(--warning-bg, rgba(255, 165, 0, 0.1));
+  border: 1px solid var(--warning, #f0a030);
+  border-radius: var(--radius-md);
+  color: var(--warning, #f0a030);
+  font-family: var(--font-body);
+  font-size: var(--text-sm);
+  font-weight: 500;
+  margin-bottom: var(--space-sm);
+}
+
+.disconnectCountdown {
+  font-variant-numeric: tabular-nums;
+  font-weight: 700;
+  min-width: 2.2em;
+  text-align: center;
+  padding: 0.1em 0.4em;
+  background: var(--warning, #f0a030);
+  color: var(--surface-1, #1a1a2e);
+  border-radius: var(--radius-sm);
+  font-size: var(--text-xs);
+}
+
 .playControlPanel {
   display: flex;
   width: 100%;

apps/frontend/src/components/play/PlayControlPanel/PlayControlPanel.module.css

@@ -1,12 +1,48 @@
+import { createEffect, createSignal, on, onCleanup, Show, type ParentComponent } from 'solid-js';
 import { usePlayGame } from '../../../store/game/PlayGameContext';
 import ButtonPanel from '../../game/ButtonPanel/ButtonPanel';
 import GameInfoPanel from '../../game/GameInfoPanel/GameInfoPanel';
 import GamePanelButton from '../../game/GamePanelButton/GamePanelButton';
 import styles from './PlayControlPanel.module.css';
-import type { ParentComponent } from 'solid-js';
+
+const RECONNECT_GRACE_SECONDS = 20;
 
 const PlayControlPanel: ParentComponent = () => {
-  const { chess, engine, actions, derived } = usePlayGame();
+  const { chess, ui, engine, actions, derived } = usePlayGame();
+
+  const [countdown, setCountdown] = createSignal(0);
+  let countdownInterval: ReturnType<typeof setInterval> | undefined;
+
+  const clearCountdown = () => {
+    if (countdownInterval !== undefined) {
+      clearInterval(countdownInterval);
+      countdownInterval = undefined;
+    }
+    setCountdown(0);
+  };
+
+  createEffect(
+    on(
+      () => ui.state.opponentDisconnected,
+      (disconnected) => {
+        clearCountdown();
+        if (disconnected) {
+          setCountdown(RECONNECT_GRACE_SECONDS);
+          countdownInterval = setInterval(() => {
+            setCountdown((prev) => {
+              if (prev <= 1) {
+                clearCountdown();
+                return 0;
+              }
+              return prev - 1;
+            });
+          }, 1000);
+        }
+      }
+    )
+  );
+
+  onCleanup(clearCountdown);
 
   const handleResign = () => {
     if (!derived.isPlaying()) return;
@@ -15,6 +51,12 @@ const PlayControlPanel: ParentComponent = () => {
 
   return (
     <div>
+      <Show when={ui.state.opponentDisconnected}>
+        <div class={styles.disconnectBanner}>
+          <span>Opponent disconnected</span>
+          <span class={styles.disconnectCountdown}>{countdown()}s</span>
+        </div>
+      </Show>
       <div class={styles.playControlPanel}>
         <ButtonPanel>
           <GamePanelButton onClick={handleResign} disabled={!derived.isPlaying()}>

apps/frontend/src/components/play/PlayControlPanel/PlayControlPanel.tsx

@@ -13,6 +13,7 @@ import type {
   MoveRejectedData,
   OpponentMoveData,
   GameEndedData,
+  GameReconnectedData,
   TimeUpdateData,
   OpponentLeftData,
   ErrorData,
@@ -152,6 +153,13 @@ export class GameSyncService {
     }
   }
 
+  reconnectGame(gameId: string): void {
+    this.send({
+      type: MT.GAME_RECONNECT,
+      data: { gameId },
+    });
+  }
+
   sendMove(gameId: string, from: string, to: string, promotion?: string): void {
     this.send({
       type: MT.MOVE,
@@ -297,6 +305,35 @@ export class GameSyncService {
         break;
       }
 
+      case MT.GAME_RECONNECTED: {
+        const payload = data as GameReconnectedData;
+        this.currentGameId = payload.gameId;
+        this.emitEvent({
+          type: 'game:reconnected',
+          data: payload,
+          timestamp: Date.now(),
+        });
+        break;
+      }
+
+      case MT.OPPONENT_DISCONNECTED: {
+        this.emitEvent({
+          type: 'game:opponent_disconnected',
+          data,
+          timestamp: Date.now(),
+        });
+        break;
+      }
+
+      case MT.OPPONENT_RECONNECTED: {
+        this.emitEvent({
+          type: 'game:opponent_reconnected',
+          data,
+          timestamp: Date.now(),
+        });
+        break;
+      }
+
       case MT.TIME_UPDATE: {
         const payload = data as TimeUpdateData;
         this.emitEvent({

apps/frontend/src/services/sync/GameSyncService.ts

@@ -0,0 +1,34 @@
+import type { Side } from '../../types/game';
+
+const RECONNECT_KEY = 'nxtchess:active_game';
+
+interface ActiveGameInfo {
+  gameId: string;
+  playerColor: Side;
+}
+
+export function saveActiveGame(info: ActiveGameInfo): void {
+  try {
+    sessionStorage.setItem(RECONNECT_KEY, JSON.stringify(info));
+  } catch {
+    /* noop */
+  }
+}
+
+export function loadActiveGame(): ActiveGameInfo | null {
+  try {
+    const raw = sessionStorage.getItem(RECONNECT_KEY);
+    if (raw) return JSON.parse(raw);
+  } catch {
+    /* noop */
+  }
+  return null;
+}
+
+export function clearActiveGame(): void {
+  try {
+    sessionStorage.removeItem(RECONNECT_KEY);
+  } catch {
+    /* noop */
+  }
+}

apps/frontend/src/services/sync/reconnectStore.ts

@@ -120,6 +120,26 @@ export interface OpponentLeftData {
   gameId: string;
 }
 
+export interface GameReconnectedData {
+  gameId: string;
+  color: 'white' | 'black';
+  fen: string;
+  moveHistory: string[];
+  whiteTimeMs: number;
+  blackTimeMs: number;
+  timeControl?: TimeControl;
+  opponent: PlayerInfo;
+  rated: boolean;
+}
+
+export interface OpponentDisconnectedData {
+  gameId: string;
+}
+
+export interface OpponentReconnectedData {
+  gameId: string;
+}
+
 export interface ErrorData {
   code: string;
   message: string;
@@ -159,6 +179,9 @@ export const MsgType = {
   MOVE: 'MOVE',
   RESIGN: 'RESIGN',
 
+  // Client → Server (reconnection)
+  GAME_RECONNECT: 'GAME_RECONNECT',
+
   // Client → Server (lobby)
   LOBBY_SUBSCRIBE: 'LOBBY_SUBSCRIBE',
   LOBBY_UNSUBSCRIBE: 'LOBBY_UNSUBSCRIBE',
@@ -178,6 +201,11 @@ export const MsgType = {
   OPPONENT_LEFT: 'OPPONENT_LEFT',
   TIME_UPDATE: 'TIME_UPDATE',
 
+  // Server → Client (reconnection)
+  GAME_RECONNECTED: 'GAME_RECONNECTED',
+  OPPONENT_DISCONNECTED: 'OPPONENT_DISCONNECTED',
+  OPPONENT_RECONNECTED: 'OPPONENT_RECONNECTED',
+
   // Server → Client (lobby)
   LOBBY_LIST: 'LOBBY_LIST',
   LOBBY_UPDATE: 'LOBBY_UPDATE',
@@ -196,6 +224,9 @@ export type SyncEventType =
   | 'game:opponent_move'
   | 'game:opponent_left'
   | 'game:time_update'
+  | 'game:reconnected'
+  | 'game:opponent_disconnected'
+  | 'game:opponent_reconnected'
   | 'lobby:list'
   | 'lobby:update'
   | 'error';