Tres restricciones, una sola celda
Classic Sudoku uses a 9×9 grid divided into nine 3×3 boxes. Digits 1 through 9 must appear once in every row, column and box. The numbers behave as symbols rather than quantities; the puzzle is a constraint system built from three overlapping families of units.
Current status: Sudoku is publicly available
Unlike several other guides in this batch, the Sudoku manifest is marked available and featured. We can describe an integrated public experience rather than only an engine under development. That makes it especially important for the article to reflect current implementation.
Generation starts from a complete valid grid
The engine creates a solved 9×9 board and copies it as the starting puzzle. It then shuffles positions and tries to remove clues one by one. A removal is kept only when the solution counter still returns exactly one solution.
The solution counter stops at two
Search chooses an empty cell with a small candidate set, tries legal values and accumulates solutions. Once the count reaches two, the generator already knows the removal is unacceptable. It does not need to enumerate every alternative.
Most-constrained-first reduces search
Choosing a cell with few candidates is a fail-fast heuristic. Contradictions appear sooner and repeated uniqueness checks become cheaper. That matters because generation invokes the counter after many attempted clue removals.
Current difficulty profiles target clue counts
Easy targets 42 clues, Medium 34, Hard 28 and Expert 24. The engine attempts to remove clues until the target is reached, but any removal that creates a second solution is reverted. The final clue count can therefore remain above the target.
Fewer clues do not automatically mean harder human solving
Clue count is a useful generation control, but two 28-clue Sudokus can require very different techniques. Future calibration could record singles, locked candidates, pairs and more complex reasoning to bring labels closer to player experience.
Uniqueness is a strong invariant of the current generator
Every accepted removal is tested with a counter that stops at two. If another solution appears, the clue returns. The final puzzle therefore preserves exactly one solution under the classic row, column and box rules.
The materialized solution supports validation and hints
The engine keeps the complete generated solution. This makes completion checking and direct hints possible. Product code still needs to ensure that hidden solution data does not leak accidentally into visible state or persistence intended for player progress.
Conflicts are detected using visible rules
The conflict function scans every row, column and 3×3 box, groups repeated values and marks all positions involved. It does not need the hidden answer to know that two 7s in one row violate Sudoku.
Visible-rule feedback preserves agency
Showing a duplicate explains a rule the player already knows. Marking a value “wrong” only because it differs from the hidden solution reveals stronger information. Keeping those concepts separate leaves deduction with the player.
Notes are first-class state
The engine maintains candidate sets for cells. Note mode changes number-pad semantics: a digit becomes a small candidate rather than a committed answer. Persistence and undo need to treat note edits differently from final values.
Auto-notes derive candidates from the current board
The tool can populate legal candidates according to row, column and box restrictions. This is substantial assistance and changes manual workload. Results can retain whether it was used if the product wants session context rather than pretending all completions were identical.
Notes may need cleanup after committed values
When a digit is placed, the same candidate becomes illegal in peer cells. The product can remove those notes automatically or leave note maintenance to the player, but the policy should be consistent and explained.
Undo and redo form a semantic action history
The engine keeps history and future. Undo should restore value, notes and derived state associated with one action rather than merely changing visible text. Redo should reapply the same semantic decision.
A new action invalidates the old redo branch
If the player undoes and then enters a different value, the previous future no longer belongs to the active timeline. Clearing that branch prevents impossible histories and should remain covered by tests.
The timer belongs to the session, not Sudoku rules
A solution is valid regardless of elapsed seconds. Time is experience metadata. Keeping it outside domain rules makes pausing, restoration and comparison easier without contaminating the solver.
Hints should be recorded as assistance
The engine receives a trackHint callback and maintains a hint count. This can be included in common results as context, not as punishment. A completion with several hints is still a completion; the metadata simply explains the session.
A hint can evolve beyond revealing one digit
The full solution enables direct hints, but a richer teaching layer can identify a naked single or explain why one digit has only one legal position in a unit. Solving and teaching remain different jobs.
Sudoku became a useful UI laboratory because the mechanic is familiar
When rules need little introduction, selection, notes, toolbars, onboarding and feedback become easier to evaluate. Several shared game-shell ideas were exercised here before being generalized to other puzzles.
Selection should expose peers without creating noise
Highlighting the active row, column and box helps visualize constraints. Matching digits can also be emphasized. Too many colours or outlines, however, can turn assistance into clutter. Visual hierarchy needs clear priority.
Keyboard input is a primary path
Digits 1–9, N for notes and Delete for clearing are natural interactions. Visible focus and predictable navigation allow fast solving without a pointer.
The number pad provides touch equivalence
The same actions need discoverable on-screen controls for mobile and for players who do not use keyboard shortcuts. A shortcut should accelerate an available function, not hide a function that lacks an accessible control.
Conflicts should not rely on red alone
Colour helps, but an accessible experience can add borders, icons, text state or ARIA information. A broken rule must remain detectable for people who do not perceive the conflict hue.
The manifest already contains Sudoku-specific onboarding
Its steps introduce 3×3 boxes, the tools under the board and the visual difference between givens and player entries. This game-specific teaching content can coexist with the shared onboarding shell.
Rules should not drift across manifest, onboarding and article
Maintaining similar text in several surfaces creates a risk of semantic divergence. Canonical rules should have one clear source, while tutorials and editorial content adapt presentation without changing meaning.
Persistence must retain puzzle, progress and notes
A resumable game needs givens, player values, notes, difficulty, elapsed time, hints and perhaps history if undo should survive reload. Hidden solution data should remain distinct from player progress.
Generation provenance matters if seeds are persisted
If a future generator changes how solved grids or clue removal work, the same seed might produce another puzzle. Durable saves should retain a materialized board or a generation version.
Common results need difficulty and assistance context
Time and mistakes have different meaning on Easy and Expert. Hints and auto-notes change the solve context as well. A useful result keeps those dimensions instead of reducing everything to one completion time.
Difficulty can eventually record actual techniques
An explanation solver can count naked singles, hidden singles, locked candidates, pairs and more complex chains. Classifying by the strongest required technique would align labels more closely with human solving than clue count alone.
Symmetry would be an editorial choice, not a Sudoku rule
Many published Sudokus use symmetric clue patterns for aesthetics. The current engine prioritizes uniqueness and clue target. Adding symmetry should be evaluated as presentation and generation style without compromising the logical invariant.
Removing symmetric clue pairs changes the target problem
If clues are removed in pairs, each attempt changes two cells and must preserve uniqueness. Exact clue targets become harder to reach. This is another reason to treat 42, 34, 28 and 24 as targets rather than guaranteed final counts.
Generation needs tail-latency benchmarks
Every attempted removal can invoke solution counting. Expert tries many removals, so unlucky orders can cost more than average. High-percentile measurements matter because one slow New Game action can make the product feel broken.
A worker could protect the main thread
If generation becomes expensive, solved grids and puzzles are simple arrays that can move through a worker boundary. Concurrency still requires cancellation and stale-result protection when the player requests another game.
A shared Sudoku needs stable identity
A share code can represent givens directly or use seed plus generation version. Another player should receive the same puzzle without the link exposing the hidden solution.
Retry should preserve the puzzle
Retry is meaningful when givens and difficulty stay identical. New game should create another instance. The distinction supports learning, comparisons and reproducible support cases.
The Sudoku family should share only what is genuinely common
X-Sudoku, Jigsaw, Killer and Sandwich reuse a Latin-grid foundation, but each adds constraints that change solving and generation. Shared shell and utilities are valuable; blindly reusing the classic solution counter where extra rules matter would be incorrect.
Catalogue taxonomy can combine family and additional mechanic
“Sudoku” explains familiarity, while arithmetic, irregular regions or diagonals explain the variant. This combination improves discovery without flattening distinct engines.
The editorial visuals explain the generation pipeline
The infographic shows complete solution, clue removal and uniqueness check. That sequence explains why the generator repeatedly needs a solver and adds more value than another generic board screenshot.
Available does not mean finished forever
Public status means an integrated experience exists and can be maintained. Every future change to generation, notes, hints or shared shell still has to preserve the guarantees that made publication trustworthy.
The central lesson is preserving uniqueness during construction
The engine does not remove all clues first and ask at the end whether the board still works. Every removal is tested against the invariant we care about. Integrating generation and verification at each step is one of the strongest patterns Sudoku contributed to other Blupoli engines.
Difficulty can also account for branching resistance
A puzzle that remains solvable by singles for a long stretch is different from one that forces advanced relationships early. Even if the internal uniqueness counter uses search, difficulty tooling can remain separate and analyze human-style techniques.
Auto-notes should be reproducible from domain state
They do not need to be persisted cell by cell if the product can recompute them from givens and current values. Persisting only meaningful player-created notes can reduce save size, provided the distinction remains clear.
Manual notes and auto-notes should not become indistinguishable
A player may intentionally keep a candidate that an automatic recomputation would remove after a temporary experiment. Product design needs a policy: either auto-notes are fully derived, or manual notes are preserved separately. Mixing both semantics creates surprising undo behaviour.
Hints should be invalidated after state changes
If hint computation is asynchronous, the response needs a board version. Undo, redo or a new value can make an old suggestion stale. The UI should ignore advice calculated for another state.
Completion should be a domain transition
Filling the last cell is not enough if conflicts remain. The engine should confirm the board matches Sudoku constraints and then call completion exactly once. Idempotence prevents duplicate results from repeated events.
Restoring a completed game should not replay celebration
Persistence can load the finished state and result without firing one-time effects again. Confetti, sound and analytics are consequences of the transition, not permanent attributes of the board.
Statistics should prefer context over judgement
Time, hints, undo count and difficulty can help a player understand their own sessions. They do not need to be collapsed into a single score that pretends to measure skill perfectly.
Historical context should stay sourced and modest
Nikoli documents introducing the puzzle to Japanese readers in 1984 under the earlier Number Place context and the evolution of the Sudoku name. That is useful background. The modern form has broader antecedents, so one publication should not be presented as the sole invention of every underlying idea.
Difficulty can measure resistance to simple techniques
A richer profile can record how many cells are solved by singles before locked candidates, pairs or more advanced techniques become necessary. Difficulty then becomes a description of the reasoning required for progress rather than only a clue-count target.
The uniqueness solver and the teaching solver do not have to be identical
Counting solutions benefits from fast search and minimum-candidate branching. Teaching benefits from an explainable sequence. Rules and candidate logic can be shared while search policy remains different. Forcing one algorithm to do both jobs can produce technically correct but pedagogically poor hints.
A pedagogical solver can become a second generation filter
After uniqueness is proven, another pass can attempt to solve the board using the technique catalogue allowed for the selected difficulty. An Easy candidate that requires guessing or an Expert candidate that collapses into singles can then be rejected even though both are unique.
Benchmarks should retain real generated puzzles
Each release can keep a small corpus per difficulty. Solver optimizations should preserve uniqueness, completion and reasonable runtime on those cases. Any puzzle that once exposed a bug should join the permanent regression suite.
Accessibility can announce peers and conflicts
A focused cell can expose row, column, box, current value and conflict state. Notes can be presented as a candidate list rather than relying on tiny visual numerals. The goal is to translate the constraint structure into useful non-visual context.
Note mode needs accessible feedback
Toggling notes changes number-pad semantics. The change should be announced and visibly persistent so a player never enters several candidates while believing they are committing answers.
Auto-notes deserve explicit product language
The feature can remove a large amount of manual candidate work. It should be presented as optional assistance rather than an invisible default because it materially changes the solve experience and the interpretation of statistics.
Session restoration needs a clear timer policy
The product can store elapsed active time and resume from there, or use another explicit model. Long periods while the tab is closed should not accidentally inflate solve time. Timing semantics belong to product and should remain stable.
Sharing a puzzle must not leak the solution
A code built from givens or a versioned seed can reproduce the same Sudoku. The solution can stay inside the local engine. URLs, DOM attributes and analytics events do not need to carry hidden answers.
Sharing a completed result is a different intent
After completion, showing the final grid may be appropriate. “Play this puzzle” and “see my result” should be separate share actions because one preserves the challenge and the other can contain spoilers.
Sudoku variants need rule-aware solvers
A classic counter is insufficient for X-Sudoku if it ignores diagonals, and for Killer Sudoku if it ignores cages. Shared utilities must either accept extra constraints correctly or stay explicitly limited to classic Sudoku.
The family can share a base candidate model
Row, column and standard box restrictions form a useful core. X adds diagonals, Jigsaw replaces boxes, and Killer adds arithmetic cages. An extensible contract can reuse candidate infrastructure without pretending every variant is identical.
Shared UI also needs escape hatches
Notes, number selection and toolbars can be reused while cage borders, irregular regions or diagonal highlighting require variant-specific rendering. A design system should make those differences easy rather than forcing entire screens to be cloned.
Published Sudoku is a useful reference implementation
Because it is available and featured, shared-shell regressions are highly visible here. Toolbar, theme, responsive and onboarding changes can be exercised on Sudoku before being generalized across the catalogue.
Shared changes still need diverse consumers
A component improved for Sudoku can break a puzzle without numeric input. Treating Sudoku as a laboratory does not mean optimizing every shared abstraction for it alone. Interaction profiles remain necessary.
Hints should preserve player agency
A direct digit reveal is useful as a last resort, but a first hint can name a technique or highlight a unit worth inspecting. The product can offer levels of help so the player chooses how much information to receive.
Hint telemetry should measure the system before judging the player
If one generated difficulty consistently triggers hints at the same stage, the generator or label may be miscalibrated. Operational data should first ask whether the product is behaving well, not turn hint use into a negative trait.
Conflict feedback should be deterministic
The same board state must always mark the same conflicting cells regardless of action history. Deriving conflicts from domain state rather than incremental CSS updates makes this property easy to test.
Auto-notes should derive from the same candidate function as the solver
Duplicating candidate rules in UI and solver invites disagreement. A shared domain function can expose legal digits while presentation decides how to render them. One rule implementation should support several product features.
Candidate functions need variant awareness when reused
The classic function knows row, column and 3×3 box. Reusing it in an X-Sudoku screen without diagonal extensions would produce incorrect auto-notes. Shared APIs should make their rule scope explicit.
Generation can be tested with metamorphic properties
Permuting digit symbols consistently, swapping equivalent rows within a band or columns within a stack should preserve Sudoku validity. Such transformations create extra test cases without requiring manually authored expected boards.
Uniqueness should survive valid symmetries
If a generated puzzle has one solution, a legal symmetry applied to both clues and solution should also have one. That property can stress serialization and transformation helpers independently from random generation.
Persistence migrations should validate domain meaning
A migrated save is not correct merely because JSON parses. Givens must remain fixed, notes must belong to editable cells, conflicts should recompute identically and the puzzle should preserve its unique solution.
Result schemas should evolve independently from game saves
A compact completed-result record may need difficulty, time, hints and puzzle identity, while a resumable save needs every current value and note. Treating them as different artifacts reduces accidental coupling.
Completion effects should not define completion state
Confetti and sounds are consequences of solving, not the evidence that solving occurred. Domain completion should be testable without rendering, and effects should fire once when the state transition happens.
Retry should clear session metadata consistently
Restarting the same puzzle should reset elapsed active time, hints, history and player entries according to one documented policy while preserving givens. Partial reset semantics can make results impossible to interpret.
New game should cancel old asynchronous work
If generation or hints ever use workers, starting another puzzle must invalidate outstanding requests from the previous one. State versions make stale-result rejection straightforward.
Difficulty labels should remain evidence-backed over time
If the implementation moves from clue targets to technique-based grading, the article, UI and analytics should update together. A label should describe the system currently running rather than the history of how it was first implemented.
The final product should preserve the central idea
A trustworthy Sudoku is a unique puzzle under simple rules, surrounded by tools that help represent reasoning without silently solving the board. Generator, counter, notes, hints and shell all exist to support that experience.
For the broader platform context, see Sudoku as a product UI laboratory, why generation and solving are different jobs, and how Blupoli separates puzzle engines from shared product infrastructure.