"""
FreeExile Expanded Meridian Passive Tree Canonical Catalog (Server-Authoritative).
Defines 29 Acupoints across 5 Constellation Clusters (Minor, Notable, Keystone, Jewel Sockets)
and Canonical Jewels (Linh Thạch), matching PoE2-depth design with mobile-optimized architecture.
"""

from __future__ import annotations
from typing import Dict, List, Optional, Set, Tuple

from server.world.meridian_types import (
    JewelItemDef,
    MeridianElement,
    MeridianNodeDef,
    MeridianNodeType,
    MeridianStatBonus,
)

CANONICAL_MERIDIAN_NODES: Dict[str, MeridianNodeDef] = {
    # =========================================================================
    # CLUSTER 0: TÂM MẠCH KHỞI NGUYÊN (CENTRAL ORIGIN HUB)
    # =========================================================================
    "m_c1": MeridianNodeDef(
        node_id="m_c1",
        name="Đản Trung",
        meridian="Nhâm Mạch",
        title="Tâm Mạch Bản Nguyên",
        node_type=MeridianNodeType.ORIGIN,
        element=MeridianElement.THUY,
        cluster="CENTER",
        x=800.0,
        y=600.0,
        lore="Chính giữa lồng ngực, nơi tụ hội chân khí và huyết dịch bản nguyên. Khởi nguồn tất yếu của võ đạo.",
        stats=MeridianStatBonus(hp=200, mp=100, resist=15.0),
        stat_display=("+200 Sinh Lực Tối Đa", "+100 Chân Khí Tối Đa", "+15 Kháng Toàn Thuộc Tính"),
    ),
    "m_c2": MeridianNodeDef(
        node_id="m_c2",
        name="Khí Hải",
        meridian="Nhâm Mạch",
        title="Đan Điền Thổ Khí",
        node_type=MeridianNodeType.VESSEL,
        element=MeridianElement.THO,
        cluster="CENTER",
        x=800.0,
        y=700.0,
        lore="Biển của sinh khí, nuôi dưỡng gốc rễ tạng phủ vững chãi.",
        stats=MeridianStatBonus(hp=100, mp=60, armor=10),
        stat_display=("+100 Sinh Lực", "+60 Chân Khí", "+10 Giáp"),
    ),
    "m_c3": MeridianNodeDef(
        node_id="m_c3",
        name="Thần Khuyết",
        meridian="Nhâm Mạch",
        title="Chân Hỏa Dẫn Lực",
        node_type=MeridianNodeType.VESSEL,
        element=MeridianElement.HOA,
        cluster="CENTER",
        x=800.0,
        y=500.0,
        lore="Huyệt rốn nơi thai tức giao hòa, kích hoạt nguồn hỏa nhiệt đan điền.",
        stats=MeridianStatBonus(dps_mult=0.08, armor=10),
        stat_display=("+8% Tổng Sát Thương", "+10 Giáp"),
    ),
    "m_c4": MeridianNodeDef(
        node_id="m_c4",
        name="Mệnh Môn",
        meridian="Đốc Mạch",
        title="Sinh Mệnh Chi Môn",
        node_type=MeridianNodeType.VESSEL,
        element=MeridianElement.THUY,
        cluster="CENTER",
        x=700.0,
        y=600.0,
        lore="Cửa ngõ sinh mệnh đối diện rốn tại thắt lưng, hộ trì bản nguyên.",
        stats=MeridianStatBonus(hp=80, resist=10.0, evasion=0.03),
        stat_display=("+80 Sinh Lực", "+10 Kháng", "+3% Né Tránh"),
    ),
    "m_c5": MeridianNodeDef(
        node_id="m_c5",
        name="Trung Phủ",
        meridian="Phế Kinh",
        title="Kim Kình Bộc Phát",
        node_type=MeridianNodeType.VESSEL,
        element=MeridianElement.KIM,
        cluster="CENTER",
        x=900.0,
        y=600.0,
        lore="Huyệt khởi đầu của kinh Phế, tăng cường kình lực và sắc bén cho đòn đánh.",
        stats=MeridianStatBonus(dps=15.0, attack_speed=0.04),
        stat_display=("+15 Sát Thương Cơ Bản", "+4% Tốc Độ Đánh"),
    ),

    # =========================================================================
    # CLUSTER 1: CƯƠNG THỂ MA CỐT (NORTH CLUSTER - PHYSIQUE & ARMOR)
    # =========================================================================
    "m_n1": MeridianNodeDef(
        node_id="m_n1",
        name="Quan Nguyên",
        meridian="Nhâm Mạch",
        title="Tụ Khí Hạ Đan Điền",
        node_type=MeridianNodeType.VESSEL,
        element=MeridianElement.HOA,
        cluster="NORTH",
        x=800.0,
        y=380.0,
        lore="Dưới rốn ba thốn, then chốt ngưng tụ nội lực cương thể.",
        stats=MeridianStatBonus(dps_mult=0.08, armor=15),
        stat_display=("+8% Tổng Sát Thương", "+15 Giáp"),
    ),
    "m_n2": MeridianNodeDef(
        node_id="m_n2",
        name="Trung Quản",
        meridian="Nhâm Mạch",
        title="Thiết Bích Cốt Khang",
        node_type=MeridianNodeType.VESSEL,
        element=MeridianElement.THO,
        cluster="NORTH",
        x=720.0,
        y=280.0,
        lore="Luyện hóa tinh hoa thức ăn thành khí huyết hộ thể kiên cố.",
        stats=MeridianStatBonus(hp=120, armor=20),
        stat_display=("+120 Sinh Lực", "+20 Giáp"),
    ),
    "m_n3": MeridianNodeDef(
        node_id="m_n3",
        name="Cự Khuyết",
        meridian="Nhâm Mạch",
        title="Trọng Kiếm Khai Sơn",
        node_type=MeridianNodeType.MAJOR,
        element=MeridianElement.KIM,
        cluster="NORTH",
        x=880.0,
        y=280.0,
        lore="Cung điện của trái tim, phóng xuất uy lực dũng mãnh vô song.",
        stats=MeridianStatBonus(dps_mult=0.18, armor=30, armor_pen=0.08),
        stat_display=("+18% Sát Thương Cận Chiến", "+30 Giáp", "+8% Xuyên Giáp"),
    ),
    "m_n4": MeridianNodeDef(
        node_id="m_n4",
        name="Cương Cốt Đại Cực",
        meridian="Kỳ Mạch",
        title="Thái Sơn Áp Đỉnh",
        node_type=MeridianNodeType.MAJOR,
        element=MeridianElement.THO,
        cluster="NORTH",
        x=800.0,
        y=200.0,
        lore="Thân xác tôi luyện qua vạn trượng nham thạch, bất khả xâm phạm.",
        stats=MeridianStatBonus(hp=300, armor=50, dmg_reduction=0.04),
        stat_display=("+300 Sinh Lực", "+50 Giáp", "-4% Sát Thương Nhận"),
    ),
    "m_n_keystone": MeridianNodeDef(
        node_id="m_n_keystone",
        name="Đới Mạch Kim Cang",
        meridian="Kỳ Kinh",
        title="Kim Cương Bất Hoại Thể",
        node_type=MeridianNodeType.KEYSTONE,
        element=MeridianElement.THO,
        cluster="NORTH",
        x=800.0,
        y=100.0,
        lore="[NGHỊCH MỆNH] Tầng cương khí bất hoại bảo bọc toàn thân. Thể phách đạt cực hạn nhưng làm giảm tính linh hoạt cơ động.",
        stats=MeridianStatBonus(hp=500, armor=80, dmg_reduction=0.10, attack_speed=-0.05),
        stat_display=("+500 Sinh Lực Tối Đa", "+80 Giáp Hộ Thể", "-10% Sát Thương Gánh Chịu", "-5% Tốc Độ Đánh (Đánh Đổi)"),
    ),
    "m_n_jewel": MeridianNodeDef(
        node_id="m_n_jewel",
        name="Khảm Tọa Bắc Đẩu",
        meridian="Thần Khiếu",
        title="Linh Cốt Khảm Tọa (Bắc)",
        node_type=MeridianNodeType.JEWEL_SOCKET,
        element=MeridianElement.UNIVERSAL,
        cluster="NORTH",
        x=720.0,
        y=150.0,
        lore="[LINH CỐT KHẢM TỌA] Rãnh khảm thiên địa thần khiếu, cho phép cắm Linh Thạch để hấp thu sức mạnh thần bí.",
        stats=MeridianStatBonus(),
        stat_display=("Cho phép khảm nạp 1 viên Linh Thạch", "Nhận 100% thuộc tính của Linh Thạch"),
    ),

    # =========================================================================
    # CLUSTER 2: DU LONG THÂN PHÁP (EAST CLUSTER - AGILITY & CRIT)
    # =========================================================================
    "m_e1": MeridianNodeDef(
        node_id="m_e1",
        name="Dương Giao",
        meridian="Dương Duy Mạch",
        title="Phong Lôi Khởi Bộ",
        node_type=MeridianNodeType.VESSEL,
        element=MeridianElement.HOA,
        cluster="EAST",
        x=1020.0,
        y=600.0,
        lore="Khởi phát lôi hỏa dưới chân, tăng gia tốc chuyển động tức thời.",
        stats=MeridianStatBonus(dps=15.0, attack_speed=0.04),
        stat_display=("+15 Sát Thương", "+4% Tốc Độ Đánh"),
    ),
    "m_e2": MeridianNodeDef(
        node_id="m_e2",
        name="Huyền Chung",
        meridian="Đảm Kinh",
        title="Lạc Cốt Tật Phong",
        node_type=MeridianNodeType.VESSEL,
        element=MeridianElement.KIM,
        cluster="EAST",
        x=1140.0,
        y=520.0,
        lore="Hội tụ tủy cốt, giúp thân pháp nhẹ như cánh én.",
        stats=MeridianStatBonus(evasion=0.05, crit_rate=0.04),
        stat_display=("+5% Thân Pháp Né", "+4% Tỉ Lệ Bạo Kích"),
    ),
    "m_e3": MeridianNodeDef(
        node_id="m_e3",
        name="Quang Minh",
        meridian="Đảm Kinh",
        title="Nhãn Minh Điểm Huyệt",
        node_type=MeridianNodeType.MAJOR,
        element=MeridianElement.KIM,
        cluster="EAST",
        x=1140.0,
        y=680.0,
        lore="Khai sáng thị giác, nhắm trúng tử huyệt đối thủ tạo đòn trí mạng.",
        stats=MeridianStatBonus(crit_rate=0.10, crit_dmg=0.30),
        stat_display=("+10% Tỉ Lệ Bạo Kích", "+30% Sát Thương Bạo Kích"),
    ),
    "m_e4": MeridianNodeDef(
        node_id="m_e4",
        name="Phong Thần Tuyệt Bộ",
        meridian="Kỳ Mạch",
        title="Hư Không Bộ Ảnh",
        node_type=MeridianNodeType.MAJOR,
        element=MeridianElement.THUY,
        cluster="EAST",
        x=1260.0,
        y=600.0,
        lore="Cước bộ lướt đi không để lại tàn ảnh, né tránh hiểm họa.",
        stats=MeridianStatBonus(evasion=0.15, attack_speed=0.08, resist=10.0),
        stat_display=("+15% Thân Pháp Né", "+8% Tốc Độ Đánh", "+10 Kháng Thuộc Tính"),
    ),
    "m_e_keystone": MeridianNodeDef(
        node_id="m_e_keystone",
        name="Hư Bộ Vô Tướng",
        meridian="Dương Kiều Mạch",
        title="Ảnh Hư Vô Ảnh",
        node_type=MeridianNodeType.KEYSTONE,
        element=MeridianElement.KIM,
        cluster="EAST",
        x=1380.0,
        y=600.0,
        lore="[NGHỊCH MỆNH] Biến đổi thân thể thành hư vô khi né tránh. Tăng vọt khả năng né và thời gian bất tử i-frame nhưng hy sinh giáp hộ thể.",
        stats=MeridianStatBonus(evasion=0.25, crit_rate=0.10, armor=-40),
        stat_display=("+25% Thân Pháp Né Tránh", "+10% Tỉ Lệ Bạo Kích", "-40 Giáp Hộ Thể (Đánh Đổi)"),
    ),
    "m_e_jewel": MeridianNodeDef(
        node_id="m_e_jewel",
        name="Khảm Tọa Thanh Long",
        meridian="Thần Khiếu",
        title="Linh Cốt Khảm Tọa (Đông)",
        node_type=MeridianNodeType.JEWEL_SOCKET,
        element=MeridianElement.UNIVERSAL,
        cluster="EAST",
        x=1260.0,
        y=500.0,
        lore="[LINH CỐT KHẢM TỌA] Rãnh khảm phong lôi phương Đông, liên kết sức mạnh linh thạch vào thân pháp.",
        stats=MeridianStatBonus(),
        stat_display=("Cho phép khảm nạp 1 viên Linh Thạch", "Nhận 100% thuộc tính của Linh Thạch"),
    ),

    # =========================================================================
    # CLUSTER 3: U MINH THẦN THỨC (SOUTH CLUSTER - MIND & LEECH)
    # =========================================================================
    "m_s1": MeridianNodeDef(
        node_id="m_s1",
        name="Chiếu Hải",
        meridian="Âm Kiều Mạch",
        title="U Tuyền Hấp Lực",
        node_type=MeridianNodeType.VESSEL,
        element=MeridianElement.MOC,
        cluster="SOUTH",
        x=800.0,
        y=820.0,
        lore="Huyệt vị âm nhu tại gót chân, hấp thu sinh khí đối thủ bù đắp bản thân.",
        stats=MeridianStatBonus(life_leech=0.03, hp=80),
        stat_display=("+3% Hút Sinh Lực", "+80 Sinh Lực"),
    ),
    "m_s2": MeridianNodeDef(
        node_id="m_s2",
        name="Phục Lưu",
        meridian="Thận Kinh",
        title="Dưỡng Chân Khí Hải",
        node_type=MeridianNodeType.VESSEL,
        element=MeridianElement.THUY,
        cluster="SOUTH",
        x=720.0,
        y=920.0,
        lore="Khơi thông dòng chảy của thận thủy, hồi phục chân khí dồi dào.",
        stats=MeridianStatBonus(mp=150, resist=10.0),
        stat_display=("+150 Chân Khí", "+10 Kháng Toàn Thuộc Tính"),
    ),
    "m_s3": MeridianNodeDef(
        node_id="m_s3",
        name="Âm Lăng Tuyền",
        meridian="Tỳ Kinh",
        title="Hóa Huyết Hấp Tủy",
        node_type=MeridianNodeType.MAJOR,
        element=MeridianElement.MOC,
        cluster="SOUTH",
        x=880.0,
        y=920.0,
        lore="Luyện hóa tinh huyết thành luồng kình lực đoạt mệnh ăn mòn đối thủ.",
        stats=MeridianStatBonus(life_leech=0.05, armor_pen=0.12),
        stat_display=("+5% Hút Sinh Lực", "+12% Xuyên Giáp"),
    ),
    "m_s4": MeridianNodeDef(
        node_id="m_s4",
        name="U Minh Đoạt Phách",
        meridian="Kỳ Mạch",
        title="Cốt Huyết Cuồng Triều",
        node_type=MeridianNodeType.MAJOR,
        element=MeridianElement.MOC,
        cluster="SOUTH",
        x=800.0,
        y=1000.0,
        lore="Tuyệt kỹ u minh đoạt lấy thần phách địch nhân, hồi phục liên tục.",
        stats=MeridianStatBonus(life_leech=0.08, dps_mult=0.15, hp=150),
        stat_display=("+8% Hút Sinh Lực", "+15% Tổng Sát Thương", "+150 Sinh Lực"),
    ),
    "m_s_keystone": MeridianNodeDef(
        node_id="m_s_keystone",
        name="U Minh Huyết Tế",
        meridian="Âm Duy Mạch",
        title="Huyết Ma Cực Công (Blood Magic)",
        node_type=MeridianNodeType.KEYSTONE,
        element=MeridianElement.MOC,
        cluster="SOUTH",
        x=800.0,
        y=1100.0,
        lore="[NGHỊCH MỆNH] Triệt tiêu hoàn toàn Chân Khí (Mana = 0). Mọi chiêu thức tiêu hao trực tiếp Sinh Lực nhưng sát thương tăng vọt.",
        stats=MeridianStatBonus(dps_mult=0.30, hp=300, life_leech=0.05, mp=-100),
        stat_display=("+30% Tổng Sát Thương", "+300 Sinh Lực", "+5% Hút Máu", "Tiêu Hao Máu Thay Chân Khí (Đánh Đổi)"),
    ),
    "m_s_jewel": MeridianNodeDef(
        node_id="m_s_jewel",
        name="Khảm Tọa Chu Tước",
        meridian="Thần Khiếu",
        title="Linh Cốt Khảm Tọa (Nam)",
        node_type=MeridianNodeType.JEWEL_SOCKET,
        element=MeridianElement.UNIVERSAL,
        cluster="SOUTH",
        x=880.0,
        y=1050.0,
        lore="[LINH CỐT KHẢM TỌA] Rãnh khảm phương Nam rực lửa, hòa quyện linh lực vào dòng huyết dịch.",
        stats=MeridianStatBonus(),
        stat_display=("Cho phép khảm nạp 1 viên Linh Thạch", "Nhận 100% thuộc tính của Linh Thạch"),
    ),

    # =========================================================================
    # CLUSTER 4: LIỆT HỎA CUỒNG NỘ (WEST CLUSTER - POWER & CRIT)
    # =========================================================================
    "m_w1": MeridianNodeDef(
        node_id="m_w1",
        name="Trúc Tân",
        meridian="Âm Duy Mạch",
        title="Băng Tâm Hàn Ý",
        node_type=MeridianNodeType.VESSEL,
        element=MeridianElement.THUY,
        cluster="WEST",
        x=580.0,
        y=600.0,
        lore="Ngưng đọng tâm trí, giữ bình tĩnh tuyệt đối trong giao tranh ác liệt.",
        stats=MeridianStatBonus(crit_rate=0.06, crit_dmg=0.15),
        stat_display=("+6% Tỉ Lệ Bạo Kích", "+15% Sát Thương Bạo Kích"),
    ),
    "m_w2": MeridianNodeDef(
        node_id="m_w2",
        name="Thái Xung",
        meridian="Can Kinh",
        title="Hỏa Kình Bộc Liệt",
        node_type=MeridianNodeType.VESSEL,
        element=MeridianElement.HOA,
        cluster="WEST",
        x=460.0,
        y=520.0,
        lore="Giải phóng nhiệt lượng tích tụ, biến mỗi đường kiếm thành ngọn lửa cuồng nộ.",
        stats=MeridianStatBonus(dps=20.0, dps_mult=0.08),
        stat_display=("+20 Sát Thương Cơ Bản", "+8% Sát Thương Hỏa"),
    ),
    "m_w3": MeridianNodeDef(
        node_id="m_w3",
        name="Hành Gian",
        meridian="Can Kinh",
        title="Liệt Diễm Trảm",
        node_type=MeridianNodeType.MAJOR,
        element=MeridianElement.HOA,
        cluster="WEST",
        x=460.0,
        y=680.0,
        lore="Nhát chém cuồng nộ bốc cháy thiêu rụi giáp trụ đối phương.",
        stats=MeridianStatBonus(dps_mult=0.18, armor_pen=0.12),
        stat_display=("+18% Tổng Sát Thương", "+12% Xuyên Giáp"),
    ),
    "m_w4": MeridianNodeDef(
        node_id="m_w4",
        name="Liệt Hỏa Bạo Kích",
        meridian="Kỳ Mạch",
        title="Vạn Kiếp Diệt Ma",
        node_type=MeridianNodeType.MAJOR,
        element=MeridianElement.KIM,
        cluster="WEST",
        x=340.0,
        y=600.0,
        lore="Khai mở tiềm năng hủy diệt, đưa mọi đòn đánh lên mức cực hạn sát thương.",
        stats=MeridianStatBonus(crit_rate=0.15, crit_dmg=0.40),
        stat_display=("+15% Tỉ Lệ Bạo Kích", "+40% Sát Thương Bạo Kích"),
    ),
    "m_w_keystone": MeridianNodeDef(
        node_id="m_w_keystone",
        name="Bách Hội Cực Ý",
        meridian="Đốc Mạch",
        title="Nghịch Mệnh Thần Sát",
        node_type=MeridianNodeType.KEYSTONE,
        element=MeridianElement.KIM,
        cluster="WEST",
        x=220.0,
        y=600.0,
        lore="[NGHỊCH MỆNH] Nghịch chuyển kinh mạch Bách Hội giải phóng 100% sát phạt tính. Sát thương bạo kích tăng vọt nhưng triệt tiêu hoàn toàn khả năng né đòn.",
        stats=MeridianStatBonus(dps_mult=0.40, crit_rate=0.20, crit_dmg=0.50, evasion=-1.0),
        stat_display=("+40% Tổng Sát Thương", "+20% Tỉ Lệ Bạo Kích", "+50% Sát Thương Bạo", "Né Tránh Trở Về 0% (Đánh Đổi)"),
    ),
    "m_w_jewel": MeridianNodeDef(
        node_id="m_w_jewel",
        name="Khảm Tọa Bạch Hổ",
        meridian="Thần Khiếu",
        title="Linh Cốt Khảm Tọa (Tây)",
        node_type=MeridianNodeType.JEWEL_SOCKET,
        element=MeridianElement.UNIVERSAL,
        cluster="WEST",
        x=340.0,
        y=500.0,
        lore="[LINH CỐT KHẢM TỌA] Rãnh khảm sát phạt phương Tây, khuếch đại bạo kích và uy lực Linh Thạch.",
        stats=MeridianStatBonus(),
        stat_display=("Cho phép khảm nạp 1 viên Linh Thạch", "Nhận 100% thuộc tính của Linh Thạch"),
    ),
}

