from typing import Dict, List

from brokk_code import __version__


def get_braille_icon() -> str:
    """
    Returns a multi-line string representing the Brokk icon using Braille characters.
    Uses characters in the U+2800–U+28FF range.
    Depicts the Viking helmet logo: two curved horns, dome, central bar, and banded lower section.
    """
    return (
        "⠀⠀⣷⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢠⡾⠀⠀\n"
        "⠀⢀⣿⡇⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢸⣷⡀⠀\n"
        "⢠⣸⡟⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢻⣇⡄\n"
        "⣿⣷⡀⠀⠀⠀⠀⡀⣤⣤⢀⠀⠀⠀⠀⢀⣾⣿\n"
        "⢿⣿⣿⣷⡤⣠⣾⡇⣿⣿⢸⣷⣄⢤⣾⣿⣿⡿\n"
        "⠀⠻⢿⡟⣴⣿⣿⡇⣿⣿⢸⣿⣿⣮⢻⡿⠟⠀\n"
        "⠀⠀⠀⠐⢿⣿⣿⡇⣿⣿⢸⣿⣿⡿⠂⠀⠀⠀\n"
        "⠀⠀⠀⣝⠷⣬⣭⡁⣿⣿⢨⣭⣵⠾⣫⠀⠀⠀\n"
        "⠀⠀⠀⠈⠛⢾⣭⣥⣿⣿⣬⣭⡶⠛⠁⠀⠀⠀\n"
        "⠀⠀⠀⠀⠀⠀⠀⢸⣿⣿⡇⠀⠀⠀⠀⠀⠀⠀\n"
        "⠀⠀⠀⠀⠀⠀⠀⠘⢝⡫⠃⠀⠀⠀⠀⠀⠀⠀"
    )


def build_welcome_message(
    commands: List[Dict[str, str]], latest_pypi_version: str | None = None
) -> str:
    """
    Constructs the branded welcome/onboarding message as a Markdown string.

    Args:
        commands: The list of supported slash commands from BrokkApp.get_slash_commands().
        latest_pypi_version: The latest version available on PyPI, if known.

    Returns:
        A Markdown-formatted string for display in the ChatPanel.
    """
    version_info = f"v{__version__}"
    if latest_pypi_version and latest_pypi_version != __version__:
        version_info += f" (Latest: {latest_pypi_version})"

    description = (
        f"# Welcome to Brokk {version_info}\n\n"
        "Brokk is a code intelligence agent designed for high-precision **context engineering**."
    )

    context_eng = (
        "### Context Engineering\n"
        "In Brokk, your workspace is managed via a living context. "
        "AI performance depends on exactly what code is visible to the model. "
        "You can prune, pin, or focus specific files and methods to optimize results."
    )

    workflows = (
        "### Key Workflows\n"
        "- **`/context`**: Toggle the Context Panel to manage what the AI sees. "
        "Use it to drop unnecessary fragments and keep your token usage efficient.\n"
        "- **`/task`**: Open the Task List to track your current objectives. "
        "The AI uses this list to stay aligned with your goals.\n"
        "- **`@mentions`**: Type `@` followed by a file or class name in the chat to "
        "immediately attach that entity to your context."
    )

    signup = "\n\nNeed a token? Go to https://brokk.ai/ to sign up and get one."

    return f"{description}\n\n{context_eng}\n\n{workflows}{signup}"
