feat: launch local-first Sudoku workbench

2026-08-30 14:14:11 +02:00
commit 659640b231
97 changed files with 19111 additions and 0 deletions
@@ -0,0 +1,73 @@
+# 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.
+- **Set** — givens, metadata, regions and typed constraints; uniqueness checks
+  and seeded classic puzzle generation.
+- **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 XV clues,
+inequalities, renban lines, palindromes, anti-knight, anti-king and
+non-consecutive rules. 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.
+
+## 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).