Implement multiplayer UNO WebSocket Space

Dockerfile

@@ -0,0 +1,15 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+
+ENV PYTHONDONTWRITEBYTECODE=1
+ENV PYTHONUNBUFFERED=1
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+
+EXPOSE 7860
+
+CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -1,10 +1,38 @@
 ---
-title: Uno
-emoji: 🏆
-colorFrom: yellow
-colorTo: red
+title: Multiplayer UNO
+emoji: 🃏
+colorFrom: red
+colorTo: blue
 sdk: docker
-pinned: false
+app_port: 7860
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Multiplayer UNO
+
+This is a Hugging Face Spaces-ready multiplayer UNO game built with FastAPI,
+WebSockets, and a browser frontend.
+
+## Features
+
+- Room-code based online multiplayer.
+- 3 to 15 total seats.
+- Host-controlled Bot seats and Bot difficulty.
+- Strict same-card jump-in rule.
+- Server-authoritative hands, deck, discard pile, turns, draw stacking, wild color
+  selection, rankings, and Bot moves.
+- The original `uno.html` is left unchanged. The multiplayer page reuses its CSS
+  through `/uno-style.css`.
+
+## Local Run
+
+```bash
+pip install -r requirements.txt
+uvicorn app:app --host 0.0.0.0 --port 7860
+```
+
+Open `http://localhost:7860`.
+
+## Hugging Face Spaces
+
+Create a Docker Space and upload this repository. The Space configuration in
+this README exposes port `7860`, matching the Dockerfile command.

app.py

