ChemGame.py

"""
离子风暴数字版（可玩 MVP）。

当前模块包含：
1) 基于 table.py 的可运行对局引擎
2) Tkinter 桌面中文界面
3) 服务器联机与多人房间加入
"""

from __future__ import annotations

import json
import random
import re
import secrets
import socket
import threading
import time
import tkinter as tk
from collections import Counter, deque
from dataclasses import dataclass, field
from tkinter import messagebox, ttk
from typing import Any, Dict, List, Optional, Tuple

import table as t


Pair = Tuple[str, str]

_SUBSCRIPT_TRANS = str.maketrans("0123456789+-()", "₀₁₂₃₄₅₆₇₈₉₊₋₍₎")
_SUPERSCRIPT_TRANS = str.maketrans("0123456789+-()", "⁰¹²³⁴⁵⁶⁷⁸⁹⁺⁻⁽⁾")

HEARTBEAT_INTERVAL_SECONDS = 1.0
HEARTBEAT_LAG_SECONDS = 3.0
HEARTBEAT_TIMEOUT_SECONDS = 8.0
HEARTBEAT_WATCHDOG_SECONDS = 1.0

_NON_ION_DISPLAY = {
    t.Au: "金",
    t.U: "铀",
    t.Acid: "强酸",
    t.Alk: "强碱",
    t.Enough: "足量",
    t.Imp: "杂质",
    t.Flt: "过滤",
    t.Fde: "褪色",
    t.AW: "洗气",
    t.Dtl: "蒸馏",
    t.AS: "加钠",
    t.Ban: "禁",
    t.Rev: "逆转",
}

_ALL_CARDS_SORTED = sorted(t.initCard.keys(), key=len, reverse=True)
_SILICIC_ACID_PAIR: Pair = (t.H, t.SiO3)
_ACID_REACTIVE_PRECIP_ANIONS = set(t.toG.get(t.H, []) + t.toWE.get(t.H, []) + t.toS.get(t.H, []))


def _format_ion_display(ion: str) -> str:
    out = ion
    out = re.sub(r"_(\d+)", lambda m: m.group(1).translate(_SUBSCRIPT_TRANS), out)
    out = re.sub(r"\^\{([^}]+)\}", lambda m: m.group(1).translate(_SUPERSCRIPT_TRANS), out)
    out = re.sub(
        r"\^([0-9+\-]+)",
        lambda m: m.group(1).translate(_SUPERSCRIPT_TRANS),
        out,
    )
    return out


def _display_card_name(card: str) -> str:
    if card in t.Ion:
        return _format_ion_display(card)
    return _NON_ION_DISPLAY.get(card, card)


def _display_text(text: str) -> str:
    out = text
    for card in _ALL_CARDS_SORTED:
        out = out.replace(card, _display_card_name(card))
    return out


def _counter_to_dict(counter: Counter[str]) -> Dict[str, int]:
    return {k: counter[k] for k in sorted(counter) if counter[k] > 0}


def _pair_counter_to_dict(counter: Counter[Pair]) -> Dict[str, int]:
    items: Dict[str, int] = {}
    for (a, b) in sorted(counter):
        n = counter[(a, b)]
        if n > 0:
            items[f"{a} + {b}"] = n
    return items


def _send_json(sock: socket.socket, payload: Dict[str, Any]) -> None:
    data = json.dumps(payload, ensure_ascii=False) + "\n"
    sock.sendall(data.encode("utf-8"))


def _recv_json_nonblocking(
    sock: socket.socket, buffer: bytes
) -> Tuple[Optional[Dict[str, Any]], bytes, bool]:
    while b"\n" not in buffer:
        try:
            chunk = sock.recv(4096)
        except (socket.timeout, BlockingIOError, InterruptedError):
            return None, buffer, False
        if not chunk:
            return None, buffer, True
        buffer += chunk
    line, buffer = buffer.split(b"\n", 1)
    line = line.strip()
    if not line:
        return None, buffer, False
    try:
        msg = json.loads(line.decode("utf-8"))
    except Exception:
        msg = {"type": "_invalid"}
    return msg, buffer, False


def _parse_host_input(raw: str, default_host: str = "127.0.0.1") -> Tuple[str, Optional[int]]:
    """
    Parse host text entered by user.

    Supported examples:
    - 192.168.1.10
    - 192.168.1.10:5000
    - ws://192.168.1.10
    - http://192.168.1.10:5000/path
    - [::1]:5000
    """
    s = str(raw or "").strip()
    # Normalize common full-width punctuation from Chinese IME.
    s = (
        s.replace("\uFF1A", ":")
        .replace("\uFF0F", "/")
        .replace("\u3002", ".")
        .replace("\uFF0E", ".")
        .replace("\uFF0C", ".")
        .replace("\u3000", " ")
    )
    s = s.strip()
    if not s:
        return default_host, None

    m = re.match(r"^[a-zA-Z][a-zA-Z0-9+.\-]*://(.*)$", s)
    if m:
        s = str(m.group(1) or "").strip()

    if "/" in s:
        s = s.split("/", 1)[0].strip()

    if not s:
        return default_host, None

    host = s
    parsed_port: Optional[int] = None

    if host.startswith("[") and "]" in host:
        end = host.find("]")
        inner = host[1:end].strip()
        rest = host[end + 1 :].strip()
        if rest.startswith(":") and rest[1:].isdigit():
            try:
                parsed_port = int(rest[1:])
            except Exception:
                parsed_port = None
        host = inner or default_host
        return host, parsed_port

    # host:port (IPv4 / hostname only). Plain IPv6 has multiple ':' and is kept as-is.
    if host.count(":") == 1:
        base, tail = host.rsplit(":", 1)
        if tail.isdigit():
            try:
                parsed_port = int(tail)
            except Exception:
                parsed_port = None
            host = base.strip() or default_host

    return host.strip() or default_host, parsed_port


def _normalize_host_input(raw: str, default_host: str = "127.0.0.1") -> str:
    host, _ = _parse_host_input(raw, default_host=default_host)
    return host


def _open_tcp_connection(host: str, port: int, timeout_seconds: float = 5.0) -> socket.socket:
    """
    Open TCP connection with AF_UNSPEC so IPv4/IPv6 host text can both work.
    """
    host_text = _normalize_host_input(host)
    port_num = int(port)
    timeout = max(0.5, float(timeout_seconds))

    try:
        infos = socket.getaddrinfo(host_text, port_num, socket.AF_UNSPEC, socket.SOCK_STREAM)
    except Exception as exc:
        raise ConnectionError(f"无法解析服务器地址: {host_text} ({exc})") from exc

    deadline = time.time() + timeout
    last_exc: Optional[BaseException] = None

    for family, socktype, proto, _canon, sockaddr in infos:
        remain = deadline - time.time()
        if remain <= 0:
            break
        sock = socket.socket(family, socktype, proto)
        try:
            sock.settimeout(min(2.5, remain))
            sock.connect(sockaddr)
            sock.settimeout(0.4)
            return sock
        except Exception as exc:
            last_exc = exc
            try:
                sock.close()
            except Exception:
                pass

    if last_exc is not None:
        raise ConnectionError(f"连接 {host_text}:{port_num} 失败: {last_exc}") from last_exc
    raise TimeoutError(f"连接 {host_text}:{port_num} 超时。")


@dataclass
class PlayerState:
    name: str
    hand: Counter[str] = field(default_factory=Counter)

    @property
    def hand_size(self) -> int:
        return sum(self.hand.values())


