Add Flask web application for Sudoku game

- Implements backend API for game logic (new game, fill, check, solve, hint)
- Manages game state using Flask sessions.
- Develops frontend with HTML, CSS, and JavaScript for user interaction, board rendering, timer, and undo functionality.
- Configures the application for production using Gunicorn and WhiteNoise.
- Updates Dockerfile and requirements for web app deployment.
- Sets up FLASK_SECRET_KEY to be read from environment variables.

Dockerfile

@@ -8,34 +8,22 @@ WORKDIR /app
 COPY requirements.txt .
 
 # 4. Install any needed packages specified in requirements.txt
-# Using --no-cache-dir to reduce image size
-# Using --default-timeout to prevent timeouts on slow networks if any package download is slow
 RUN pip install --no-cache-dir --upgrade pip && \
     pip install --no-cache-dir --default-timeout=100 -r requirements.txt
 
 # 5. Copy the rest of the application code into the container at /app
-# This includes your sudoku_bot directory and main.py (if it's in the root or sudoku_bot folder)
-# Assuming your Procfile specifies `python sudoku_bot/main.py`
-# and main.py is inside sudoku_bot directory.
-# If main.py is in the root, you might adjust the CMD or Procfile.
 COPY . .
-# If your sudoku_bot folder is the main source, you could also do:
-# COPY sudoku_bot ./sudoku_bot
-# COPY requirements.txt .
-# COPY Procfile . # If you have other files in root needed in the image
 
-# 6. Make port 8080 available to the world outside this container (optional, not strictly needed for a worker)
-# For a worker process like a Telegram bot, exposing a port isn't strictly necessary
-# unless you have a health check endpoint or something similar.
-# EXPOSE 8080 
+# 6. Make port available
+ENV PORT ${PORT:-7860}
+EXPOSE $PORT
 
-# 7. Define environment variable for the bot token (BEST PRACTICE: set this in Hugging Face Space secrets)
-# We expect BOT_TOKEN to be set in the Hugging Face Space environment
+# 7. Define environment variables (set these in HF Space secrets or your deployment environment)
 ENV BOT_TOKEN=""
+ENV FLASK_SECRET_KEY="a_very_secure_default_secret_key_that_you_SHOULD_override"
+# It's best practice for FLASK_SECRET_KEY to be set in the environment, not defaulted here.
+# The default above is just a placeholder to avoid crashes if not set.
 
-# 8. Run main.py when the container launches
-# This command will be overridden by the Procfile if you use one with Hugging Face.
-# However, it's good practice to have a default command.
-# If you are using a Procfile (`worker: python sudoku_bot/main.py`),
-# Hugging Face will use that. This CMD can be a fallback or for local Docker runs.
-CMD ["python", "sudoku_bot/main.py"]
+# 8. Run Gunicorn to serve the Flask app
+# The module is web_app.app and the Flask instance is named 'app'
+CMD ["gunicorn", "--workers", "2", "--bind", "0.0.0.0:$PORT", "web_app.app:app"]

requirements.txt

@@ -1,2 +1,5 @@
 python-telegram-bot
 numpy
+Flask
+gunicorn
+whitenoise

sudoku_bot/game_logic/__init__.py

@@ -0,0 +1 @@
+# This file makes Python treat the `game_logic` directory as a package.

web_app/__init__.py

@@ -0,0 +1 @@
+# This file makes Python treat the `web_app` directory as a package.

web_app/app.py

