🔢 SudokuWeb — Sudoku in the Browser
A modern, animated Sudoku built with vanilla HTML, CSS and JavaScript — uniquely-solvable puzzles, pencil-mark notes, limited hints and a local leaderboard, bilingual PT/EN.
🎮 Live Demo
"SudokuWeb" is a from-scratch browser implementation — no frameworks, no build step, no backend — built around a single guarantee: every generated puzzle has exactly one solution. There's no puzzle database — each game is freshly generated in the browser by filling a full grid and carving it back down while checking uniqueness at every step.
The interface opens with a short animated intro, and is fully bilingual, switching instantly between European Portuguese and English.
📦 What's Inside
- 🎚️ Three difficulty levels — Easy (target: 40 clues), Medium (target: 32) and Hard (target: 26)
- ✅ Uniquely-solvable puzzles — clues are removed one at a time, keeping each removal only if the puzzle still solves to exactly one grid
- ✏️ Pencil-mark notes mode — jot down candidate digits in a cell instead of committing a final value
- 🚫 Live conflict detection — placing a digit that already exists in the same row, column or 3x3 box highlights every conflicting cell
- 💡 Two-step teaching hints: the first tap gives a free clue — where to look, without filling anything; the second tap (Reveal, 3/4/5 per game by difficulty) fills the cell and explains the deduction. A wrong digit is fixed first; otherwise the hint uses the simplest technique that works — a single (only one cell for a digit in a box/row/column, or only one digit for a cell), exposed when needed by pointing or claiming candidates, a naked pair or, the hardest, an X-Wing — and shows only the elimination steps that single actually needs
- 🧠 Difficulty graded by human technique, never by guessing: Easy and Medium are solvable with singles alone; Hard always needs pointing/claiming candidates or naked pairs, and those are always enough; expert challenge levels are always solvable by logic up to X-Wing
- ↩️ Undo for the last 200 moves, including after resuming a saved game
- 🔊 Short synthesized sounds (Web Audio, no audio files) with an on/off toggle in the game header, remembered between visits
- 🎬 Smooth animations — pop-in on digit entry and hints, shake on conflicts, a confetti burst on winning
- ⌨️ Full keyboard support — digits 1-9 to fill, Backspace/Delete to erase, arrow keys to move the selection, N to toggle notes, Ctrl/⌘+Z to undo
- 💾 Autosaves mid-game to
localStorage, with a "Continue Game" option from the main menu
- 🏆 A local best-time / fewest-hints leaderboard per difficulty, shown after a win
- 📖 An in-app "How to Play" guide covering the rule, given cells, conflicts, notes and the hint/undo tools
- 🇵🇹 🇬🇧 One-click language toggle between European Portuguese and English, remembered between visits
- 📱 Fully responsive — layout rescales from desktop down to mobile
🛠️ Tech Stack
🏗️ Project Structure
SudokuWeb/
├── index.html # Splash, menu, how-to-play, game screen, modals
├── css/
│ ├── style.css # Theme tokens, base, splash, menu, how-to-play, game header
│ └── board.css # Grid, controls, modals, challenges, responsive (loaded after style.css)
├── js/
│ ├── i18n.js # PT/EN strings and language persistence
│ ├── solver.js # Bitmask MRV solution counter and conflict scan
│ ├── techniques.js # Human techniques: singles, pointing/claiming, naked pairs, X-Wing, grading
│ ├── challenge.js # Endless challenge ladder, stars and level picker
│ ├── generator.js # Randomized full-grid fill + hole digging with uniqueness checks
│ ├── engine.js # Board state, dispatch results, undo stack, teaching hints, snapshots
│ ├── sound.js # Web Audio UI sounds and the on/off preference
│ ├── storage.js # Saved game, menu difficulty and leaderboard persistence
│ ├── overlays.js # Splash, modals, toast, win screens and confetti
│ └── ui.js # Rendering, screen navigation, keyboard input, wiring
├── tests/ # Node regression suites (node tests/game.test.js)
├── LICENSE
└── README.md
⚙️ Game Mechanics
Generating a uniquely-solvable puzzle
1. Fill an empty 9x9 grid completely via randomized backtracking
(shuffled digit order at each cell, row/col/box legality check)
2. Dig holes: shuffle cell order, then for each cell —
- tentatively clear it
- re-solve the puzzle with a capped counter (stop early at 2 solutions)
- keep the removal only if the count is still exactly 1
- otherwise put the digit back
stop once the difficulty's target clue count is reached; a dig that
gets stuck above the target is retried (up to 12 times) and the
sparsest puzzle is kept. Removals must also keep the puzzle solvable by
human techniques: singles only at 32+ clues (Easy, Medium), singles +
pointing/claiming/naked pairs at 26-31 (Hard — which is retried until
singles alone are not enough), and all of those plus X-Wing below 26
(expert levels — retried for a puzzle that needs eliminations, and for
one that needs X-Wing within a bounded budget, since those are rare)
3. The uniqueness check is a bitmask MRV (minimum-remaining-values)
backtracker: row/column/box digits live in 9-bit masks and the search
always branches on the emptiest cell first, so even expert grids are
generated in a few milliseconds. Hints never re-solve — they read the
cached solution grid
여기까지가 README 앞부분입니다. 나머지는 원문에서 읽을 수 있습니다. README 전문 보기 ↗
