runecast_protocol/protocol/

server_messages.rs

//! Server-to-client messages.
//!
//! All messages that can be sent from the backend server to frontend clients.
//! Messages are tagged with `type` field for JSON serialization.
//!
//! # Categories
//!
//! - **Connection**: Handshake responses, heartbeat acks
//! - **Lobby State**: Snapshots and deltas for lobby state
//! - **Game State**: Snapshots and deltas for game state
//! - **Events**: Discrete events (player joined, word scored, etc.)
//! - **Errors**: Error responses with codes and messages

use serde::{Deserialize, Serialize};

use crate::protocol::GameType;

use super::types::{
    AdminGameInfo, AdventureEventKind, CustomMeta, DebugBackendGameState, DebugHandlerGameState,
    DebugLobbyState, DebugPlayerInfo, DebugWebsocketContext, ErrorCode, GameChange, GameConfig,
    GamePlayerInfo, GameSnapshot, Grid, LobbyChange, LobbyGameInfo, LobbyPlayerInfo, LobbyType,
    NewsItemPayload, PlayerInfo, PlayerName, Position, RematchCountdownState, RuneBoxStanding,
    ScoreInfo, SpectatorInfo, TimerVoteState,
};

/// Messages sent from server to client.
// Servers box outgoing messages; boxing fields here would change the public API.
#[allow(clippy::large_enum_variant)]
#[serde_with::serde_as]
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(tag = "type", rename_all = "snake_case")]
pub enum ServerMessage {
    // ========================================================================
    // Connection Messages
    // ========================================================================
    /// Initial server greeting after WebSocket connect.
    ///
    /// Sent immediately upon connection, before Identify.
    Hello {
        /// Recommended heartbeat interval in milliseconds
        heartbeat_interval_ms: u32,
        /// Server version for compatibility checks
        #[serde(skip_serializing_if = "Option::is_none")]
        server_version: Option<String>,
    },

    /// Successful authentication response.
    ///
    /// Contains the full initial state snapshot.
    Ready {
        /// Unique session ID for this connection
        session_id: String,
        /// The authenticated player's user ID
        #[serde_as(as = "serde_with::DisplayFromStr")]
        player_id: i64,
        /// Full lobby state (if in a lobby)
        #[serde(skip_serializing_if = "Option::is_none")]
        lobby: Option<LobbySnapshot>,
        /// Full game state (if in a game)
        #[serde(skip_serializing_if = "Option::is_none")]
        game: Option<GameSnapshot>,
    },

    /// Session resumed successfully after reconnect.
    ///
    /// Contains any events missed during disconnection.
    Resumed {
        /// Events that occurred while disconnected
        missed_events: Vec<ServerMessage>,
    },

    /// Heartbeat response.
    ///
    /// Echoes back for latency calculation.
    HeartbeatAck {
        /// Server timestamp when heartbeat was received
        server_time: u64,
    },

    /// Session is invalid or expired.
    ///
    /// Client should re-authenticate.
    InvalidSession { reason: String },

    // ========================================================================
    // Lobby State Messages
    // ========================================================================
    /// Sent when successfully joining a lobby.
    LobbyJoined {
        lobby_id: String,
        /// 6-char code for custom lobbies
        #[serde(skip_serializing_if = "Option::is_none")]
        lobby_code: Option<String>,
        /// Full lobby state
        lobby: LobbySnapshot,
    },

    /// Full lobby state snapshot.
    ///
    /// Sent on initial join or when delta sync fails.
    LobbySnapshot { lobby: LobbySnapshot },

    /// Incremental lobby state update.
    ///
    /// More efficient than full snapshots for small changes.
    LobbyDelta { changes: Vec<LobbyChange> },

    /// Confirmation of leaving lobby.
    LobbyLeft,

    /// Custom lobby was created successfully.
    CustomLobbyCreated {
        lobby_id: String,
        lobby_code: String,
    },
    // ========================================================================
    // Game Lifecycle Messages
    // ========================================================================
    /// A new game has started.
    ///
    /// Contains initial game state for all participants.
    GameStarted {
        game_id: String,
        /// Which mode this game is — the same field, and the same reasoning, as
        /// [`GameSnapshot::game_type`].
        ///
        /// v0.18.0 put the mode on the snapshot and stopped there, which left
        /// the JOIN path still inferring it. That is the worse half to leave
        /// undone: a snapshot is a reconnect/spectate message, so a player who
        /// joins normally never receives one, and every bug that has hidden in
        /// this mode so far hid on exactly this path.
        #[serde(default)]
        game_type: GameType,
        grid: Grid,
        players: Vec<GamePlayerInfo>,
        /// Your turn order (0-indexed)
        your_turn_order: u8,
        /// Who goes first
        #[serde_as(as = "serde_with::DisplayFromStr")]
        current_turn: i64,
        round: u8,
        max_rounds: u8,
        /// Turn time limit in seconds (if configured)
        #[serde(skip_serializing_if = "Option::is_none")]
        turn_time_limit: Option<u32>,
        /// `Some` marks this as an unranked custom (sandbox) game so every
        /// participant — not just the host — can render the unranked badge.
        /// Omitted for FFA/Adventure (wire format unchanged).
        #[serde(default, skip_serializing_if = "Option::is_none")]
        custom: Option<CustomMeta>,
        /// Server-authoritative time left in the run, in milliseconds. Set for
        /// Daily Challenge runs (incl. resumes); omitted otherwise.
        #[serde(default, skip_serializing_if = "Option::is_none")]
        time_remaining_ms: Option<u64>,
    },

    /// Full game state snapshot.
    ///
    /// Sent when joining as spectator or when delta sync fails.
    GameSnapshot { game_id: String, game: GameSnapshot },

    /// Incremental game state update.
    GameDelta {
        game_id: String,
        changes: Vec<GameChange>,
    },

    /// Game has ended normally.
    GameOver {
        game_id: String,
        /// Final scores, sorted by rank
        final_scores: Vec<ScoreInfo>,
        /// Winner's user ID
        #[serde_as(as = "serde_with::DisplayFromStr")]
        winner_id: i64,
        /// Whether it was a draw
        #[serde(default)]
        is_draw: bool,
    },

    /// Game was cancelled (not enough players, host left, etc.).
    GameCancelled { game_id: String, reason: String },

    /// Adventure Mode level ended. Sent after `GameOver` for sessions that
    /// had `adventure_level.is_some()` in their config. The client uses
    /// this to render the level-complete modal; the server has already
    /// upserted the row in `adventure_progress` by the time this is sent.
    AdventureLevelResult {
        /// Which level was played (1..=50).
        level: u32,
        /// Human player's final score for this run.
        score: i32,
        /// Stars awarded (0..=3). 0 = target not hit; 1+ = hit one_star/two_star/three_star.
        stars: u8,
        /// True iff `score` exceeded the prior `high_score` for this user + level.
        personal_best: bool,
        /// If this run unlocked a new level, the newly-unlocked level id.
        /// `None` if no new level was unlocked (level was already completed
        /// or was the campaign finale).
        #[serde(skip_serializing_if = "Option::is_none")]
        unlocked_level: Option<u32>,
        /// This run's duration in milliseconds (from game creation to
        /// game_over). Lets the client render "Time: 2:34" in the result
        /// modal without fetching progress. Unsigned since durations
        /// are non-negative, and consistent with other duration /
        /// interval fields in the protocol (`heartbeat_interval_ms`,
        /// `server_time`).
        #[serde(skip_serializing_if = "Option::is_none")]
        duration_ms: Option<u64>,
    },

