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, 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 M, 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.

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

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.1.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.