reznum-minesweeper 0.2.2__tar.gz

reznum_minesweeper-0.2.2/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.2] - 2026-09-19
+
+### Added
+- Rich interactive Terminal User Interface (TUI) with responsive styling.
+- 7 distinct color themes: Classic, Ocean, Matrix, Dracula, Cyberpunk, Nord, and Monochrome.
+- Traditional Minesweeper engine with first-move protection guaranteeing a safe initial cell.
+- Predefined difficulty levels: Easy (9x9), Medium (16x16), Hard (30x16), and Expert (30x24).
+- Custom game mode with interactive dimension and mine count validation.
+- Responsive board viewport scrolling for smaller terminals, phones, and Termux on Android.
+- Cross-platform single-key input (`readchar`) with seamless fallback to line/command input mode.
+- Fully customizable keybindings with collision validation and default reset.
+- Persistent high scores, best completion times, and statistics per difficulty.
+- Custom game statistics tracking.
+- Dedicated "About the Creator" screen and comprehensive "How to Play" guide.
+- CLI flags support: `--difficulty`, `--custom`, `--theme`, `--version`, and `--help`.
+- Automated test suite covering board logic, game loop, persistence, settings, and CLI.
+- GitHub Actions CI matrix for tests across Windows, Linux, and macOS.
+
+## [0.2.0] - 2026-08-15
+- Prototype terminal board rendering.
+- Basic cell reveal and flag mechanics.
+
+## [0.1.0] - 2026-07-01
+- Initial core engine proof-of-concept.

reznum_minesweeper-0.2.2/CONTRIBUTING.md

@@ -0,0 +1,62 @@
+# Contributing to Minesweeper CLI
+
+Thank you for your interest in contributing to Minesweeper CLI! We welcome bug reports, feature suggestions, and pull requests.
+
+## Development Setup
+
+1. **Clone the repository:**
+   ```bash
+   git clone https://github.com/ItsReZNuM/Minesweeper-CLI.git
+   cd Minesweeper-CLI
+   ```
+
+2. **Create a virtual environment (recommended):**
+   ```bash
+   python -m venv .venv
+   # Windows:
+   .venv\Scripts\activate
+   # Linux/macOS:
+   source .venv/bin/activate
+   ```
+
+3. **Install the package in editable mode with development dependencies:**
+   ```bash
+   python -m pip install -e ".[dev]"
+   ```
+
+4. **Run the game:**
+   ```bash
+   minesweeper
+   # or
+   python -m minesweeper_cli
+   ```
+
+## Running Tests
+
+Ensure all automated tests pass before submitting a pull request:
+```bash
+python -m pytest tests/ -v
+```
+
+## Packaging Verification
+
+Check distribution builds:
+```bash
+python -m build
+python -m twine check dist/*
+```
+
+## Code Guidelines
+
+- Target **Python 3.10+**.
+- Follow **PEP 8** style conventions.
+- Maintain cross-platform compatibility (Windows, Linux, macOS, Android/Termux).
+- Avoid unnecessary external dependencies.
+- Keep comments concise and reserved for non-obvious algorithms or platform quirks.
+- Write tests for new gameplay logic or CLI behaviors.
+
+## Submitting Pull Requests
+
+1. Create a feature branch: `git checkout -b feature/your-feature-name`.
+2. Commit changes using clear, descriptive messages.
+3. Push to your branch and open a Pull Request with a summary of changes.

reznum_minesweeper-0.2.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ItsReZNuM
+
+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.

reznum_minesweeper-0.2.2/MANIFEST.in

@@ -0,0 +1,7 @@
+include README.md
+include LICENSE
+include CHANGELOG.md
+include CONTRIBUTING.md
+include pyproject.toml
+recursive-include src/minesweeper_cli *.py py.typed
+recursive-include tests *.py

reznum_minesweeper-0.2.2/PKG-INFO