    /// Daily Challenge run finished (deadline reached or player ended early).
    /// The server has already recorded the attempt + move log by send time.
    DailyResult {
        /// The day's seed (deterministic from the UTC date).
        seed: i64,
        /// This run's final score.
        score: i32,
        /// The player's best score across today's attempts.
        personal_best: i32,
        /// 1-based rank on today's shared leaderboard.
        rank: u32,
        /// Attempts used so far today (incl. this one).
        attempts_used: u8,
        /// Max attempts today for this user (1 free, 3 premium).
        attempts_max: u8,
    },

    /// Adventure Mode random event (bomb / snake / UFO). Broadcast by
    /// the event scheduler when a roll succeeds at round change.
    /// `affected_positions` is the set of grid cells the client should
    /// animate; `new_grid` is the post-effect board so the client can
    /// swap in the updated tiles atomically with the animation.
    AdventureEvent {
        game_id: String,
        kind: AdventureEventKind,
        affected_positions: Vec<Position>,
        /// Full post-effect grid. Clients apply this as an authoritative
        /// snapshot — no delta needed.
        new_grid: Grid,
        /// Short human-readable label for the event, already localized
        /// server-side. Rendered in a brief toast alongside the animation.
        label: String,
    },

    // ========================================================================
    // Game Event Messages
    // ========================================================================
    /// A player joined the lobby.
    PlayerJoined { player: LobbyPlayerInfo },

    /// A player left the lobby.
    PlayerLeft {
        #[serde_as(as = "serde_with::DisplayFromStr")]
        player_id: i64,
        #[serde(skip_serializing_if = "Option::is_none")]
        reason: Option<String>,
    },

    /// A player reconnected after disconnection.
    PlayerReconnected {
        #[serde_as(as = "serde_with::DisplayFromStr")]
        player_id: i64,
    },

    /// A player disconnected (may reconnect).
    PlayerDisconnected {
        #[serde(skip_serializing_if = "Option::is_none")]
        game_id: Option<String>,
        #[serde_as(as = "serde_with::DisplayFromStr")]
        player_id: i64,
        /// Grace period in seconds before they're removed
        grace_period_seconds: u32,
    },

    /// A word was successfully scored.
    WordScored {
        #[serde_as(as = "serde_with::DisplayFromStr")]
        player_id: i64,
        game_id: String,
        word: String,
        score: i32,
        /// Positions that formed the word
        path: Vec<super::types::Position>,
        /// New total score
        total_score: i32,
        /// Gems earned from this word
        gems_earned: i32,
        /// New gem total
        total_gems: i32,
        /// Updated grid (letters replaced)
        new_grid: Grid,
    },

    /// RuneBox: a word was accepted — sent to the **submitting player only**.
    ///
    /// Deliberately not a reuse of [`ServerMessage::WordScored`]. That variant
    /// carries gems and a full `new_grid`, neither of which exists in RuneBox
    /// (the board is static and there are no gems), so both would be dead weight
    /// re-sent on every word — and its `word` field would leak to opponents.
    RuneBoxWordAccepted {
        /// Game this word was played in.
        game_id: String,
        /// The accepted word, echoed back so the client can list it.
        word: String,
        /// Letters gained — equal to the word's length. Sent explicitly so the
        /// client never re-derives scoring rules locally.
        letters: i32,
        /// The submitting player's new running total.
        total_score: i32,
    },

    /// RuneBox: another player's score moved — broadcast to everyone else.
    ///
    /// Carries **no word, and must never gain one**. RuneBox found-sets are
    /// independent, so a word another player found is still worth full value to
    /// you; naming it would hand you the answer. Opponents see the score move
    /// and nothing more.
    RuneBoxScoreChanged {
        /// Whose score changed.
        #[serde_as(as = "serde_with::DisplayFromStr")]
        player_id: i64,
        /// Game the score belongs to.
        game_id: String,
        /// That player's new running total.
        total_score: i32,
    },

    /// RuneBox: a **round** ended and the match continues.
    ///
    /// Deliberately distinct from [`ServerMessage::GameOver`], which keeps its
    /// existing meaning: the MATCH is over, no further play. That separation is
    /// what makes this addition non-breaking — every other mode plays exactly
    /// one round, so it only ever sends `GameOver` and never sees this message.
    ///
    /// A client that receives this should present standings and wait, NOT tear
    /// the game screen down.
    ///
    /// Carries no word lists, and must never gain any: the anti-leak rule that
    /// splits [`ServerMessage::RuneBoxWordAccepted`] from
    /// [`ServerMessage::RuneBoxScoreChanged`] applies just as much between
    /// rounds, because an eliminated player may still be watching.
    RuneBoxRoundEnded {
        /// Match this round belongs to.
        game_id: String,
        /// Which round just finished, 1-based.
        round: u8,
        /// How many rounds this match will play at most. `N - 1` for an
        /// elimination match of N players; 3 for a two-player best-of-3, which
        /// can still finish in 2.
        max_rounds: u8,
        /// THIS round's scores alone, highest first. Not cumulative — the
        /// running match total lives on `standings`.
        round_scores: Vec<ScoreInfo>,
        /// Players eliminated by this round's result.
        ///
        /// Empty in a two-player best-of-3, where nobody is eliminated until
        /// the match itself ends. Normally one id, but the field is a list
        /// because the rules do not forbid a round that eliminates more than
        /// one player.
        #[serde_as(as = "Vec<serde_with::DisplayFromStr>")]
        eliminated: Vec<i64>,
        /// Every player's match standing after this round — survivors and
        /// eliminated alike, so a client renders the whole picture without
        /// accumulating round results itself. A client that missed a round
        /// (reconnect) is therefore still correct.
        standings: Vec<RuneBoxStanding>,
        /// When the next round's board goes live, for the client's countdown.
        ///
        /// `None` means the server has not scheduled it yet; it does NOT mean
        /// the match is over — that is `GameOver`.
        #[serde(skip_serializing_if = "Option::is_none")]
        next_round_starts_at: Option<chrono::DateTime<chrono::Utc>>,
    },

    /// Turn changed to another player.
    TurnChanged {
        #[serde_as(as = "serde_with::DisplayFromStr")]
        player_id: i64,
        game_id: String,
        round: u8,
        /// Time remaining for this turn (if timer active)
        #[serde(skip_serializing_if = "Option::is_none")]
        time_remaining: Option<u32>,
    },

    /// A player passed their turn.
    TurnPassed {
        #[serde_as(as = "serde_with::DisplayFromStr")]
        player_id: i64,
        game_id: String,
    },

    /// Round number changed.
    RoundChanged {
        game_id: String,
        round: u8,
        max_rounds: u8,
        /// New grid if board was regenerated at the start of this round.
        /// Only present when the game is configured with `regenerate_board_each_round: true`.
        #[serde(skip_serializing_if = "Option::is_none")]
        new_grid: Option<Grid>,
    },

    /// Board was shuffled.
    BoardShuffled {
        #[serde_as(as = "serde_with::DisplayFromStr")]
        player_id: i64,
        game_id: String,
        new_grid: Grid,
        gems_spent: i32,
        /// Player's remaining gems after shuffle
        total_gems: i32,
    },

    /// A tile was swapped.
    TileSwapped {
        #[serde_as(as = "serde_with::DisplayFromStr")]
        player_id: i64,
        game_id: String,
        row: usize,
        col: usize,
        old_letter: char,
        new_letter: char,
        gems_spent: i32,
        /// Player's remaining gems after swap
        total_gems: i32,
    },

    /// Player entered swap mode (for animation).
    SwapModeEntered {
        #[serde_as(as = "serde_with::DisplayFromStr")]
        player_id: i64,
        game_id: String,
    },

    /// Player exited swap mode.
    SwapModeExited {
        #[serde_as(as = "serde_with::DisplayFromStr")]
        player_id: i64,
        game_id: String,
    },