@@ -0,0 +1,911 @@
+from __future__ import annotations
+
+import asyncio
+import random
+import secrets
+import string
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from fastapi import FastAPI, HTTPException, WebSocket, WebSocketDisconnect
+from fastapi.responses import FileResponse, JSONResponse, Response
+from fastapi.staticfiles import StaticFiles
+from pydantic import BaseModel, Field
+
+
+ROOT = Path(__file__).resolve().parent
+STATIC_DIR = ROOT / "static"
+UNO_HTML = ROOT / "uno.html"
+
+COLORS = ["red", "blue", "green", "yellow"]
+ACTION_VALUES = {"skip", "reverse", "draw2", "wild", "wild_draw4"}
+BOT_DELAYS = {"easy": 0.6, "medium": 1.0, "hard": 1.4}
+MIN_PLAYERS = 3
+MAX_PLAYERS = 15
+ROOM_IDLE_SECONDS = 30 * 60
+RECONNECT_SECONDS = 2 * 60
+
+
+class GameError(Exception):
+    def __init__(self, code: str, message: str):
+        super().__init__(message)
+        self.code = code
+        self.message = message
+
+
+@dataclass
+class Card:
+    id: str
+    color: str
+    value: str
+
+    def public(self) -> dict[str, str]:
+        return {"id": self.id, "color": self.color, "value": self.value}
+
+
+@dataclass
+class Player:
+    id: str
+    name: str
+    token: str
+    is_bot: bool = False
+    connected: bool = False
+    hand: list[Card] = field(default_factory=list)
+    said_uno: bool = False
+    finished: bool = False
+    rank: int | None = None
+    disconnected_at: float | None = None
+
+
+@dataclass
+class Room:
+    code: str
+    host_player_id: str
+    total_players: int
+    bot_difficulty: str = "hard"
+    bot_jump_in: bool = True
+    phase: str = "lobby"
+    players: list[Player] = field(default_factory=list)
+    deck: list[Card] = field(default_factory=list)
+    discard_pile: list[Card] = field(default_factory=list)
+    current_player_id: str | None = None
+    direction: int = 1
+    current_color: str = "red"
+    pending_draw: int = 0
+    finish_order: list[str] = field(default_factory=list)
+    awaiting_color_player_id: str | None = None
+    awaiting_color_card_value: str | None = None
+    jump_in_enabled: bool = True
+    connections: dict[str, WebSocket] = field(default_factory=dict)
+    lock: asyncio.Lock = field(default_factory=asyncio.Lock)
+    created_at: float = field(default_factory=time.time)
+    last_active: float = field(default_factory=time.time)
+    version: int = 0
+    card_uid_seed: int = 1
+
+    def touch(self) -> None:
+        self.last_active = time.time()
+
+    def next_card_id(self) -> str:
+        card_id = f"card_{self.card_uid_seed}"
+        self.card_uid_seed += 1
+        return card_id
+
+    def active_players(self) -> list[Player]:
+        return [p for p in self.players if not p.finished]
+
+    def human_players(self) -> list[Player]:
+        return [p for p in self.players if not p.is_bot]
+
+    def get_player(self, player_id: str) -> Player:
+        for player in self.players:
+            if player.id == player_id:
+                return player
+        raise GameError("player_not_found", "Player is not in this room.")
+
+    def get_player_index(self, player_id: str) -> int:
+        for idx, player in enumerate(self.players):
+            if player.id == player_id:
+                return idx
+        raise GameError("player_not_found", "Player is not in this room.")
+
+    def get_top_card(self) -> Card:
+        if not self.discard_pile:
+            raise GameError("no_discard", "The discard pile is empty.")
+        return self.discard_pile[-1]
+
+    def make_deck(self) -> list[Card]:
+        deck: list[Card] = []
+        for color in COLORS:
+            deck.append(Card(self.next_card_id(), color, "0"))
+            for value in range(1, 10):
+                deck.append(Card(self.next_card_id(), color, str(value)))
+                deck.append(Card(self.next_card_id(), color, str(value)))
+            for value in ("skip", "reverse", "draw2"):
+                deck.append(Card(self.next_card_id(), color, value))
+                deck.append(Card(self.next_card_id(), color, value))
+        for _ in range(4):
+            deck.append(Card(self.next_card_id(), "wild", "wild"))
+            deck.append(Card(self.next_card_id(), "wild", "wild_draw4"))
+        random.shuffle(deck)
+        return deck
+
+    def start_game(self, actor_id: str) -> dict[str, Any]:
+        self.require_host(actor_id)
+        if self.phase == "playing":
+            raise GameError("already_started", "This room is already playing.")
+        if not (MIN_PLAYERS <= len(self.players) <= MAX_PLAYERS):
+            raise GameError("bad_player_count", "A game needs 3 to 15 players.")
+        disconnected = [p for p in self.players if not p.is_bot and not p.connected]
+        if disconnected:
+            raise GameError("player_offline", "All human players must be connected before starting.")
+
+        self.card_uid_seed = 1
+        self.deck = self.make_deck()
+        self.discard_pile = []
+        self.direction = 1
+        self.pending_draw = 0
+        self.finish_order = []
+        self.awaiting_color_player_id = None
+        self.awaiting_color_card_value = None
+        self.phase = "playing"
+
+        for player in self.players:
+            player.hand = []
+            player.said_uno = False
+            player.finished = False
+            player.rank = None
+
+        for _ in range(7):
+            for player in self.players:
+                player.hand.append(self.deck.pop())
+
+        start_card: Card | None = None
+        while self.deck:
+            candidate = self.deck.pop()
+            if candidate.color == "wild":
+                self.deck.insert(0, candidate)
+                random.shuffle(self.deck)
+                continue
+            start_card = candidate
+            break
+        if start_card is None:
+            raise GameError("deck_error", "Could not choose a starting card.")
+
+        self.discard_pile.append(start_card)
+        self.current_color = start_card.color
+        self.current_player_id = self.active_players()[0].id
+        self.sync_uno_flags()
+        return {"type": "game_started", "roomCode": self.code}
+
+    def require_host(self, actor_id: str) -> None:
+        if actor_id != self.host_player_id:
+            raise GameError("not_host", "Only the host can do that.")
+
+    def set_room_options(self, actor_id: str, payload: dict[str, Any]) -> dict[str, Any]:
+        self.require_host(actor_id)
+        if self.phase != "lobby":
+            raise GameError("game_started", "Room options can only be changed in the lobby.")
+        total = int(payload.get("totalPlayers", self.total_players))
+        if not (MIN_PLAYERS <= total <= MAX_PLAYERS):
+            raise GameError("bad_total_players", "Total players must be between 3 and 15.")
+        if total < len(self.players):
+            raise GameError("too_small", "Total players cannot be lower than current seats.")
+        difficulty = payload.get("botDifficulty", self.bot_difficulty)
+        if difficulty not in BOT_DELAYS:
+            raise GameError("bad_difficulty", "Bot difficulty must be easy, medium, or hard.")
+        self.total_players = total
+        self.bot_difficulty = difficulty
+        self.bot_jump_in = bool(payload.get("botJumpIn", self.bot_jump_in))
+        return {"type": "room_options_changed"}
+
+    def add_bot(self, actor_id: str) -> dict[str, Any]:
+        self.require_host(actor_id)
+        if self.phase != "lobby":
+            raise GameError("game_started", "Bots can only be added in the lobby.")
+        if len(self.players) >= self.total_players:
+            raise GameError("room_full", "The room is already full.")
+        bot_num = 1 + sum(1 for p in self.players if p.is_bot)
+        bot = Player(
+            id=make_id("bot"),
+            name=f"Bot {bot_num}",
+            token=secrets.token_urlsafe(16),
+            is_bot=True,
+            connected=True,
+        )
+        self.players.append(bot)
+        return {"type": "bot_added", "playerId": bot.id, "name": bot.name}
+
+    def remove_bot(self, actor_id: str) -> dict[str, Any]:
+        self.require_host(actor_id)
+        if self.phase != "lobby":
+            raise GameError("game_started", "Bots can only be removed in the lobby.")
+        for idx in range(len(self.players) - 1, -1, -1):
+            if self.players[idx].is_bot:
+                bot = self.players.pop(idx)
+                return {"type": "bot_removed", "playerId": bot.id, "name": bot.name}
+        raise GameError("no_bot", "There are no bots to remove.")
+
+    def is_valid_play(self, card: Card) -> bool:
+        top_card = self.get_top_card()
+        if self.pending_draw > 0:
+            if top_card.value == "draw2":
+                return card.value in {"draw2", "wild_draw4"}
+            if top_card.value == "wild_draw4":
+                return card.value == "wild_draw4"
+            return False
+        if card.color == "wild":
+            return True
+        if card.color == self.current_color:
+            return True
+        return card.value == top_card.value
+
+    def is_strict_jump_in(self, card: Card) -> bool:
+        top_card = self.get_top_card()
+        return card.color == top_card.color and card.value == top_card.value
+
+    def legal_card_ids_for(self, player_id: str) -> list[str]:
+        if self.phase != "playing" or self.awaiting_color_player_id:
+            return []
+        player = self.get_player(player_id)
+        if player.finished:
+            return []
+        if player_id == self.current_player_id:
+            return [card.id for card in player.hand if self.is_valid_play(card)]
+        return [card.id for card in player.hand if self.is_strict_jump_in(card)]
+
+    def can_draw(self, player_id: str) -> bool:
+        return (
+            self.phase == "playing"
+            and not self.awaiting_color_player_id
+            and player_id == self.current_player_id
+            and not self.get_player(player_id).finished
+        )
+
+    def find_card(self, player: Player, card_id: str) -> Card:
+        for card in player.hand:
+            if card.id == card_id:
+                return card
+        raise GameError("card_not_found", "That card is not in your hand.")
+
+    def remove_card(self, player: Player, card: Card) -> None:
+        for idx, candidate in enumerate(player.hand):
+            if candidate.id == card.id:
+                player.hand.pop(idx)
+                return
+        raise GameError("card_not_found", "That card is not in your hand.")
+
+    def choose_bot_color(self, bot: Player) -> str:
+        counts = {color: 0 for color in COLORS}
+        for card in bot.hand:
+            if card.color in counts:
+                counts[card.color] += 1
+        return max(COLORS, key=lambda color: counts[color])
+
+    def pick_bot_card(self, bot: Player) -> Card | None:
+        legal = [card for card in bot.hand if self.is_valid_play(card)]
+        if not legal:
+            return None
+        if self.bot_difficulty == "easy":
+            return random.choice(legal)
+        if self.bot_difficulty == "medium":
+            action = next((c for c in legal if c.color == self.current_color and c.value in {"skip", "reverse", "draw2"}), None)
+            if action:
+                return action
+            number = next((c for c in legal if c.color == self.current_color and c.value.isdigit()), None)
+            return number or legal[0]
+
+        has_current_color = any(c.color == self.current_color for c in bot.hand if c.color != "wild")
+        if not has_current_color:
+            wild_draw4 = next((c for c in legal if c.value == "wild_draw4"), None)
+            if wild_draw4:
+                return wild_draw4
+        action = next((c for c in legal if c.color == self.current_color and c.value in {"skip", "reverse"}), None)
+        if action:
+            return action
+        draw2 = next((c for c in legal if c.color == self.current_color and c.value == "draw2"), None)
+        if draw2:
+            return draw2
+        numbers = [c for c in legal if c.color == self.current_color and c.value.isdigit()]
+        if numbers:
+            return sorted(numbers, key=lambda c: int(c.value), reverse=True)[0]
+        non_wild = next((c for c in legal if c.color != "wild"), None)
+        return non_wild or legal[0]
+
+    def play_card(
+        self,
+        player_id: str,
+        card_id: str,
+        *,
+        bot_auto_color: bool = False,
+        expected_top_card_id: str | None = None,
+        expected_version: int | None = None,
+    ) -> dict[str, Any]:
+        if self.phase != "playing":
+            raise GameError("not_playing", "The game is not currently playing.")
+        if self.awaiting_color_player_id:
+            raise GameError("awaiting_color", "A wild card color must be chosen first.")
+
+        player = self.get_player(player_id)
+        if player.finished:
+            raise GameError("player_finished", "Finished players cannot play cards.")
+        card = self.find_card(player, card_id)
+        if expected_version is not None and expected_version != self.version:
+            raise GameError("stale_table", "The table changed before your play arrived.")
+        if expected_top_card_id is not None and expected_top_card_id != self.get_top_card().id:
+            raise GameError("stale_table", "The discard pile changed before your play arrived.")
+        jump_in = player_id != self.current_player_id
+        if jump_in:
+            if expected_version is None or expected_top_card_id is None:
+                raise GameError("stale_jump_in", "Jump-in requires the latest table snapshot.")
+            if not self.jump_in_enabled:
+                raise GameError("jump_in_disabled", "Jump-in is not enabled.")
+            if not self.is_strict_jump_in(card):
+                raise GameError("bad_jump_in", "Jump-in requires the exact same card.")
+            self.current_player_id = player_id
+        elif not self.is_valid_play(card):
+            raise GameError("bad_play", "That card cannot be played right now.")
+
+        self.remove_card(player, card)
+        self.discard_pile.append(card)
+
+        if card.color != "wild":
+            self.current_color = card.color
+        if card.value == "reverse":
+            self.direction *= -1
+        elif card.value == "draw2":
+            self.pending_draw += 2
+        elif card.value == "wild_draw4":
+            self.pending_draw += 4
+            self.current_color = "wild"
+        elif card.value == "wild":
+            self.current_color = "wild"
+
+        self.sync_uno_flags()
+        self.mark_finished_if_needed(player)
+
+        chosen_color: str | None = None
+        if self.phase != "ended":
+            if card.value in {"wild", "wild_draw4"}:
+                if bot_auto_color or player.is_bot:
+                    chosen_color = self.choose_bot_color(player)
+                    self.current_color = chosen_color
+                    self.finish_turn_after(player_id, card)
+                else:
+                    self.awaiting_color_player_id = player_id
+                    self.awaiting_color_card_value = card.value
+            else:
+                self.finish_turn_after(player_id, card)
+
+        return {
+            "type": "card_played",
+            "playerId": player_id,
+            "playerName": player.name,
+            "card": card.public(),
+            "jumpIn": jump_in,
+            "chosenColor": chosen_color,
+        }
+
+    def choose_color(self, player_id: str, color: str) -> dict[str, Any]:
+        if color not in COLORS:
+            raise GameError("bad_color", "Color must be red, blue, green, or yellow.")
+        if self.awaiting_color_player_id != player_id:
+            raise GameError("not_awaiting_you", "This room is not waiting for you to choose a color.")
+        value = self.awaiting_color_card_value or "wild"
+        self.current_color = color
+        self.awaiting_color_player_id = None
+        self.awaiting_color_card_value = None
+        if self.phase != "ended":
+            self.finish_turn_after(player_id, Card("color_choice", "wild", value))
+        player = self.get_player(player_id)
+        return {"type": "color_changed", "playerId": player_id, "playerName": player.name, "color": color}
+
+    def draw_for_player(self, player_id: str) -> dict[str, Any]:
+        if self.phase != "playing":
+            raise GameError("not_playing", "The game is not currently playing.")
+        if self.awaiting_color_player_id:
+            raise GameError("awaiting_color", "A wild card color must be chosen first.")
+        if player_id != self.current_player_id:
+            raise GameError("not_your_turn", "Only the current player can draw.")
+        player = self.get_player(player_id)
+        if player.finished:
+            raise GameError("player_finished", "Finished players cannot draw.")
+
+        count = self.pending_draw if self.pending_draw > 0 else 1
+        drawn = self.take_cards(count)
+        player.hand.extend(drawn)
+        self.pending_draw = 0
+        self.sync_uno_flags()
+        self.finish_turn_after(player_id, None)
+        return {
+            "type": "cards_drawn",
+            "playerId": player_id,
+            "playerName": player.name,
+            "count": len(drawn),
+            "cards": [card.public() for card in drawn],
+        }
+
+    def take_cards(self, count: int) -> list[Card]:
+        drawn: list[Card] = []
+        for _ in range(count):
+            if not self.deck:
+                self.reshuffle_deck()
+            if not self.deck:
+                break
+            drawn.append(self.deck.pop())
+        return drawn
+
+    def reshuffle_deck(self) -> None:
+        if len(self.discard_pile) <= 1:
+            return
+        top_card = self.discard_pile[-1]
+        recycled = self.discard_pile[:-1]
+        random.shuffle(recycled)
+        self.deck.extend(recycled)
+        self.discard_pile = [top_card]
+
+    def sync_uno_flags(self) -> None:
+        for player in self.players:
+            if len(player.hand) != 1:
+                player.said_uno = False
+
+    def call_uno(self, player_id: str) -> dict[str, Any]:
+        player = self.get_player(player_id)
+        if len(player.hand) != 1:
+            raise GameError("not_uno", "UNO can only be called with exactly one card.")
+        player.said_uno = True
+        return {"type": "uno_called", "playerId": player_id, "playerName": player.name}
+
+    def mark_finished_if_needed(self, player: Player) -> None:
+        if player.hand or player.finished:
+            return
+        player.finished = True
+        player.rank = len(self.finish_order) + 1
+        self.finish_order.append(player.id)
+        remaining = [p for p in self.players if not p.finished]
+        if len(remaining) == 1:
+            last = remaining[0]
+            last.finished = True
+            last.rank = len(self.finish_order) + 1
+            self.finish_order.append(last.id)
+            self.phase = "ended"
+            self.current_player_id = None
+            self.awaiting_color_player_id = None
+            self.awaiting_color_card_value = None
+
+    def advance_steps_from(self, player_id: str, steps: int) -> str:
+        if not self.active_players():
+            return player_id
+        idx = self.get_player_index(player_id)
+        for _ in range(steps):
+            for _ in range(len(self.players)):
+                idx = (idx + self.direction + len(self.players)) % len(self.players)
+                candidate = self.players[idx]
+                if not candidate.finished:
+                    break
+        return self.players[idx].id
+
+    def finish_turn_after(self, player_id: str, card: Card | None) -> None:
+        if self.phase == "ended":
+            return
+        steps = 1
+        if card and card.value == "skip":
+            steps = 2
+        elif card and card.value == "reverse" and len(self.active_players()) == 2:
+            steps = 2
+        self.current_player_id = self.advance_steps_from(player_id, steps)
+
+    def snapshot_for(self, recipient_id: str) -> dict[str, Any]:
+        legal_ids = self.legal_card_ids_for(recipient_id) if self.phase == "playing" else []
+        players_payload: list[dict[str, Any]] = []
+        for player in self.players:
+            payload: dict[str, Any] = {
+                "id": player.id,
+                "name": player.name,
+                "isBot": player.is_bot,
+                "connected": player.connected,
+                "handCount": len(player.hand),
+                "saidUno": player.said_uno,
+                "finished": player.finished,
+                "rank": player.rank,
+            }
+            if player.id == recipient_id:
+                payload["hand"] = [card.public() for card in player.hand]
+            players_payload.append(payload)
+        top_card = self.discard_pile[-1].public() if self.discard_pile else None
+        return {
+            "roomCode": self.code,
+            "phase": self.phase,
+            "myPlayerId": recipient_id,
+            "hostPlayerId": self.host_player_id,
+            "settings": {
+                "totalPlayers": self.total_players,
+                "botDifficulty": self.bot_difficulty,
+                "botJumpIn": self.bot_jump_in,
+            },
+            "players": players_payload,
+            "deckCount": len(self.deck),
+            "discardPile": [card.public() for card in self.discard_pile],
+            "topCard": top_card,
+            "currentPlayerId": self.current_player_id,
+            "direction": self.direction,
+            "currentColor": self.current_color,
+            "pendingDraw": self.pending_draw,
+            "finishOrder": list(self.finish_order),
+            "awaitingColorPlayerId": self.awaiting_color_player_id,
+            "legalCardIds": legal_ids,
+            "canDraw": self.can_draw(recipient_id) if self.phase == "playing" else False,
+            "version": self.version,
+        }
+
+
+class CreateRoomRequest(BaseModel):
+    name: str = Field(min_length=1, max_length=24)
+    totalPlayers: int = Field(default=3, ge=MIN_PLAYERS, le=MAX_PLAYERS)
+    botDifficulty: str = "hard"
+    botJumpIn: bool = True
+
+
+class JoinRoomRequest(BaseModel):
+    name: str = Field(min_length=1, max_length=24)
+
+
+rooms: dict[str, Room] = {}
+app = FastAPI(title="Multiplayer UNO", version="1.0.0")
+app.mount("/static", StaticFiles(directory=STATIC_DIR), name="static")
+
+
+def make_id(prefix: str) -> str:
+    return f"{prefix}_{secrets.token_urlsafe(8)}"
+
+
+def make_room_code() -> str:
+    alphabet = string.ascii_uppercase + string.digits
+    while True:
+        code = "".join(secrets.choice(alphabet) for _ in range(5))
+        if code not in rooms:
+            return code
+
+
+def normalize_name(name: str) -> str:
+    cleaned = " ".join(name.strip().split())
+    return cleaned[:24] or "Player"
+
+
+def validate_difficulty(value: str) -> str:
+    if value not in BOT_DELAYS:
+        raise HTTPException(status_code=400, detail="botDifficulty must be easy, medium, or hard")
+    return value
+
+
+def public_join_payload(room: Room, player: Player) -> dict[str, str]:
+    return {"roomCode": room.code, "playerId": player.id, "token": player.token}
+
+
+@app.get("/")
+async def index() -> FileResponse:
+    return FileResponse(STATIC_DIR / "index.html")
+
+
+@app.get("/healthz")
+async def healthz() -> JSONResponse:
+    return JSONResponse({"ok": True, "rooms": len(rooms)})
+
+
+@app.get("/favicon.ico")
+async def favicon() -> Response:
+    return Response(status_code=204)
+
+
+@app.get("/uno-style.css")
+async def uno_style() -> Response:
+    if not UNO_HTML.exists():
+        return Response("", media_type="text/css")
+    text = UNO_HTML.read_text(encoding="utf-8", errors="replace")
+    start = text.find("<style>")
+    end = text.find("</style>")
+    css = text[start + len("<style>") : end] if start != -1 and end != -1 else ""
+    return Response(css, media_type="text/css")
+
+
+@app.post("/api/rooms")
+async def create_room(request: CreateRoomRequest) -> JSONResponse:
+    difficulty = validate_difficulty(request.botDifficulty)
+    code = make_room_code()
+    host = Player(
+        id=make_id("player"),
+        name=normalize_name(request.name),
+        token=secrets.token_urlsafe(24),
+        connected=False,
+    )
+    room = Room(
+        code=code,
+        host_player_id=host.id,
+        total_players=request.totalPlayers,
+        bot_difficulty=difficulty,
+        bot_jump_in=request.botJumpIn,
+        players=[host],
+    )
+    rooms[code] = room
+    return JSONResponse(public_join_payload(room, host))
+
+
+@app.post("/api/rooms/{room_code}/join")
+async def join_room(room_code: str, request: JoinRoomRequest) -> JSONResponse:
+    code = room_code.upper()
+    room = rooms.get(code)
+    if not room:
+        raise HTTPException(status_code=404, detail="Room not found")
+    async with room.lock:
+        if room.phase != "lobby":
+            raise HTTPException(status_code=409, detail="This room has already started")
+        if len(room.players) >= room.total_players:
+            raise HTTPException(status_code=409, detail="This room is full")
+        player = Player(
+            id=make_id("player"),
+            name=normalize_name(request.name),
+            token=secrets.token_urlsafe(24),
+            connected=False,
+        )
+        room.players.append(player)
+        room.touch()
+        room.version += 1
+    await broadcast_room(room, {"type": "player_joined", "playerId": player.id, "playerName": player.name})
+    return JSONResponse(public_join_payload(room, player))
+
+
+@app.websocket("/ws/{room_code}")
+async def websocket_endpoint(websocket: WebSocket, room_code: str) -> None:
+    code = room_code.upper()
+    player_id = websocket.query_params.get("playerId", "")
+    token = websocket.query_params.get("token", "")
+    await websocket.accept()
+
+    room = rooms.get(code)
+    if not room:
+        await websocket.send_json({"type": "error", "code": "room_not_found", "message": "Room not found."})
+        await websocket.close()
+        return
+
+    try:
+        async with room.lock:
+            player = room.get_player(player_id)
+            if player.token != token:
+                raise GameError("bad_token", "Invalid reconnect token.")
+            if player.is_bot:
+                raise GameError("bot_socket", "Bots cannot open sockets.")
+            player.connected = True
+            player.disconnected_at = None
+            room.connections[player_id] = websocket
+            room.touch()
+            room.version += 1
+        await broadcast_room(room, {"type": "player_connected", "playerId": player.id, "playerName": player.name})
+        schedule_bots(room)
+
+        while True:
+            data = await websocket.receive_json()
+            await handle_command(room, player_id, data)
+    except WebSocketDisconnect:
+        pass
+    except GameError as exc:
+        await websocket.send_json({"type": "error", "code": exc.code, "message": exc.message})
+    finally:
+        async with room.lock:
+            existing = room.connections.get(player_id)
+            if existing is websocket:
+                room.connections.pop(player_id, None)
+            try:
+                player = room.get_player(player_id)
+                player.connected = False
+                player.disconnected_at = time.time()
+                room.version += 1
+            except GameError:
+                player = None
+        if player:
+            await broadcast_room(room, {"type": "player_disconnected", "playerId": player.id, "playerName": player.name})
+
+
+async def handle_command(room: Room, player_id: str, data: dict[str, Any]) -> None:
+    command = data.get("type")
+    payload = data.get("payload") or {}
+    event: dict[str, Any] | None = None
+    error: GameError | None = None
+    changed = False
+
+    async with room.lock:
+        try:
+            room.touch()
+            if command == "set_room_options":
+                event = room.set_room_options(player_id, payload)
+                changed = True
+            elif command == "add_bot":
+                event = room.add_bot(player_id)
+                changed = True
+            elif command == "remove_bot":
+                event = room.remove_bot(player_id)
+                changed = True
+            elif command == "start_game":
+                event = room.start_game(player_id)
+                changed = True
+            elif command == "play_card":
+                card_id = str(payload.get("cardId", ""))
+                expected_top = payload.get("expectedTopCardId")
+                expected_version = payload.get("expectedVersion")
+                if expected_version is not None:
+                    expected_version = int(expected_version)
+                event = room.play_card(
+                    player_id,
+                    card_id,
+                    expected_top_card_id=str(expected_top) if expected_top is not None else None,
+                    expected_version=expected_version,
+                )
+                changed = True
+            elif command == "draw":
+                event = room.draw_for_player(player_id)
+                changed = True
+            elif command == "choose_color":
+                color = str(payload.get("color", ""))
+                event = room.choose_color(player_id, color)
+                changed = True
+            elif command == "call_uno":
+                event = room.call_uno(player_id)
+                changed = True
+            elif command == "restart":
+                event = room.start_game(player_id)
+                changed = True
+            else:
+                raise GameError("unknown_command", "Unknown command.")
+            if changed:
+                room.version += 1
+        except GameError as exc:
+            error = exc
+
+    if error:
+        await send_error(room, player_id, error)
+        return
+    if changed:
+        await broadcast_room(room, event)
+        schedule_bots(room)
+
+
+async def send_error(room: Room, player_id: str, error: GameError) -> None:
+    websocket = room.connections.get(player_id)
+    if not websocket:
+        return
+    await websocket.send_json({"type": "error", "code": error.code, "message": error.message})
+    async with room.lock:
+        snapshot = room.snapshot_for(player_id)
+    await websocket.send_json({"type": "snapshot", "state": snapshot})
+
+
+def event_for_recipient(event: dict[str, Any] | None, recipient_id: str) -> dict[str, Any] | None:
+    if not event:
+        return None
+    filtered = dict(event)
+    if filtered.get("type") == "cards_drawn" and filtered.get("playerId") != recipient_id:
+        filtered.pop("cards", None)
+    return filtered
+
+
+async def broadcast_room(room: Room, event: dict[str, Any] | None = None) -> None:
+    async with room.lock:
+        recipients = list(room.connections.items())
+        snapshots = {player_id: room.snapshot_for(player_id) for player_id, _ in recipients}
+    dead: list[str] = []
+    for player_id, websocket in recipients:
+        try:
+            recipient_event = event_for_recipient(event, player_id)
+            if recipient_event:
+                await websocket.send_json({"type": "event", "event": recipient_event})
+            await websocket.send_json({"type": "snapshot", "state": snapshots[player_id]})
+        except Exception:
+            dead.append(player_id)
+    if dead:
+        async with room.lock:
+            for player_id in dead:
+                room.connections.pop(player_id, None)
+
+
+def schedule_bots(room: Room) -> None:
+    if room.phase != "playing" or room.awaiting_color_player_id:
+        return
+    version = room.version
+    current = None
+    try:
+        current = room.get_player(room.current_player_id or "")
+    except GameError:
+        pass
+    if current and current.is_bot:
+        delay = BOT_DELAYS.get(room.bot_difficulty, 1.0)
+        asyncio.create_task(run_bot_turn(room.code, current.id, version, delay))
+    if room.bot_jump_in:
+        for player in room.players:
+            if player.is_bot and player.id != room.current_player_id and not player.finished:
+                if any(room.is_strict_jump_in(card) for card in player.hand):
+                    delay = random.uniform(0.45, 0.9)
+                    asyncio.create_task(run_bot_jump_in(room.code, player.id, version, delay))
+
+
+async def run_bot_turn(room_code: str, player_id: str, expected_version: int, delay: float) -> None:
+    await asyncio.sleep(delay)
+    room = rooms.get(room_code)
+    if not room:
+        return
+    event: dict[str, Any] | None = None
+    async with room.lock:
+        if room.version != expected_version or room.phase != "playing" or room.awaiting_color_player_id:
+            return
+        if room.current_player_id != player_id:
+            return
+        bot = room.get_player(player_id)
+        card = room.pick_bot_card(bot)
+        if card:
+            event = room.play_card(player_id, card.id, bot_auto_color=True)
+        else:
+            event = room.draw_for_player(player_id)
+        room.touch()
+        room.version += 1
+    await broadcast_room(room, event)
+    schedule_bots(room)
+
+
+async def run_bot_jump_in(room_code: str, player_id: str, expected_version: int, delay: float) -> None:
+    await asyncio.sleep(delay)
+    room = rooms.get(room_code)
+    if not room:
+        return
+    event: dict[str, Any] | None = None
+    async with room.lock:
+        if room.version != expected_version or room.phase != "playing" or room.awaiting_color_player_id:
+            return
+        if room.current_player_id == player_id:
+            return
+        bot = room.get_player(player_id)
+        card = next((candidate for candidate in bot.hand if room.is_strict_jump_in(candidate)), None)
+        if not card:
+            return
+        event = room.play_card(
+            player_id,
+            card.id,
+            bot_auto_color=True,
+            expected_top_card_id=room.get_top_card().id,
+            expected_version=expected_version,
+        )
+        room.touch()
+        room.version += 1
+    await broadcast_room(room, event)
+    schedule_bots(room)
+
+
+async def cleanup_rooms() -> None:
+    while True:
+        await asyncio.sleep(30)
+        now = time.time()
+        for code, room in list(rooms.items()):
+            async with room.lock:
+                if now - room.last_active > ROOM_IDLE_SECONDS:
+                    rooms.pop(code, None)
+                    continue
+                if room.phase == "lobby":
+                    for player in list(room.players):
+                        if (
+                            not player.is_bot
+                            and not player.connected
+                            and player.disconnected_at
+                            and now - player.disconnected_at > RECONNECT_SECONDS
+                            and player.id != room.host_player_id
+                        ):
+                            room.players.remove(player)
+                            room.version += 1
+
+
+@app.on_event("startup")
+async def on_startup() -> None:
+    asyncio.create_task(cleanup_rooms())
+
+
+def create_deck_for_tests() -> list[Card]:
+    room = Room(code="TEST", host_player_id="host", total_players=3)
+    return room.make_deck()

