Enhance Flask Sudoku Game UI and Functionality

.gitignore

@@ -4,3 +4,6 @@ Thumbs.db
 
 # Ignore Python virtual environment
 .venv/
+# Ignore Python cache files
+__pycache__/
+*.py[cod]

instruction.md

@@ -0,0 +1,75 @@
+# Project Instructions
+
+## Project Overview
+
+This project is a Python Flask Sudoku game being refactored from legacy code into a maintainable, responsive, and user-friendly application.
+
+## Code Quality
+
+- Follow clean and readable Python coding practices.
+- Follow PEP 8 conventions.
+- Use meaningful names for variables, functions, and classes.
+- Prefer small, focused, reusable functions.
+- Avoid unnecessary code duplication.
+- Keep Sudoku game logic separate from Flask route handling where practical.
+- Preserve existing working functionality unless a requirement requires changing it.
+- Add comments and docstrings where they improve understanding.
+- Use consistent error handling.
+
+## Sudoku Requirements
+
+The completed application must:
+
+- Generate valid Sudoku puzzles.
+- Ensure every generated puzzle has exactly one unique solution.
+- Support Easy, Medium, and Hard difficulty levels.
+- Adjust the number of prefilled cells according to difficulty.
+- Keep prefilled cells locked.
+- Provide immediate visual feedback for invalid moves.
+- Display a completion message when the puzzle is solved correctly.
+
+## Game Features
+
+The application must include:
+
+- A Hint button that fills one correct empty cell and locks it.
+- A Check button that highlights incorrect entries.
+- A timer that tracks the player's solving time.
+- A Top 10 scoreboard containing player name, time, difficulty, and number of hints.
+- Browser localStorage so Top 10 scores persist between sessions.
+- A dark mode toggle.
+
+## UI and Styling
+
+- Keep the interface clean and consistent.
+- Support both light and dark modes.
+- Make the layout responsive for desktop and mobile screens.
+- Use alternating colors for the 3x3 Sudoku blocks.
+- Keep text, buttons, and controls readable.
+- Avoid unnecessary layout shifts.
+
+## Testing
+
+- Establish the testing framework before refactoring the application.
+- Preserve existing behavior during refactoring.
+- Run tests after every major refactor or feature update.
+- Do not remove or weaken tests just to make them pass.
+- Investigate the underlying cause of test failures.
+
+## Copilot Usage
+
+- Inspect the existing code before making significant changes.
+- Start with the larger architectural problems before smaller refinements.
+- Prefer incremental and focused changes.
+- Do not rewrite working code unnecessarily.
+- Evaluate Copilot-generated suggestions before accepting them.
+- Reject or modify suggestions that introduce unnecessary complexity.
+- Prefer simple solutions that satisfy the project requirements.
+- Explain unfamiliar generated code before relying on it.
+
+## Documentation
+
+- Keep the README updated with setup and testing instructions.
+- Document the command required to run the test suite.
+- Store required Copilot screenshots in the Screenshots folder.
+- Never include passwords, API keys, or other sensitive information in the repository.

starter/app.py

@@ -6,20 +6,35 @@
 # Keep a simple in-memory store for current puzzle and solution
 CURRENT = {
     'puzzle': None,
-    'solution': None
+    'solution': None,
+    'difficulty': 'medium'
 }
 
+
 @app.route('/')
 def index():
     return render_template('index.html')
 
+
 @app.route('/new')
 def new_game():
-    clues = int(request.args.get('clues', 35))
-    puzzle, solution = sudoku_logic.generate_puzzle(clues)
+    difficulty = request.args.get('difficulty', 'medium')
+    clues = request.args.get('clues')
+
+    try:
+        if clues is not None:
+            clues = int(clues)
+        else:
+            clues = sudoku_logic.get_difficulty_clues(difficulty)
+        puzzle, solution = sudoku_logic.generate_puzzle(clues=clues)
+    except ValueError:
+        return jsonify({'error': 'Invalid difficulty or clue count'}), 400
+
     CURRENT['puzzle'] = puzzle
     CURRENT['solution'] = solution
-    return jsonify({'puzzle': puzzle})
+    CURRENT['difficulty'] = difficulty
+    return jsonify({'puzzle': puzzle, 'solution': solution, 'difficulty': difficulty, 'clues': clues})
+
 
 @app.route('/check', methods=['POST'])
 def check_solution():
@@ -28,12 +43,9 @@ def check_solution():
     solution = CURRENT.get('solution')
     if solution is None:
         return jsonify({'error': 'No game in progress'}), 400
-    incorrect = []
-    for i in range(sudoku_logic.SIZE):
-        for j in range(sudoku_logic.SIZE):
-            if board[i][j] != solution[i][j]:
-                incorrect.append([i, j])
+    incorrect = sudoku_logic.find_incorrect_cells(board, solution)
     return jsonify({'incorrect': incorrect})
 
+
 if __name__ == '__main__':
     app.run(debug=True)

starter/requirements.txt

@@ -1 +1,2 @@
 Flask>=2.0
+pytest>=7.0