# 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).