A bilingual Chrome extension that provides real-time chess board detection, structural positioning evaluation, and dynamic auto-highlighting. Built as an educational tool for analyzing chess positions directly in the browser.
- Universal Board Detection: Dynamically reads DOM states and is compatible with modern web components like
cg-board,chess-board, and generic piece layouts. - Real-Time Observation: Uses a debounced
MutationObserverto automatically track piece movements without requiring manual page refreshes. - Smart Auto-Highlighting: Generates a synchronized, detached DOM overlay to visually indicate the engine's suggested move directly on the board, ensuring it doesn't interfere with the host website's native drag-and-drop mechanics.
- Animated Tug-of-War UI: Features a dynamic, animated progress bar that visualizes your win chance based on the current evaluation.
- Deep Customization: Includes a settings panel to toggle Dark/Bright modes, upload custom app backgrounds, add custom corner stickers/GIFs to the highlighted squares, and customize the highlight colors.
- Bilingual Interface: Fully supports both English and Kurdish (Sorani), dynamically adjusting text direction (LTR/RTL) and typography using the Vazirmatn font.
- Clone this repository or download the source code as a ZIP file and extract it.
- Open Google Chrome and navigate to
chrome://extensions/. - Enable Developer mode (the toggle located in the top right corner).
- Click Load unpacked in the top left.
- Select the extracted
chesscube-extensiondirectory.
- Navigate to a webpage containing a supported chess board.
- Click the ChessCube Assistant icon in your Chrome toolbar to open the side panel.
- The extension will automatically detect the board, determine your playing color, parse the position, and fetch the evaluation.
- The best move will be automatically highlighted on the board.
- Click the ⚙️ (Gear Icon) in the side panel header to open the customizations menu and personalize your UI.
- If the board state gets out of sync or you navigate to a new game, click the ↻ (Rescan) icon in the side panel header to manually trigger a fresh DOM scan and clear existing highlights.
ChessCube operates using a decoupled architecture, separating DOM observation, API communication, and state management into specific extension components.
The background script acts as the central message router and state manager.
- Injection Logic: To save memory, it safely manages the programmatic injection of the content script into the active tab only when the user opens the side panel.
- Event Routing: It listens for board state changes from the content script, relays them to the side panel, and routes highlight commands and user preferences back to the active webpage.
This script handles all direct interaction with the host webpage's DOM.
- Board Parsing Logic: It scans for standard chess board elements and extracts piece positions based on CSS classes and 2D transform coordinates. It then reverse-engineers the board state into a standard FEN (Forsyth–Edwards Notation) string.
- Highlight Overlay Logic: Instead of injecting elements directly into complex virtual DOMs, it calculates the
getBoundingClientRect()of the board. It then creates a detachedabsoluteoverlay fixed to the documentbody, mapping standard algebraic notation to X/Y percentages. It recalculates these positions automatically on window resize or scroll.
The side panel serves as the user interface and the external communicator.
- Evaluation Logic: It receives the valid FEN string from the background worker and sends an asynchronous payload to a public Stockfish 16 API (
chess-api.com/v1). - Data Parsing: It processes the returned JSON to extract centipawn evaluations, calculate win-chance percentages, and format the principal variation (PV) lines.
- Error Handling: It strictly validates structural anomalies to prevent math errors or crashes if an illegal FEN is accidentally generated during piece animations.