@@ -0,0 +1,223 @@
+import os
+from flask import Flask, jsonify, request, session, render_template
+import sys
+
+# Add the parent directory to the Python path to access sudoku_bot
+sys.path.append(os.path.abspath(os.path.join(os.path.dirname(__file__), '..')))
+
+from sudoku_bot.game_logic.sudoku import generate_puzzle, check_win as check_sudoku_win, solve_sudoku, is_valid_move, SIDE
+
+from whitenoise import WhiteNoise
+
+app = Flask(__name__, template_folder='templates', static_folder='static')
+# It's crucial to set a secret key for session management
+# Read from environment variable for production, with a fallback for local development
+app.secret_key = os.environ.get('FLASK_SECRET_KEY', 'dev_secret_key_123!@#')
+# IMPORTANT: The fallback key is for local development ONLY.
+# Set FLASK_SECRET_KEY in your production environment (e.g., Hugging Face Space secrets).
+
+# Serve static files efficiently in production using WhiteNoise
+# WhiteNoise will automatically find your static files if static_folder is set correctly
+app.wsgi_app = WhiteNoise(app.wsgi_app, root=os.path.join(os.path.dirname(__file__), 'static'))
+# Add prefix for static files if they are not at root (e.g. /static/css/style.css)
+# app.wsgi_app = WhiteNoise(app.wsgi_app, root=os.path.join(os.path.dirname(__file__), 'static'), prefix='static/')
+# However, Flask's default static_url_path is '/static', so WhiteNoise should work correctly
+# with the default static serving if files are in 'web_app/static' and accessed via url_for.
+# The most robust way for WhiteNoise to pick up Flask's static files is to let it wrap the app
+# and it will use Flask's static_folder and static_url_path.
+# Let's simplify the WhiteNoise setup assuming default Flask static handling.
+# app.wsgi_app = WhiteNoise(app.wsgi_app)
+# WhiteNoise should automatically use app.static_folder.
+# If static_folder is 'static' (relative to app.py location), it's usually fine.
+# The Flask app's static_folder is 'static', relative to the app's root path (where app.py is).
+# So, web_app/static/ should be found by WhiteNoise.
+# The following configuration is standard and should work:
+# It tells WhiteNoise to serve files from the app's static_folder
+# (which is 'static' relative to app.py, so web_app/static/)
+# at the URL specified by app.static_url_path (default is '/static').
+app.wsgi_app = WhiteNoise(app.wsgi_app, root=os.path.join(os.path.dirname(__file__), 'static'))
+# No, this is not quite right. WhiteNoise's `root` is for *all* files if you are not using add_files.
+# The recommended way for Flask is simpler:
+# app.wsgi_app = WhiteNoise(app.wsgi_app)
+# app.wsgi_app.add_files(os.path.join(os.path.dirname(__file__), 'static'), prefix='static/')
+# Flask's default static_url_path is 'static'.
+# `static_folder` is 'static' relative to `app.py`.
+# The most straightforward way:
+app.wsgi_app = WhiteNoise(app.wsgi_app)
+app.wsgi_app.add_files(os.path.join(os.path.dirname(__file__), 'static'), prefix=app.static_url_path)
+
+
+# --- Helper Functions ---
+def get_user_game():
+    """Retrieves game state from session."""
+    return {
+        'puzzle_board': session.get('puzzle_board'),
+        'solution_board': session.get('solution_board'),
+        'current_board': session.get('current_board'),
+        'difficulty': session.get('difficulty')
+    }
+
+def set_user_game(puzzle, solution, current, difficulty):
+    """Saves game state to session."""
+    session['puzzle_board'] = puzzle
+    session['solution_board'] = solution
+    session['current_board'] = current
+    session['difficulty'] = difficulty
+    session['game_active'] = True
+
+def clear_user_game():
+    """Clears game state from session."""
+    session.pop('puzzle_board', None)
+    session.pop('solution_board', None)
+    session.pop('current_board', None)
+    session.pop('difficulty', None)
+    session.pop('game_active', False)
+
+# --- API Routes ---
+
+@app.route('/api/new_game', methods=['POST'])
+def new_game_api():
+    data = request.get_json()
+    difficulty = data.get('difficulty', 'easy').lower()
+    if difficulty not in ['easy', 'medium', 'hard']:
+        difficulty = 'easy'
+
+    try:
+        puzzle, solution = generate_puzzle(difficulty)
+        current_board_copy = [row[:] for row in puzzle] # User will modify this
+        set_user_game(puzzle, solution, current_board_copy, difficulty)
+
+        return jsonify({
+            'message': f'New game started with difficulty: {difficulty}',
+            'puzzle_board': puzzle,
+            'current_board': current_board_copy, # Send initial state
+            'difficulty': difficulty
+        }), 200
+    except Exception as e:
+        print(f"Error generating puzzle: {e}") # Log error
+        return jsonify({'error': 'Could not start new game. ' + str(e)}), 500
+
+@app.route('/api/fill_cell', methods=['POST'])
+def fill_cell_api():
+    if not session.get('game_active'):
+        return jsonify({'error': 'No active game. Start a new game first.'}), 400
+
+    data = request.get_json()
+    row = data.get('row')
+    col = data.get('col')
+    num = data.get('num')
+
+    game_state = get_user_game()
+    current_board = game_state.get('current_board')
+    puzzle_board = game_state.get('puzzle_board')
+
+    if current_board is None or puzzle_board is None:
+         return jsonify({'error': 'Game state not found in session.'}), 500
+
+    if not (isinstance(row, int) and isinstance(col, int) and isinstance(num, int) and \
+            0 <= row < SIDE and 0 <= col < SIDE and 0 <= num <= SIDE): # num can be 0 to clear
+        return jsonify({'error': 'Invalid input. Row/col must be 0-8, num must be 0-9 (0 to clear).'}), 400
+
+    # Check if the cell is part of the original puzzle
+    if puzzle_board[row][col] != 0:
+        return jsonify({'error': 'Cannot change pre-filled numbers of the puzzle.'}), 400
+
+    current_board[row][col] = num
+    session['current_board'] = current_board # Update session
+
+    return jsonify({
+        'message': f'Cell ({row+1}, {col+1}) updated to {num if num != 0 else "empty"}.',
+        'current_board': current_board
+    }), 200
+
+@app.route('/api/check_game', methods=['GET'])
+def check_game_api():
+    if not session.get('game_active'):
+        return jsonify({'error': 'No active game.'}), 400
+
+    game_state = get_user_game()
+    current_board = game_state.get('current_board')
+    solution_board = game_state.get('solution_board')
+
+    if current_board is None or solution_board is None:
+         return jsonify({'error': 'Game state not found in session.'}), 500
+
+    is_filled = all(all(cell != 0 for cell in row) for row in current_board)
+    is_correct = check_sudoku_win(current_board, solution_board)
+
+    if is_correct:
+        return jsonify({
+            'is_solved': True,
+            'is_filled': True,
+            'message': 'تبریک! شما سودوکو را حل کردید!'
+        }), 200
+    else:
+        return jsonify({
+            'is_solved': False,
+            'is_filled': is_filled,
+            'message': 'جدول فعلی (هنوز) یک راه‌حل صحیح نیست.' if is_filled else 'جدول هنوز کامل نشده یا دارای خطا است.'
+        }), 200
+
+
+@app.route('/api/solve_game', methods=['GET'])
+def solve_game_api():
+    if not session.get('game_active'):
+        return jsonify({'error': 'No active game.'}), 400
+
+    game_state = get_user_game()
+    solution_board = game_state.get('solution_board')
+
+    if solution_board is None:
+        return jsonify({'error': 'Solution not found in session.'}), 500
+
+    # Update current board in session to the solution
+    session['current_board'] = [row[:] for row in solution_board]
+
+    return jsonify({
+        'message': 'Showing solution.',
+        'current_board': solution_board # Send the solved board
+        }), 200
+
+@app.route('/api/hint', methods=['GET'])
+def hint_api():
+    if not session.get('game_active'):
+        return jsonify({'error': 'No active game.'}), 400
+
+    game_state = get_user_game()
+    current_board = game_state.get('current_board')
+    solution_board = game_state.get('solution_board')
+
+    if current_board is None or solution_board is None:
+        return jsonify({'error': 'Game state not found in session.'}), 500
+
+    empty_cells = []
+    for r_idx in range(SIDE):
+        for c_idx in range(SIDE):
+            if current_board[r_idx][c_idx] == 0:
+                empty_cells.append({'row': r_idx, 'col': c_idx})
+
+    if not empty_cells:
+        return jsonify({'message': 'Board is already full! No hints available.', 'hint': None, 'current_board': current_board}), 200
+
+    import random
+    hint_cell_info = random.choice(empty_cells)
+    row, col = hint_cell_info['row'], hint_cell_info['col']
+    hint_value = solution_board[row][col]
+
+    current_board[row][col] = hint_value
+    session['current_board'] = current_board
+
+    return jsonify({
+        'message': f'راهنمایی: مقدار خانه ({row+1}, {col+1}) عدد {hint_value} است.',
+        'hint': {'row': row, 'col': col, 'value': hint_value},
+        'current_board': current_board
+    }), 200
+
+
+# --- Route for serving the main HTML page ---
+@app.route('/')
+def index():
+    return render_template('index.html') # Will be created later
+
+if __name__ == '__main__':
+    app.run(debug=True, port=5001)

