# Chess puzzle trainer

The local library contains 12,048 puzzles selected from the Lichess puzzle database, obtained 10 November 2026 through the official Lichess/chess-puzzles dataset on Hugging Face. Included puzzles had popularity at least 70, at least 100 plays and rating deviation at most 110 in that snapshot. Each entry stores the original puzzle ID, pre-move FEN, complete UCI line, rating, rating deviation and themes. The first move is played before the player sees the board. The source dataset is released under CC0: https://database.lichess.org/#puzzles and https://huggingface.co/datasets/Lichess/chess-puzzles.

Chess move validation uses chess.js 1.4.0 under its BSD-2-Clause license, reproduced in CHESS_ENGINE_LICENSE.txt. Any legal immediate checkmate is accepted, including a mate different from the recorded solution. Otherwise the dataset's recorded line is required.

## Rating and records

The device-local player rating starts at 1500, rating deviation (RD) 350 and volatility 0.06. Each first attempt is scored as a binary win/loss against the fixed source puzzle rating and RD, using the Glicko-2 formulas with tau 0.5. Each result is treated as one rating period. Each complete inactive day since the preceding result adds one empty-period volatility increment to the RD, capped at 350; the displayed range reflects this increase before the next result as well. The inactivity period and tau are design choices, not parameters calibrated against this site's players. Glicko-2 is normally intended for larger rating periods; sequential puzzle updates and the fixed, filtered puzzle pool mean the displayed uncertainty range is approximate. The range is rating ± 2 RD, not an empirically validated prediction interval. The implementation rejects invalid or extreme stored inputs, bounds numerical probabilities away from zero and one, and caps ratings at ±10,000 as a numerical safety limit; these bounds do not represent a chess title or normal expected range. This is not an official chess or Lichess account rating.

An incorrect legal move, hint, solution or skip records a loss immediately; completing an untouched full line or making an immediate checkmate records a win. A failed puzzle can still be completed without a second update. The scored outcome, first-attempt timing and final board state are persisted together; the settlement transition is idempotent. Rated puzzles are selected randomly within 200 points of the current estimate where possible, with the closest available range as a fallback. Seen IDs, the current position, attempt, rating and records are saved locally. Old saves are preserved; earlier versions did not store timing, history or best streak, so those details cannot be reconstructed.

The clock accumulates while the page is visible, stops on the first rated result and pauses when the page is hidden. It is checkpointed periodically and on page exit. A recovered attempt whose clock was still running at the last save, or a clock interval with a large monotonic/wall-time discrepancy, is excluded from speed records because its elapsed time may be incomplete. Visible-tab time is not proof of continuous attention, and system sleep may not always be detectable. Quickest and average solve times use successful first attempts recorded since timing was added. Separate fastest records are maintained for difficulty bands below 1200, 1200–1599, 1600–1999 and 2000+, but even puzzles in the same band are not directly comparable. Time is deliberately not converted into a rating bonus or penalty: the source puzzle ratings are based on solve outcomes and contain no solve-time distribution with which to calibrate a speed-adjusted rating. The recent median includes timed first-try solves in the last 30 attempts, while the average covers all timed first-try solves since timing began. The rating trend displays up to the latest 30 stored attempts. The recent-results comparison reports the observed solve rate and average model-predicted probability for up to 30 attempts. Prediction uses five-point Gauss-Hermite integration over player rating uncertainty while retaining the Glicko approximation for puzzle RD. Older predictions are excluded from this comparison when the prediction model changes; small samples can vary substantially and do not validate calibration.

Personal best rating, best streak, accuracy, timings and recent attempts update automatically on this device. A separate leaderboard best tracks ratings from the fifteenth rated result onwards, regardless of rating deviation or inactivity. An older profile with at least 15 rated attempts adopts its current rating if that exceeds its already-recorded eligible best. Its unrestricted all-time peak is never copied into the leaderboard record because that peak may come from before puzzle 15. Previously unrecorded historical eligible highs cannot be reconstructed. The all-time best may include provisional ratings. Device records remain self-reported; optional community sharing is described below. For older profiles, the previous version's saved peak may include its initial 1500 starting mark. Browser storage can be cleared or modified by the user. Full puzzle progress stays in this browser; shared community scores can be viewed across devices. Browsers supporting Web Locks allow one visible trainer tab to update the profile at a time; a second tab waits and takes over when the owner is hidden or closed. Browsers without Web Locks display a one-tab warning. If saved profile data cannot be parsed or validated, it is left untouched and new results remain temporary.
# Additional puzzle-trainer details

Pausing explicitly hides the board, disables moves and hints, and stops the active clock; the pause survives reload and tab handover. The visible clock also stops while the tab is hidden. Pauses are allowed, and the clock cannot verify whether someone keeps thinking while paused, so speed records are personal practice records rather than competitive or independently verified times. The in-progress time in an exported backup is deliberately excluded from future speed records because time after export cannot be reconstructed.

