5.7 KiB
Sudoku Tools
Sudoku Tools is a standalone, local-first browser workbench for setting, playing, analysing and solving Sudoku puzzles. It belongs to the add·ideas Toolbox, but every release also runs independently from any static HTTPS host or local preview.
Workspaces
- Play — keyboard, mouse and touch entry; multi-cell selection; values, corner/centre notes and colours; undo/redo; named savepoints, hypothesis branches and read-only replay; conflict highlighting; timer and local progress; optional digit-completion counts, matching-digit highlights and a configurable non-constraining aid-mémoire.
- Set — givens, metadata, regions and typed constraints; uniqueness checks with overlap-safe cage replacement and selection-based cage removal.
- Generate — seedable, bounded construction for classic and 12 variant families; independent uniqueness verification and evidence-based difficulty assessment; deterministic mining for a requested logical technique.
- Solve — exact solution counting plus an original human-style engine whose steps include structured evidence, placements and eliminations.
- Helpers — generalized sum combinations with positional candidates and manual eliminations; selected-cell and house candidate-link analysis; Killer combinations, 45-rule residuals, and Kropki, sum-pair or inequality pairs.
Classic grids and common variants share one bounded puzzle model: irregular regions, diagonals, Killer cages, thermometers, arrows, Kropki and numbered 5/10 sum-pair clues, inequalities, renban lines, palindromes, X-sums, skyscrapers, quadruples, maximum cells, anti-knight, anti-king and non-consecutive rules. Every local clue can also be required to be false for liar/Wrogn constructions. Fourteen original bundled examples demonstrate every supported constraint and are exact-search verified as unique.
The board exposes real row/gridcell semantics and concise per-cell state to assistive technology, including candidates, notes, colours, conflicts and touching variant clues. Arrow keys never wrap; Home/End, Control/Command + Home/End and Page Up/Down provide row- and grid-level navigation. The same navigation model is available in the aid-mémoire scratch grid.
Interoperability and visual export
The import dialog recognises compact grids, Sudoku Tools JSON/share fragments, raw or inline f-puzzles data, SudokuPad/CTC (SCL) data, and Penpa+ self-contained long links. It never follows a URL or resolves a server-side short ID. Imports are size/decompression bounded, report their detected source before applying, and stop with a list when a construct cannot be represented faithfully.
SudokuPad compatibility currently preserves cells, givens and progress, notes, regions, metadata, solutions, Killer cages and supported global rules. Penpa+ compatibility is intentionally narrower: square, unrotated Sudoku grids with givens/progress, thermometers and arrows. Visual-only lines, overlays, custom symbols and other unsupported geometry are reported rather than ignored. f-puzzles export likewise refuses false clues it cannot preserve.
Export can produce a standalone SVG, a high-resolution PNG, or a single-page PDF entirely in the browser. Each visual uses the same trusted puzzle model and renders region boundaries, supported variant clues and givens; current values, notes and cell colours can be included or omitted with the progress switch.
Generation supports only size/variant combinations which pass the bounded construction checks. The requested difficulty controls clue-removal targets; the displayed 0–100 result is calculated afterwards from logical techniques, clue load and reproducible exact-search evidence. A timeout or node limit is reported as unknown and never promoted to a uniqueness or difficulty claim. Technique practice performs a bounded, deterministic search and returns a puzzle only when its independently analysed solve path actually contains the requested technique.
Privacy and storage
Puzzle parsing, solving, generation and export happen entirely in the browser. There are no analytics, advertisements, accounts or network-backed puzzle lookups. Projects and progress are saved only in local IndexedDB after an explicit save action and can be cleared from inside the app. Exported files and share URLs contain the puzzle data you chose to include.
SudokuPad short IDs identify server-hosted records and therefore cannot be resolved by this deliberately offline application. Embedded f-puzzles payloads and user-provided Sudoku Tools JSON documents are accepted without contacting their originating site. Externally authored puzzle definitions are not bundled.
Development
Requirements: Node.js 22 or newer and npm 11 or newer.
npm ci
npm run check
npm run test:browser
npm run dev
Vite uses base: './', so dist/ works at / and at nested Toolbox paths.
toolbox-check validates both standalone and contextual operation.
Release
npm run release:artifact
The command verifies the manifest, types, formatting, tests, production build,
browser workflows and Toolbox contract before creating a deterministic
release/sudoku-tools-0.1.0.zip with a matching SHA-256 sidecar.
Scope and references
The interaction ideas and published solving concepts explored by SudokuPad, SudokuWiki and the wider puzzle community informed the product requirements. No externally authored puzzle definitions, code, artwork or documentation text is bundled. Algorithms, UI, original examples and explanations are independently implemented from mathematical rules and public standards.
Licence
Sudoku Tools is free software under GPL-3.0-or-later. See LICENSE.