# =============================================================================
# TOPOLOGICAL EDGES (MA TRẬN LIÊN KẾT CẠNH CÁC CỤM)
# =============================================================================
CANONICAL_MERIDIAN_CONNECTIONS: Tuple[Tuple[str, str], ...] = (
    # --- Center Hub Interconnections ---
    ("m_c1", "m_c2"),
    ("m_c1", "m_c3"),
    ("m_c1", "m_c4"),
    ("m_c1", "m_c5"),

    # --- Center -> North Cluster (Physique) ---
    ("m_c3", "m_n1"),
    ("m_n1", "m_n2"),
    ("m_n1", "m_n3"),
    ("m_n2", "m_n4"),
    ("m_n3", "m_n4"),
    ("m_n4", "m_n_keystone"),
    ("m_n2", "m_n_jewel"),
    ("m_n_jewel", "m_n_keystone"),

    # --- Center -> East Cluster (Agility) ---
    ("m_c5", "m_e1"),
    ("m_e1", "m_e2"),
    ("m_e1", "m_e3"),
    ("m_e2", "m_e4"),
    ("m_e3", "m_e4"),
    ("m_e4", "m_e_keystone"),
    ("m_e2", "m_e_jewel"),
    ("m_e_jewel", "m_e_keystone"),

    # --- Center -> South Cluster (Mind & Leech) ---
    ("m_c2", "m_s1"),
    ("m_s1", "m_s2"),
    ("m_s1", "m_s3"),
    ("m_s2", "m_s4"),
    ("m_s3", "m_s4"),
    ("m_s4", "m_s_keystone"),
    ("m_s3", "m_s_jewel"),
    ("m_s_jewel", "m_s_keystone"),

    # --- Center -> West Cluster (Power & Crit) ---
    ("m_c4", "m_w1"),
    ("m_w1", "m_w2"),
    ("m_w1", "m_w3"),
    ("m_w2", "m_w4"),
    ("m_w3", "m_w4"),
    ("m_w4", "m_w_keystone"),
    ("m_w2", "m_w_jewel"),
    ("m_w_jewel", "m_w_keystone"),
)

