chess/docs/API_REFERENCE.md

# API Reference - HTML Chess Game

## Table of Contents

1. [Core Classes](#core-classes)
2. [Piece Classes](#piece-classes)
3. [Move System](#move-system)
4. [UI Components](#ui-components)
5. [Utilities](#utilities)
6. [Events](#events)
7. [Data Structures](#data-structures)

---

## Core Classes

### ChessGame

Main game controller that orchestrates all game logic.

#### Constructor

```javascript
new ChessGame(config?: GameConfig)
```

**Parameters:**
- `config` (optional): Configuration object
  - `autoSave`: boolean - Enable automatic saving (default: true)
  - `enableTimer`: boolean - Enable move timer (default: false)
  - `timeControl`: number - Time in milliseconds per player

**Example:**
```javascript
const game = new ChessGame({
    autoSave: true,
    enableTimer: false
});
```

#### Properties

| Property | Type | Description |
|----------|------|-------------|
| `board` | Board | The game board instance |
| `currentTurn` | 'white' \| 'black' | Current player's turn |
| `gameState` | GameState | Game state manager |
| `status` | GameStatus | Current game status |
| `winner` | 'white' \| 'black' \| null | Winner if game ended |

#### Methods

##### makeMove()

Execute a chess move.

```javascript
makeMove(fromRow: number, fromCol: number, toRow: number, toCol: number): MoveResult
```

**Parameters:**
- `fromRow`: Source row (0-7)
- `fromCol`: Source column (0-7)
- `toRow`: Destination row (0-7)
- `toCol`: Destination column (0-7)

**Returns:** `MoveResult`
```javascript
{
    success: boolean,
    move?: Move,
    error?: string,
    gameStatus?: GameStatus
}
```

**Example:**
```javascript
const result = game.makeMove(6, 4, 4, 4); // e2 to e4
if (result.success) {
    console.log('Move executed:', result.move.notation);
    console.log('Game status:', result.gameStatus);
} else {
    console.error('Invalid move:', result.error);
}
```

##### getLegalMoves()

Get all legal moves for a piece.

```javascript
getLegalMoves(piece: Piece): Position[]
```

**Parameters:**
- `piece`: The piece to get moves for

**Returns:** Array of legal positions
```javascript
[
    {row: 4, col: 4},
    {row: 5, col: 4}
]
```

##### isInCheck()

Check if a player is in check.

```javascript
isInCheck(color: Color): boolean
```

**Parameters:**
- `color`: 'white' or 'black'

**Returns:** `true` if in check, `false` otherwise

##### newGame()

Start a new game.

```javascript
newGame(): void
```

Resets the board and game state to initial position.

##### undo()

Undo the last move.

```javascript
undo(): boolean
```

**Returns:** `true` if undo successful, `false` if no moves to undo

##### redo()

Redo a previously undone move.

```javascript
redo(): boolean
```

**Returns:** `true` if redo successful, `false` if no moves to redo

##### resign()

Current player resigns.

```javascript
resign(): void
```

Sets game status to ended with opponent as winner.

##### offerDraw()

Offer a draw to opponent.

```javascript
offerDraw(): void
```

##### acceptDraw()

Accept a draw offer.

```javascript
acceptDraw(): void
```

Sets game status to draw.

---

### Board

Manages the chess board state and piece positions.

#### Constructor

```javascript
new Board()
```

#### Properties

| Property | Type | Description |
|----------|------|-------------|
| `grid` | (Piece \| null)[][] | 8x8 grid of pieces |

#### Methods

##### getPiece()

Get piece at position.

```javascript
getPiece(row: number, col: number): Piece | null
```

##### setPiece()

Place piece at position.

```javascript
setPiece(row: number, col: number, piece: Piece | null): void
```

##### movePiece()

Move piece from one position to another.

```javascript
movePiece(fromRow: number, fromCol: number, toRow: number, toCol: number): Piece | null
```

**Returns:** Captured piece if any

##### clone()

Create deep copy of board.

```javascript
clone(): Board
```

**Returns:** New board instance with copied state

##### setupInitialPosition()

Set up standard chess starting position.

```javascript
setupInitialPosition(): void
```

##### clear()

Remove all pieces from board.

```javascript
clear(): void
```

##### toFEN()

Export board to FEN notation.

```javascript
toFEN(): string
```

**Returns:** FEN string representing board state

**Example:**
```javascript
const fen = board.toFEN();
// "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR"
```

##### fromFEN()

Import board from FEN notation.

```javascript
fromFEN(fen: string): void
```

**Parameters:**
- `fen`: FEN notation string

---

### GameState

Manages game state, move history, and metadata.

#### Constructor

```javascript
new GameState()
```

#### Properties

| Property | Type | Description |
|----------|------|-------------|
| `moveHistory` | Move[] | Array of all moves |
| `currentMove` | number | Current position in history |
| `capturedPieces` | CapturedPieces | Captured pieces by color |
| `status` | GameStatus | Current game status |
| `enPassantTarget` | Position \| null | Available en passant target |
| `halfMoveClock` | number | Moves since capture/pawn move |
| `fullMoveNumber` | number | Full move counter |

#### Methods

##### recordMove()

Record a move in history.

```javascript
recordMove(move: Move): void
```

##### getLastMove()

Get the most recent move.

```javascript
getLastMove(): Move | null
```

##### undo()

Undo to previous state.

```javascript
undo(): Move | null
```

**Returns:** Undone move or null

##### redo()

Redo to next state.

```javascript
redo(): Move | null
```

**Returns:** Redone move or null

##### toFEN()

Export full game state to FEN.

```javascript
toFEN(board: Board, currentTurn: Color): string
```

**Returns:** Complete FEN string

##### toPGN()

Export game to PGN notation.

```javascript
toPGN(metadata?: PGNMetadata): string
```

**Parameters:**
- `metadata` (optional): Game metadata
  - `event`: string
  - `site`: string
  - `date`: string
  - `white`: string
  - `black`: string
  - `result`: string

**Returns:** PGN formatted string

**Example:**
```javascript
const pgn = gameState.toPGN({
    event: "Casual Game",
    white: "Player 1",
    black: "Player 2",
    date: "2025.01.22"
});
```

---

## Piece Classes

### Piece (Abstract Base Class)

Base class for all chess pieces.

#### Constructor

```javascript
new Piece(color: Color, position: Position)
```

**Parameters:**
- `color`: 'white' or 'black'
- `position`: {row: number, col: number}

#### Properties

| Property | Type | Description |
|----------|------|-------------|
| `color` | 'white' \| 'black' | Piece color |
| `position` | Position | Current position |
| `type` | PieceType | Type of piece |
| `hasMoved` | boolean | Has piece moved |

#### Methods

##### getValidMoves()

Get all valid moves (without check validation).

```javascript
getValidMoves(board: Board): Position[]
```

**Returns:** Array of valid positions

##### isValidMove()

Check if move to position is valid.

```javascript
isValidMove(board: Board, toRow: number, toCol: number): boolean
```

##### clone()

Create copy of piece.

```javascript
clone(): Piece
```

##### getSymbol()

Get Unicode symbol for piece.

```javascript
getSymbol(): string
```

**Returns:** Unicode chess symbol (♔, ♕, ♖, etc.)

---

### Pawn

Implements pawn-specific movement and rules.

#### Methods

##### getValidMoves()

```javascript
getValidMoves(board: Board): Position[]
```

**Special behavior:**
- Forward 1 or 2 squares from starting position
- Diagonal captures
- En passant (handled separately)
- Promotion at last rank

**Example:**
```javascript
const pawn = new Pawn('white', {row: 6, col: 4});
const moves = pawn.getValidMoves(board);
// [{row: 5, col: 4}, {row: 4, col: 4}] if starting position
```

---

### Knight

Implements knight movement (L-shaped).

#### Methods

##### getValidMoves()

```javascript
getValidMoves(board: Board): Position[]
```

**Movement pattern:** 2 squares in one direction, 1 square perpendicular

---

### Bishop

Implements bishop movement (diagonals).

#### Methods

##### getValidMoves()

```javascript
getValidMoves(board: Board): Position[]
```

**Movement pattern:** Any number of squares diagonally

---

### Rook

Implements rook movement (straight lines).

#### Methods

##### getValidMoves()

```javascript
getValidMoves(board: Board): Position[]
```

**Movement pattern:** Any number of squares horizontally or vertically

---

### Queen

Implements queen movement (rook + bishop).

#### Methods

##### getValidMoves()

```javascript
getValidMoves(board: Board): Position[]
```

**Movement pattern:** Combination of rook and bishop

---

### King

Implements king movement and castling.

#### Methods

##### getValidMoves()

```javascript
getValidMoves(board: Board): Position[]
```

**Movement pattern:** One square in any direction

##### canCastle()

Check if castling is possible.

```javascript
canCastle(board: Board, side: 'kingside' | 'queenside'): boolean
```

---

## Move System

### MoveValidator

Static methods for move validation.

#### Methods

##### isMoveLegal()

Validate if move is legal (including check).

```javascript
static isMoveLegal(
    board: Board,
    piece: Piece,
    toRow: number,
    toCol: number,
    gameState: GameState
): boolean
```

##### isKingInCheck()

Check if king is under attack.

```javascript
static isKingInCheck(board: Board, color: Color): boolean
```

##### isCheckmate()

Check if position is checkmate.

```javascript
static isCheckmate(board: Board, color: Color): boolean
```

##### isStalemate()

Check if position is stalemate.

```javascript
static isStalemate(board: Board, color: Color): boolean
```

##### hasAnyLegalMove()

Check if player has any legal moves.

```javascript
static hasAnyLegalMove(board: Board, color: Color): boolean
```

---

### SpecialMoves

Handles special chess moves.

#### Methods

##### canCastle()

Check if castling is legal.

```javascript
static canCastle(
    board: Board,
    king: King,
    rook: Rook,
    side: 'kingside' | 'queenside'
): boolean
```

##### executeCastle()

Execute castling move.

```javascript
static executeCastle(
    board: Board,
    king: King,
    rook: Rook,
    side: 'kingside' | 'queenside'
): void
```

##### canEnPassant()

Check if en passant is legal.

```javascript
static canEnPassant(
    board: Board,
    pawn: Pawn,
    targetCol: number,
    gameState: GameState
): boolean
```

##### executeEnPassant()

Execute en passant capture.

```javascript
static executeEnPassant(
    board: Board,
    pawn: Pawn,
    targetRow: number,
    targetCol: number
): Piece
```

**Returns:** Captured pawn

##### canPromote()

Check if pawn can be promoted.

```javascript
static canPromote(pawn: Pawn): boolean
```

##### executePiece promotion()

Promote pawn to another piece.

```javascript
static promote(
    board: Board,
    pawn: Pawn,
    pieceType: 'queen' | 'rook' | 'bishop' | 'knight'
): Piece
```

**Returns:** New promoted piece

---

## UI Components

### BoardRenderer

Renders the chess board to DOM.

#### Constructor

```javascript
new BoardRenderer(boardElement: HTMLElement, config?: RendererConfig)
```

**Parameters:**
- `boardElement`: DOM element to render board into
- `config` (optional):
  - `showCoordinates`: boolean - Show rank/file labels
  - `pieceStyle`: 'symbols' | 'images' - Piece rendering style
  - `highlightLastMove`: boolean - Highlight last move

#### Methods

##### renderBoard()

Render complete board state.

```javascript
renderBoard(board: Board, gameState: GameState): void
```

##### highlightMoves()

Highlight legal moves for a piece.

```javascript
highlightMoves(moves: Position[]): void
```

##### clearHighlights()

Remove all move highlights.

```javascript
clearHighlights(): void
```

##### selectSquare()

Select a square.

```javascript
selectSquare(row: number, col: number): void
```

##### deselectSquare()

Deselect current square.

```javascript
deselectSquare(): void
```

##### updateSquare()

Update a single square.

```javascript
updateSquare(row: number, col: number, piece: Piece | null): void
```

---

### DragDropHandler

Handles drag-and-drop interactions.

#### Constructor

```javascript
new DragDropHandler(game: ChessGame, renderer: BoardRenderer)
```

#### Methods

##### enable()

Enable drag-and-drop.

```javascript
enable(): void
```

##### disable()

Disable drag-and-drop.

```javascript
disable(): void
```

#### Events

Emits custom events on board element:

- `piece-drag-start`: Piece drag started
- `piece-drag-over`: Piece dragged over square
- `piece-drop`: Piece dropped
- `piece-drag-end`: Drag ended

---

### UIController

Manages all UI state and interactions.

#### Constructor

```javascript
new UIController(game: ChessGame)
```

#### Methods

##### init()

Initialize UI components.

```javascript
init(): void
```

##### updateGameStatus()

Update game status display.

```javascript
updateGameStatus(status: GameStatus, message?: string): void
```

##### showPromotionDialog()

Show pawn promotion piece selection.

```javascript
showPromotionDialog(callback: (pieceType: PieceType) => void): void
```

##### updateMoveHistory()

Update move history display.

```javascript
updateMoveHistory(moves: Move[]): void
```

##### updateCapturedPieces()

Update captured pieces display.

```javascript
updateCapturedPieces(captured: CapturedPieces): void
```

---

## Utilities

### Notation

Chess notation utilities.

#### Methods

##### positionToAlgebraic()

Convert position to algebraic notation.

```javascript
static positionToAlgebraic(row: number, col: number): string
```

**Example:**
```javascript
positionToAlgebraic(7, 4); // "e1"
positionToAlgebraic(0, 0); // "a8"
```

##### algebraicToPosition()

Convert algebraic notation to position.

```javascript
static algebraicToPosition(notation: string): Position
```

**Example:**
```javascript
algebraicToPosition("e4"); // {row: 4, col: 4}
```

##### moveToNotation()

Convert move to standard notation.

```javascript
static moveToNotation(move: Move, board: Board): string
```

**Example:**
```javascript
moveToNotation(move, board); // "Nf3", "Qxe5+", "O-O", etc.
```

---

### Storage

LocalStorage wrapper for game persistence.

#### Methods

##### save()

Save game state.

```javascript
static save(game: ChessGame, slotName: string = 'auto'): void
```

##### load()

Load game state.

```javascript
static load(slotName: string = 'auto'): SavedGame | null
```

**Returns:**
```javascript
{
    fen: string,
    pgn: string,
    timestamp: number
}
```

##### list()

List all saved games.

```javascript
static list(): string[]
```

**Returns:** Array of save slot names

##### delete()

Delete saved game.

```javascript
static delete(slotName: string): void
```

---

## Events

### Game Events

The ChessGame instance emits events via EventTarget interface.

#### Available Events

##### move

Fired when a move is made.

```javascript
game.addEventListener('move', (event) => {
    console.log('Move:', event.detail.move);
    console.log('Result:', event.detail.result);
});
```

**Event Detail:**
```javascript
{
    move: Move,
    result: MoveResult
}
```

##### check

Fired when a king is in check.

```javascript
game.addEventListener('check', (event) => {
    console.log('King in check:', event.detail.color);
});
```

##### checkmate

Fired when checkmate occurs.

```javascript
game.addEventListener('checkmate', (event) => {
    console.log('Winner:', event.detail.winner);
});
```

##### stalemate

Fired when stalemate occurs.

```javascript
game.addEventListener('stalemate', () => {
    console.log('Game ended in stalemate');
});
```

##### promotion

Fired when pawn promotion is available.

```javascript
game.addEventListener('promotion', (event) => {
    // Show promotion dialog
    showPromotionDialog(event.detail.pawn);
});
```

---

## Data Structures

### Types

```javascript
type Color = 'white' | 'black';

type PieceType = 'pawn' | 'knight' | 'bishop' | 'rook' | 'queen' | 'king';

type GameStatus = 'active' | 'check' | 'checkmate' | 'stalemate' | 'draw' | 'resigned';

interface Position {
    row: number; // 0-7
    col: number; // 0-7
}

interface Move {
    from: Position;
    to: Position;
    piece: Piece;
    captured?: Piece;
    notation: string;
    special?: 'castle-kingside' | 'castle-queenside' | 'en-passant' | 'promotion';
    promotedTo?: PieceType;
    timestamp: number;
}

interface MoveResult {
    success: boolean;
    move?: Move;
    error?: string;
    gameStatus?: GameStatus;
}

interface CapturedPieces {
    white: Piece[];
    black: Piece[];
}

interface GameConfig {
    autoSave?: boolean;
    enableTimer?: boolean;
    timeControl?: number;
}

interface RendererConfig {
    showCoordinates?: boolean;
    pieceStyle?: 'symbols' | 'images';
    highlightLastMove?: boolean;
}

interface PGNMetadata {
    event?: string;
    site?: string;
    date?: string;
    white?: string;
    black?: string;
    result?: string;
}

interface SavedGame {
    fen: string;
    pgn: string;
    timestamp: number;
}
```

---

## Usage Examples

### Basic Game Setup

```javascript
import { ChessGame } from './js/game/ChessGame.js';
import { UIController } from './js/ui/UIController.js';

// Create game instance
const game = new ChessGame({
    autoSave: true
});

// Initialize UI
const ui = new UIController(game);
ui.init();

// Listen for game events
game.addEventListener('move', (e) => {
    console.log('Move made:', e.detail.move.notation);
});

game.addEventListener('checkmate', (e) => {
    alert(`Checkmate! ${e.detail.winner} wins!`);
});
```

### Making Moves Programmatically

```javascript
// Make a move
const result = game.makeMove(6, 4, 4, 4); // e2 to e4

if (result.success) {
    console.log('Move successful');
    if (result.gameStatus === 'check') {
        console.log('Check!');
    }
} else {
    console.error('Invalid move:', result.error);
}
```

### Save and Load

```javascript
// Save game
GameStorage.save(game.gameState, game.board);

// Load game
const saved = GameStorage.load();
if (saved) {
    game.gameState.fromFEN(saved.fen);
}
```

### Custom Event Handling

```javascript
// Handle piece promotion
game.addEventListener('promotion', (event) => {
    const pawn = event.detail.pawn;

    // Show UI dialog
    ui.showPromotionDialog((pieceType) => {
        SpecialMoves.promote(game.board, pawn, pieceType);
    });
});
```

---

## Error Handling

All methods that can fail return result objects or throw descriptive errors:

```javascript
try {
    const result = game.makeMove(6, 4, 4, 4);
    if (!result.success) {
        console.error('Move failed:', result.error);
        // Possible errors:
        // - "No piece at source position"
        // - "Not your turn"
        // - "Invalid move for this piece"
        // - "Move would leave king in check"
    }
} catch (error) {
    console.error('Unexpected error:', error);
}
```

---

## Performance Considerations

- **Move Validation**: Cached when possible, invalidated on board changes
- **Board Cloning**: Deep copy only when necessary (undo/check simulation)
- **DOM Updates**: Batched and debounced to minimize reflows
- **Event Handling**: Use event delegation for board squares

---

## Browser Compatibility

Minimum requirements:
- ES6+ support
- Drag and Drop API
- LocalStorage API
- CSS Grid

Supported browsers:
- Chrome 60+
- Firefox 54+
- Safari 10.1+
- Edge 79+

---

**For implementation examples, see [IMPLEMENTATION_GUIDE.md](IMPLEMENTATION_GUIDE.md)**