requirements.txt

@@ -0,0 +1,6 @@
+fastapi==0.115.6
+uvicorn[standard]==0.34.0
+pydantic==2.10.4
+pytest==8.3.4
+pytest-asyncio==0.25.2
+httpx==0.28.1

static/index.html

@@ -0,0 +1,921 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>UNO Multiplayer</title>
+<link rel="stylesheet" href="/uno-style.css">
+<style>
+.field-stack{display:flex;flex-direction:column;gap:8px}
+.text-input{
+  width:100%;padding:12px 14px;border-radius:12px;border:1px solid rgba(255,255,255,0.12);
+  background:rgba(255,255,255,0.06);color:var(--text-primary);font-size:14px;outline:none;
+}
+.text-input:focus{border-color:rgba(74,156,212,0.72);box-shadow:0 0 0 3px rgba(74,156,212,0.16)}
+.lobby-line{display:flex;align-items:center;justify-content:space-between;gap:12px}
+.room-code{
+  font-size:24px;font-weight:900;letter-spacing:5px;color:#fff;
+  text-shadow:0 0 18px rgba(74,156,212,0.5);
+}
+.status-text{min-height:18px;color:var(--text-muted);font-size:12px;line-height:1.4}
+.player-list{display:flex;flex-direction:column;gap:6px;max-height:176px;overflow:auto;padding-right:2px}
+.lobby-player{
+  display:flex;align-items:center;justify-content:space-between;gap:10px;
+  padding:8px 10px;border-radius:10px;background:rgba(255,255,255,0.05);
+  color:var(--text-primary);font-size:13px;
+}
+.pill{font-size:10px;letter-spacing:1px;text-transform:uppercase;color:#fff;border-radius:999px;padding:3px 7px;background:rgba(74,156,212,0.35)}
+.pill.host{background:rgba(243,156,18,0.42)}
+.pill.bot{background:rgba(46,204,113,0.32)}
+.mini-actions{display:flex;gap:8px}
+.small-btn{
+  border:none;border-radius:10px;padding:9px 12px;cursor:pointer;font-weight:800;font-size:12px;
+  color:var(--text-primary);background:rgba(255,255,255,0.08);transition:all 0.2s;
+}
+.small-btn:hover{background:rgba(255,255,255,0.14)}
+.small-btn:disabled,.glow-btn:disabled{opacity:0.42;cursor:not-allowed;transform:none;box-shadow:none}
+.number-input{max-width:78px;text-align:center}
+.toggle-row{display:flex;align-items:center;justify-content:space-between;gap:12px;font-size:13px;color:var(--text-primary)}
+.toggle-row input{width:18px;height:18px;accent-color:#2ecc71}
+.opponent-me{display:none}
+#ai-row.many-opponents{
+  align-self:flex-start;
+  width:calc(100% - 300px);
+  max-width:calc(100% - 300px);
+  margin-left:72px;
+  flex-wrap:nowrap;
+  justify-content:flex-start;
+  overflow-x:auto;
+  overflow-y:hidden;
+  padding:0 0 8px;
+  scrollbar-width:none;
+}
+#ai-row.many-opponents::-webkit-scrollbar{display:none}
+#ai-row.many-opponents .ai-opponent{flex:0 0 auto}
+.flying-card{
+  position:fixed;z-index:600;pointer-events:none;
+  transition:left 0.42s cubic-bezier(0.2,0.7,0.3,1),top 0.42s cubic-bezier(0.2,0.7,0.3,1),transform 0.42s cubic-bezier(0.2,0.7,0.3,1),opacity 0.25s ease;
+}
+#connection-chip{
+  position:fixed;left:14px;top:12px;z-index:120;color:var(--text-muted);
+  font-size:11px;letter-spacing:1px;text-transform:uppercase;
+  background:rgba(255,255,255,0.05);border:1px solid rgba(255,255,255,0.08);border-radius:999px;padding:6px 10px;
+}
+#connection-chip.online{color:#2ecc71}
+#connection-chip.offline{color:#e63946}
+#start-screen.connected{justify-content:flex-start;padding-top:42px;overflow:auto}
+#start-screen.connected .uno-logo{font-size:58px}
+#start-screen.connected .setup-panel{margin-bottom:32px}
+#player-hand .card-slot{cursor:pointer}
+@media (max-width: 760px){
+  #connection-chip{display:none}
+  #top-row{padding-top:34px}
+  #rotation-ring{top:8px;right:8px;font-size:9px;gap:5px}
+  #rotation-ring .ring-arrow{font-size:14px}
+  #start-screen.connected{padding:24px 12px}
+  .setup-panel{width:min(92vw,420px)}
+  .lobby-line{align-items:flex-start;flex-direction:column}
+  .mini-actions{width:100%}
+  .mini-actions .small-btn{flex:1}
+  #ai-row.many-opponents{
+    align-self:center;
+    width:100%;
+    max-width:100%;
+    margin-left:0;
+    padding:0 56px 8px 8px;
+  }
+}
+</style>
+</head>
+<body>
+<div class="bg-aurora"></div>
+<div id="connection-chip" class="offline">offline</div>
+
+<div id="start-screen">
+  <div class="uno-logo">UNO</div>
+  <p class="uno-tagline">Online Card Game</p>
+  <div class="setup-panel">
+    <div class="field-stack">
+      <label for="name-input">Name</label>
+      <input id="name-input" class="text-input" maxlength="24" autocomplete="nickname" placeholder="Player">
+    </div>
+
+    <div id="entry-panel" class="field-stack">
+      <label>Room Code</label>
+      <input id="room-input" class="text-input" maxlength="5" autocomplete="off" placeholder="ABCDE">
+      <div class="btn-group">
+        <button id="create-room-btn" class="active">Create</button>
+        <button id="join-room-btn">Join</button>
+      </div>
+    </div>
+
+    <div id="connected-panel" class="field-stack hidden">
+      <div class="lobby-line">
+        <div>
+          <label>Room</label>
+          <div id="room-code" class="room-code">-----</div>
+        </div>
+        <button id="copy-room-btn" class="small-btn">Copy Code</button>
+      </div>
+
+      <div class="field-stack" id="host-options">
+        <label>Seats</label>
+        <div class="lobby-line">
+          <input id="total-players-input" class="text-input number-input" type="number" min="3" max="15" value="3">
+          <div class="btn-group difficulty-btns">
+            <button data-diff="easy">Easy</button>
+            <button data-diff="medium">Medium</button>
+            <button data-diff="hard" class="active">Hard</button>
+          </div>
+        </div>
+        <label class="toggle-row">
+          <span>Bot jump-in</span>
+          <input id="bot-jump-input" type="checkbox" checked>
+        </label>
+        <div class="mini-actions">
+          <button id="add-bot-btn" class="small-btn">Add Bot</button>
+          <button id="remove-bot-btn" class="small-btn">Remove Bot</button>
+        </div>
+      </div>
+
+      <label>Players</label>
+      <div id="player-list" class="player-list"></div>
+      <button class="glow-btn" id="start-btn">START GAME</button>
+    </div>
+
+    <div id="status-text" class="status-text"></div>
+  </div>
+</div>
+
+<div id="game-board">
+  <div id="top-row">
+    <div id="rotation-ring">
+      <span id="ring-arrow" class="ring-arrow clockwise">-></span>
+      <span id="ring-text">Clockwise</span>
+    </div>
+    <div id="turn-orbit">
+      <div class="orbit-track" id="orbit-track"></div>
+      <div class="orbit-pointer" id="orbit-pointer"></div>
+    </div>
+    <div id="ai-row"></div>
+  </div>
+
+  <div id="center-area">
+    <div class="pile-zone">
+      <div id="draw-pile">
+        <div class="draw-stack" id="draw-stack"></div>
+      </div>
+      <div id="discard-zone">
+        <div id="discard-scatter"></div>
+      </div>
+    </div>
+    <div id="color-badge">
+      <span class="color-dot" id="color-dot"></span>
+      <span id="color-text">RED</span>
+    </div>
+  </div>
+
+  <div id="player-area">
+    <div id="turn-badge">Waiting</div>
+    <div id="score-row"></div>
+    <div id="player-hand"></div>
+    <button id="uno-call-btn">UNO!</button>
+  </div>
+
+  <div id="turn-toast"></div>
+  <div id="color-wash"></div>
+  <div id="card-stage"></div>
+
+  <div id="color-selector">
+    <span class="sel-label">Color</span>
+    <div class="sel-opt red" data-color="red"></div>
+    <div class="sel-opt blue" data-color="blue"></div>
+    <div class="sel-opt green" data-color="green"></div>
+    <div class="sel-opt yellow" data-color="yellow"></div>
+  </div>
+</div>
+
+<div id="win-screen">
+  <div class="confetti-container" id="confetti-container"></div>
+  <div class="win-content">
+    <h1>UNO!</h1>
+    <div class="winner-name" id="winner-name"></div>
+    <div class="win-scores" id="win-scores"></div>
+    <button class="glow-btn" id="play-again-btn">Play Again</button>
+  </div>
+</div>
+
+<script>
+const COLORS = ['red','blue','green','yellow'];
+const COLOR_NAMES = {red:'RED',blue:'BLUE',green:'GREEN',yellow:'YELLOW',wild:'WILD'};
+const COLOR_HEX = {red:'#e63946',blue:'#4a9cd4',green:'#2ecc71',yellow:'#f39c12',wild:'#ffffff'};
+const CARD_SYMBOLS = {
+  '0':'0','1':'1','2':'2','3':'3','4':'4','5':'5','6':'6','7':'7','8':'8','9':'9',
+  'skip':'⊘','reverse':'⇄','draw2':'+2','wild':'★','wild_draw4':'+4'
+};
+const DRAW_STACK_MAX_VISIBLE = 8;
+
+let state = null;
+let ws = null;
+let credentials = null;
+let previousPhase = null;
+let previousColor = null;
+let pendingDeal = false;
+let selectedDifficulty = 'hard';
+
+const $ = (id) => document.getElementById(id);
+
+function setStatus(text){ $('status-text').textContent = text || ''; }
+function setConnection(online){
+  const chip = $('connection-chip');
+  chip.textContent = online ? 'online' : 'offline';
+  chip.className = online ? 'online' : 'offline';
+}
+function sanitizeRoomCode(value){ return (value || '').trim().toUpperCase().replace(/[^A-Z0-9]/g,'').slice(0,5); }
+function getName(){ return ($('name-input').value || 'Player').trim() || 'Player'; }
+
+async function createRoom(){
+  setStatus('Creating room...');
+  const payload = {
+    name: getName(),
+    totalPlayers: clamp(parseInt($('total-players-input').value || '3',10),3,15),
+    botDifficulty: selectedDifficulty,
+    botJumpIn: $('bot-jump-input').checked
+  };
+  const res = await fetch('/api/rooms', {
+    method:'POST',
+    headers:{'Content-Type':'application/json'},
+    body:JSON.stringify(payload)
+  });
+  if(!res.ok){ setStatus(await responseText(res)); return; }
+  credentials = await res.json();
+  $('room-input').value = credentials.roomCode;
+  connectSocket();
+}
+
+async function joinRoom(){
+  const code = sanitizeRoomCode($('room-input').value);
+  if(code.length !== 5){ setStatus('Enter a 5 character room code.'); return; }
+  setStatus('Joining room...');
+  const res = await fetch(`/api/rooms/${code}/join`, {
+    method:'POST',
+    headers:{'Content-Type':'application/json'},
+    body:JSON.stringify({name:getName()})
+  });
+  if(!res.ok){ setStatus(await responseText(res)); return; }
+  credentials = await res.json();
+  connectSocket();
+}
+
+async function responseText(res){
+  try{
+    const data = await res.json();
+    return data.detail || data.message || res.statusText;
+  }catch{
+    return res.statusText;
+  }
+}
+
+function connectSocket(){
+  if(ws) ws.close();
+  const proto = location.protocol === 'https:' ? 'wss' : 'ws';
+  const url = `${proto}://${location.host}/ws/${credentials.roomCode}?playerId=${encodeURIComponent(credentials.playerId)}&token=${encodeURIComponent(credentials.token)}`;
+  ws = new WebSocket(url);
+  ws.onopen = () => { setConnection(true); setStatus('Connected.'); };
+  ws.onclose = () => { setConnection(false); setStatus('Connection closed. Refresh or rejoin with your room code.'); };
+  ws.onerror = () => setStatus('Connection error.');
+  ws.onmessage = (message) => {
+    const payload = JSON.parse(message.data);
+    if(payload.type === 'snapshot') handleSnapshot(payload.state);
+    if(payload.type === 'event') handleEvent(payload.event);
+    if(payload.type === 'error') setStatus(payload.message || payload.code || 'Error');
+  };
+}
+
+function send(type,payload={}){
+  if(!ws || ws.readyState !== WebSocket.OPEN){ setStatus('Socket is not connected.'); return; }
+  ws.send(JSON.stringify({type,payload}));
+}
+
+function handleEvent(event){
+  if(!event) return;
+  if(event.type === 'card_played'){
+    animatePlayedCard(event);
+    const name = event.playerName || 'Player';
+    showToast(`${name}${event.jumpIn ? ' jumped in' : ' played'}`,'ai-turn');
+    if(event.chosenColor) setTimeout(()=>triggerColorWash(event.chosenColor,event.playerId),180);
+  }
+  if(event.type === 'cards_drawn'){
+    animateDrawEvent(event);
+    showToast(`${event.playerName || 'Player'} drew ${event.count}`,'ai-turn');
+  }
+  if(event.type === 'color_changed'){
+    triggerColorWash(event.color,event.playerId);
+    showToast(`${event.playerName || 'Player'} chose ${COLOR_NAMES[event.color]}`,'player-turn');
+  }
+  if(event.type === 'uno_called'){
+    showToast(`${event.playerName || 'Player'}: UNO!`,'player-turn');
+    const anchor = getPlayerAnchor(event.playerId);
+    spawnParticleBurst(anchor.left + anchor.width/2, anchor.top + anchor.height/2, '#f39c12');
+  }
+  if(event.type === 'game_started'){
+    pendingDeal = true;
+  }
+  if(['bot_added','bot_removed','player_joined','player_connected','player_disconnected','room_options_changed'].includes(event.type)){
+    setStatus('');
+  }
+}
+
+function handleSnapshot(nextState){
+  previousPhase = state ? state.phase : null;
+  state = nextState;
+  renderApp();
+  if((previousPhase === 'lobby' && state.phase === 'playing') || pendingDeal){
+    pendingDeal = false;
+    setTimeout(animateDeal,80);
+  }
+}
+
+function renderApp(){
+  if(!state) return;
+  if(state.phase === 'lobby'){
+    $('start-screen').style.display = 'flex';
+    $('start-screen').style.opacity = '1';
+    $('start-screen').classList.add('connected');
+    $('connected-panel').classList.remove('hidden');
+    $('game-board').classList.remove('active');
+    $('win-screen').classList.remove('show');
+    renderLobby();
+    return;
+  }
+  $('start-screen').style.display = 'none';
+  $('game-board').classList.add('active');
+  renderAll();
+  if(state.phase === 'ended') showWinScreen();
+  else $('win-screen').classList.remove('show');
+}
+
+function renderLobby(){
+  $('room-code').textContent = state.roomCode;
+  const isHost = state.myPlayerId === state.hostPlayerId;
+  $('host-options').style.display = isHost ? 'flex' : 'none';
+  $('start-btn').style.display = isHost ? 'block' : 'none';
+  $('start-btn').disabled = !isHost || state.players.length < 3;
+  $('total-players-input').value = state.settings.totalPlayers;
+  $('bot-jump-input').checked = !!state.settings.botJumpIn;
+  selectedDifficulty = state.settings.botDifficulty;
+  document.querySelectorAll('.difficulty-btns button').forEach(btn=>{
+    btn.classList.toggle('active', btn.dataset.diff === selectedDifficulty);
+  });
+  $('add-bot-btn').disabled = state.players.length >= state.settings.totalPlayers;
+  $('remove-bot-btn').disabled = !state.players.some(p=>p.isBot);
+
+  const list = $('player-list');
+  list.innerHTML = '';
+  state.players.forEach(player=>{
+    const row = document.createElement('div');
+    row.className = 'lobby-player';
+    const left = document.createElement('span');
+    left.textContent = `${player.name}${player.connected || player.isBot ? '' : ' (offline)'}`;
+    const right = document.createElement('span');
+    right.innerHTML = [
+      player.id === state.hostPlayerId ? '<span class="pill host">Host</span>' : '',
+      player.isBot ? '<span class="pill bot">Bot</span>' : '',
+      player.id === state.myPlayerId ? '<span class="pill">You</span>' : ''
+    ].join(' ');
+    row.appendChild(left);
+    row.appendChild(right);
+    list.appendChild(row);
+  });
+}
+
+function renderAll(){
+  renderAI();
+  renderPlayerHand();
+  renderDrawPile();
+  renderDiscard();
+  renderColorBadge();
+  renderDirection();
+  renderTurnBadge();
+  renderScores();
+  renderColorSelector();
+}
+
+function getMe(){
+  return state?.players.find(p=>p.id === state.myPlayerId);
+}
+function getPlayer(id){
+  return state?.players.find(p=>p.id === id);
+}
+function playerDomId(id){
+  return `player-${String(id).replace(/[^a-zA-Z0-9_-]/g,'_')}`;
+}
+function isMyTurn(){
+  return !!state && state.currentPlayerId === state.myPlayerId;
+}
+function isAwaitingMyColor(){
+  return !!state && state.awaitingColorPlayerId === state.myPlayerId;
+}
+
+function buildCardFront(card){
+  const sym = CARD_SYMBOLS[card.value] || card.value;
+  return `
+    <span class="corner-pip tl">${sym}</span>
+    <div class="card-center"><span class="big-symbol">${sym}</span></div>
+    <span class="corner-pip br">${sym}</span>`;
+}
+
+function buildCardEl(card){
+  const el = document.createElement('div');
+  el.className = `card ${card.color}`;
+  el.dataset.cardId = card.id || '';
+  el.innerHTML = `
+    <div class="card-inner">
+      <div class="card-front">${buildCardFront(card)}</div>
+      <div class="card-back"></div>
+    </div>`;
+  return el;
+}
+
+function buildCardBackMini(){
+  const el = document.createElement('div');
+  el.className = 'card-back-mini';
+  return el;
+}
+
+function getFanLayout(idx,total,spread=24,lift=10){
+  const fanAngle = total > 1 ? (idx/(total-1))*spread - spread/2 : 0;
+  const fanY = total > 1 ? Math.abs(Math.sin(idx/(total-1)*Math.PI))*(-lift) : 0;
+  return {fanAngle,fanY,baseTransform:`rotateZ(${fanAngle}deg) translateY(${fanY}px)`};
+}
+
+function getAIHandScale(){
+  if(window.innerWidth < 480) return 0.36;
+  if(window.innerWidth < 768) return 0.42;
+  return state && state.players.length > 10 ? 0.42 : 0.5;
+}
+
+function renderAIHandRow(handRow,totalCards){
+  handRow.innerHTML = '';
+  if(totalCards === 0){
+    handRow.innerHTML = '<span style="font-size:11px;color:var(--text-muted)">EMPTY</span>';
+    return;
+  }
+  const visible = totalCards;
+  const aiScale = getAIHandScale();
+  const zoneWidth = parseFloat(getComputedStyle(document.documentElement).getPropertyValue('--ai-hand-zone')) || 220;
+  const baseCardWidth = parseFloat(getComputedStyle(document.documentElement).getPropertyValue('--card-w')) || 76;
+  const displayWidth = baseCardWidth * aiScale;
+  const fixedStep = Math.max(12, displayWidth * 0.56);
+  const step = visible <= 6 ? fixedStep : Math.max(5, Math.min(fixedStep, (zoneWidth-displayWidth)/Math.max(visible-1,1)));
+  const overlap = Math.round(step - baseCardWidth);
+  handRow.style.setProperty('--ai-card-scale', String(aiScale));
+  for(let idx=0; idx<visible; idx++){
+    const slot = document.createElement('div');
+    slot.className = 'ai-card-slot';
+    slot.dataset.idx = idx;
+    const spread = visible <= 6 ? 18 : Math.max(8,18-(visible-6)*0.8);
+    const {baseTransform} = getFanLayout(idx,visible,spread,6);
+    slot.dataset.baseTransform = baseTransform;
+    slot.style.transform = baseTransform;
+    if(idx > 0) slot.style.marginLeft = `${overlap}px`;
+    const card = buildCardEl({id:`back_${idx}`,color:'blue',value:'0'});
+    card.classList.add('flipped');
+    slot.appendChild(card);
+    handRow.appendChild(slot);
+  }
+}
+
+function renderAI(){
+  const row = $('ai-row');
+  row.innerHTML = '';
+  row.classList.toggle('many-opponents', state.players.length > 8);
+  state.players.filter(p=>p.id !== state.myPlayerId).forEach(player=>{
+    const opp = document.createElement('div');
+    opp.className = 'ai-opponent' + (state.currentPlayerId === player.id ? ' active-ai' : '');
+    opp.id = playerDomId(player.id);
+
+    const label = document.createElement('div');
+    label.className = 'ai-label-row' + (state.currentPlayerId === player.id ? ' active' : '');
+    label.innerHTML = `<span class="active-dot"></span><span class="ai-name">${escapeHtml(player.name)}</span>`;
+
+    const count = document.createElement('div');
+    count.className = 'ai-card-count';
+    count.textContent = player.rank ? placementLabel(player.rank) : `${player.handCount} cards`;
+
+    const hand = document.createElement('div');
+    hand.className = 'ai-hand-row';
+    renderAIHandRow(hand, player.handCount);
+    if(player.rank){
+      const badge = document.createElement('div');
+      badge.className = `placement-badge ${placementClass(player.rank)}`;
+      badge.textContent = placementLabel(player.rank);
+      hand.appendChild(badge);
+    }
+    opp.appendChild(label);
+    opp.appendChild(count);
+    opp.appendChild(hand);
+    row.appendChild(opp);
+  });
+}
+
+function renderPlayerHand(){
+  const me = getMe();
+  const container = $('player-hand');
+  const playerArea = $('player-area');
+  playerArea.querySelector('.player-placement')?.remove();
+  container.innerHTML = '';
+  if(!me) return;
+  const legal = new Set(state.legalCardIds || []);
+  const total = me.hand ? me.hand.length : 0;
+  (me.hand || []).forEach((card,idx)=>{
+    const slot = document.createElement('div');
+    slot.className = 'card-slot';
+    slot.dataset.idx = idx;
+    slot.dataset.cardId = card.id;
+    const {baseTransform} = getFanLayout(idx,total,24,10);
+    slot.style.transform = baseTransform;
+    if(idx > 0) slot.style.marginLeft = window.innerWidth < 480 ? '-20px' : window.innerWidth < 768 ? '-24px' : '-32px';
+    const el = buildCardEl(card);
+    if(legal.has(card.id)) el.classList.add('playable-card');
+    slot.appendChild(el);
+    slot.addEventListener('click',()=>activateCard(card,el));
+    container.appendChild(slot);
+  });
+  if(me.rank){
+    const badge = document.createElement('div');
+    badge.className = `placement-badge player-placement ${placementClass(me.rank)}`;
+    badge.textContent = placementLabel(me.rank);
+    playerArea.appendChild(badge);
+  }
+  $('uno-call-btn').classList.toggle('visible', total === 1 && !me.saidUno && state.phase === 'playing');
+}
+
+function activateCard(card,el){
+  const legal = new Set(state.legalCardIds || []);
+  if(!legal.has(card.id)){
+    el.classList.remove('shake-anim');
+    void el.offsetWidth;
+    el.classList.add('shake-anim');
+    setTimeout(()=>el.classList.remove('shake-anim'),400);
+    return;
+  }
+  send('play_card',{
+    cardId:card.id,
+    expectedTopCardId:state.topCard?.id,
+    expectedVersion:state.version
+  });
+}
+
+function renderDrawPile(){
+  const stack = $('draw-stack');
+  const show = Math.min(state.deckCount || 0, DRAW_STACK_MAX_VISIBLE);
+  stack.innerHTML = '';
+  for(let i=0;i<show;i++){
+    const card = buildCardBackMini();
+    card.style.left = `${i*3}px`;
+    card.style.top = `${-i*2.5}px`;
+    card.style.opacity = String(Math.max(0.45,1-i*0.12));
+    card.style.zIndex = String(show-i);
+    stack.appendChild(card);
+  }
+  stack.dataset.label = state ? `${state.deckCount}` : '';
+  const zone = $('draw-pile');
+  let badge = zone.querySelector('.pending-badge');
+  if(state.pendingDraw > 0){
+    if(!badge){
+      badge = document.createElement('div');
+      badge.className = 'pending-badge';
+      zone.appendChild(badge);
+    }
+    badge.textContent = `+${state.pendingDraw}`;
+    badge.style.opacity = '1';
+  }else if(badge){
+    badge.remove();
+  }
+}
+
+function renderDiscard(){
+  const scatter = $('discard-scatter');
+  const pile = state.discardPile || [];
+  scatter.innerHTML = '';
+  pile.forEach((card,idx)=>{
+    const total = pile.length;
+    const age = total - 1 - idx;
+    const el = buildCardEl(card);
+    el.style.position = 'absolute';
+    el.style.left = '50%';
+    el.style.top = '50%';
+    const ox = (seededRand(idx*3+1)-0.5) * Math.min(70,30+age*5) * 2;
+    const oy = (seededRand(idx*3+2)-0.5) * Math.min(70,30+age*5) * 2;
+    const rot = (seededRand(idx*3+3)-0.5) * 40;
+    el.style.transform = `translate(calc(-50% + ${ox}px), calc(-50% + ${oy}px)) rotate(${rot}deg)`;
+    el.style.filter = `brightness(${Math.max(0.3,1-age*0.07)})`;
+    el.style.zIndex = idx === total-1 ? 99 : idx;
+    if(idx === total-1) el.classList.add('discard-land-anim');
+    scatter.appendChild(el);
+  });
+}
+
+function renderColorBadge(){
+  const color = state.currentColor || 'red';
+  const dot = $('color-dot');
+  const txt = $('color-text');
+  const badge = $('color-badge');
+  const hex = COLOR_HEX[color] || '#fff';
+  dot.style.background = hex;
+  dot.style.color = hex;
+  txt.textContent = COLOR_NAMES[color] || color.toUpperCase();
+  badge.style.borderColor = `${hex}55`;
+  badge.style.boxShadow = `0 0 24px ${hex}22`;
+  if(previousColor !== null && previousColor !== color){
+    badge.classList.remove('color-ripple');
+    void badge.offsetWidth;
+    badge.classList.add('color-ripple');
+    setTimeout(()=>badge.classList.remove('color-ripple'),700);
+  }
+  previousColor = color;
+}
+
+function renderDirection(){
+  const arrow = $('ring-arrow');
+  const text = $('ring-text');
+  arrow.className = `ring-arrow ${state.direction === -1 ? 'reversed' : 'clockwise'}`;
+  arrow.textContent = state.direction === -1 ? '<-' : '->';
+  const next = state.currentPlayerId ? getPlayer(state.currentPlayerId) : null;
+  text.textContent = next ? `${state.direction === -1 ? 'Counter' : 'Clockwise'} / ${next.name}` : 'Finished';
+}
+
+function renderTurnBadge(){
+  const badge = $('turn-badge');
+  const current = state.currentPlayerId ? getPlayer(state.currentPlayerId) : null;
+  if(state.awaitingColorPlayerId){
+    const chooser = getPlayer(state.awaitingColorPlayerId);
+    badge.textContent = chooser?.id === state.myPlayerId ? 'Choose a color' : `${chooser?.name || 'Player'} is choosing color`;
+    badge.className = chooser?.id === state.myPlayerId ? 'your-turn' : '';
+    return;
+  }
+  if(isMyTurn()){
+    badge.textContent = state.canDraw ? 'Your turn - play or draw' : 'Your turn';
+    badge.className = 'your-turn';
+  }else{
+    badge.textContent = current ? `${current.name} is playing...` : 'Waiting';
+    badge.className = '';
+  }
+}
+
+function renderScores(){
+  $('score-row').innerHTML = '';
+}
+
+function renderColorSelector(){
+  const selector = $('color-selector');
+  selector.classList.toggle('show', isAwaitingMyColor());
+}
+
+function showToast(msg,cls){
+  const toast = $('turn-toast');
+  toast.textContent = msg;
+  toast.className = `show ${cls || ''}`;
+  clearTimeout(toast._tid);
+  toast._tid = setTimeout(()=>toast.classList.remove('show'),1800);
+}
+
+function showWinScreen(){
+  const firstId = state.finishOrder[0];
+  const winner = getPlayer(firstId) || state.players.find(p=>p.rank === 1);
+  $('winner-name').textContent = `${winner ? winner.name : 'Winner'} Takes 1st!`;
+  const scores = $('win-scores');
+  scores.innerHTML = '';
+  state.players
+    .filter(p=>p.rank)
+    .sort((a,b)=>a.rank-b.rank)
+    .forEach(player=>{
+      const row = document.createElement('div');
+      row.className = 'win-score-item' + (player.rank === 1 ? ' winner-highlight' : '');
+      row.textContent = `${placementLabel(player.rank)} - ${player.name}`;
+      scores.appendChild(row);
+    });
+  $('win-screen').classList.add('show');
+  spawnConfetti();
+}
+
+function animateDeal(){
+  document.querySelectorAll('.ai-hand-row .ai-card-slot,#player-hand .card-slot').forEach((slot,i)=>{
+    const base = slot.style.transform || 'translateY(0px)';
+    slot.style.transition = 'none';
+    slot.style.opacity = '0';
+    slot.style.transform = `translateY(-40px) ${base}`;
+    setTimeout(()=>{
+      slot.style.transition = 'opacity 0.25s, transform 0.3s cubic-bezier(0.34,1.3,0.64,1)';
+      slot.style.opacity = '1';
+      slot.style.transform = base;
+    },80+i*34);
+  });
+}
+
+function animatePlayedCard(event){
+  const card = event.card;
+  const from = getCardSourceRect(event.playerId, card.id);
+  const to = getDiscardCenterAnchor();
+  animateCardFlight(card,from,to,true);
+}
+
+function animateDrawEvent(event){
+  const from = $('draw-pile').getBoundingClientRect();
+  const to = getPlayerAnchor(event.playerId);
+  const cards = event.cards || Array.from({length:event.count || 1},(_,idx)=>({id:`draw_${idx}`,color:'blue',value:'0',back:true}));
+  cards.forEach((card,idx)=>{
+    setTimeout(()=>animateCardFlight(card,from,to,!card.back && event.playerId === state?.myPlayerId),idx*90);
+  });
+}
+
+function animateCardFlight(card,fromRect,toRect,faceUp=true){
+  const flying = buildCardEl(card || {id:'fly',color:'blue',value:'0'});
+  flying.classList.add('flying-card');
+  if(!faceUp) flying.classList.add('flipped');
+  document.body.appendChild(flying);
+  const start = rectCenterPosition(fromRect);
+  const end = rectCenterPosition(toRect);
+  flying.style.left = `${start.left}px`;
+  flying.style.top = `${start.top}px`;
+  flying.style.transform = 'scale(0.92) rotate(-8deg)';
+  flying.style.opacity = '0.96';
+  requestAnimationFrame(()=>{
+    flying.style.left = `${end.left}px`;
+    flying.style.top = `${end.top}px`;
+    flying.style.transform = 'scale(0.84) rotate(10deg)';
+    flying.style.opacity = '0.82';
+  });
+  setTimeout(()=>flying.remove(),520);
+}
+
+function getCardSourceRect(playerId,cardId){
+  if(playerId === state?.myPlayerId){
+    const slot = document.querySelector(`#player-hand .card-slot[data-card-id="${cssEscape(cardId)}"]`);
+    if(slot) return slot.getBoundingClientRect();
+  }
+  return getPlayerAnchor(playerId);
+}
+
+function getPlayerAnchor(playerId){
+  const el = playerId === state?.myPlayerId ? $('player-area') : document.getElementById(playerDomId(playerId));
+  if(el) return el.getBoundingClientRect();
+  return {left:window.innerWidth/2,top:window.innerHeight/2,width:1,height:1};
+}
+
+function getDiscardCenterAnchor(){
+  const dz = $('discard-zone');
+  return dz ? dz.getBoundingClientRect() : {left:window.innerWidth/2,top:window.innerHeight/2,width:1,height:1};
+}
+
+function rectCenterPosition(rect){
+  const width = parseFloat(getComputedStyle(document.documentElement).getPropertyValue('--card-w')) || 76;
+  const height = parseFloat(getComputedStyle(document.documentElement).getPropertyValue('--card-h')) || 114;
+  return {
+    left: rect.left + rect.width/2 - width/2,
+    top: rect.top + rect.height/2 - height/2
+  };
+}
+
+function triggerColorWash(color,playerId){
+  const wash = $('color-wash');
+  const hex = COLOR_HEX[color] || '#ffffff';
+  let rect = playerId ? getPlayerAnchor(playerId) : {left:window.innerWidth/2,top:window.innerHeight/2,width:1,height:1};
+  const cx = `${rect.left + rect.width/2}px`;
+  const cy = `${rect.top + rect.height/2}px`;
+  wash.style.setProperty('--wash-x',cx);
+  wash.style.setProperty('--wash-y',cy);
+  wash.style.setProperty('--wash-color',hex);
+  wash.classList.remove('active');
+  void wash.offsetWidth;
+  wash.classList.add('active');
+  setTimeout(()=>wash.classList.remove('active'),900);
+}
+
+function spawnParticleBurst(x,y,color){
+  for(let i=0;i<16;i++){
+    const p = document.createElement('div');
+    p.className = 'particle';
+    const angle = (i/16)*Math.PI*2;
+    const dist = 50 + Math.random()*70;
+    const size = 4 + Math.random()*6;
+    p.style.cssText = `left:${x}px;top:${y}px;width:${size}px;height:${size}px;background:${color};--px:${Math.cos(angle)*dist}px;--py:${Math.sin(angle)*dist}px;`;
+    document.body.appendChild(p);
+    setTimeout(()=>p.remove(),800);
+  }
+}
+
+function spawnConfetti(){
+  const c = $('confetti-container');
+  if(c.children.length) return;
+  const colors = ['#e63946','#4a9cd4','#2ecc71','#f39c12','#9b59b6','#e91e63','#fff'];
+  for(let i=0;i<80;i++){
+    const p = document.createElement('div');
+    p.className = 'confetti-piece';
+    p.style.cssText = `left:${Math.random()*100}vw;background:${colors[Math.floor(Math.random()*colors.length)]};width:${6+Math.random()*10}px;height:${6+Math.random()*10}px;animation-duration:${2+Math.random()*2}s;animation-delay:${Math.random()*2}s;`;
+    c.appendChild(p);
+  }
+}
+
+function seededRand(seed){
+  const x = Math.sin(seed*9301+49297)*233280;
+  return x - Math.floor(x);
+}
+function clamp(value,min,max){ return Math.min(max,Math.max(min,value)); }
+function placementLabel(rank){
+  if(rank === 1) return 'Gold Crown';
+  if(rank === 2) return 'Silver Crown';
+  if(rank === 3) return 'Bronze Crown';
+  return `${rank}th`;
+}
+function placementClass(rank){
+  if(rank === 1) return 'gold';
+  if(rank === 2) return 'silver';
+  if(rank === 3) return 'bronze';
+  return 'place';
+}
+function escapeHtml(text){
+  return String(text).replace(/[&<>"']/g, ch => ({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;',"'":'&#039;'}[ch]));
+}
+function cssEscape(value){
+  return window.CSS && CSS.escape ? CSS.escape(value) : String(value).replace(/"/g,'\\"');
+}
+
+$('create-room-btn').addEventListener('click',createRoom);
+$('join-room-btn').addEventListener('click',joinRoom);
+$('room-input').addEventListener('input',e=>{ e.target.value = sanitizeRoomCode(e.target.value); });
+$('copy-room-btn').addEventListener('click',async()=>{
+  if(!state) return;
+  await navigator.clipboard?.writeText(state.roomCode);
+  setStatus('Room code copied.');
+});
+$('start-btn').addEventListener('click',()=>send('start_game'));
+$('add-bot-btn').addEventListener('click',()=>send('add_bot'));
+$('remove-bot-btn').addEventListener('click',()=>send('remove_bot'));
+$('total-players-input').addEventListener('change',()=>{
+  send('set_room_options',{
+    totalPlayers:clamp(parseInt($('total-players-input').value || '3',10),3,15),
+    botDifficulty:selectedDifficulty,
+    botJumpIn:$('bot-jump-input').checked
+  });
+});
+$('bot-jump-input').addEventListener('change',()=>{
+  send('set_room_options',{
+    totalPlayers:clamp(parseInt($('total-players-input').value || '3',10),3,15),
+    botDifficulty:selectedDifficulty,
+    botJumpIn:$('bot-jump-input').checked
+  });
+});
+document.querySelectorAll('.difficulty-btns button').forEach(btn=>{
+  btn.addEventListener('click',()=>{
+    selectedDifficulty = btn.dataset.diff;
+    document.querySelectorAll('.difficulty-btns button').forEach(b=>b.classList.remove('active'));
+    btn.classList.add('active');
+    if(state && state.phase === 'lobby'){
+      send('set_room_options',{
+        totalPlayers:clamp(parseInt($('total-players-input').value || '3',10),3,15),
+        botDifficulty:selectedDifficulty,
+        botJumpIn:$('bot-jump-input').checked
+      });
+    }
+  });
+});
+$('draw-pile').addEventListener('click',()=>{ if(state?.canDraw) send('draw'); });
+$('uno-call-btn').addEventListener('click',()=>send('call_uno'));
+document.querySelectorAll('#color-selector .sel-opt').forEach(opt=>{
+  opt.addEventListener('click',()=>send('choose_color',{color:opt.dataset.color}));
+});
+$('play-again-btn').addEventListener('click',()=>send('restart'));
+document.addEventListener('keydown',event=>{
+  if(event.key.toLowerCase() === 'u') send('call_uno');
+  if(event.key === ' ' && state?.canDraw){ event.preventDefault(); send('draw'); }
+});
+window.addEventListener('resize',()=>{ if(state?.phase === 'playing') renderAll(); });
+
+window.render_game_to_text = () => JSON.stringify({
+  roomCode: state?.roomCode,
+  phase: state?.phase,
+  myPlayerId: state?.myPlayerId,
+  currentPlayerId: state?.currentPlayerId,
+  direction: state?.direction,
+  currentColor: state?.currentColor,
+  pendingDraw: state?.pendingDraw,
+  awaitingColorPlayerId: state?.awaitingColorPlayerId,
+  topCard: state?.topCard,
+  deckCount: state?.deckCount,
+  players: (state?.players || []).map(p=>({
+    id:p.id,name:p.name,isBot:p.isBot,handCount:p.handCount,finished:p.finished,rank:p.rank,
+    isMe:p.id === state?.myPlayerId
+  })),
+  myHand: getMe()?.hand || [],
+  legalCardIds: state?.legalCardIds || [],
+  canDraw: !!state?.canDraw
+});
+window.advanceTime = () => { if(state) renderAll(); };
+
+$('name-input').value = `Player ${Math.floor(100 + Math.random()*900)}`;
+setConnection(false);
+</script>
+</body>
+</html>

tests/conftest.py

@@ -0,0 +1,7 @@
+import sys
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[1]
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))

tests/test_rules.py

@@ -0,0 +1,124 @@
+import pytest
+
+from app import Card, GameError, Player, Room, create_deck_for_tests
+
+
+def make_room(player_count=3):
+    players = [
+        Player(id=f"p{i}", name=f"P{i}", token=f"t{i}", connected=True)
+        for i in range(player_count)
+    ]
+    return Room(code="TEST", host_player_id="p0", total_players=player_count, players=players)
+
+
+def test_deck_has_108_cards():
+    deck = create_deck_for_tests()
+    assert len(deck) == 108
+    assert sum(1 for c in deck if c.color == "wild" and c.value == "wild") == 4
+    assert sum(1 for c in deck if c.color == "wild" and c.value == "wild_draw4") == 4
+
+
+def test_start_game_with_15_players_is_legal():
+    room = make_room(15)
+    event = room.start_game("p0")
+    assert event["type"] == "game_started"
+    assert room.phase == "playing"
+    assert all(len(p.hand) == 7 for p in room.players)
+    assert len(room.discard_pile) == 1
+    assert room.discard_pile[-1].color != "wild"
+    assert len(room.deck) == 2
+
+
+def test_reshuffle_keeps_top_discard():
+    room = make_room()
+    top = Card("top", "red", "5")
+    old = Card("old", "blue", "7")
+    room.discard_pile = [old, top]
+    room.deck = []
+    room.reshuffle_deck()
+    assert room.discard_pile == [top]
+    assert room.deck == [old]
+
+
+def test_normal_play_rules_and_draw_stacking():
+    room = make_room()
+    room.phase = "playing"
+    room.current_player_id = "p0"
+    room.current_color = "red"
+    room.discard_pile = [Card("top", "red", "3")]
+    assert room.is_valid_play(Card("same_color", "red", "9"))
+    assert room.is_valid_play(Card("same_value", "blue", "3"))
+    assert room.is_valid_play(Card("wild", "wild", "wild"))
+    assert not room.is_valid_play(Card("bad", "green", "8"))
+
+    room.pending_draw = 2
+    room.discard_pile = [Card("draw_top", "red", "draw2")]
+    assert room.is_valid_play(Card("stack2", "blue", "draw2"))
+    assert room.is_valid_play(Card("stack4", "wild", "wild_draw4"))
+    assert not room.is_valid_play(Card("number", "red", "3"))
+
+
+def test_strict_jump_in_requires_color_and_value():
+    room = make_room()
+    room.phase = "playing"
+    room.discard_pile = [Card("top", "red", "7")]
+    assert room.is_strict_jump_in(Card("same", "red", "7"))
+    assert not room.is_strict_jump_in(Card("value_only", "blue", "7"))
+    assert not room.is_strict_jump_in(Card("color_only", "red", "8"))
+
+    room.discard_pile = [Card("wild_top", "wild", "wild_draw4")]
+    assert room.is_strict_jump_in(Card("wild_same", "wild", "wild_draw4"))
+    assert not room.is_strict_jump_in(Card("wild_other", "wild", "wild"))
+
+
+def test_jump_in_interrupts_and_continues_from_jumper():
+    room = make_room(4)
+    room.phase = "playing"
+    room.current_player_id = "p0"
+    room.current_color = "red"
+    room.discard_pile = [Card("top", "red", "5")]
+    room.players[2].hand = [Card("jump", "red", "5")]
+    room.play_card("p2", "jump", expected_top_card_id="top", expected_version=0)
+    assert room.current_player_id == "p3"
+    assert room.discard_pile[-1].id == "jump"
+
+
+def test_jump_in_with_reverse_uses_jumper_as_turn_source():
+    room = make_room(4)
+    room.phase = "playing"
+    room.current_player_id = "p0"
+    room.direction = 1
+    room.current_color = "green"
+    room.discard_pile = [Card("top", "green", "reverse")]
+    room.players[2].hand = [Card("jump", "green", "reverse")]
+    room.play_card("p2", "jump", expected_top_card_id="top", expected_version=0)
+    assert room.direction == -1
+    assert room.current_player_id == "p1"
+
+
+def test_second_simultaneous_jump_in_revalidates_top_card():
+    room = make_room(4)
+    room.phase = "playing"
+    room.current_player_id = "p0"
+    room.current_color = "red"
+    room.discard_pile = [Card("top", "red", "5")]
+    room.players[2].hand = [Card("jump1", "red", "5")]
+    room.players[3].hand = [Card("jump2", "red", "5")]
+    room.play_card("p2", "jump1", expected_top_card_id="top", expected_version=0)
+    with pytest.raises(GameError):
+        room.version += 1
+        room.play_card("p3", "jump2", expected_top_card_id="top", expected_version=0)
+
+
+def test_bot_jump_in_revalidation_shape():
+    room = make_room(4)
+    room.players[2].is_bot = True
+    room.phase = "playing"
+    room.current_player_id = "p0"
+    room.current_color = "red"
+    room.discard_pile = [Card("top", "red", "5")]
+    bot_card = Card("bot_jump", "red", "5")
+    room.players[2].hand = [bot_card]
+    assert any(room.is_strict_jump_in(card) for card in room.players[2].hand)
+    room.discard_pile.append(Card("changed", "blue", "9"))
+    assert not any(room.is_strict_jump_in(card) for card in room.players[2].hand)

tests/test_websocket.py

@@ -0,0 +1,126 @@
+from fastapi.testclient import TestClient
+
+from app import app, rooms
+
+
+def setup_function():
+    rooms.clear()
+
+
+def create_room(client, name="Host", total=3):
+    res = client.post(
+        "/api/rooms",
+        json={"name": name, "totalPlayers": total, "botDifficulty": "hard", "botJumpIn": True},
+    )
+    assert res.status_code == 200
+    return res.json()
+
+
+def join_room(client, code, name):
+    res = client.post(f"/api/rooms/{code}/join", json={"name": name})
+    assert res.status_code == 200
+    return res.json()
+
+
+def ws_url(creds):
+    return f"/ws/{creds['roomCode']}?playerId={creds['playerId']}&token={creds['token']}"
+
+
+def read_until_snapshot(ws):
+    while True:
+        msg = ws.receive_json()
+        if msg["type"] == "snapshot":
+            return msg["state"]
+
+
+def read_until_snapshot_matching(ws, predicate):
+    while True:
+        state = read_until_snapshot(ws)
+        if predicate(state):
+            return state
+
+
+def test_room_create_join_add_bot_and_privacy():
+    with TestClient(app) as client:
+        host = create_room(client, total=4)
+        p2 = join_room(client, host["roomCode"], "P2")
+        with client.websocket_connect(ws_url(host)) as ws1, client.websocket_connect(ws_url(p2)) as ws2:
+            s1 = read_until_snapshot(ws1)
+            s2 = read_until_snapshot(ws2)
+            assert s1["roomCode"] == host["roomCode"]
+            assert s2["roomCode"] == host["roomCode"]
+
+            ws1.send_json({"type": "add_bot", "payload": {}})
+            s1 = read_until_snapshot_matching(ws1, lambda state: any(p["isBot"] for p in state["players"]))
+            assert any(p["isBot"] for p in s1["players"])
+
+            ws1.send_json({"type": "add_bot", "payload": {}})
+            s1 = read_until_snapshot_matching(ws1, lambda state: len(state["players"]) == 4)
+            assert len(s1["players"]) == 4
+
+            ws1.send_json({"type": "start_game", "payload": {}})
+            s1 = read_until_snapshot_matching(ws1, lambda state: state["phase"] == "playing")
+            s2 = read_until_snapshot_matching(ws2, lambda state: state["phase"] == "playing")
+            assert s1["phase"] == "playing"
+            my1 = next(p for p in s1["players"] if p["id"] == s1["myPlayerId"])
+            other1 = next(p for p in s1["players"] if p["id"] == s2["myPlayerId"])
+            assert "hand" in my1
+            assert "hand" not in other1
+            assert other1["handCount"] == 7
+
+
+def test_non_host_cannot_start_or_change_options():
+    with TestClient(app) as client:
+        host = create_room(client, total=3)
+        p2 = join_room(client, host["roomCode"], "P2")
+        join_room(client, host["roomCode"], "P3")
+        with client.websocket_connect(ws_url(p2)) as ws:
+            read_until_snapshot(ws)
+            ws.send_json({"type": "start_game", "payload": {}})
+            msg = ws.receive_json()
+            assert msg["type"] == "error"
+            assert msg["code"] == "not_host"
+
+
+def test_room_full_and_started_errors():
+    with TestClient(app) as client:
+        host = create_room(client, total=3)
+        join_room(client, host["roomCode"], "P2")
+        join_room(client, host["roomCode"], "P3")
+        full = client.post(f"/api/rooms/{host['roomCode']}/join", json={"name": "P4"})
+        assert full.status_code == 409
+
+        p2 = {
+            "roomCode": host["roomCode"],
+            "playerId": rooms[host["roomCode"]].players[1].id,
+            "token": rooms[host["roomCode"]].players[1].token,
+        }
+        p3 = {
+            "roomCode": host["roomCode"],
+            "playerId": rooms[host["roomCode"]].players[2].id,
+            "token": rooms[host["roomCode"]].players[2].token,
+        }
+        with (
+            client.websocket_connect(ws_url(host)) as ws,
+            client.websocket_connect(ws_url(p2)),
+            client.websocket_connect(ws_url(p3)),
+        ):
+            read_until_snapshot(ws)
+            ws.send_json({"type": "start_game", "payload": {}})
+            read_until_snapshot_matching(ws, lambda state: state["phase"] == "playing")
+        late = client.post(f"/api/rooms/{host['roomCode']}/join", json={"name": "Late"})
+        assert late.status_code == 409
+
+
+def test_bad_room_and_bad_token_errors():
+    with TestClient(app) as client:
+        missing = client.post("/api/rooms/ZZZZZ/join", json={"name": "Nope"})
+        assert missing.status_code == 404
+
+        host = create_room(client, total=3)
+        bad = dict(host)
+        bad["token"] = "wrong"
+        with client.websocket_connect(ws_url(bad)) as ws:
+            msg = ws.receive_json()
+            assert msg["type"] == "error"
+            assert msg["code"] == "bad_token"