86 lines
3.7 KiB
Markdown
86 lines
3.7 KiB
Markdown
# 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](https://git.add-ideas.de/lotobo/toolbox-portal), 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; conflict highlighting; timer and
|
||
local progress; optional digit-completion counts and matching-digit
|
||
highlights.
|
||
- **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.
|
||
- **Solve** — exact solution counting plus an original human-style engine whose
|
||
steps include structured evidence, placements and eliminations.
|
||
- **Helpers** — Killer combinations and candidate-aware assignments, 45-rule
|
||
residuals, and Kropki, XV or inequality relation 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, anti-knight,
|
||
anti-king and non-consecutive rules. Thirteen bundled, uniquely checked examples
|
||
demonstrate every supported constraint. Import accepts compact grid strings,
|
||
this project's JSON format, share fragments, and the common f-puzzles fields
|
||
supported by the model. Unknown constraints are reported rather than silently
|
||
discarded.
|
||
|
||
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.
|
||
|
||
## 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
|
||
are accepted without contacting their originating site.
|
||
|
||
## Development
|
||
|
||
Requirements: Node.js 22 or newer and npm 11 or newer.
|
||
|
||
```sh
|
||
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
|
||
|
||
```sh
|
||
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 code, artwork, wording or proprietary puzzle data from those applications is
|
||
included. Algorithms and explanations in this repository are independently
|
||
implemented from mathematical rules and public standards.
|
||
|
||
## Licence
|
||
|
||
Sudoku Tools is free software under `GPL-3.0-or-later`. See [LICENSE](LICENSE).
|