From b17f346b25177aeb95bab2432f7543de52af726d Mon Sep 17 00:00:00 2001 From: Owen Rees Date: Fri, 6 Nov 2026 15:31:11 +0100 Subject: [PATCH] Show tablebase moves during review (#65) (#102) * engine 8+ tablebase adr * Show tablebase moves during review (#65) - group reviewed moves by winning/drawn/losing and make each row playable - move review navigation under the board with start/end jumps - give review a full-height scrollable tablebase pane --- docs/adr/0011-engine-corridor-endgames.md | 2 +- .../components/play_components.ex | 358 ++++++++++++------ .../live/endgame_live/guest_train.ex | 6 + .../live/endgame_live/play.ex | 6 + .../live/endgame_live/play_core.ex | 55 ++- .../live/endgame_live/train.ex | 6 + .../live/endgame_live/play_test.exs | 102 ++++- 7 files changed, 382 insertions(+), 153 deletions(-) diff --git a/docs/adr/0011-engine-corridor-endgames.md b/docs/adr/0011-engine-corridor-endgames.md index ba750cb..8d13f03 100644 --- a/docs/adr/0011-engine-corridor-endgames.md +++ b/docs/adr/0011-engine-corridor-endgames.md @@ -1,6 +1,6 @@ # Eight-or-more-piece endgames are trained from engine-sourced corridors that hand off to the tablebase at seven -_Status: proposed. Extends ADR-0005: the ≤7-piece source split stands; this adds a source for 8+._ +_Status: accepted. Extends ADR-0005: the ≤7-piece source split stands; this adds a source for 8+._ Syzygy stops at seven pieces and there is no tablebase for eight or more. To train such endgames without pretending to a completeness they lack, each 8+ diff --git a/lib/chesstrainer_web/components/play_components.ex b/lib/chesstrainer_web/components/play_components.ex index 4a2f694..ae995ee 100644 --- a/lib/chesstrainer_web/components/play_components.ex +++ b/lib/chesstrainer_web/components/play_components.ex @@ -28,123 +28,62 @@ defmodule ChesstrainerWeb.PlayComponents do def play_surface(assigns) do ~H"""
-
-
- -
-
-

- {turn_label(@status, @awaiting_reply)} - You play {colour_name(@endgame.color)} -

+
+
-
- <%= cond do %> - <% @status == :loading -> %> -

Loading tablebase…

- <% @status == :blocked -> %> -

Tablebase unavailable

-

{@blocked_reason}

- <% @status == :solved -> %> -

- {if @endgame.result == :draw, do: "Draw held!", else: "Solved!"} -

- <% @status == :failed -> %> -

Failed

-

- {if @endgame.result == :draw, - do: "That move loses the draw.", - else: "That move throws away the win."} -

- <%= if @best_move && @plies != [] do %> -

- You played {List.last(@plies).san}; best was: {@best_move} -

- <% end %> - <% @awaiting_reply -> %> -

Opponent is replying…

- <% @last_grade == :optimal -> %> -

Optimal move

- <% @last_grade == :winning -> %> -

- {if @endgame.result == :draw, - do: "Keeps the draw — but not the sharpest", - else: "Winning — but not the sharpest"} -

- <% @last_grade == :losing -> %> -

- {if @endgame.result == :draw, - do: "Losing move — this loses the draw", - else: "Losing move — this throws away the win"} -

- <% @last_grade == :unknown -> %> -

Could not grade that move

- <% true -> %> -

Make a move to have it graded.

- <% end %> -

- Puzzle rating: {round(@endgame.rating)} -

-
- -
- <%= cond do %> - <% @review_blocked -> %> -

Best move unavailable here

-

{@review_blocked}

- <% @review_tablebase -> %> -

Best move:

-

{PlayCore.best_move_text(@review_tablebase) || "—"}

- <%= if played_ply = played_ply_at(@line, @review_index) do %> -

Played: {played_ply.san}

- <% end %> - <% true -> %> -

No best move.

- <% end %> -
- -
- <% plies = display_plies(@reviewing, @line, @plies) %> -

Moves:

-
- <%= if plies == [] do %> -

No Moves

- <% else %> - <%= for {[white_ply, black_ply], move_no} <- move_rows(plies, @endgame.color) do %> -
- {move_no}. - <%= if white_ply do %> - <.ply - ply={white_ply} - reviewing={@reviewing} - review_index={@review_index} - result={@endgame.result} - /> - <% else %> - ... - <% end %> - <%= if black_ply do %> - <.ply - ply={black_ply} - reviewing={@reviewing} - review_index={@review_index} - result={@endgame.result} - /> - <% end %> -
- <% end %> - <% end %> -
+
+ <.button + id="review-start" + phx-click="review_start" + disabled={@review_index <= 0} + title="Back to start" + > + {"<<"} + + <.button + id="review-prev" + phx-click="review_prev" + disabled={@review_index <= 0} + title="Previous position" + > + ← + + <.button + id="review-next" + phx-click="review_next" + disabled={@review_index >= length(@line)} + title="Next position" + > + → + + <.button + id="review-end" + phx-click="review_end" + disabled={@review_index >= length(@line)} + title="Go to end" + > + {">>"} +
+ <.button + :if={(@reviewing and @review_tablebase) && PlayCore.best_move_text(@review_tablebase)} + phx-click="play_best_line" + disabled={@awaiting_best_line} + > + Play best line + + <.button :if={@reviewing and @line != @plies} phx-click="back_to_game"> + Back to game + <.button :if={@status in [:solved, :failed] and not @reviewing} phx-click="review" @@ -164,24 +103,193 @@ defmodule ChesstrainerWeb.PlayComponents do Next puzzle
+
-
- <.button phx-click="review_prev" disabled={@review_index <= 0}>← - <.button phx-click="review_next" disabled={@review_index >= length(@line)}>→ - <.button - :if={@review_tablebase && PlayCore.best_move_text(@review_tablebase)} - phx-click="play_best_line" - disabled={@awaiting_best_line} - > - Play best line - - <.button :if={@line != @plies} phx-click="back_to_game">Back to game +
+
+ <%= if @reviewing do %> +
+ <%= cond do %> + <% @review_blocked -> %> +

Best move unavailable here

+

{@review_blocked}

+ <% @review_tablebase -> %> +

Best move:

+

{PlayCore.best_move_text(@review_tablebase) || "—"}

+ <%= if played_ply = played_ply_at(@line, @review_index) do %> +

Played: {played_ply.san}

+ <% end %> + <.tablebase_options tablebase={@review_tablebase} /> + <% true -> %> +

No best move.

+ <% end %> +
+ <% else %> +
+

+ {turn_label(@status, @awaiting_reply)} + + You play {colour_name(@endgame.color)} + +

+
+ +
+ <%= cond do %> + <% @status == :loading -> %> +

Loading tablebase…

+ <% @status == :blocked -> %> +

Tablebase unavailable

+

{@blocked_reason}

+ <% @status == :solved -> %> +

+ {if @endgame.result == :draw, do: "Draw held!", else: "Solved!"} +

+ <% @status == :failed -> %> +

Failed

+

+ {if @endgame.result == :draw, + do: "That move loses the draw.", + else: "That move throws away the win."} +

+ <%= if @best_move && @plies != [] do %> +

+ You played {List.last(@plies).san}; best was: {@best_move} +

+ <% end %> + <% @awaiting_reply -> %> +

Opponent is replying…

+ <% @last_grade == :optimal -> %> +

Optimal move

+ <% @last_grade == :winning -> %> +

+ {if @endgame.result == :draw, + do: "Keeps the draw — but not the sharpest", + else: "Winning — but not the sharpest"} +

+ <% @last_grade == :losing -> %> +

+ {if @endgame.result == :draw, + do: "Losing move — this loses the draw", + else: "Losing move — this throws away the win"} +

+ <% @last_grade == :unknown -> %> +

Could not grade that move

+ <% true -> %> +

Make a move to have it graded.

+ <% end %> +

+ Puzzle rating: {round(@endgame.rating)} +

+
+ +
+ <% plies = display_plies(@reviewing, @line, @plies) %> +

Moves:

+
+ <%= if plies == [] do %> +

No Moves

+ <% else %> + <%= for {[white_ply, black_ply], move_no} <- move_rows(plies, @endgame.color) do %> +
+ {move_no}. + <%= if white_ply do %> + <.ply + ply={white_ply} + reviewing={@reviewing} + review_index={@review_index} + result={@endgame.result} + /> + <% else %> + ... + <% end %> + <%= if black_ply do %> + <.ply + ply={black_ply} + reviewing={@reviewing} + review_index={@review_index} + result={@endgame.result} + /> + <% end %> +
+ <% end %> + <% end %> +
+
+ <% end %>
""" end + attr :tablebase, :any, required: true + + # The reviewed position's moves grouped like lichess's tablebase explorer: + # each heading is the outcome for the side to move, one table per outcome. + defp tablebase_options(assigns) do + assigns = assign(assigns, :groups, tablebase_groups(assigns.tablebase)) + + ~H""" +
+

Tablebase

+
+

{label}

+ + + + + + + +
{move.san} + {dtz_text(move)} +
+
+
+ """ + end + + defp tablebase_groups(%{moves: moves}) when is_list(moves) do + [ + {"Winning", "text-success-text", :win}, + {"Drawn", "text-muted", :draw}, + {"Losing", "text-error", :loss}, + {"Unknown", "text-muted", :unknown} + ] + |> Enum.flat_map(fn {label, class, outcome} -> + case Enum.filter(moves, &(mover_outcome(&1.category) == outcome)) do + [] -> [] + moves -> [{label, class, moves}] + end + end) + end + + defp tablebase_groups(_tablebase), do: [] + + # A move's category is the outcome for the side to move *after* the move, so + # the mover's outcome is its flip. + defp mover_outcome(:loss), do: :win + defp mover_outcome(:win), do: :loss + defp mover_outcome(:draw), do: :draw + defp mover_outcome(_), do: :unknown + + defp dtz_text(%{dtz: nil}), do: "" + + defp dtz_text(%{dtz: dtz}), do: "DTZ #{abs(dtz)}" + attr :ply, :map, required: true attr :reviewing, :boolean, required: true attr :review_index, :integer, required: true @@ -242,15 +350,17 @@ defmodule ChesstrainerWeb.PlayComponents do defp played_ply_at(line, review_index) do case Enum.at(line, review_index) do - %{best_line: true} -> nil + %{analysis: true} -> nil ply -> ply end end defp ply_class(%{best_line: true}), do: "text-info italic" + defp ply_class(%{analysis: true}), do: "text-info" defp ply_class(ply), do: grade_class(ply.grade) defp ply_title(%{best_line: true}, _result), do: "Best line" + defp ply_title(%{analysis: true}, _result), do: "Tablebase move" defp ply_title(ply, result), do: grade_label(ply.grade, result) defp grade_class(:optimal), do: "text-success-text" diff --git a/lib/chesstrainer_web/live/endgame_live/guest_train.ex b/lib/chesstrainer_web/live/endgame_live/guest_train.ex index 38d46a2..27fe0ea 100644 --- a/lib/chesstrainer_web/live/endgame_live/guest_train.ex +++ b/lib/chesstrainer_web/live/endgame_live/guest_train.ex @@ -167,6 +167,12 @@ defmodule ChesstrainerWeb.EndgameLive.GuestTrain do def handle_event("review_step", %{"index" => index}, socket), do: PlayCore.review_step(socket, index) + def handle_event("review_start", _params, socket), do: PlayCore.review_start(socket) + + def handle_event("review_end", _params, socket), do: PlayCore.review_end(socket) + + def handle_event("review_move", params, socket), do: PlayCore.review_move(socket, params) + def handle_event("play_best_line", _params, socket), do: PlayCore.play_best_line(socket) def handle_event("best_line_move_applied", params, socket), diff --git a/lib/chesstrainer_web/live/endgame_live/play.ex b/lib/chesstrainer_web/live/endgame_live/play.ex index af2b3b4..7571e88 100644 --- a/lib/chesstrainer_web/live/endgame_live/play.ex +++ b/lib/chesstrainer_web/live/endgame_live/play.ex @@ -85,6 +85,12 @@ defmodule ChesstrainerWeb.EndgameLive.Play do def handle_event("review_step", %{"index" => index}, socket), do: PlayCore.review_step(socket, index) + def handle_event("review_start", _params, socket), do: PlayCore.review_start(socket) + + def handle_event("review_end", _params, socket), do: PlayCore.review_end(socket) + + def handle_event("review_move", params, socket), do: PlayCore.review_move(socket, params) + def handle_event("play_best_line", _params, socket), do: PlayCore.play_best_line(socket) def handle_event("best_line_move_applied", params, socket), diff --git a/lib/chesstrainer_web/live/endgame_live/play_core.ex b/lib/chesstrainer_web/live/endgame_live/play_core.ex index 7ae5732..00041d5 100644 --- a/lib/chesstrainer_web/live/endgame_live/play_core.ex +++ b/lib/chesstrainer_web/live/endgame_live/play_core.ex @@ -46,7 +46,7 @@ defmodule ChesstrainerWeb.EndgameLive.PlayCore do |> assign(:review_tablebase, nil) |> assign(:review_blocked, nil) |> assign(:awaiting_best_line, false) - |> assign(:pending_best_move, nil) + |> assign(:pending_move, nil) |> assign(:last_san, "None yet") |> assign(:last_from_to, "None yet") |> assign(:last_grade, nil) @@ -135,7 +135,7 @@ defmodule ChesstrainerWeb.EndgameLive.PlayCore do |> assign(:review_tablebase, nil) |> assign(:review_blocked, nil) |> assign(:awaiting_best_line, false) - |> assign(:pending_best_move, nil) + |> assign(:pending_move, nil) |> assign(:last_san, "None yet") |> assign(:last_from_to, "None yet") |> assign(:last_grade, nil) @@ -162,6 +162,10 @@ defmodule ChesstrainerWeb.EndgameLive.PlayCore do def review_next(socket), do: step_review(socket, 1) + def review_start(socket), do: review_step(socket, 0) + + def review_end(socket), do: review_step(socket, length(socket.assigns.line)) + def review_step(socket, index) do if socket.assigns.reviewing do last = length(socket.assigns.line) @@ -177,21 +181,41 @@ defmodule ChesstrainerWeb.EndgameLive.PlayCore do with true <- socket.assigns.reviewing, %Tablebase{} = tablebase <- socket.assigns.review_tablebase, %Tablebase.Move{} = move <- pick_best_move(tablebase) do - # Branch the review line at the current position, then play one best move. - {:noreply, - socket - |> assign(:line, Enum.take(socket.assigns.line, socket.assigns.review_index)) - |> assign(:awaiting_best_line, true) - |> assign(:pending_best_move, move) - |> push_event("best_line_move", reply_payload(move))} + play_review_move(socket, move, true) else _ -> {:noreply, socket} end end + @doc """ + Plays one tablebase move from the reviewed position, branching the line. + + The move comes from a `phx-value-uci` on the tablebase table. + """ + def review_move(socket, %{"uci" => uci}) do + with true <- socket.assigns.reviewing, + %Tablebase{} = tablebase <- socket.assigns.review_tablebase, + %Tablebase.Move{} = move <- find_move_by_uci(tablebase, uci) do + play_review_move(socket, move, false) + else + _ -> {:noreply, socket} + end + end + + # Branch the review line at the current position, then ask the board to play + # the move; `best_line_move_applied/2` appends it once chess.js confirms it. + defp play_review_move(socket, move, best_line?) do + {:noreply, + socket + |> assign(:line, Enum.take(socket.assigns.line, socket.assigns.review_index)) + |> assign(:awaiting_best_line, true) + |> assign(:pending_move, %{move: move, best_line: best_line?}) + |> push_event("best_line_move", reply_payload(move))} + end + def best_line_move_applied(socket, %{"fen" => fen}) do if socket.assigns.awaiting_best_line do - move = socket.assigns.pending_best_move + %{move: move, best_line: best_line?} = socket.assigns.pending_move line = socket.assigns.line ++ @@ -201,7 +225,8 @@ defmodule ChesstrainerWeb.EndgameLive.PlayCore do san: move.san, fen_after: fen, grade: nil, - best_line: true + analysis: true, + best_line: best_line? } ] @@ -209,7 +234,7 @@ defmodule ChesstrainerWeb.EndgameLive.PlayCore do socket |> assign(:line, line) |> assign(:awaiting_best_line, false) - |> assign(:pending_best_move, nil) + |> assign(:pending_move, nil) |> set_review_index(length(line)) {:noreply, push_review_position(socket)} @@ -489,6 +514,12 @@ defmodule ChesstrainerWeb.EndgameLive.PlayCore do defp find_move(_tablebase, _from, _to, _promotion), do: nil + defp find_move_by_uci(%Tablebase{moves: moves}, uci) when is_list(moves) do + Enum.find(moves, &(&1.uci == uci)) + end + + defp find_move_by_uci(_tablebase, _uci), do: nil + # Compare only the board and side to move: chess.js may normalise the rest # (castling/en-passant/halfmove/fullmove) differently from the stored FEN. defp same_position?(fen_a, fen_b), do: position_key(fen_a) == position_key(fen_b) diff --git a/lib/chesstrainer_web/live/endgame_live/train.ex b/lib/chesstrainer_web/live/endgame_live/train.ex index 5edd14e..7826511 100644 --- a/lib/chesstrainer_web/live/endgame_live/train.ex +++ b/lib/chesstrainer_web/live/endgame_live/train.ex @@ -269,6 +269,12 @@ defmodule ChesstrainerWeb.EndgameLive.Train do def handle_event("review_step", %{"index" => index}, socket), do: PlayCore.review_step(socket, index) + def handle_event("review_start", _params, socket), do: PlayCore.review_start(socket) + + def handle_event("review_end", _params, socket), do: PlayCore.review_end(socket) + + def handle_event("review_move", params, socket), do: PlayCore.review_move(socket, params) + def handle_event("play_best_line", _params, socket), do: PlayCore.play_best_line(socket) def handle_event("best_line_move_applied", params, socket), diff --git a/test/chesstrainer_web/live/endgame_live/play_test.exs b/test/chesstrainer_web/live/endgame_live/play_test.exs index 302e9c0..6a4314e 100644 --- a/test/chesstrainer_web/live/endgame_live/play_test.exs +++ b/test/chesstrainer_web/live/endgame_live/play_test.exs @@ -80,7 +80,7 @@ defmodule ChesstrainerWeb.EndgameLive.PlayTest do # Plays one optimal move, applies the opponent's reply, then a losing move, # leaving a three-ply failed attempt to review. - defp seeded_attempt(conn) do + defp seeded_attempt(conn, start_moves \\ grading_moves()) do endgame = endgame_fixture() # The tablebase cache is keyed by position (clocks ignored), so these must @@ -91,7 +91,7 @@ defmodule ChesstrainerWeb.EndgameLive.PlayTest do reply = %Tablebase.Move{uci: "e8e7", san: "Ke7", category: :loss, dtz: -3} losing_reply = %Tablebase.Move{uci: "e8e7", san: "Ke7", category: :draw, dtz: 0} - seed_tablebase(endgame.fen, moves: grading_moves()) + seed_tablebase(endgame.fen, moves: start_moves) seed_tablebase(after_first, category: :loss, moves: [reply]) seed_tablebase(after_reply, category: :win, moves: grading_moves()) seed_tablebase(after_losing, category: :draw, moves: [losing_reply]) @@ -791,20 +791,35 @@ defmodule ChesstrainerWeb.EndgameLive.PlayTest do assert back == fens.after_first end - test "clicking a ply jumps to its position", %{conn: conn} do + test "hides the result panels and move list while reviewing", %{conn: conn} do + {view, _fens} = seeded_attempt(conn) + + view |> element("button", "Review") |> render_click() + + assert has_element?(view, "#best-move-panel") + refute has_element?(view, "#move-list") + refute render(view) =~ "Failed" + refute render(view) =~ "Solved!" + end + + test "jumps to the start and end of the reviewed line", %{conn: conn} do {view, fens} = seeded_attempt(conn) view |> element("button", "Review") |> render_click() %{proxy: {ref, _topic, _}} = view + assert_receive {^ref, {:push_event, "review_position", %{fen: after_losing}}}, 100 + assert after_losing == fens.after_losing - # Consume the position pushed on entering review. - assert_receive {^ref, {:push_event, "review_position", _payload}}, 100 + view |> element("#review-start") |> render_click() - view |> element("button", "Ke7") |> render_click() + assert_receive {^ref, {:push_event, "review_position", %{fen: start}}}, 100 + assert start == fens.start - assert_receive {^ref, {:push_event, "review_position", %{fen: fen}}}, 100 - assert fen == fens.after_reply + view |> element("#review-end") |> render_click() + + assert_receive {^ref, {:push_event, "review_position", %{fen: at_end}}}, 100 + assert at_end == fens.after_losing end test "try again exits review and starts a fresh attempt", %{conn: conn} do @@ -857,6 +872,56 @@ defmodule ChesstrainerWeb.EndgameLive.PlayTest do assert panel =~ "Played: Qd4" end + test "groups tablebase moves by outcome during review", %{conn: conn} do + start_moves = [ + %Tablebase.Move{uci: "d1d7", san: "Qd7+", category: :loss, dtz: -1}, + %Tablebase.Move{uci: "d1d4", san: "Qd4", category: :draw, dtz: 0}, + %Tablebase.Move{uci: "d1d8", san: "Qd8", category: :win, dtz: 5} + ] + + {view, _fens} = seeded_attempt(conn, start_moves) + + view |> element("button", "Review") |> render_click() + render_hook(view, "review_step", %{"index" => "0"}) + + panel = view |> element("#best-move-panel") |> render() + + assert panel =~ ~r/Winning.*Qd7\+.*Drawn.*Qd4.*Losing.*Qd8/s + assert panel =~ "DTZ 1" + assert panel =~ "DTZ 5" + end + + test "clicking a tablebase move plays it from the reviewed position", %{conn: conn} do + {view, _fens} = seeded_attempt(conn) + + view |> element("button", "Review") |> render_click() + render_hook(view, "review_step", %{"index" => "2"}) + + %{proxy: {ref, _topic, _}} = view + assert_receive {^ref, {:push_event, "review_position", _}}, 100 + assert_receive {^ref, {:push_event, "review_position", _}}, 100 + + view |> element("#best-move-panel tr[phx-value-uci='d1d5']") |> render_click() + + assert_receive {^ref, {:push_event, "best_line_move", %{from: "d1", to: "d5"}}}, 100 + + best_after = "8/8/8/8/8/8/8/6K1 b - - 1 1" + + seed_tablebase(best_after, + category: :draw, + moves: [%Tablebase.Move{uci: "g1g2", san: "Kg2", category: :draw, dtz: 0}] + ) + + render_hook(view, "best_line_move_applied", %{"fen" => best_after}) + + assert_receive {^ref, {:push_event, "review_position", %{fen: ^best_after}}}, 100 + + panel = view |> element("#best-move-panel") |> render() + assert panel =~ "Kg2" + assert has_element?(view, "button", "Back to game") + refute has_element?(view, "#move-list") + end + test "summarises the failing move and the best alternative", %{conn: conn} do {view, _fens} = seeded_attempt(conn) @@ -864,7 +929,7 @@ defmodule ChesstrainerWeb.EndgameLive.PlayTest do end test "play best line branches and steps the optimal continuation", %{conn: conn} do - {view, _fens} = seeded_attempt(conn) + {view, fens} = seeded_attempt(conn) view |> element("button", "Review") |> render_click() render_hook(view, "review_prev", %{}) @@ -878,20 +943,25 @@ defmodule ChesstrainerWeb.EndgameLive.PlayTest do assert_receive {^ref, {:push_event, "best_line_move", %{from: "d1", to: "d7"}}}, 100 best_after = "8/8/8/8/8/8/8/8 w - - 2 1" - seed_tablebase(best_after, category: :draw, moves: []) + + seed_tablebase(best_after, + category: :draw, + moves: [%Tablebase.Move{uci: "d8d7", san: "Qd7", category: :draw, dtz: 0}] + ) + render_hook(view, "best_line_move_applied", %{"fen" => best_after}) assert_receive {^ref, {:push_event, "review_position", %{fen: ^best_after}}}, 100 - moves = view |> element("#move-list") |> render() - refute moves =~ "Qd4" - assert moves =~ "Qd7+" - assert moves =~ ~s(title="Best line") + panel = view |> element("#best-move-panel") |> render() + assert panel =~ "Qd7" + assert has_element?(view, "button", "Back to game") view |> element("button", "Back to game") |> render_click() - moves = view |> element("#move-list") |> render() - assert moves =~ "Qd4" + assert_receive {^ref, {:push_event, "review_position", %{fen: fen}}}, 100 + assert fen == fens.after_losing + refute has_element?(view, "button", "Back to game") end test "degrades gracefully and reuses played-position snapshots", %{conn: conn} do