EPIC: Puzzle Mode: server integration, player guidance tooltips, and test coverage

[jasonappah]

Goal
Deliver a complete first iteration of Puzzle Mode that players can use end‑to‑end, with clear on‑board guidance and reliable behavior validated by tests.

Why

• Provide a guided tactical-training experience that works consistently across simulator and hardware
• Make puzzles understandable (“who moves?” and “what’s the objective?”)
• Increase confidence in puzzle behavior with unit tests

Scope

1. Server-side puzzle-game integration that runs in simulator
2. Puzzle UI tooltips that communicate side-to-move and objective (e.g., “White to mate in 2”)
3. Unit tests covering puzzle parsing/flow and critical logic

Out of Scope

• New puzzle generation pipeline
• Full visual redesign of the puzzle board

Acceptance

• Simulator run shows a working puzzle-game flow (load → make best move checking → complete)
• UI always shows side-to-move and the puzzle objective sourced from puzzle metadata
• Unit tests cover parsing/validation and happy-path + key error paths