The records panel can download a versioned JSON backup and restore it on this device. Restoration validates the profile and the current puzzle position against the bundled library, shows the backup rating and attempt count, and requires an explicit replace confirmation in the interface. Restoring replaces the current device's rating, records, history and active puzzle. A failed validation or failed local-storage write leaves the prior profile in place. The backup remains on the device unless the player chooses to share it.

For at least ten recent scored attempts, the diagnostic reports the observed solve rate, mean predicted probability and Brier score (the mean squared error of the predicted probabilities against first-attempt outcomes). Zero is the best possible Brier score; a constant 50% prediction scores 0.25. Hints and skips count as losses. The diagnostic is descriptive, based on at most 30 adaptively selected puzzles and a small sample; it does not independently validate or calibrate the rating model.

## Casual practice

Casual practice is separate from rated puzzles: it does not change the rated rating, streak, high scores, rated prediction report or timed records. Each mode saves its unfinished position, so switching modes or reloading returns to the same puzzle. Casual puzzles and rated puzzles both exclude previously shown IDs; one pair of duplicate source positions is also excluded together. Thus practice does not subsequently present an already-seen position as a fresh rated puzzle. The finite library can eventually be exhausted.

The practice estimate starts from the current rated estimate and its inactivity-adjusted RD (with the prior RD constrained to 120–350). Up to 20 recent unassisted first attempts update a regularised logistic skill estimate using the source puzzle rating and deviation, with weight 0.9 per older observation. As observations leave that window, they are folded into a persistent Glicko-based baseline with each baseline shift capped at 35 points; later changes to the rated estimate shift the baseline as well. This lets the estimate keep adapting over long-term casual play. Sparse evidence is shrunk towards the rated prior by n/(n+4), and the pre-shrink adjustment is bounded to ±500 points; these are training heuristics, not validated player ratings. The next target is 60 points above the resulting estimate. The selector chooses an unseen puzzle within 100 points of that target when possible, gives candidates at or above the estimate twice the sampling weight, and otherwise uses the closest available range. A correct full first attempt and a first wrong move provide observations; asking for help or skipping before an error is neutral. If a wrong move has already been observed, later help does not erase it. Completing a puzzle after assistance or retries still counts as a casual completion. The practice clock runs through retries and hints, can be paused, and is not used in rated speed records.

Version 2 backups preserve both mode slots, the casual observations and the set of exposed puzzles. Version 1 backups remain importable. Unfinished puzzles restored from a backup are paused and excluded from rated speed records, because time since export cannot be reconstructed.


## Match and puzzle navigation

The match setup keeps the start button and puzzle entry visible while its options scroll, and restores keyboard focus when dismissed. Its selections expose their state to assistive technology. Timed matches pause while the setup is open; cancelling returns to the same position. The board supports arrow-key navigation and Enter or Space to select a square. The puzzle trainer’s Back to match link resumes an unfinished saved match when one is available; otherwise it opens match setup.

The personal high scores panel records the latest ten new displayed rating highs, including the attempt, date and provisional status; five are shown. Existing best ratings are retained when upgrading, but older milestone dates cannot be reconstructed. These records are included in profile backups. The setup screen offers direct casual and rated links, and each mode retains its unfinished puzzle.

## Community high scores

The shared community board requires a registered, signed-in account with a verified email to submit a best eligible rated puzzle estimate after at least 15 rated attempts. Rating confidence and RD never restrict eligibility. The current rating and previously recorded eligible best are used; an unrestricted peak from before the fifteenth result is never imported. The displayed uncertainty range remains informational. Casual practice and time do not affect the board. Opening the leaderboard hides the puzzle board and stops the active clock until it closes. Submission is explicit. Scores and names are public, and scores are self-reported and unverified. Submissions use the reserved account username; guests can read the board and keep local records. The same moderation, rate limits, local fallback and manually retried pending uploads as the other games apply. The separate `0007_chess_puzzle_scores.sql` migration must be applied to the existing D1 database before this board can be used. Existing game tables and records remain unchanged.

Verified signed-in players may explicitly enable automatic community sharing under their account username. Logging out or switching accounts stops automatic sharing until it is enabled again. Only the highest eligible rated best from puzzle 15 onwards is queued; it survives reload and retries with backoff while an owning tab is active and online. Turning it off stops future retries, although a request already received by the server may still complete. The saved opt-in and pending score are local to the browser, and community scores remain self-reported. Signed-in submissions are linked to the verified account name. A puzzle clock pauses and its board is hidden while appearance settings or the leaderboard are open. Board and piece finishes are shared between match and puzzle screens on this device.