web_app/static/css/style.css

@@ -0,0 +1,273 @@
+/* web_app/static/css/style.css */
+body {
+    font-family: 'Tahoma', sans-serif; /* یک فونت فارسی خوانا */
+    display: flex;
+    justify-content: center;
+    align-items: flex-start; /* تغییر به flex-start برای جلوگیری از کشیدگی عمودی اولیه */
+    min-height: 100vh;
+    margin: 0;
+    background-color: #f0f0f0;
+    direction: rtl;
+    padding-top: 20px; /* کمی فاصله از بالا */
+}
+
+.container {
+    background-color: #fff;
+    padding: 20px;
+    border-radius: 8px;
+    box-shadow: 0 0 15px rgba(0,0,0,0.1);
+    text-align: center;
+    width: auto; /* اجازه می‌دهد محتوا عرض را تعیین کند */
+    max-width: 500px; /* حداکثر عرض برای جلوگیری از کشیدگی زیاد در صفحات بزرگ */
+}
+
+h1 {
+    color: #333;
+    margin-bottom: 20px;
+}
+
+.game-controls {
+    margin-bottom: 20px;
+    display: flex;
+    justify-content: center;
+    align-items: center;
+    gap: 15px; /* فاصله بین انتخابگر سطح و دکمه */
+    flex-wrap: wrap; /* اجازه شکستن در صفحات کوچکتر */
+}
+
+.difficulty-selector {
+    display: flex;
+    align-items: center;
+    gap: 5px;
+}
+
+#sudoku-board-container {
+    margin-bottom: 20px;
+    display: grid;
+    grid-template-columns: repeat(9, 1fr);
+    grid-template-rows: repeat(9, 1fr);
+    width: 360px; /* اندازه ثابت برای جدول */
+    height: 360px; /* ارتفاع ثابت برای جدول */
+    border: 3px solid #333; /* خط بیرونی ضخیم تر */
+    margin-left: auto;
+    margin-right: auto;
+    box-sizing: border-box;
+}
+
+.sudoku-cell {
+    box-sizing: border-box;
+    border: 1px solid #ccc;
+    display: flex;
+    justify-content: center;
+    align-items: center;
+    font-size: 1.4em;
+    cursor: pointer;
+    background-color: #fff;
+    transition: background-color 0.2s;
+}
+
+.sudoku-cell input {
+    width: 100%; /* ورودی تمام خانه را بگیرد */
+    height: 100%;
+    text-align: center;
+    border: none;
+    outline: none;
+    font-size: inherit; /* ارث‌بری اندازه فونت از والد */
+    padding: 0;
+    margin: 0;
+    background-color: transparent; /* ورودی شفاف */
+    cursor: pointer;
+    color: #007bff; /* رنگ آبی برای اعداد وارد شده توسط کاربر */
+}
+
+.sudoku-cell.pre-filled input {
+    font-weight: bold;
+    color: #000; /* رنگ مشکی و ضخیم برای اعداد ثابت */
+    cursor: not-allowed;
+}
+
+.sudoku-cell.selected {
+    background-color: #e0f0ff; /* رنگ پس‌زمینه برای خانه انتخاب شده */
+    outline: 2px solid #007bff; /* یک حاشیه برای تاکید بیشتر */
+    z-index: 1;
+}
+
+/* خطوط ضخیم‌تر برای جدا کردن بلوک‌های 3x3 */
+/* ردیف ها */
+#sudoku-board-container .sudoku-cell:nth-child(n+19):nth-child(-n+27), /* مرز پایین ردیف 3 */
+#sudoku-board-container .sudoku-cell:nth-child(n+46):nth-child(-n+54)  /* مرز پایین ردیف 6 */
+{
+    border-bottom: 2px solid #333;
+}
+
+/* ستون ها */
+#sudoku-board-container .sudoku-cell:nth-child(3n) {
+    border-left: 2px solid #333; /* مرز چپ ستون 3 و 6 (چون rtl هستیم، چپ می شود) */
+}
+/* اصلاح برای اینکه خط بیرونی جدول را دوباره نکشد */
+#sudoku-board-container .sudoku-cell:nth-child(9n) {
+     border-left: 1px solid #ccc; /* برگرداندن به خط عادی برای آخرین ستون در هر ردیف */
+}
+/* خطوط برای اولین ستون در حالت rtl */
+#sudoku-board-container .sudoku-cell:nth-child(9n-8) {
+    border-right: none; /* حذف خط راست پیش فرض */
+}
+
+
+.ingame-controls {
+    margin-top: 15px;
+    margin-bottom: 15px;
+}
+
+#numbers-panel {
+    display: flex;
+    justify-content: center;
+    gap: 5px;
+    margin-bottom: 15px;
+    flex-wrap: wrap;
+}
+
+#numbers-panel button {
+    width: 40px; /* کمی بزرگتر */
+    height: 40px;
+    font-size: 1.3em;
+    border-radius: 5px; /* کمی گردتر */
+}
+
+.action-buttons {
+    display: flex;
+    justify-content: center;
+    gap: 10px;
+    flex-wrap: wrap;
+}
+
+.action-buttons button, .game-controls button, #numbers-panel button {
+    padding: 8px 12px;
+    font-size: 1em;
+    cursor: pointer;
+    border: 1px solid #ccc;
+    border-radius: 4px;
+    background-color: #f9f9f9;
+    transition: background-color 0.2s, box-shadow 0.2s;
+    box-shadow: 0 2px 2px rgba(0,0,0,0.05);
+}
+
+.action-buttons button:hover, .game-controls button:hover, #numbers-panel button:hover {
+    background-color: #e9e9e9;
+    box-shadow: 0 2px 5px rgba(0,0,0,0.1);
+}
+.action-buttons button:active, .game-controls button:active, #numbers-panel button:active {
+    background-color: #ddd;
+    box-shadow: inset 0 1px 3px rgba(0,0,0,0.1);
+}
+
+
+.action-buttons button:disabled, #numbers-panel button:disabled {
+    background-color: #e9ecef;
+    cursor: not-allowed;
+    color: #6c757d;
+    box-shadow: none;
+}
+#new-game-btn { /* دکمه بازی جدید را کمی متمایز کنیم */
+    background-color: #28a745;
+    color: white;
+    border-color: #28a745;
+}
+#new-game-btn:hover {
+    background-color: #218838;
+    border-color: #1e7e34;
+}
+
+
+#timer-section {
+    font-size: 1.1em;
+    margin-bottom: 15px;
+    color: #555;
+}
+
+#message-area {
+    margin-top: 15px;
+    padding: 10px 15px;
+    min-height: 24px;
+    border-radius: 4px;
+    font-weight: 500; /* کمی خواناتر */
+    text-align: right; /* برای پیام‌های فارسی */
+    visibility: hidden; /* در ابتدا مخفی */
+    opacity: 0;
+    transition: opacity 0.3s ease-in-out, visibility 0.3s ease-in-out;
+}
+#message-area.visible {
+    visibility: visible;
+    opacity: 1;
+}
+
+
+.message-success {
+    background-color: #d4edda;
+    color: #155724;
+    border: 1px solid #c3e6cb;
+}
+
+.message-error {
+    background-color: #f8d7da;
+    color: #721c24;
+    border: 1px solid #f5c6cb;
+}
+
+.message-info {
+    background-color: #e2e3e5;
+    color: #383d41;
+    border: 1px solid #d6d8db;
+}
+
+.sudoku-cell.error input {
+    color: red !important;
+    font-weight: bold;
+    animation: shake 0.5s;
+}
+
+@keyframes shake {
+  0%, 100% {transform: translateX(0);}
+  25% {transform: translateX(-3px);}
+  75% {transform: translateX(3px);}
+}
+
+.sudoku-cell.hint-cell {
+    background-color: #d1eaff !important;
+    animation: pulse 0.8s ease-in-out;
+}
+
+@keyframes pulse {
+    0% { transform: scale(1); box-shadow: 0 0 0 0 rgba(0, 123, 255, 0.7); }
+    50% { transform: scale(1.05); box-shadow: 0 0 5px 10px rgba(0, 123, 255, 0); }
+    100% { transform: scale(1); box-shadow: 0 0 0 0 rgba(0, 123, 255, 0); }
+}
+
+/* Responsive adjustments */
+@media (max-width: 540px) { /* نقطه شکست را کمی تغییر دادم */
+    .container {
+        width: 98%; /* کمی بیشتر فضا بدهیم */
+        padding: 10px;
+    }
+    #sudoku-board-container {
+        width: 100%;
+        max-width: 360px;
+        height: auto;
+        aspect-ratio: 1 / 1;
+    }
+    .sudoku-cell {
+        font-size: max(3.5vw, 1em); /* اندازه فونت واکنش‌گرا با حداقل سایز */
+    }
+    .game-controls, .ingame-controls, .action-buttons, #numbers-panel {
+        gap: 8px; /* فاصله کمتر در موبایل */
+    }
+    .action-buttons button, .game-controls button, #numbers-panel button {
+        padding: 6px 10px;
+        font-size: 0.9em;
+    }
+     #numbers-panel button {
+        width: 35px;
+        height: 35px;
+        font-size: 1.1em;
+    }
+}