# =============================================================================
# CANONICAL JEWELS CATALOG (LINH THẠCH MẪU)
# =============================================================================
CANONICAL_JEWELS: Dict[str, JewelItemDef] = {
    "jewel_red_bloodstone": JewelItemDef(
        jewel_id="jewel_red_bloodstone",
        name="Cổ Huyết Xích Ngọc",
        rarity="RARE",
        element=MeridianElement.HOA,
        icon="💎",
        stats=MeridianStatBonus(hp=120, dps_mult=0.12, armor=15),
        lore="Khối ngọc tinh luyện từ máu huyết cổ thú thượng cổ, tỏa nhiệt lượng rực cháy tiếp thêm sinh lực vô tận.",
        stat_display=("+120 Sinh Lực Tối Đa", "+12% Sát Thương Cận Chiến", "+15 Giáp Hộ Thể"),
    ),
    "jewel_blue_frost": JewelItemDef(
        jewel_id="jewel_blue_frost",
        name="Hàn Băng Thần Tinh",
        rarity="RARE",
        element=MeridianElement.THUY,
        icon="💠",
        stats=MeridianStatBonus(mp=100, resist=15.0, attack_speed=0.06),
        lore="Mảnh băng vạn năm khai quật từ hàn đầm lãnh nguyên, ngưng thần tĩnh khí tăng tốc thi triển chiêu thức.",
        stat_display=("+100 Chân Khí Tối Đa", "+15 Kháng Toàn Thuộc Tính", "+6% Tốc Độ Xuất Chiêu"),
    ),
    "jewel_gold_thunder": JewelItemDef(
        jewel_id="jewel_gold_thunder",
        name="U Lôi Tàn Cốt",
        rarity="UNIQUE",
        element=MeridianElement.KIM,
        icon="⚡",
        stats=MeridianStatBonus(crit_rate=0.12, crit_dmg=0.35, armor_pen=0.10),
        lore="[HOÀNG KIM CỰC PHẨM] Đoạn xương linh thú ngậm lôi điện, ẩn chứa kình lực sát phạt xuyên thủng hộ giáp.",
        stat_display=("+12% Tỉ Lệ Bạo Kích", "+35% Sát Thương Bạo Kích", "+10% Xuyên Giáp"),
    ),
    "jewel_green_emerald": JewelItemDef(
        jewel_id="jewel_green_emerald",
        name="U Minh Bích Thạch",
        rarity="RARE",
        element=MeridianElement.MOC,
        icon="🟢",
        stats=MeridianStatBonus(life_leech=0.06, hp=80, evasion=0.08),
        lore="Đá ngọc bích nhiễm độc vụ u minh, kích hoạt bản năng sinh tồn hút máu và né tránh đòn hiểm.",
        stat_display=("+6% Hút Sinh Lực Cổ Cốt", "+80 Sinh Lực Tối Đa", "+8% Thân Pháp Né"),
    ),
}