class GameEngine:
    def __init__(
        self,
        player_names: List[str],
        initial_hand_size: Optional[int] = None,
        seed: Optional[int] = None,
    ) -> None:
        if len(player_names) < 2:
            raise ValueError("至少需要 2 名玩家。")
        self.players: List[PlayerState] = [PlayerState(name=n) for n in player_names]
        self.deck: List[str] = []
        self.discard: List[str] = []
        self.solution: Counter[str] = Counter()
        self.precipitates: Counter[Pair] = Counter()
        self.gases: Counter[Pair] = Counter()
        self.weak_electrolytes: Counter[Pair] = Counter()
        self.gold_count = 0
        self.uranium_timers: List[int] = []
        self.skip_turns: Counter[int] = Counter()
        self.current_player = 0
        self.direction = 1
        self.actions_left = 1
        self.played_card_this_turn = False
        self.winner: Optional[int] = None
        self.turn_number = 1
        self.log: deque[str] = deque(maxlen=200)
        self.pending_draw_effect: Optional[Dict[str, Any]] = None
        self._pending_draw_effect_seq = 0
        self._rng = random.Random(seed)
        self._build_deck()

        if initial_hand_size is None:
            hand_size = self._default_hand_size(len(self.players))
        else:
            hand_size = int(initial_hand_size)
        if hand_size < 2:
            raise ValueError("初始手牌数必须至少为 2。")
        hand_size = min(10, hand_size)
        for idx in range(len(self.players)):
            self._draw_cards(idx, hand_size)

        self._log(f"对局开始。初始手牌数: {hand_size}。")
        self._log(f"当前玩家: {self.players[self.current_player].name}。")

    @staticmethod
    def _default_hand_size(player_count: int) -> int:
        if player_count == 2:
            return 10
        if player_count <= 4:
            return 7
        return 6

    def _build_deck(self) -> None:
        self.deck.clear()
        for card, count in t.initCard.items():
            self.deck.extend([card] * count)
        self._rng.shuffle(self.deck)

    def _log(self, text: str) -> None:
        self.log.append(text)

    def _next_index(self, idx: Optional[int] = None) -> int:
        if idx is None:
            idx = self.current_player
        return (idx + self.direction) % len(self.players)

    def _prev_index(self, idx: int) -> int:
        return (idx - self.direction) % len(self.players)

    def _direction_hint_text(self) -> str:
        if not self.players:
            return "按座位顺序"
        if self.direction == 1:
            order = list(range(len(self.players)))
            prefix = "按座位顺序"
        else:
            order = list(range(len(self.players) - 1, -1, -1))
            prefix = "按座位逆序"
        chain = "→".join([str(idx + 1) for idx in order] + [str(order[0] + 1)])
        return f"{prefix}({chain})"

    def _remove_from_hand(self, player_idx: int, card: str, count: int = 1) -> bool:
        hand = self.players[player_idx].hand
        if count <= 0 or hand[card] < count:
            return False
        hand[card] -= count
        if hand[card] <= 0:
            hand.pop(card, None)
        return True

    def _draw_cards(self, player_idx: int, count: int) -> List[str]:
        drawn: List[str] = []
        for _ in range(max(0, count)):
            if not self.deck:
                break
            card = self.deck.pop()
            self.players[player_idx].hand[card] += 1
            drawn.append(card)
        return drawn

    def _draw_all_from(self, start_idx: int, count_each: int) -> None:
        idx = start_idx
        for _ in range(len(self.players)):
            self._draw_cards(idx, count_each)
            idx = self._next_index(idx)

    def _draw_min_hand_players_once(self) -> None:
        if not self.players:
            return
        min_hand = min(p.hand_size for p in self.players)
        for idx, player in enumerate(self.players):
            if player.hand_size == min_hand:
                self._draw_cards(idx, 1)

    def _distribute_draws(self, start_idx: int, total: int) -> List[Tuple[int, int]]:
        if total <= 0:
            return []
        details: List[Tuple[int, int]] = []
        remaining = total
        idx = start_idx
        while remaining > 0 and self.deck:
            # 按规则：一次发牌超过 3 张时，按顺序轮转，每人每轮最多摸 3 张；双人局不受此限制。
            if len(self.players) == 2:
                limit = remaining
            else:
                limit = min(3, remaining)
            drawn = self._draw_cards(idx, limit)
            got = len(drawn)
            if got <= 0:
                break
            details.append((idx, got))
            remaining -= got
            idx = self._next_index(idx)
        return details

    @staticmethod
    def _format_draw_details(players: List[PlayerState], details: List[Tuple[int, int]]) -> str:
        if not details:
            return "无人摸牌"
        merged: Dict[int, int] = {}
        order: List[int] = []
        for idx, num in details:
            if idx not in merged:
                merged[idx] = 0
                order.append(idx)
            merged[idx] += num
        parts = [f"{players[idx].name}+{merged[idx]}" for idx in order]
        return ", ".join(parts)

    @staticmethod
    def _pair_key(ion_a: str, ion_b: str) -> Pair:
        if ion_a in t.Cation:
            return (ion_a, ion_b)
        return (ion_b, ion_a)

    def _cleanup_solution(self, ion: str) -> None:
        if self.solution[ion] <= 0:
            self.solution.pop(ion, None)

    @staticmethod
    def _pair_ion_coeff(pair: Pair, ion: str) -> int:
        cation, anion = pair
        coeffs = t.Balance.get(cation, {}).get(anion)
        if not coeffs:
            return 0
        if ion == cation:
            return int(coeffs[0])
        if ion == anion:
            return int(coeffs[1])
        return 0

    @staticmethod
    def _is_silicic_acid_pair(pair: Pair) -> bool:
        return pair == _SILICIC_ACID_PAIR

    def _pair_reaction_allowed(
        self,
        zone_name: str,
        pair: Pair,
        trigger_ion: str,
        target_ion: str,
    ) -> bool:
        if self._pair_ion_coeff(pair, target_ion) <= 0:
            return False
        # Prevent no-op loops like H+ reacting with H2SiO3/H2O products repeatedly.
        if self._pair_ion_coeff(pair, trigger_ion) > 0:
            return False

        if zone_name != "precipitates":
            return True

        cation, anion = pair
        if self._is_silicic_acid_pair(pair):
            # Silicic acid only reacts with hydroxide.
            return trigger_ion == t.OH and target_ion == t.H

        if trigger_ion == t.H:
            # Acid can only attack precipitate anion that is acid-reactive.
            return target_ion == anion and anion in _ACID_REACTIVE_PRECIP_ANIONS

        if trigger_ion == t.OH:
            # In precipitate zone, hydroxide only attacks silicic acid.
            return False

        return True

    def _count_ion_in_pair_counter(
        self,
        zone_name: str,
        zone: Counter[Pair],
        ion: str,
        trigger_ion: Optional[str] = None,
    ) -> int:
        total = 0
        for pair, groups in zone.items():
            if groups <= 0:
                continue
            if trigger_ion is not None and not self._pair_reaction_allowed(
                zone_name=zone_name,
                pair=pair,
                trigger_ion=trigger_ion,
                target_ion=ion,
            ):
                continue
            coeff = self._pair_ion_coeff(pair, ion)
            if coeff > 0:
                total += coeff * groups
        return total

    def _count_ion_in_products(self, ion: str, trigger_ion: Optional[str] = None) -> int:
        return (
            self._count_ion_in_pair_counter("precipitates", self.precipitates, ion, trigger_ion)
            + self._count_ion_in_pair_counter(
                "weak_electrolytes", self.weak_electrolytes, ion, trigger_ion
            )
            + self._count_ion_in_pair_counter("gases", self.gases, ion, trigger_ion)
        )

    def _extract_ion_from_pair_counter(
        self,
        zone_name: str,
        zone: Counter[Pair],
        ion: str,
        need: int,
        trigger_ion: Optional[str] = None,
    ) -> Tuple[int, Counter[str]]:
        if need <= 0:
            return 0, Counter()
        consumed = 0
        released: Counter[str] = Counter()
        for pair in sorted(list(zone.keys())):
            if consumed >= need:
                break
            if trigger_ion is not None and not self._pair_reaction_allowed(
                zone_name=zone_name,
                pair=pair,
                trigger_ion=trigger_ion,
                target_ion=ion,
            ):
                continue
            cation, anion = pair
            if ion == cation:
                source_ion = cation
                other_ion = anion
            elif ion == anion:
                source_ion = anion
                other_ion = cation
            else:
                continue

            source_per_group = self._pair_ion_coeff(pair, source_ion)
            other_per_group = self._pair_ion_coeff(pair, other_ion)
            if source_per_group <= 0:
                continue

            groups = zone.get(pair, 0)
            while groups > 0 and consumed < need:
                zone[pair] -= 1
                groups -= 1
                if zone[pair] <= 0:
                    zone.pop(pair, None)

                remaining = need - consumed
                take = min(source_per_group, remaining)
                consumed += take
                if source_per_group > take:
                    released[source_ion] += source_per_group - take
                if other_per_group > 0:
                    released[other_ion] += other_per_group
        return consumed, released

    def _extract_ion_from_products(
        self,
        ion: str,
        need: int,
        trigger_ion: Optional[str] = None,
    ) -> int:
        if need <= 0:
            return 0
        consumed_total = 0
        released_total: Counter[str] = Counter()
        zones = (
            ("precipitates", self.precipitates),
            ("weak_electrolytes", self.weak_electrolytes),
            ("gases", self.gases),
        )
        for zone_name, zone in zones:
            if consumed_total >= need:
                break
            consumed, released = self._extract_ion_from_pair_counter(
                zone_name=zone_name,
                zone=zone,
                ion=ion,
                need=need - consumed_total,
                trigger_ion=trigger_ion,
            )
            consumed_total += consumed
            released_total.update(released)
        for rel_ion, amount in released_total.items():
            if amount > 0:
                self.solution[rel_ion] += amount
        return consumed_total

    def _resolve_reaction_with_ion(self, ion: str) -> int:
        if ion not in t.Ion:
            return 0
        reacted_cards = 0

        def consume(other: str, into: Optional[Counter[Pair]], slightly_soluble: bool = False) -> int:
            nonlocal reacted_cards
            if other not in t.Balance[ion]:
                return 0
            coeff_ion, coeff_other = t.Balance[ion][other]
            threshold_scale = 2 if slightly_soluble else 1
            gained = 0
            while True:
                enough_ion = self.solution[ion] >= threshold_scale * coeff_ion
                enough_other_in_solution = self.solution[other] >= threshold_scale * coeff_other
                enough_other_in_products = (
                    self._count_ion_in_products(other, trigger_ion=ion)
                    >= threshold_scale * coeff_other
                )
                if not enough_ion:
                    break
                if not enough_other_in_solution and not enough_other_in_products:
                    break

                self.solution[ion] -= coeff_ion
                self._cleanup_solution(ion)
                if enough_other_in_solution:
                    self.solution[other] -= coeff_other
                    self._cleanup_solution(other)
                else:
                    got = self._extract_ion_from_products(
                        other,
                        coeff_other,
                        trigger_ion=ion,
                    )
                    if got < coeff_other:
                        self.solution[ion] += coeff_ion
                        break

                if into is not None:
                    into[self._pair_key(ion, other)] += 1
                reacted_cards += coeff_ion + coeff_other
                gained += 1
            return gained

        for other in t.toS[ion]:
            consume(other, self.precipitates, slightly_soluble=False)
        for other in t.toG[ion]:
            consume(other, self.gases, slightly_soluble=False)
        for other in t.toWE[ion]:
            consume(other, self.weak_electrolytes, slightly_soluble=False)
        for other in t.toSS[ion]:
            consume(other, self.precipitates, slightly_soluble=True)
        for other in t.toNE[ion]:
            consume(other, None, slightly_soluble=False)

        return reacted_cards

    @staticmethod
    def _reactable_list(ion: str) -> List[str]:
        seq = t.toS[ion] + t.toG[ion] + t.toWE[ion] + t.toSS[ion] + t.toNE[ion]
        seen = set()
        out = []
        for x in seq:
            if x not in seen:
                seen.add(x)
                out.append(x)
        return out

    def _consume_reactable_ions_only(self, ion: str) -> int:
        if ion not in t.Ion:
            return 0
        reacted_partner_cards = 0
        for other in self._reactable_list(ion):
            if other not in t.Balance[ion]:
                continue
            coeff_other = t.Balance[ion][other][1]
            if coeff_other <= 0:
                continue
            threshold_scale = 2 if other in t.toSS[ion] else 1
            while True:
                if self.solution[other] >= threshold_scale * coeff_other:
                    self.solution[other] -= coeff_other
                    self._cleanup_solution(other)
                    reacted_partner_cards += coeff_other
                    continue
                if self._count_ion_in_products(other, trigger_ion=ion) >= threshold_scale * coeff_other:
                    got = self._extract_ion_from_products(
                        other,
                        coeff_other,
                        trigger_ion=ion,
                    )
                    if got < coeff_other:
                        break
                    reacted_partner_cards += coeff_other
                    continue
                break
        return reacted_partner_cards

    def _check_winner(self, player_idx: int) -> None:
        if self.players[player_idx].hand_size == 0 and self.winner is None:
            self.winner = player_idx
            self.pending_draw_effect = None
            self._log(f"{self.players[player_idx].name} 获胜。")

    def _consume_action(self) -> bool:
        if self.actions_left <= 0:
            return False
        self.actions_left -= 1
        return True

    def _apply_radiation_for_player(self, player_idx: int) -> None:
        if not self.uranium_timers:
            return
        radiation_cards = len(self.uranium_timers)
        if radiation_cards > 0:
            self._draw_cards(player_idx, radiation_cards)
            self._log(f"辐射: {self.players[player_idx].name} 摸 {radiation_cards} 张。")
        for i in range(len(self.uranium_timers)):
            self.uranium_timers[i] -= 1
        self.uranium_timers = [x for x in self.uranium_timers if x > 0]

    def _apply_radiation_for_current_player(self) -> None:
        self._apply_radiation_for_player(self.current_player)

    def _begin_turn_from(self, start_player: int) -> None:
        self.actions_left = 1
        self.played_card_this_turn = False
        candidate = start_player
        while True:
            self.current_player = candidate
            self.turn_number += 1
            skip_count = self.skip_turns[self.current_player]
            if skip_count > 0:
                self.skip_turns[self.current_player] -= 1
                if self.skip_turns[self.current_player] <= 0:
                    self.skip_turns.pop(self.current_player, None)
                self._log(
                    f"第 {self.turn_number} 回合: {self.players[self.current_player].name} 被跳过。"
                )
                candidate = self._next_index(self.current_player)
                continue
            self._apply_radiation_for_current_player()
            self._log(f"第 {self.turn_number} 回合: {self.players[self.current_player].name}。")
            return

    def _end_turn_internal(self) -> None:
        self._begin_turn_from(self._next_index(self.current_player))

    def _clear_board_cards(self) -> Tuple[int, int]:
        removed_gold = self.gold_count
        removed_uranium = len(self.uranium_timers)
        self.solution.clear()
        self.precipitates.clear()
        self.gases.clear()
        self.weak_electrolytes.clear()
        self.gold_count = 0
        self.uranium_timers.clear()
        return removed_gold, removed_uranium

    def _apply_removed_special_effects(
        self, player_idx: int, removed_gold: int, removed_uranium: int
    ) -> None:
        if removed_gold > 0:
            self._draw_all_from(player_idx, 1)
            self._draw_min_hand_players_once()
            self._log("金被移除，触发共同富裕。")
        if removed_uranium > 0:
            self._draw_all_from(player_idx, 1)
            self._log("铀被移除，触发核泄漏。")

    def _draw_limit_per_player(self, remaining: int) -> int:
        if remaining <= 0:
            return 0
        if len(self.players) == 2:
            return remaining
        return min(3, remaining)

    def _start_pending_draw_effect(
        self,
        source_player: int,
        effect_card: str,
        total_draw: int,
        post_removed_special: Optional[Tuple[int, int, int]] = None,
    ) -> None:
        if total_draw <= 0:
            if post_removed_special is not None:
                owner, removed_gold, removed_uranium = post_removed_special
                self._apply_removed_special_effects(owner, removed_gold, removed_uranium)
            return
        self._pending_draw_effect_seq += 1
        self.pending_draw_effect = {
            "id": self._pending_draw_effect_seq,
            "effect_card": effect_card,
            "source_player": int(source_player),
            "remaining": int(total_draw),
            "cursor": self._next_index(source_player),
            "follow_open": True,
            "awaiting_player": None,
            "follow_allowed": False,
            "counter_allowed": False,
            "forced_next_player": None,
            "post_removed_special": post_removed_special,
            "canceled_by_counter": False,
        }
        self._advance_pending_draw_effect()

    def _pending_waiting_player(self) -> Optional[int]:
        pending = self.pending_draw_effect
        if not pending:
            return None
        waiting = pending.get("awaiting_player")
        if waiting is None:
            return None
        try:
            idx = int(waiting)
        except Exception:
            return None
        if 0 <= idx < len(self.players):
            return idx
        return None

    def _advance_pending_draw_effect(self) -> None:
        while self.pending_draw_effect is not None and self.winner is None:
            pending = self.pending_draw_effect
            remaining = int(pending.get("remaining", 0))
            if remaining <= 0:
                self._finalize_pending_draw_effect()
                return

            cursor = int(pending.get("cursor", self.current_player))
            if cursor < 0 or cursor >= len(self.players):
                pending["remaining"] = 0
                self._finalize_pending_draw_effect()
                return

            effect_card = str(pending.get("effect_card", "")).strip()
            source_player = int(pending.get("source_player", self.current_player))
            follow_open = bool(pending.get("follow_open", False))
            is_offline_placeholder = self.skip_turns[cursor] >= 10**8
            can_follow = (
                (not is_offline_placeholder)
                and follow_open
                and cursor == self._next_index(source_player)
                and self.players[cursor].hand[effect_card] > 0
            )
            can_counter = (
                (not is_offline_placeholder)
                and self.players[cursor].hand[t.AS] > 0
            )

            if can_follow or can_counter:
                pending["awaiting_player"] = cursor
                pending["follow_allowed"] = can_follow
                pending["counter_allowed"] = can_counter
                return

            draw_limit = self._draw_limit_per_player(remaining)
            if draw_limit <= 0:
                pending["remaining"] = 0
                self._finalize_pending_draw_effect()
                return
            got = len(self._draw_cards(cursor, draw_limit))
            if got <= 0:
                pending["remaining"] = 0
                self._finalize_pending_draw_effect()
                return

            pending["remaining"] = remaining - got
            pending["cursor"] = self._next_index(cursor)
            pending["follow_open"] = False
            self._log(f"{self.players[cursor].name} 受到 {effect_card} 效果，摸 {got} 张。")

    def _finalize_pending_draw_effect(self) -> None:
        pending = self.pending_draw_effect
        if pending is None:
            return
        forced_next = pending.get("forced_next_player")
        remaining = int(pending.get("remaining", 0))
        effect_card = str(pending.get("effect_card", "")).strip()
        if remaining > 0:
            self._log(f"{effect_card} 剩余未执行摸牌 {remaining} 张，效果结束。")
        post_removed_special = pending.get("post_removed_special")
        canceled_by_counter = bool(pending.get("canceled_by_counter", False))
        self.pending_draw_effect = None
        if (
            (not canceled_by_counter)
            and isinstance(post_removed_special, tuple)
            and len(post_removed_special) == 3
        ):
            owner, removed_gold, removed_uranium = post_removed_special
            self._apply_removed_special_effects(
                int(owner), int(removed_gold), int(removed_uranium)
            )
        if self.winner is not None:
            return
        if forced_next is not None:
            self._begin_turn_from(int(forced_next))
            return
        if self.actions_left <= 0:
            self._end_turn_internal()

    def _handle_pending_draw_response(self, player_idx: int, decision: str) -> Tuple[bool, str]:
        pending = self.pending_draw_effect
        if pending is None:
            return False, "当前没有待响应的加牌效果。"
        waiting_player = self._pending_waiting_player()
        if waiting_player is None or player_idx != waiting_player:
            return False, "当前不是你的加牌响应时机。"

        decision_key = str(decision or "").strip().lower()
        follow_allowed = bool(pending.get("follow_allowed", False))
        counter_allowed = bool(pending.get("counter_allowed", False))
        effect_card = str(pending.get("effect_card", "")).strip()
        source_player = int(pending.get("source_player", self.current_player))
        player_name = self.players[player_idx].name

        pending["awaiting_player"] = None
        pending["follow_allowed"] = False
        pending["counter_allowed"] = False

        if decision_key == "follow":
            if not follow_allowed:
                return False, "当前不允许跟牌传递。"
            if not self._remove_from_hand(player_idx, effect_card, 1):
                return False, f"你没有可跟牌的 {effect_card}。"
            self.discard.append(effect_card)
            pending["source_player"] = player_idx
            pending["cursor"] = self._next_index(player_idx)
            pending["follow_open"] = True
            pending["forced_next_player"] = self._next_index(player_idx)
            self._apply_radiation_for_player(player_idx)
            self._log(f"{player_name} 跟牌打出 {effect_card}，将效果传递给下家。")
            self._check_winner(player_idx)
            if self.winner is not None:
                self.pending_draw_effect = None
                return True, "已跟牌。"
            self._advance_pending_draw_effect()
            return True, "已跟牌。"

        if decision_key == "counter":
            if not counter_allowed:
                return False, "当前不允许加钠反制。"
            if not self._remove_from_hand(player_idx, t.AS, 1):
                return False, "你没有可用于反制的加钠。"
            self.discard.append(t.AS)
            self._apply_add_sodium_effect(player_idx, "加钠(反制)")
            upper_neighbor = self._prev_index(player_idx)
            if source_player == upper_neighbor:
                pending["forced_next_player"] = self._next_index(player_idx)
                self._apply_radiation_for_player(player_idx)
                self._log(
                    f"{player_name} 对上家的 {effect_card} 使用加钠反制，"
                    "视为耗尽本回合。"
                )
            else:
                self._draw_cards(player_idx, 1)
                pending["forced_next_player"] = self._next_index(source_player)
                self._log(
                    f"{player_name} 对 {self.players[source_player].name} 的 {effect_card} 使用加钠反制，"
                    f"额外摸 1 张，回合改到 {self.players[pending['forced_next_player']].name}。"
                )
            pending["remaining"] = 0
            pending["canceled_by_counter"] = True
            self._check_winner(player_idx)
            self._finalize_pending_draw_effect()
            return True, "已使用加钠反制。"

        if decision_key not in {"draw", "accept", "pass"}:
            return False, "无效的响应指令。"

        remaining = int(pending.get("remaining", 0))
        draw_limit = self._draw_limit_per_player(remaining)
        got = len(self._draw_cards(player_idx, draw_limit))
        pending["remaining"] = max(0, remaining - got)
        pending["cursor"] = self._next_index(player_idx)
        pending["follow_open"] = False
        self._log(f"{player_name} 选择执行摸牌，摸 {got} 张。")
        self._advance_pending_draw_effect()
        return True, "已执行摸牌。"

    def on_player_disconnected(self, player_idx: int) -> None:
        waiting_player = self._pending_waiting_player()
        if waiting_player is None or waiting_player != player_idx:
            return
        self._log(f"{self.players[player_idx].name} 在响应阶段离线，按“摸牌”处理。")
        self._handle_pending_draw_response(player_idx, "draw")

    def _apply_add_sodium_effect(self, player_idx: int, source_label: str) -> None:
        removed_gold, removed_uranium = self._clear_board_cards()
        self._log(
            f"{self.players[player_idx].name} 使用 {source_label}。清空场面，全员摸 1 张。"
        )
        self._draw_all_from(player_idx, 1)
        self._apply_removed_special_effects(player_idx, removed_gold, removed_uranium)

    def _play_wangzha(self, player_idx: int) -> Tuple[bool, str]:
        if not self._consume_action():
            return False, "没有剩余行动次数。"
        hand = self.players[player_idx].hand
        if hand[t.Acid] < 1 or hand[t.Alk] < 1:
            self.actions_left += 1
            return False, "王炸需要手牌中同时有 1 张强酸和 1 张强碱。"
        self._remove_from_hand(player_idx, t.Acid, 1)
        self._remove_from_hand(player_idx, t.Alk, 1)
        self.discard.extend([t.Acid, t.Alk])
        self._apply_add_sodium_effect(player_idx, "王炸(强酸+强碱)")
        self._check_winner(player_idx)
        return True, "已打出王炸。"

    def _play_ion(self, player_idx: int, card: str, count: int) -> Tuple[bool, str]:
        if card not in t.Ion:
            return False, f"{card} 不是离子牌。"
        if count <= 0:
            return False, "数量必须为正整数。"
        if not self._consume_action():
            return False, "没有剩余行动次数。"
        if not self._remove_from_hand(player_idx, card, count):
            self.actions_left += 1
            return False, f"手牌中 {card} 数量不足。"

        self.solution[card] += count
        reacted_cards = self._resolve_reaction_with_ion(card)
        extra_actions = (reacted_cards + 1) // 2 if reacted_cards > 0 else 0
        self.actions_left += extra_actions
        self._log(
            f"{self.players[player_idx].name} 打出 {card} ×{count}。"
            f"参与反应牌数={reacted_cards}，额外行动={extra_actions}。"
        )
        self._check_winner(player_idx)
        return True, "离子牌已打出。"

    def _play_special(self, player_idx: int, card: str) -> Tuple[bool, str]:
        if card not in t.Special:
            return False, f"{card} 不是特殊牌。"
        if not self._consume_action():
            return False, "没有剩余行动次数。"
        if not self._remove_from_hand(player_idx, card, 1):
            self.actions_left += 1
            return False, f"手牌中 {card} 数量不足。"

        if card == t.Au:
            self.gold_count += 1
        elif card == t.U:
            self.uranium_timers.append(3)

        self._log(f"{self.players[player_idx].name} 打出特殊牌 {card}。")
        self._check_winner(player_idx)
        return True, "特殊牌已打出。"

    def _play_from_impurity(self, player_idx: int) -> None:
        while True:
            drawn = self._draw_cards(player_idx, 1)
            if not drawn:
                self._log("杂质触发：牌堆为空。")
                return
            card = drawn[0]
            self._log(f"杂质摸到 {card}。")
            if card in t.Ion:
                self._remove_from_hand(player_idx, card, 1)
                self.solution[card] += 1
                reacted_cards = self._resolve_reaction_with_ion(card)
                extra_actions = (reacted_cards + 1) // 2 if reacted_cards > 0 else 0
                self.actions_left += extra_actions
                self._log(
                    f"杂质自动打出离子 {card}。"
                    f"参与反应牌数={reacted_cards}，额外行动={extra_actions}。"
                )
                return
            if card in t.Special:
                self._remove_from_hand(player_idx, card, 1)
                if card == t.Au:
                    self.gold_count += 1
                else:
                    self.uranium_timers.append(3)
                self._log(f"杂质自动打出特殊牌 {card}。")
                return
            self._remove_from_hand(player_idx, card, 1)
            self.discard.append(card)
            self._log(f"杂质弃置 {card}（非离子/非特殊牌）。")

    def _play_operation(self, player_idx: int, card: str, action: Dict[str, Any]) -> Tuple[bool, str]:
        if card not in t.Function:
            return False, f"{card} 不是功能牌。"
        if not self._consume_action():
            return False, "没有剩余行动次数。"
        if not self._remove_from_hand(player_idx, card, 1):
            self.actions_left += 1
            return False, f"手牌中 {card} 数量不足。"

        self.discard.append(card)
        current_name = self.players[player_idx].name
        draw_effect_card: Optional[str] = None
        draw_total = 0
        post_removed_special: Optional[Tuple[int, int, int]] = None

        if card == t.Acid:
            reacted = self._consume_reactable_ions_only(t.H)
            draw_effect_card = card
            draw_total = reacted
            if reacted > 0:
                self._log(
                    f"{current_name} 使用 {t.Acid}。可反应离子数={reacted}。"
                    "将按顺序结算摸牌（可跟牌/反制）。"
                )
            else:
                self._log(f"{current_name} 使用 {t.Acid}，但无可反应离子。")
        elif card == t.Alk:
            reacted = self._consume_reactable_ions_only(t.OH)
            draw_effect_card = card
            draw_total = reacted
            if reacted > 0:
                self._log(
                    f"{current_name} 使用 {t.Alk}。可反应离子数={reacted}。"
                    "将按顺序结算摸牌（可跟牌/反制）。"
                )
            else:
                self._log(f"{current_name} 使用 {t.Alk}，但无可反应离子。")
        elif card == t.Enough:
            target_ion = str(action.get("target_ion", "")).strip()
            try:
                target_count = int(action.get("target_count", 1))
            except Exception:
                target_count = 1
            target_count = max(1, target_count)
            self._draw_cards(player_idx, 1)
            if (
                target_ion in t.Ion
                and self.players[player_idx].hand[target_ion] >= target_count
                and self._remove_from_hand(player_idx, target_ion, target_count)
            ):
                # 足量要求先打出所选离子 A，A 本身保留在场上。
                self.solution[target_ion] += target_count
                reacted = self._consume_reactable_ions_only(target_ion)
                self.actions_left += reacted
                self._log(
                    f"{current_name} 使用 {t.Enough}，打出 {target_ion} ×{target_count}。"
                    f"可反应离子数={reacted}，额外行动={reacted}。"
                )
            else:
                self._log(f"{current_name} 使用 {t.Enough}，但未提供有效目标离子。")
        elif card == t.Imp:
            self._log(f"{current_name} 使用 {t.Imp}。")
            self._play_from_impurity(player_idx)
        elif card == t.Flt:
            normal_precip = sum(self.precipitates.values())
            self.precipitates.clear()
            draw_effect_card = card
            draw_total = normal_precip
            if normal_precip > 0:
                self._log(
                    f"{current_name} 使用 {t.Flt}。沉淀组数={normal_precip}。"
                    "将按顺序结算摸牌（可跟牌/反制）。"
                )
            else:
                self._log(f"{current_name} 使用 {t.Flt}，场上无可计数沉淀。")

            removed_gold = self.gold_count
            removed_uranium = len(self.uranium_timers)
            self.gold_count = 0
            self.uranium_timers.clear()
            post_removed_special = (player_idx, removed_gold, removed_uranium)
        elif card == t.Fde:
            colored = 0
            for ion in t.Color:
                colored += self.solution[ion]
                self.solution[ion] = 0
                self._cleanup_solution(ion)
            draw_effect_card = card
            draw_total = 2 * colored
            if draw_total > 0:
                self._log(
                    f"{current_name} 使用 {t.Fde}。有色离子数={colored}。"
                    "将按顺序结算摸牌（可跟牌/反制）。"
                )
            else:
                self._log(f"{current_name} 使用 {t.Fde}，但无有色离子。")
        elif card == t.AW:
            gases = sum(self.gases.values())
            self.gases.clear()
            draw_effect_card = card
            draw_total = 2 * gases
            if draw_total > 0:
                self._log(
                    f"{current_name} 使用 {t.AW}。气体组数={gases}。"
                    "将按顺序结算摸牌（可跟牌/反制）。"
                )
            else:
                self._log(f"{current_name} 使用 {t.AW}，但无气体。")
        elif card == t.Dtl:
            blocked = (
                sum(self.precipitates.values()) > 0
                or sum(self.gases.values()) > 0
                or self.gold_count > 0
                or len(self.uranium_timers) > 0
            )
            if blocked:
                self._log(f"{current_name} 使用 {t.Dtl}，但当前无效。")
            else:
                ion_num = sum(self.solution.values())
                self.solution.clear()
                draw_effect_card = card
                draw_total = ion_num
                if ion_num > 0:
                    self._log(
                        f"{current_name} 使用 {t.Dtl}。移除离子数={ion_num}。"
                        "将按顺序结算摸牌（可跟牌/反制）。"
                    )
                else:
                    self._log(f"{current_name} 使用 {t.Dtl}，溶液区无离子。")
        elif card == t.AS:
            self._apply_add_sodium_effect(player_idx, t.AS)
        elif card == t.Ban:
            target = self._next_index(player_idx)
            self.skip_turns[target] += 1
            self._log(
                f"{current_name} 使用 {t.Ban}。"
                f"{self.players[target].name} 的下回合将被跳过。"
            )
        elif card == t.Rev:
            if len(self.players) == 2:
                target = self._next_index(player_idx)
                self.skip_turns[target] += 1
                self._log(
                    f"{current_name} 在双人模式下使用 {t.Rev}，按 {t.Ban} 处理。"
                    f"跳过 {self.players[target].name}。"
                )
            else:
                self.direction *= -1
                self._log(
                    f"{current_name} 使用 {t.Rev}。出牌方向改为 {self._direction_hint_text()}。"
                )
        else:
            self._log(f"{current_name} 打出功能牌 {card}（无实际效果）。")

        if draw_effect_card is not None:
            self._start_pending_draw_effect(
                source_player=player_idx,
                effect_card=draw_effect_card,
                total_draw=draw_total,
                post_removed_special=post_removed_special,
            )

        self._check_winner(player_idx)
        return True, "功能牌已打出。"

    def apply_action(self, player_idx: int, action: Dict[str, Any]) -> Tuple[bool, str]:
        if self.winner is not None:
            return False, "对局已结束。"
        if not isinstance(action, dict):
            return False, "操作数据无效。"

        kind = action.get("kind")
        waiting_player = self._pending_waiting_player()
        if waiting_player is not None:
            if player_idx != waiting_player:
                return False, f"当前等待 {self.players[waiting_player].name} 响应摸牌效果。"
            if kind != "respond_draw_effect":
                return False, "当前必须先响应摸牌效果。"
            decision = str(action.get("decision", "draw")).strip().lower()
            return self._handle_pending_draw_response(player_idx, decision)

        if kind == "respond_draw_effect":
            return False, "当前没有待响应的摸牌效果。"

        if player_idx != self.current_player:
            return False, "未轮到你行动。"

        if kind == "end_turn":
            if not self.played_card_this_turn:
                return False, "本回合尚未出牌，不能直接结束回合。"
            self._end_turn_internal()
            return True, "已结束回合。"

        if self.actions_left <= 0:
            return False, "没有剩余行动次数，请先结束回合。"

        ok = False
        msg = ""
        if kind == "play_ion":
            card = str(action.get("card", "")).strip()
            try:
                count = int(action.get("count", 1))
            except (TypeError, ValueError):
                return False, "离子数量无效。"
            ok, msg = self._play_ion(player_idx, card, count)
        elif kind == "play_special":
            card = str(action.get("card", "")).strip()
            ok, msg = self._play_special(player_idx, card)
        elif kind == "play_operation":
            card = str(action.get("card", "")).strip()
            ok, msg = self._play_operation(player_idx, card, action)
        elif kind == "play_wangzha":
            ok, msg = self._play_wangzha(player_idx)
        else:
            return False, f"不支持的操作类型: {kind}"

        if ok and player_idx == self.current_player:
            self.played_card_this_turn = True
        if (
            ok
            and self.winner is None
            and self.pending_draw_effect is None
            and player_idx == self.current_player
            and self.actions_left <= 0
        ):
            self._end_turn_internal()
            msg = f"{msg} 行动次数已耗尽，自动结束回合。"
        return ok, msg

    def serialize_state(
        self,
        viewer_idx: Optional[int] = None,
        reveal_all_hands: bool = False,
        mode: str = "local",
    ) -> Dict[str, Any]:
        players_data: List[Dict[str, Any]] = []
        for idx, player in enumerate(self.players):
            entry: Dict[str, Any] = {
                "name": player.name,
                "hand_size": player.hand_size,
            }
            can_see_hand = reveal_all_hands or (viewer_idx is not None and idx == viewer_idx)
            if can_see_hand:
                entry["hand"] = _counter_to_dict(player.hand)
            players_data.append(entry)

        waiting_player = self._pending_waiting_player()
        pending_payload: Dict[str, Any] = {"active": False}
        if self.pending_draw_effect is not None:
            pending = self.pending_draw_effect
            source_player = int(pending.get("source_player", self.current_player))
            effect_card = str(pending.get("effect_card", "")).strip()
            pending_payload = {
                "active": True,
                "id": int(pending.get("id", 0)),
                "source_player": source_player,
                "source_name": self.players[source_player].name
                if 0 <= source_player < len(self.players)
                else "",
                "effect_card": effect_card,
                "remaining": int(pending.get("remaining", 0)),
                "awaiting_player": waiting_player,
                "awaiting_name": (
                    self.players[waiting_player].name
                    if waiting_player is not None and 0 <= waiting_player < len(self.players)
                    else ""
                ),
                "follow_allowed": bool(pending.get("follow_allowed", False)),
                "counter_allowed": bool(pending.get("counter_allowed", False)),
            }

        can_act = False
        can_end_turn = False
        if viewer_idx is not None and self.winner is None:
            if waiting_player is not None:
                can_act = viewer_idx == waiting_player
                can_end_turn = False
            else:
                can_act = viewer_idx == self.current_player and self.actions_left > 0
                can_end_turn = (
                    viewer_idx == self.current_player
                    and self.actions_left > 0
                    and self.played_card_this_turn
                )

        return {
            "mode": mode,
            "game_started": True,
            "you_index": viewer_idx,
            "current_player": self.current_player,
            "actions_left": self.actions_left,
            "direction": self.direction,
            "direction_hint": self._direction_hint_text(),
            "turn_number": self.turn_number,
            "winner": self.winner,
            "deck_size": len(self.deck),
            "discard_size": len(self.discard),
            "can_act": can_act,
            "can_end_turn": can_end_turn,
            "played_card_this_turn": self.played_card_this_turn,
            "pending_response": pending_payload,
            "players": players_data,
            "board": {
                "solution": _counter_to_dict(self.solution),
                "precipitates": _pair_counter_to_dict(self.precipitates),
                "gases": _pair_counter_to_dict(self.gases),
                "weak_electrolytes": _pair_counter_to_dict(self.weak_electrolytes),
                "gold": self.gold_count,
                "uranium": len(self.uranium_timers),
                "skip_turns": {
                    self.players[idx].name: turns
                    for idx, turns in self.skip_turns.items()
                    if turns > 0
                },
            },
            "log": list(self.log),
        }