web_app/static/js/main.js

@@ -0,0 +1,401 @@
+// web_app/static/js/main.js
+
+document.addEventListener('DOMContentLoaded', () => {
+    const SIDE = 9;
+    let currentBoard = []; // The board user interacts with
+    let initialPuzzle = []; // The original puzzle, to identify pre-filled cells
+    // let solutionBoard = []; // Not strictly needed to store globally on client if backend handles it
+    let selectedCell = null; // { row, col, element }
+    let undoStack = []; // For undo functionality
+    let timerInterval = null;
+    let timerSeconds = 0;
+
+    // DOM Elements
+    const boardContainer = document.getElementById('sudoku-board-container');
+    const numbersPanel = document.getElementById('numbers-panel');
+    const newGameBtn = document.getElementById('new-game-btn');
+    const difficultySelect = document.getElementById('difficulty');
+    const checkBtn = document.getElementById('check-btn');
+    const solveBtn = document.getElementById('solve-btn');
+    const hintBtn = document.getElementById('hint-btn');
+    const undoBtn = document.getElementById('undo-btn');
+    const messageArea = document.getElementById('message-area');
+    const timerDisplay = document.getElementById('timer');
+
+    // --- Helper Functions ---
+    async function fetchAPI(url, method = 'GET', body = null) {
+        const options = {
+            method: method,
+            headers: {
+                'Content-Type': 'application/json',
+                'Accept': 'application/json'
+            }
+        };
+        if (body) {
+            options.body = JSON.stringify(body);
+        }
+        try {
+            const response = await fetch(url, options);
+            const responseData = await response.json();
+            if (!response.ok) {
+                throw new Error(responseData.error || `HTTP error! status: ${response.status}`);
+            }
+            return responseData;
+        } catch (error) {
+            console.error('API Error:', error);
+            showMessage(`خطا در ارتباط با سرور: ${error.message}`, 'error');
+            return null;
+        }
+    }
+
+    function showMessage(message, type = 'info') {
+        messageArea.textContent = message;
+        messageArea.className = 'message-area visible';
+        messageArea.classList.add(`message-${type}`);
+    }
+
+    function clearMessage() {
+        messageArea.textContent = '';
+        messageArea.className = 'message-area';
+    }
+
+    function toggleActionButtons(disabled) {
+        checkBtn.disabled = disabled;
+        solveBtn.disabled = disabled;
+        hintBtn.disabled = disabled;
+        undoBtn.disabled = disabled || undoStack.length === 0;
+    }
+
+    // --- Timer Functions ---
+    function startTimer() {
+        stopTimer();
+        timerSeconds = 0;
+        updateTimerDisplay();
+        timerInterval = setInterval(() => {
+            timerSeconds++;
+            updateTimerDisplay();
+        }, 1000);
+    }
+
+    function stopTimer() {
+        clearInterval(timerInterval);
+        timerInterval = null;
+    }
+
+    function updateTimerDisplay() {
+        const minutes = Math.floor(timerSeconds / 60);
+        const seconds = timerSeconds % 60;
+        timerDisplay.textContent = `${String(minutes).padStart(2, '0')}:${String(seconds).padStart(2, '0')}`;
+    }
+
+    // --- Undo Functionality ---
+    function pushToUndoStack(row, col, oldValue, newValue) {
+        undoStack.push({ row, col, oldValue, newValue });
+        undoBtn.disabled = false;
+    }
+
+    function handleUndo() {
+        if (undoStack.length === 0) return;
+        const lastAction = undoStack.pop();
+
+        currentBoard[lastAction.row][lastAction.col] = lastAction.oldValue;
+        updateCellOnBoard(lastAction.row, lastAction.col, lastAction.oldValue);
+
+        if (selectedCell && selectedCell.row === lastAction.row && selectedCell.col === lastAction.col) {
+            selectedCell.element.querySelector('input').value = lastAction.oldValue !== 0 ? lastAction.oldValue : '';
+        }
+        // showMessage(`حرکت قبلی بازگردانده شد.`, 'info');
+        if (undoStack.length === 0) {
+            undoBtn.disabled = true;
+        }
+    }
+
+    // --- Board Rendering and Interaction ---
+    function renderBoard(boardData, initialPuzzleData) {
+        boardContainer.innerHTML = '';
+        currentBoard = JSON.parse(JSON.stringify(boardData));
+        initialPuzzle = JSON.parse(JSON.stringify(initialPuzzleData));
+
+        for (let r = 0; r < SIDE; r++) {
+            for (let c = 0; c < SIDE; c++) {
+                const cell = document.createElement('div');
+                cell.classList.add('sudoku-cell');
+                cell.dataset.row = r;
+                cell.dataset.col = c;
+
+                const input = document.createElement('input');
+                input.type = 'text';
+                input.maxLength = 1;
+
+                const isPreFilled = initialPuzzle[r][c] !== 0;
+                if (isPreFilled) {
+                    input.value = initialPuzzle[r][c];
+                    input.readOnly = true;
+                    cell.classList.add('pre-filled');
+                } else {
+                    input.value = boardData[r][c] !== 0 ? boardData[r][c] : '';
+                }
+
+                input.addEventListener('focus', (e) => handleCellFocus(e, cell, r, c));
+                input.addEventListener('input', (e) => handleCellInput(e, r, c));
+                input.addEventListener('keydown', (e) => handleCellKeyDown(e, r, c));
+                // Click is handled by focus generally, but explicit click can also select
+                cell.addEventListener('click', (e) => handleCellFocus(e, cell, r, c));
+
+
+                cell.appendChild(input);
+                boardContainer.appendChild(cell);
+            }
+        }
+    }
+
+    function updateCellOnBoard(row, col, value, isHint = false) {
+        const cellElement = boardContainer.querySelector(`.sudoku-cell[data-row='${row}'][data-col='${col}']`);
+        if (cellElement) {
+            const inputElement = cellElement.querySelector('input');
+            inputElement.value = value !== 0 ? value : '';
+
+            document.querySelectorAll('.hint-cell').forEach(hc => hc.classList.remove('hint-cell'));
+            if (isHint) {
+                cellElement.classList.add('hint-cell');
+                // Auto-remove highlight after animation completes (CSS animation is ~1s)
+                setTimeout(() => cellElement.classList.remove('hint-cell'), 1500);
+            }
+            // Clear any error styling on this cell if a new value is set
+            cellElement.classList.remove('error');
+        }
+    }
+
+    function handleCellFocus(event, cellElement, row, col) {
+        event.stopPropagation();
+        if (selectedCell && selectedCell.element) {
+            selectedCell.element.classList.remove('selected');
+        }
+
+        const isPreFilled = initialPuzzle[row][col] !== 0;
+        if (isPreFilled) {
+            selectedCell = null;
+            cellElement.querySelector('input').blur();
+            return;
+        }
+
+        selectedCell = { row, col, element: cellElement };
+        cellElement.classList.add('selected');
+        // input already focused by click or tab
+    }
+
+    function handleCellInput(event, row, col) {
+        const value = event.target.value;
+        let num = parseInt(value);
+
+        if (value === '') {
+            num = 0;
+        } else if (isNaN(num) || num < 1 || num > 9) {
+            event.target.value = currentBoard[row][col] !== 0 ? currentBoard[row][col] : '';
+            showMessage('لطفاً یک عدد بین ۱ تا ۹ وارد کنید.', 'error');
+            return;
+        }
+
+        const oldValue = currentBoard[row][col];
+        if (oldValue !== num) {
+            fillCellWithValue(row, col, num, oldValue);
+        }
+    }
+
+    function handleCellKeyDown(event, row, col) {
+        const inputElement = event.target;
+        if (event.key === "Backspace" || event.key === "Delete") {
+            event.preventDefault();
+            if (currentBoard[row][col] !== 0 && initialPuzzle[row][col] === 0) { // Can only clear non-pre-filled
+                 fillCellWithValue(row, col, 0, currentBoard[row][col]);
+            }
+        } else if (event.key >= '1' && event.key <= '9') {
+            // Let input event handle this, but ensure focus remains for direct typing
+            inputElement.value = ''; // Clear previous to allow new single digit input
+        } else if (!["ArrowUp", "ArrowDown", "ArrowLeft", "ArrowRight", "Tab", "Enter"].includes(event.key)) {
+            // Prevent other characters if not navigation or number
+            if (event.key.length === 1 && !event.ctrlKey && !event.altKey && !event.metaKey) {
+                 event.preventDefault();
+            }
+        }
+        // Add arrow key navigation later if desired
+    }
+
+
+    function renderNumbersPanel() {
+        numbersPanel.innerHTML = '';
+        for (let i = 1; i <= 9; i++) {
+            const btn = document.createElement('button');
+            btn.textContent = i;
+            btn.addEventListener('click', () => handleNumberPanelClick(i));
+            numbersPanel.appendChild(btn);
+        }
+        const clearBtn = document.createElement('button');
+        clearBtn.textContent = 'پاک';
+        clearBtn.title = "پاک کردن خانه انتخاب شده";
+        clearBtn.addEventListener('click', () => handleNumberPanelClick(0));
+        numbersPanel.appendChild(clearBtn);
+    }
+
+    function handleNumberPanelClick(num) {
+        if (!selectedCell || (initialPuzzle[selectedCell.row][selectedCell.col] !== 0) ) {
+            showMessage('لطفاً ابتدا یک خانه خالی را از جدول انتخاب کنید.', 'info');
+            return;
+        }
+        const { row, col } = selectedCell;
+        const oldValue = currentBoard[row][col];
+
+        if (oldValue !== num) {
+             fillCellWithValue(row, col, num, oldValue);
+        }
+        // Keep focus on the cell after number panel click for convenience
+        selectedCell.element.querySelector('input').focus();
+    }
+
+    async function fillCellWithValue(row, col, num, oldValue) {
+        currentBoard[row][col] = num; // Optimistic UI update
+        updateCellOnBoard(row, col, num);
+         if (selectedCell && selectedCell.row === row && selectedCell.col === col) {
+             selectedCell.element.querySelector('input').value = num !== 0 ? num : '';
+        }
+
+        pushToUndoStack(row, col, oldValue, num);
+
+        const response = await fetchAPI('/api/fill_cell', 'POST', { row, col, num });
+        if (response) {
+            if (response.error) {
+                currentBoard[row][col] = oldValue; // Revert
+                updateCellOnBoard(row, col, oldValue);
+                 if (selectedCell && selectedCell.row === row && selectedCell.col === col) {
+                    selectedCell.element.querySelector('input').value = oldValue !== 0 ? oldValue : '';
+                }
+                if(undoStack.length > 0 && undoStack[undoStack.length-1].row === row && undoStack[undoStack.length-1].col === col && undoStack[undoStack.length-1].newValue === num) {
+                    undoStack.pop();
+                    if(undoStack.length === 0) undoBtn.disabled = true;
+                }
+                showMessage(response.error, 'error');
+            } else {
+                currentBoard = response.current_board; // Ensure client board is in sync with server's perspective
+                clearMessage();
+            }
+        } else { // Network or other major error
+            currentBoard[row][col] = oldValue; // Revert
+            updateCellOnBoard(row, col, oldValue);
+            if (selectedCell && selectedCell.row === row && selectedCell.col === col) {
+                 selectedCell.element.querySelector('input').value = oldValue !== 0 ? oldValue : '';
+            }
+            if(undoStack.length > 0 && undoStack[undoStack.length-1].row === row && undoStack[undoStack.length-1].col === col && undoStack[undoStack.length-1].newValue === num) {
+                undoStack.pop();
+                 if(undoStack.length === 0) undoBtn.disabled = true;
+            }
+        }
+    }
+
+    // --- Game Actions ---
+    async function handleNewGame() {
+        stopTimer();
+        const difficulty = difficultySelect.value;
+        showMessage('در حال ایجاد بازی جدید...', 'info');
+        toggleActionButtons(true); // Disable buttons during load
+        newGameBtn.disabled = true; // Disable new game btn itself too
+        undoStack = [];
+        undoBtn.disabled = true;
+        selectedCell = null;
+
+        const data = await fetchAPI('/api/new_game', 'POST', { difficulty });
+        newGameBtn.disabled = false; // Re-enable new game btn
+        if (data && data.puzzle_board) {
+            renderBoard(data.current_board, data.puzzle_board);
+            showMessage(`بازی جدید با سطح ${difficultySelect.options[difficultySelect.selectedIndex].text} شروع شد!`, 'success');
+            startTimer();
+            toggleActionButtons(false);
+        } else {
+            showMessage('خطا در شروع بازی جدید. لطفاً دوباره تلاش کنید.', 'error');
+            toggleActionButtons(false); // Re-enable if failed, except undo
+            undoBtn.disabled = true;
+        }
+    }
+
+    async function handleCheckGame() {
+        showMessage('در حال بررسی جدول...', 'info');
+        const data = await fetchAPI('/api/check_game', 'GET');
+        if (data) {
+            if (data.is_solved) {
+                showMessage(data.message || 'تبریک! شما سودوکو را حل کردید!', 'success');
+                stopTimer();
+                toggleActionButtons(true);
+            } else {
+                showMessage(data.message || 'جدول هنوز کامل یا صحیح نیست.', 'error');
+                 // Future: Could add logic to highlight incorrect cells if backend provides them
+            }
+        }
+    }
+
+    async function handleSolveGame() {
+        if (!confirm('آیا مطمئن هستید که می‌خواهید راه‌حل نمایش داده شود؟ بازی فعلی شما تمام می‌شود.')) {
+            return;
+        }
+        showMessage('در حال دریافت راه‌حل...', 'info');
+        const data = await fetchAPI('/api/solve_game', 'GET');
+        if (data && data.current_board) {
+            renderBoard(data.current_board, initialPuzzle);
+            showMessage('راه‌حل نمایش داده شد.', 'success');
+            stopTimer();
+            toggleActionButtons(true);
+            undoStack = []; // Clear undo stack as game is over/solved
+        } else {
+            showMessage('خطا در دریافت راه‌حل.', 'error');
+        }
+    }
+
+    async function handleHint() {
+        showMessage('در حال دریافت راهنمایی...', 'info');
+        const data = await fetchAPI('/api/hint', 'GET');
+        if (data) {
+            if (data.hint) {
+                const { row, col, value } = data.hint;
+                const oldValue = currentBoard[row][col];
+                currentBoard[row][col] = value; // Update client model
+                updateCellOnBoard(row, col, value, true);
+                pushToUndoStack(row, col, oldValue, value);
+                showMessage(data.message, 'info');
+
+                // Check if board is now solved after hint
+                if(data.current_board){ // Server sends updated board after hint
+                    currentBoard = data.current_board; // Sync with server
+                    const checkData = await fetchAPI('/api/check_game', 'GET');
+                    if (checkData && checkData.is_solved) {
+                         showMessage(checkData.message || 'تبریک! با این راهنمایی، سودوکو حل شد!', 'success');
+                         stopTimer();
+                         toggleActionButtons(true);
+                    }
+                }
+            } else {
+                showMessage(data.message || 'راهنمایی‌ای موجود نیست.', 'info');
+            }
+        }
+    }
+
+    // --- Initialization ---
+    function init() {
+        newGameBtn.addEventListener('click', handleNewGame);
+        checkBtn.addEventListener('click', handleCheckGame);
+        solveBtn.addEventListener('click', handleSolveGame);
+        hintBtn.addEventListener('click', handleHint);
+        undoBtn.addEventListener('click', handleUndo);
+
+        document.addEventListener('click', (event) => {
+            if (!boardContainer.contains(event.target) && !numbersPanel.contains(event.target) && selectedCell) {
+                 if(selectedCell.element && !selectedCell.element.contains(event.target)) {
+                    selectedCell.element.classList.remove('selected');
+                    selectedCell = null;
+                 }
+            }
+        });
+
+        renderNumbersPanel();
+        handleNewGame();
+    }
+
+    init();
+});

