feat(react-chess): add Dockerfile, docker-compose, provider tests, docs

- Dockerfile: multi-stage Vite build → nginx serve
- docker-compose.yml: frontend + rust/go/js backends with health checks
- 90 new tests for LocalProvider, adapters, RemoteProvider, types (151 total)
- Updated README with multi-backend docs, Docker section, env config
- Updated CHANGELOG with provider system additions

Author: RumenDamyanov

.dockerignore

@@ -0,0 +1,44 @@
+# Dependency directories
+node_modules/
+
+# Build output (we COPY source and rebuild inside Docker)
+dist/
+dist-ssr/
+
+# Test & coverage
+coverage/
+*.test.ts
+*.test.tsx
+*.spec.ts
+*.spec.tsx
+tests/
+
+# Editor / OS
+.vscode/
+.idea/
+.DS_Store
+*.local
+
+# Git
+.git/
+.gitignore
+
+# Docs (not needed in image)
+*.md
+LICENSE*
+CHANGELOG*
+CONTRIBUTING*
+CODE_OF_CONDUCT*
+SECURITY*
+FUNDING*
+wiki/
+docs/
+
+# CI config
+.github/
+.prettierrc
+.prettierignore
+eslint.config.js
+jest.config.ts
+tsconfig.jest.json
+.ai/

CHANGELOG.md

@@ -9,9 +9,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- **Multi-backend provider system** — switch between local (@rumenx/chess), rust-chess, go-chess, and js-chess backends
+  - `ChessProvider` interface with unified types across all backends
+  - `LocalProvider` — in-browser engine wrapper (zero latency, offline-capable)
+  - `RemoteProvider` — HTTP-based provider with per-backend response adapters
+  - Response normalizers for rust-chess (camelCase), go-chess (snake_case), js-chess (/api/v1/)
+  - `BackendContext` — React context with health checking, localStorage persistence, env var support
+  - `useChessBackendGame` hook — backend-aware game hook with optimistic local updates
+- **Backend picker UI** in settings panel
+  - Engine selector dropdown (Local / Rust / Go / JS)
+  - Custom URL input for remote backends
+  - Live connection status indicator (checking / connected / error) with retry
+  - Capability warnings (e.g. "Go backend does not support undo")
+- **Header connection indicator** — colored dot showing backend connection state
+- **Environment variable configuration** — `VITE_CHESS_BACKEND`, `VITE_CHESS_RUST_URL`, `VITE_CHESS_GO_URL`, `VITE_CHESS_JS_URL`
+- **`.env.example`** with all configuration options documented
 - Game archival subsystem (in progress)
 - Replay mode UI (planned)
-- Comprehensive test suite (planned)
 
 ### Changed
 

Dockerfile

@@ -0,0 +1,31 @@
+# Stage 1: Build
+FROM node:22-alpine AS builder
+
+WORKDIR /app
+
+# Install dependencies first (layer caching)
+COPY package.json package-lock.json ./
+RUN npm ci --ignore-scripts
+
+# Copy source and build
+COPY index.html vite.config.ts tsconfig*.json ./
+COPY public/ public/
+COPY src/ src/
+
+RUN npm run build
+
+# Stage 2: Serve with nginx
+FROM nginx:alpine
+
+# Copy built assets
+COPY --from=builder /app/dist /usr/share/nginx/html
+
+# Custom nginx config for SPA routing
+COPY nginx.conf /etc/nginx/conf.d/default.conf
+
+EXPOSE 80
+
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s \
+    CMD wget -qO- http://localhost/ || exit 1
+
+CMD ["nginx", "-g", "daemon off;"]

README.md

