Files
chess-endgame-trainer/docs/adr/0009-ephemeral-puzzle-sessions.md
owenrees 55d2e2a913 add puzzle training sessions with difficulty and ratings
- /train starts an ephemeral session by choosing easy/medium/hard, banded
  relative to the user's current rating (band width configurable)
- session timer, average per-puzzle time, net rating gain and per-puzzle delta
- next puzzle, plus review and retry reused from the play surface
- explicit stop/start: stopping returns to the difficulty picker
- puzzle rating shown once a puzzle completes, and a side-to-move indicator
- extract the play logic/markup into shared PlayCore and PlayComponents so the
  standalone play view and sessions share one implementation
- sticky footer; glossary entries for Difficulty and Session; ADR 0009
2026-11-05 15:44:11 +01:00

32 lines
1.8 KiB
Markdown

# Puzzle sessions are ephemeral and share one play surface
A session — one continuous spell of puzzle play, started by choosing a
difficulty — carries a start time and a rating baseline for the timer and
rating-gain monitor, and lives only in the running `Train` LiveView. Nothing is
persisted: attempts are still recorded per endgame, but the session itself has
no table.
The alternative was to keep `EndgameLive.Play` as the play surface and navigate
from puzzle to puzzle (e.g. `/endgames/:code/play?session=...`), carrying the
session in the URL or a short-lived server token. Navigation kills the LiveView
socket, so the timer, per-puzzle times, baseline and completed count would all
have to be carried or re-derived; that fights the "ephemeral" decision and
leaks session state into URLs. Instead the session owns one socket and swaps the
current endgame in place, which keeps every session value in one place.
To avoid a second copy of the move grading and best-line review, the play
surface (board, grading, opponent reply, review, retry) is extracted into a
shared module used by both `EndgameLive.Play` (standalone, optional auth, used
by daily/curated deep links) and the new `EndgameLive.Train` (session, login
only). Both keep their own `handle_event` entry points, which delegate to the
shared logic, so the existing play tests and event contract are unchanged.
## Consequences
- `/endgames/:public_code/play` stays a standalone play surface; `/train` is the
session front door.
- Session state (difficulty, start time, baseline, completed count, per-puzzle
timing) never leaves the `Train` socket and disappears when the page closes.
- Difficulty is relative to the current user's rating, not an absolute property
of an endgame; its band width is a config constant.