chess-analyzer-tui 0.1.1__tar.gz

chess_analyzer_tui-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Leonardo Laurindo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

chess_analyzer_tui-0.1.1/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: chess-analyzer-tui
+Version: 0.1.1
+Summary: Terminal chess analysis TUI with Stockfish.
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/leolaurindo/chess-analyzer-tui
+Project-URL: Source, https://github.com/leolaurindo/chess-analyzer-tui
+Project-URL: Issues, https://github.com/leolaurindo/chess-analyzer-tui/issues
+Keywords: chess,stockfish,terminal,tui,analysis
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Games/Entertainment :: Board Games
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: licenses/chess-tui-MIT.txt
+Requires-Dist: chess>=1.11.2
+Requires-Dist: textual>=8.2.8
+Dynamic: license-file
+
+# Chess Analyzer TUI
+
+Interactive terminal chess analysis, with Stockfish as the default and support for other UCI engines.
+
+Piece rendering adapted from [Thomas Mauran's chess-tui](https://github.com/thomas-mauran/chess-tui).
+Full renderer credits and license information are below.
+
+## Install and run
+
+Requires Python 3.11+.
+
+Once published on PyPI, install the `chess-analyzer-tui` package with either tool
+manager. Both install the `chess-analyzer` command (the command name is not a
+separate PyPI package):
+
+```sh
+uv tool install chess-analyzer-tui   # or: pipx install chess-analyzer-tui
+chess-analyzer
+chess-analyzer --pgn game.pgn
+chess-analyzer --white "Supi" --black "Carlsen" "2kr2nr/1pp2ppp/3b4/1P3q2/2Pp1B2/5Q1P/RP3PP1/R5K1 w - - 0 1"
+```
+
+The command works from any directory. If it isn't on PATH, use
+`uv tool update-shell` (or `pipx ensurepath`) and restart your shell.
+
+Alternatively, pass a quoted FEN.
+
+Options:
+
+- `--ascii` — use ASCII pieces
+- `--time 0.5` — set analysis time
+- `--lines 3` — show multiple lines
+- `--threads 2` — set engine threads, if supported
+- `--hash 256` — set engine hash size, if supported
+- `--engine /path/to/engine` — choose a UCI engine executable
+- `--white "Supi"` / `--black "Carlsen"` — label the players (override PGN names)
+
+## Stockfish
+
+Stockfish is the default engine and is installed separately. If it isn't found,
+the app detects your OS (and Linux distribution) and suggests an installation command:
+
+| Platform | Command |
+| --- | --- |
+| Debian/Ubuntu and derivatives (e.g. Linux Mint) | `sudo apt install stockfish` |
+| Arch and derivatives (e.g. Manjaro) | `sudo pacman -S stockfish` |
+| Fedora | `sudo dnf install stockfish` |
+| macOS (Homebrew) | `brew install stockfish` |
+| Windows (WinGet) | `winget install --id Stockfish.Stockfish --exact` |
+
+Other distros/platforms get the [official download link](https://stockfishchess.org/download/).
+
+After installation, make sure `stockfish` (`stockfish.exe` on Windows) is on
+PATH: add the executable’s directory to PATH and restart your shell if needed.
+Alternatively, pass an executable with `chess-analyzer --engine /path/to/stockfish`
+(on Windows: `chess-analyzer --engine "C:\path\to\stockfish.exe"`).
+
+Stockfish is found on PATH or beside the application module as `stockfish`
+(`stockfish.exe` on Windows). Other UCI engines can be selected with
+`--engine /path/to/engine`—for example, Leela Chess Zero (Lc0) with
+`--engine /path/to/lc0`. Configure engine-specific files and settings, such as
+Lc0's network weights and backend, separately. The app applies thread, hash,
+and multiple-line settings only when the engine supports them.
+
+## Navigation
+
+PGNs open at the final position and use their `White`/`Black` headers for player labels
+when present. Use `--white` and `--black` to set or override names, including for FENs.
+
+- **↑/↓** — choose an original move or engine alternative
+- **→/Enter** — follow the selected move; **←** — step back
+- **Esc** — return from an explored line to its game position
+- **f** — flip board; **r** — reanalyze; **q** — quit
+
+Moves, the return link, and any original-game move (or Start) are clickable.
+Branches are retained, and navigation never waits for analysis.
+
+Use at least 40×24 terminal cells. Larger boards use multiline pieces; smaller
+ones use chess glyphs. Narrow layouts stack the panels; scroll with the mouse
+wheel or Page Up/Down. Blue highlights the selected move, yellow the previous
+move, and red a checked king.
+
+## Renderer credits
+
+The piece artwork and size-adaptive rendering approach are adapted from
+[Thomas Mauran's chess-tui](https://github.com/thomas-mauran/chess-tui), using its
+[piece designs](https://github.com/thomas-mauran/chess-tui/tree/fc1d4841532bf72f5a25c5cb45abe82ec25e056b/src/pieces).
+The artwork is used under the MIT License; the full notice is preserved in
+[licenses/chess-tui-MIT.txt](licenses/chess-tui-MIT.txt). The rest of this project
+is released under [MIT](LICENSE).
+
+## Verify
+
+With Stockfish installed: `uv run python -m unittest discover -s tests -v`.

chess_analyzer_tui-0.1.1/README.md

@@ -0,0 +1,94 @@
+# Chess Analyzer TUI
+
+Interactive terminal chess analysis, with Stockfish as the default and support for other UCI engines.
+
+Piece rendering adapted from [Thomas Mauran's chess-tui](https://github.com/thomas-mauran/chess-tui).
+Full renderer credits and license information are below.
+
+## Install and run
+
+Requires Python 3.11+.
+
+Once published on PyPI, install the `chess-analyzer-tui` package with either tool
+manager. Both install the `chess-analyzer` command (the command name is not a
+separate PyPI package):
+
+```sh
+uv tool install chess-analyzer-tui   # or: pipx install chess-analyzer-tui
+chess-analyzer
+chess-analyzer --pgn game.pgn
+chess-analyzer --white "Supi" --black "Carlsen" "2kr2nr/1pp2ppp/3b4/1P3q2/2Pp1B2/5Q1P/RP3PP1/R5K1 w - - 0 1"
+```
+
+The command works from any directory. If it isn't on PATH, use
+`uv tool update-shell` (or `pipx ensurepath`) and restart your shell.
+
+Alternatively, pass a quoted FEN.
+
+Options:
+
+- `--ascii` — use ASCII pieces
+- `--time 0.5` — set analysis time
+- `--lines 3` — show multiple lines
+- `--threads 2` — set engine threads, if supported
+- `--hash 256` — set engine hash size, if supported
+- `--engine /path/to/engine` — choose a UCI engine executable
+- `--white "Supi"` / `--black "Carlsen"` — label the players (override PGN names)
+
+## Stockfish
+
+Stockfish is the default engine and is installed separately. If it isn't found,
+the app detects your OS (and Linux distribution) and suggests an installation command:
+
+| Platform | Command |
+| --- | --- |
+| Debian/Ubuntu and derivatives (e.g. Linux Mint) | `sudo apt install stockfish` |
+| Arch and derivatives (e.g. Manjaro) | `sudo pacman -S stockfish` |
+| Fedora | `sudo dnf install stockfish` |
+| macOS (Homebrew) | `brew install stockfish` |
+| Windows (WinGet) | `winget install --id Stockfish.Stockfish --exact` |
+
+Other distros/platforms get the [official download link](https://stockfishchess.org/download/).
+
+After installation, make sure `stockfish` (`stockfish.exe` on Windows) is on
+PATH: add the executable’s directory to PATH and restart your shell if needed.
+Alternatively, pass an executable with `chess-analyzer --engine /path/to/stockfish`
+(on Windows: `chess-analyzer --engine "C:\path\to\stockfish.exe"`).
+
+Stockfish is found on PATH or beside the application module as `stockfish`
+(`stockfish.exe` on Windows). Other UCI engines can be selected with
+`--engine /path/to/engine`—for example, Leela Chess Zero (Lc0) with
+`--engine /path/to/lc0`. Configure engine-specific files and settings, such as
+Lc0's network weights and backend, separately. The app applies thread, hash,
+and multiple-line settings only when the engine supports them.
+
+## Navigation
+
+PGNs open at the final position and use their `White`/`Black` headers for player labels
+when present. Use `--white` and `--black` to set or override names, including for FENs.
+
+- **↑/↓** — choose an original move or engine alternative
+- **→/Enter** — follow the selected move; **←** — step back
+- **Esc** — return from an explored line to its game position
+- **f** — flip board; **r** — reanalyze; **q** — quit
+
+Moves, the return link, and any original-game move (or Start) are clickable.
+Branches are retained, and navigation never waits for analysis.
+
+Use at least 40×24 terminal cells. Larger boards use multiline pieces; smaller
+ones use chess glyphs. Narrow layouts stack the panels; scroll with the mouse
+wheel or Page Up/Down. Blue highlights the selected move, yellow the previous
+move, and red a checked king.
+
+## Renderer credits
+
+The piece artwork and size-adaptive rendering approach are adapted from
+[Thomas Mauran's chess-tui](https://github.com/thomas-mauran/chess-tui), using its
+[piece designs](https://github.com/thomas-mauran/chess-tui/tree/fc1d4841532bf72f5a25c5cb45abe82ec25e056b/src/pieces).
+The artwork is used under the MIT License; the full notice is preserved in
+[licenses/chess-tui-MIT.txt](licenses/chess-tui-MIT.txt). The rest of this project
+is released under [MIT](LICENSE).
+
+## Verify
+
+With Stockfish installed: `uv run python -m unittest discover -s tests -v`.

chess_analyzer_tui-0.1.1/chess_analyzer_tui.egg-info/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: chess-analyzer-tui
+Version: 0.1.1
+Summary: Terminal chess analysis TUI with Stockfish.
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/leolaurindo/chess-analyzer-tui
+Project-URL: Source, https://github.com/leolaurindo/chess-analyzer-tui
+Project-URL: Issues, https://github.com/leolaurindo/chess-analyzer-tui/issues
+Keywords: chess,stockfish,terminal,tui,analysis
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Games/Entertainment :: Board Games
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: licenses/chess-tui-MIT.txt
+Requires-Dist: chess>=1.11.2
+Requires-Dist: textual>=8.2.8
+Dynamic: license-file
+
+# Chess Analyzer TUI
+
+Interactive terminal chess analysis, with Stockfish as the default and support for other UCI engines.
+
+Piece rendering adapted from [Thomas Mauran's chess-tui](https://github.com/thomas-mauran/chess-tui).
+Full renderer credits and license information are below.
+
+## Install and run
+
+Requires Python 3.11+.
+
+Once published on PyPI, install the `chess-analyzer-tui` package with either tool
+manager. Both install the `chess-analyzer` command (the command name is not a
+separate PyPI package):
+
+```sh
+uv tool install chess-analyzer-tui   # or: pipx install chess-analyzer-tui
+chess-analyzer
+chess-analyzer --pgn game.pgn
+chess-analyzer --white "Supi" --black "Carlsen" "2kr2nr/1pp2ppp/3b4/1P3q2/2Pp1B2/5Q1P/RP3PP1/R5K1 w - - 0 1"
+```
+
+The command works from any directory. If it isn't on PATH, use
+`uv tool update-shell` (or `pipx ensurepath`) and restart your shell.
+
+Alternatively, pass a quoted FEN.
+
+Options:
+
+- `--ascii` — use ASCII pieces
+- `--time 0.5` — set analysis time
+- `--lines 3` — show multiple lines
+- `--threads 2` — set engine threads, if supported
+- `--hash 256` — set engine hash size, if supported
+- `--engine /path/to/engine` — choose a UCI engine executable
+- `--white "Supi"` / `--black "Carlsen"` — label the players (override PGN names)
+
+## Stockfish
+
+Stockfish is the default engine and is installed separately. If it isn't found,
+the app detects your OS (and Linux distribution) and suggests an installation command:
+
+| Platform | Command |
+| --- | --- |
+| Debian/Ubuntu and derivatives (e.g. Linux Mint) | `sudo apt install stockfish` |
+| Arch and derivatives (e.g. Manjaro) | `sudo pacman -S stockfish` |
+| Fedora | `sudo dnf install stockfish` |
+| macOS (Homebrew) | `brew install stockfish` |
+| Windows (WinGet) | `winget install --id Stockfish.Stockfish --exact` |
+
+Other distros/platforms get the [official download link](https://stockfishchess.org/download/).
+
+After installation, make sure `stockfish` (`stockfish.exe` on Windows) is on
+PATH: add the executable’s directory to PATH and restart your shell if needed.
+Alternatively, pass an executable with `chess-analyzer --engine /path/to/stockfish`
+(on Windows: `chess-analyzer --engine "C:\path\to\stockfish.exe"`).
+
+Stockfish is found on PATH or beside the application module as `stockfish`
+(`stockfish.exe` on Windows). Other UCI engines can be selected with
+`--engine /path/to/engine`—for example, Leela Chess Zero (Lc0) with
+`--engine /path/to/lc0`. Configure engine-specific files and settings, such as
+Lc0's network weights and backend, separately. The app applies thread, hash,
+and multiple-line settings only when the engine supports them.
+
+## Navigation
+
+PGNs open at the final position and use their `White`/`Black` headers for player labels
+when present. Use `--white` and `--black` to set or override names, including for FENs.
+
+- **↑/↓** — choose an original move or engine alternative
+- **→/Enter** — follow the selected move; **←** — step back
+- **Esc** — return from an explored line to its game position
+- **f** — flip board; **r** — reanalyze; **q** — quit
+
+Moves, the return link, and any original-game move (or Start) are clickable.
+Branches are retained, and navigation never waits for analysis.
+
+Use at least 40×24 terminal cells. Larger boards use multiline pieces; smaller
+ones use chess glyphs. Narrow layouts stack the panels; scroll with the mouse
+wheel or Page Up/Down. Blue highlights the selected move, yellow the previous
+move, and red a checked king.
+
+## Renderer credits
+
+The piece artwork and size-adaptive rendering approach are adapted from
+[Thomas Mauran's chess-tui](https://github.com/thomas-mauran/chess-tui), using its
+[piece designs](https://github.com/thomas-mauran/chess-tui/tree/fc1d4841532bf72f5a25c5cb45abe82ec25e056b/src/pieces).
+The artwork is used under the MIT License; the full notice is preserved in
+[licenses/chess-tui-MIT.txt](licenses/chess-tui-MIT.txt). The rest of this project
+is released under [MIT](LICENSE).
+
+## Verify
+
+With Stockfish installed: `uv run python -m unittest discover -s tests -v`.

chess_analyzer_tui-0.1.1/chess_analyzer_tui.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+chess_tui.py
+piece_art.py
+pyproject.toml
+chess_analyzer_tui.egg-info/PKG-INFO
+chess_analyzer_tui.egg-info/SOURCES.txt
+chess_analyzer_tui.egg-info/dependency_links.txt
+chess_analyzer_tui.egg-info/entry_points.txt
+chess_analyzer_tui.egg-info/requires.txt
+chess_analyzer_tui.egg-info/top_level.txt
+licenses/chess-tui-MIT.txt
+tests/test_chess_tui.py
+tests/test_cli.py

chess_analyzer_tui-0.1.1/chess_analyzer_tui.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

chess_analyzer_tui-0.1.1/chess_analyzer_tui.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+chess-analyzer = chess_tui:main

chess_analyzer_tui-0.1.1/chess_analyzer_tui.egg-info/requires.txt

@@ -0,0 +1,2 @@
+chess>=1.11.2
+textual>=8.2.8

chess_analyzer_tui-0.1.1/chess_analyzer_tui.egg-info/top_level.txt

@@ -0,0 +1,2 @@
+chess_tui
+piece_art

chess_analyzer_tui-0.1.1/chess_tui.py

@@ -0,0 +1,600 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import asyncio
+import math
+import os
+import platform
+import shutil
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import chess
+import chess.engine
+import chess.pgn
+from rich.style import Style
+from rich.text import Text
+from textual import work
+from textual.app import App, ComposeResult
+from textual.binding import Binding
+from textual.containers import Horizontal, Vertical, VerticalScroll
+from textual.events import Resize
+from textual.widget import Widget
+from textual.widgets import Footer, Header, Static
+
+from piece_art import PIECE_ART
+
+
+@dataclass
+class Candidate:
+    move: chess.Move
+    score: str
+    pv: str
+
+
+@dataclass
+class Node:
+    board: chess.Board
+    parent: Node | None = None
+    move_from_parent: chess.Move | None = None
+    mainline_next: Node | None = None
+    is_mainline: bool = False
+    candidates: list[Candidate] = field(default_factory=list)
+    selected: int = 0
+    children: dict[chess.Move, Node] = field(default_factory=dict)
+    analyzed: bool = False
+
+    def child(self, move: chess.Move) -> Node:
+        if move not in self.children:
+            board = self.board.copy()
+            board.push(move)
+            self.children[move] = Node(board, parent=self, move_from_parent=move)
+        return self.children[move]
+
+
+def find_stockfish() -> str | None:
+    local = Path(__file__).with_name("stockfish.exe" if os.name == "nt" else "stockfish")
+    paths = [shutil.which("stockfish"), str(local), "/usr/games/stockfish",
+             "/usr/bin/stockfish", "/usr/local/bin/stockfish"]
+    return next((p for p in paths if p and os.path.isfile(p) and os.access(p, os.X_OK)), None)
+
+
+def missing_engine_message() -> str:
+    system = platform.system()
+    label = "macOS" if system == "Darwin" else system
+    suggestion = "Download an executable from https://stockfishchess.org/download/"
+    if system == "Windows":
+        suggestion = "winget install --id Stockfish.Stockfish --exact"
+    elif system == "Darwin":
+        suggestion = "brew install stockfish (requires Homebrew)"
+    elif system == "Linux":
+        try:
+            release = platform.freedesktop_os_release()
+        except OSError:
+            release = {}
+        if release.get("PRETTY_NAME"):
+            label += f" ({release['PRETTY_NAME']})"
+        families = {release.get("ID"), *release.get("ID_LIKE", "").split()}
+        if families & {"debian", "ubuntu"}:
+            suggestion = "sudo apt install stockfish"
+        elif "arch" in families:
+            suggestion = "sudo pacman -S stockfish"
+        elif release.get("ID") == "fedora":
+            suggestion = "sudo dnf install stockfish"
+    executable = '"C:\\path\\to\\stockfish.exe"' if system == "Windows" else "/path/to/stockfish"
+    return (
+        "No engine detected on PATH or beside the application.\n"
+        f"OS detection: {label}\n"
+        f"Suggested Stockfish installation: {suggestion}\n"
+        "After installation, make sure Stockfish is on PATH; restart your shell if needed.\n"
+        f"Or pass any UCI engine: chess-analyzer --engine {executable}"
+    )
+
+
+def side_label(color: str, name: str) -> str:
+    return color if name == color else f"{color} · {name}"
+
+
+def format_score(score: chess.engine.PovScore) -> str:
+    """Evaluation in pawns, from White's perspective."""
+    white = score.white()
+    mate = white.mate()
+    if mate is not None:
+        sign = "" if white > chess.engine.Cp(0) else "-"
+        return f"{sign}M{abs(mate)}"
+    cp = white.score()
+    return "?" if cp is None else f"{cp / 100:+.2f}"
+
+
+def history_to_san(node: Node) -> str:
+    moves = []
+    while node.parent:
+        moves.append(node.move_from_parent)
+        node = node.parent
+    return node.board.variation_san(reversed(moves)) if moves else "(starting position)"
+
+
+class EvaluationBar(Widget):
+    def render(self) -> Text:
+        candidate = next(iter(self.app.current.candidates), None)
+        score = candidate.score if candidate else "0.00"
+        if score.startswith("M"):
+            white_share = 1.0
+        elif score.startswith("-M"):
+            white_share = 0.0
+        else:
+            white_share = 1 / (1 + math.exp(-float(score) / 1.5)) if score != "?" else 0.5
+        height = max(1, self.size.height)
+        white_rows = round(height * white_share)
+        return Text("\n").join(
+            Text("  ", style=f"on {'#f0f0e8' if row < white_rows else '#30343b'}")
+            for row in range(height)
+        )
+
+
+class ChessBoard(Widget):
+    """Native terminal cells; piece art is credited in piece_art.py and README.md."""
+
+    def render(self) -> Text:
+        app = self.app
+        board = app.current.board
+        selected = app.selected_move()
+        last = app.current.move_from_parent
+        files = list(range(7, -1, -1) if app.flipped else range(8))
+        ranks = range(8) if app.flipped else range(7, -1, -1)
+        cell_width = max(2, min(10, (self.size.width - 3) // 8))
+        cell_height = max(1, min(5, (self.size.height - 1) // 8))
+        art = {}
+        if not app.ascii_pieces:
+            for (height, width), sprites in PIECE_ART.items():
+                if cell_height >= height and cell_width >= width:
+                    art = sprites
+        text = Text(no_wrap=True)
+        for rank in ranks:
+            for row in range(cell_height):
+                text.append(f"{rank + 1}  " if row == cell_height // 2 else "   ")
+                for file in files:
+                    square = chess.square(file, rank)
+                    piece = board.piece_at(square)
+                    background = "#899779" if (rank + file) % 2 else "#536747"
+                    if last and square in (last.from_square, last.to_square):
+                        background = "#898e3c"
+                    if selected and square in (selected.from_square, selected.to_square):
+                        background = "#4c809c"
+                    if board.is_check() and square == board.king(board.turn):
+                        background = "#ad4b4b"
+                    symbol = " "
+                    if piece:
+                        lines = art[piece.piece_type] if art else (
+                            piece.symbol() if app.ascii_pieces else piece.unicode_symbol(),
+                        )
+                        piece_row = row - (cell_height // 2 - len(lines) // 2)
+                        if 0 <= piece_row < len(lines):
+                            symbol = lines[piece_row]
+                    color = "#ffffff" if art and piece and piece.color else "#121212"
+                    text.append(symbol.center(cell_width), style=f"bold {color} on {background}")
+                text.append("\n")
+        text.append("   " + "".join(chess.FILE_NAMES[file].center(cell_width) for file in files))
+        return text
+
+
+class ChessAnalysisApp(App):
+    TITLE = "Chess Analysis"
+    CSS = """
+    Widget { link-style: none; link-style-hover: none; }
+    Screen { background: #0d1117; color: #e6edf3; }
+    Header, Footer { background: #161b22; }
+    Static { height: auto; }
+    #main { height: 1fr; padding: 0 1; }
+    #board-side { width: 1fr; min-width: 22; padding: 0 1; }
+    #analysis-side {
+        width: 1fr; min-width: 27; border: round #30363d;
+        background: #161b22; padding: 0 1;
+    }
+    #position-info, #engine-title, .player-name { text-style: bold; }
+    .player-name { color: #c9d1d9; }
+    #board-area, #board {
+        width: 1fr; height: 1fr; min-height: 9; content-align: center middle;
+    }
+    #evaluation-bar { width: 2; height: 1fr; margin: 1 0; }
+    #fen, #status { color: #8b949e; }
+    #fen { max-height: 3; }
+    .narrow #main { layout: vertical; }
+    .narrow #board-side { width: 1fr; height: 14; }
+    .narrow #analysis-side { width: 1fr; height: 1fr; }
+    #engine-title, #return-game, #candidates { margin-bottom: 1; }
+    #return-game { color: #e3b341; }
+    #pv, #history { border-top: solid #30363d; padding-top: 1; margin-top: 1; }
+    #history { color: #c9d1d9; }
+    #status { margin-top: 1; }
+    """
+    BINDINGS = [
+        Binding("left", "previous_position", "Back", priority=True),
+        Binding("right", "next_position", "Follow", priority=True),
+        Binding("enter", "next_position", "Follow", show=False, priority=True),
+        Binding("up", "select_move(-1)", "Choose", priority=True),
+        Binding("down", "select_move(1)", "Choose", priority=True),
+        Binding("escape", "return_to_game", "Original game", priority=True),
+        ("f", "flip_board", "Flip"),
+        ("r", "reanalyze", "Re-analyze"),
+        ("q", "quit", "Quit"),
+    ]
+
+    def __init__(self, board: chess.Board, engine: chess.engine.UciProtocol,
+                 think_time: float, multipv: int, ascii_pieces: bool = False,
+                 moves: list[chess.Move] | None = None, engine_name: str = "Engine",
+                 white_name: str = "White", black_name: str = "Black"):
+        super().__init__()
+        self.engine = engine
+        self.think_time = think_time
+        self.multipv = multipv
+        self.ascii_pieces = ascii_pieces
+        self.engine_name = engine_name
+        self.white_name = white_name
+        self.black_name = black_name
+        self.has_pgn = moves is not None
+        self.root = Node(board.copy(), is_mainline=self.has_pgn)
+        self.current = self.root
+        self.return_position: Node | None = None
+        for move in moves or []:
+            child = self.current.child(move)
+            child.is_mainline = True
+            self.current.mainline_next = child
+            self.current = child
+        self.flipped = False
+        self.analysis_requested = asyncio.Event()
+
+    def compose(self) -> ComposeResult:
+        yield Header()
+        with Horizontal(id="main"):
+            with Vertical(id="board-side"):
+                yield Static(id="position-info")
+                yield Static(id="top-player", classes="player-name")
+                with Horizontal(id="board-area"):
+                    yield ChessBoard(id="board")
+                    yield EvaluationBar(id="evaluation-bar")
+                yield Static(id="bottom-player", classes="player-name")
+                yield Static(id="fen")
+            with VerticalScroll(id="analysis-side"):
+                for name in ("engine-title", "return-game", "candidates", "pv", "history", "status"):
+                    yield Static(id=name)
+        yield Footer()
+
+    def on_mount(self) -> None:
+        self.refresh_ui()
+        self.analyze_requested_position()
+        self.analysis_loop()
+
+    def on_resize(self, event: Resize) -> None:
+        self.screen.set_class(event.size.width < 64, "narrow")
+
+    def check_action(self, action: str, parameters: tuple[object, ...]) -> bool:
+        return action != "return_to_game" or self.return_position is not None
+
+    def refresh_ui(self) -> None:
+        self.refresh_board()
+        self.refresh_analysis_panel()
+        board = self.current.board
+        info = Text("White to move" if board.turn else "Black to move", style="bold")
+        if board.is_check():
+            info.append("   CHECKMATE" if board.is_checkmate() else "   CHECK", style="bold red")
+        if self.current.is_mainline:
+            info.append("   Original game", style="bold #e3b341")
+        elif self.return_position:
+            branch = self.return_position.board
+            turn = "." if branch.turn else "..."
+            info.append(f"   Exploring from {branch.fullmove_number}{turn} · Esc: game",
+                        style="bold #58a6ff")
+        self.query_one("#position-info", Static).update(info)
+        self.query_one("#fen", Static).update(Text(f"FEN  {board.fen()}", style="dim"))
+
+    def move_choices(self, node: Node) -> list[chess.Move | None]:
+        original = node.mainline_next.move_from_parent if node.mainline_next else None
+        # A non-playable end row prevents jumping from the PGN into an engine line.
+        moves = [original] if node.is_mainline else []
+        return moves + [c.move for c in node.candidates if c.move != original]
+
+    def selected_move(self) -> chess.Move | None:
+        moves = self.move_choices(self.current)
+        if not moves:
+            return None
+        self.current.selected %= len(moves)
+        return moves[self.current.selected]
+
+    def refresh_board(self) -> None:
+        self.query_one("#board", ChessBoard).refresh()
+        self.query_one("#evaluation-bar", EvaluationBar).refresh()
+        top_color, top_name, bottom_color, bottom_name = (
+            ("White", self.white_name, "Black", self.black_name) if self.flipped
+            else ("Black", self.black_name, "White", self.white_name)
+        )
+        self.query_one("#top-player", Static).update(side_label(top_color, top_name))
+        self.query_one("#bottom-player", Static).update(side_label(bottom_color, bottom_name))
+
+    def refresh_analysis_panel(self) -> None:
+        node = self.current
+        board = node.board
+        candidates = {c.move: c for c in node.candidates}
+        self.query_one("#engine-title", Static).update(
+            Text(f"{self.engine_name}   {self.think_time:g}s / {self.multipv} lines", style="bold")
+        )
+        return_link = self.query_one("#return-game", Static)
+        return_link.display = self.return_position is not None
+        return_link.update(Text("← Back to original game [Esc]", style=Style(
+            color="#e3b341", meta={"@click": "app.return_to_game"},
+        )))
+        selected_move = self.selected_move()
+        lines = Text("Next move · ↑/↓ choose\n", style="bold")
+        for index, move in enumerate(self.move_choices(node)):
+            original = node.is_mainline and index == 0
+            candidate = candidates.get(move)
+            san = board.san(move) if move else "End of original game"
+            label = "Original" if original else "Engine"
+            row = f"{'▶' if index == node.selected else ' '} {label:<9} {san}"
+            if candidate:
+                row += f"  {candidate.score}"
+            lines.append(row + "\n", style=Style(
+                color="#e3b341" if original else "#58a6ff", reverse=index == node.selected,
+                meta={"@click": f"app.follow_choice({index})"},
+            ))
+        lines.append("→ / Enter follows selection\n", style="dim")
+        if board.is_game_over():
+            lines.append(f"Game over: {board.result()}\n", style="dim")
+        elif not node.candidates:
+            lines.append("No engine lines. Press r to retry." if node.analyzed
+                         else "Engine is thinking…", style="dim")
+        self.query_one("#candidates", Static).update(lines)
+        candidate = candidates.get(selected_move)
+        pv = Text()
+        if selected_move is None and not board.is_game_over():
+            pv.append("↑/↓ choose an engine move to keep exploring.", style="dim")
+        elif candidate:
+            pv.append("Selected continuation\n\n", style="bold")
+            pv.append(candidate.pv)
+        elif node.mainline_next:
+            pv.append("Continue the original game with → or Enter.", style="dim")
+        self.query_one("#pv", Static).update(pv)
+
+        history = Text()
+        if self.has_pgn:
+            history.append("Original game · click a move\n", style="bold #e3b341")
+            anchor = node if node.is_mainline else self.return_position
+            history.append("Start", style=Style(
+                color="#e3b341", reverse=anchor is self.root,
+                meta={"@click": "app.game_position(0)"},
+            ))
+            cursor = self.root
+            index = 0
+            while cursor.mainline_next:
+                parent = cursor
+                cursor = cursor.mainline_next
+                index += 1
+                prefix = f"{parent.board.fullmove_number}. " if parent.board.turn else ""
+                if index == 1 and not parent.board.turn:
+                    prefix = f"{parent.board.fullmove_number}... "
+                history.append("  " + prefix + parent.board.san(cursor.move_from_parent), style=Style(
+                    color="#e3b341", reverse=cursor is anchor,
+                    meta={"@click": f"app.game_position({index})"},
+                ))
+            if not node.is_mainline:
+                history.append("\n\nExplored line\n", style="bold #58a6ff")
+                history.append(history_to_san(node))
+        else:
+            history.append("Current line\n\n", style="bold")
+            history.append(history_to_san(node))
+        self.query_one("#history", Static).update(history)
+
+    def set_status(self, message: str, style: str = "dim") -> None:
+        self.query_one("#status", Static).update(Text(message, style=style))
+
+    def analyze_requested_position(self) -> None:
+        self.analysis_requested.set()
+
+    @work(group="engine")
+    async def analysis_loop(self) -> None:
+        while True:
+            await self.analysis_requested.wait()
+            self.analysis_requested.clear()
+            node = self.current
+            if node.analyzed or node.board.is_game_over():
+                continue
+            self.set_status("Engine is thinking…", "yellow")
+            try:
+                analysis = await self.engine.analysis(
+                    node.board.copy(), chess.engine.Limit(time=self.think_time),
+                    multipv=self.multipv,
+                )
+                with analysis:
+                    finished = asyncio.create_task(analysis.wait())
+                    changed = asyncio.create_task(self.analysis_requested.wait())
+                    try:
+                        done, _ = await asyncio.wait(
+                            (finished, changed), return_when=asyncio.FIRST_COMPLETED,
+                        )
+                        if changed in done:
+                            analysis.stop()
+                        await finished
+                    finally:
+                        changed.cancel()
+                        await asyncio.gather(changed, return_exceptions=True)
+                if changed in done:
+                    continue
+            except chess.engine.EngineError as exc:
+                if node is self.current:
+                    self.set_status(f"Engine error: {exc} · r to retry", "bold red")
+                continue
+            previous = self.move_choices(node)
+            selected = previous[node.selected] if node.selected < len(previous) else None
+            node.candidates = [
+                Candidate(info["pv"][0], format_score(info["score"]),
+                          node.board.variation_san(info["pv"]))
+                for info in analysis.multipv if info.get("pv")
+            ]
+            node.analyzed = True
+            choices = self.move_choices(node)
+            node.selected = choices.index(selected) if selected in choices else 0
+            if node is self.current:
+                self.set_status("Analysis ready.")
+                self.refresh_ui()
+
+    def action_select_move(self, direction: int) -> None:
+        moves = self.move_choices(self.current)
+        if moves:
+            self.current.selected = (self.current.selected + direction) % len(moves)
+            self.refresh_board()
+            self.refresh_analysis_panel()
+
+    def action_next_position(self) -> None:
+        move = self.selected_move()
+        if move is not None:
+            if self.current.is_mainline:
+                original = self.current.mainline_next
+                self.return_position = (
+                    None if original and original.move_from_parent == move else self.current
+                )
+            self.show_position(self.current.child(move))
+
+    def action_follow_choice(self, index: int) -> None:
+        self.current.selected = index
+        self.action_next_position()
+
+    def action_game_position(self, index: int) -> None:
+        node = self.root
+        for _ in range(index):
+            if node.mainline_next is None:
+                break
+            node = node.mainline_next
+        self.return_position = None
+        node.selected = 0
+        self.show_position(node)
+
+    def show_position(self, node: Node) -> None:
+        self.current = node
+        self.refresh_bindings()
+        self.set_status("Analysis ready." if node.analyzed else "")
+        self.refresh_ui()
+        self.query_one("#candidates").scroll_visible(animate=False)
+        self.analyze_requested_position()
+
+    def action_return_to_game(self) -> None:
+        if self.return_position:
+            node = self.return_position
+            self.return_position = None
+            node.selected = 0
+            self.show_position(node)
+
+    def action_previous_position(self) -> None:
+        node = self.current.parent
+        if node:
+            if node.is_mainline:
+                self.return_position = None
+            self.show_position(node)
+
+    def action_flip_board(self) -> None:
+        self.flipped = not self.flipped
+        self.refresh_board()
+
+    def action_reanalyze(self) -> None:
+        self.current.analyzed = False
+        self.analyze_requested_position()
+
+
+async def run_app(args, board: chess.Board, engine_path: str, moves: list[chess.Move],
+                  white_name: str, black_name: str) -> None:
+    transport, engine = await chess.engine.popen_uci(engine_path)
+    try:
+        settings = {}
+        for name, value in {"Threads": args.threads, "Hash": args.hash}.items():
+            option = engine.options.get(name)
+            if option and option.type == "spin":
+                if option.min is not None:
+                    value = max(value, option.min)
+                if option.max is not None:
+                    value = min(value, option.max)
+                settings[name] = value
+        await engine.configure(settings)
+        multipv_option = engine.options.get("MultiPV")
+        multipv = args.lines if multipv_option else 1
+        if multipv_option:
+            if multipv_option.min is not None:
+                multipv = max(multipv, multipv_option.min)
+            if multipv_option.max is not None:
+                multipv = min(multipv, multipv_option.max)
+        engine_name = engine.id.get("name") or Path(engine_path).name
+        app = ChessAnalysisApp(board, engine, args.time, multipv, args.ascii,
+                               moves=moves if args.pgn else None, engine_name=engine_name,
+                               white_name=white_name, black_name=black_name)
+        await app.run_async()
+    finally:
+        try:
+            await asyncio.wait_for(engine.quit(), timeout=3)
+        finally:
+            transport.close()
+
+
+def player_name(value: str | None, fallback: str) -> str:
+    name = (value or "").strip()
+    return fallback if name in {"", "?"} else name
+
+
+def load_pgn(path: str) -> tuple[chess.Board, list[chess.Move], str, str]:
+    try:
+        with open(path, encoding="utf-8") as pgn_file:
+            game = chess.pgn.read_game(pgn_file)
+    except OSError as exc:
+        raise SystemExit(f"Could not read PGN: {exc}") from exc
+    if game is None:
+        raise SystemExit("The PGN file does not contain a game.")
+    if game.errors:
+        raise SystemExit(f"Could not parse PGN: {game.errors[0]}")
+    return (game.board(), list(game.mainline_moves()),
+            player_name(game.headers.get("White"), "White"),
+            player_name(game.headers.get("Black"), "Black"))
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="chess-analyzer", description="Interactive UCI chess engine analyzer.",
+    )
+    parser.add_argument("fen", nargs="?", help="FEN position (mutually exclusive with --pgn)")
+    parser.add_argument("--pgn", help="PGN file to analyze from its final position")
+    parser.add_argument("--white", help="White player's display name (overrides PGN header)")
+    parser.add_argument("--black", help="Black player's display name (overrides PGN header)")
+    parser.add_argument("-t", "--time", type=float, default=1.0, help="Thinking time per position")
+    parser.add_argument("-n", "--lines", type=int, default=5, help="Number of engine continuations")
+    parser.add_argument("--threads", type=int, default=2, help="Engine threads (if supported)")
+    parser.add_argument("--hash", type=int, default=256, help="Engine hash size in MB (if supported)")
+    parser.add_argument("--engine", help="Path to a UCI engine executable (default: Stockfish)")
+    parser.add_argument("--ascii", action="store_true", help="Use letters instead of chess glyphs")
+    args = parser.parse_args()
+    if not math.isfinite(args.time) or args.time <= 0:
+        parser.error("--time must be a positive, finite number")
+    if min(args.lines, args.threads, args.hash) < 1:
+        parser.error("--lines, --threads and --hash must be positive")
+    if args.fen and args.pgn:
+        parser.error("provide either a FEN or --pgn, not both")
+    moves = []
+    if args.pgn:
+        board, moves, pgn_white, pgn_black = load_pgn(args.pgn)
+    else:
+        pgn_white, pgn_black = "White", "Black"
+        try:
+            board = chess.Board(args.fen or chess.STARTING_FEN)
+        except ValueError as exc:
+            raise SystemExit(f"Invalid FEN: {exc}") from exc
+    white_name = player_name(args.white, pgn_white)
+    black_name = player_name(args.black, pgn_black)
+    if not board.is_valid():
+        raise SystemExit("The starting position is invalid.")
+    engine_path = args.engine or find_stockfish()
+    if not engine_path:
+        raise SystemExit(missing_engine_message())
+    try:
+        asyncio.run(run_app(args, board, engine_path, moves, white_name, black_name))
+    except (OSError, chess.engine.EngineError, asyncio.TimeoutError) as exc:
+        raise SystemExit(f"Engine error: {exc}") from exc
+
+
+if __name__ == "__main__":
+    main()

chess_analyzer_tui-0.1.1/licenses/chess-tui-MIT.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Thomas Mauran
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

chess_analyzer_tui-0.1.1/piece_art.py

@@ -0,0 +1,36 @@
+"""Piece art adapted from Thomas Mauran's chess-tui (MIT).
+
+Source: https://github.com/thomas-mauran/chess-tui/tree/fc1d4841532bf72f5a25c5cb45abe82ec25e056b/src/pieces
+Copyright (c) 2023 Thomas Mauran. See licenses/chess-tui-MIT.txt.
+"""
+
+import chess
+
+# (required rows, required columns), ordered from compact to large.
+PIECE_ART = {
+    (3, 5): {
+        chess.PAWN: ("  ▂  ", " ▆█▆ ", " ▔▔▔ "),
+        chess.KNIGHT: (" ▄▟▟▖", " ▂█▛▘", "▝▀▀▀▘"),
+        chess.BISHOP: (" ▆▖▆ ", " ▐▙▌ ", " ▀▀▀ "),
+        chess.ROOK: (" ▅ ▅ ", " ███ ", "▝▀▀▀▘"),
+        chess.QUEEN: (" ▆▄▆ ", " ▗█▖ ", " ▀▀▀ "),
+        chess.KING: ("▗▂╋▂▖", " ▀█▀ ", " ▀▀▀ "),
+    },
+    (4, 5): {
+        chess.PAWN: ("     ", " ▝█▘ ", " ▟█▙ ", " ▔▔▔ "),
+        chess.KNIGHT: ("  ▖▗ ", "▗▇▟█▌", " ▟█▛ ", "▝▀▀▀▘"),
+        chess.BISHOP: (" ▄▁▗ ", " ██▟ ", " ▟█▙ ", "▝▀▀▀▘"),
+        chess.ROOK: ("▄ ▄ ▄", "█████", " ███ ", "▀▀▀▀▀"),
+        chess.QUEEN: ("▂ ▄ ▂", "▜▙█▟▛", " ▜█▛ ", "▝▀▀▀▘"),
+        chess.KING: (" ▂╋▂ ", "▜███▛", " ▜█▛ ", "▝▀▀▀▘"),
+    },
+    (5, 7): {
+        chess.PAWN: ("     ", " ▄▇▄ ", " ▜█▛ ", "▄███▄", "▔▔▔▔▔"),
+        chess.KNIGHT: ("  ▅ ▅", " ▟▛███▖", "▝▀▜███▊", " ▗███▛ ", " ▀▀▀▀▀ "),
+        chess.BISHOP: ("▗▅  ▖", "██▍ █", "███▍█", "▝███▘", "▀▀▀▀▀"),
+        chess.ROOK: ("▗▄ ▃ ▄▖", "▐█▄█▄█▌", "▝▜███▛▘", " ▟███▙ ", "▝▀▀▀▀▀▘"),
+        chess.QUEEN: ("▗  ▂  ▖", "▐▙▟█▙▟▌", " ▜███▛ ", " ▗███▖ ", "▝▀▀▀▀▀▘"),
+        # Remove one column of outer padding to fit the shared seven-column size.
+        chess.KING: (" ▂▃╋▃▂ ", "▐█████▋", " ▜███▛ ", "  ▟█▙  ", " ▀▀▀▀▀ "),
+    },
+}

chess_analyzer_tui-0.1.1/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "chess-analyzer-tui"
+version = "0.1.1"
+description = "Terminal chess analysis TUI with Stockfish."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE", "licenses/chess-tui-MIT.txt"]
+keywords = ["chess", "stockfish", "terminal", "tui", "analysis"]
+classifiers = [
+    "Environment :: Console",
+    "Programming Language :: Python :: 3",
+    "Topic :: Games/Entertainment :: Board Games",
+]
+requires-python = ">=3.11"
+dependencies = [
+    "chess>=1.11.2",
+    "textual>=8.2.8",
+]
+
+[project.urls]
+Homepage = "https://github.com/leolaurindo/chess-analyzer-tui"
+Source = "https://github.com/leolaurindo/chess-analyzer-tui"
+Issues = "https://github.com/leolaurindo/chess-analyzer-tui/issues"
+
+[project.scripts]
+chess-analyzer = "chess_tui:main"
+
+[tool.setuptools]
+py-modules = ["chess_tui", "piece_art"]

chess_analyzer_tui-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

chess_analyzer_tui-0.1.1/tests/test_chess_tui.py

@@ -0,0 +1,152 @@
+import asyncio
+import tempfile
+import unittest
+import xml.etree.ElementTree as ET
+from pathlib import Path
+
+import chess
+import chess.engine
+
+from chess_tui import ChessAnalysisApp, find_stockfish, load_pgn
+
+
+def screen_text(app):
+    svg = ET.fromstring(app.export_screenshot())
+    return "".join("".join(e.itertext()) for e in svg.iter("{http://www.w3.org/2000/svg}text"))
+
+
+async def wait_for_analysis(app, pilot):
+    async def ready():
+        while not app.current.analyzed:
+            await asyncio.sleep(0.01)
+        await pilot.pause()
+
+    await asyncio.wait_for(ready(), timeout=4)
+
+
+class ChessTuiTests(unittest.IsolatedAsyncioTestCase):
+    async def asyncSetUp(self):
+        path = find_stockfish()
+        if not path:
+            self.skipTest("Stockfish is required for TUI integration tests")
+        self.transport, self.engine = await chess.engine.popen_uci(path)
+        await self.engine.configure({"Threads": 1, "Hash": 16})
+
+    async def asyncTearDown(self):
+        try:
+            await asyncio.wait_for(self.engine.quit(), timeout=3)
+        finally:
+            self.transport.close()
+
+    async def test_board_fits_and_large_pawns_stay_straight(self):
+        app = ChessAnalysisApp(chess.Board(), self.engine, 0.05, 3)
+        async with app.run_test(size=(80, 24)) as pilot:
+            await wait_for_analysis(app, pilot)
+            for width, height in [(80, 24), (42, 28), (160, 50), (144, 50)]:
+                with self.subTest(size=(width, height)):
+                    await pilot.resize_terminal(width, height)
+                    await pilot.pause()
+                    for selector in ("#board", "#analysis-side"):
+                        region = app.query_one(selector).region
+                        self.assertTrue(0 <= region.x < region.right <= width)
+                        self.assertTrue(1 <= region.y < region.bottom <= height - 1)
+                    visible = "".join(screen_text(app).split())
+                    self.assertIn("abcdefgh", visible)
+                    if width < 144:
+                        self.assertIn("♜♞♝♛♚♝♞♜", visible)
+                        self.assertIn("♖♘♗♕♔♗♘♖", visible)
+                        continue
+                    rows = app.query_one("#board").render().plain.splitlines()
+                    heads = [row for row in rows if "▄▇▄" in row]
+                    necks = [row for row in rows if "▜█▛" in row]
+                    bases = [row for row in rows if "▄███▄" in row]
+                    self.assertEqual((len(heads), len(necks), len(bases)), (2, 2, 2))
+                    for head, neck, base in zip(heads, necks, bases):
+                        centers = [i for i, char in enumerate(head) if char == "▇"]
+                        self.assertEqual(len(centers), 8)
+                        for center in centers:
+                            self.assertEqual(neck[center], "█")
+                            self.assertEqual(base[center - 2:center + 3], "▄███▄")
+
+    async def test_ascii_and_flip_work_even_with_room_for_art(self):
+        app = ChessAnalysisApp(chess.Board(), self.engine, 0.05, 3, ascii_pieces=True)
+        async with app.run_test(size=(160, 50)) as pilot:
+            await wait_for_analysis(app, pilot)
+            await pilot.pause()
+            visible = "".join(screen_text(app).split())
+            self.assertIn("8rnbqkbnr", visible)
+            self.assertIn("1RNBQKBNR", visible)
+            self.assertNotIn("╋", visible)
+            await pilot.press("f")
+            visible = "".join(screen_text(app).split())
+            self.assertIn("1RNBKQBNR", visible)
+            self.assertIn("hgfedcba", visible)
+
+    async def test_rapid_navigation_during_analysis_keeps_engine_usable(self):
+        moves = [chess.Move.from_uci(move) for move in
+                 ("e2e4", "e7e5", "g1f3", "b8c6", "f1c4", "g8f6")]
+        app = ChessAnalysisApp(chess.Board(), self.engine, 30, 5, moves=moves)
+        async with app.run_test(size=(80, 24)) as pilot:
+            for _ in range(12):
+                await asyncio.wait_for(pilot.press("left", "right"), timeout=2)
+            app.think_time = 0.05
+            await asyncio.wait_for(pilot.press("left"), timeout=2)
+            await wait_for_analysis(app, pilot)
+            self.assertTrue(app.current.candidates)
+            await asyncio.wait_for(pilot.press("right"), timeout=2)
+            await wait_for_analysis(app, pilot)
+            self.assertTrue(app.current.candidates)
+
+    async def test_pgn_navigation_and_exploration(self):
+        with tempfile.TemporaryDirectory() as directory:
+            path = Path(directory) / "game.pgn"
+            path.write_text('[Event "Test"]\n[White "Supi"]\n[Black "Carlsen"]\n\n1. e4 h5 *\n', encoding="utf-8")
+            board, moves, white_name, black_name = load_pgn(path)
+        final = board.copy()
+        for move in moves:
+            final.push(move)
+        app = ChessAnalysisApp(board, self.engine, 0.05, 3, moves=moves,
+                               white_name=white_name, black_name=black_name)
+        async with app.run_test(size=(120, 42)) as pilot:
+            await wait_for_analysis(app, pilot)
+            self.assertEqual(app.query_one("#top-player").render().plain, "Black · Carlsen")
+            self.assertEqual(app.query_one("#bottom-player").render().plain, "White · Supi")
+            await pilot.press("f")
+            self.assertEqual(app.query_one("#top-player").render().plain, "White · Supi")
+            self.assertEqual(app.query_one("#bottom-player").render().plain, "Black · Carlsen")
+            await pilot.press("f")
+            await pilot.press("right", "enter")
+            self.assertEqual(app.current.board.fen(), final.fen())  # Stop at the PGN's end.
+            app.think_time = 30
+            await pilot.press("left")
+            anchor = app.current.board.fen()
+            self.assertIn("Original", str(app.query_one("#candidates").render()))
+            await asyncio.wait_for(pilot.press("enter"), timeout=2)
+            self.assertEqual(app.current.board.fen(), final.fen())
+            app.think_time = 0.05
+            await pilot.press("left")
+            await wait_for_analysis(app, pilot)
+            await pilot.press("down", "right")
+            branch = app.current.board.fen()
+            self.assertFalse(app.current.is_mainline)
+            await wait_for_analysis(app, pilot)
+            self.assertIn("1...", str(app.query_one("#position-info").render()))
+            await pilot.press("right", "escape")
+            self.assertEqual(app.current.board.fen(), anchor)
+            await pilot.press("down", "right")
+            self.assertEqual(app.current.board.fen(), branch)
+            await pilot.click("#return-game")
+            self.assertEqual(app.current.board.fen(), anchor)
+            await pilot.press("enter")
+            self.assertEqual(app.current.board.fen(), final.fen())
+            await pilot.press("left")
+            await pilot.pause()
+            await pilot.click("#candidates", offset=(4, 2))
+            self.assertFalse(app.current.is_mainline)
+            await pilot.pause()
+            await pilot.click("#history", offset=(2, 3))
+            self.assertEqual(app.current.board.fen(), chess.STARTING_FEN)
+
+
+if __name__ == "__main__":
+    unittest.main()

chess_analyzer_tui-0.1.1/tests/test_cli.py

@@ -0,0 +1,40 @@
+import unittest
+from unittest.mock import patch
+
+from chess_tui import main
+
+
+class CliTests(unittest.TestCase):
+    def test_missing_engine_explains_installation_for_the_detected_os(self):
+        cases = [
+            ("Windows", {}, "Windows", "winget install --id Stockfish.Stockfish --exact"),
+            ("Darwin", {}, "macOS", "brew install stockfish"),
+            ("Linux", {"ID": "ubuntu"}, "Linux", "sudo apt install stockfish"),
+            ("Linux", {"ID": "linuxmint", "ID_LIKE": "ubuntu debian", "PRETTY_NAME": "Linux Mint"},
+             "Linux (Linux Mint)", "sudo apt install stockfish"),
+            ("Linux", {"ID": "manjaro", "ID_LIKE": "arch"}, "Linux", "sudo pacman -S stockfish"),
+            ("Linux", {"ID": "fedora"}, "Linux", "sudo dnf install stockfish"),
+            ("Linux", {"ID": "unknown"}, "Linux", "https://stockfishchess.org/download/"),
+            ("Linux", OSError("No os-release file"), "Linux", "https://stockfishchess.org/download/"),
+            ("FreeBSD", {}, "FreeBSD", "https://stockfishchess.org/download/"),
+        ]
+        for system, release, label, suggestion in cases:
+            with self.subTest(system=system, release=release):
+                with (
+                    patch("sys.argv", ["chess-analyzer"]),
+                    patch("chess_tui.find_stockfish", return_value=None),
+                    patch("platform.system", return_value=system),
+                    patch("platform.freedesktop_os_release", side_effect=[release]),
+                    self.assertRaises(SystemExit) as error,
+                ):
+                    main()
+                message = str(error.exception)
+                self.assertIn("No engine detected", message)
+                self.assertIn(f"OS detection: {label}", message)
+                self.assertIn(suggestion, message)
+                self.assertIn("make sure Stockfish is on PATH", message)
+                self.assertIn("chess-analyzer --engine", message)
+
+
+if __name__ == "__main__":
+    unittest.main()