    // ========================================================================
    // Spectator Messages
    // ========================================================================
    /// Successfully joined as spectator.
    SpectatorJoined {
        game_id: String,
        /// Full game state
        game: GameSnapshot,
    },

    /// A new spectator joined (broadcast to others).
    SpectatorAdded {
        spectator: SpectatorInfo,
        game_id: String,
    },

    /// A spectator left.
    SpectatorRemoved {
        #[serde_as(as = "serde_with::DisplayFromStr")]
        spectator_id: i64,
        game_id: String,
    },

    /// Spectator joined as player.
    SpectatorBecamePlayer {
        #[serde_as(as = "serde_with::DisplayFromStr")]
        player_id: i64,
        /// The player's raw Discord username: the unique handle. Display
        /// `name` instead when it is present.
        username: String,
        /// What to call this player. Absent from servers older than protocol
        /// 0.20; fall back to `username`.
        #[serde(default, skip_serializing_if = "Option::is_none")]
        name: Option<PlayerName>,
        game_id: String,
    },

    /// Confirmation of leaving spectator mode.
    SpectatorLeft,

    // ========================================================================
    // Live Update Messages
    // ========================================================================
    /// Another player's tile selection (for live preview).
    SelectionUpdate {
        #[serde_as(as = "serde_with::DisplayFromStr")]
        player_id: i64,
        game_id: String,
        positions: Vec<super::types::Position>,
    },

    // ========================================================================
    // Timer Vote Messages
    // ========================================================================
    /// Timer vote state changed.
    TimerVoteUpdate {
        state: TimerVoteState,
        game_id: String,
    },

    /// Turn timer started (vote passed).
    TurnTimerStarted {
        #[serde_as(as = "serde_with::DisplayFromStr")]
        target_player_id: i64,
        game_id: String,
        seconds: u32,
    },

    /// Turn timer expired - player auto-passed.
    TurnTimerExpired {
        #[serde_as(as = "serde_with::DisplayFromStr")]
        player_id: i64,
        game_id: String,
    },

    // ========================================================================
    // Rematch Countdown Messages
    // ========================================================================
    /// Rematch countdown state update.
    ///
    /// Sent to all players on the results screen after a game ends.
    RematchCountdownUpdate {
        /// Current countdown state
        state: RematchCountdownState,
        /// The game that just ended
        previous_game_id: String,
    },

    /// A player opted out of rematch pool.
    ///
    /// Broadcast to remaining players so they can update the player list.
    PlayerLeftRematch {
        #[serde_as(as = "serde_with::DisplayFromStr")]
        player_id: i64,
        /// The game they left from
        previous_game_id: String,
    },

    /// Rematch is starting (sent right before `GameStarted`).
    ///
    /// Allows frontend to show "Starting..." before the new game begins.
    RematchStarting {
        /// Who triggered the early start (None if countdown expired naturally)
        #[serde(skip_serializing_if = "Option::is_none")]
        #[serde_as(as = "Option<serde_with::DisplayFromStr>")]
        triggered_by: Option<i64>,
        /// The previous game that ended
        previous_game_id: String,
    },

    // ========================================================================
    // Pool
    // ========================================================================
    //
    PlayerPoolChanged {
        #[serde_as(as = "serde_with::DisplayFromStr")]
        player_id: i64,
        old_pool: Option<GameType>,
        new_pool: Option<GameType>,
    },

    // ========================================================================
    // Game Pool Messages (Legacy)
    // ========================================================================
    /// Player joined the game pool.
    PoolJoined {
        position: i32,
        total_in_pool: i32,
        game_id: String,
    },

    /// Pool position updated.
    PoolUpdate {
        position: i32,
        total_in_pool: i32,
        game_id: String,
    },

    /// Left the pool.
    PoolLeft,

    // ========================================================================
    // Admin Messages
    // ========================================================================
    /// Response to admin game list request.
    AdminGamesList { games: Vec<AdminGameInfo> },

    /// Game was deleted by admin.
    AdminGameDeleted { game_id: String },

    // ========================================================================
    // Legacy Compatibility Messages
    // ========================================================================
    /// Generic state update (legacy format).
    ///
    /// Used for backward compatibility with existing frontend.
    #[serde(rename = "game_state")]
    GameStateUpdate {
        game_id: String,
        state: String,
        grid: Grid,
        players: Vec<PlayerInfo>,
        current_turn: i64,
        round: i32,
        max_rounds: i32,
        used_words: Vec<String>,
        spectators: Vec<SpectatorInfo>,
        timer_vote_state: TimerVoteState,
    },

    /// Lobby state update (legacy format).
    #[serde(rename = "lobby_state")]
    LobbyStateUpdate {
        lobby_id: String,
        players: Vec<LobbyPlayerInfo>,
        games: Vec<LobbyGameInfo>,
    },

    // ========================================================================
    // Debug Messages
    // ========================================================================
    /// Debug state response with player context diagnostics.
    DebugStateResponse {
        timestamp: String,
        player: DebugPlayerInfo,
        websocket_context: DebugWebsocketContext,
        lobby_state: Option<DebugLobbyState>,
        backend_game_state: Option<DebugBackendGameState>,
        handler_game_state: Option<DebugHandlerGameState>,
    },

    // ========================================================================
    // News / Maintenance Announcements
    // ========================================================================
    /// A news/notification item was created or activated by an admin.
    ///
    /// Pushed to every connected client when an admin posts a new item
    /// via the news admin endpoints, or when an existing item is
    /// updated in a way that should re-surface it (becoming active,
    /// extending expires_at, etc.). Clients should treat it the same
    /// as if they had just fetched `/api/news` and seen this entry —
    /// in particular, maintenance items with a future `expires_at`
    /// drive the corner-countdown toast, while announcement/update
    /// items go through the existing full-screen overlay.
    NewsAnnounced { item: NewsItemPayload },

    // ========================================================================
    // Error Messages
    // ========================================================================
    /// Error response.
    Error {
        code: ErrorCode,
        message: String,
        /// Additional context (e.g., which field was invalid)
        #[serde(skip_serializing_if = "Option::is_none")]
        details: Option<serde_json::Value>,
    },
}

impl ServerMessage {
    /// Create an error message from an error code.
    #[must_use]
    pub fn error(code: ErrorCode) -> Self {
        Self::Error {
            message: code.message().to_string(),
            code,
            details: None,
        }
    }

    /// Create an error message with custom message.
    pub fn error_with_message(code: ErrorCode, message: impl Into<String>) -> Self {
        Self::Error {
            code,
            message: message.into(),
            details: None,
        }
    }

    /// Create an error message with details.
    pub fn error_with_details(
        code: ErrorCode,
        message: impl Into<String>,
        details: serde_json::Value,
    ) -> Self {
        Self::Error {
            code,
            message: message.into(),
            details: Some(details),
        }
    }

