sudoku-tools/README.md

# 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; staged guided hints; candidate maintenance;
  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 registry-backed constraints;
  overlap-safe clue replacement and removal; quick uniqueness checks; and a
  bounded quality lab for ambiguity, contradictions, redundancy and
  minimality.
- **Generate** — seedable single or batch construction for classic and 12
  variant families, including mixed-family recipes, clue symmetry, constraint
  density, optional minimal-givens proof and independently checked technique
  profiles.
- **Solve** — exact solution counting plus an original human-style engine whose
  deterministic steps include structured evidence, placements and
  eliminations. Uniqueness-dependent logic is disabled unless uniqueness has
  already been proved by a completed exact search.
- **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.

## Constraint coverage

Classic grids and variants share one validated puzzle model and constraint
registry. The production engine currently supports:

- classic, irregular and extra regions; diagonals; disjoint groups;
  anti-knight, anti-king and non-consecutive rules;
- Killer cages, ordered clone regions, quadruples, maximum/minimum cells and
  odd/even cells;
- thermometers, arrows, renban and palindrome lines, between lines, German
  whispers, region-sum lines, modular lines, entropic lines, zipper lines and
  double arrows;
- Kropki dots, numbered 5/10 sum pairs and inequalities;
- X-sums, skyscrapers, little-killer diagonals and sandwich sums; and
- row, column and rectangular-box indexers, plus display-only Fog of War.

Each supported semantic constraint is validated and participates in candidate
filtering and exact solving. Negatable clues can instead be required to be false
for liar/Wrogn constructions; global house rules, extra regions and fog are not
given a misleading false mode. Fourteen original bundled examples cover the
core families and the uniquely checked “Truth and lies” construction. The
newer constraint packs are covered by focused validation, feasibility and exact
solver tests rather than bundled third-party puzzles.

Fog is deliberately a presentation rule, not a hidden solver constraint. It
can be set only when the puzzle carries a complete solution that validates
against the current givens and constraints. Initial lights, givens and correctly
entered digits reveal a radius-zero or radius-one Chebyshev neighbourhood;
wrong entries reveal nothing. Obscured cells are disabled and their values,
notes, candidates, hints, quality overlays and fully hidden clue graphics are
omitted. The trusted solution remains part of the local puzzle document.

## Guided solving and candidate maintenance

A guided hint asks the worker for one supported logical step and discloses it in
four explicit stages: where to look, technique, reasoning and effects preview.
Later-stage answer content is not placed in the document before it is revealed,
and the board does not change until **Apply this step** is chosen. Applying a
step is one undoable transition.

Candidate controls can fill every empty cell with its currently legal centre
candidates, remove invalid centre/corner notes, and optionally prune peer notes
after a placement. Erasing a digit never invents candidates. If an
elimination-only hint is applied without tracked candidates, the app first
creates a complete legal centre-candidate grid and then applies the explicit
elimination.

The logical engine covers singles; naked and hidden pairs, triples and quads;
pointing and claiming; X-Wing, Swordfish and Jellyfish; finned X-Wing and
finned Swordfish; XY-Wing and XYZ-Wing; Skyscraper; Two-String Kite; Simple
Colouring; W-Wing; X-Chains, XY-Chains and alternating inference chains; and
Killer-cage deductions. Unique Rectangle is available only when the caller
supplies a completed uniqueness proof. The engine never infers uniqueness from
a puzzle’s appearance, metadata or a truncated search.

## Setter-quality analysis

The quick setter check performs a bounded zero/one/two-solution audit. A pair of
solutions produces a concrete ambiguity witness with every differing cell and
value. For a uniquely proved baseline, full analysis uses leave-one-out exact
searches to classify each given and constraint as critical, redundant or
unknown and creates a per-cell criticality heatmap. For an unsatisfiable
baseline it instead uses bounded deletion tests to localise a contradictory
core. Optional minimality is proved only when the unique baseline and every
required removal check complete.

Every quality search has configurable per-check node/time limits and shared
aggregate check/node/time limits. Results retain the checks performed, elapsed
time and reasons for unknown conclusions. Reaching a safety limit is never
silently converted into uniqueness, redundancy, contradiction localisation or
minimality. The worker analysis can be cancelled without discarding the last
completed result.

## Generator 2.0

Generation supports the existing classic, diagonal, anti-knight, anti-king,
non-consecutive, Killer, thermo, arrow, Kropki, XV, inequality, renban and
palindrome families. Compatible families can be combined when they share a
supported grid size. Local marking density can be sparse, balanced or dense;
for Killer this changes cage granularity, while inherently global rules retain
their fixed meaning.

Clue removal supports no symmetry, half-turn rotation, horizontal or vertical
reflection, either diagonal reflection, and four-way quarter-turn symmetry.
Minimal-givens mode checks every retained given individually and reports either
a completed proof or the exact unknown reasons. Individual minimisation may
break the requested visual symmetry, which is reported rather than hidden.