@@ -5,13 +5,17 @@
 [![Dependabot](https://github.com/RumenDamyanov/react-chess/actions/workflows/dependabot/dependabot-updates/badge.svg)](https://github.com/RumenDamyanov/react-chess/actions/workflows/dependabot/dependabot-updates)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
 
-Modern, fully client-side chess application built with **React + TypeScript + Vite**, powered by the custom engine [@rumenx/chess](https://www.npmjs.com/package/@rumenx/chess).
+Modern chess application built with **React + TypeScript + Vite**, powered by the custom engine [@rumenx/chess](https://www.npmjs.com/package/@rumenx/chess).
+
+Supports **multiple backend engines** — play offline in the browser or connect to [rust-chess](https://github.com/RumenDamyanov/rust-chess), [go-chess](https://github.com/RumenDamyanov/go-chess), or [npm-chess](https://github.com/RumenDamyanov/npm-chess) REST APIs.
 
 ---
 
 ## ✨ Features
 
-- Legal move generation & game state via \`@rumenx/chess\`
+- Legal move generation & game state via `@rumenx/chess`
+- **Multi-backend support** — switch between Local (in-browser), Rust, Go, and JS engines
+- Backend picker with live connection status & health checking
 - Move history with time-travel (jump to any ply)
 - AI opponent with multiple difficulty tiers (random → depth 5 minimax w/ alpha-beta & capture ordering)
 - Hint system (on-demand best move preview)
@@ -53,21 +57,115 @@ npm run dev
 
 Then open: [http://localhost:5173](http://localhost:5173)
 
+## 🔀 Switching Backends
+
+React Chess supports **four chess engines** — you can switch between them at any time without losing your current game position.
+
+| Backend | Engine | Runs In | Default URL |
+|---------|--------|---------|-------------|
+| **Local** | `@rumenx/chess` | Browser (no server) | — |
+| **Rust** | `rumenx-chess` | REST API | `http://localhost:8082` |
+| **Go** | `go-chess` | REST API | `http://localhost:8080` |
+| **JS** | `npm-chess` | REST API | `http://localhost:8081` |
+
+### Method 1: Settings Panel (UI)
+
+1. Open the app at [http://localhost:5173](http://localhost:5173)
+2. In the left sidebar, find the **Backend Engine** section
+3. Select an engine from the **Engine** dropdown (Local, Rust, Go, or JS)
+4. For remote backends, a **URL** field appears — edit it if your server runs on a different host/port
+5. A connection indicator shows the status:
+   - ⏳ **Checking…** — health check in progress
+   - ✅ **Connected** — backend is reachable
+   - ❌ **Disconnected** — server unreachable; click **🔄 Retry**
+6. Start playing — the game resets with the new engine
+
+Your selection is persisted in `localStorage`, so it survives page reloads.
+
+### Method 2: Environment Variables
+
+Set the default backend before starting the dev server:
+
+```bash
+cp .env.example .env
+```
+
+Edit `.env`:
+
+```env
+# Options: local | rust | go | js
+VITE_CHESS_BACKEND=rust
+
+# Override default URLs (optional)
+VITE_CHESS_RUST_URL=http://localhost:8082
+VITE_CHESS_GO_URL=http://localhost:8080
+VITE_CHESS_JS_URL=http://localhost:8081
+```
+
+Then run `npm run dev` — the app opens with the chosen backend pre-selected.
+
+### Method 3: Docker Compose (all backends)
+
+Start the frontend and all three remote backends together:
+
+```bash
+docker compose up
+```
+
+| Service | URL |
+|---------|-----|
+| Frontend | [http://localhost:3001](http://localhost:3001) |
+| Rust API | [http://localhost:8082](http://localhost:8082) |
+| Go API | [http://localhost:8080](http://localhost:8080) |
+| JS API | [http://localhost:8081](http://localhost:8081) |
+
+Once running, switch freely between all four engines in the Settings panel.
+
+### Backend Capabilities
+
+Not every backend supports every feature:
+
+| Capability | Local | Rust | Go | JS |
+|------------|:-----:|:----:|:--:|:--:|
+| AI opponent | ✅ | ✅ | ✅ | ✅ |
+| Hint | ✅ | ✅ | ✅ | ✅ |
+| Undo | ✅ | ✅ | ❌ | ✅ |
+| FEN load | ✅ | ✅ | ✅ | ✅ |
+| PGN export | ✅ | ✅ | ✅ | ✅ |
+| Analysis | ❌ | ✅ | ✅ | ✅ |
+| LLM Chat | ❌ | ✅ | ✅ | ❌ |
+| WebSocket | ❌ | ✅ | ✅ | ❌ |
+
+The UI automatically warns when a feature is unavailable (e.g. "⚠️ This backend does not support undo").
+
 ## 🧩 Project Structure
 
-\`\`\`text
+```text
 src/
-  App.tsx                 # Composition + settings + clocks
+  App.tsx                    # Composition + settings + backend picker
   hooks/
-    useChessGame.ts       # Core game + clocks + history logic
-    ... (future: useGameArchive.ts)
-  services/ChessAI.ts     # AI difficulty + search
-  components/ChessBoard/  # Board + Square rendering
-  components/MoveHistory  # Move list & navigation
-  utils/                  # PGN, persistence helpers
-  styles/                 # SCSS tokens & theming
-tests/                    # Jest tests (planned)
-\`\`\`
+    useChessGame.ts          # Core game + clocks + history logic
+    useChessBackendGame.ts   # Backend-aware game hook (delegates to provider)
+  providers/
+    types.ts                 # BackendId, presets, normalised game types
+    LocalProvider.ts         # In-browser provider via @rumenx/chess
+    RemoteProvider.ts        # HTTP provider for Rust/Go/JS APIs
+    adapters.ts              # Response normalisers per backend
+    BackendContext.tsx        # React context (selection, health, persistence)
+    index.ts                 # Barrel export
+  services/
+    ChessAI.ts               # AI difficulty + minimax search
+    ChessEngine.ts           # Engine wrapper for local play
+  components/
+    ChessBoard/              # Board + Square rendering
+    MoveHistory/             # Move list & navigation
+  utils/                     # PGN, persistence, notation helpers
+  styles/                    # SCSS tokens & theming
+tests/
+  providers/                 # Provider & adapter tests
+  services/                  # ChessAI & ChessEngine tests
+  utils/                     # Notation utility tests
+```
 
 ## 🔧 Development Scripts
 
@@ -88,7 +186,7 @@ tests/                    # Jest tests (planned)
 
 Comprehensive test coverage for core functionality:
 
-- **61 passing tests** covering services and utilities
+- **151 passing tests** covering providers, services, and utilities
 - **85%+ coverage** on ChessAI service (difficulty levels, move selection, minimax)
 - **77%+ coverage** on ChessEngine wrapper (initialization, moves, game state)
 - **50%+ coverage** on chess notation utilities (SAN formatting, move chunking)
@@ -123,16 +221,22 @@ See the full [Contributing Guide](./CONTRIBUTING.md) for detailed guidelines.
 
 ## 📦 Future Enhancements
 
+- WebSocket real-time game sync (rust-chess, go-chess)
+- AI chat panel (LLM integration via rust-chess, go-chess)
 - Opening explorer / book weighting
 - Engine benchmarking panel
 - Dark theme toggle
+- Save slots (3 game slots)
+- PGN import
 - Cloud sync (optional)
 
 ## 🛠 Tech Stack
 
-- React + TypeScript + Vite
-- Custom chess engine: \`@rumenx/chess\`
+- React 19 + TypeScript 5 + Vite 7
+- Custom chess engine: `@rumenx/chess`
+- Multi-backend provider layer (Local / Rust / Go / JS)
 - SCSS modules (design tokens & utilities)
+- Docker + Docker Compose (optional)
 
 ## 🔗 Related Projects
 
@@ -141,6 +245,8 @@ Explore other libraries and tools from the same developer:
 ### NPM Packages
 
 - **[@rumenx/chess](https://github.com/RumenDamyanov/npm-chess)** - TypeScript chess engine with legal move generation ([npm](https://www.npmjs.com/package/@rumenx/chess))
+- **[rust-chess](https://github.com/RumenDamyanov/rust-chess)** - Rust chess engine + REST API ([crates.io](https://crates.io/crates/rumenx-chess))
+- **[go-chess](https://github.com/RumenDamyanov/go-chess)** - Go chess engine + REST API
 - **[@rumenx/chatbot](https://github.com/RumenDamyanov/npm-chatbot)** - AI chatbot integration library ([npm](https://www.npmjs.com/package/@rumenx/chatbot))
 - **[@rumenx/seo](https://github.com/RumenDamyanov/npm-seo)** - SEO analysis and optimization toolkit ([npm](https://www.npmjs.com/package/@rumenx/seo))
 - **[@rumenx/sitemap](https://github.com/RumenDamyanov/npm-sitemap)** - Dynamic sitemap generator ([npm](https://www.npmjs.com/package/@rumenx/sitemap))

docker-compose.yml

@@ -0,0 +1,87 @@
+# Docker Compose — react-chess with all backend engines
+#
+# Usage:
+#   docker compose up              # start all services
+#   docker compose up frontend     # start frontend only (local mode)
+#   docker compose up rust-backend # start a specific backend
+#
+# The frontend is served at http://localhost:3001
+# Switch backends from the Settings panel in the UI.
+
+services:
+  # ── Frontend ────────────────────────────────────────────
+  frontend:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    ports:
+      - "3001:80"
+    environment:
+      - VITE_CHESS_BACKEND=local
+      - VITE_CHESS_RUST_URL=http://localhost:8082
+      - VITE_CHESS_GO_URL=http://localhost:8080
+      - VITE_CHESS_JS_URL=http://localhost:8081
+    depends_on:
+      rust-backend:
+        condition: service_healthy
+        required: false
+      go-backend:
+        condition: service_healthy
+        required: false
+      js-backend:
+        condition: service_healthy
+        required: false
+    restart: unless-stopped
+
+  # ── Rust Backend (rust-chess) ───────────────────────────
+  rust-backend:
+    build:
+      context: ../rust-chess
+      dockerfile: Dockerfile
+    ports:
+      - "8082:8082"
+    environment:
+      - PORT=8082
+      - RUST_LOG=info
+    healthcheck:
+      test: ["/rust-chess", "--health-check"]
+      interval: 15s
+      timeout: 3s
+      start_period: 5s
+      retries: 3
+    restart: unless-stopped
+
+  # ── Go Backend (go-chess) ───────────────────────────────
+  go-backend:
+    build:
+      context: ../go-chess
+      dockerfile: Dockerfile
+    ports:
+      - "8080:8080"
+    environment:
+      - CHESS_HOST=0.0.0.0
+      - CHESS_PORT=8080
+    healthcheck:
+      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:8080/health"]
+      interval: 15s
+      timeout: 3s
+      start_period: 5s
+      retries: 3
+    restart: unless-stopped
+
+  # ── JS Backend (npm-chess) ─────────────────────────────
+  js-backend:
+    build:
+      context: ../npm-chess
+      dockerfile: Dockerfile
+    ports:
+      - "8081:8081"
+    environment:
+      - PORT=8081
+    healthcheck:
+      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:8081/api/v1/health"]
+      interval: 15s
+      timeout: 3s
+      start_period: 5s
+      retries: 3
+    restart: unless-stopped