Accept alternative checkmating moves in puzzles

internal/client/screens/puzzle.go

@@ -1,4 +1,4 @@
 package screens
 
 import (
 	"fmt"
@@ -261,7 +261,9 @@
 		if algN.Encode(pos, mv) != userSAN {
 			continue
 		}
-		if uciN.Encode(pos, mv) != expectedUCI {
+		// Accept the scripted move, or any alternative that delivers checkmate:
+		// if the player finds a different mate, the puzzle is solved all the same.
+		if uciN.Encode(pos, mv) != expectedUCI && pos.Update(mv).Status() != chess.Checkmate {
 			m.state = puzzleStateFailure
 			return false, ""
 		}
@@ -280,6 +282,12 @@
 	m.solutionIdx++
 	m.viewIdx = m.totalViewPositions()
 	m.updateMoveList()
+	// A checkmating move ends the game immediately — the puzzle is solved even if
+	// the scripted line had more moves (e.g. an alternative, shorter mate).
+	if m.game.Method() == chess.Checkmate {
+		m.state = puzzleStateSuccess
+		return true, ""
+	}
 	if m.solutionIdx < len(m.solution) {
 		return true, m.solution[m.solutionIdx]
 	}

internal/client/screens/puzzle_test.go

@@ -212,6 +212,53 @@ func TestPuzzleSkipMarksAsUnsolved(t *testing.T) {
 	}
 }
 
+// TestPuzzleAcceptsAlternativeMate verifies that a move differing from the scripted
+// solution is accepted when it delivers checkmate. The position (white to move) has
+// several queen mates on the h-file/g7; the puzzle scripts Qh1# ("g2h1") but Qh2# is
+// an equally valid mate and must be accepted as solved.
+func TestPuzzleAcceptsAlternativeMate(t *testing.T) {
+	record := shared.PuzzleRecord{
+		ID:               "altmate1",
+		FEN:              "7k/5K2/8/8/8/8/6Q1/8 w - - 0 1",
+		Moves:            "g2h1", // scripted: Qh1#
+		Rating:           1500,
+		UserPuzzleRating: 1500,
+	}
+	m := NewPuzzleModel("testuser")
+	m.SetPuzzle(record)
+	ok, engineUCI := m.validateAndApply("Qh2#") // different mate than scripted Qh1#
+	if !ok {
+		t.Fatal("alternative mating move Qh2# was rejected")
+	}
+	if engineUCI != "" {
+		t.Errorf("expected no engine response after mate, got %q", engineUCI)
+	}
+	if m.state != puzzleStateSuccess {
+		t.Errorf("state = %v after alternative mate, want puzzleStateSuccess", m.state)
+	}
+}
+
+// TestPuzzleRejectsNonMateAlternative verifies the alternative acceptance is narrow:
+// a legal-but-wrong move that does NOT deliver mate is still a failure.
+func TestPuzzleRejectsNonMateAlternative(t *testing.T) {
+	record := shared.PuzzleRecord{
+		ID:               "altmate2",
+		FEN:              "7k/5K2/8/8/8/8/6Q1/8 w - - 0 1",
+		Moves:            "g2h1", // scripted: Qh1#
+		Rating:           1500,
+		UserPuzzleRating: 1500,
+	}
+	m := NewPuzzleModel("testuser")
+	m.SetPuzzle(record)
+	ok, _ := m.validateAndApply("Qa2") // legal, not the solution, not mate
+	if ok {
+		t.Error("non-mating off-solution move Qa2 was accepted")
+	}
+	if m.state != puzzleStateFailure {
+		t.Errorf("state = %v, want puzzleStateFailure", m.state)
+	}
+}
+
 func setupMultiMovePuzzle(t *testing.T) *PuzzleModel {
 	t.Helper()
 	record := shared.PuzzleRecord{