Architecture

How @reetesh/sudoku-engine supports multiple Sudoku variants and how to extend it. For product usage see Overview and Guides.

Design choice: presets + houses

We evaluated two APIs:

// A — named presets (public)
createEngine({ variant: "hyper" });
 
// B — constraint composition (future / advanced)
createEngine({
  constraints: [rowConstraint(), columnConstraint(), boxConstraint(), hyperConstraint()],
});

Chosen: named presets publicly, implemented as composed house sets internally. Advanced users inject a full SudokuVariant via createEngine({ definition }) + defineVariant / composeHouses.

Uniqueness constraints map to houses: fixed sets of cells where digits must be all different.

Beyond uniqueness, meta-constraints (cage-sum, thermometer, kropki) live on SudokuVariant.metaConstraints and are usually attached per puzzle via withMeta / GeneratedPuzzle.metaConstraints.

Layers

Public API
  ├─ createEngine({ variant | definition })  → PuzzleEngine
  ├─ defineVariant / composeHouses           → custom rulesets
  ├─ BatchEngine                             → seeded batch generation
  └─ Classic top-level exports               → lazy classicEngine() facades
 
PuzzleEngine
  └─ SudokuVariant (grid + houses + meta + playable + generation)
 
Core (source of truth)
  ├─ GridSpec / HouseSet / BitGrid / meta
  ├─ validation / solver / generator / hints / play
  └─ errors (SudokuEngineError)
 
Compat shims (classic folders)
  └─ thin classicEngine() wrappers — no new logic
 
Variants (registry)
  └─ named presets only

BitGrid

Each house stores a bitmask of used digits. For a cell:

candidates = fullMask & ~(OR of house masks for that cell)

MRV picks the empty cell with the fewest candidates. House uniqueness uses house masks; meta variants also prune via meta candidate masks.

Solver flow

1. validateBoard (shape + house duplicates + meta when present)
2. BitGrid.fromBoard
3. MRV backtracking: pick cell, try each candidate bit, recurse
4. countSolutions uses the same search with a solution limit (typically 2 for uniqueness)

Generator flow

1. Seed one or more disjoint regions with shuffled digits
2. Backtrack-fill remaining cells using candidate masks (+ meta)
3. Carve clues: shuffle cell order, remove while countSolutions === 1
4. For meta variants, generate cages / thermos / dots consistent with the solution
5. Retry with alternate target clue counts; return null if all attempts fail

Generation tuning lives on SudokuVariant.generation (GenerationProfile), not in variant.id switches:

Tight variants (diagonal, hyper, windoku) use conservative seeding; extra houses make aggressive multi-box seeds unreliable during fill.

Hyper vs Windoku regions

Hyper — four edge-centered 3×3 windows (0-indexed):

Windoku — four inner-corner windows anchored at (1,1), (1,5), (5,1), (5,5).

Built with buildHyperRegionHouses / hyperSudokuHouses and buildWindokuRegionHouses / windokuSudokuHouses in core/houses.ts.

Board type

Board remains (number | null)[][]. Shape and digit range are validated through the active variant.

Classic 9×9 exports (GRID_SIZE, Digit, etc.) stay for backward compatibility. Samurai uses size === 21 on its GridSpec.

Adding a variant

1. Prefer a preset in variants/registry.ts (GridSpec, houses, clue ranges, generation, optional meta/playable).
2. For one-off layouts, build houses with composeHouses / map helpers, then
   createEngine({ definition: defineVariant({ ...base, houses }) }).
3. Keep algorithm code in core/ — never add behavior to classic facade folders.
4. Extend VariantId only when shipping a named preset.
5. Add tests via ALL_VARIANTS / META_VARIANTS and the QA rigorous suite.
6. Document the user-facing rules in OVERVIEW.md and recipes in GUIDES.md.

Files