About ChessVectors
ChessVectors is an interactive chess visualization tool that helps players understand positional relationships between pieces through visual attack and defense vectors.
What Makes It Unique
Unlike traditional chess interfaces that only show legal moves, ChessVectors visualizes the complete tactical landscape of any position:
- Attack Vectors - Red arrows showing all pieces under attack
- Defense Vectors - Green/Blue arrows showing which pieces are defended
- Hanging Pieces - Automatic detection of pieces attacked more times than they're defended
- Undefended Pieces - Highlights pieces with zero defenders, even if not currently under attack
- Pin Detection - Purple arrows showing pinned pieces and what's at risk behind them
- Skewer Detection - Same purple arrows as pins, for the mirror-image tactic: a directly-attacked piece with something less valuable exposed behind it
- Discovery Detection - Pink dotted arrows showing discovered attacks that actually win material or check the king once a blocking piece moves
- Interactive Analysis - Real-time updates as you make moves
Proprietary Components
The following core algorithms and visualizations were custom-built for ChessVectors:
AttackCalculator
Analyzes all pieces on the board to identify attack vectors. Uses chess.js move generation to find all legal captures for both sides, then visualizes these attack relationships as directional arrows on the board.
DefenseCalculator
Finds every piece that could legally recapture on a given square, then verifies each one by simulating the actual recapture and checking whether it would expose that side's king - so a defender is only counted if the recapture is genuinely safe, not just geometrically possible. Distinguishes between white and black defenders for color-coded visualization.
HangingDetector
Uses a count-based approach to identify tactically vulnerable pieces. Counts attackers and defenders for each piece, marking it as hanging when attackers outnumber defenders. Displays the ratio (e.g., "3v1" means 3 attackers vs 1 defender) to help players evaluate tactical exchanges and material threats.
PinDetector
Detects absolute pins (a piece shielding its own king) and relative pins (shielding a more valuable piece), by checking whether removing a candidate piece would newly expose the piece behind it to attack.
SkewerDetector
Shares its detection logic with PinDetector - same geometry, opposite value comparison. A skewer is a pin turned around: the directly-attacked piece is equal or higher value than what's behind it (or is the king itself, forced to move by check), so it's the front piece that's expected to move, exposing the piece behind.
DiscoveryDetector
Detects discovered attacks: a friendly piece blocking one of your own sliding pieces from an enemy target, where moving the blocker would reveal the attack. Only flags it as a real discovery if the newly-exposed target is the enemy king, hanging, or undefended - an even or losing trade isn't counted.
Dual-Side Vector Calculation
Custom approach that calculates attack and defense vectors for BOTH sides simultaneously. Uses FEN manipulation to flip the side-to-move, runs calculations for each side, then combines the results. This allows visualization of the complete tactical landscape rather than just one player's perspective.
ChessEngine Wrapper
Enhanced chess game management that extends chess.js with move history tracking, position rebuilding, and integration with the proprietary analysis components.
Technology Stack
Framework & Core
- Next.js 14 - React framework with App Router
- React 18 - UI library with modern hooks
- TypeScript - Type-safe development
- Tailwind CSS - Utility-first styling
Chess Libraries
- chess.js - Chess game logic and move validation
- react-chessboard - Interactive chess board UI component
- Stockfish 18 - World's strongest chess engine for analysis and play mode
State Management & Utilities
- React Hooks - useState, useRef, useEffect, useCallback for state
- HTML5 Canvas API - High-performance vector rendering
- clsx & tailwind-merge - Dynamic className utilities
Development Environment
- VS Code - Primary code editor on Windows 11
- Claude Code (CLI) - AI-powered development assistant
- Claude Sonnet 4.5 - AI model used for code generation, architecture decisions, and implementation
- Explore Agent - Specialized Claude agent for codebase exploration and research tasks
- Plan Mode - AI planning agent used to design implementation strategies before coding
- AI-Assisted Development - The entire application was built through iterative collaboration with Claude, including custom algorithms, responsive design patterns, and feature implementation
Key Features
Analysis Mode
Explore positions freely with Stockfish evaluation, best move suggestions, and real-time tactical analysis.
Play Mode
Play against Stockfish with adjustable difficulty (1-20) while seeing attack and defense vectors in real-time.
Famous Games
Study 95 legendary games including "The Immortal Game", "The Opera Game", and classics from Réti's "Masters of the Chessboard".
Customization
Customize board themes, piece sets, and the attack/defense vector colors, opacity, line widths, and arrowhead sizes.
Import/Export
Load positions via FEN notation or full games via PGN format. Navigate move history with keyboard shortcuts.
Responsive Design
Fully responsive with collapsible panels and board resizing, plus a Focus Mode on mobile/tablet that clears the panels away for the board alone.
Development & Testing
- Vitest - Modern unit testing framework
- Testing Library - React component testing
- ESLint - Code quality and consistency
- Prettier - Automatic code formatting
Open Source
ChessVectors is built on top of excellent open-source libraries while contributing its own proprietary algorithms for attack, defense, pin, skewer, discovery, and hanging piece detection. The vector visualization system and tactical analysis components are custom-developed to provide unique insights into chess positions.
Created by Mark Theophilis