    /// Get the message type as a string (for logging/debugging).
    #[must_use]
    pub fn message_type(&self) -> &'static str {
        match self {
            Self::Hello { .. } => "hello",
            Self::Ready { .. } => "ready",
            Self::Resumed { .. } => "resumed",
            Self::HeartbeatAck { .. } => "heartbeat_ack",
            Self::InvalidSession { .. } => "invalid_session",
            Self::LobbyJoined { .. } => "lobby_joined",
            Self::LobbySnapshot { .. } => "lobby_snapshot",
            Self::LobbyDelta { .. } => "lobby_delta",
            Self::LobbyLeft => "lobby_left",
            Self::CustomLobbyCreated { .. } => "custom_lobby_created",
            Self::GameStarted { .. } => "game_started",
            Self::GameSnapshot { .. } => "game_snapshot",
            Self::GameDelta { .. } => "game_delta",
            Self::GameOver { .. } => "game_over",
            Self::GameCancelled { .. } => "game_cancelled",
            Self::AdventureLevelResult { .. } => "adventure_level_result",
            Self::DailyResult { .. } => "daily_result",
            Self::AdventureEvent { .. } => "adventure_event",
            Self::PlayerJoined { .. } => "player_joined",
            Self::PlayerLeft { .. } => "player_left",
            Self::PlayerReconnected { .. } => "player_reconnected",
            Self::PlayerDisconnected { .. } => "player_disconnected",
            Self::PlayerPoolChanged { .. } => "player_pool_changed",
            Self::WordScored { .. } => "word_scored",
            Self::RuneBoxWordAccepted { .. } => "rune_box_word_accepted",
            Self::RuneBoxScoreChanged { .. } => "rune_box_score_changed",
            Self::RuneBoxRoundEnded { .. } => "rune_box_round_ended",
            Self::TurnChanged { .. } => "turn_changed",
            Self::TurnPassed { .. } => "turn_passed",
            Self::RoundChanged { .. } => "round_changed",
            Self::BoardShuffled { .. } => "board_shuffled",
            Self::TileSwapped { .. } => "tile_swapped",
            Self::SwapModeEntered { .. } => "swap_mode_entered",
            Self::SwapModeExited { .. } => "swap_mode_exited",
            Self::SpectatorJoined { .. } => "spectator_joined",
            Self::SpectatorAdded { .. } => "spectator_added",
            Self::SpectatorRemoved { .. } => "spectator_removed",
            Self::SpectatorLeft => "spectator_left",
            Self::SpectatorBecamePlayer { .. } => "spectator_became_player",
            Self::SelectionUpdate { .. } => "selection_update",
            Self::TimerVoteUpdate { .. } => "timer_vote_update",
            Self::TurnTimerStarted { .. } => "turn_timer_started",
            Self::TurnTimerExpired { .. } => "turn_timer_expired",
            Self::RematchCountdownUpdate { .. } => "rematch_countdown_update",
            Self::PlayerLeftRematch { .. } => "player_left_rematch",
            Self::RematchStarting { .. } => "rematch_starting",
            Self::PoolJoined { .. } => "pool_joined",
            Self::PoolUpdate { .. } => "pool_update",
            Self::PoolLeft => "pool_left",
            Self::AdminGamesList { .. } => "admin_games_list",
            Self::AdminGameDeleted { .. } => "admin_game_deleted",
            Self::GameStateUpdate { .. } => "game_state",
            Self::LobbyStateUpdate { .. } => "lobby_state",
            Self::DebugStateResponse { .. } => "debug_state_response",

            Self::NewsAnnounced { .. } => "news_announced",

            Self::Error { .. } => "error",
        }
    }

    /// Check if this is an error message.
    #[must_use]
    pub fn is_error(&self) -> bool {
        matches!(self, Self::Error { .. })
    }

    /// Check if this message should be stored for reconnection replay.
    ///
    /// Some messages are transient and don't need to be replayed.
    #[must_use]
    pub fn should_store_for_replay(&self) -> bool {
        !matches!(
            self,
            Self::Hello { .. }
                | Self::HeartbeatAck { .. }
                | Self::SelectionUpdate { .. }
                | Self::TimerVoteUpdate {
                    state: TimerVoteState::Idle,
                    ..
                }
                | Self::PlayerPoolChanged { .. }
                | Self::TurnTimerStarted { .. }
                | Self::TurnTimerExpired { .. }
                | Self::DebugStateResponse { .. }
                // News is re-fetched from /api/news on (re)connect, so
                // replaying a stale announcement would either duplicate
                // a still-active item or surface one that has since
                // expired/been deleted. Skip replay; the HTTP fetch is
                // authoritative.
                | Self::NewsAnnounced { .. }
        )
    }
}

/// Convert a `ServerMessage` to a `serde_json::Value`.
impl From<ServerMessage> for serde_json::Value {
    fn from(msg: ServerMessage) -> Self {
        serde_json::to_value(msg).unwrap()
    }
}

/// Convert a `serde_json::Value` to a `ServerMessage`.
impl TryFrom<serde_json::Value> for ServerMessage {
    type Error = serde_json::Error;

    fn try_from(
        value: serde_json::Value,
    ) -> Result<Self, <ServerMessage as TryFrom<serde_json::Value>>::Error> {
        serde_json::from_value(value)
    }
}
// ============================================================================
// Snapshot Types
// ============================================================================

/// Complete lobby state snapshot.
#[serde_with::serde_as]
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct LobbySnapshot {
    pub lobby_id: String,
    pub lobby_type: LobbyType,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub lobby_code: Option<String>,
    pub players: Vec<LobbyPlayerInfo>,
    pub games: Vec<LobbyGameInfo>,
    /// Maximum players allowed
    #[serde(default = "default_max_players")]
    pub max_players: u8,
    /// Current sandbox config for the lobby, if a host has set one.
    /// Absent for normal (non-sandbox) lobbies.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub sandbox_config: Option<GameConfig>,
    /// The lobby's current host (the player who controls sandbox config),
    /// if one has been assigned. Lets clients show host-only controls and a
    /// read-only mirror for non-hosts. Updated live on host transfer.
    /// Serialized as a STRING (like every other id) so JS doesn't lose
    /// precision on snowflake-magnitude ids (>2^53).
    #[serde_as(as = "Option<serde_with::DisplayFromStr>")]
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub host_id: Option<i64>,
}

fn default_max_players() -> u8 {
    6
}

#[cfg(test)]
mod tests {
    use super::*;
    // Test-only: the lib build has no other use of this, so importing it at
    // module scope makes it an unused import outside `cfg(test)`.
    use crate::protocol::types::NewsNotificationType;
    use crate::protocol::{types, GameType};