class LocalController:
    def __init__(self, names: List[str], initial_hand_size: Optional[int] = None) -> None:
        self.engine = GameEngine(names, initial_hand_size=initial_hand_size)

    def get_state(self) -> Dict[str, Any]:
        viewer = self.engine.current_player
        waiting = self.engine._pending_waiting_player()
        if waiting is not None:
            viewer = waiting
        return self.engine.serialize_state(viewer_idx=viewer, reveal_all_hands=False, mode="local")

    def act(self, action: Dict[str, Any]) -> Tuple[bool, str]:
        player_idx = self.engine.current_player
        return self.engine.apply_action(player_idx, action)

    def close(self) -> None:
        return


class HostServer:
    def __init__(
        self,
        host_name: str,
        port: int,
        room_size: int = 2,
        initial_hand_size: Optional[int] = None,
        include_host_player: bool = True,
    ) -> None:
        self.host_name = host_name
        self.port = port
        self.room_size = max(2, min(8, int(room_size)))
        self.initial_hand_size = initial_hand_size
        self.include_host_player = bool(include_host_player)
        self.listener: Optional[socket.socket] = None
        self.engine: Optional[GameEngine] = None
        self.lock = threading.Lock()
        self.running = False
        self.error: Optional[str] = None

        self.lobby_players: Dict[int, str] = {}
        if self.include_host_player:
            self.lobby_players[0] = host_name
        self.clients: Dict[int, Dict[str, Any]] = {}
        self.reconnect_keys: Dict[int, str] = {}

    def start(self) -> None:
        self.listener = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
        self.listener.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
        self.listener.settimeout(0.5)
        self.listener.bind(("0.0.0.0", self.port))
        non_host_slots = self.room_size - (1 if self.include_host_player else 0)
        self.listener.listen(max(1, non_host_slots))
        self.running = True
        threading.Thread(target=self._accept_loop, daemon=True).start()
        threading.Thread(target=self._heartbeat_watchdog_loop, daemon=True).start()

    def _find_open_slot_locked(self) -> Optional[int]:
        start_idx = 1 if self.include_host_player else 0
        for idx in range(start_idx, self.room_size):
            if idx not in self.lobby_players:
                return idx
        return None

    @staticmethod
    def _new_reconnect_key() -> str:
        return secrets.token_urlsafe(12)

    def _ensure_reconnect_key_locked(self, slot: int) -> str:
        key = str(self.reconnect_keys.get(slot, "")).strip()
        if not key:
            key = self._new_reconnect_key()
            self.reconnect_keys[slot] = key
        return key

    def _resolve_reconnect_slot_locked(
        self,
        remote_name: str,
        resume_index: Optional[int],
        resume_key: str,
    ) -> Tuple[Optional[int], Optional[str]]:
        offline_slots: List[int] = []
        for idx in range(self.room_size):
            if self.include_host_player and idx == 0:
                continue
            if idx not in self.lobby_players:
                continue
            if idx in self.clients:
                continue
            offline_slots.append(idx)

        if not offline_slots:
            return None, "当前没有可重连的离线座位。"

        if resume_key:
            matched = [
                idx
                for idx in offline_slots
                if str(self.reconnect_keys.get(idx, "")).strip() == resume_key
            ]
            if len(matched) == 1:
                return matched[0], None
            all_matched = [
                idx
                for idx in range(self.room_size)
                if str(self.reconnect_keys.get(idx, "")).strip() == resume_key
            ]
            if all_matched:
                return None, "该座位已在线，无法重复登录。"
            return None, "重连凭据无效，请使用原会话信息重连。"

        if resume_index is not None:
            idx = int(resume_index)
            if idx < 0 or idx >= self.room_size:
                return None, "重连座位号无效。"
            if self.include_host_player and idx == 0:
                return None, "该座位不支持客户端重连。"
            if idx not in self.lobby_players:
                return None, "该座位不存在。"
            if idx in self.clients:
                return None, "该座位已在线。"
            seat_name = str(self.lobby_players.get(idx, "")).strip()
            if seat_name and remote_name and seat_name != remote_name:
                return None, f"重连昵称不匹配，{idx + 1}号位应为“{seat_name}”。"
            return idx, None

        if remote_name:
            matched_by_name = [
                idx
                for idx in offline_slots
                if str(self.lobby_players.get(idx, "")).strip() == remote_name
            ]
            if len(matched_by_name) == 1:
                return matched_by_name[0], None
            if len(matched_by_name) > 1:
                return None, "存在重名离线玩家，请使用原会话重连。"

        return None, "对局已开始，仅支持已掉线玩家重连。"

    def _status_text_from_net_state(self, net_state: str) -> str:
        if net_state == "lagging":
            return "网卡"
        return "在线"

    def _slot_status_text(
        self,
        idx: int,
        game_started: bool,
        client_states: Dict[int, str],
    ) -> str:
        if self.include_host_player and idx == 0:
            return "在线"
        if idx in client_states:
            return self._status_text_from_net_state(client_states[idx])
        if game_started:
            return "离线"
        return ""

    def _decorate_state_with_player_status(self, state: Dict[str, Any], game_started: bool) -> None:
        players = state.get("players")
        if not isinstance(players, list):
            return
        with self.lock:
            client_states = {
                idx: str(info.get("net_state", "online"))
                for idx, info in self.clients.items()
            }
        for idx, entry in enumerate(players):
            if isinstance(entry, dict):
                entry["status"] = self._slot_status_text(
                    idx=idx,
                    game_started=game_started,
                    client_states=client_states,
                )

    def _heartbeat_watchdog_loop(self) -> None:
        while self.running:
            time.sleep(HEARTBEAT_WATCHDOG_SECONDS)
            drop_list: List[int] = []
            status_changed = False
            game_started = False
            now = time.time()
            with self.lock:
                game_started = self.engine is not None
                for idx, info in list(self.clients.items()):
                    last_seen = float(info.get("last_seen", now))
                    elapsed = now - last_seen
                    if elapsed >= HEARTBEAT_TIMEOUT_SECONDS:
                        drop_list.append(idx)
                        continue
                    expected = "lagging" if elapsed >= HEARTBEAT_LAG_SECONDS else "online"
                    if str(info.get("net_state", "online")) != expected:
                        info["net_state"] = expected
                        status_changed = True
            for idx in drop_list:
                self._drop_client(idx, " 心跳超时下线。")
            if status_changed:
                if game_started:
                    self._broadcast_state()
                else:
                    self._broadcast_lobby_state()

    def _build_lobby_state(self, viewer_idx: int, mode: str) -> Dict[str, Any]:
        with self.lock:
            lobby_players = dict(self.lobby_players)
            client_states = {
                idx: str(info.get("net_state", "online"))
                for idx, info in self.clients.items()
            }
            error_text = self.error

        players_data: List[Dict[str, Any]] = []
        for idx in range(self.room_size):
            if idx in lobby_players:
                name = lobby_players[idx]
            else:
                name = ""
            entry: Dict[str, Any] = {
                "name": name,
                "hand_size": "",
                "status": self._slot_status_text(
                    idx=idx,
                    game_started=False,
                    client_states=client_states,
                ),
            }
            if idx == viewer_idx and idx in lobby_players:
                entry["hand"] = {}
            players_data.append(entry)

        joined = len(lobby_players)
        left = self.room_size - joined
        if left > 0:
            wait_msg = f"房间等待中：已加入 {joined}/{self.room_size}，还需 {left} 人。"
        else:
            wait_msg = "房间已满，正在开始对局..."

        logs: List[str] = []
        if error_text:
            logs.append(error_text)

        return {
            "mode": mode,
            "game_started": False,
            "message": wait_msg,
            "you_index": viewer_idx,
            "current_player": None,
            "actions_left": 0,
            "direction": 1,
            "turn_number": 0,
            "winner": None,
            "deck_size": 0,
            "discard_size": 0,
            "can_act": False,
            "room_size": self.room_size,
            "joined_count": joined,
            "players": players_data,
            "board": {},
            "log": logs,
        }

    def _broadcast_lobby_state(self) -> None:
        with self.lock:
            clients_snapshot = {
                idx: info["sock"]
                for idx, info in self.clients.items()
            }

        for idx, sock in clients_snapshot.items():
            try:
                state = self._build_lobby_state(viewer_idx=idx, mode="client")
                _send_json(sock, {"type": "state", "state": state})
            except Exception:
                pass

    def _try_start_game(self) -> None:
        start_game = False
        with self.lock:
            if self.engine is None and len(self.lobby_players) == self.room_size:
                names = [self.lobby_players[i] for i in range(self.room_size)]
                self.engine = GameEngine(names, initial_hand_size=self.initial_hand_size)
                start_game = True
        if start_game:
            self._broadcast_state()

    def _accept_loop(self) -> None:
        if self.listener is None:
            return
        while self.running:
            try:
                conn, _ = self.listener.accept()
            except socket.timeout:
                continue
            except Exception as exc:  # pragma: no cover
                self.error = f"监听异常: {exc}"
                return

            try:
                conn.settimeout(0.4)
                buffer = b""
                join_msg: Optional[Dict[str, Any]] = None
                while self.running:
                    msg, buffer, closed = _recv_json_nonblocking(conn, buffer)
                    if closed:
                        conn.close()
                        join_msg = None
                        break
                    if msg is None:
                        continue
                    join_msg = msg
                    break

                if join_msg is None:
                    continue

                if join_msg.get("type") != "join":
                    _send_json(conn, {"type": "error", "message": "首条消息必须是 join。"})
                    conn.close()
                    continue

                remote_name = str(join_msg.get("name", "玩家")).strip() or "玩家"
                raw_resume_index = join_msg.get("resume_index")
                resume_index: Optional[int]
                if raw_resume_index is None:
                    resume_index = None
                else:
                    try:
                        resume_index = int(raw_resume_index)
                    except Exception:
                        resume_index = None
                resume_key = str(join_msg.get("resume_key", "")).strip()
                reject_msg: Optional[str] = None
                slot: Optional[int] = None
                reconnect_key = ""
                game_started = False
                is_rejoin = False
                with self.lock:
                    game_started = self.engine is not None
                    if game_started:
                        slot, reject_msg = self._resolve_reconnect_slot_locked(
                            remote_name=remote_name,
                            resume_index=resume_index,
                            resume_key=resume_key,
                        )
                        if slot is not None:
                            seat_name = str(self.lobby_players.get(slot, remote_name)).strip() or remote_name
                            now = time.time()
                            reconnect_key = self._ensure_reconnect_key_locked(slot)
                            self.clients[slot] = {
                                "sock": conn,
                                "buffer": buffer,
                                "name": seat_name,
                                "last_seen": now,
                                "net_state": "online",
                            }
                            is_rejoin = True
                            if self.engine is not None:
                                self.engine.skip_turns.pop(slot, None)
                                self.engine._log(f"{seat_name} 已重连并回到 {slot + 1} 号位。")
                            self.error = f"{seat_name} 已重连。"
                    elif len(self.lobby_players) >= self.room_size:
                        reject_msg = "房间已满。"
                    else:
                        slot = self._find_open_slot_locked()
                        if slot is None:
                            reject_msg = "房间暂无可用座位。"
                        else:
                            now = time.time()
                            reconnect_key = self._ensure_reconnect_key_locked(slot)
                            self.lobby_players[slot] = remote_name
                            self.clients[slot] = {
                                "sock": conn,
                                "buffer": buffer,
                                "name": remote_name,
                                "last_seen": now,
                                "net_state": "online",
                            }

                if reject_msg is not None or slot is None:
                    _send_json(conn, {"type": "error", "message": reject_msg or "加入房间失败。"})
                    conn.close()
                    continue

                _send_json(
                    conn,
                    {
                        "type": "welcome",
                        "player_index": slot,
                        "room_size": self.room_size,
                        "reconnect_key": reconnect_key,
                        "rejoined": is_rejoin,
                    },
                )
                threading.Thread(target=self._client_loop, args=(slot,), daemon=True).start()
                if game_started:
                    self._broadcast_state()
                else:
                    self._broadcast_lobby_state()
                    self._try_start_game()
            except Exception as exc:  # pragma: no cover
                self.error = f"接入异常: {exc}"
                try:
                    conn.close()
                except Exception:
                    pass

    def _drop_client(self, player_idx: int, disconnected_text: str) -> None:
        client: Optional[Dict[str, Any]] = None
        game_started = False
        name = f"玩家{player_idx + 1}"
        advance_turn = False
        with self.lock:
            client = self.clients.pop(player_idx, None)
            game_started = self.engine is not None
            if client is not None:
                name = str(client.get("name", name))
            if not game_started and player_idx in self.lobby_players:
                self.lobby_players.pop(player_idx, None)
                self.reconnect_keys.pop(player_idx, None)
            if game_started and self.engine is not None:
                self.engine.skip_turns[player_idx] = 10**9
                self.engine._log(f"{name} 掉线，后续回合将自动跳过。")
                self.engine.on_player_disconnected(player_idx)
                if (
                    self.engine.current_player == player_idx
                    and self.engine._pending_waiting_player() is None
                ):
                    advance_turn = True
            self.error = f"{name}{disconnected_text}"

            if advance_turn and self.engine is not None and self.engine.winner is None:
                self.engine._end_turn_internal()

        if client is not None:
            sock = client.get("sock")
            if isinstance(sock, socket.socket):
                try:
                    sock.shutdown(socket.SHUT_RDWR)
                except Exception:
                    pass
                try:
                    sock.close()
                except Exception:
                    pass

        if game_started:
            self._broadcast_state()
        else:
            self._broadcast_lobby_state()

    def _client_loop(self, player_idx: int) -> None:
        while self.running:
            with self.lock:
                client = self.clients.get(player_idx)
                if client is None:
                    return
                conn = client["sock"]
                buffer = client["buffer"]

            try:
                msg, buffer, closed = _recv_json_nonblocking(conn, buffer)
                status_recovered = False
                game_started = False
                with self.lock:
                    if player_idx in self.clients:
                        info = self.clients[player_idx]
                        info["buffer"] = buffer
                        if msg is not None:
                            info["last_seen"] = time.time()
                            if str(info.get("net_state", "online")) != "online":
                                info["net_state"] = "online"
                                status_recovered = True
                        game_started = self.engine is not None
                if closed:
                    self._drop_client(player_idx, " 已断开连接。")
                    return
                if msg is None:
                    continue

                if status_recovered:
                    if game_started:
                        self._broadcast_state()
                    else:
                        self._broadcast_lobby_state()

                mtype = msg.get("type")
                if mtype == "h":
                    continue
                if mtype == "bye":
                    self._drop_client(player_idx, " 已结束会话。")
                    return
                if mtype == "action":
                    self.apply_action(player_idx, msg.get("data", {}))
                elif mtype == "_invalid":
                    _send_json(conn, {"type": "error", "message": "JSON 格式无效。"})
            except Exception:
                self._drop_client(player_idx, " 网络异常断开。")
                return

    def _broadcast_state(self) -> None:
        with self.lock:
            engine = self.engine
            if engine is None:
                return
            clients_snapshot = {
                idx: info["sock"]
                for idx, info in self.clients.items()
            }

        for idx, sock in clients_snapshot.items():
            try:
                client_state = engine.serialize_state(
                    viewer_idx=idx,
                    reveal_all_hands=False,
                    mode="client",
                )
                client_state["room_size"] = self.room_size
                self._decorate_state_with_player_status(client_state, game_started=True)
                _send_json(sock, {"type": "state", "state": client_state})
            except Exception:
                pass

    def apply_action(self, player_idx: int, action: Dict[str, Any]) -> Tuple[bool, str]:
        with self.lock:
            if self.engine is None:
                return False, "房间人数未满，无法出牌。"
            ok, msg = self.engine.apply_action(player_idx, action)
            err_sock = None
            is_local_host_action = self.include_host_player and player_idx == 0
            if not ok and not is_local_host_action:
                client = self.clients.get(player_idx)
                if client is not None:
                    err_sock = client["sock"]

        if ok:
            self._broadcast_state()
        elif err_sock is not None:
            try:
                _send_json(err_sock, {"type": "error", "message": msg})
            except Exception:
                pass
        return ok, msg

    def get_host_state(self) -> Dict[str, Any]:
        with self.lock:
            engine = self.engine
        if engine is None:
            state = self._build_lobby_state(viewer_idx=0, mode="host")
            state["message"] = f"主机已开启 0.0.0.0:{self.port}。{state['message']}"
            return state
        state = engine.serialize_state(viewer_idx=0, reveal_all_hands=False, mode="host")
        state["room_size"] = self.room_size
        self._decorate_state_with_player_status(state, game_started=True)
        return state

    def stop(self) -> None:
        self.running = False
        with self.lock:
            clients = list(self.clients.values())
            self.clients.clear()

        for client in clients:
            sock = client.get("sock")
            if isinstance(sock, socket.socket):
                try:
                    sock.shutdown(socket.SHUT_RDWR)
                except Exception:
                    pass
                try:
                    sock.close()
                except Exception:
                    pass

        if self.listener is not None:
            try:
                self.listener.close()
            except Exception:
                pass


