diff --git a/docs/plans/replay.md b/docs/plans/replay.md new file mode 100644 index 0000000..0506c0b --- /dev/null +++ b/docs/plans/replay.md @@ -0,0 +1,89 @@ +# Replay: post-attempt review of a played puzzle + +Goal: after a puzzle ends (solved or failed), let the user step through the game +they just played, see the best move at each position, and — where they went +wrong — follow the optimal line to see how it should have gone. + +## Definition of done + +- On `:solved`/`:failed`, an explicit **Review** button appears alongside + "Try again". Clicking it enters read-only review mode. +- The move list shows the **full game** — the user's moves *and* the opponent's + replies — with the user's plies color-coded by grade (optimal / winning / + losing), result-aware for draw puzzles. +- Clicking any ply (or using prev/next) repositions the board to that position. +- At every reviewed position, the best move(s) for the side to move are shown. +- On a failed attempt, the losing move is highlighted with the best alternative, + and **"Play best line"** steps through the tablebase's optimal continuation. +- Review is **ephemeral**: it lives in socket `assigns` and is lost on refresh. +- Review is **read-only**: no resuming play from a replayed position. + +## Decisions (see GLOSSARY.md, docs/adr/) + +- Review is entered via an explicit button, not auto-entered on finish. +- **LiveView owns the move history**; the board is a pure FEN display driven by + the existing `set_fen` hook (our own solution now; see "Future" below). +- The played line is recorded with a per-ply tablebase snapshot, so best moves + on the played line need no re-query. Off-line "Play best line" positions fetch + on demand and degrade gracefully under rate-limit/cooldown. +- Review is ephemeral and read-only; "Try again" starts a fresh attempt. + +## Work breakdown + +### 0. Rating default (independent) +- Add `default: 1500` to `field :rating` in `lib/chesstrainer/endgames/endgame.ex` + (matches the DB migration default). The new-endgame form then auto-fills 1500. + +### 1. Record the full game during play (`EndgameLive.Play`) +- Replace `move_list` (SAN strings) with a ply list; each ply records + `{san, uci, fen_after, side, grade, tablebase_snapshot}`. +- Append the opponent's reply (currently discarded in `opponent_reply_applied` / + `start_opponent_reply`) to the same list. +- Snapshot the `%Tablebase{}` used at each position (the one already fetched for + grading / reply selection) onto its ply. + +### 2. Review state + navigation +- Add `:review` status and a current-ply index; a "Review" button transitions + `:solved`/`:failed` → review mode. +- Move list: render full game, each ply `phx-click`-able; prev/next controls and + arrow-key navigation. +- On ply selection, push that ply's FEN to the board via the existing `set_fen` + handler. + +### 3. Best-move panel +- At the reviewed position: show the best move(s) from the ply's snapshot + (reuse `best_move_text/1` logic, extended to a list). +- On the failing ply: highlight it red, show "You played X; best was Y". + +### 4. "Play best line" (optimal continuation) +- From any reviewed position, offer "Play best line": step forward through the + tablebase's best moves, fetching `Tablebase.new/1` on demand for positions off + the played line. +- On `{:cooldown, _}` / `{:error, _}`, show a graceful "tablebase unavailable + here" note and stop the line, without breaking the rest of review. + +### 5. Move-list rendering +- Full game with grade colors; draw-puzzle-aware labels ("keeps the draw" / + "throws away the draw" rather than "winning"/"losing"). + +## Future: chessground-native move list (Approach 2) + +Our current solution keeps the move history in LiveView and treats the board as +a FEN display. A later migration to the lichess-style approach would: + +- Feed chess.js the full move history and run chessground in `viewOnly` mode. +- On ply click, read `chess.history({verbose:true})[i]` and `ground.set({fen})` + client-side, removing the per-ply server round-trip. + +The move-list component itself is not part of chessground (it lives in lichess's +`ui`). **Licensing**: chessground is GPL-3.0-or-later (already a dependency, so +reusing more of it adds no new obligation). lichess's `ui` is AGPL-3.0-or-later +(network copyleft — obligations trigger merely by serving the app). So the +migration stays license-clean only if we build the move list ourselves and do +not vendor lichess `ui`. This reading is not legal advice. + +## Out of scope (deferred) + +- Persisting reviews / attempt history to the DB. +- Resuming play from a replayed position. +- Auth and per-user Glicko ratings (unchanged from MVP).