new: usr: add initialization bonus points' system to the gameplay #5

docs/game-mechanics/BONUS_POINTS_SYSTEM.md

@@ -0,0 +1,133 @@
+# Mine-Seeker Bonus Points System
+
+## Overview
+The Mine-Seeker game includes a bonus points system that rewards skilled play. Bonus points are tracked separately from the main score and displayed in the "Bonus Statistics" dialog.
+
+## Bonus Point Types
+
+### 1. Blind Hit (+2 points)
+**When**: Click a mine with no revealed numbered neighbors around it.
+
+**Example**: Mine surrounded by unrevealed cells = +2 points
+
+---
+
+### 2. Chain Combo
+**When**: Click consecutive mines without clicking any safe cell in between.
+
+**Tracked as**:
+- `chainCurrent`: Current streak (resets when you click a safe cell)
+- `chainBest`: Longest streak achieved
+
+**Example**: Mine → Mine → Mine = chainBest becomes 3
+
+---
+
+### 3. Edge Mine (+1 point)
+**When**: Click a mine on the board boundary (row 0, row 15, col 0, or col 15).
+
+**Example**: Click a mine on the edge = +1 point
+
+---
+
+### 4. Endgame Mine (+3 points)
+**When**: Click a mine when 10 or fewer mines remain on the board.
+
+**Calculation**: `51 total mines - (red_points + blue_points) = mines_remaining`
+
+**Example**: When 8 mines remain, click one = +3 points
+
+---
+
+### 5. Safe Cell Bonus (+0.5 points per cell)
+**When**: Click a safe cell and reveal 2 or more cells.
+
+**Important**: Minimum 2 cells required. Single cell reveals = 0 points.
+
+**Examples**:
+- Reveal 1 safe cell = 0 points
+- Reveal 2 safe cells = 1.0 points
+- Reveal 11 safe cells = 5.5 points
+
+---
+
+### 6. Biggest Reveal (Tracking stat)
+**What**: Tracks the largest number of safe cells revealed in one click.
+
+**Example**: Largest reveal in a game = 15 cells shown in stats
+
+---
+
+## Bonus Statistics Display
+
+### Dialog Shows
+- Both players' bonus statistics side-by-side
+- Each stat with label, description, and value
+- Total bonus points per player
+
+### Player Name Rules
+- `anon_*` usernames → displays as "Anonymous"
+- Names longer than 10 chars → truncated to 7 chars + "..." (example: `VeryLongName` → `VeryLon...`)
+
+---
+
+## Tracked Statistics
+
+```javascript
+{
+  blindHits: 0,      // Blind hit mines clicked
+  chainBest: 0,      // Longest mine streak
+  chainCurrent: 0,   // Current active streak
+  lastMineHits: 0,   // Endgame mines clicked
+  edgeMines: 0,      // Edge mine clicks
+  biggestReveal: 0   // Largest safe cell reveal
+}
+```
+
+---
+
+## Database
+- `red_bonus_points` (FLOAT) — Red player's total bonus points
+- `blue_bonus_points` (FLOAT) — Blue player's total bonus points
+- `red_bonus_stats` (JSON) — Red player's tracked stats
+- `blue_bonus_stats` (JSON) — Blue player's tracked stats
+
+---
+
+## 📋 Documentation Maintenance
+
+**IMPORTANT**: This documentation must be updated whenever:
+- New bonus types are added
+- Point values change
+- Bonus calculation logic changes
+- New stats are tracked
+- Bonus display rules change
+
+**Update these files**:
+1. This file (`BONUS_POINTS_SYSTEM.md`) — Update descriptions and examples
+2. Code comments in `/src/Util/TopicManager.php` — Explain calculation logic
+3. `/docs/README.md` — Update Quick Reference table if values change
+
+**Keep documentation**:
+- ✅ Simple and clear
+- ✅ With real code examples
+- ✅ Synchronized with actual code behavior
+- ✅ Updated before/after feature changes
+
+---
+
+## Implementation Files
+- Backend: `/src/Util/TopicManager.php` — Bonus calculation logic
+- Frontend: `/assets/js/mine-seeker/contexts/GameProvider.jsx` — State sync
+- UI: `/assets/js/mine-seeker/components/BonusStatsDialog.jsx` — Display dialog
+- Constants: `/assets/js/mine-seeker/utils/constants.jsx` — Labels and defaults
+
+---
+
+## Quick Checklist for Changes
+- [ ] Code changes implemented
+- [ ] This documentation updated
+- [ ] `/docs/README.md` Quick Reference table updated
+- [ ] Code comments added/updated
+- [ ] Examples updated to match new behavior
+