def get_meridian_node(node_id: str) -> Optional[MeridianNodeDef]:
    """Returns canonical node definition by ID."""
    return CANONICAL_MERIDIAN_NODES.get(node_id)


def get_all_meridian_nodes() -> Dict[str, MeridianNodeDef]:
    """Returns full dictionary of canonical nodes."""
    return dict(CANONICAL_MERIDIAN_NODES)


def get_meridian_connections() -> Tuple[Tuple[str, str], ...]:
    """Returns all bidirectional topological connections."""
    return CANONICAL_MERIDIAN_CONNECTIONS


def get_node_neighbors(node_id: str) -> Set[str]:
    """Computes all adjacent node IDs for a given node in the graph."""
    neighbors: Set[str] = set()
    for a, b in CANONICAL_MERIDIAN_CONNECTIONS:
        if a == node_id:
            neighbors.add(b)
        elif b == node_id:
            neighbors.add(a)
    return neighbors


def get_canonical_jewel(jewel_id: str) -> Optional[JewelItemDef]:
    """Returns canonical jewel item definition by ID."""
    return CANONICAL_JEWELS.get(jewel_id)


def get_all_canonical_jewels() -> Dict[str, JewelItemDef]:
    """Returns all available canonical jewels."""
    return dict(CANONICAL_JEWELS)