class ClientConnection:
    def __init__(
        self,
        host: str,
        port: int,
        name: str,
        resume_index: Optional[int] = None,
        resume_key: str = "",
    ) -> None:
        self.host = _normalize_host_input(host)
        self.port = port
        self.name = name
        self.sock: Optional[socket.socket] = None
        self.recv_buffer = b""
        self.state: Optional[Dict[str, Any]] = None
        self.error: Optional[str] = None
        self.my_index: Optional[int] = None
        self.room_size: Optional[int] = None
        self.lock = threading.Lock()
        self.send_lock = threading.Lock()
        self.running = False
        self.resume_index = int(resume_index) if resume_index is not None else None
        self.resume_key = str(resume_key).strip()

    def _send_packet(self, payload: Dict[str, Any]) -> None:
        sock = self.sock
        if sock is None:
            raise ConnectionError("尚未连接到主机。")
        with self.send_lock:
            _send_json(sock, payload)

    def connect(self) -> None:
        self.sock = _open_tcp_connection(self.host, self.port, timeout_seconds=3.0)
        self.running = True
        join_payload: Dict[str, Any] = {"type": "join", "name": self.name}
        if self.resume_index is not None:
            join_payload["resume_index"] = int(self.resume_index)
        if self.resume_key:
            join_payload["resume_key"] = self.resume_key
        self._send_packet(join_payload)
        threading.Thread(target=self._recv_loop, daemon=True).start()
        threading.Thread(target=self._heartbeat_loop, daemon=True).start()

    def _recv_loop(self) -> None:
        while self.running:
            sock = self.sock
            if sock is None:
                return
            try:
                msg, self.recv_buffer, closed = _recv_json_nonblocking(sock, self.recv_buffer)
                if closed:
                    with self.lock:
                        self.error = "与主机连接已断开。"
                    return
                if msg is None:
                    continue

                mtype = msg.get("type")
                with self.lock:
                    if mtype == "welcome":
                        self.my_index = int(msg.get("player_index", 1))
                        self.room_size = int(msg.get("room_size", 2))
                        self.resume_index = self.my_index
                        key = str(msg.get("reconnect_key", "")).strip()
                        if key:
                            self.resume_key = key
                    elif mtype == "state":
                        self.state = msg.get("state")
                    elif mtype == "error":
                        self.error = str(msg.get("message", "未知错误"))
                    elif mtype == "_invalid":
                        self.error = "收到无效 JSON 数据。"
            except Exception as exc:  # pragma: no cover
                with self.lock:
                    self.error = f"网络接收异常: {exc}"
                return

    def _heartbeat_loop(self) -> None:
        while self.running:
            try:
                self._send_packet({"type": "h"})
            except Exception as exc:
                with self.lock:
                    self.error = f"心跳发送异常: {exc}"
                return
            time.sleep(HEARTBEAT_INTERVAL_SECONDS)

    def send_action(self, action: Dict[str, Any]) -> Tuple[bool, str]:
        try:
            self._send_packet({"type": "action", "data": action})
            return True, "操作已发送。"
        except Exception as exc:
            return False, f"发送失败: {exc}"

    def get_state(self) -> Dict[str, Any]:
        with self.lock:
            if self.state is not None:
                return self.state
            return {
                "mode": "client",
                "game_started": False,
                "message": "已连接，等待主机凑齐人数并开始对局...",
                "you_index": self.my_index,
                "room_size": self.room_size or 2,
                "players": [],
                "board": {},
                "log": [self.error] if self.error else [],
            }

    def wait_for_server_ready(self, timeout_seconds: float = 5.0) -> Tuple[bool, str]:
        deadline = time.time() + max(0.5, float(timeout_seconds))
        while time.time() < deadline:
            with self.lock:
                if self.my_index is not None:
                    return True, ""
                err = self.error
            if err:
                return False, str(err)
            if not self.running:
                return False, "与主机连接已断开。"
            time.sleep(0.05)

        with self.lock:
            err = self.error
        if err:
            return False, str(err)
        return False, "连接超时，未收到服务器确认。"

    def get_resume_info(self) -> Tuple[Optional[int], str]:
        with self.lock:
            return self.resume_index, self.resume_key

    def close(self) -> None:
        self.running = False
        if self.sock is not None:
            try:
                self._send_packet({"type": "bye"})
            except Exception:
                pass
            try:
                self.sock.shutdown(socket.SHUT_RDWR)
            except Exception:
                pass
            try:
                self.sock.close()
            except Exception:
                pass


class ClientController:
    def __init__(
        self,
        host: str,
        port: int,
        name: str,
        resume_index: Optional[int] = None,
        resume_key: str = "",
    ) -> None:
        self.conn = ClientConnection(
            host=host,
            port=port,
            name=name,
            resume_index=resume_index,
            resume_key=resume_key,
        )
        self.conn.connect()

    def get_state(self) -> Dict[str, Any]:
        return self.conn.get_state()

    def act(self, action: Dict[str, Any]) -> Tuple[bool, str]:
        return self.conn.send_action(action)

    def wait_ready(self, timeout_seconds: float = 5.0) -> Tuple[bool, str]:
        return self.conn.wait_for_server_ready(timeout_seconds)

    def get_resume_info(self) -> Tuple[Optional[int], str]:
        return self.conn.get_resume_info()

    def close(self) -> None:
        self.conn.close()