    #[test]
    fn spectator_became_player_carries_the_name_on_the_wire() {
        let msg = ServerMessage::SpectatorBecamePlayer {
            player_id: 1_234_567_890_123_456_789,
            username: "ada".to_string(),
            name: Some(PlayerName::new("Ada", Some("Rune Queen".into()))),
            game_id: "g1".to_string(),
        };
        let json = serde_json::to_string(&msg).unwrap();
        assert!(json.contains(r#""name":{"discord":"Ada","runecast":"Rune Queen"}"#));
        assert!(json.contains(r#""player_id":"1234567890123456789""#));
    }

    #[test]
    fn spectator_became_player_without_a_name_parses_as_none() {
        let raw = r#"{"type":"spectator_became_player","player_id":"42","username":"ada","game_id":"g1"}"#;
        match serde_json::from_str::<ServerMessage>(raw).unwrap() {
            ServerMessage::SpectatorBecamePlayer {
                player_id, name, ..
            } => {
                assert_eq!(player_id, 42);
                assert!(name.is_none());
            }
            other => panic!("wrong variant: {other:?}"),
        }
    }

    #[test]
    fn test_server_message_into_json() {
        let msg = ServerMessage::BoardShuffled {
            player_id: 1_234_567_890,
            game_id: "1234567890".to_string(),
            new_grid: Grid::new(),
            gems_spent: 0,
            total_gems: 0,
        };
        let json = serde_json::to_string(&msg).unwrap();
        assert!(json.contains(r#""type":"board_shuffled""#));
        assert!(json.contains(r#""player_id":"1234567890""#));
        assert!(json.contains(r#""game_id":"1234567890""#));
        assert!(json.contains(r#""new_grid":[]"#));
        assert!(json.contains(r#""gems_spent":0"#));
        assert!(json.contains(r#""total_gems":0"#));
    }

    #[test]
    fn test_heartbeat_ack_serialization() {
        let msg = ServerMessage::HeartbeatAck {
            server_time: 1_701_234_567_890,
        };
        let json = serde_json::to_string(&msg).unwrap();
        assert!(json.contains(r#""type":"heartbeat_ack""#));
        assert!(json.contains(r#""server_time":1701234567890"#));
    }

    #[test]
    fn test_error_message_creation() {
        let msg = ServerMessage::error(ErrorCode::NotYourTurn);
        match msg {
            ServerMessage::Error { code, message, .. } => {
                assert_eq!(code, ErrorCode::NotYourTurn);
                assert_eq!(message, "It's not your turn");
            }
            _ => panic!("Expected error message"),
        }
    }

    #[test]
    fn test_error_with_details() {
        let msg = ServerMessage::error_with_details(
            ErrorCode::InvalidPath,
            "Tiles must be adjacent",
            serde_json::json!({"positions": [[0,0], [2,2]]}),
        );
        match msg {
            ServerMessage::Error { details, .. } => {
                assert!(details.is_some());
            }
            _ => panic!("Expected error message"),
        }
    }

    #[test]
    fn test_player_joined_serialization() {
        let msg = ServerMessage::PlayerJoined {
            player: LobbyPlayerInfo {
                user_id: 123,
                username: "TestPlayer".to_string(),
                name: None,
                avatar_url: None,
                banner_url: None,
                accent_color: None,
                current_game_pool: None,
                active_game_id: None,
                spectate_game_id: None,
            },
        };
        let json = serde_json::to_string(&msg).unwrap();
        assert!(json.contains(r#""type":"player_joined""#));
        assert!(json.contains(r#""user_id":"123""#));
    }

    #[test]
    fn test_game_state_update_legacy() {
        // Verify legacy format still works
        let json = r#"{"type":"game_state","game_id":"abc","state":"in_progress","grid":[],"players":[],"current_turn":123,"round":1,"max_rounds":5,"used_words":[],"spectators":[],"timer_vote_state":{"status":"idle"}}"#;
        let msg: ServerMessage = serde_json::from_str(json).unwrap();
        assert!(matches!(msg, ServerMessage::GameStateUpdate { .. }));
    }

    #[test]
    fn test_should_store_for_replay() {
        assert!(!ServerMessage::HeartbeatAck { server_time: 0 }.should_store_for_replay());
        assert!(ServerMessage::PlayerJoined {
            player: LobbyPlayerInfo {
                user_id: 1,
                username: "x".into(),
                name: None,
                avatar_url: None,
                banner_url: None,
                accent_color: None,
                current_game_pool: None,
                active_game_id: None,
                spectate_game_id: None,
            }
        }
        .should_store_for_replay());
    }

    #[test]
    fn test_message_type() {
        assert_eq!(
            ServerMessage::HeartbeatAck { server_time: 0 }.message_type(),
            "heartbeat_ack"
        );
        assert_eq!(
            ServerMessage::error(ErrorCode::NotYourTurn).message_type(),
            "error"
        );

        // Adventure-mode variants — keep these assertions in sync with
        // any future additions so the match in `message_type()` can't
        // silently fall out of step with the enum.
        assert_eq!(
            ServerMessage::AdventureLevelResult {
                level: 1,
                score: 10,
                stars: 1,
                personal_best: true,
                unlocked_level: None,
                duration_ms: None,
            }
            .message_type(),
            "adventure_level_result",
        );
        assert_eq!(
            ServerMessage::AdventureEvent {
                game_id: "g".to_string(),
                kind: types::AdventureEventKind::Bomb,
                affected_positions: vec![],
                new_grid: vec![],
                label: String::new(),
            }
            .message_type(),
            "adventure_event",
        );
    }

    #[test]
    fn test_adventure_level_result_serialization() {
        // With both optional fields absent: they should be omitted
        // entirely via skip_serializing_if so older clients don't
        // see unexpected nulls.
        let msg = ServerMessage::AdventureLevelResult {
            level: 3,
            score: 120,
            stars: 2,
            personal_best: false,
            unlocked_level: None,
            duration_ms: None,
        };
        let json = serde_json::to_string(&msg).unwrap();
        assert!(json.contains(r#""type":"adventure_level_result""#));
        assert!(json.contains(r#""level":3"#));
        assert!(json.contains(r#""score":120"#));
        assert!(json.contains(r#""stars":2"#));
        assert!(json.contains(r#""personal_best":false"#));
        assert!(
            !json.contains("unlocked_level"),
            "unlocked_level should be omitted when None (got: {json})"
        );
        assert!(
            !json.contains("duration_ms"),
            "duration_ms should be omitted when None (got: {json})"
        );

        // Both optional fields present: serialize with their canonical
        // field names. duration_ms must be a plain JSON number (u64);
        // JSON-wise that looks the same as a signed int, but exercising
        // the path ensures the u64 type didn't accidentally become a
        // stringified-int somewhere.
        let msg = ServerMessage::AdventureLevelResult {
            level: 3,
            score: 120,
            stars: 3,
            personal_best: true,
            unlocked_level: Some(4),
            duration_ms: Some(123_456),
        };
        let json = serde_json::to_string(&msg).unwrap();
        assert!(json.contains(r#""unlocked_level":4"#));
        assert!(json.contains(r#""duration_ms":123456"#));

        // Round-trip — the deserialize path needs to accept the
        // serialized form and reproduce the same structure.
        let parsed: ServerMessage = serde_json::from_str(&json).unwrap();
        match parsed {
            ServerMessage::AdventureLevelResult {
                level,
                score,
                stars,
                personal_best,
                unlocked_level,
                duration_ms,
            } => {
                assert_eq!(level, 3);
                assert_eq!(score, 120);
                assert_eq!(stars, 3);
                assert!(personal_best);
                assert_eq!(unlocked_level, Some(4));
                assert_eq!(duration_ms, Some(123_456));
            }
            other => panic!("expected AdventureLevelResult, got {other:?}"),
        }
    }

    #[test]
    fn daily_result_serializes() {
        let msg = ServerMessage::DailyResult {
            seed: 1_592_668_382,
            score: 240,
            personal_best: 240,
            rank: 3,
            attempts_used: 1,
            attempts_max: 1,
        };
        assert_eq!(msg.message_type(), "daily_result");
        let s = serde_json::to_string(&msg).unwrap();
        assert!(s.contains("\"type\":\"daily_result\""));
        assert!(s.contains("\"rank\":3"));
        let back: ServerMessage = serde_json::from_str(&s).unwrap();
        assert!(matches!(back, ServerMessage::DailyResult { rank: 3, .. }));
    }

    #[test]
    fn game_started_time_remaining_optional() {
        let msg = ServerMessage::GameStarted {
            game_type: GameType::Open,
            game_id: "g1".into(),
            grid: vec![],
            players: vec![],
            your_turn_order: 0,
            current_turn: 42,
            round: 1,
            max_rounds: 1,
            turn_time_limit: None,
            custom: None,
            time_remaining_ms: None,
        };
        let s = serde_json::to_string(&msg).unwrap();
        assert!(!s.contains("time_remaining_ms"));
    }

    #[test]
    fn test_adventure_event_serialization() {
        let msg = ServerMessage::AdventureEvent {
            game_id: "abc".to_string(),
            kind: types::AdventureEventKind::Bomb,
            affected_positions: vec![
                types::Position { row: 1, col: 2 },
                types::Position { row: 2, col: 2 },
            ],
            new_grid: vec![vec![
                // One plain cell + one hole cell — this lets the test
                // assert GridCell's is_hole flag on AdventureEvent's
                // embedded Grid field stays wire-compatible.
                types::GridCell {
                    letter: 'A',
                    value: 1,
                    multiplier: None,
                    has_gem: false,
                    is_hole: false,
                    is_poisoned: false,
                    is_abducted: false,
                },
                types::GridCell {
                    letter: ' ',
                    value: 0,
                    multiplier: None,
                    has_gem: false,
                    is_hole: true,
                    is_poisoned: false,
                    is_abducted: false,
                },
            ]],
            label: "💣 Bomb!".to_string(),
        };

        let json = serde_json::to_string(&msg).unwrap();
        assert!(json.contains(r#""type":"adventure_event""#));
        assert!(json.contains(r#""game_id":"abc""#));
        // kind serializes via the enum's snake_case rename.
        assert!(json.contains(r#""kind":"bomb""#));
        // Affected positions are plain { row, col } objects.
        assert!(json.contains(r#""affected_positions":[{"row":1,"col":2}"#));
        // new_grid's plain cell omits is_hole; hole cell carries it.
        assert!(json.contains(r#""letter":"A""#));
        assert!(json.contains(r#""is_hole":true"#));

        // Round-trip so we know the type tag + enum field decode correctly.
        let parsed: ServerMessage = serde_json::from_str(&json).unwrap();
        match parsed {
            ServerMessage::AdventureEvent {
                game_id,
                kind,
                affected_positions,
                new_grid,
                label,
            } => {
                assert_eq!(game_id, "abc");
                assert_eq!(kind, types::AdventureEventKind::Bomb);
                assert_eq!(affected_positions.len(), 2);
                assert_eq!(new_grid[0].len(), 2);
                assert!(new_grid[0][1].is_hole);
                assert_eq!(label, "💣 Bomb!");
            }
            other => panic!("expected AdventureEvent, got {other:?}"),
        }
    }

    #[test]
    fn test_selection_update_serialization() {
        let msg = ServerMessage::SelectionUpdate {
            player_id: 11,
            game_id: "game1".to_string(),
            positions: vec![
                types::Position { row: 0, col: 0 },
                types::Position { row: 0, col: 1 },
            ],
        };
        let json = serde_json::to_string(&msg).unwrap();
        assert!(json.contains(r#""type":"selection_update""#));
        assert!(json.contains(r#""player_id":"11""#));
        assert!(json.contains(r#""game_id":"game1""#));
    }

    #[test]
    fn test_player_queue_changed_serialization() {
        let msg = ServerMessage::PlayerPoolChanged {
            player_id: 123,
            old_pool: Some(GameType::Open),
            new_pool: Some(GameType::Adventure),
        };
        let json = serde_json::to_string(&msg).unwrap();
        assert!(json.contains(r#""type":"player_pool_changed""#));
        assert!(json.contains(r#""player_id":"123""#));
        assert!(json.contains(r#""old_pool":"open""#));
        assert!(json.contains(r#""new_pool":"adventure""#));
    }

    #[test]
    fn test_debug_state_response_serialization() {
        let msg = ServerMessage::DebugStateResponse {
            timestamp: "2024-01-01T12:00:00Z".to_string(),
            player: DebugPlayerInfo {
                user_id: 987654321,
                username: "debug_user".to_string(),
            },
            websocket_context: DebugWebsocketContext {
                lobby_id: Some("lobby123".to_string()),
                game_id: Some("game456".to_string()),
                is_spectating: false,
            },
            lobby_state: Some(DebugLobbyState::Found {
                lobby_id: "lobby123".to_string(),
                player_in_lobby: true,
                lobby_player_ids: vec![111, 222, 333],
                active_game_id: Some("game456".to_string()),
            }),
            backend_game_state: Some(DebugBackendGameState::Found {
                game_id: "game456".to_string(),
                player_in_session_players: true,
                spectator_in_session: false,
                session_player_ids: vec![111, 222],
                session_spectator_ids: vec![],
                lobby_id: "lobby123".to_string(),
            }),
            handler_game_state: Some(DebugHandlerGameState::Found {
                game_id: "game456".to_string(),
                player_in_handler_game: true,
                handler_player_ids: vec![111, 222],
                current_turn_index: 0,
                round: 1,
                state: "in_progress".to_string(),
            }),
        };

        // Test serialization
        let json = serde_json::to_string(&msg).unwrap();

        // Verify type field
        assert!(json.contains(r#""type":"debug_state_response""#));

        // Verify ID fields are serialized as numbers
        assert!(json.contains(r#""user_id":987654321"#));
        assert!(json.contains(r#""lobby_player_ids":[111,222,333]"#));
        assert!(json.contains(r#""session_player_ids":[111,222]"#));
        assert!(json.contains(r#""handler_player_ids":[111,222]"#));

        // Verify other key fields
        assert!(json.contains(r#""timestamp":"2024-01-01T12:00:00Z""#));
        assert!(json.contains(r#""username":"debug_user""#));
        assert!(json.contains(r#""lobby_id":"lobby123""#));
        assert!(json.contains(r#""game_id":"game456""#));
        assert!(json.contains(r#""is_spectating":false"#));
        assert!(json.contains(r#""player_in_lobby":true"#));

        // Test deserialization (round-trip)
        let deserialized: ServerMessage = serde_json::from_str(&json).unwrap();
        match deserialized {
            ServerMessage::DebugStateResponse {
                timestamp,
                player,
                websocket_context,
                lobby_state,
                backend_game_state,
                handler_game_state,
            } => {
                assert_eq!(timestamp, "2024-01-01T12:00:00Z");
                assert_eq!(player.user_id, 987654321);
                assert_eq!(player.username, "debug_user");
                assert_eq!(websocket_context.lobby_id, Some("lobby123".to_string()));
                assert_eq!(websocket_context.game_id, Some("game456".to_string()));
                assert!(!websocket_context.is_spectating);
                assert!(lobby_state.is_some());
                assert!(backend_game_state.is_some());
                assert!(handler_game_state.is_some());
            }
            _ => panic!("Expected DebugStateResponse message"),
        }
    }

    #[test]
    fn test_debug_state_response_with_errors() {
        // Test with error variants in debug states
        let msg = ServerMessage::DebugStateResponse {
            timestamp: "2024-01-01T12:00:00Z".to_string(),
            player: DebugPlayerInfo {
                user_id: 123,
                username: "test".to_string(),
            },
            websocket_context: DebugWebsocketContext {
                lobby_id: None,
                game_id: None,
                is_spectating: false,
            },
            lobby_state: Some(DebugLobbyState::Error {
                error: "Lobby not found".to_string(),
            }),
            backend_game_state: Some(DebugBackendGameState::Error {
                error: "Game not found".to_string(),
            }),
            handler_game_state: Some(DebugHandlerGameState::Error {
                error: "Handler not found".to_string(),
            }),
        };

        let json = serde_json::to_string(&msg).unwrap();

        // Verify error messages are included
        assert!(json.contains(r#""error":"Lobby not found""#));
        assert!(json.contains(r#""error":"Game not found""#));
        assert!(json.contains(r#""error":"Handler not found""#));

        // Round-trip test
        let deserialized: ServerMessage = serde_json::from_str(&json).unwrap();
        assert!(matches!(
            deserialized,
            ServerMessage::DebugStateResponse { .. }
        ));
    }

    #[test]
    fn test_debug_state_response_minimal() {
        // Test with None values for optional fields
        let msg = ServerMessage::DebugStateResponse {
            timestamp: "2024-01-01T12:00:00Z".to_string(),
            player: DebugPlayerInfo {
                user_id: 456,
                username: "minimal_user".to_string(),
            },
            websocket_context: DebugWebsocketContext {
                lobby_id: None,
                game_id: None,
                is_spectating: true,
            },
            lobby_state: None,
            backend_game_state: None,
            handler_game_state: None,
        };

        let json = serde_json::to_string(&msg).unwrap();

        // Verify type field
        assert!(json.contains(r#""type":"debug_state_response""#));

        // Verify required fields
        assert!(json.contains(r#""user_id":456"#));
        assert!(json.contains(r#""username":"minimal_user""#));
        assert!(json.contains(r#""is_spectating":true"#));

        // Round-trip test
        let deserialized: ServerMessage = serde_json::from_str(&json).unwrap();
        match deserialized {
            ServerMessage::DebugStateResponse {
                player,
                lobby_state,
                backend_game_state,
                handler_game_state,
                ..
            } => {
                assert_eq!(player.user_id, 456);
                assert!(lobby_state.is_none());
                assert!(backend_game_state.is_none());
                assert!(handler_game_state.is_none());
            }
            _ => panic!("Expected DebugStateResponse message"),
        }
    }

    #[test]
    fn test_news_announced_round_trip() {
        let now = chrono::Utc::now();
        let expires = now + chrono::Duration::hours(1);
        let original = ServerMessage::NewsAnnounced {
            item: NewsItemPayload {
                id: "abc-123".to_string(),
                title: "Scheduled Maintenance".to_string(),
                message: "Servers will restart for ~5 minutes.".to_string(),
                notification_type: NewsNotificationType::Maintenance,
                created_at: now,
                expires_at: Some(expires),
                auto_hide_seconds: 0,
                refresh_on_every_login: false,
                priority: 100,
            },
        };

        let json = serde_json::to_string(&original).unwrap();
        assert!(json.contains(r#""type":"news_announced""#));
        assert!(json.contains(r#""notification_type":"maintenance""#));

        let parsed: ServerMessage = serde_json::from_str(&json).unwrap();
        match parsed {
            ServerMessage::NewsAnnounced { item } => {
                assert_eq!(item.id, "abc-123");
                assert_eq!(item.notification_type, NewsNotificationType::Maintenance);
                assert_eq!(item.priority, 100);
                assert_eq!(item.expires_at, Some(expires));
            }
            _ => panic!("Expected NewsAnnounced"),
        }
    }

    #[test]
    fn test_news_announced_excluded_from_replay() {
        // News is re-fetched from /api/news on reconnect, so replaying
        // the original announcement would duplicate or surface stale.
        let msg = ServerMessage::NewsAnnounced {
            item: NewsItemPayload {
                id: "x".to_string(),
                title: "t".to_string(),
                message: "m".to_string(),
                notification_type: NewsNotificationType::Announcement,
                created_at: chrono::Utc::now(),
                expires_at: None,
                auto_hide_seconds: 0,
                refresh_on_every_login: false,
                priority: 0,
            },
        };
        assert!(!msg.should_store_for_replay());
    }

    #[test]
    fn game_started_custom_marker_roundtrips_and_omits_when_none() {
        use crate::protocol::types::CustomMeta;

        // Build a GameStarted with custom: Some(CustomMeta {})
        let msg = ServerMessage::GameStarted {
            game_type: GameType::Open,
            game_id: "game-sandbox-1".to_string(),
            grid: vec![],
            players: vec![types::GamePlayerInfo {
                user_id: 111_222_333_444_555_666,
                username: "Player1".to_string(),
                name: None,
                avatar_url: None,
                turn_order: 0,
                score: 0,
                gems: 0,
                is_connected: true,
                team: None,
            }],
            your_turn_order: 0,
            current_turn: 111_222_333_444_555_666,
            round: 1,
            max_rounds: 5,
            turn_time_limit: None,
            custom: Some(CustomMeta {}),
            time_remaining_ms: None,
        };
        let json = serde_json::to_string(&msg).unwrap();
        assert!(
            json.contains("\"custom\""),
            "custom should serialize when Some (got: {json})"
        );
        let back: ServerMessage = serde_json::from_str(&json).unwrap();
        assert!(
            matches!(
                back,
                ServerMessage::GameStarted {
                    custom: Some(_),
                    ..
                }
            ),
            "custom should deserialize as Some"
        );

        // Same shape but custom: None — field must be absent on the wire
        let ffa = ServerMessage::GameStarted {
            game_type: GameType::Open,
            game_id: "game-ffa-1".to_string(),
            grid: vec![],
            players: vec![],
            your_turn_order: 0,
            current_turn: 111_222_333_444_555_666,
            round: 1,
            max_rounds: 5,
            turn_time_limit: None,
            custom: None,
            time_remaining_ms: None,
        };
        let json2 = serde_json::to_string(&ffa).unwrap();
        assert!(
            !json2.contains("\"custom\""),
            "custom should be omitted when None (got: {json2})"
        );
    }

    #[test]
    fn lobby_snapshot_carries_sandbox_config() {
        // Build a minimal LobbySnapshot with sandbox_config set.
        let mut snap = LobbySnapshot {
            lobby_id: "test-lobby".to_string(),
            lobby_type: LobbyType::Custom,
            lobby_code: None,
            players: vec![],
            games: vec![],
            max_players: 6,
            sandbox_config: None,
            host_id: None,
        };
        snap.sandbox_config = Some(GameConfig::default());

        let json = serde_json::to_string(&snap).unwrap();
        assert!(
            json.contains("sandbox_config"),
            "sandbox_config should be present when Some (got: {json})"
        );
        let back: LobbySnapshot = serde_json::from_str(&json).unwrap();
        assert!(back.sandbox_config.is_some());

        // Confirm it's omitted on the wire when None (back-compat).
        let plain = LobbySnapshot {
            lobby_id: "plain-lobby".to_string(),
            lobby_type: LobbyType::Custom,
            lobby_code: None,
            players: vec![],
            games: vec![],
            max_players: 6,
            sandbox_config: None,
            host_id: None,
        };
        assert!(
            !serde_json::to_string(&plain)
                .unwrap()
                .contains("sandbox_config"),
            "sandbox_config should be omitted when None"
        );
        assert!(
            !serde_json::to_string(&plain).unwrap().contains("host_id"),
            "host_id should be omitted when None"
        );
    }

    #[test]
    fn lobby_snapshot_host_id_serializes_as_string_snowflake_safe() {
        // host_id must serialize as a STRING (like every other id) so JS
        // doesn't lose precision on snowflake-magnitude ids (>2^53). A
        // JSON-number would round and break host detection on the client.
        let snowflake: i64 = 123_456_789_012_345_678; // 18 digits, > 2^53
        let snap = LobbySnapshot {
            lobby_id: "lobby".to_string(),
            lobby_type: LobbyType::Custom,
            lobby_code: None,
            players: vec![],
            games: vec![],
            max_players: 6,
            sandbox_config: None,
            host_id: Some(snowflake),
        };
        let json = serde_json::to_string(&snap).unwrap();
        // Quoted = string on the wire; an unquoted number would be the bug.
        assert!(
            json.contains(r#""host_id":"123456789012345678""#),
            "host_id must serialize as a quoted string, got: {json}"
        );
        // Exact round-trip (no precision loss).
        let back: LobbySnapshot = serde_json::from_str(&json).unwrap();
        assert_eq!(back.host_id, Some(snowflake));
    }

    #[test]
    fn runebox_word_accepted_round_trips() {
        let msg = ServerMessage::RuneBoxWordAccepted {
            game_id: "g1".to_string(),
            word: "RUNES".to_string(),
            letters: 5,
            total_score: 17,
        };
        let json = serde_json::to_string(&msg).unwrap();
        assert!(json.contains(r#""type":"rune_box_word_accepted""#));
        let back: ServerMessage = serde_json::from_str(&json).unwrap();
        match back {
            ServerMessage::RuneBoxWordAccepted {
                word,
                letters,
                total_score,
                ..
            } => {
                assert_eq!(word, "RUNES");
                assert_eq!(letters, 5);
                assert_eq!(total_score, 17);
            }
            other => panic!("wrong variant: {other:?}"),
        }
    }

    #[test]
    fn runebox_score_changed_carries_no_word() {
        // THE anti-leak assertion. RuneBox found-sets are independent, so a word
        // another player found is still worth full value to you — telling you
        // what it was would hand you the answer. This variant having no `word`
        // field is what enforces that, so assert on the serialized form: a
        // future field addition fails here rather than silently shipping.
        let msg = ServerMessage::RuneBoxScoreChanged {
            player_id: 1_234_567_890_123_456_789,
            game_id: "g1".to_string(),
            total_score: 12,
        };
        let json = serde_json::to_string(&msg).unwrap();
        assert!(
            !json.contains("word"),
            "opponent broadcast leaked a word: {json}"
        );
        // Snowflakes ride as strings or they corrupt above 2^53 in JS.
        assert!(
            json.contains(r#""player_id":"1234567890123456789""#),
            "player_id must serialize as a quoted string, got: {json}"
        );
        let back: ServerMessage = serde_json::from_str(&json).unwrap();
        match back {
            ServerMessage::RuneBoxScoreChanged {
                player_id,
                total_score,
                ..
            } => {
                assert_eq!(player_id, 1_234_567_890_123_456_789);
                assert_eq!(total_score, 12);
            }
            other => panic!("wrong variant: {other:?}"),
        }
    }

    #[test]
    fn runebox_messages_have_distinct_wire_types() {
        let accepted = ServerMessage::RuneBoxWordAccepted {
            game_id: "g1".to_string(),
            word: "RUNES".to_string(),
            letters: 5,
            total_score: 5,
        };
        let changed = ServerMessage::RuneBoxScoreChanged {
            player_id: 1,
            game_id: "g1".to_string(),
            total_score: 5,
        };
        assert_eq!(accepted.message_type(), "rune_box_word_accepted");
        assert_eq!(changed.message_type(), "rune_box_score_changed");
    }

    /// The JOIN path must be self-describing too.
    ///
    /// v0.18.0 put the mode on `GameSnapshot` and stopped, which fixed the
    /// reconnect/spectate path and left the one a normal player actually takes
    /// still inferring. Both halves or neither.
    #[test]
    fn game_started_carries_its_game_type() {
        let msg = ServerMessage::GameStarted {
            game_type: GameType::RuneBox,
            game_id: "g1".to_string(),
            grid: vec![],
            players: vec![],
            your_turn_order: 0,
            current_turn: 1,
            round: 1,
            max_rounds: 3,
            turn_time_limit: None,
            custom: None,
            time_remaining_ms: Some(90_000),
        };
        let json = serde_json::to_string(&msg).unwrap();
        assert!(
            json.contains(r#""game_type":"rune_box""#),
            "game_started must name the mode, got: {json}"
        );
        let back: ServerMessage = serde_json::from_str(&json).unwrap();
        match back {
            ServerMessage::GameStarted { game_type, .. } => {
                assert_eq!(game_type, GameType::RuneBox);
            }
            other => panic!("wrong variant: {other:?}"),
        }
    }

    /// A two-round match state used by the round-end tests below.
    fn round_ended_sample(
        next_round_starts_at: Option<chrono::DateTime<chrono::Utc>>,
    ) -> ServerMessage {
        ServerMessage::RuneBoxRoundEnded {
            game_id: "g1".to_string(),
            round: 1,
            max_rounds: 2,
            round_scores: vec![
                ScoreInfo {
                    user_id: 1_234_567_890_123_456_789,
                    username: "Ada".to_string(),
                    name: None,
                    score: 41,
                },
                ScoreInfo {
                    user_id: 8_876_543_210_987_654_321_i64,
                    username: "Bo".to_string(),
                    name: None,
                    score: 12,
                },
            ],
            eliminated: vec![8_876_543_210_987_654_321_i64],
            standings: vec![RuneBoxStanding {
                player_id: 1_234_567_890_123_456_789,
                username: "Ada".to_string(),
                name: None,
                round_wins: 1,
                total_score: 41,
                eliminated: false,
            }],
            next_round_starts_at,
        }
    }

    /// Round-end must be its OWN message. `GameOver` keeps meaning "the match is
    /// over" — that is what makes this addition non-breaking for the modes that
    /// play exactly one round and only ever send `GameOver`.
    #[test]
    fn round_end_is_a_distinct_message_type_from_game_over() {
        let round_end = round_ended_sample(None);
        let match_end = ServerMessage::GameOver {
            game_id: "g1".to_string(),
            final_scores: vec![],
            winner_id: 1,
            is_draw: false,
        };
        assert_eq!(round_end.message_type(), "rune_box_round_ended");
        assert_eq!(match_end.message_type(), "game_over");
        assert_ne!(round_end.message_type(), match_end.message_type());
    }

    #[test]
    fn round_ended_round_trips_with_snowflakes_as_strings() {
        let json = serde_json::to_string(&round_ended_sample(None)).unwrap();
        assert!(json.contains(r#""type":"rune_box_round_ended""#));
        // Every snowflake on this message rides as a quoted string, including
        // the ones inside the `eliminated` list — a bare i64 there corrupts
        // above 2^53 in JS exactly like a top-level one would.
        assert!(
            json.contains(r#""eliminated":["8876543210987654321"]"#),
            "eliminated ids must be quoted strings, got: {json}"
        );
        assert!(
            json.contains(r#""player_id":"1234567890123456789""#),
            "standings player_id must be a quoted string, got: {json}"
        );
        assert!(
            json.contains(r#""user_id":"1234567890123456789""#),
            "round score user_id must be a quoted string, got: {json}"
        );

        let back: ServerMessage = serde_json::from_str(&json).unwrap();
        match back {
            ServerMessage::RuneBoxRoundEnded {
                round,
                max_rounds,
                round_scores,
                eliminated,
                standings,
                next_round_starts_at,
                ..
            } => {
                assert_eq!(round, 1);
                assert_eq!(max_rounds, 2);
                assert_eq!(round_scores.len(), 2);
                assert_eq!(eliminated, vec![8_876_543_210_987_654_321_i64]);
                assert_eq!(standings[0].round_wins, 1);
                assert_eq!(standings[0].total_score, 41);
                assert!(!standings[0].eliminated);
                assert!(next_round_starts_at.is_none());
            }
            other => panic!("wrong variant: {other:?}"),
        }
    }

    /// The SP1 anti-leak rule does not lapse between rounds. An eliminated
    /// player is still watching, and the survivors keep playing boards they
    /// remember, so a round-end summary must never name anyone's words.
    #[test]
    fn round_ended_leaks_no_words() {
        let json = serde_json::to_string(&round_ended_sample(None)).unwrap();
        assert!(
            !json.contains("word"),
            "round-end summary leaked a word field: {json}"
        );
    }

    /// `None` means "not scheduled yet", not "match over" — so it must be
    /// omitted rather than serialized as an explicit null a client could
    /// misread as a value.
    #[test]
    fn round_ended_omits_unscheduled_next_round() {
        let json = serde_json::to_string(&round_ended_sample(None)).unwrap();
        assert!(!json.contains("next_round_starts_at"), "got: {json}");

        let at = chrono::DateTime::parse_from_rfc3339("2026-07-29T12:00:00Z")
            .unwrap()
            .with_timezone(&chrono::Utc);
        let json = serde_json::to_string(&round_ended_sample(Some(at))).unwrap();
        assert!(json.contains("next_round_starts_at"), "got: {json}");
        let back: ServerMessage = serde_json::from_str(&json).unwrap();
        match back {
            ServerMessage::RuneBoxRoundEnded {
                next_round_starts_at,
                ..
            } => assert_eq!(next_round_starts_at, Some(at)),
            other => panic!("wrong variant: {other:?}"),
        }
    }
}