117 lines
5.7 KiB
Markdown
117 lines
5.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; 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.
|
||
|
||
```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 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](LICENSE).
|