web_app/templates/index.html

@@ -0,0 +1,52 @@
+<!DOCTYPE html>
+<html lang="fa" dir="rtl">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>بازی سودوکو</title>
+    <link rel="stylesheet" href="{{ url_for('static', filename='css/style.css') }}">
+</head>
+<body>
+    <div class="container">
+        <h1>سودوکو</h1>
+
+        <div class="game-controls">
+            <div class="difficulty-selector">
+                <label for="difficulty">سطح سختی:</label>
+                <select id="difficulty">
+                    <option value="easy" selected>آسان</option>
+                    <option value="medium">متوسط</option>
+                    <option value="hard">سخت</option>
+                </select>
+            </div>
+            <button id="new-game-btn">بازی جدید</button>
+        </div>
+
+        <div id="sudoku-board-container">
+            <!-- جدول سودوکو توسط جاوااسکریپت در اینجا ساخته می‌شود -->
+        </div>
+
+        <div class="ingame-controls">
+            <div id="numbers-panel">
+                <!-- دکمه‌های اعداد ۱-۹ و پاک‌کن توسط جاوااسکریپت -->
+            </div>
+            <div class="action-buttons">
+                <button id="check-btn" disabled>بررسی</button>
+                <button id="solve-btn" disabled>حل کن</button>
+                <button id="hint-btn" disabled>راهنمایی</button>
+                <button id="undo-btn" disabled>واگرد</button>
+            </div>
+        </div>
+
+        <div id="timer-section">
+            زمان: <span id="timer">00:00</span>
+        </div>
+
+        <div id="message-area">
+            <!-- پیام‌ها به کاربر در اینجا نمایش داده می‌شوند -->
+        </div>
+    </div>
+
+    <script src="{{ url_for('static', filename='js/main.js') }}"></script>
+</body>
+</html>