Technique profiles can require or forbid supported logical techniques, set
minimum/maximum occurrence counts and require an exact hardest technique. A
puzzle is accepted only when an independent, complete logical path matches the
whole profile and an independent exact check proves uniqueness. Deterministic
batches contain at most 12 candidates and can be ranked by difficulty, fewest
givens or most givens; failed bounded candidates remain visible as failures and
are never included in the verified ranking. Generation is cancellable by
terminating and restarting its worker.

Requested difficulty still controls the clue-removal target rather than
promising a rating. The displayed 0–100 result is calculated afterwards from
logical techniques, clue load and reproducible exact-search evidence. Supported
size/family combinations are deliberately restricted, and a bounded mixed
construction may fail cleanly for an incompatible or unusually difficult
recipe.

## Mobile and accessibility

The board viewport offers a locally persisted 75–200% scale in 25% steps,
increment/decrement controls and a Fit action that returns to 100% and the
origin. Control/Command + plus, minus or zero are board-scoped equivalents.
Explicit Pan mode announces its state, cancels any in-progress drag selection
and disables cell pointer targeting until it is stopped. Tap multi-select, also
available with <kbd>M</kbd>, toggles cells individually without drag selection
and never leaves the active selection empty.

At widths up to 48rem, Play and Set show exactly one sticky entry pad (outside
read-only replay) with safe-area padding and touch-sized zoom controls. Eight
colour marks use distinct patterns as well as hues and expose the hue/pattern
name on both the Sudoku board and aid-mémoire. Screen-reader candidate detail is
independently selectable as Off, concise counts or detailed digits without
changing the visible board.

The board exposes real row/gridcell semantics and concise per-cell state to
assistive technology, including candidates, notes, colours, conflicts,
touching variant clues, hint previews and quality findings. 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. Guided-hint and quality status changes use live
regions.

Fogged cells remain disabled and expose only an obscured status to assistive
technology. Hidden values, notes, constraint descriptions, candidate/helper
overlays and hint effects are masked, and toolbar/helper selection is reduced
to visible cells. A guided hint is shown only if all of its focus and effect
cells are visible; otherwise the app returns a generic no-visible-hint status.

## 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. Before applying one, a structured mapping
preview separates solver-enforced semantics, preserved drawings, retained
metadata and warnings.

The shared inert visual model supports bounded lines, polylines, rectangles,
ellipses, circles and text. f-puzzles maps its decorative line, rectangle,
circle and text fields; SCL maps supported lines, underlays, overlays and
arrows. Drawings, local source identity and scalar metadata survive domain
edits, explicit saves, autosaves, reopening, and project/share exports. They
never become Sudoku rules unless the preview also lists a mapped semantic
constraint. Raw SVG, HTML, CSS, paths or code, unsafe colour syntax, unknown
visual fields, excessive data and rotated or otherwise unrepresentable layouts
are rejected rather than executed or silently changed.

SudokuPad compatibility maps cells, givens and progress, notes, regions,
metadata, solutions, Killer cages and supported global rules. Export can create
readable SudokuPad/CTC JSON or a self-contained `scl…` payload with progress,
regions, cages and canonical drawings for registered constraints. Sudoku Tools
retains its bounded constraint record for its own exact round-trip; another SCL
consumer should only be assumed to enforce constructs it represents natively.
Negated clues and free-form global rules cannot be exported to SCL.

Penpa+ compatibility remains intentionally narrower: square, unrotated Sudoku
grids with givens/progress, thermometers and arrows. f-puzzles export likewise
refuses false clues and underlay, free-coordinate or offset drawings it cannot
preserve faithfully. Preserved source drawings appear on the interactive board
and in static/SCL exports; Fog covers their obscured in-grid portions.

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, safe preserved drawings and
givens; current values, notes and cell colours can be included or omitted with
the progress switch.

## Privacy, recovery and Library

Puzzle parsing, solving, generation and export happen entirely in the browser.
There are no analytics, advertisements, accounts or network-backed puzzle
lookups. Explicit projects are stored in IndexedDB. A separate, debounced
autosave slot retains the current puzzle state, progress, aid-mémoire and a
bounded gameplay history. After an interrupted session, the app offers to
restore or discard that recovery state without silently replacing an explicit
project. Its status distinguishes checking, saving, saved, ready and unavailable
states.

Gameplay history includes undo/redo moments, named savepoints and hypothesis
branches, and is validated when restored. It is bounded to 500 moments and one
MiB for its serialized history payload. The Library supports title and tag
search, tag and completion filters, script-free grid thumbnails, bounded tag
editing, and selected export, duplication or confirmed deletion. Whole-library
import and export remain versioned operations.

If IndexedDB is unavailable, a bounded in-memory fallback keeps work for the
current tab and the interface reports that persistence is unavailable. Browser
storage can still be removed by the browser or user, so important projects
should be exported. 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.

## Offline application shell

Production builds include a relative-scope web app manifest and register a
subpath-aware service worker after the page has loaded. It caches the application
shell and same-origin built assets, uses network-first navigation with a cached
fallback, serves cached static assets when available and removes obsolete cache
versions.

The first successful online load is still required to install those resources,
and service-worker availability depends on browser support and a secure origin.
Registration is progressive enhancement: the application continues to work
when a service worker is unavailable, and puzzle operations never depend on a
network connection.

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