web/SETUP_GUIDE.md

Chess UI Setup Guide

This guide will help you set up and run the Chess UI web application.

Prerequisites

• Node.js (v14 or later)
• npm (v6 or later)
• Python with the chess engine backend running

Setup Steps

1. Install Dependencies

Navigate to the web UI directory and install the required dependencies:

cd frontend/web
npm install

2. Copy Chess Assets

The UI requires chess piece and board images. Copy them from the assets directory:

# Create the necessary directories if they don't exist
mkdir -p public/assets/pieces
mkdir -p public/assets/boards/brown
mkdir -p public/assets/boards/grey
mkdir -p public/assets/sounds

# Copy the assets
cp ../../frontend/assets/pieces/*.png public/assets/pieces/
cp ../../frontend/assets/boards/brown/*.png public/assets/boards/brown/
cp ../../frontend/assets/boards/grey/*.png public/assets/boards/grey/

3. Add Sound Files (Optional)

For a better experience, add sound effects to the public/assets/sounds directory:

• move.mp3 - Sound for regular piece movement
• capture.mp3 - Sound for capturing a piece
• check.mp3 - Sound for when a king is in check
• castle.mp3 - Sound for castling
• promote.mp3 - Sound for pawn promotion
• game-start.mp3 - Sound for starting a new game
• game-end.mp3 - Sound for game ending

4. Configure Backend URL

The UI is configured to connect to the backend at http://localhost:8000. If your backend is running on a different URL, update the vite.config.ts file:

server: {
  proxy: {
    '/api': {
      target: 'http://your-backend-url:port',
      changeOrigin: true,
      rewrite: (path) => path.replace(/^\/api/, '')
    }
  }
}

5. Start the Development Server

Run the development server:

npm run dev

The UI will be available at http://localhost:5173 (or another port if 5173 is in use).

6. Build for Production

To create a production build:

npm run build

The build output will be in the dist directory, which you can serve using any static file server.

Troubleshooting

TypeScript Errors

If you encounter TypeScript errors related to React:

1. Run the fix-dependencies script:

./fix-dependencies.bat

2. Or manually reinstall React dependencies:

npm uninstall react react-dom @types/react @types/react-dom
npm install --save react react-dom
npm install --save-dev @types/react @types/react-dom

Backend Connection Issues

If the UI can't connect to the backend:

1. Make sure the backend server is running
2. Check that the proxy configuration in vite.config.ts points to the correct URL
3. Look for CORS errors in the browser console and update the backend to allow requests from the UI's origin

Features

• Interactive chess board with piece movement
• Visual indicators for legal moves (green dots)
• Hint system with highlighted squares
• Game controls (new game, undo, resign)
• Position analysis display
• Move history tracking
• Captured pieces display
• Chess timer
• Sound effects for moves and captures
• Multiple board themes (brown and grey)