@@ -0,0 +1,288 @@
+Metadata-Version: 2.4
+Name: reznum-minesweeper
+Version: 0.2.2
+Summary: A modern, beautiful, and interactive terminal Minesweeper game written in Python with Rich.
+Author: ItsReZNuM
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ItsReZNuM/Minesweeper-CLI
+Project-URL: Repository, https://github.com/ItsReZNuM/Minesweeper-CLI
+Project-URL: Issues, https://github.com/ItsReZNuM/Minesweeper-CLI/issues
+Project-URL: Changelog, https://github.com/ItsReZNuM/Minesweeper-CLI/blob/main/CHANGELOG.md
+Keywords: minesweeper,cli,terminal,game,rich,cross-platform,termux,retro,tui
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Games/Entertainment :: Board Games
+Classifier: Topic :: Games/Entertainment :: Puzzle Games
+Classifier: Topic :: Terminals
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: rich>=13.0.0
+Requires-Dist: readchar>=4.0.0
+Requires-Dist: platformdirs>=3.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: build>=1.0.0; extra == "dev"
+Requires-Dist: twine>=5.0.0; extra == "dev"
+Dynamic: license-file
+
+# Minesweeper CLI 💣
+
+[![PyPI Version](https://img.shields.io/pypi/v/reznum-minesweeper.svg)](https://pypi.org/project/reznum-minesweeper/)
+[![Tests & Lint](https://github.com/ItsReZNuM/Minesweeper-CLI/actions/workflows/tests.yml/badge.svg)](https://github.com/ItsReZNuM/Minesweeper-CLI/actions/workflows/tests.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python Version](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue)](https://www.python.org/)
+[![Code Style](https://img.shields.io/badge/code%20style-pep8-brightgreen.svg)](https://pep8.org/)
+
+A modern, colorful, production-quality terminal Minesweeper game built in Python using [Rich](https://github.com/Textualize/rich). Designed for cross-platform play across Windows (CMD, PowerShell, Windows Terminal), Linux, macOS, SSH, and Android (Termux).
+
+```text
+┌────────────────────────────────────────────────────────────┐
+│                    💣 MINESWEEPER CLI 💣                   │
+├────────────────────────────────────────────────────────────┤
+│  Medium   💣 Mines: 40  🚩 Flags: 12  Left: 28   ⏱️ 01:42   │
+├────────────────────────────────────────────────────────────┤
+│                     Minesweeper Board                      │
+│     00 01 02 03 04 05 06 07 08 09 10 11 12 13 14 15        │
+│  0 │ ·  ·  1  ■  ■  ■  ■  ■  ■  ■  ■  ■  ■  ■  ■  ■        │
+│  1 │ 1  1  2  ■ [2] ■  ■  ■  ■  ■  ■  ■  ■  ■  ■  ■        │
+│  2 │ 0  0  1  ■  🚩 ■  ■  ■  ■  ■  ■  ■  ■  ■  ■  ■        │
+│  3 │ 0  0  1  1  2  ■  ■  ■  ■  ■  ■  ■  ■  ■  ■  ■        │
+│  4 │ 1  1  0  0  1  ■  ■  ■  ■  ■  ■  ■  ■  ■  ■  ■        │
+└────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## ✨ Features
+
+- **First-Move Protection**: Your first clicked tile is guaranteed safe and opens up the initial clearing.
+- **7 Visual Themes**: Classic, Ocean, Matrix, Dracula, Cyberpunk, Nord, and Monochrome.
+- **Predefined Difficulties**:
+  - **Easy**: 9x9 board with 10 mines
+  - **Medium**: 16x16 board with 40 mines
+  - **Hard**: 30x16 board with 99 mines
+  - **Expert**: 30x24 board with 150 mines
+- **Custom Board Mode**: Configure your own width (4–60), height (4–40), and mine density.
+- **Chord Reveal**: Press `C` on a revealed number when all surrounding flags are placed to instantly open remaining neighbors.
+- **Cross-Platform Single-Key Input**: Responsive single-key control (`readchar`) with automatic fallback to Enter-based command mode if raw terminal mode is unavailable.
+- **Responsive Layout & Viewport Scrolling**: Auto-scrolls and pans around the cursor on small screens, preventing broken line wraps in mobile terminals like Termux.
+- **Configurable Controls**: Remap any gameplay action with key conflict validation.
+- **Persistent High Scores & Statistics**: Tracks completion best times, total games played, wins, losses, and custom configurations.
+- **Zero Heavy Frameworks**: Pure Python with lightweight, high-performance terminal rendering.
+
+---
+
+## 🚀 Installation
+
+### Local Development Installation (Current)
+
+Clone the repository and install in editable mode:
+
+```bash
+git clone https://github.com/ItsReZNuM/Minesweeper-CLI.git
+cd Minesweeper-CLI
+python -m pip install -e .
+```
+
+You can now run the game directly:
+
+```bash
+minesweeper
+```
+
+Or run via module execution without PATH modification:
+
+```bash
+python -m minesweeper_cli
+```
+
+### PyPI Installation
+
+Install directly from PyPI:
+
+```bash
+pip install reznum-minesweeper
+minesweeper
+```
+
+---
+
+## 🎮 How to Play & Controls
+
+Navigate the cursor over tiles, reveal safe cells, and flag suspected mines.
+
+### Default Controls
+
+| Action | Default Keys | Description |
+| :--- | :--- | :--- |
+| **Move Cursor** | `W` / `A` / `S` / `D` or `Arrow Keys` | Move cursor Up, Left, Down, Right |
+| **Reveal Cell** | `Enter` or `Space` | Open hidden cell at cursor |
+| **Toggle Flag** | `F` | Place or remove a flag on cursor |
+| **Chord Reveal**| `C` | Open all adjacent unflagged cells |
+| **Restart Game**| `R` | Reset and generate a fresh board |
+| **Quit to Menu**| `Q` or `Esc` | Return to main menu |
+
+### Fallback Command Mode
+
+If running in non-interactive terminals, redirected streams, or legacy shells without raw input support:
+- Type `w`, `a`, `s`, `d` to move.
+- Type `r` to reveal or `f` to flag.
+- Type direct coordinates: `r <x> <y>` to reveal cell `(x, y)` or `f <x> <y>` to flag `(x, y)`.
+- Type `q` to return to the menu.
+
+---
+
+## ⚙️ Command-Line Arguments
+
+Launch directly into specific game modes or themes:
+
+```bash
+# Display help and usage
+minesweeper --help
+
+# Display version
+minesweeper --version
+
+# Directly launch specific difficulty preset
+minesweeper --difficulty easy
+minesweeper --difficulty medium
+minesweeper --difficulty hard
+minesweeper --difficulty expert
+
+# Directly open custom board configuration dialog
+minesweeper --custom
+
+# Select a visual theme on launch
+minesweeper --theme matrix
+```
+
+---
+
+## 🎨 Themes Showcase
+
+Themes alter board colors, borders, menus, status indicators, and numbers 1–8:
+
+1. **Classic**: Traditional Windows Minesweeper palette with bright primary numbers.
+2. **Matrix**: Digital phosphor rain with emerald borders and hacker aesthetic.
+3. **Ocean**: Deep blues, cyan reefs, and serene marine highlights.
+4. **Dracula**: Modern dark mode with purple, pink, and vibrant accents.
+5. **Cyberpunk**: High-voltage neon yellow, electric magenta, and neon cyan.
+6. **Nord**: Cool arctic blues, slate gray, and pastel typography.
+7. **Monochrome**: High-contrast grayscale suitable for any 8-color terminal or monochrome display.
+
+You can switch themes in **Settings > Theme** or via `minesweeper --theme <name>`.
+
+---
+
+## 📱 Termux & Mobile Compatibility
+
+Minesweeper CLI is built to run smoothly on Android via **Termux**:
+- Viewport auto-centers around the cursor when boards are wider than the terminal.
+- Supports compact rendering mode (`Settings > Compact Mode: ON` or auto-detected).
+- Uses standard terminal character fallbacks if your mobile font lacks full Unicode emoji support.
+
+To install on Termux:
+```bash
+pkg update && pkg install python git
+git clone https://github.com/ItsReZNuM/Minesweeper-CLI.git
+cd Minesweeper-CLI
+pip install -e .
+minesweeper
+```
+
+---
+
+## 📁 Project Structure
+
+```text
+Minesweeper-CLI/
+├── .github/
+│   └── workflows/
+│       ├── tests.yml        # CI test matrix (Python 3.10-3.13 on Linux/Win/macOS)
+│       └── release.yml      # Release packaging automation
+├── src/
+│   └── minesweeper_cli/
+│       ├── __init__.py      # Package version and metadata
+│       ├── __main__.py      # python -m minesweeper_cli entrypoint
+│       ├── board.py         # Pure engine logic, flood-fill, chords, win/loss
+│       ├── cell.py          # Cell data structure and state
+│       ├── cli.py           # Command-line argument parsing and dispatcher
+│       ├── config.py        # Difficulty presets and application constants
+│       ├── controls.py      # Action mappings, key normalization, conflict checks
+│       ├── game.py          # Interactive game session and viewport scrolling
+│       ├── menu.py          # Main menu, custom dialogs, settings, records
+│       ├── persistence.py   # Atomic filesystem storage using platformdirs
+│       ├── platform_compat.py # Cross-platform single-key reader & fallback
+│       ├── records.py       # Best times and gameplay statistics tracker
+│       ├── renderer.py      # Rich terminal UI components and styling
+│       ├── settings.py      # User configuration and keybinding storage
+│       ├── themes.py        # 7 distinct color themes
+│       ├── timer.py         # Non-busy monotonic gameplay duration timer
+│       └── py.typed         # PEP 561 type marker
+├── tests/
+│   ├── test_board.py        # Board generation, rules, chords, win/loss
+│   ├── test_cli.py          # CLI flags and arguments
+│   ├── test_controls.py     # Control mappings and conflict validation
+│   ├── test_game.py         # Viewport calculation and command parser
+│   ├── test_records.py      # Statistics, best times, custom records
+│   └── test_settings.py     # Settings persistence and corrupted data recovery
+├── CHANGELOG.md             # Semantic version history
+├── CONTRIBUTING.md          # Contribution guidelines
+├── LICENSE                  # MIT License
+├── MANIFEST.in              # Package manifest
+├── pyproject.toml           # Modern PEP 517/621 packaging configuration
+└── README.md
+```
+
+---
+
+## 🧪 Testing
+
+Run the automated test suite with `pytest`:
+
+```bash
+python -m pytest tests/ -v
+```
+
+---
+
+## 📦 Building and Packaging
+
+Build the source distribution and wheel:
+
+```bash
+python -m build
+```
+
+Verify the distribution packages:
+
+```bash
+python -m twine check dist/*
+```
+
+---
+
+## 👤 Author
+
+**Made with ❤️ by ItsReZNuM**
+
+- **GitHub Profile**: [https://github.com/ItsReZNuM](https://github.com/ItsReZNuM)
+- **Repository**: [https://github.com/ItsReZNuM/Minesweeper-CLI](https://github.com/ItsReZNuM/Minesweeper-CLI)
+- **Telegram**: [https://t.me/ItsReZNuM](https://t.me/ItsReZNuM)
+- **Instagram**: [https://instagram.com/rez.num](https://instagram.com/rez.num)
+
+⭐ **Enjoying the game?** Please consider starring the repository on GitHub! It means a lot and supports future development.
+
+---
+
+## 📄 License
+
+This project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.

reznum_minesweeper-0.2.2/README.md

@@ -0,0 +1,253 @@
+# Minesweeper CLI 💣
+
+[![PyPI Version](https://img.shields.io/pypi/v/reznum-minesweeper.svg)](https://pypi.org/project/reznum-minesweeper/)
+[![Tests & Lint](https://github.com/ItsReZNuM/Minesweeper-CLI/actions/workflows/tests.yml/badge.svg)](https://github.com/ItsReZNuM/Minesweeper-CLI/actions/workflows/tests.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python Version](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue)](https://www.python.org/)
+[![Code Style](https://img.shields.io/badge/code%20style-pep8-brightgreen.svg)](https://pep8.org/)
+
+A modern, colorful, production-quality terminal Minesweeper game built in Python using [Rich](https://github.com/Textualize/rich). Designed for cross-platform play across Windows (CMD, PowerShell, Windows Terminal), Linux, macOS, SSH, and Android (Termux).
+
+```text
+┌────────────────────────────────────────────────────────────┐
+│                    💣 MINESWEEPER CLI 💣                   │
+├────────────────────────────────────────────────────────────┤
+│  Medium   💣 Mines: 40  🚩 Flags: 12  Left: 28   ⏱️ 01:42   │
+├────────────────────────────────────────────────────────────┤
+│                     Minesweeper Board                      │
+│     00 01 02 03 04 05 06 07 08 09 10 11 12 13 14 15        │
+│  0 │ ·  ·  1  ■  ■  ■  ■  ■  ■  ■  ■  ■  ■  ■  ■  ■        │
+│  1 │ 1  1  2  ■ [2] ■  ■  ■  ■  ■  ■  ■  ■  ■  ■  ■        │
+│  2 │ 0  0  1  ■  🚩 ■  ■  ■  ■  ■  ■  ■  ■  ■  ■  ■        │
+│  3 │ 0  0  1  1  2  ■  ■  ■  ■  ■  ■  ■  ■  ■  ■  ■        │
+│  4 │ 1  1  0  0  1  ■  ■  ■  ■  ■  ■  ■  ■  ■  ■  ■        │
+└────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## ✨ Features
+
+- **First-Move Protection**: Your first clicked tile is guaranteed safe and opens up the initial clearing.
+- **7 Visual Themes**: Classic, Ocean, Matrix, Dracula, Cyberpunk, Nord, and Monochrome.
+- **Predefined Difficulties**:
+  - **Easy**: 9x9 board with 10 mines
+  - **Medium**: 16x16 board with 40 mines
+  - **Hard**: 30x16 board with 99 mines
+  - **Expert**: 30x24 board with 150 mines
+- **Custom Board Mode**: Configure your own width (4–60), height (4–40), and mine density.
+- **Chord Reveal**: Press `C` on a revealed number when all surrounding flags are placed to instantly open remaining neighbors.
+- **Cross-Platform Single-Key Input**: Responsive single-key control (`readchar`) with automatic fallback to Enter-based command mode if raw terminal mode is unavailable.
+- **Responsive Layout & Viewport Scrolling**: Auto-scrolls and pans around the cursor on small screens, preventing broken line wraps in mobile terminals like Termux.
+- **Configurable Controls**: Remap any gameplay action with key conflict validation.
+- **Persistent High Scores & Statistics**: Tracks completion best times, total games played, wins, losses, and custom configurations.
+- **Zero Heavy Frameworks**: Pure Python with lightweight, high-performance terminal rendering.
+
+---
+
+## 🚀 Installation
+
+### Local Development Installation (Current)
+
+Clone the repository and install in editable mode:
+
+```bash
+git clone https://github.com/ItsReZNuM/Minesweeper-CLI.git
+cd Minesweeper-CLI
+python -m pip install -e .
+```
+
+You can now run the game directly:
+
+```bash
+minesweeper
+```
+
+Or run via module execution without PATH modification:
+
+```bash
+python -m minesweeper_cli
+```
+
+### PyPI Installation
+
+Install directly from PyPI:
+
+```bash
+pip install reznum-minesweeper
+minesweeper
+```
+
+---
+
+## 🎮 How to Play & Controls
+
+Navigate the cursor over tiles, reveal safe cells, and flag suspected mines.
+
+### Default Controls
+
+| Action | Default Keys | Description |
+| :--- | :--- | :--- |
+| **Move Cursor** | `W` / `A` / `S` / `D` or `Arrow Keys` | Move cursor Up, Left, Down, Right |
+| **Reveal Cell** | `Enter` or `Space` | Open hidden cell at cursor |
+| **Toggle Flag** | `F` | Place or remove a flag on cursor |
+| **Chord Reveal**| `C` | Open all adjacent unflagged cells |
+| **Restart Game**| `R` | Reset and generate a fresh board |
+| **Quit to Menu**| `Q` or `Esc` | Return to main menu |
+
+### Fallback Command Mode
+
+If running in non-interactive terminals, redirected streams, or legacy shells without raw input support:
+- Type `w`, `a`, `s`, `d` to move.
+- Type `r` to reveal or `f` to flag.
+- Type direct coordinates: `r <x> <y>` to reveal cell `(x, y)` or `f <x> <y>` to flag `(x, y)`.
+- Type `q` to return to the menu.
+
+---
+
+## ⚙️ Command-Line Arguments
+
+Launch directly into specific game modes or themes:
+
+```bash
+# Display help and usage
+minesweeper --help
+
+# Display version
+minesweeper --version
+
+# Directly launch specific difficulty preset
+minesweeper --difficulty easy
+minesweeper --difficulty medium
+minesweeper --difficulty hard
+minesweeper --difficulty expert
+
+# Directly open custom board configuration dialog
+minesweeper --custom
+
+# Select a visual theme on launch
+minesweeper --theme matrix
+```
+
+---
+
+## 🎨 Themes Showcase
+
+Themes alter board colors, borders, menus, status indicators, and numbers 1–8:
+
+1. **Classic**: Traditional Windows Minesweeper palette with bright primary numbers.
+2. **Matrix**: Digital phosphor rain with emerald borders and hacker aesthetic.
+3. **Ocean**: Deep blues, cyan reefs, and serene marine highlights.
+4. **Dracula**: Modern dark mode with purple, pink, and vibrant accents.
+5. **Cyberpunk**: High-voltage neon yellow, electric magenta, and neon cyan.
+6. **Nord**: Cool arctic blues, slate gray, and pastel typography.
+7. **Monochrome**: High-contrast grayscale suitable for any 8-color terminal or monochrome display.
+
+You can switch themes in **Settings > Theme** or via `minesweeper --theme <name>`.
+
+---
+
+## 📱 Termux & Mobile Compatibility
+
+Minesweeper CLI is built to run smoothly on Android via **Termux**:
+- Viewport auto-centers around the cursor when boards are wider than the terminal.
+- Supports compact rendering mode (`Settings > Compact Mode: ON` or auto-detected).
+- Uses standard terminal character fallbacks if your mobile font lacks full Unicode emoji support.
+
+To install on Termux:
+```bash
+pkg update && pkg install python git
+git clone https://github.com/ItsReZNuM/Minesweeper-CLI.git
+cd Minesweeper-CLI
+pip install -e .
+minesweeper
+```
+
+---
+
+## 📁 Project Structure
+
+```text
+Minesweeper-CLI/
+├── .github/
+│   └── workflows/
+│       ├── tests.yml        # CI test matrix (Python 3.10-3.13 on Linux/Win/macOS)
+│       └── release.yml      # Release packaging automation
+├── src/
+│   └── minesweeper_cli/
+│       ├── __init__.py      # Package version and metadata
+│       ├── __main__.py      # python -m minesweeper_cli entrypoint
+│       ├── board.py         # Pure engine logic, flood-fill, chords, win/loss
+│       ├── cell.py          # Cell data structure and state
+│       ├── cli.py           # Command-line argument parsing and dispatcher
+│       ├── config.py        # Difficulty presets and application constants
+│       ├── controls.py      # Action mappings, key normalization, conflict checks
+│       ├── game.py          # Interactive game session and viewport scrolling
+│       ├── menu.py          # Main menu, custom dialogs, settings, records
+│       ├── persistence.py   # Atomic filesystem storage using platformdirs
+│       ├── platform_compat.py # Cross-platform single-key reader & fallback
+│       ├── records.py       # Best times and gameplay statistics tracker
+│       ├── renderer.py      # Rich terminal UI components and styling
+│       ├── settings.py      # User configuration and keybinding storage
+│       ├── themes.py        # 7 distinct color themes
+│       ├── timer.py         # Non-busy monotonic gameplay duration timer
+│       └── py.typed         # PEP 561 type marker
+├── tests/
+│   ├── test_board.py        # Board generation, rules, chords, win/loss
+│   ├── test_cli.py          # CLI flags and arguments
+│   ├── test_controls.py     # Control mappings and conflict validation
+│   ├── test_game.py         # Viewport calculation and command parser
+│   ├── test_records.py      # Statistics, best times, custom records
+│   └── test_settings.py     # Settings persistence and corrupted data recovery
+├── CHANGELOG.md             # Semantic version history
+├── CONTRIBUTING.md          # Contribution guidelines
+├── LICENSE                  # MIT License
+├── MANIFEST.in              # Package manifest
+├── pyproject.toml           # Modern PEP 517/621 packaging configuration
+└── README.md
+```
+
+---
+
+## 🧪 Testing
+
+Run the automated test suite with `pytest`:
+
+```bash
+python -m pytest tests/ -v
+```
+
+---
+
+## 📦 Building and Packaging
+
+Build the source distribution and wheel:
+
+```bash
+python -m build
+```
+
+Verify the distribution packages:
+
+```bash
+python -m twine check dist/*
+```
+
+---
+
+## 👤 Author
+
+**Made with ❤️ by ItsReZNuM**
+
+- **GitHub Profile**: [https://github.com/ItsReZNuM](https://github.com/ItsReZNuM)
+- **Repository**: [https://github.com/ItsReZNuM/Minesweeper-CLI](https://github.com/ItsReZNuM/Minesweeper-CLI)
+- **Telegram**: [https://t.me/ItsReZNuM](https://t.me/ItsReZNuM)
+- **Instagram**: [https://instagram.com/rez.num](https://instagram.com/rez.num)
+
+⭐ **Enjoying the game?** Please consider starring the repository on GitHub! It means a lot and supports future development.
+
+---
+
+## 📄 License
+
+This project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.