class ChemGameApp(tk.Tk):
    def __init__(self) -> None:
        super().__init__()
        self.title("离子风暴 - 数字版")
        screen_w = max(1024, int(self.winfo_screenwidth()))
        screen_h = max(720, int(self.winfo_screenheight()))
        init_w = min(1320, screen_w - 48)
        init_h = min(820, screen_h - 88)
        self.geometry(f"{init_w}x{init_h}+16+16")

        self.controller: Optional[Any] = None
        self.last_state: Optional[Dict[str, Any]] = None
        self.hand_cards_by_index: List[str] = []
        self._resize_job: Optional[str] = None
        self._layout_bucket: Tuple[int, int] = (-1, -1)
        self.resume_cache: Dict[Tuple[str, int, str], Tuple[Optional[int], str]] = {}

        self.status_var = tk.StringVar(value="就绪。")
        self.selected_card_var = tk.StringVar(value="当前选中: 无")

        self.local_names_var = tk.StringVar(value="玩家1,玩家2")
        self.local_player_count_var = tk.StringVar(value="2")
        self.local_hand_size_var = tk.StringVar(value="10")

        self.remote_server_host_var = tk.StringVar(value="127.0.0.1")
        self.remote_name_var = tk.StringVar(value="玩家")
        self.remote_room_size_var = tk.StringVar(value="3")
        self.remote_hand_size_var = tk.StringVar(value="10")

        self.join_name_var = tk.StringVar(value="玩家")
        self.join_host_var = tk.StringVar(value="127.0.0.1")
        self.join_port_var = tk.StringVar(value="")

        self.count_var = tk.StringVar(value="1")
        self.count_spin: Optional[tk.Spinbox] = None
        self.btn_play_primary: Optional[ttk.Button] = None
        self.btn_play_wangzha: Optional[ttk.Button] = None
        self._can_play_controls = False
        self._awaiting_response_mode = False
        self._response_prompt_token: Optional[Tuple[int, int, int, str]] = None
        self.setup_panel: Optional[ttk.LabelFrame] = None
        self.action_frame: Optional[ttk.LabelFrame] = None
        self.players_table_frame: Optional[ttk.Frame] = None

        self._build_setup_panel()
        self._build_game_panel()
        self._set_action_controls_enabled(False, False)
        self.bind("<Configure>", self._on_window_resize)
        self.minsize(860, 540)
        self.after(80, self._apply_responsive_layout)
        self._poll_state()
        self.protocol("WM_DELETE_WINDOW", self._on_close)

    def _build_setup_panel(self) -> None:
        setup = ttk.LabelFrame(self, text="对局设置")
        self.setup_panel = setup
        setup.pack(fill="x", padx=8, pady=8)

        mode_row = ttk.Frame(setup)
        mode_row.pack(fill="x", padx=4, pady=(4, 2))
        # ttk.Button 的 width 以字符单位计，对中文偏窄，这里放大一倍保证可读性。
        mode_btn_width = len("向服务器申请联机") * 2
        ttk.Button(
            mode_row,
            text="本地对局",
            width=mode_btn_width,
            command=self._open_local_setup_dialog,
        ).grid(
            row=0, column=0, sticky="w", padx=2, pady=2
        )
        ttk.Button(
            mode_row,
            text="向服务器申请联机",
            width=mode_btn_width,
            command=self._open_remote_setup_dialog_async,
        ).grid(
            row=0, column=1, sticky="w", padx=2, pady=2
        )
        ttk.Button(
            mode_row,
            text="加入服务器房间",
            width=mode_btn_width,
            command=self._open_join_setup_dialog_async,
        ).grid(
            row=0, column=2, sticky="w", padx=2, pady=2
        )

        hint_row = ttk.Frame(setup)
        hint_row.pack(fill="x", padx=6, pady=(0, 2))
        ttk.Label(
            hint_row,
            text="点击上方按钮后会弹出详细设置窗口，再开始对应模式。",
            foreground="#3f4f63",
        ).pack(anchor="w")

        bottom_row = ttk.Frame(setup)
        bottom_row.pack(fill="x", padx=4, pady=(2, 4))
        bottom_row.columnconfigure(0, weight=1)
        ttk.Label(bottom_row, textvariable=self.status_var, foreground="#0b4f6c").grid(row=0, column=0, sticky="w", padx=(0, 8), pady=2)
        ttk.Button(bottom_row, text="停止当前会话", command=self._stop_session).grid(row=0, column=1, sticky="e", pady=2)

    def _center_dialog(self, dialog: tk.Toplevel) -> None:
        self.update_idletasks()
        dialog.update_idletasks()
        parent_x = int(self.winfo_rootx())
        parent_y = int(self.winfo_rooty())
        parent_w = max(1, int(self.winfo_width()))
        parent_h = max(1, int(self.winfo_height()))
        dialog_w = max(1, int(dialog.winfo_reqwidth()))
        dialog_h = max(1, int(dialog.winfo_reqheight()))
        x = parent_x + max(0, (parent_w - dialog_w) // 2)
        y = parent_y + max(0, (parent_h - dialog_h) // 2)
        dialog.geometry(f"+{x}+{y}")

    def _open_local_setup_dialog(self) -> None:
        dialog = tk.Toplevel(self)
        dialog.title("本地对局设置")
        dialog.transient(self)
        dialog.resizable(False, False)

        names_var = tk.StringVar(value=self.local_names_var.get())
        player_count_var = tk.StringVar(value=self.local_player_count_var.get())
        hand_size_var = tk.StringVar(value=self.local_hand_size_var.get())

        body = ttk.Frame(dialog, padding=10)
        body.pack(fill="both", expand=True)
        body.columnconfigure(1, weight=1)

        ttk.Label(body, text="玩家名(逗号分隔)").grid(row=0, column=0, sticky="w", padx=(0, 6), pady=3)
        names_entry = ttk.Entry(body, textvariable=names_var, width=38)
        names_entry.grid(row=0, column=1, sticky="ew", pady=3)

        ttk.Label(body, text="游戏人数").grid(row=1, column=0, sticky="w", padx=(0, 6), pady=3)
        ttk.Spinbox(body, from_=2, to=8, textvariable=player_count_var, width=7).grid(
            row=1, column=1, sticky="w", pady=3
        )

        ttk.Label(body, text="初始手牌数").grid(row=2, column=0, sticky="w", padx=(0, 6), pady=3)
        ttk.Spinbox(body, from_=2, to=10, textvariable=hand_size_var, width=7).grid(
            row=2, column=1, sticky="w", pady=3
        )

        ttk.Label(
            body,
            text="留空玩家名将自动生成“玩家1,玩家2...”",
            foreground="#3f4f63",
        ).grid(row=3, column=0, columnspan=2, sticky="w", pady=(2, 6))

        btn_row = ttk.Frame(body)
        btn_row.grid(row=4, column=0, columnspan=2, sticky="ew")
        btn_row.columnconfigure(0, weight=1)
        btn_row.columnconfigure(1, weight=1)

        def on_confirm() -> None:
            self.local_names_var.set(names_var.get())
            self.local_player_count_var.set(player_count_var.get())
            self.local_hand_size_var.set(hand_size_var.get())
            before = self.controller
            self._start_local()
            after = self.controller
            if after is not before and after is not None:
                dialog.destroy()

        ttk.Button(btn_row, text="取消", command=dialog.destroy).grid(row=0, column=0, sticky="ew", padx=(0, 4))
        ttk.Button(btn_row, text="开始本地对局", command=on_confirm).grid(row=0, column=1, sticky="ew")

        dialog.bind("<Return>", lambda _e: on_confirm())
        dialog.bind("<Escape>", lambda _e: dialog.destroy())
        dialog.protocol("WM_DELETE_WINDOW", dialog.destroy)
        self._center_dialog(dialog)
        dialog.grab_set()
        names_entry.focus_set()
        self.wait_window(dialog)

    def _show_remote_room_access_dialog(self, host: str, port: int) -> None:
        dialog = tk.Toplevel(self)
        dialog.title("房间信息")
        dialog.transient(self)
        dialog.resizable(False, False)

        body = ttk.Frame(dialog, padding=10)
        body.pack(fill="both", expand=True)
        body.columnconfigure(1, weight=1)

        ip_value = str(host).strip() or "127.0.0.1"
        port_value = str(int(port))

        ttk.Label(body, text="IP地址").grid(row=0, column=0, sticky="w", padx=(0, 6), pady=3)
        ip_text = tk.Text(body, width=28, height=1, wrap="none")
        ip_text.grid(row=0, column=1, sticky="ew", pady=3)
        ip_text.insert("1.0", ip_value)
        ip_text.config(state="disabled")

        ttk.Label(body, text="端口").grid(row=1, column=0, sticky="w", padx=(0, 6), pady=3)
        port_text = tk.Text(body, width=28, height=1, wrap="none")
        port_text.grid(row=1, column=1, sticky="ew", pady=3)
        port_text.insert("1.0", port_value)
        port_text.config(state="disabled")

        def copy_value(value: str, label: str) -> None:
            try:
                self.clipboard_clear()
                self.clipboard_append(value)
                self.update_idletasks()
                self._set_status(f"已复制{label}：{value}")
            except Exception:
                self._set_status(f"{label}复制失败。")

        copy_row = ttk.Frame(body)
        copy_row.grid(row=2, column=0, columnspan=2, sticky="ew", pady=(2, 6))
        copy_row.columnconfigure(0, weight=1)
        copy_row.columnconfigure(1, weight=1)
        ttk.Button(copy_row, text="复制IP", command=lambda: copy_value(ip_value, "IP")).grid(
            row=0, column=0, sticky="ew", padx=(0, 4)
        )
        ttk.Button(copy_row, text="复制端口", command=lambda: copy_value(port_value, "端口")).grid(
            row=0, column=1, sticky="ew"
        )

        ttk.Label(
            body,
            text="房间信息只显示一次，此后无法再次查看。\n若房间信息丢失请重新申请房间。",
            foreground="#3f4f63",
        ).grid(row=3, column=0, columnspan=2, sticky="w", pady=(0, 6))

        ttk.Button(body, text="关闭", command=dialog.destroy).grid(row=4, column=0, columnspan=2, sticky="ew")
        dialog.bind("<Escape>", lambda _e: dialog.destroy())
        self._center_dialog(dialog)
        dialog.lift()
        dialog.focus_force()

    def _open_remote_setup_dialog(self) -> None:
        dialog = tk.Toplevel(self)
        dialog.title("向服务器申请联机")
        dialog.transient(self)
        dialog.resizable(False, False)

        server_host_var = tk.StringVar(value=self.remote_server_host_var.get())
        name_var = tk.StringVar(value=self.remote_name_var.get())
        room_size_var = tk.StringVar(value=self.remote_room_size_var.get())
        hand_size_var = tk.StringVar(value=self.remote_hand_size_var.get())

        body = ttk.Frame(dialog, padding=10)
        body.pack(fill="both", expand=True)
        body.columnconfigure(1, weight=1)

        ttk.Label(body, text="服务器IP").grid(row=0, column=0, sticky="w", padx=(0, 6), pady=3)
        ttk.Entry(body, textvariable=server_host_var, width=24).grid(row=0, column=1, sticky="ew", pady=3)

        ttk.Label(body, text="你的昵称").grid(row=1, column=0, sticky="w", padx=(0, 6), pady=3)
        ttk.Entry(body, textvariable=name_var, width=24).grid(row=1, column=1, sticky="ew", pady=3)

        ttk.Label(body, text="房间人数").grid(row=2, column=0, sticky="w", padx=(0, 6), pady=3)
        ttk.Spinbox(body, from_=2, to=8, textvariable=room_size_var, width=7).grid(
            row=2, column=1, sticky="w", pady=3
        )

        ttk.Label(body, text="初始手牌数").grid(row=3, column=0, sticky="w", padx=(0, 6), pady=3)
        ttk.Spinbox(body, from_=2, to=10, textvariable=hand_size_var, width=7).grid(
            row=3, column=1, sticky="w", pady=3
        )

        ttk.Label(
            body,
            text="程序会连接服务器主端口 5000 并申请新的对局端口。",
            foreground="#3f4f63",
        ).grid(row=4, column=0, columnspan=2, sticky="w", pady=(2, 6))

        btn_row = ttk.Frame(body)
        btn_row.grid(row=5, column=0, columnspan=2, sticky="ew")
        btn_row.columnconfigure(0, weight=1)
        btn_row.columnconfigure(1, weight=1)

        def on_confirm() -> None:
            self.remote_server_host_var.set(server_host_var.get())
            self.remote_name_var.set(name_var.get())
            self.remote_room_size_var.set(room_size_var.get())
            self.remote_hand_size_var.set(hand_size_var.get())
            before = self.controller
            self._start_remote_host()
            after = self.controller
            if after is not before and after is not None:
                dialog.destroy()

        ttk.Button(btn_row, text="取消", command=dialog.destroy).grid(row=0, column=0, sticky="ew", padx=(0, 4))
        ttk.Button(btn_row, text="申请并加入对局", command=on_confirm).grid(row=0, column=1, sticky="ew")

        dialog.bind("<Return>", lambda _e: on_confirm())
        dialog.bind("<Escape>", lambda _e: dialog.destroy())
        dialog.protocol("WM_DELETE_WINDOW", dialog.destroy)
        self._center_dialog(dialog)
        dialog.grab_set()
        self.wait_window(dialog)

    def _open_remote_setup_dialog_async(self) -> None:
        dialog = tk.Toplevel(self)
        dialog.title("向服务器申请联机")
        dialog.transient(self)
        dialog.resizable(False, False)

        server_host_var = tk.StringVar(value=self.remote_server_host_var.get())
        name_var = tk.StringVar(value=self.remote_name_var.get())
        room_size_var = tk.StringVar(value=self.remote_room_size_var.get())
        hand_size_var = tk.StringVar(value=self.remote_hand_size_var.get())
        tip_var = tk.StringVar(value="程序会连接服务器主端口 5000 并申请新的对局端口。")

        body = ttk.Frame(dialog, padding=10)
        body.pack(fill="both", expand=True)
        body.columnconfigure(1, weight=1)

        ttk.Label(body, text="服务器IP").grid(row=0, column=0, sticky="w", padx=(0, 6), pady=3)
        server_host_entry = ttk.Entry(body, textvariable=server_host_var, width=24)
        server_host_entry.grid(row=0, column=1, sticky="ew", pady=3)

        ttk.Label(body, text="你的昵称").grid(row=1, column=0, sticky="w", padx=(0, 6), pady=3)
        name_entry = ttk.Entry(body, textvariable=name_var, width=24)
        name_entry.grid(row=1, column=1, sticky="ew", pady=3)

        ttk.Label(body, text="房间人数").grid(row=2, column=0, sticky="w", padx=(0, 6), pady=3)
        room_size_spin = ttk.Spinbox(body, from_=2, to=8, textvariable=room_size_var, width=7)
        room_size_spin.grid(row=2, column=1, sticky="w", pady=3)

        ttk.Label(body, text="初始手牌数").grid(row=3, column=0, sticky="w", padx=(0, 6), pady=3)
        hand_size_spin = ttk.Spinbox(body, from_=2, to=10, textvariable=hand_size_var, width=7)
        hand_size_spin.grid(row=3, column=1, sticky="w", pady=3)

        ttk.Label(body, textvariable=tip_var, foreground="#3f4f63").grid(
            row=4, column=0, columnspan=2, sticky="w", pady=(2, 6)
        )

        btn_row = ttk.Frame(body)
        btn_row.grid(row=5, column=0, columnspan=2, sticky="ew")
        btn_row.columnconfigure(0, weight=1)
        btn_row.columnconfigure(1, weight=1)

        input_widgets = [server_host_entry, name_entry, room_size_spin, hand_size_spin]
        spinner_frames = ["◐", "◓", "◑", "◒"]
        pending = {"running": False, "job": None, "frame": 0}

        def set_pending(running: bool) -> None:
            pending["running"] = running
            for widget in input_widgets:
                try:
                    widget.configure(state=("disabled" if running else "normal"))
                except Exception:
                    pass
            if running:
                btn_cancel.state(["disabled"])
                btn_confirm.state(["disabled"])
                pending["frame"] = 0

                def tick() -> None:
                    if not pending["running"] or not dialog.winfo_exists():
                        return
                    frame = spinner_frames[pending["frame"] % len(spinner_frames)]
                    pending["frame"] += 1
                    btn_confirm.configure(text=f"{frame} 申请并加入对局")
                    pending["job"] = dialog.after(120, tick)

                tick()
            else:
                job = pending.get("job")
                if job is not None:
                    try:
                        dialog.after_cancel(job)
                    except Exception:
                        pass
                pending["job"] = None
                btn_cancel.state(["!disabled"])
                btn_confirm.state(["!disabled"])
                btn_confirm.configure(text="申请并加入对局")

        def close_dialog() -> None:
            if pending["running"]:
                return
            dialog.destroy()

        def on_confirm() -> None:
            if pending["running"]:
                return
            raw_server_host = server_host_var.get().strip() or "127.0.0.1"
            server_host, embedded_port = _parse_host_input(raw_server_host)
            if embedded_port is not None and embedded_port != 5000:
                messagebox.showerror("错误", "服务器主端口固定为 5000，请仅填写 IP，或填写 IP:5000。")
                return
            creator_name = name_var.get().strip() or "玩家"
            try:
                room_size = int(room_size_var.get().strip())
            except ValueError:
                messagebox.showerror("错误", "远程房间人数输入无效。")
                return
            if room_size < 2 or room_size > 8:
                messagebox.showerror("错误", "远程房间人数必须在 2~8 之间。")
                return
            try:
                initial_hand_size = int(hand_size_var.get().strip())
            except ValueError:
                messagebox.showerror("错误", "远程初始手牌数输入无效。")
                return
            if initial_hand_size < 2 or initial_hand_size > 10:
                messagebox.showerror("错误", "远程初始手牌数必须在 2~10 之间。")
                return

            self.remote_server_host_var.set(server_host)
            self.remote_name_var.set(creator_name)
            self.remote_room_size_var.set(str(room_size))
            self.remote_hand_size_var.set(str(initial_hand_size))
            tip_var.set("正在向服务器申请房间，请稍候...")
            set_pending(True)

            def worker() -> None:
                try:
                    assigned_port = self._request_remote_room_port(
                        server_host=server_host,
                        room_size=room_size,
                        initial_hand_size=initial_hand_size,
                    )
                    controller, connect_err = self._create_verified_client_controller(
                        host=server_host,
                        port=int(assigned_port),
                        name=creator_name,
                        timeout_seconds=5.0,
                    )
                    if controller is None:
                        raise RuntimeError(connect_err or "未收到房间服务器确认。")
                except Exception as exc:
                    def fail_callback() -> None:
                        if not dialog.winfo_exists():
                            return
                        set_pending(False)
                        tip_var.set("申请失败，请检查服务器地址后重试。")
                        messagebox.showerror("错误", f"远程联机失败: {exc}")

                    self.after(0, fail_callback)
                    return

                def success_callback() -> None:
                    if not dialog.winfo_exists():
                        try:
                            controller.close()
                        except Exception:
                            pass
                        return
                    self._adopt_connected_controller(
                        controller,
                        host=server_host,
                        port=int(assigned_port),
                        name=creator_name,
                        created_room=True,
                        show_access=True,
                    )
                    set_pending(False)
                    tip_var.set("连接成功，可继续在本窗口修改参数后再次申请。")
                    if dialog.winfo_exists():
                        dialog.destroy()

                self.after(0, success_callback)

            threading.Thread(target=worker, daemon=True).start()

        btn_cancel = ttk.Button(btn_row, text="取消", command=close_dialog)
        btn_cancel.grid(row=0, column=0, sticky="ew", padx=(0, 4))
        btn_confirm = ttk.Button(btn_row, text="申请并加入对局", command=on_confirm)
        btn_confirm.grid(row=0, column=1, sticky="ew")

        dialog.bind("<Return>", lambda _e: on_confirm())
        dialog.bind("<Escape>", lambda _e: close_dialog())
        dialog.protocol("WM_DELETE_WINDOW", close_dialog)
        self._center_dialog(dialog)
        dialog.grab_set()
        self.wait_window(dialog)

    def _open_join_setup_dialog_async(self) -> None:
        dialog = tk.Toplevel(self)
        dialog.title("加入服务器房间")
        dialog.transient(self)
        dialog.resizable(False, False)

        name_var = tk.StringVar(value=self.join_name_var.get())
        host_var = tk.StringVar(value=self.join_host_var.get())
        port_var = tk.StringVar(value=self.join_port_var.get())
        tip_var = tk.StringVar(value="仅在收到服务器欢迎确认后才算连接成功。注意：5000 是主端口，不是对局端口。")

        body = ttk.Frame(dialog, padding=10)
        body.pack(fill="both", expand=True)
        body.columnconfigure(1, weight=1)

        ttk.Label(body, text="你的昵称").grid(row=0, column=0, sticky="w", padx=(0, 6), pady=3)
        name_entry = ttk.Entry(body, textvariable=name_var, width=24)
        name_entry.grid(row=0, column=1, sticky="ew", pady=3)

        ttk.Label(body, text="服务器地址").grid(row=1, column=0, sticky="w", padx=(0, 6), pady=3)
        host_entry = ttk.Entry(body, textvariable=host_var, width=24)
        host_entry.grid(row=1, column=1, sticky="ew", pady=3)

        ttk.Label(body, text="对局端口").grid(row=2, column=0, sticky="w", padx=(0, 6), pady=3)
        port_entry = ttk.Entry(body, textvariable=port_var, width=12)
        port_entry.grid(row=2, column=1, sticky="w", pady=3)

        ttk.Label(body, textvariable=tip_var, foreground="#3f4f63").grid(
            row=3, column=0, columnspan=2, sticky="w", pady=(2, 6)
        )

        btn_row = ttk.Frame(body)
        btn_row.grid(row=4, column=0, columnspan=2, sticky="ew")
        btn_row.columnconfigure(0, weight=1)
        btn_row.columnconfigure(1, weight=1)

        input_widgets = [name_entry, host_entry, port_entry]
        spinner_frames = ["◐", "◓", "◑", "◒"]
        pending = {"running": False, "job": None, "frame": 0}

        def set_pending(running: bool) -> None:
            pending["running"] = running
            for widget in input_widgets:
                try:
                    widget.configure(state=("disabled" if running else "normal"))
                except Exception:
                    pass
            if running:
                btn_cancel.state(["disabled"])
                btn_confirm.state(["disabled"])
                pending["frame"] = 0

                def tick() -> None:
                    if not pending["running"] or not dialog.winfo_exists():
                        return
                    frame = spinner_frames[pending["frame"] % len(spinner_frames)]
                    pending["frame"] += 1
                    btn_confirm.configure(text=f"{frame} 加入对局")
                    pending["job"] = dialog.after(120, tick)

                tick()
            else:
                job = pending.get("job")
                if job is not None:
                    try:
                        dialog.after_cancel(job)
                    except Exception:
                        pass
                pending["job"] = None
                btn_cancel.state(["!disabled"])
                btn_confirm.state(["!disabled"])
                btn_confirm.configure(text="加入对局")

        def close_dialog() -> None:
            if pending["running"]:
                return
            dialog.destroy()

        def on_confirm() -> None:
            if pending["running"]:
                return
            raw_host = host_var.get().strip() or "127.0.0.1"
            host, embedded_port = _parse_host_input(raw_host)
            name = name_var.get().strip() or "玩家"
            raw_port = port_var.get().strip()
            if raw_port:
                try:
                    port = int(raw_port)
                except ValueError:
                    messagebox.showerror("错误", "端口输入无效。")
                    return
            elif embedded_port is not None:
                port = int(embedded_port)
            else:
                messagebox.showerror("错误", "端口输入无效。")
                return
            if embedded_port is not None and raw_port and port != int(embedded_port):
                messagebox.showerror("错误", "地址中的端口与“对局端口”输入不一致，请统一后重试。")
                return
            if port <= 0:
                messagebox.showerror("错误", "端口输入无效。")
                return

            if port == 5000:
                messagebox.showerror("错误", "5000 是主端口，不能直接加入对局。请先“向服务器申请联机”或输入房主给出的对局端口。")
                return

            self.join_name_var.set(name)
            self.join_host_var.set(host)
            self.join_port_var.set(str(port))
            tip_var.set("正在连接房间并等待服务器确认，请稍候...")
            set_pending(True)

            def worker() -> None:
                controller, err = self._create_verified_client_controller(
                    host=host,
                    port=port,
                    name=name,
                    timeout_seconds=5.0,
                )
                if controller is None:
                    def fail_callback() -> None:
                        if not dialog.winfo_exists():
                            return
                        set_pending(False)
                        tip_var.set("连接失败，请检查服务器地址和端口后重试。")
                        messagebox.showerror("错误", f"加入房间失败: {err}")

                    self.after(0, fail_callback)
                    return

                def success_callback() -> None:
                    if not dialog.winfo_exists():
                        try:
                            controller.close()
                        except Exception:
                            pass
                        return
                    self._adopt_connected_controller(
                        controller,
                        host=host,
                        port=port,
                        name=name,
                        created_room=False,
                        show_access=False,
                    )
                    set_pending(False)
                    tip_var.set("连接成功，可继续在本窗口修改参数后再次加入。")
                    if dialog.winfo_exists():
                        dialog.destroy()

                self.after(0, success_callback)

            threading.Thread(target=worker, daemon=True).start()

        btn_cancel = ttk.Button(btn_row, text="取消", command=close_dialog)
        btn_cancel.grid(row=0, column=0, sticky="ew", padx=(0, 4))
        btn_confirm = ttk.Button(btn_row, text="加入对局", command=on_confirm)
        btn_confirm.grid(row=0, column=1, sticky="ew")

        dialog.bind("<Return>", lambda _e: on_confirm())
        dialog.bind("<Escape>", lambda _e: close_dialog())
        dialog.protocol("WM_DELETE_WINDOW", close_dialog)
        self._center_dialog(dialog)
        dialog.grab_set()
        self.wait_window(dialog)

    def _open_join_setup_dialog(self) -> None:
        dialog = tk.Toplevel(self)
        dialog.title("加入服务器房间")
        dialog.transient(self)
        dialog.resizable(False, False)

        name_var = tk.StringVar(value=self.join_name_var.get())
        host_var = tk.StringVar(value=self.join_host_var.get())
        port_var = tk.StringVar(value=self.join_port_var.get())

        body = ttk.Frame(dialog, padding=10)
        body.pack(fill="both", expand=True)
        body.columnconfigure(1, weight=1)

        ttk.Label(body, text="你的昵称").grid(row=0, column=0, sticky="w", padx=(0, 6), pady=3)
        ttk.Entry(body, textvariable=name_var, width=24).grid(row=0, column=1, sticky="ew", pady=3)

        ttk.Label(body, text="服务器地址").grid(row=1, column=0, sticky="w", padx=(0, 6), pady=3)
        ttk.Entry(body, textvariable=host_var, width=24).grid(row=1, column=1, sticky="ew", pady=3)

        ttk.Label(body, text="对局端口").grid(row=2, column=0, sticky="w", padx=(0, 6), pady=3)
        ttk.Entry(body, textvariable=port_var, width=12).grid(row=2, column=1, sticky="w", pady=3)

        ttk.Label(
            body,
            text="若与上次地址/端口/昵称一致，会自动尝试恢复原座位。",
            foreground="#3f4f63",
        ).grid(row=3, column=0, columnspan=2, sticky="w", pady=(2, 6))

        btn_row = ttk.Frame(body)
        btn_row.grid(row=4, column=0, columnspan=2, sticky="ew")
        btn_row.columnconfigure(0, weight=1)
        btn_row.columnconfigure(1, weight=1)

        def on_confirm() -> None:
            self.join_name_var.set(name_var.get())
            self.join_host_var.set(host_var.get())
            self.join_port_var.set(port_var.get())
            before = self.controller
            self._join_host()
            after = self.controller
            if after is not before and after is not None:
                dialog.destroy()

        ttk.Button(btn_row, text="取消", command=dialog.destroy).grid(row=0, column=0, sticky="ew", padx=(0, 4))
        ttk.Button(btn_row, text="加入对局", command=on_confirm).grid(row=0, column=1, sticky="ew")

        dialog.bind("<Return>", lambda _e: on_confirm())
        dialog.bind("<Escape>", lambda _e: dialog.destroy())
        dialog.protocol("WM_DELETE_WINDOW", dialog.destroy)
        self._center_dialog(dialog)
        dialog.grab_set()
        self.wait_window(dialog)

    def _build_game_panel(self) -> None:
        main = ttk.Frame(self)
        main.pack(fill="both", expand=True, padx=8, pady=8)

        left = ttk.Frame(main)
        left.pack(side="left", fill="y")
        left.columnconfigure(0, weight=1)
        left.rowconfigure(0, weight=1)
        left.rowconfigure(1, weight=0)
        right = ttk.Frame(main)
        right.pack(side="left", fill="both", expand=True, padx=8)

        action_frame = ttk.LabelFrame(left, text="出牌操作")
        self.action_frame = action_frame
        action_frame.grid(row=1, column=0, sticky="ew", pady=(6, 0))
        action_frame.columnconfigure(0, weight=1)
        action_frame.columnconfigure(1, weight=1)
        ttk.Label(action_frame, textvariable=self.selected_card_var).grid(
            row=0, column=0, columnspan=2, padx=2, pady=2, sticky="w"
        )
        self.btn_play_primary = ttk.Button(action_frame, text="出牌", command=self._play_selected_card)
        self.btn_play_primary.grid(row=5, column=0, padx=2, pady=2, sticky="ew")
        self.btn_play_wangzha = ttk.Button(action_frame, text="王炸(强酸+强碱)", command=self._play_wangzha)
        self.btn_play_wangzha.grid(row=5, column=1, padx=2, pady=2, sticky="ew")

        hand_frame = ttk.LabelFrame(left, text="我的手牌")
        hand_frame.grid(row=0, column=0, sticky="nsew")
        hand_frame.columnconfigure(0, weight=1)
        hand_frame.rowconfigure(0, weight=1)
        self.hand_list = tk.Listbox(hand_frame, width=36, height=18)
        self.hand_list.grid(row=0, column=0, sticky="nsew", padx=(6, 0), pady=6)
        hand_scroll = ttk.Scrollbar(hand_frame, orient="vertical", command=self.hand_list.yview)
        hand_scroll.grid(row=0, column=1, sticky="ns", padx=(0, 6), pady=6)
        self.hand_list.config(yscrollcommand=hand_scroll.set)
        self.hand_list.bind("<<ListboxSelect>>", lambda _e: self._on_hand_select())
        self.hand_list.bind("<Double-1>", lambda _e: self._play_selected_card())

        info_frame = ttk.LabelFrame(right, text="桌面信息")
        info_frame.pack(fill="both", expand=True)

        self.turn_label = ttk.Label(info_frame, text="尚未开始对局。")
        self.turn_label.pack(anchor="w", padx=6, pady=4)
        self.players_table_frame = ttk.Frame(info_frame)
        self.players_table_frame.pack(fill="x", padx=6, pady=4)
        self._render_players_table([], None, None)

        board_frame = ttk.Frame(info_frame)
        board_frame.pack(fill="both", expand=False, padx=6, pady=4)
        board_frame.columnconfigure(0, weight=1)
        board_frame.rowconfigure(0, weight=1)
        self.board_text = tk.Text(board_frame, width=88, height=16, state="disabled")
        self.board_text.grid(row=0, column=0, sticky="nsew")
        board_scroll = ttk.Scrollbar(board_frame, orient="vertical", command=self.board_text.yview)
        board_scroll.grid(row=0, column=1, sticky="ns", padx=(4, 0))
        self.board_text.config(yscrollcommand=board_scroll.set)

        log_frame = ttk.LabelFrame(right, text="对局日志")
        log_frame.pack(fill="both", expand=True, pady=(8, 0))
        log_frame.columnconfigure(0, weight=1)
        log_frame.rowconfigure(0, weight=1)
        self.log_text = tk.Text(log_frame, width=88, height=16, state="disabled")
        self.log_text.grid(row=0, column=0, sticky="nsew", padx=(6, 0), pady=6)
        log_scroll = ttk.Scrollbar(log_frame, orient="vertical", command=self.log_text.yview)
        log_scroll.grid(row=0, column=1, sticky="ns", padx=(0, 6), pady=6)
        self.log_text.config(yscrollcommand=log_scroll.set)

    def _on_window_resize(self, event: tk.Event) -> None:
        if event.widget is not self:
            return
        if self._resize_job is not None:
            try:
                self.after_cancel(self._resize_job)
            except Exception:
                pass
        self._resize_job = self.after(80, self._apply_responsive_layout)

    def _apply_responsive_layout(self) -> None:
        self._resize_job = None
        self.update_idletasks()
        width = max(640, int(self.winfo_width()))
        height = max(460, int(self.winfo_height()))
        bucket = (width // 36, height // 26)
        if bucket == self._layout_bucket:
            return
        self._layout_bucket = bucket

        hand_width = max(28, min(48, width // 42))
        setup_height = self.setup_panel.winfo_height() if self.setup_panel is not None else 190
        action_height = self.action_frame.winfo_reqheight() if self.action_frame is not None else 230
        game_height = max(160, height - setup_height - 48)
        hand_pixels = max(84, game_height - action_height - 14)
        hand_height = max(3, min(36, hand_pixels // 18))
        board_width = max(72, min(140, (width - 280) // 10))
        board_height = max(8, min(20, (game_height - 120) // 24))
        log_height = max(8, min(24, (game_height - 120) // 20))

        self.hand_list.config(width=hand_width, height=hand_height)
        self.board_text.config(width=board_width, height=board_height)
        self.log_text.config(width=board_width, height=log_height)

    def _set_action_controls_enabled(self, can_play: bool, can_end_turn: bool) -> None:
        self._can_play_controls = bool(can_play)
        self._refresh_play_action_buttons()

    def _refresh_play_action_buttons(self) -> None:
        selected_card = self._selected_card_quiet()
        can_play = self._can_play_controls and (not self._awaiting_response_mode)
        hand = self._current_hand()
        has_wangzha = hand.get(t.Acid, 0) >= 1 and hand.get(t.Alk, 0) >= 1

        can_play_selected = False
        if can_play and selected_card is not None:
            if selected_card in t.Ion:
                can_play_selected = self._max_playable_count(selected_card) > 0
            elif selected_card in t.Special or selected_card in t.Function:
                can_play_selected = True

        if self.btn_play_primary is not None:
            self.btn_play_primary.config(state="normal" if can_play_selected else "disabled")
        if self.btn_play_wangzha is not None:
            self.btn_play_wangzha.config(state="normal" if (can_play and has_wangzha) else "disabled")

        if self.count_spin is not None:
            self.count_spin.config(state="disabled")

    def _render_players_table(
        self,
        players: List[Dict[str, Any]],
        current: Optional[int],
        you: Optional[int],
    ) -> None:
        frame = self.players_table_frame
        if frame is None:
            return
        for child in frame.winfo_children():
            child.destroy()

        if not players:
            tk.Label(frame, text="暂无玩家信息", anchor="w").grid(row=0, column=0, sticky="w")
            return

        total_cols = len(players) + 1
        for col in range(total_cols):
            frame.grid_columnconfigure(col, weight=1)

        header_bg = "#eef4fb"
        value_bg = "#ffffff"
        border = {"borderwidth": 1, "relief": "solid", "padx": 6, "pady": 3}

        tk.Label(frame, text="玩家", bg=header_bg, **border).grid(row=0, column=0, sticky="nsew")
        tk.Label(frame, text="手牌数", bg=header_bg, **border).grid(row=1, column=0, sticky="nsew")
        tk.Label(frame, text="状态", bg=header_bg, **border).grid(row=2, column=0, sticky="nsew")

        for idx, player in enumerate(players):
            marker = ""
            if idx == current:
                marker += "【当前】"
            if idx == you:
                marker += "【你】"
            raw_name = player.get("name", "")
            name = str(raw_name).strip() if raw_name is not None else ""
            raw_hand_size = player.get("hand_size", "")
            hand_size = ""
            if raw_hand_size is not None:
                text = str(raw_hand_size).strip()
                if text:
                    hand_size = text
            raw_status = player.get("status", "")
            status = str(raw_status).strip() if raw_status is not None else ""
            if not status and name:
                status = "在线"
            seat_text = f"{idx + 1}号位"
            if name:
                seat_text += f" {name}"
            if marker:
                seat_text += marker
            tk.Label(
                frame,
                text=seat_text,
                bg=header_bg,
                **border,
            ).grid(row=0, column=idx + 1, sticky="nsew")
            tk.Label(frame, text=hand_size, bg=value_bg, **border).grid(
                row=1, column=idx + 1, sticky="nsew"
            )
            tk.Label(frame, text=status, bg=value_bg, **border).grid(
                row=2, column=idx + 1, sticky="nsew"
            )

    def _set_status(self, msg: str) -> None:
        self.status_var.set(msg)

    @staticmethod
    def _resume_cache_key(host: str, port: int, name: str) -> Tuple[str, int, str]:
        return (_normalize_host_input(host).strip().lower(), int(port), name.strip())

    def _get_cached_resume_info(self, host: str, port: int, name: str) -> Tuple[Optional[int], str]:
        key = self._resume_cache_key(host, port, name)
        return self.resume_cache.get(key, (None, ""))

    def _remember_controller_resume_info(self, controller: Optional[Any]) -> None:
        if not isinstance(controller, ClientController):
            return
        try:
            resume_index, resume_key = controller.get_resume_info()
        except Exception:
            return
        host = str(controller.conn.host)
        name = str(controller.conn.name)
        try:
            port = int(controller.conn.port)
        except Exception:
            return
        if resume_index is None and not resume_key:
            return
        cache_key = self._resume_cache_key(host, port, name)
        self.resume_cache[cache_key] = (resume_index, resume_key)

    def _stop_session(self) -> None:
        self._remember_controller_resume_info(self.controller)
        if self.controller is not None:
            try:
                self.controller.close()
            except Exception:
                pass
        self.controller = None
        self.last_state = None
        self.hand_cards_by_index = []
        self._awaiting_response_mode = False
        self._response_prompt_token = None
        self.hand_list.delete(0, tk.END)
        self.selected_card_var.set("当前选中: 无")
        self.count_var.set("1")
        self._set_action_controls_enabled(False, False)
        self._set_status("已停止当前会话。")

    def _start_local(self) -> None:
        try:
            player_count = int(self.local_player_count_var.get().strip())
        except ValueError:
            messagebox.showerror("错误", "本地人数输入无效。")
            return
        if player_count < 2 or player_count > 8:
            messagebox.showerror("错误", "本地人数必须在 2~8 之间。")
            return
        try:
            initial_hand_size = int(self.local_hand_size_var.get().strip())
        except ValueError:
            messagebox.showerror("错误", "初始手牌数输入无效。")
            return
        if initial_hand_size < 2 or initial_hand_size > 10:
            messagebox.showerror("错误", "初始手牌数必须在 2~10 之间。")
            return

        names = [x.strip() for x in self.local_names_var.get().split(",") if x.strip()]
        if not names:
            names = [f"玩家{i + 1}" for i in range(player_count)]
        elif len(names) < player_count:
            for i in range(len(names), player_count):
                names.append(f"玩家{i + 1}")
        elif len(names) > player_count:
            names = names[:player_count]

        self._stop_session()
        self.controller = LocalController(names, initial_hand_size=initial_hand_size)
        self.local_names_var.set(",".join(names))
        self._set_status(f"本地对局已开始，人数 {len(names)}，初始手牌数 {initial_hand_size}。")

    def _request_remote_room_port(self, server_host: str, room_size: int, initial_hand_size: int) -> int:
        payload = {
            "type": "create_room",
            "room_size": int(room_size),
            "initial_hand_size": int(initial_hand_size),
            "protocol": "tcp",
        }
        normalized_host = _normalize_host_input(server_host)
        sock: Optional[socket.socket] = None
        timeout_seconds = 5.0
        try:
            deadline = time.time() + timeout_seconds
            sock = _open_tcp_connection(normalized_host, 5000, timeout_seconds=timeout_seconds)
            _send_json(sock, payload)
            buffer = b""
            while time.time() < deadline:
                msg, buffer, closed = _recv_json_nonblocking(sock, buffer)
                if closed:
                    raise RuntimeError("主服务器连接已断开。")
                if msg is None:
                    time.sleep(0.02)
                    continue
                mtype = str(msg.get("type", "")).strip()
                if mtype == "room_created":
                    try:
                        port = int(msg.get("port", 0))
                    except Exception:
                        port = 0
                    if port <= 0:
                        raise RuntimeError("主服务器返回的房间端口无效。")
                    room_protocol = str(msg.get("protocol", "tcp")).strip().lower() or "tcp"
                    if room_protocol != "tcp":
                        raise RuntimeError(
                            "主服务器分配的是 WebSocket 房间，桌面版 ChemGame.py 无法加入。"
                            "请改用 ChemGame.html 加入，或让房主创建 TCP 房间。"
                        )
                    return port
                if mtype == "error":
                    raise RuntimeError(str(msg.get("message", "主服务器返回错误。")))
                raise RuntimeError("主服务器返回了无法识别的数据。")
            raise RuntimeError("等待主服务器分配端口超时。")
        finally:
            try:
                if sock is not None:
                    sock.close()
            except Exception:
                pass

    def _create_verified_client_controller(
        self,
        host: str,
        port: int,
        name: str,
        timeout_seconds: float = 5.0,
    ) -> Tuple[Optional[ClientController], str]:
        normalized_host = _normalize_host_input(host)
        resume_index, resume_key = self._get_cached_resume_info(
            host=normalized_host,
            port=port,
            name=name,
        )
        try:
            controller = ClientController(
                host=normalized_host,
                port=port,
                name=name,
                resume_index=resume_index,
                resume_key=resume_key,
            )
        except Exception as exc:
            return None, str(exc)

        ok, msg = controller.wait_ready(timeout_seconds=timeout_seconds)
        if not ok:
            try:
                controller.close()
            except Exception:
                pass
            fail_msg = str(msg or "未收到房间服务器欢迎确认。")
            if int(port) == 5000:
                fail_msg = f"{fail_msg}（5000 为主端口，不能直接加入对局）"
            elif "超时" in fail_msg or "欢迎确认" in fail_msg or "连接已断开" in fail_msg:
                fail_msg = (
                    f"{fail_msg}（该端口可能是 WebSocket 房间端口。"
                    "ChemGame.py 仅支持 TCP 房间，请改用 ChemGame.html，或让房主创建 TCP 房间）"
                )
            return None, fail_msg
        return controller, ""

    def _adopt_connected_controller(
        self,
        controller: ClientController,
        host: str,
        port: int,
        name: str,
        *,
        created_room: bool = False,
        show_access: bool = False,
    ) -> None:
        self._stop_session()
        self.controller = controller
        self.join_host_var.set(host)
        self.join_port_var.set(str(int(port)))
        self.join_name_var.set(name)
        if created_room:
            self._set_status(f"远程房间已创建，地址 {host}:{int(port)}。你已作为“{name}”加入。")
        else:
            self._set_status(f"已连接 {host}:{int(port)}，你当前为“{name}”。")
        if show_access:
            self._show_remote_room_access_dialog(host, int(port))

    def _connect_remote_assigned_room(self, server_host: str, creator_name: str, assigned_port: int) -> bool:
        controller, err = self._create_verified_client_controller(
            host=server_host,
            port=int(assigned_port),
            name=creator_name,
            timeout_seconds=5.0,
        )
        if controller is None:
            messagebox.showerror("错误", f"连接远程房间失败: {err}")
            return False
        self._adopt_connected_controller(
            controller,
            host=server_host,
            port=int(assigned_port),
            name=creator_name,
            created_room=True,
            show_access=True,
        )
        return True

    def _start_remote_host(self) -> None:
        raw_server_host = self.remote_server_host_var.get().strip() or "127.0.0.1"
        server_host, embedded_port = _parse_host_input(raw_server_host)
        if embedded_port is not None and embedded_port != 5000:
            messagebox.showerror("错误", "服务器主端口固定为 5000，请仅填写 IP，或填写 IP:5000。")
            return
        creator_name = self.remote_name_var.get().strip() or "玩家"
        try:
            room_size = int(self.remote_room_size_var.get().strip())
        except ValueError:
            messagebox.showerror("错误", "远程房间人数输入无效。")
            return
        if room_size < 2 or room_size > 8:
            messagebox.showerror("错误", "远程房间人数必须在 2~8 之间。")
            return
        try:
            initial_hand_size = int(self.remote_hand_size_var.get().strip())
        except ValueError:
            messagebox.showerror("错误", "远程初始手牌数输入无效。")
            return
        if initial_hand_size < 2 or initial_hand_size > 10:
            messagebox.showerror("错误", "远程初始手牌数必须在 2~10 之间。")
            return

        try:
            assigned_port = self._request_remote_room_port(
                server_host=server_host,
                room_size=room_size,
                initial_hand_size=initial_hand_size,
            )
        except Exception as exc:
            messagebox.showerror("错误", f"远程联机失败: {exc}")
            return

        self._connect_remote_assigned_room(
            server_host=server_host,
            creator_name=creator_name,
            assigned_port=assigned_port,
        )

    def _join_host(self) -> None:
        raw_host = self.join_host_var.get().strip() or "127.0.0.1"
        host, embedded_port = _parse_host_input(raw_host)
        raw_port = self.join_port_var.get().strip()
        if raw_port:
            try:
                port = int(raw_port)
            except ValueError:
                messagebox.showerror("错误", "端口输入无效。")
                return
        elif embedded_port is not None:
            port = int(embedded_port)
            self.join_port_var.set(str(port))
        else:
            messagebox.showerror("错误", "端口输入无效。")
            return
        if embedded_port is not None and raw_port and port != int(embedded_port):
            messagebox.showerror("错误", "地址中的端口与“对局端口”输入不一致，请统一后重试。")
            return
        if port <= 0:
            messagebox.showerror("错误", "端口输入无效。")
            return
        if port == 5000:
            messagebox.showerror("错误", "5000 是主端口，不能直接加入对局。请先“向服务器申请联机”或输入房主给出的对局端口。")
            return
        name = self.join_name_var.get().strip() or "玩家"
        resume_index, resume_key = self._get_cached_resume_info(host=host, port=port, name=name)
        if resume_index is None and not resume_key:
            self._set_status(f"正在连接 {host}:{port}，等待服务器确认...")
        else:
            self._set_status(f"正在连接 {host}:{port}，并尝试恢复原座位...")

        controller, err = self._create_verified_client_controller(
            host=host,
            port=port,
            name=name,
            timeout_seconds=5.0,
        )
        if controller is None:
            messagebox.showerror("错误", f"加入房间失败: {err}")
            return
        self._adopt_connected_controller(
            controller,
            host=host,
            port=port,
            name=name,
            created_room=False,
            show_access=False,
        )

    def _poll_state(self) -> None:
        if self.controller is not None:
            try:
                state = self.controller.get_state()
                self.last_state = state
                self._render_state(state)
                self._remember_controller_resume_info(self.controller)
            except Exception as exc:
                self._set_status(f"状态更新异常: {exc}")
        self.after(400, self._poll_state)

    def _render_state(self, state: Dict[str, Any]) -> None:
        if not state.get("game_started"):
            msg = state.get("message", "等待中...")
            self.turn_label.config(text=msg)
            players = state.get("players", [])
            self._render_players_table(players, None, state.get("you_index"))
            self._set_text(self.board_text, "")
            self._set_text(
                self.log_text,
                "\n".join([_display_text(str(x)) for x in state.get("log", [])]),
                scroll_to_end=True,
            )
            self.hand_cards_by_index = []
            self.hand_list.delete(0, tk.END)
            self.selected_card_var.set("当前选中: 无")
            self.count_var.set("1")
            self._awaiting_response_mode = False
            self._response_prompt_token = None
            self._set_action_controls_enabled(False, False)
            return

        players = state.get("players", [])
        current = state.get("current_player")
        you = state.get("you_index")
        actions = state.get("actions_left", 0)
        can_act = bool(state.get("can_act", False))
        can_end_turn = bool(state.get("can_end_turn", can_act and actions > 0))
        pending = state.get("pending_response", {}) or {}
        pending_active = bool(pending.get("active", False))
        waiting_player = pending.get("awaiting_player")
        awaiting_response = (
            pending_active
            and can_act
            and waiting_player is not None
            and you is not None
            and int(waiting_player) == int(you)
        )
        self._awaiting_response_mode = awaiting_response
        if not awaiting_response:
            self._response_prompt_token = None
        self._set_action_controls_enabled(
            can_play=(can_act and not awaiting_response),
            can_end_turn=(can_end_turn and not awaiting_response),
        )
        winner = state.get("winner")
        deck_size = state.get("deck_size", 0)
        discard_size = state.get("discard_size", 0)
        direction = state.get("direction", 1)

        direction_text = str(state.get("direction_hint", "")).strip()
        if not direction_text:
            direction_text = "按座位顺序" if direction == 1 else "按座位逆序"
        if winner is None:
            current_name = players[current]["name"] if players and current is not None else "?"
            turn_text = (
                f"第 {state.get('turn_number', 0)} 回合 | 当前玩家: {current_name} | 剩余行动: {actions} | {direction_text}"
            )
            if pending_active:
                waiting_name = str(pending.get("awaiting_name", "")).strip() or "某玩家"
                effect_card = str(pending.get("effect_card", "")).strip()
                remaining = int(pending.get("remaining", 0))
                turn_text += (
                    f" | 等待 {waiting_name} 响应 {_display_card_name(effect_card)}"
                    f"（剩余摸牌 {remaining}）"
                )
            self.turn_label.config(text=turn_text)
        else:
            win_name = players[winner]["name"] if players else "?"
            self.turn_label.config(text=f"胜者: {win_name}")

        self._render_players_table(players, current, you)

        hand: Dict[str, int] = {}
        if you is not None and 0 <= you < len(players):
            hand = players[you].get("hand", {}) or {}
        prev_selected_card: Optional[str] = None
        prev_view = self.hand_list.yview()
        cur_sel = self.hand_list.curselection()
        if cur_sel:
            prev_idx = int(cur_sel[0])
            if 0 <= prev_idx < len(self.hand_cards_by_index):
                prev_selected_card = self.hand_cards_by_index[prev_idx]
        new_hand_cards = sorted(hand)
        new_display = [f"{_display_card_name(card)} ×{hand[card]}" for card in new_hand_cards]
        old_display = list(self.hand_list.get(0, tk.END))
        hand_changed = old_display != new_display or self.hand_cards_by_index != new_hand_cards
        if hand_changed:
            self.hand_list.delete(0, tk.END)
            for line in new_display:
                self.hand_list.insert(tk.END, line)
            if prev_view:
                self.hand_list.yview_moveto(prev_view[0])
        self.hand_cards_by_index = new_hand_cards

        if prev_selected_card and prev_selected_card in self.hand_cards_by_index:
            new_idx = self.hand_cards_by_index.index(prev_selected_card)
            need_reselect = hand_changed
            if not need_reselect and cur_sel:
                need_reselect = int(cur_sel[0]) != new_idx
            if need_reselect:
                self.hand_list.selection_clear(0, tk.END)
                self.hand_list.selection_set(new_idx)
                self.hand_list.activate(new_idx)
        elif hand_changed:
            self.hand_list.selection_clear(0, tk.END)
        self._on_hand_select()

        board = state.get("board", {})
        skip_turns = board.get("skip_turns", {}) or {}
        board_lines = [
            f"牌堆: {deck_size} | 弃牌堆: {discard_size}",
            "",
            "【溶液区离子】",
            *self._format_dict_lines(board.get("solution", {})),
            "",
            "【沉淀区】",
            *self._format_dict_lines(board.get("precipitates", {})),
            f"金: {board.get('gold', 0)}",
            f"铀: {board.get('uranium', 0)}",
            "",
            "【气体区】",
            *self._format_dict_lines(board.get("gases", {})),
            "",
            "【弱电解质区】",
            *self._format_dict_lines(board.get("weak_electrolytes", {})),
            "",
            "【跳过队列】",
            *self._format_dict_lines(skip_turns),
        ]
        self._set_text(self.board_text, "\n".join(board_lines), preserve_yview=True)
        self._set_text(
            self.log_text,
            "\n".join([_display_text(str(x)) for x in state.get("log", [])]),
            scroll_to_end=True,
        )
        self._maybe_prompt_pending_response(state)

    @staticmethod
    def _format_dict_lines(items: Dict[str, Any]) -> List[str]:
        if not items:
            return ["(无)"]
        lines: List[str] = []
        for k, v in items.items():
            key = str(k)
            if key in t.initCard:
                disp_key = _display_card_name(key)
            else:
                disp_key = _display_text(key)
            lines.append(f"{disp_key}: {v}")
        return lines

    @staticmethod
    def _set_text(
        widget: tk.Text,
        content: str,
        scroll_to_end: bool = False,
        preserve_yview: bool = False,
    ) -> bool:
        current = widget.get("1.0", "end-1c")
        changed = current != content
        prev_y = widget.yview() if preserve_yview else None
        if changed:
            widget.config(state="normal")
            widget.delete("1.0", tk.END)
            widget.insert("1.0", content)
            widget.config(state="disabled")
            if preserve_yview and prev_y:
                widget.yview_moveto(prev_y[0])
        if scroll_to_end and changed:
            widget.see("end")
        return changed

    def _maybe_prompt_pending_response(self, state: Dict[str, Any]) -> None:
        pending = state.get("pending_response", {}) or {}
        if not bool(pending.get("active", False)):
            return
        if not bool(state.get("can_act", False)):
            return
        you = state.get("you_index")
        waiting_player = pending.get("awaiting_player")
        if you is None or waiting_player is None:
            return
        try:
            if int(you) != int(waiting_player):
                return
        except Exception:
            return

        prompt_id = int(pending.get("id", 0))
        remaining = int(pending.get("remaining", 0))
        effect_card = str(pending.get("effect_card", "")).strip()
        token = (prompt_id, int(waiting_player), remaining, effect_card)
        if self._response_prompt_token == token:
            return
        self._response_prompt_token = token

        source_name = str(pending.get("source_name", "")).strip() or "上家"
        follow_allowed = bool(pending.get("follow_allowed", False))
        counter_allowed = bool(pending.get("counter_allowed", False))

        dialog = tk.Toplevel(self)
        dialog.title("摸牌效果响应")
        dialog.transient(self)
        dialog.resizable(False, False)

        body = ttk.Frame(dialog, padding=10)
        body.pack(fill="both", expand=True)
        ttk.Label(
            body,
            text=(
                f"{source_name} 打出 {_display_card_name(effect_card)}，"
                f"当前轮到你处理摸牌（剩余 {remaining} 张）。"
            ),
            wraplength=420,
            justify="left",
        ).pack(anchor="w", pady=(0, 8))
        ttk.Label(
            body,
            text="可选操作：直接摸牌；或按规则跟牌/加钠反制。",
            foreground="#3f4f63",
        ).pack(anchor="w", pady=(0, 10))

        btn_row = ttk.Frame(body)
        btn_row.pack(fill="x")

        def submit(decision: str) -> None:
            ok = self._dispatch_action({"kind": "respond_draw_effect", "decision": decision})
            if ok:
                try:
                    dialog.destroy()
                except Exception:
                    pass
            else:
                self._response_prompt_token = None

        def close_without_action() -> None:
            self._response_prompt_token = None
            dialog.destroy()

        ttk.Button(btn_row, text="摸牌", command=lambda: submit("draw")).pack(
            side="left", expand=True, fill="x"
        )
        if follow_allowed:
            ttk.Button(btn_row, text="跟牌传递", command=lambda: submit("follow")).pack(
                side="left", expand=True, fill="x", padx=4
            )
        if counter_allowed:
            ttk.Button(btn_row, text="加钠反制", command=lambda: submit("counter")).pack(
                side="left", expand=True, fill="x"
            )

        dialog.bind("<Escape>", lambda _e: close_without_action())
        dialog.protocol("WM_DELETE_WINDOW", close_without_action)
        self._center_dialog(dialog)
        dialog.grab_set()

    def _current_hand(self) -> Dict[str, int]:
        if not self.last_state:
            return {}
        you = self.last_state.get("you_index")
        players = self.last_state.get("players", [])
        try:
            you_idx = int(you)
        except Exception:
            return {}
        if not (0 <= you_idx < len(players)):
            return {}
        hand = players[you_idx].get("hand", {})
        if not isinstance(hand, dict):
            return {}
        return hand

    def _max_playable_count(self, card: str) -> int:
        hand = self._current_hand()
        try:
            return max(0, int(hand.get(card, 0)))
        except Exception:
            return 0

    def _sync_ion_count_control(self, card: Optional[str]) -> None:
        if self.count_spin is None:
            return
        is_ion = card in t.Ion
        max_count = max(1, self._max_playable_count(card)) if is_ion else 1

        try:
            current = int(str(self.count_var.get()).strip())
        except Exception:
            current = 1
        current = min(max(1, current), max_count)
        self.count_var.set(str(current))

        spin_state = "normal" if (self._can_play_controls and is_ion) else "disabled"
        self.count_spin.config(from_=1, to=max_count, state=spin_state)

    def _choose_card_from_list(
        self,
        title: str,
        prompt: str,
        options: List[str],
    ) -> Optional[str]:
        if not options:
            return None
        result: Dict[str, Optional[str]] = {"value": None}

        dialog = tk.Toplevel(self)
        dialog.title(title)
        dialog.transient(self)
        dialog.resizable(False, False)

        ttk.Label(dialog, text=prompt).pack(anchor="w", padx=10, pady=(10, 6))
        listbox = tk.Listbox(dialog, width=34, height=min(10, len(options)), exportselection=False)
        for card in options:
            listbox.insert(tk.END, _display_card_name(card))
        listbox.selection_set(0)
        listbox.activate(0)
        listbox.pack(fill="both", expand=True, padx=10, pady=(0, 8))

        btn_frame = ttk.Frame(dialog)
        btn_frame.pack(fill="x", padx=10, pady=(0, 10))

        def choose() -> None:
            cur = listbox.curselection()
            if not cur:
                return
            result["value"] = options[int(cur[0])]
            dialog.destroy()

        def cancel() -> None:
            dialog.destroy()

        ttk.Button(btn_frame, text="确定", command=choose).pack(side="left", expand=True, fill="x", padx=(0, 4))
        ttk.Button(btn_frame, text="取消", command=cancel).pack(side="left", expand=True, fill="x")
        listbox.bind("<Double-1>", lambda _e: choose())
        dialog.bind("<Return>", lambda _e: choose())
        dialog.bind("<Escape>", lambda _e: cancel())
        dialog.protocol("WM_DELETE_WINDOW", cancel)
        self._center_dialog(dialog)
        dialog.grab_set()
        self.wait_window(dialog)
        return result["value"]

    def _choose_ion_count(self, card: str, max_count: int) -> Optional[int]:
        if max_count <= 0:
            return None
        result: Dict[str, Optional[int]] = {"value": None}

        dialog = tk.Toplevel(self)
        dialog.title("选择离子出牌数量")
        dialog.transient(self)
        dialog.resizable(False, False)

        ttk.Label(
            dialog,
            text=f"请选择 {_display_card_name(card)} 的出牌数量（最多 {max_count} 张）",
        ).pack(anchor="w", padx=10, pady=(10, 6))

        listbox = tk.Listbox(dialog, width=24, height=min(12, max_count), exportselection=False)
        for i in range(1, max_count + 1):
            listbox.insert(tk.END, f"{i} 张")
        listbox.selection_set(0)
        listbox.activate(0)
        listbox.pack(fill="both", expand=True, padx=10, pady=(0, 8))

        quick_frame = ttk.Frame(dialog)
        quick_frame.pack(fill="x", padx=10, pady=(0, 8))

        def focus_count(n: int) -> None:
            idx = min(max(1, n), max_count) - 1
            listbox.selection_clear(0, tk.END)
            listbox.selection_set(idx)
            listbox.activate(idx)
            listbox.see(idx)

        ttk.Button(quick_frame, text="1张", command=lambda: focus_count(1)).pack(side="left", expand=True, fill="x")
        ttk.Button(
            quick_frame,
            text="半数",
            command=lambda: focus_count((max_count + 1) // 2),
        ).pack(side="left", expand=True, fill="x", padx=4)
        ttk.Button(quick_frame, text="全出", command=lambda: focus_count(max_count)).pack(
            side="left", expand=True, fill="x"
        )

        btn_frame = ttk.Frame(dialog)
        btn_frame.pack(fill="x", padx=10, pady=(0, 10))

        def choose() -> None:
            cur = listbox.curselection()
            if not cur:
                return
            result["value"] = int(cur[0]) + 1
            dialog.destroy()

        def cancel() -> None:
            dialog.destroy()

        ttk.Button(btn_frame, text="确定", command=choose).pack(side="left", expand=True, fill="x", padx=(0, 4))
        ttk.Button(btn_frame, text="取消", command=cancel).pack(side="left", expand=True, fill="x")
        listbox.bind("<Double-1>", lambda _e: choose())
        dialog.bind("<Return>", lambda _e: choose())
        dialog.bind("<Escape>", lambda _e: cancel())
        dialog.protocol("WM_DELETE_WINDOW", cancel)
        self._center_dialog(dialog)
        dialog.grab_set()
        self.wait_window(dialog)
        return result["value"]

    def _selected_card(self) -> Optional[str]:
        card = self._selected_card_quiet()
        if card is None:
            self._set_status("请先在手牌区选择一张牌。")
            return None
        return card

    def _selected_card_quiet(self) -> Optional[str]:
        cur = self.hand_list.curselection()
        if not cur:
            return None
        idx = int(cur[0])
        if idx < 0 or idx >= len(self.hand_cards_by_index):
            return None
        return self.hand_cards_by_index[idx]

    def _card_kind_text(self, card: str) -> str:
        if card in t.Ion:
            return "离子牌"
        if card in t.Special:
            return "特殊牌"
        if card in t.Function:
            return "功能牌"
        return "未知牌型"

    def _on_hand_select(self) -> None:
        cur = self.hand_list.curselection()
        if not cur:
            self.selected_card_var.set("当前选中: 无")
            self._refresh_play_action_buttons()
            return
        card = self._selected_card()
        if not card:
            self.selected_card_var.set("当前选中: 无")
            self._refresh_play_action_buttons()
            return
        if card in t.Ion:
            max_count = self._max_playable_count(card)
            self.selected_card_var.set(
                f"当前选中: {_display_card_name(card)}（{self._card_kind_text(card)}，可出 1~{max_count} 张）"
            )
        else:
            self.selected_card_var.set(
                f"当前选中: {_display_card_name(card)}（{self._card_kind_text(card)}）"
            )
        self._refresh_play_action_buttons()

    def _dispatch_action(self, action: Dict[str, Any]) -> bool:
        if self.controller is None:
            self._set_status("当前没有活动会话。")
            return False
        kind = str(action.get("kind", ""))
        if self.last_state is not None:
            can_act = bool(self.last_state.get("can_act", False))
            can_end_turn = bool(self.last_state.get("can_end_turn", can_act))
            if kind == "end_turn" and not can_end_turn:
                self._set_status("当前不能结束回合。请先出牌。")
                return False
            if kind != "end_turn" and not can_act:
                self._set_status("当前不是你的可操作时机。")
                return False
        ok, msg = self.controller.act(action)
        if ok:
            self._set_status(_display_text(str(msg)))
            return True
        else:
            self._set_status(f"操作失败: {_display_text(str(msg))}")
            return False

    def _play_selected_card(self) -> None:
        if self._awaiting_response_mode:
            self._set_status("当前需先处理摸牌响应。")
            return
        card = self._selected_card()
        if not card:
            return
        if card in t.Ion:
            self._play_ion()
            return
        if card in t.Special:
            self._play_special()
            return
        if card in t.Function:
            self._play_operation()
            return
        self._set_status("无法识别该牌的牌型。")

    def _play_ion(self) -> None:
        card = self._selected_card()
        if not card:
            return
        if card not in t.Ion:
            self._set_status("选中的不是离子牌。")
            return
        max_count = self._max_playable_count(card)
        if max_count <= 0:
            self._set_status("当前离子手牌数量不足。")
            return
        if max_count == 1:
            self.count_var.set("1")
            self._dispatch_ion_play(card, 1)
            return
        chosen = self._choose_ion_count(card, max_count)
        if chosen is None:
            return
        self.count_var.set(str(chosen))
        self._dispatch_ion_play(card, chosen)

    def _play_ion_with_current_count(self) -> None:
        card = self._selected_card()
        if not card:
            return
        if card not in t.Ion:
            self._set_status("选中的不是离子牌。")
            return
        max_count = self._max_playable_count(card)
        if max_count <= 0:
            self._set_status("当前离子手牌数量不足。")
            return
        try:
            count = int(self.count_var.get().strip())
        except ValueError:
            count = 1
        count = min(max(1, count), max_count)
        self.count_var.set(str(count))
        self._dispatch_ion_play(card, count)

    def _dispatch_ion_play(self, card: str, count: int) -> None:
        self._dispatch_action({"kind": "play_ion", "card": card, "count": count})

    def _play_all_selected_ion(self) -> None:
        card = self._selected_card()
        if not card:
            return
        if card not in t.Ion:
            self._set_status("选中的不是离子牌。")
            return
        max_count = self._max_playable_count(card)
        if max_count <= 0:
            self._set_status("当前离子手牌数量不足。")
            return
        self.count_var.set(str(max_count))
        self._dispatch_ion_play(card, max_count)

    def _play_ion_with_picker(self) -> None:
        self._play_ion()

    def _play_special(self) -> None:
        card = self._selected_card()
        if not card:
            return
        if card not in t.Special:
            self._set_status("选中的不是特殊牌。")
            return
        self._dispatch_action({"kind": "play_special", "card": card})

    def _play_operation(self) -> None:
        card = self._selected_card()
        if not card:
            return
        if card not in t.Function:
            self._set_status("选中的不是功能牌。")
            return

        action: Dict[str, Any] = {"kind": "play_operation", "card": card}
        if card == t.Enough and self.last_state:
            you = self.last_state.get("you_index")
            players = self.last_state.get("players", [])
            hand = {}
            if you is not None and 0 <= you < len(players):
                hand = players[you].get("hand", {}) or {}
            ion_options = sorted([x for x in hand if x in t.Ion and hand[x] > 0])
            if not ion_options:
                self._set_status("使用“足量”前，手牌中至少要有一张离子牌。")
                return
            selected_ion = self._choose_card_from_list(
                title="足量目标离子",
                prompt="请选择“足量”要指定的离子：",
                options=ion_options,
            )
            if selected_ion is None:
                return
            max_count = int(hand.get(selected_ion, 0))
            if max_count <= 0:
                self._set_status("所选离子数量不足。")
                return
            if max_count == 1:
                selected_count = 1
            else:
                selected_count = self._choose_ion_count(selected_ion, max_count)
                if selected_count is None:
                    return
            action["target_ion"] = selected_ion
            action["target_count"] = selected_count

        self._dispatch_action(action)

    def _play_wangzha(self) -> None:
        if self.last_state:
            you = self.last_state.get("you_index")
            players = self.last_state.get("players", [])
            if you is not None and 0 <= you < len(players):
                hand = players[you].get("hand", {}) or {}
                if hand.get(t.Acid, 0) < 1 or hand.get(t.Alk, 0) < 1:
                    self._set_status("王炸需要手牌中同时有“强酸”和“强碱”。")
                    return
        self._dispatch_action({"kind": "play_wangzha"})

    def _end_turn(self) -> None:
        self._dispatch_action({"kind": "end_turn"})

    def _on_close(self) -> None:
        self._stop_session()
        self.destroy()


if __name__ == "__main__":
    app = ChemGameApp()
    app.mainloop()