v0.15.0 password recovery, phone layout, CLI pager, embed policy fixes

.github/workflows/test.yml

@@ -43,3 +43,57 @@ jobs:
         run: |
           GOOS=freebsd GOARCH=amd64 go build -trimpath -o /dev/null ./cmd/chess-server
           GOOS=js GOARCH=wasm go build -trimpath -o /dev/null ./cmd/chess-client-cli
+
+  e2e:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    services:
+      postgres:
+        image: postgres:18
+        env:
+          POSTGRES_USER: chess_test
+          POSTGRES_PASSWORD: chess_test
+          POSTGRES_DB: chess_test
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U chess_test -d chess_test"
+          --health-interval 2s
+          --health-timeout 5s
+          --health-retries 30
+    env:
+      CHESS_TEST_DSN: postgres://chess_test:chess_test@localhost:5432/chess_test?sslmode=disable
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+      - uses: actions/setup-go@40f1582b2485089dde7abd97c1529aa768e1baff # v5
+        with:
+          go-version: '1.27.x'
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version: '22'
+      - name: Install Stockfish
+        run: sudo apt-get update -qq && sudo apt-get install -y -qq stockfish
+      - name: Build the server
+        run: make server
+      - name: Install Playwright and Chromium
+        working-directory: test/e2e
+        run: npm install && npx playwright install --with-deps chromium
+      - name: Start the test server with the web client
+        run: |
+          WEB_PORT=9090 MAIL_DIR="$RUNNER_TEMP/chess-mail" LOG_LEVEL=info test/run-test-server.sh bin/chess-server > server.log 2>&1 &
+          for i in $(seq 1 60); do curl -sf http://localhost:8080/health && break; sleep 1; done
+          curl -sf http://localhost:8080/health
+      - name: Run the web client tests
+        working-directory: test/e2e
+        env:
+          CHESS_E2E_MAIL_DIR: ${{ runner.temp }}/chess-mail
+        run: npm test
+      - name: Server log
+        if: failure()
+        run: tail -n 200 server.log
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        if: failure()
+        with:
+          name: playwright-traces
+          path: test/e2e/test-results/
+          if-no-files-found: ignore

Makefile

@@ -167,6 +167,12 @@ test-replay:
 test-draw:
 	test/test-draw.sh
 
+# Web client end-to-end tests (Playwright); needs a server started with
+# WEB_PORT=9090 test/run-test-server.sh and `npm install` in test/e2e.
+.PHONY: test-e2e
+test-e2e:
+	cd test/e2e && npm test
+
 # Database operations
 .PHONY: db-init
 db-init: server
@@ -251,6 +257,7 @@ help:
 	@echo "  make test-endstate Run end-state tests"
 	@echo "  make test-replay  Run replay (SAN, PGN, listing) tests"
 	@echo "  make test-draw    Run draw and resignation tests"
+	@echo "  make test-e2e     Run the web client's Playwright tests (see test/README.md)"
 	@echo ""
 	@echo "Database targets (CHESS_DSN=$(CHESS_DSN)):"
 	@echo "  make db-init      Create or migrate the schema"

README.md

@@ -30,6 +30,8 @@ Go backend server providing a RESTful API for chess gameplay with user authentic
 - Authenticated stored-game listing with cursor pagination and filters
 - Configurable structured debug logs for persistence, cleanup, and engine work
 - User management with secure Argon2id password storage and scoped JWTs
+- Password recovery by email (SMTP relay, or a directory of `.eml` files in
+  development) and administrative reset links
 - Self-service account deletion: claims and names are cleared from stored games
 - Static, CGO-free binaries (cross-compiles for FreeBSD)
 - Scripted deployment: FreeBSD jail (rc.d) or Linux (sandboxed systemd unit)
@@ -134,9 +136,12 @@ their last activity.
 # List all users
 ./chess-server db user list
 
-# Update password
+# Update password (a forgotten one too); without -password it prompts
 ./chess-server db user set-password -username alice -password NewPass456
 
+# One-time reset link to hand to the person (what the recovery email carries)
+./chess-server db user reset-link -username alice -url https://example.com/chess/web-client/
+
 # Update email
 ./chess-server db user set-email -username alice -email newemail@example.com
 
@@ -167,12 +172,16 @@ The chess server includes an embedded web UI for playing games through a browser
 
 - Visual chess board with click-to-move and a promotion picker
 - Human vs Computer gameplay, with undo, draw offers and resignation
-- Configurable engine strength (0-20)
+- Configurable engine strength (0-20) and custom starting positions
-- UCI move history with move numbers
+- Move list in standard algebraic notation; copy the FEN or the PGN
-- FEN display and custom starting positions
+- **My games**: a signed-in user's stored games with thumbnails, filters and
-- Real-time server health monitoring
+  paging; games played anonymously on the device are listed for 24 hours
-- User authentication support
+- **Replay** of any stored game: step, autoplay, flip, keyboard navigation,
-- Responsive design for mobile devices
+  export FEN and PGN at any ply, and shareable links
+  (`?replay=<gameId>&ply=<n>`)
+- Server and storage health in the top bar
+- Accounts: register, sign in, forgotten-password recovery by email, delete
+- Responsive layout, board beside or above the panel
 
 Access the UI at `http://localhost:9090` when server is running with `-serve` flag.
 
@@ -184,8 +193,8 @@ Access the UI at `http://localhost:9090` when server is running with `-serve` fl
 - [Database Operations](./doc/database.md) - layout, psql as `postgres`, games, users, integrity sweep, starting fresh
 - [Architecture](./doc/architecture.md) - System design with auth layer
 - [Development](./doc/development.md) - Build, test, and user management
-- [Client Guide](./doc/client.md) - Interactive debugging client
+- [Client Guide](./doc/client.md) - Interactive debugging client, including replay
-- [Replay Plan](./doc/todo.md) - Phased game-replay implementation and open decisions
+- [Replay Plan](./doc/todo.md) - Game-replay phases, decisions, and what is left
 - [Stockfish Integration](./doc/stockfish.md) - Engine communication
 
 ## License

cmd/chess-client-cli/main.go

@@ -35,8 +35,14 @@ func runClient() (restart bool) {
 		Verbose:    false,
 	}
 
-	// Initialize simple input scanner
+	// Initialize simple input scanner; the pager reads from it between screens
 	scanner := bufio.NewScanner(os.Stdin)
+	s.ReadLine = func() (string, bool) {
+		if !scanner.Scan() {
+			return "", false
+		}
+		return scanner.Text(), true
+	}
 
 	display.Println(display.Cyan, "Chess Debug Client")
 	display.Println(display.Cyan, "API: %s", s.APIBaseURL)
@@ -114,6 +120,12 @@ func buildPrompt(s *session.Session) string {
 		}
 	}
 
+	// A replay replaces the turn: the live game is not what the board shows
+	if seg := command.ReplayPrompt(s); seg != "" {
+		b.Add(display.Magenta, seg)
+		return display.Prompt(b.String())
+	}
+
 	// Add game state if available
 	if s.CurrentGameState != nil {
 		turnInfo := " - Turn:"

cmd/chess-server/cli/cli.go

@@ -5,6 +5,7 @@ import (
 	"errors"
 	"flag"
 	"fmt"
+	"net/url"
 	"os"
 	"strings"
 	"syscall"
@@ -12,6 +13,7 @@ import (
 	"time"
 
 	"github.com/lixenwraith/chess/internal/server/replay"
+	"github.com/lixenwraith/chess/internal/server/service"
 	"github.com/lixenwraith/chess/internal/server/storage"
 
 	"github.com/google/uuid"
@@ -40,7 +42,7 @@ func Run(args []string) error {
 		return runVerify(args[1:])
 	case "user":
 		if len(args) < 2 {
-			return fmt.Errorf("user subcommand required: add, delete, set-password, set-hash, set-email, set-username, list")
+			return fmt.Errorf("user subcommand required: add, delete, set-password, set-hash, set-email, set-username, reset-link, list")
 		}
 		return runUser(args[1], args[2:])
 	default:
@@ -303,6 +305,8 @@ func runUser(subcommand string, args []string) error {
 		return runUserSetEmail(args)
 	case "set-username":
 		return runUserSetUsername(args)
+	case "reset-link":
+		return runUserResetLink(args)
 	case "list":
 		return runUserList(args)
 	default:
@@ -310,6 +314,48 @@ func runUser(subcommand string, args []string) error {
 	}
 }
 
+// runUserResetLink prints a one-time password-reset link for an account, the
+// same link the recovery email carries, for an administrator to pass on when
+// the server sends no mail or the account has no email. It works for an hour
+// and replaces any pending link.
+func runUserResetLink(args []string) error {
+	fs, dsn := newFlagSet("user reset-link")
+	username := fs.String("username", "", "Username")
+	userID := fs.String("id", "", "User ID")
+	publicURL := fs.String("url", "", "Web client address the link opens, e.g. https://example.com/chess/web-client/ (required)")
+	if err := fs.Parse(args); err != nil {
+		return err
+	}
+	base, err := url.Parse(*publicURL)
+	if *publicURL == "" || err != nil || base.Scheme == "" || base.Host == "" {
+		return fmt.Errorf("-url must be the web client's absolute address")
+	}
+
+	store, err := openStore(*dsn, true)
+	if err != nil {
+		return err
+	}
+	defer store.Close()
+
+	targetID, err := lookupUser(store, *username, *userID)
+	if err != nil {
+		return err
+	}
+	token, hash, err := service.NewResetToken()
+	if err != nil {
+		return err
+	}
+	now := time.Now().UTC()
+	if err := store.CreatePasswordReset(storage.PasswordResetRecord{
+		UserID: targetID, TokenHash: hash, CreatedAt: now, ExpiresAt: now.Add(service.PasswordResetTTL),
+	}); err != nil {
+		return fmt.Errorf("failed to create reset: %w", err)
+	}
+	fmt.Printf("Reset link for %s, valid until %s (one use):\n%s\n",
+		abbreviateID(targetID), now.Add(service.PasswordResetTTL).Format(time.RFC3339), service.ResetLink(base, token))
+	return nil
+}
+
 // readPassword prompts on the terminal without echo.
 func readPassword(prompt string) (string, error) {
 	fmt.Print(prompt)

cmd/chess-server/main.go

@@ -5,6 +5,7 @@ package main
 import (
 	"context"
 	"crypto/rand"
+	"errors"
 	"flag"
 	"fmt"
 	"log"
@@ -16,6 +17,7 @@ import (
 
 	"github.com/lixenwraith/chess/cmd/chess-server/cli"
 	"github.com/lixenwraith/chess/internal/server/http"
+	"github.com/lixenwraith/chess/internal/server/mail"
 	"github.com/lixenwraith/chess/internal/server/processor"
 	"github.com/lixenwraith/chess/internal/server/service"
 	"github.com/lixenwraith/chess/internal/server/storage"
@@ -58,6 +60,17 @@ func main() {
 		jwtFile     = flag.String("jwt-secret-file", "", "File holding a stable JWT signing key, mode 0600, at least 32 bytes (default $CHESS_JWT_SECRET_FILE)")
 		dbCleanup   = flag.String("db-cleanup", "off", "Hourly integrity sweep of stored games and accounts: off, report (log only), or delete")
 
+		// Password recovery by email: a transport (SMTP relay, or a directory
+		// of .eml files for development) and the web client's address, which
+		// the emailed link opens. Without a transport, recovery is off.
+		smtpHost     = flag.String("smtp-host", "", "SMTP relay for password-reset email (recovery is off when empty)")
+		smtpPort     = flag.Int("smtp-port", 25, "SMTP relay port")
+		smtpUser     = flag.String("smtp-user", "", "SMTP user name (optional; the password comes from -smtp-password-file)")
+		smtpPassFile = flag.String("smtp-password-file", "", "File holding the SMTP password, mode 0600")
+		mailFrom     = flag.String("mail-from", "", "Sender address of server email, e.g. \"Chess <chess@example.com>\"")
+		mailDir      = flag.String("mail-dir", "", "Write email to .eml files in this directory instead of sending (development)")
+		publicURL    = flag.String("public-url", "", "Web client address that emailed links open, e.g. https://example.com/chess/web-client/")
+
 		// Web UI server flags
 		serve     = flag.Bool("serve", false, "Enable web UI server")
 		webHost   = flag.String("web-host", "localhost", "Web UI server host")
@@ -165,6 +178,27 @@ func main() {
 	}
 	svc.SetIntegrityMode(integrity)
 
+	// Password recovery needs mail and the client's public address.
+	sender, err := mail.Config{
+		SMTPHost: *smtpHost, SMTPPort: *smtpPort, SMTPUser: *smtpUser, SMTPPasswordFile: *smtpPassFile,
+		Dir: *mailDir, From: *mailFrom,
+	}.Build()
+	switch {
+	case errors.Is(err, mail.ErrNoSender):
+		log.Printf("Password recovery disabled (no -smtp-host or -mail-dir)")
+	case err != nil:
+		log.Fatalf("Invalid mail configuration: %v", err)
+	case store == nil:
+		log.Fatalf("Password recovery (-smtp-host or -mail-dir) requires a database (-dsn)")
+	case *publicURL == "":
+		log.Fatalf("Password recovery requires -public-url, the web client address that reset links open")
+	default:
+		if err := svc.SetMailer(sender, *publicURL); err != nil {
+			log.Fatalf("Invalid -public-url: %v", err)
+		}
+		log.Printf("Password recovery enabled: %s; links open %s", sender.Describe(), *publicURL)
+	}
+
 	// Start cleanup job for expired users/sessions
 	cleanupCtx, cleanupCancel := context.WithCancel(context.Background())
 	cleanupDone := make(chan struct{})

deploy/freebsd/rc.d/chessd

@@ -18,11 +18,25 @@
 #                          Default: ${chessd_home}/jwt.key
 # chessd_trusted_proxies:  Reverse-proxy address(es) whose X-Real-IP header is
 #                          trusted as the client address. Default: none
+# chessd_public_url:       The web client's public address, which emailed links
+#                          open. Default: none
+# chessd_smtp_host:        SMTP relay for password-reset email (the mail jail).
+#                          Unset leaves password recovery off. Default: none
+# chessd_smtp_port:        Relay port. Default: 25
+# chessd_smtp_user:        Relay user name, when the relay authenticates
+#                          this host. Default: none
+# chessd_smtp_password_file: File holding that user's password, mode 0600.
+#                          Default: ${chessd_home}/smtp.secret when it exists
+# chessd_mail_from:        Sender address of server email. Default: none
 # chessd_flags:            Additional flags passed to the binary. Default: ""
 #
 # Add the following to /etc/rc.conf to enable:
 #   chessd_enable="YES"
 #   chessd_trusted_proxies="<address nginx connects from>"
+# and, for password recovery by email, once the mail jail relays for this one:
+#   chessd_public_url="https://<site>/chess/web-client/"
+#   chessd_smtp_host="<mail jail address>"
+#   chessd_mail_from="Chess <chess@<site>>"
 
 . /etc/rc.subr
 
@@ -43,6 +57,12 @@ load_rc_config "$name"
 : ${chessd_dsn:="postgres:///chess?host=/tmp"}
 : ${chessd_jwt_key:="${chessd_home}/jwt.key"}
 : ${chessd_trusted_proxies:=""}
+: ${chessd_public_url:=""}
+: ${chessd_smtp_host:=""}
+: ${chessd_smtp_port:="25"}
+: ${chessd_smtp_user:=""}
+: ${chessd_smtp_password_file:=""}
+: ${chessd_mail_from:=""}
 : ${chessd_flags:=""}
 
 command="${chessd_bin}"
@@ -85,6 +105,19 @@ chessd_start()
     if [ -n "${chessd_trusted_proxies}" ]; then
         set -- "$@" -trusted-proxies "${chessd_trusted_proxies}"
     fi
+    # Password recovery by email: relay, sender, and the client address the
+    # link opens. The server refuses a relay without the other two.
+    if [ -n "${chessd_smtp_host}" ]; then
+        set -- "$@" -smtp-host "${chessd_smtp_host}" -smtp-port "${chessd_smtp_port}" \
+            -mail-from "${chessd_mail_from}" -public-url "${chessd_public_url}"
+        if [ -n "${chessd_smtp_user}" ]; then
+            set -- "$@" -smtp-user "${chessd_smtp_user}"
+            secret="${chessd_smtp_password_file:-${chessd_home}/smtp.secret}"
+            if [ -f "${secret}" ]; then
+                set -- "$@" -smtp-password-file "${secret}"
+            fi
+        fi
+    fi
 
     echo "Starting ${desc}."
     # -r restarts the server 5 seconds after an unexpected exit (for example

doc/api.md

@@ -116,6 +116,48 @@ Errors: 400 `INVALID_REQUEST` without a password, 401 for a wrong password or
 token, 429 past 5 attempts a minute per IP, 503 `RESOURCE_LIMIT` when password
 hashing is saturated or `STORAGE_UNAVAILABLE` when storage is down.
 
+### Request a Password Reset
+`POST /auth/recover`
+
+Emails a one-time reset link to the account's address. The response is the
+same whether or not the account exists or has an email, so nothing is
+revealed.
+
+**Request:**
+```json
+{"identifier": "alice"}
+```
+
+- `identifier` (string, required): Username or email address
+
+**Response (202):**
+```json
+{"message": "If the account has an email address, a reset link has been sent to it."}
+```
+
+Errors: 429 past 3 requests a minute per IP, 503 `NOT_CONFIGURED` when the
+server has no mail transport (`/health` reports `"mail": "disabled"`), 502
+when the relay refused the message.
+
+### Reset a Password
+`POST /auth/reset`
+
+Sets a new password with the token from the link (`?reset=<token>` on the web
+client) and signs the user in; the token works once, for an hour, and every
+other session of the account ends.
+
+**Request:**
+```json
+{"token": "…", "password": "NewPass123"}
+```
+
+**Response (200):** as login (`token`, `userId`, `username`, `email`,
+`expiresAt`).
+
+Errors: 400 `INVALID_REQUEST` for a weak password or an invalid, used or
+expired token (`"invalid or expired reset link"`), 429 past 10 a minute per
+IP, 503 when storage or password hashing is unavailable.
+
 ## Game Endpoints
 
 ### Health Check
@@ -129,10 +171,14 @@ Returns server and storage status, and the build the server runs.
   "status": "healthy",
   "time": 1699123456,
   "storage": "ok",
+  "mail": "disabled",
   "version": "v0.14.0-3-g1a2b3c4"
 }
 ```
 
+`mail` is `"ok"` when the server can email password-reset links (the web
+client then offers **Forgot password?**), otherwise `"disabled"`.
+
 `version` is `git describe` of the source the binary was built from (`make`
 sets it), or `dev` for a plain `go build`. Compare it after a deployment: a
 client newer than the server gets 404 `NOT_FOUND` for endpoints the server
@@ -180,6 +226,7 @@ Authorization: Bearer <token>
   "turn": "w",
   "state": "ongoing",
   "moves": [],
+  "san": [],
   "players": {
     "white": {"id": "550e8400-...", "color": 1, "type": 1},
     "black": {"id": "ai-player-...", "color": 2, "type": 2, "level": 15, "searchTime": 1000}
@@ -210,6 +257,9 @@ GET /games/{gameId}?wait=true&moveCount=5
 ```
 
 Response includes all game data. Compare `moves` array length to detect changes.
+`moves` holds the UCI line and `san` the same moves in standard algebraic
+notation, derived by the rules core from the position before each move (an
+entry is empty only for a move it cannot notate, which the server logs).
 
 **Timeout behavior:**
 - Returns current state after 30 seconds even if no changes
@@ -337,8 +387,9 @@ later first-move slot claim, newest first. Requires
   be combined with `cursor`, and pages shift when games are added.
 
 Each item contains game ID, initial FEN, final FEN (after the last stored move,
-or the initial FEN when there is none), result and its `pgnResult` token,
+or the initial FEN when there is none), result, its `pgnResult` token and
-timestamps, players, and move count. `nextCursor` is present only when another
+`termination` (as in the history; both omitted while ongoing), timestamps,
+players, and move count. `nextCursor` is present only when another
 page exists; `nextOffset` also, on requests without a cursor. A game belongs
 to a user who created it while authenticated or claimed a slot with a first
 move; the association survives later player reconfiguration.
@@ -355,6 +406,7 @@ Returns 400 `INVALID_REQUEST` for a malformed cursor or filter.
       "finalFen": "r1bqkb1r/pppp1Qpp/2n2n2/4p3/2B1P3/8/PPPP1PPP/RNB1K1NR b KQkq - 0 4",
       "result": "white_wins",
       "pgnResult": "1-0",
+      "termination": "checkmate",
       "startTimeUtc": "2026-09-07T12:00:00Z",
       "endTimeUtc": "2026-09-07T12:15:00Z",
       "moveCount": 7,
@@ -550,6 +602,7 @@ Error codes:
 - Registration: 5 requests/minute/IP
 - Login: 10 requests/minute/IP
 - Account deletion: 5 requests/minute/IP
+- Password recovery: 3 requests/minute/IP; reset: 10 requests/minute/IP
 
 Exceeding limit returns 429 status. Behind a reverse proxy the client IP is the
 proxy's `X-Real-IP` header, trusted only from addresses listed in

doc/client.md

@@ -12,13 +12,13 @@ The chess client is an interactive command-line debugging tool for the chess ser
 - Verbose mode for detailed API request/response inspection
 - Long-polling support for real-time game updates
 
-## Replay Foundation
+## Replay
 
 The Go API client exposes `GetGameHistory(gameID)`, `GetGamePGN(gameID, ply)`,
 and `GetMyGames(limit, cursor)`, including durable result, timestamps, player
 claims, move count, ordered UCI and SAN moves, and FEN after every move. The
-`games` and `pgn` commands use them; step-by-step `replay` controls are still
+`games`, `pgn` and `replay` commands use them. A replay renders the stored
-planned, see [Replay Implementation Tasks](./todo.md).
+FEN of each ply; the client never computes a move.
 
 ## Building
 ```bash
@@ -44,6 +44,7 @@ The prompt dynamically updates to show context:
 - `chess [username - gameId]` - User in active game
 - `chess [username - gameId] White` - Shows player color
 - Turn indicator with player type (h=human, c=computer)
+- `chess [...] replay 12/40` - Replaying a stored game at ply 12 of 40
 
 ## Command Reference
 
@@ -180,19 +181,76 @@ repetition.` or `Black wins by resignation.`; a pending offer is shown as
 `White offers a draw`.
 
 #### `games` / `g`
-List your stored games, newest first, 20 per page (requires login). The
+List your stored games, newest first, 20 per page (requires login), numbered
-result column is the PGN token (`1-0`, `0-1`, `1/2-1/2`, `*`).
+for `replay <#>`. The result column is the PGN token (`1-0`, `0-1`,
+`1/2-1/2`, `*`).
 ```
 chess > games        # Newest games
 chess > games more   # Next page
 ```
 
 #### `pgn`
-Print a stored game as PGN (SAN movetext, standard tags).
+Print a stored game as PGN (SAN movetext, standard tags), or save it with
+`save <path>`. During a replay the default is the replayed game up to the
+current ply.
 ```
-chess > pgn                  # Current game, every ply
+chess > pgn                        # Current game, every ply
-chess > pgn 10               # Current game, first 10 plies
+chess > pgn 10                     # Current game, first 10 plies
-chess > pgn <gameId> [ply]   # Another game
+chess > pgn <gameId> [ply]         # Another game
+chess > pgn save game.pgn          # Write instead of print
+```
+In the browser build there is no file system: `save` prints the PGN to copy.
+
+### Replay Commands
+
+A replay steps through a stored game's history: any game by ID (histories
+are public to holders of the ID), or one of your own by its number in the
+last `games` listing. The replay is separate from the live session: the
+current game, login and poll position are kept, and `new`, `join`, `move`,
+`computer`, `undo`, `delete`, `poll`, `resign` and `draw` are refused until
+`live` ends the replay.
+
+#### `replay`
+Load a stored game and show its initial position, the players, the result,
+and the whole move list.
+```
+chess > replay 2                                      # From the last 'games' page
+chess > replay a1b2c3d4-e5f6-7890-1234-567890abcdef   # Any stored game
+```
+
+#### `next` / `>`, `prev` / `<`, `first`, `last`, `goto`
+Move through the line; each prints the board, the ply, and the move that
+led to it (`2... Nf6`). `next` and `prev` take a count.
+```
+chess > next
+chess > next 4
+chess > prev
+chess > goto 12
+chess > last
+chess > first
+```
+
+#### `auto`
+Play forward from the current ply to the end of the line, one board per ply,
+with a delay in milliseconds (default 1000).
+```
+chess > auto        # one ply a second
+chess > auto 250
+```
+
+#### `fen`
+Print the FEN of the current position.
+```
+chess > fen
+```
+
+#### `show` / `h` while replaying
+Shows the replayed position instead of the live game.
+
+#### `live`
+Leave the replay and return to the live session.
+```
+chess > live
 ```
 
 ### Debug Commands
@@ -236,6 +294,13 @@ Exit the client.
 chess > exit
 ```
 
+### Long output
+
+`help`, `games`, `pgn`, `state`, `show` and `replay` print one screen at a
+time when their output is taller than the terminal: `-- More (N lines left;
+Enter continues, q quits) --`. The terminal's size comes from the TTY, or in
+the browser from xterm.js; output piped to another program is never paged.
+
 ### Verbose Mode
 
 Append `-v` flag to any command for detailed output:
@@ -285,10 +350,14 @@ ASCII board with colored pieces:
 ```
 
 ### Move History
-Displayed in UCI notation with move numbers:
+The live game's history is displayed in UCI notation with move numbers:
 ```
 History: 1.e2e4 e7e5 2.g1f3 b8c6 3.f1b5
 ```
+A replay lists the stored game in SAN, with the current ply in brackets:
+```
+1. e4 c5 2. [Nf3] Nf6 3. Nc3 e6
+```
 
 ## Workflows
 
@@ -319,8 +388,9 @@ History: 1.e2e4 e7e5 2.g1f3 b8c6 3.f1b5
 ### Limitations
 - No move validation in client (server validates)
 - No algebraic notation input (UCI format only)
-- Single game context at a time
+- Single game context at a time (plus one replay)
 - No persistent authentication across restarts
+- `auto` runs to the end of the line; it cannot be interrupted
 
 ## Error Handling
 

doc/database.md

@@ -131,9 +131,15 @@ sudo chess-db user list
 su -m chess -c '/home/chess/bin/chess-server db user add -username <name> -dsn "postgres:///chess?host=/tmp"'
 ```
 
-Other `user` subcommands: `delete`, `set-email`, `set-username`, and
+Other `user` subcommands: `delete`, `set-email`, `set-username`, `set-hash`
-`set-hash` (an existing PHC string). CLI-created accounts are identical to
+(an existing PHC string), and `reset-link -url <web client>`, which prints a
-site registrations, and the CLI ignores the registration cap.
+one-time password-reset link (valid an hour) to hand to someone who cannot
+receive the recovery email. CLI-created accounts are identical to site
+registrations, and the CLI ignores the registration cap.
+
+Pending password resets live in `password_resets`: the SHA-256 of the token
+in the emailed link, one per account, deleted when used, expired, or by the
+hourly cleanup. The token itself is never stored.
 
 Sign a user out everywhere (takes effect on their next request):
 

doc/deployment-linux.md

@@ -120,7 +120,7 @@ file is kept next to it with a timestamp).
 | `CHESSD_DSN` | `"host=<socket dir> dbname=chess"` | Database over the socket as the OS account |
 | `CHESSD_JWT_KEY` | `/var/lib/chessd/jwt.key` | Stable signing key |
 | `CHESSD_TRUSTED_PROXIES` | `TRUSTED_PROXIES` | Comma-separated proxy addresses |
-| `CHESSD_FLAGS` | empty | Other server flags, e.g. `-max-users 500 -db-cleanup report` |
+| `CHESSD_FLAGS` | empty | Other server flags, e.g. `-max-users 500 -db-cleanup report`, or password recovery by email: `-smtp-host <relay> -mail-from "Chess <chess@example.com>" -public-url https://example.com/chess/web-client/` (see [deployment.md](deployment.md#password-recovery-by-email); the sandboxed unit can read a password file only under `/var/lib/chessd`) |
 
 Server flags worth knowing: `-max-users` (registration cap, default 100),
 `-anonymous-game-ttl` (default `24h`), `-finished-game-ttl` (default `1h`),

doc/deployment.md

@@ -154,6 +154,10 @@ as `postgres`, list them with `\dt chess.*` and name them as `chess.games`.
 | `chessd_dsn` | `postgres:///chess?host=/tmp` | Database `chess` over the socket as the OS user |
 | `chessd_jwt_key` | `${chessd_home}/jwt.key` | JWT signing key; created (0600) on first start if missing |
 | `chessd_trusted_proxies` | empty | Proxy address(es) whose `X-Real-IP` is trusted |
+| `chessd_public_url` | empty | The web client's public address, which emailed reset links open (`https://<site>/chess/web-client/`) |
+| `chessd_smtp_host`, `chessd_smtp_port` | empty, `25` | SMTP relay for password-reset email; unset leaves recovery off |
+| `chessd_smtp_user`, `chessd_smtp_password_file` | empty, `${chessd_home}/smtp.secret` if present | Relay credentials, when the relay authenticates this host; the file is mode 0600 |
+| `chessd_mail_from` | empty | Sender address, e.g. `Chess <chess@<site>>` |
 | `chessd_flags` | empty | Extra flags, e.g. `-max-users 500 -db-cleanup report` |
 
 The script runs `daemon(8)` as root, which writes the supervisor pidfile
@@ -174,6 +178,11 @@ Server flags:
 | `-anonymous-game-ttl` | | Retention of games without a registered player (default `24h`) |
 | `-finished-game-ttl` | | Memory retention of finished games (default `1h`) |
 | `-db-cleanup` | | Hourly integrity sweep: `off` (default), `report` (log findings), or `delete` ([database.md](database.md#integrity-sweep)) |
+| `-smtp-host`, `-smtp-port` | | SMTP relay for password-reset email (default port 25); recovery is off without a transport |
+| `-smtp-user`, `-smtp-password-file` | | Relay credentials, optional; the file is mode 0600 and only sent over TLS |
+| `-mail-from` | | Sender address of server email |
+| `-mail-dir` | | Development: write email to `.eml` files here instead of a relay |
+| `-public-url` | | The web client's address that emailed links open; required with a transport |
 
 Administrative CLI commands run as `chess` so peer authentication selects the
 right role; root may use `su -m` although the account has no shell:
@@ -186,7 +195,47 @@ jail# su -m chess -c '/home/chess/bin/chess-server db user list -dsn "postgres:/
 (games, with 8-digit ID prefixes), `pgn -gameId <id|prefix> [-ply N]`,
 `verify [-gameId <id|prefix>]` (replays stored games against the rules and
 exits non-zero on a mismatch; run it after an upgrade), and `user add|delete|
-set-password|set-hash|set-email|set-username|list`.
+set-password|set-hash|set-email|set-username|reset-link|list`.
+
+A forgotten password is reset from the jail without mail:
+
+```sh
+jail# su -m chess -c '/home/chess/bin/chess-server db user set-password -username <name> -dsn "postgres:///chess?host=/tmp"'
+```
+
+which prompts for the new password (or takes `-password`), or with a one-time
+link to hand to the person, the same link the recovery email carries:
+
+```sh
+jail# su -m chess -c '/home/chess/bin/chess-server db user reset-link -username <name> -url https://<site>/chess/web-client/ -dsn "postgres:///chess?host=/tmp"'
+```
+
+## Password Recovery by Email
+
+With an SMTP relay the server emails a reset link on request (`POST
+/api/auth/recover`, the **Forgot password?** link in the web client); the link
+opens the client, which sets the new password and signs the person in. The
+link works for an hour and once; using it signs the account out everywhere
+else. Accounts without an email address cannot use it (the CLI commands above
+can).
+
+The relay is a separate jail reached over the internal network. Set in
+`rc.conf`:
+
+```sh
+sysrc chessd_public_url="https://<site>/chess/web-client/"
+sysrc chessd_smtp_host="<mail jail address>"      # chessd_smtp_port, default 25
+sysrc chessd_mail_from="Chess <chess@<site>>"
+# only when the relay authenticates this host:
+sysrc chessd_smtp_user="<user>"
+(umask 077 && echo '<password>' > /home/chess/smtp.secret) && chown chess:chess /home/chess/smtp.secret
+service chessd restart
+```
+
+The server uses STARTTLS when the relay offers it and sends credentials only
+over TLS. `GET /chess/health` reports `"mail": "ok"` once recovery is on. For
+a test without a relay, `-mail-dir <dir>` in `chessd_flags` writes each
+message to a file instead.
 
 ## Host nginx and Web Clients
 

doc/development.md

@@ -38,6 +38,9 @@ go build ./cmd/chess-client-cli
 - `-anonymous-game-ttl`: How long games without a registered player survive after their last activity, in memory and in the database (default: `24h`; `0` keeps them)
 - `-max-users`: Accounts at which public registration closes (default: `100`; `0` = no limit; the CLI is not limited)
 - `-web-api-url`: Browser-visible API origin for the embedded web client, set on its script element as `data-api`; useful when its public origin differs from the listen address
+- `-smtp-host`, `-smtp-port`, `-smtp-user`, `-smtp-password-file`, `-mail-from`: SMTP relay for password-reset email; without a transport, recovery is off
+- `-mail-dir`: Development: write email to `.eml` files in this directory instead of sending
+- `-public-url`: The web client's address that emailed links open (required with a transport)
 
 ### Modes
 ```bash
@@ -221,6 +224,10 @@ go test ./...
 
 # Concurrency checks for the state/persistence boundary
 go test -race ./internal/server/storage ./internal/server/service
+
+# Web client end-to-end (Playwright): see test/README.md
+WEB_PORT=9090 MAIL_DIR=/tmp/chess-mail test/run-test-server.sh   # terminal 1
+CHESS_E2E_MAIL_DIR=/tmp/chess-mail make test-e2e                 # terminal 2
 ```
 
 ## Configuration
@@ -304,11 +311,11 @@ go test -race ./internal/server/storage ./internal/server/service
 - JWT tokens don't support refresh (must re-login after expiry)
 - User deletion doesn't cascade to games (games keep player and claim IDs)
 - Games played without a registered player are deleted 24 hours after their last activity
-- No password recovery mechanism
+- Password recovery needs an SMTP relay and an email on the account
 - No email verification for registration
 - Fixed worker pool size for engine calculations
 - No push-based game updates (30-second long-polling is used)
 - Live games are not rehydrated after restart; persisted games are currently replay-only
 - Database history has no automatic retention policy
-- Replay UI, PGN export, and curated games are planned in [Replay Plan](./todo.md)
+- Curated games are planned in [Replay Plan](./todo.md)
 - REST API only

doc/todo.md

@@ -31,6 +31,8 @@ into phases that each ship and test on their own.
 - [x] Rules core (`internal/server/chess`, R1) and replay API (R2), below.
 - [x] Pawn promotion in the web client (piece picker) and a specific API error
   for a promotion without its piece.
+- [x] Web replay UI (R3) and terminal replay commands (R4), below; `san` on
+  the live game response and `termination` on the listing.
 
 ## Decisions
 
@@ -44,6 +46,9 @@ into phases that each ship and test on their own.
 | D6 | Undo after a result | **Decided: keep allowed**, so a player can step back from a finished game and play a line again. Consequence: a finished game's stored history, result, and end time are rewritten by undo; replay shows the line as it stands now. **Refined (v3 schema):** a resignation or agreed draw between two humans is final, and undo, player changes, and unload respect other users' claims (no takebacks between players). Against the computer a concession can be undone, but the first one stays on record (`concession_*`) and in history and PGN. |
 | D8 | Human-vs-human in the web client | **Open.** The web client plays only against the computer; two-player games run through the API and terminal client (`join`, `poll`). A web mode would need join-by-link, a long-poll for the opponent's moves, and an offer indicator on the Draw button (accept by pressing it). |
 | D7 | List pagination | **Done.** Opaque keyset `cursor` on `(start_time_utc, game_id)`; `offset` kept for existing clients and exclusive with `cursor`. |
+| D9 | Replay for visitors without an account | **Done.** The history endpoint is public by ID (D2), so the web client keeps a list of the games it created anonymously in `localStorage` (ID, side, level, last position; entries expire with the server's 24-hour retention) and shows them under **On this device** in My games. A signed-in user's list comes from the API. No server change. |
+| D10 | Live SAN | **Done.** The live game response carries `san` beside `moves`, derived by the rules core from the position before each ply (the shadow check already parses it), so the web client shows SAN without an extra history request and without storage. |
+| D11 | Replay history | **Done.** Views push browser history entries (`?games`, `?replay=<id>&ply=<n>`, or both); stepping through a replay replaces the entry so back and forward move between the live view, the list and the replay rather than ply by ply. |
 
 ## Phase R1 — Notation Core (server) — done
 
@@ -88,29 +93,43 @@ Test gate:
   PGN, ETag, promotion, FEN validation, cursor paging and filters).
 - [x] Terminal client: `games` (cursor paging) and `pgn` commands.
 
-## Phase R3 — Web Replay UI
+## Phase R3 — Web Replay UI — done
 
-Plain JavaScript in the embedded client, no framework.
+Plain JavaScript in the embedded client, no framework. The client was
+restructured around the replay: a top bar (brand, server and storage dots,
+**My games**, account), the board, and a side panel with a live pane and a
+replay pane; the board colours and piece glyphs are unchanged.
 
-- [ ] **My games** button beside the account indicator (authenticated only)
+- [x] **My games** button in the top bar opening a drawer: mini-board from
-  opening a panel: mini-board from `finalFen`, result, date, opponent or
+  `finalFen`, players (the viewer's side as "You"), result and termination,
-  engine level, move count; loading, empty, error, and "load more" states.
+  date, move count; status and colour filters; loading, empty, error (with
-- [ ] Replay mode entered from the panel or a deep link
+  retry), and "load more" (cursor) states. Signed-out visitors see the games
-  `?replay=<gameId>&ply=<n>`; `history.pushState` so browser back/forward
+  played on this device (D9) and a sign-in note.
-  restores the list and the ply.
+- [x] Replay mode entered from the drawer, the live pane's **Replay** button,
-- [ ] Controls: first, previous, next, last; keyboard `←` `→` `Home` `End`;
+  or a deep link `?replay=<gameId>&ply=<n>`; `history.pushState` per view
-  clickable SAN move list; autoplay with speed selector and pause; board flip;
+  (D11), so browser back/forward restores the list and the ply.
-  current ply announced through an `aria-live` region.
+- [x] Controls: first, previous, next, last; keyboard `←` `→` `Home` `End`,
-- [ ] Position rendering assigns the stored FEN for the ply; the browser never
+  `Space` (autoplay), `F` (flip), `Esc` (leave); clickable SAN move list with
-  computes moves.
+  the current ply marked; autoplay with a speed selector and pause; board
-- [ ] Export at the current ply: copy FEN, copy PGN, and download PGN (fetched
+  flip, defaulting to the viewer's side; current ply announced through an
-  from R2 as a `Blob`, saved through a temporary `<a download>`). The live
+  `aria-live` region.
-  view's "Copy PGN" button copies UCI moves today; point it at the PGN
+- [x] Position rendering assigns the stored FEN for the ply; the browser never
-  endpoint too.
+  computes moves. The mated king and the last move are marked as in live play.
-- [ ] Show SAN in the live move list (from the history, or a `san` field on
+- [x] Export at the current ply: copy FEN, copy PGN (`?ply=N`, or the full
-  the live game response).
+  export at the last ply), download PGN (fetched as a `Blob`, saved through a
-- [ ] While replaying: stop live long-polling, disable move, undo, new-game,
+  temporary `<a download>`; the host's iframe sandbox needs
-  and player-configuration controls; **Back to live game** restores them.
+  `allow-downloads`), and copy a link to the position. The live view's "Copy
+  PGN" copies the stored game's PGN, falling back to the SAN line and FEN
+  when storage is off; "Copy FEN" beside it.
+- [x] SAN in the live move list from the `san` field on the live game
+  response (D10).
+- [x] While replaying: live long-polling stops, the live pane (move, undo,
+  new game, draw, resign) hides and square clicks are ignored; **Back to
+  live game** (or **Close replay** without one) restores them and resumes
+  polling if the computer was thinking.
+- [x] History responses are revalidated with `If-None-Match`; `ETag` and
+  `Content-Disposition` are exposed over CORS for the development setup,
+  where the web client and the API are on different ports.
 
 Constraints from the host's security headers:
 
@@ -128,20 +147,62 @@ Constraints from the host's security headers:
 
 Test gate:
 
-- [ ] Playwright (Chromium) end-to-end against server and PostgreSQL: play a
+- [x] Playwright (Chromium) end-to-end against server and PostgreSQL
-  short game, open My games, step backward and forward, autoplay to the end,
+  (`test/e2e`, run by the `e2e` CI job): play a short game, open My games,
-  and compare exported FEN/PGN with the API.
+  step backward and forward with buttons and keys, autoplay to the end,
-- [ ] Keyboard-only navigation and screen-reader labels; reduced-motion
+  compare the exported FEN and PGN with the API, download, copy a link,
-  disables autoplay animation.
+  browser back through replay and list; a deep link to a checkmate; the
-- [ ] Deep link works beneath `/projects/chess/` with the API at `/chess`.
+  device list for an anonymous visitor.
+- [x] Keyboard-only navigation and labels: every control is a button with a
+  name, the move list is a list of buttons, the current ply has
+  `aria-current` and is announced; `prefers-reduced-motion` disables the
+  client's animations and transitions (autoplay itself is user-initiated and
+  stays).
+- [x] Deep link: the client reads `?replay=` from its own URL, so it works
+  wherever the document is published (`/chess/web-client/` on lixen.com,
+  with the API at `/chess`); the old `/projects/chess/` path redirects there.
 
-## Phase R4 — CLI and WASM Replay (optional)
+## Phase R4 — CLI and WASM Replay — done
 
-- [x] `games` (list with cursor paging) and `pgn [gameId] [ply]`.
+- [x] `games` (list with cursor paging, numbered) and `pgn [gameId] [ply]`.
-- [ ] `replay <gameId|index>`, `next`, `prev`, `first`, `last`, `goto <ply>`,
+- [x] `replay <gameId|index>` (index into the last `games` page), `next`
-  `auto <ms>`, `fen`, `pgn save <path>`.
+  `prev` (`>` `<`, with a count), `first`, `last`, `goto <ply>`, `auto [ms]`,
-- [ ] Replay state is separate from the live session: no polling, moves, undo,
+  `fen`, `pgn [save <path>]` (the replayed game up to the current ply; in
-  or configuration while replaying.
+  the browser build the PGN is printed instead of saved), `live` to leave.
+- [x] Replay state is separate from the live session: `new`, `join`, `move`,
+  `computer`, `undo`, `delete`, `poll`, `resign` and `draw` are refused
+  while replaying, `show` shows the replayed position, and the prompt reads
+  `replay <ply>/<plies>`; `live` returns to the game as it was.
+
+Follow-up polish (done): the phone layout is full-width rows under the board
+(`svh` units, so the browser's bars never cover the controls; a replay
+reserves more height than live play), the turn strip says whose move it is in
+two words with the dot showing the side, the sign-in dialog keeps the focus in
+the password field after a wrong password, the brand mark is the site's
+bishop, and the terminal client pages long output (help, games, pgn, state,
+show, replay) one screen at a time, natively and in the browser.
+
+Later for the replay clients:
+
+- [ ] Web: an "Analysis" link on a replay (chess.com-style evaluation needs
+  an engine in the browser or a server endpoint; none exists).
+- [ ] CLI: `auto` cannot be interrupted before the end of the line.
+
+## Accounts
+
+- [x] Password recovery by email: `POST /api/auth/recover` sends a one-time
+  link (an hour, SHA-256 of the token stored in `password_resets`, schema
+  v4) to the account's address through an SMTP relay (`-smtp-host`, with
+  optional credentials over TLS) or, for development, a directory of `.eml`
+  files (`-mail-dir`); `POST /api/auth/reset` sets the password, ends the
+  account's other sessions and signs the person in; the web client offers
+  **Forgot password?** when `/health` reports `"mail": "ok"` and opens the
+  password form from `?reset=<token>`. `db user reset-link` prints the same
+  link for an administrator; `db user set-password` resets without one.
+- [ ] Deliver from the chess jail through the mail jail (devops): relay
+  address, sender, and `chessd_smtp_*` in `rc.conf` (deployment.md).
+- [ ] Email verification at registration and on `set-email`; today an
+  address is taken as typed, so a typo sends nobody a link.
 
 ## Phase R5 — Curated Archive (later)
 

go.mod

@@ -13,7 +13,7 @@ require (
 
 require (
 	github.com/clipperhouse/uax29/v2 v2.7.0 // indirect
-	github.com/gabriel-vasile/mimetype v1.4.15 // indirect
+	github.com/gabriel-vasile/mimetype v1.4.16 // indirect
 	github.com/go-playground/locales v0.14.2 // indirect
 	github.com/go-playground/universal-translator v0.18.2 // indirect
 	github.com/golang-jwt/jwt/v5 v5.3.1 // indirect
@@ -26,10 +26,10 @@ require (
 	github.com/mattn/go-isatty v0.0.24 // indirect
 	github.com/mattn/go-runewidth v0.0.31 // indirect
 	github.com/molecule-man/go-brrr v1.3.0 // indirect
-	github.com/philhofer/fwd v1.2.0 // indirect
+	github.com/philhofer/fwd v1.2.1 // indirect
 	github.com/tinylib/msgp v1.6.5 // indirect
 	github.com/valyala/bytebufferpool v1.0.0 // indirect
-	github.com/valyala/fasthttp v1.75.0 // indirect
+	github.com/valyala/fasthttp v1.76.0 // indirect
 	golang.org/x/crypto v0.58.0 // indirect
 	golang.org/x/sync v0.24.0 // indirect
 	golang.org/x/sys v0.49.0 // indirect

go.sum

@@ -3,8 +3,8 @@ github.com/clipperhouse/uax29/v2 v2.7.0/go.mod h1:EFJ2TJMRUaplDxHKj1qAEhCtQPW2tJ
 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
-github.com/gabriel-vasile/mimetype v1.4.15 h1:05iP/CYtZ/w455R/KZM6rZ5ieAdh99UPtd+d3YzLmaI=
+github.com/gabriel-vasile/mimetype v1.4.16 h1:5izNFuvA37st1dDRAcA7TtmngBmRgiIPDmTtiEvjx1E=
-github.com/gabriel-vasile/mimetype v1.4.15/go.mod h1:azpTcoLcDZRNgFou5j+APrqQx9HqVPWa6ijYQIIVswQ=
+github.com/gabriel-vasile/mimetype v1.4.16/go.mod h1:3oFFwxX8kTklZwzIl2aQEDZT0lKY8xH92ST88bAwba4=
 github.com/go-playground/assert/v2 v2.2.0 h1:JvknZsQTYeFEAhQwI4qEt9cyV5ONwRHC+lYKSsYSR8s=
 github.com/go-playground/assert/v2 v2.2.0/go.mod h1:VDjEfimB/XKnb+ZQfWdccd7VUvScMdVu0Titje2rxJ4=
 github.com/go-playground/locales v0.14.2 h1:d8UmcrM6Nip0hfGZKLGpAvZH37XB4TS0xzK9B56YNCY=
@@ -41,8 +41,8 @@ github.com/mattn/go-runewidth v0.0.31 h1:1oCV4ReTlosDBc6rYRw5cL8S/4y8iv5oRl4SJ5I
 github.com/mattn/go-runewidth v0.0.31/go.mod h1:3qAiGCV4Koz/yuveO58qUefmUTRm8r0IGEXZ9jeHp/8=
 github.com/molecule-man/go-brrr v1.3.0 h1:KEGPkUk9PYFw5+Sv/evCOSU5OmMDXCGFqQ9YjRB7GeU=
 github.com/molecule-man/go-brrr v1.3.0/go.mod h1:7ybW6/7gA3oKY45jOfVNjSJDtrr6ea4tzbsTkjmQDC4=
-github.com/philhofer/fwd v1.2.0 h1:e6DnBTl7vGY+Gz322/ASL4Gyp1FspeMvx1RNDoToZuM=
+github.com/philhofer/fwd v1.2.1 h1:UtpS73q8bFgy/yH3gCq8LSNvj5gv/FowNOiWZa7uKwQ=
-github.com/philhofer/fwd v1.2.0/go.mod h1:RqIHx9QI14HlwKwm98g9Re5prTQ6LdeRQn+gXJFxsJM=
+github.com/philhofer/fwd v1.2.1/go.mod h1:RqIHx9QI14HlwKwm98g9Re5prTQ6LdeRQn+gXJFxsJM=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
@@ -54,8 +54,8 @@ github.com/tinylib/msgp v1.6.5 h1:iAH6XTP7BpzErjBZlujJQXxA+GmRi2YWs6M4KdLtNbE=
 github.com/tinylib/msgp v1.6.5/go.mod h1:RSp0LW9oSxFut3KzESt5Voq4GVWyS+PSulT77roAqEA=
 github.com/valyala/bytebufferpool v1.0.0 h1:GqA5TC/0021Y/b9FG4Oi9Mr3q7XYx6KllzawFIhcdPw=
 github.com/valyala/bytebufferpool v1.0.0/go.mod h1:6bBcMArwyJ5K/AmCkWv1jt77kVWyCJ6HpOuEn7z0Csc=
-github.com/valyala/fasthttp v1.75.0 h1:W3xrvNJHG60j2ZCjxpP8kkB+oPG8kh9/g1n4+3xUwNA=
+github.com/valyala/fasthttp v1.76.0 h1:QitrT4foDQuqvUnr/hzmQUDbYzV12Zz4vkLOlipU4Cw=
-github.com/valyala/fasthttp v1.75.0/go.mod h1:JiVkPRZU124PuPsreV/s9dZRgG2lRK7wNEikdQ0Rk4s=
+github.com/valyala/fasthttp v1.76.0/go.mod h1:m8oTPC8riDDky07invpl+Gz3RixnAN5BbwyUuVB5H2o=
 golang.org/x/crypto v0.58.0 h1:COkYLr4k7nDI4r6QtMML2AfzeIswWHAJthLS6K/M/54=
 golang.org/x/crypto v0.58.0/go.mod h1:Xh+kl5A+M0gMiWDytH2Hhr5Z7WbNCpv/eB/EFgfSk+w=
 golang.org/x/sync v0.24.0 h1:iqiDrGoDgyuvAKrhLQthUEzU/R378N78gXbBjxed7oA=

internal/client/api/client.go

@@ -107,7 +107,7 @@ func (c *Client) doRequest(method, path string, body any, result any) error {
 	if resp.StatusCode >= 400 {
 		statusColor = display.Red
 	}
-	fmt.Printf("%s[%d %s]%s\n", statusColor, resp.StatusCode, http.StatusText(resp.StatusCode), display.Reset)
+	display.Printf("%s[%d %s]%s\n", statusColor, resp.StatusCode, http.StatusText(resp.StatusCode), display.Reset)
 
 	// Display response body if verbose
 	if c.Verbose && len(respBody) > 0 {

internal/client/api/types.go

@@ -45,6 +45,7 @@ type GameResponse struct {
 	DrawOutcome string          `json:"drawOutcome,omitempty"`
 	Concession  *Concession     `json:"concession,omitempty"`
 	Moves       []string        `json:"moves"`
+	SAN         []string        `json:"san"`
 	Players     PlayersResponse `json:"players"`
 	LastMove    *MoveInfo       `json:"lastMove,omitempty"`
 }
@@ -129,6 +130,7 @@ type GameHistoryResponse struct {
 	Termination  string          `json:"termination,omitempty"`
 	StartTimeUTC time.Time       `json:"startTimeUtc"`
 	EndTimeUTC   *time.Time      `json:"endTimeUtc,omitempty"`
+	Concession   *Concession     `json:"concession,omitempty"` // Result in stored form ("black_wins")
 	Players      PlayersResponse `json:"players"`
 	Moves        []HistoryMove   `json:"moves"`
 }
@@ -148,6 +150,7 @@ type GameSummary struct {
 	FinalFEN     string          `json:"finalFen"`
 	Result       string          `json:"result,omitempty"`
 	PGNResult    string          `json:"pgnResult"`
+	Termination  string          `json:"termination,omitempty"`
 	StartTimeUTC time.Time       `json:"startTimeUtc"`
 	EndTimeUTC   *time.Time      `json:"endTimeUtc,omitempty"`
 	MoveCount    int             `json:"moveCount"`

internal/client/command/auth.go

@@ -81,8 +81,8 @@ func registerHandler(s *session.Session, args []string) error {
 	c.SetToken(resp.Token)
 
 	display.Println(display.Green, "Registered successfully")
-	fmt.Printf("User ID: %s\n", resp.UserID)
+	display.Printf("User ID: %s\n", resp.UserID)
-	fmt.Printf("Username: %s\n", resp.Username)
+	display.Printf("Username: %s\n", resp.Username)
 
 	return nil
 }
@@ -111,8 +111,8 @@ func loginHandler(s *session.Session, args []string) error {
 	c.SetToken(resp.Token)
 
 	display.Println(display.Green, "Logged in successfully")
-	fmt.Printf("User ID: %s\n", resp.UserID)
+	display.Printf("User ID: %s\n", resp.UserID)
-	fmt.Printf("Username: %s\n", resp.Username)
+	display.Printf("Username: %s\n", resp.Username)
 
 	return nil
 }
@@ -151,14 +151,14 @@ func whoamiHandler(s *session.Session, args []string) error {
 	}
 
 	display.Println(display.Cyan, "Current User:")
-	fmt.Printf("  User ID:  %s\n", user.UserID)
+	display.Printf("  User ID:  %s\n", user.UserID)
-	fmt.Printf("  Username: %s\n", user.Username)
+	display.Printf("  Username: %s\n", user.Username)
 	if user.Email != "" {
-		fmt.Printf("  Email:    %s\n", user.Email)
+		display.Printf("  Email:    %s\n", user.Email)
 	}
-	fmt.Printf("  Created:  %s\n", user.CreatedAt.Format("2006-01-02 15:04:05"))
+	display.Printf("  Created:  %s\n", user.CreatedAt.Format("2006-01-02 15:04:05"))
 	if user.LastLogin != nil {
-		fmt.Printf("  Last Login: %s\n", user.LastLogin.Format("2006-01-02 15:04:05"))
+		display.Printf("  Last Login: %s\n", user.LastLogin.Format("2006-01-02 15:04:05"))
 	}
 
 	return nil
@@ -172,7 +172,7 @@ func setUserHandler(s *session.Session, args []string) error {
 	userID := args[0]
 	s.SetCurrentUser(userID)
 	display.Println(display.Cyan, "User ID set to: %s", userID)
-	fmt.Println("Note: This doesn't authenticate, just sets the ID for display")
+	display.Line("Note: This doesn't authenticate, just sets the ID for display")
 
 	return nil
 }

internal/client/command/debug.go

@@ -44,12 +44,12 @@ func healthHandler(s *session.Session, args []string) error {
 	}
 
 	display.Println(display.Cyan, "Server Health:")
-	fmt.Printf("  Status:  %s\n", resp.Status)
+	display.Printf("  Status:  %s\n", resp.Status)
 	// Convert Unix timestamp to readable time
 	t := time.Unix(resp.Time, 0)
-	fmt.Printf("  Time:    %s\n", t.Format("2006-01-02 15:04:05"))
+	display.Printf("  Time:    %s\n", t.Format("2006-01-02 15:04:05"))
 	if resp.Storage != "" {
-		fmt.Printf("  Storage: %s\n", resp.Storage)
+		display.Printf("  Storage: %s\n", resp.Storage)
 	}
 
 	return nil
@@ -57,7 +57,7 @@ func healthHandler(s *session.Session, args []string) error {
 
 func urlHandler(s *session.Session, args []string) error {
 	if len(args) == 0 {
-		fmt.Printf("Current API URL: %s\n", s.GetAPIBaseURL())
+		display.Printf("Current API URL: %s\n", s.GetAPIBaseURL())
 		return nil
 	}
 

internal/client/command/game.go

@@ -59,6 +59,7 @@ func (r *Registry) registerGameCommands() {
 		Description: "Show board and game state",
 		Usage:       "show",
 		Handler:     showBoardHandler,
+		Paged:       true,
 	})
 
 	r.Register(&Command{
@@ -67,6 +68,7 @@ func (r *Registry) registerGameCommands() {
 		Description: "Show raw game JSON",
 		Usage:       "state",
 		Handler:     gameStateHandler,
+		Paged:       true,
 	})
 
 	r.Register(&Command{
@@ -99,14 +101,16 @@ func (r *Registry) registerGameCommands() {
 		Description: "List your stored games, newest first (login required)",
 		Usage:       "games [more]",
 		Handler:     gamesHandler,
+		Paged:       true,
 	})
 
 	r.Register(&Command{
 		Name:        "pgn",
 		ShortName:   "",
-		Description: "Print a stored game as PGN",
+		Description: "Print or save a stored game as PGN",
-		Usage:       "pgn [gameId] [ply]  (default: current game, all plies)",
+		Usage:       "pgn [gameId] [ply] [save <path>]  (default: current or replayed game)",
 		Handler:     pgnHandler,
+		Paged:       true,
 	})
 
 	r.Register(&Command{
@@ -259,8 +263,8 @@ func joinGameHandler(s *session.Session, args []string) error {
 		}
 	}
 
-	fmt.Printf("%sJoined game: %s%s\n", display.Green, gameID, display.Reset)
+	display.Printf("%sJoined game: %s%s\n", display.Green, gameID, display.Reset)
-	fmt.Printf("Turn: %s | State: %s | Moves: %d\n", resp.Turn, resp.State, len(resp.Moves))
+	display.Printf("Turn: %s | State: %s | Moves: %d\n", resp.Turn, resp.State, len(resp.Moves))
 
 	return nil
 }
@@ -368,9 +372,9 @@ func computerMoveHandler(s *session.Session, args []string) error {
 	if final.LastMove != nil && len(final.Moves) > baselineMoves {
 		display.Print(display.Magenta, "Computer played: %s", final.LastMove.Move)
 		if final.LastMove.Depth > 0 {
-			fmt.Printf(" (depth %d, score %d)", final.LastMove.Depth, final.LastMove.Score)
+			display.Printf(" (depth %d, score %d)", final.LastMove.Depth, final.LastMove.Score)
 		}
-		fmt.Println()
+		display.Line()
 	}
 
 	printOutcome(final)
@@ -520,6 +524,9 @@ func undoHandler(s *session.Session, args []string) error {
 }
 
 func showBoardHandler(s *session.Session, args []string) error {
+	if s.Replay != nil {
+		return showReplayPosition(s)
+	}
 	gameID := s.GetCurrentGame()
 	if gameID == "" {
 		return fmt.Errorf("no current game, use 'new' or 'join <gameId>'")
@@ -543,28 +550,28 @@ func showBoardHandler(s *session.Session, args []string) error {
 	s.SetGameState(game)
 
 	// Display board with colors
-	fmt.Println()
+	display.Line()
 	display.RenderBoard(board.Board)
 
 	// Display game info
-	fmt.Printf("\nFEN: %s\n", game.FEN)
+	display.Printf("\nFEN: %s\n", game.FEN)
-	fmt.Printf("Turn: %s | State: %s | Moves: %d\n",
+	display.Printf("Turn: %s | State: %s | Moves: %d\n",
 		display.ColorForTurn(game.Turn), game.State, len(game.Moves))
 
 	// Display move history
 	if len(game.Moves) > 0 {
-		fmt.Printf("\nHistory: ")
+		display.Printf("\nHistory: ")
 		for i, move := range game.Moves {
 			if i > 0 {
-				fmt.Print(" ")
+				display.Write(" ")
 			}
 			if i%2 == 0 {
-				fmt.Printf("%d.%s", (i/2)+1, move)
+				display.Printf("%d.%s", (i/2)+1, move)
 			} else {
-				fmt.Printf(" %s", move)
+				display.Printf(" %s", move)
 			}
 		}
-		fmt.Println()
+		display.Line()
 	}
 
 	// Display last move info
@@ -573,11 +580,11 @@ func showBoardHandler(s *session.Session, args []string) error {
 		if game.LastMove.PlayerColor == "b" {
 			color = "Black"
 		}
-		fmt.Printf("Last move: %s by %s", game.LastMove.Move, color)
+		display.Printf("Last move: %s by %s", game.LastMove.Move, color)
 		if game.LastMove.Depth > 0 {
-			fmt.Printf(" (depth %d, score %d)", game.LastMove.Depth, game.LastMove.Score)
+			display.Printf(" (depth %d, score %d)", game.LastMove.Depth, game.LastMove.Score)
 		}
-		fmt.Println()
+		display.Line()
 	}
 	printOutcome(game)
 	printConcession(game)
@@ -627,7 +634,7 @@ func deleteGameHandler(s *session.Session, args []string) error {
 		s.SetLastMoveCount(0)
 	}
 
-	fmt.Printf("%sLive game unloaded (history retained): %s%s\n", display.Green, gameID, display.Reset)
+	display.Printf("%sLive game unloaded (history retained): %s%s\n", display.Green, gameID, display.Reset)
 	return nil
 }
 
@@ -658,7 +665,7 @@ func pollHandler(s *session.Session, args []string) error {
 	case len(resp.Moves) > moveCount:
 		display.Println(display.Green, "Game updated! New moves detected")
 		if resp.LastMove != nil {
-			fmt.Printf("Last move: %s\n", resp.LastMove.Move)
+			display.Printf("Last move: %s\n", resp.LastMove.Move)
 		}
 	case len(resp.Moves) < moveCount:
 		display.Println(display.Green, "Game updated: %d move(s) taken back", moveCount-len(resp.Moves))
@@ -692,19 +699,21 @@ func gamesHandler(s *session.Session, args []string) error {
 		return err
 	}
 	s.GamesCursor = resp.NextCursor
+	s.GamesPage = resp.Games
 	if len(resp.Games) == 0 {
 		display.Println(display.Yellow, "No stored games")
 		return nil
 	}
 
-	fmt.Printf("\n%-36s  %-20s  %-20s  %-7s  %5s  %s\n", "Game ID", "White", "Black", "Result", "Plies", "Started (UTC)")
+	display.Printf("\n%3s  %-36s  %-20s  %-20s  %-7s  %5s  %s\n", "#", "Game ID", "White", "Black", "Result", "Plies", "Started (UTC)")
-	for _, g := range resp.Games {
+	for i, g := range resp.Games {
-		fmt.Printf("%-36s  %-20s  %-20s  %-7s  %5d  %s\n", g.GameID,
+		display.Printf("%3d  %-36s  %-20s  %-20s  %-7s  %5d  %s\n", i+1, g.GameID,
 			playerLabel(g.Players.White), playerLabel(g.Players.Black), g.PGNResult, g.MoveCount,
 			g.StartTimeUTC.UTC().Format("2006-01-02 15:04"))
 	}
+	display.Println(display.Cyan, "\nReplay one: replay <#> or replay <gameId>")
 	if resp.NextCursor != "" {
-		display.Println(display.Cyan, "\nMore games: games more")
+		display.Println(display.Cyan, "More games: games more")
 	}
 	return nil
 }
@@ -720,9 +729,21 @@ func playerLabel(p api.PlayerInfo) string {
 }
 
 // pgnHandler prints the stored game as PGN: the current game unless an ID is
-// given, and every ply unless a count is given.
+// given, and every ply unless a count is given. During a replay the default
+// is the replayed game up to the current ply. "save <path>" writes the
+// export to a file instead of printing it.
 func pgnHandler(s *session.Session, args []string) error {
+	path, args, err := pgnSaveArgs(args)
+	if err != nil {
+		return err
+	}
 	gameID, ply := s.CurrentGame, -1
+	if s.Replay != nil {
+		gameID = s.Replay.History.GameID
+		if !s.Replay.AtEnd() {
+			ply = s.Replay.Ply
+		}
+	}
 	for _, arg := range args {
 		if n, err := strconv.Atoi(arg); err == nil && n >= 0 {
 			ply = n
@@ -737,7 +758,14 @@ func pgnHandler(s *session.Session, args []string) error {
 	if err != nil {
 		return err
 	}
-	fmt.Println()
+	if path != "" {
-	fmt.Print(text)
+		if err := savePGN(path, trimPGN(text)); err != nil {
+			return err
+		}
+		display.Println(display.Green, "Saved PGN of %s to %s", describePGNTarget(gameID, ply), path)
+		return nil
+	}
+	display.Line()
+	display.Write(text)
 	return nil
 }

internal/client/command/pass_native.go

@@ -3,15 +3,15 @@
 package command
 
 import (
-	"fmt"
+	"github.com/lixenwraith/chess/internal/client/display"
 
 	"golang.org/x/term"
 )
 
 func readPassword(prompt string) (string, error) {
-	fmt.Print(prompt)
+	display.Write(prompt)
 	bytePassword, err := term.ReadPassword(0) // 0 is stdin
-	fmt.Println()
+	display.Line()
 	if err != nil {
 		return "", err
 	}

internal/client/command/registry.go

@@ -1,6 +1,7 @@
 package command
 
 import (
+	"bytes"
 	"fmt"
 	"strings"
 
@@ -16,6 +17,9 @@ type Command struct {
 	Description string
 	Usage       string
 	Handler     func(*session.Session, []string) error
+	// Paged commands print at length and read nothing: their output is
+	// shown one screen at a time (display.Page).
+	Paged bool
 }
 
 type Registry struct {
@@ -32,6 +36,7 @@ func NewRegistry(s *session.Session) *Registry {
 
 	// Register all commands
 	r.registerGameCommands()
+	r.registerReplayCommands()
 	r.registerAuthCommands()
 	r.registerDebugCommands()
 
@@ -42,6 +47,7 @@ func NewRegistry(s *session.Session) *Registry {
 		Description: "Show available commands",
 		Usage:       "help [command]",
 		Handler:     r.helpHandler,
+		Paged:       true,
 	})
 
 	// Exit command (handled in main loop, but registered for help display)
@@ -78,12 +84,28 @@ func (r *Registry) Execute(input string) {
 		display.Println(display.Reset, "Type 'help' for available commands")
 		return
 	}
+	if r.session.Replay != nil && liveOnly[cmd.Name] {
+		display.Println(display.Red, "'%s' is not available while replaying; 'live' returns to the live session", cmd.Name)
+		return
+	}
 
 	// Set verbose mode in client if session supports it
 	if cl, ok := r.session.GetClient().(*api.Client); ok {
 		cl.SetVerbose(r.session.IsVerbose())
 	}
 
+	if cmd.Paged && r.session.ReadLine != nil {
+		var buf bytes.Buffer
+		previous := display.Out
+		display.Out = &buf
+		err := cmd.Handler(r.session, args)
+		display.Out = previous
+		display.Page(buf.String(), r.session.ReadLine)
+		if err != nil {
+			display.Println(display.Red, "Error: %s", err.Error())
+		}
+		return
+	}
 	if err := cmd.Handler(r.session, args); err != nil {
 		display.Println(display.Red, "Error: %s", err.Error())
 	}
@@ -96,13 +118,13 @@ func (r *Registry) helpHandler(s *session.Session, args []string) error {
 		if !exists {
 			return fmt.Errorf("unknown command: %s", args[0])
 		}
-		fmt.Println()
+		display.Line()
 		display.Print(display.Cyan, cmd.Name)
 		display.Println(display.Reset, " - %s", cmd.Description)
 		if cmd.ShortName != "" {
 			display.Println(display.Cyan, "Short form: %s", cmd.ShortName)
 		}
-		fmt.Printf("Usage: %s\n", cmd.Usage)
+		display.Printf("Usage: %s\n", cmd.Usage)
 		return nil
 	}
 
@@ -132,6 +154,18 @@ func (r *Registry) helpHandler(s *session.Session, args []string) error {
 		{"pgn", "", ""},
 	}
 
+	replayCommands := []cmdInfo{
+		{"replay", "", ""},
+		{"next", ">", ""},
+		{"prev", "<", ""},
+		{"first", "", ""},
+		{"last", "", ""},
+		{"goto", "", ""},
+		{"auto", "", ""},
+		{"fen", "", ""},
+		{"live", "", ""},
+	}
+
 	authCommands := []cmdInfo{
 		{"register", "r", ""},
 		{"login", "l", ""},
@@ -156,18 +190,20 @@ func (r *Registry) helpHandler(s *session.Session, args []string) error {
 				if info.shortName != "" {
 					shortPart = fmt.Sprintf("[%s%s%s] ", display.Cyan, info.shortName, display.Reset)
 				}
-				fmt.Printf("  %s%-10s %s\n", shortPart, cmd.Name, cmd.Description)
+				display.Printf("  %s%-10s %s\n", shortPart, cmd.Name, cmd.Description)
 			}
 		}
-		fmt.Println()
+		display.Line()
 	}
 
 	printCommandGroup("Game Commands", gameCommands)
+	printCommandGroup("Replay Commands", replayCommands)
 	printCommandGroup("Auth Commands", authCommands)
 	printCommandGroup("Utility Commands", utilCommands)
 
 	display.Println(display.Reset, "Type 'help <command>' for detailed usage")
-	display.Println(display.Reset, "Add '-v' to any command for verbose output\n")
+	display.Println(display.Reset, "Add '-v' to any command for verbose output")
+	display.Println(display.Reset, "Long output pauses after each screen: Enter continues, q stops\n")
 	return nil
 }
 

internal/client/command/replay.go

@@ -0,0 +1,290 @@
+package command
+
+import (
+	"fmt"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/lixenwraith/chess/internal/client/display"
+	"github.com/lixenwraith/chess/internal/client/replay"
+	"github.com/lixenwraith/chess/internal/client/session"
+)
+
+// Replay commands step through a stored game from its history. The replay
+// state lives beside the live session, which keeps its game, user and poll
+// position; live commands that would change the game are refused until
+// 'live' ends the replay (see liveOnly).
+func (r *Registry) registerReplayCommands() {
+	r.Register(&Command{
+		Name:        "replay",
+		ShortName:   "",
+		Description: "Step through a stored game",
+		Usage:       "replay <gameId|index>  (index from the last 'games' listing)",
+		Handler:     replayHandler,
+		Paged:       true,
+	})
+	r.Register(&Command{
+		Name:        "next",
+		ShortName:   ">",
+		Description: "Replay: next ply",
+		Usage:       "next [count]",
+		Handler:     stepHandler(1),
+	})
+	r.Register(&Command{
+		Name:        "prev",
+		ShortName:   "<",
+		Description: "Replay: previous ply",
+		Usage:       "prev [count]",
+		Handler:     stepHandler(-1),
+	})
+	r.Register(&Command{
+		Name:        "first",
+		ShortName:   "",
+		Description: "Replay: initial position",
+		Usage:       "first",
+		Handler: func(s *session.Session, args []string) error {
+			return gotoHandler(s, []string{"0"})
+		},
+	})
+	r.Register(&Command{
+		Name:        "last",
+		ShortName:   "",
+		Description: "Replay: final position",
+		Usage:       "last",
+		Handler: func(s *session.Session, args []string) error {
+			if s.Replay == nil {
+				return errNotReplaying
+			}
+			return gotoHandler(s, []string{strconv.Itoa(s.Replay.Len())})
+		},
+	})
+	r.Register(&Command{
+		Name:        "goto",
+		ShortName:   "",
+		Description: "Replay: show the position after N plies",
+		Usage:       "goto <ply>",
+		Handler:     gotoHandler,
+	})
+	r.Register(&Command{
+		Name:        "auto",
+		ShortName:   "",
+		Description: "Replay: play forward to the end",
+		Usage:       "auto [ms]  (delay per ply, default 1000)",
+		Handler:     autoHandler,
+	})
+	r.Register(&Command{
+		Name:        "fen",
+		ShortName:   "",
+		Description: "Replay: print the FEN of the current position",
+		Usage:       "fen",
+		Handler:     fenHandler,
+	})
+	r.Register(&Command{
+		Name:        "live",
+		ShortName:   "",
+		Description: "Leave the replay and return to the live session",
+		Usage:       "live",
+		Handler:     liveHandler,
+	})
+}
+
+var errNotReplaying = fmt.Errorf("no replay in progress; use 'replay <gameId|index>'")
+
+// liveOnly names the commands a replay refuses: they would change the live
+// game or poll it, while a replay only reads a stored one.
+var liveOnly = map[string]bool{
+	"new": true, "join": true, "move": true, "computer": true, "undo": true,
+	"delete": true, "poll": true, "resign": true, "draw": true,
+}
+
+// replayHandler loads a stored game by ID, or by its position in the last
+// 'games' listing, and shows its initial position.
+func replayHandler(s *session.Session, args []string) error {
+	if len(args) < 1 {
+		return fmt.Errorf("usage: replay <gameId|index>")
+	}
+	gameID := args[0]
+	if index, err := strconv.Atoi(gameID); err == nil {
+		if index < 1 || index > len(s.GamesPage) {
+			if len(s.GamesPage) == 0 {
+				return fmt.Errorf("no listing to index; run 'games' first or give a game ID")
+			}
+			return fmt.Errorf("index %d is outside the last listing (1-%d)", index, len(s.GamesPage))
+		}
+		gameID = s.GamesPage[index-1].GameID
+	}
+
+	history, err := s.Client.GetGameHistory(gameID)
+	if err != nil {
+		return err
+	}
+	s.Replay = replay.New(history)
+
+	white, black := s.Replay.Players()
+	display.Println(display.Cyan, "\nReplaying %s", history.GameID)
+	display.Printf("%s vs %s  ·  %s  ·  %d plies  ·  started %s\n",
+		display.C(display.Blue, white), display.C(display.Red, black), s.Replay.Result(), s.Replay.Len(),
+		history.StartTimeUTC.UTC().Format("2006-01-02 15:04"))
+	if c := history.Concession; c != nil {
+		what := "a draw was agreed"
+		switch c.Result {
+		case "white_wins":
+			what = "Black resigned"
+		case "black_wins":
+			what = "White resigned"
+		}
+		display.Println(display.Yellow, "%s at ply %d; play continued.", what, c.Ply)
+	}
+	display.Line()
+	display.Line(s.Replay.Movetext(80))
+	display.Println(display.Reset, "\nnext, prev, first, last, goto <ply>, auto [ms], fen, pgn [save <path>], live")
+	return showReplayPosition(s)
+}
+
+func stepHandler(direction int) func(*session.Session, []string) error {
+	return func(s *session.Session, args []string) error {
+		if s.Replay == nil {
+			return errNotReplaying
+		}
+		count := 1
+		if len(args) > 0 {
+			n, err := strconv.Atoi(args[0])
+			if err != nil || n < 1 {
+				return fmt.Errorf("invalid count: %s", args[0])
+			}
+			count = n
+		}
+		before := s.Replay.Ply
+		s.Replay.Goto(before + direction*count)
+		if s.Replay.Ply == before {
+			if direction > 0 {
+				display.Println(display.Yellow, "At the end of the game")
+			} else {
+				display.Println(display.Yellow, "At the initial position")
+			}
+		}
+		return showReplayPosition(s)
+	}
+}
+
+func gotoHandler(s *session.Session, args []string) error {
+	if s.Replay == nil {
+		return errNotReplaying
+	}
+	if len(args) < 1 {
+		return fmt.Errorf("usage: goto <ply> (0-%d)", s.Replay.Len())
+	}
+	ply, err := strconv.Atoi(args[0])
+	if err != nil {
+		return fmt.Errorf("invalid ply: %s", args[0])
+	}
+	if ply < 0 || ply > s.Replay.Len() {
+		return fmt.Errorf("ply %d is outside 0-%d", ply, s.Replay.Len())
+	}
+	s.Replay.Goto(ply)
+	return showReplayPosition(s)
+}
+
+// autoHandler plays forward from the current ply to the end, one board per
+// ply, pausing between them.
+func autoHandler(s *session.Session, args []string) error {
+	if s.Replay == nil {
+		return errNotReplaying
+	}
+	delay := 1000
+	if len(args) > 0 {
+		n, err := strconv.Atoi(args[0])
+		if err != nil || n < 0 || n > 60000 {
+			return fmt.Errorf("delay must be 0-60000 ms")
+		}
+		delay = n
+	}
+	if s.Replay.AtEnd() {
+		display.Println(display.Yellow, "At the end of the game; 'first' to start over")
+		return nil
+	}
+	for !s.Replay.AtEnd() {
+		time.Sleep(time.Duration(delay) * time.Millisecond)
+		s.Replay.Next()
+		if err := showReplayPosition(s); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func fenHandler(s *session.Session, args []string) error {
+	if s.Replay == nil {
+		return errNotReplaying
+	}
+	display.Line(s.Replay.FEN())
+	return nil
+}
+
+func liveHandler(s *session.Session, args []string) error {
+	if s.Replay == nil {
+		display.Println(display.Yellow, "Not replaying")
+		return nil
+	}
+	s.Replay = nil
+	display.Println(display.Green, "Back to the live session")
+	if s.CurrentGame != "" {
+		display.Println(display.Cyan, "Current game: %s", s.CurrentGame)
+	}
+	return nil
+}
+
+// showReplayPosition prints the board at the current ply with its label.
+func showReplayPosition(s *session.Session) error {
+	r := s.Replay
+	board, err := display.BoardFromFEN(r.FEN())
+	if err != nil {
+		return fmt.Errorf("stored position cannot be shown: %w", err)
+	}
+	display.Line()
+	display.RenderBoard(board)
+	label := r.Label(r.Ply)
+	if r.Ply == 0 {
+		label = "initial position"
+	}
+	display.Printf("\nPly %d/%d  %s\n", r.Ply, r.Len(), display.C(display.Cyan, label))
+	if r.AtEnd() && r.History.Result != "" {
+		display.Println(display.Green, "Result: %s", r.Result())
+	}
+	return nil
+}
+
+// replayPrompt is the prompt segment while replaying.
+func ReplayPrompt(s *session.Session) string {
+	if s.Replay == nil {
+		return ""
+	}
+	return fmt.Sprintf(" replay %d/%d", s.Replay.Ply, s.Replay.Len())
+}
+
+// pgnSaveArgs splits "pgn save <path> [gameId] [ply]" style arguments:
+// a "save" followed by a path, and the remaining arguments.
+func pgnSaveArgs(args []string) (path string, rest []string, err error) {
+	for i, arg := range args {
+		if arg == "save" {
+			if i+1 >= len(args) {
+				return "", nil, fmt.Errorf("usage: pgn save <path>")
+			}
+			rest = append(append([]string{}, args[:i]...), args[i+2:]...)
+			return args[i+1], rest, nil
+		}
+	}
+	return "", args, nil
+}
+
+func describePGNTarget(gameID string, ply int) string {
+	if ply >= 0 {
+		return fmt.Sprintf("%s (first %d plies)", gameID, ply)
+	}
+	return gameID
+}
+
+func trimPGN(text string) string {
+	return strings.TrimRight(text, "\n") + "\n"
+}

internal/client/command/replay_test.go

@@ -0,0 +1,64 @@
+package command
+
+import (
+	"testing"
+
+	"github.com/lixenwraith/chess/internal/client/api"
+	"github.com/lixenwraith/chess/internal/client/replay"
+	"github.com/lixenwraith/chess/internal/client/session"
+)
+
+func TestPGNSaveArgs(t *testing.T) {
+	for name, tc := range map[string]struct {
+		args []string
+		path string
+		rest []string
+		err  bool
+	}{
+		"none":         {[]string{"abc", "3"}, "", []string{"abc", "3"}, false},
+		"save last":    {[]string{"abc", "save", "out.pgn"}, "out.pgn", []string{"abc"}, false},
+		"save first":   {[]string{"save", "out.pgn", "abc", "3"}, "out.pgn", []string{"abc", "3"}, false},
+		"missing path": {[]string{"save"}, "", nil, true},
+	} {
+		path, rest, err := pgnSaveArgs(tc.args)
+		if (err != nil) != tc.err || path != tc.path || len(rest) != len(tc.rest) {
+			t.Errorf("%s: path %q rest %v err %v", name, path, rest, err)
+			continue
+		}
+		for i := range rest {
+			if rest[i] != tc.rest[i] {
+				t.Errorf("%s: rest = %v, want %v", name, rest, tc.rest)
+			}
+		}
+	}
+}
+
+func TestReplayRefusesLiveCommandsAndPrompt(t *testing.T) {
+	s := &session.Session{APIBaseURL: "http://127.0.0.1:1", Client: api.New("http://127.0.0.1:1")}
+	r := NewRegistry(s)
+	if ReplayPrompt(s) != "" {
+		t.Error("prompt segment while live")
+	}
+	s.Replay = replay.New(&api.GameHistoryResponse{
+		GameID: "g", InitialFEN: "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1",
+		Moves: []api.HistoryMove{{MoveNumber: 1, MoveUCI: "e2e4", SAN: "e4", FENAfterMove: "rnbqkbnr/pppppppp/8/8/4P3/8/PPPP1PPP/RNBQKBNR b KQkq - 0 1", PlayerColor: "w"}},
+	})
+	if got := ReplayPrompt(s); got != " replay 0/1" {
+		t.Errorf("prompt segment = %q", got)
+	}
+	// A live command is refused without touching the client (no server).
+	r.Execute("move e2e4")
+	r.Execute("next")
+	if s.Replay.Ply != 1 || ReplayPrompt(s) != " replay 1/1" {
+		t.Errorf("after next: ply %d", s.Replay.Ply)
+	}
+	r.Execute("live")
+	if s.Replay != nil {
+		t.Error("live did not end the replay")
+	}
+	for _, name := range []string{"new", "join", "move", "computer", "undo", "delete", "poll", "resign", "draw"} {
+		if !liveOnly[name] {
+			t.Errorf("%s is not refused while replaying", name)
+		}
+	}
+}

internal/client/command/save_native.go

@@ -0,0 +1,10 @@
+//go:build !js && !wasm
+
+package command
+
+import "os"
+
+// savePGN writes a PGN export to path.
+func savePGN(path, text string) error {
+	return os.WriteFile(path, []byte(text), 0o644)
+}

internal/client/command/save_wasm.go

@@ -0,0 +1,16 @@
+//go:build js && wasm
+
+package command
+
+import (
+	"fmt"
+
+	"github.com/lixenwraith/chess/internal/client/display"
+)
+
+// savePGN has no file system in the browser: the PGN is printed instead,
+// to be copied from the terminal.
+func savePGN(path, text string) error {
+	display.Write(text)
+	return fmt.Errorf("files cannot be saved from the browser; the PGN is printed above")
+}

internal/client/display/board.go

@@ -40,7 +40,7 @@ func RenderBoard(asciiBoard string) {
 				Print(Reset, "%c", char)
 			}
 		}
-		fmt.Println()
+		fmt.Fprintln(Out)
 	}
 }
 

internal/client/display/colors.go

@@ -24,12 +24,12 @@ func C(color, text string) string {
 
 // Print outputs colored text immediately
 func Print(color, format string, args ...any) {
-	fmt.Printf(C(color, format), args...)
+	fmt.Fprintf(Out, C(color, format), args...)
 }
 
 // Println outputs colored text with newline
 func Println(color, format string, args ...any) {
-	fmt.Println(C(color, fmt.Sprintf(format, args...)))
+	fmt.Fprintln(Out, C(color, fmt.Sprintf(format, args...)))
 }
 
 // Build creates a multi-colored string

internal/client/display/fen.go

@@ -0,0 +1,50 @@
+package display
+
+import (
+	"fmt"
+	"strings"
+)
+
+// BoardFromFEN renders a FEN's piece placement in the server's ASCII board
+// format (files on the first and last lines, ranks at both ends of a row,
+// "." for an empty square), so RenderBoard colors it the same way.
+func BoardFromFEN(fen string) (string, error) {
+	fields := strings.Fields(fen)
+	if len(fields) == 0 {
+		return "", fmt.Errorf("empty FEN")
+	}
+	rows := strings.Split(fields[0], "/")
+	if len(rows) != 8 {
+		return "", fmt.Errorf("FEN has %d ranks, want 8", len(rows))
+	}
+	var b strings.Builder
+	b.WriteString("  a b c d e f g h\n")
+	for i, row := range rows {
+		rank := byte('8' - i)
+		b.WriteByte(rank)
+		b.WriteByte(' ')
+		files := 0
+		for _, c := range row {
+			switch {
+			case c >= '1' && c <= '8':
+				for n := 0; n < int(c-'0'); n++ {
+					b.WriteString(". ")
+				}
+				files += int(c - '0')
+			case strings.ContainsRune("pnbrqkPNBRQK", c):
+				b.WriteRune(c)
+				b.WriteByte(' ')
+				files++
+			default:
+				return "", fmt.Errorf("invalid FEN character %q", c)
+			}
+		}
+		if files != 8 {
+			return "", fmt.Errorf("rank %c has %d files, want 8", rank, files)
+		}
+		b.WriteByte(rank)
+		b.WriteByte('\n')
+	}
+	b.WriteString("  a b c d e f g h")
+	return b.String(), nil
+}

internal/client/display/fen_test.go

@@ -0,0 +1,28 @@
+package display
+
+import "testing"
+
+func TestBoardFromFEN(t *testing.T) {
+	got, err := BoardFromFEN("rnbqkbnr/pppppppp/8/8/4P3/8/PPPP1PPP/RNBQKBNR b KQkq e3 0 1")
+	if err != nil {
+		t.Fatal(err)
+	}
+	want := "  a b c d e f g h\n" +
+		"8 r n b q k b n r 8\n" +
+		"7 p p p p p p p p 7\n" +
+		"6 . . . . . . . . 6\n" +
+		"5 . . . . . . . . 5\n" +
+		"4 . . . . P . . . 4\n" +
+		"3 . . . . . . . . 3\n" +
+		"2 P P P P . P P P 2\n" +
+		"1 R N B Q K B N R 1\n" +
+		"  a b c d e f g h"
+	if got != want {
+		t.Errorf("board:\n%s\nwant:\n%s", got, want)
+	}
+	for _, bad := range []string{"", "8/8/8/8/8/8/8 w - - 0 1", "9/8/8/8/8/8/8/8 w - - 0 1", "x7/8/8/8/8/8/8/8 w - - 0 1"} {
+		if _, err := BoardFromFEN(bad); err == nil {
+			t.Errorf("BoardFromFEN(%q) accepted", bad)
+		}
+	}
+}

internal/client/display/format.go

@@ -12,5 +12,5 @@ func PrettyPrintJSON(v any) {
 		Print(Red, "Error formatting JSON: %s\n", err.Error())
 		return
 	}
-	fmt.Println(string(data))
+	fmt.Fprintln(Out, string(data))
 }

internal/client/display/output.go

@@ -0,0 +1,79 @@
+package display
+
+import (
+	"fmt"
+	"io"
+	"os"
+	"regexp"
+	"strings"
+	"unicode/utf8"
+)
+
+// Out receives everything the client prints. A paged command runs with Out
+// swapped for a buffer, which Page then shows one screen at a time.
+var Out io.Writer = os.Stdout
+
+// Printf, Line and Write are fmt.Printf, fmt.Println and fmt.Print to Out.
+func Printf(format string, args ...any) { fmt.Fprintf(Out, format, args...) }
+func Line(args ...any)                  { fmt.Fprintln(Out, args...) }
+func Write(args ...any)                 { fmt.Fprint(Out, args...) }
+
+var ansiPattern = regexp.MustCompile("\x1b\\[[0-9;?]*[ -/]*[@-~]")
+
+// TermSize returns the terminal's rows and columns, or zeros when the output
+// is not a terminal (then nothing is paged). Platform files set it.
+var TermSize = func() (rows, cols int) { return 0, 0 }
+
+// Page prints text to Out one screen at a time. After each full screen it
+// asks to continue; readLine supplies the answer (an empty line continues,
+// "q" stops). Without a terminal, or when the text fits, it prints at once.
+func Page(text string, readLine func() (string, bool)) {
+	rows, cols := TermSize()
+	lines := strings.Split(strings.TrimRight(text, "\n"), "\n")
+	if rows < 4 || readLine == nil || visualRows(lines, cols) <= rows-1 {
+		if text != "" {
+			fmt.Fprint(Out, strings.TrimRight(text, "\n")+"\n")
+		}
+		return
+	}
+	pageRows := rows - 1 // one line for the prompt
+	used, i := 0, 0
+	for i < len(lines) {
+		need := wrappedRows(lines[i], cols)
+		if used > 0 && used+need > pageRows {
+			remaining := len(lines) - i
+			fmt.Fprintf(Out, "%s-- More (%d lines left; Enter continues, q quits) --%s", Yellow, remaining, Reset)
+			answer, ok := readLine()
+			// Clear the prompt and the echoed answer line.
+			fmt.Fprint(Out, "\r\x1b[2K\x1b[1A\r\x1b[2K")
+			if !ok || strings.HasPrefix(strings.ToLower(strings.TrimSpace(answer)), "q") {
+				return
+			}
+			used = 0
+			continue
+		}
+		fmt.Fprintln(Out, lines[i])
+		used += need
+		i++
+	}
+}
+
+func visualRows(lines []string, cols int) int {
+	total := 0
+	for _, line := range lines {
+		total += wrappedRows(line, cols)
+	}
+	return total
+}
+
+// wrappedRows is how many terminal rows a line takes, ignoring colour codes.
+func wrappedRows(line string, cols int) int {
+	if cols <= 0 {
+		return 1
+	}
+	width := utf8.RuneCountInString(ansiPattern.ReplaceAllString(line, ""))
+	if width == 0 {
+		return 1
+	}
+	return (width + cols - 1) / cols
+}

internal/client/display/output_test.go

@@ -0,0 +1,58 @@
+package display
+
+import (
+	"bytes"
+	"strings"
+	"testing"
+)
+
+func TestPagePrintsScreensAndStopsOnQ(t *testing.T) {
+	var buf bytes.Buffer
+	prevOut, prevSize := Out, TermSize
+	Out = &buf
+	TermSize = func() (int, int) { return 5, 80 } // 4 lines a page
+	defer func() { Out, TermSize = prevOut, prevSize }()
+
+	var lines []string
+	for i := 1; i <= 10; i++ {
+		lines = append(lines, "line "+string(rune('0'+i%10)))
+	}
+	answers := []string{"", "q"}
+	reads := 0
+	readLine := func() (string, bool) {
+		if reads >= len(answers) {
+			return "", false
+		}
+		reads++
+		return answers[reads-1], true
+	}
+	Page(strings.Join(lines, "\n")+"\n", readLine)
+	out := buf.String()
+	if reads != 2 {
+		t.Errorf("prompted %d times, want 2", reads)
+	}
+	if !strings.Contains(out, "line 1\nline 2\nline 3\nline 4\n") || !strings.Contains(out, "More (6 lines left") {
+		t.Errorf("first page = %q", out)
+	}
+	if !strings.Contains(out, "line 5\nline 6\nline 7\nline 8\n") || strings.Contains(out, "line 9") {
+		t.Errorf("second page / stop = %q", out)
+	}
+
+	// Fits on one screen: no prompt. A wrapped long line counts as two rows.
+	buf.Reset()
+	reads = 0
+	Page("a\nb\n", readLine)
+	if buf.String() != "a\nb\n" || reads != 0 {
+		t.Errorf("short text = %q, prompts %d", buf.String(), reads)
+	}
+	if wrappedRows(Red+strings.Repeat("x", 100)+Reset, 80) != 2 || wrappedRows("", 80) != 1 {
+		t.Error("wrapped rows")
+	}
+	// No terminal: everything at once.
+	TermSize = func() (int, int) { return 0, 0 }
+	buf.Reset()
+	Page(strings.Join(lines, "\n"), readLine)
+	if strings.Count(buf.String(), "\n") != 10 || reads != 0 {
+		t.Errorf("unpaged = %q", buf.String())
+	}
+}

internal/client/display/termsize_native.go

@@ -0,0 +1,23 @@
+//go:build !js && !wasm
+
+package display
+
+import (
+	"os"
+
+	"golang.org/x/term"
+)
+
+func init() {
+	TermSize = func() (rows, cols int) {
+		fd := int(os.Stdout.Fd())
+		if !term.IsTerminal(fd) {
+			return 0, 0
+		}
+		cols, rows, err := term.GetSize(fd)
+		if err != nil {
+			return 0, 0
+		}
+		return rows, cols
+	}
+}

internal/client/display/termsize_wasm.go

@@ -0,0 +1,21 @@
+//go:build js && wasm
+
+package display
+
+import "syscall/js"
+
+// The page's terminal wrapper (terminal.js) publishes xterm's size as
+// globalThis.chessTerminal.rows and .cols.
+func init() {
+	TermSize = func() (rows, cols int) {
+		t := js.Global().Get("chessTerminal")
+		if t.IsUndefined() || t.IsNull() {
+			return 24, 80
+		}
+		rows, cols = t.Get("rows").Int(), t.Get("cols").Int()
+		if rows <= 0 || cols <= 0 {
+			return 24, 80
+		}
+		return rows, cols
+	}
+}

internal/client/replay/replay.go

@@ -0,0 +1,175 @@
+// Package replay steps through a stored game's history in the terminal
+// client. The state is separate from the live session: it holds the
+// history the server returned and a ply, and renders positions from the
+// stored FENs; it never computes a move.
+package replay
+
+import (
+	"fmt"
+	"strconv"
+	"strings"
+
+	"github.com/lixenwraith/chess/internal/client/api"
+)
+
+// State is a stored game and the ply shown: 0 is the initial position,
+// Len() the position after the last move.
+type State struct {
+	History *api.GameHistoryResponse
+	Ply     int
+}
+
+// New starts a replay at the initial position.
+func New(history *api.GameHistoryResponse) *State {
+	return &State{History: history}
+}
+
+// Len is the number of stored plies.
+func (s *State) Len() int { return len(s.History.Moves) }
+
+// Goto shows the position after ply plies, clamped to the stored line, and
+// returns the ply shown.
+func (s *State) Goto(ply int) int {
+	if ply < 0 {
+		ply = 0
+	}
+	if ply > s.Len() {
+		ply = s.Len()
+	}
+	s.Ply = ply
+	return s.Ply
+}
+
+func (s *State) Next() int  { return s.Goto(s.Ply + 1) }
+func (s *State) Prev() int  { return s.Goto(s.Ply - 1) }
+func (s *State) First() int { return s.Goto(0) }
+func (s *State) Last() int  { return s.Goto(s.Len()) }
+
+// AtEnd reports whether the last stored position is shown.
+func (s *State) AtEnd() bool { return s.Ply >= s.Len() }
+
+// FEN is the stored position at the current ply.
+func (s *State) FEN() string {
+	if s.Ply == 0 {
+		return s.History.InitialFEN
+	}
+	return s.History.Moves[s.Ply-1].FENAfterMove
+}
+
+// Move is the ply-th move (from 1), or nil for the initial position.
+func (s *State) Move(ply int) *api.HistoryMove {
+	if ply < 1 || ply > s.Len() {
+		return nil
+	}
+	return &s.History.Moves[ply-1]
+}
+
+// startsWithBlack and firstMoveNumber come from the initial FEN, so a game
+// from a custom position numbers its moves as its PGN does.
+func (s *State) start() (number int, black bool) {
+	parts := strings.Fields(s.History.InitialFEN)
+	number = 1
+	if len(parts) >= 6 {
+		if n, err := strconv.Atoi(parts[5]); err == nil && n > 0 {
+			number = n
+		}
+	}
+	black = len(parts) >= 2 && parts[1] == "b"
+	return number, black
+}
+
+// Label names a ply in PGN style: "2. Nf3", "2... Nf6", or "start".
+func (s *State) Label(ply int) string {
+	move := s.Move(ply)
+	if move == nil {
+		return "start"
+	}
+	first, black := s.start()
+	offset := ply - 1
+	if black {
+		offset++
+	}
+	number := first + offset/2
+	text := move.SAN
+	if text == "" {
+		text = move.MoveUCI
+	}
+	if move.PlayerColor == "b" {
+		return fmt.Sprintf("%d... %s", number, text)
+	}
+	return fmt.Sprintf("%d. %s", number, text)
+}
+
+// Movetext lists the moves with numbers, the current ply in brackets,
+// wrapped at width columns (80 when width is not positive).
+func (s *State) Movetext(width int) string {
+	if width <= 0 {
+		width = 80
+	}
+	first, black := s.start()
+	var tokens []string
+	number := first
+	for i, move := range s.History.Moves {
+		text := move.SAN
+		if text == "" {
+			text = move.MoveUCI
+		}
+		if i+1 == s.Ply {
+			text = "[" + text + "]"
+		}
+		switch {
+		case i == 0 && black:
+			tokens = append(tokens, fmt.Sprintf("%d...", number), text)
+			number++
+		case move.PlayerColor == "w":
+			tokens = append(tokens, fmt.Sprintf("%d.", number), text)
+		default:
+			tokens = append(tokens, text)
+			number++
+		}
+	}
+	if len(tokens) == 0 {
+		return "(no moves)"
+	}
+	var b strings.Builder
+	col := 0
+	for _, token := range tokens {
+		if col > 0 && col+1+len(token) > width {
+			b.WriteByte('\n')
+			col = 0
+		} else if col > 0 {
+			b.WriteByte(' ')
+			col++
+		}
+		b.WriteString(token)
+		col += len(token)
+	}
+	return b.String()
+}
+
+// Players names the sides: the stored name, the engine and level, or
+// "Anonymous".
+func (s *State) Players() (white, black string) {
+	return playerLabel(s.History.Players.White), playerLabel(s.History.Players.Black)
+}
+
+func playerLabel(p api.PlayerInfo) string {
+	switch {
+	case p.Type == 2:
+		return fmt.Sprintf("Stockfish L%d", p.Level)
+	case p.Name != "":
+		return p.Name
+	}
+	return "Anonymous"
+}
+
+// Result describes the outcome: "1-0 (checkmate)" or "ongoing".
+func (s *State) Result() string {
+	if s.History.Result == "" {
+		return "ongoing"
+	}
+	if s.History.Termination != "" {
+		return fmt.Sprintf("%s (%s)", s.History.PGNResult, strings.ReplaceAll(s.History.Termination, "_", " "))
+	}
+	return s.History.PGNResult
+}

internal/client/replay/replay_test.go

@@ -0,0 +1,91 @@
+package replay
+
+import (
+	"testing"
+
+	"github.com/lixenwraith/chess/internal/client/api"
+)
+
+func TestNavigationClampsAndSelectsStoredFEN(t *testing.T) {
+	h := &api.GameHistoryResponse{
+		InitialFEN: "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1",
+		Moves: []api.HistoryMove{
+			{MoveNumber: 1, MoveUCI: "e2e4", SAN: "e4", FENAfterMove: "fen1", PlayerColor: "w"},
+			{MoveNumber: 2, MoveUCI: "c7c5", SAN: "c5", FENAfterMove: "fen2", PlayerColor: "b"},
+			{MoveNumber: 3, MoveUCI: "g1f3", SAN: "Nf3", FENAfterMove: "fen3", PlayerColor: "w"},
+		},
+	}
+	s := New(h)
+	if s.Ply != 0 || s.FEN() != h.InitialFEN || s.Label(0) != "start" {
+		t.Fatalf("new state: ply %d fen %q label %q", s.Ply, s.FEN(), s.Label(0))
+	}
+	if got := s.Next(); got != 1 || s.FEN() != "fen1" || s.Label(1) != "1. e4" {
+		t.Errorf("next: ply %d fen %q label %q", got, s.FEN(), s.Label(1))
+	}
+	if got := s.Last(); got != 3 || !s.AtEnd() || s.Label(3) != "2. Nf3" {
+		t.Errorf("last: ply %d atEnd %v label %q", got, s.AtEnd(), s.Label(3))
+	}
+	if got := s.Next(); got != 3 {
+		t.Errorf("next past the end = %d", got)
+	}
+	if got := s.Goto(-5); got != 0 || s.FEN() != h.InitialFEN {
+		t.Errorf("goto -5 = %d", got)
+	}
+	if got := s.Goto(2); got != 2 || s.Label(2) != "1... c5" || s.FEN() != "fen2" {
+		t.Errorf("goto 2 = %d label %q", got, s.Label(2))
+	}
+	if got := s.Prev(); got != 1 {
+		t.Errorf("prev = %d", got)
+	}
+	if s.Move(0) != nil || s.Move(4) != nil || s.Move(3).SAN != "Nf3" {
+		t.Error("Move bounds")
+	}
+	want := "1. e4 c5 2. [Nf3]"
+	s.Last()
+	if got := s.Movetext(80); got != want {
+		t.Errorf("movetext = %q, want %q", got, want)
+	}
+	if got := s.Movetext(8); got != "1. e4 c5\n2. [Nf3]" {
+		t.Errorf("wrapped movetext = %q", got)
+	}
+	if s.Result() != "ongoing" {
+		t.Errorf("result = %q", s.Result())
+	}
+	h.Result, h.PGNResult, h.Termination = "white_wins", "1-0", "checkmate"
+	if s.Result() != "1-0 (checkmate)" {
+		t.Errorf("result = %q", s.Result())
+	}
+}
+
+func TestCustomStartNumbersFromItsMoveAndSide(t *testing.T) {
+	h := &api.GameHistoryResponse{
+		InitialFEN: "4k3/8/8/8/8/8/8/4K2R b K - 0 40",
+		Moves: []api.HistoryMove{
+			{MoveNumber: 1, MoveUCI: "e8d8", SAN: "Kd8", FENAfterMove: "f1", PlayerColor: "b"},
+			{MoveNumber: 2, MoveUCI: "e1g1", SAN: "O-O", FENAfterMove: "f2", PlayerColor: "w"},
+			{MoveNumber: 3, MoveUCI: "d8c8", SAN: "Kc8", FENAfterMove: "f3", PlayerColor: "b"},
+		},
+	}
+	s := New(h)
+	for ply, want := range map[int]string{1: "40... Kd8", 2: "41. O-O", 3: "41... Kc8"} {
+		if got := s.Label(ply); got != want {
+			t.Errorf("label %d = %q, want %q", ply, got, want)
+		}
+	}
+	s.Goto(2)
+	if got := s.Movetext(80); got != "40... Kd8 41. [O-O] Kc8" {
+		t.Errorf("movetext = %q", got)
+	}
+	if w, b := s.Players(); w != "Anonymous" || b != "Anonymous" {
+		t.Errorf("players = %q %q", w, b)
+	}
+	h.Players.White = api.PlayerInfo{Type: 2, Level: 7}
+	h.Players.Black = api.PlayerInfo{Type: 1, Name: "alice"}
+	if w, b := s.Players(); w != "Stockfish L7" || b != "alice" {
+		t.Errorf("players = %q %q", w, b)
+	}
+	empty := New(&api.GameHistoryResponse{InitialFEN: h.InitialFEN})
+	if empty.Movetext(80) != "(no moves)" || empty.Last() != 0 {
+		t.Error("empty history")
+	}
+}

internal/client/session/session.go

@@ -2,6 +2,7 @@ package session
 
 import (
 	"github.com/lixenwraith/chess/internal/client/api"
+	"github.com/lixenwraith/chess/internal/client/replay"
 )
 
 // Session maintains client state and configuration
@@ -12,9 +13,16 @@ type Session struct {
 	AuthToken     string
 	Username      string
 	LastMoveCount int
-	GamesCursor   string // next page of the "games" listing
+	GamesCursor   string            // next page of the "games" listing
+	GamesPage     []api.GameSummary // the last "games" page, for "replay <index>"
 	Client        *api.Client
-	Verbose       bool
+	// Replay is the stored game being stepped through, nil while live. The
+	// live game, user, and poll state above are untouched by a replay.
+	Replay *replay.State
+	// ReadLine reads the next input line (false at end of input); the pager
+	// uses it to wait between screens.
+	ReadLine func() (string, bool)
+	Verbose  bool
 	// Game state for prompt
 	CurrentGameState *api.GameResponse
 	PlayerColor      string // "w", "b", or ""

internal/server/core/api.go

@@ -42,7 +42,9 @@ type UndoRequest struct {
 // DrawOffer is the color whose draw offer awaits an answer; DrawOutcome
 // reports what a draw request did ("offered", "accepted", "declined") and is
 // set only on responses to that request. Concession is the game's first
-// resignation or agreed draw, kept after an undo continues play.
+// resignation or agreed draw, kept after an undo continues play. SAN runs
+// parallel to Moves, derived by the rules core from the position before each
+// move; an entry is empty only for a move the core cannot notate.
 type GameResponse struct {
 	GameID      string          `json:"gameId"`
 	FEN         string          `json:"fen"`
@@ -53,6 +55,7 @@ type GameResponse struct {
 	DrawOutcome string          `json:"drawOutcome,omitempty"`
 	Concession  *Concession     `json:"concession,omitempty"`
 	Moves       []string        `json:"moves"`
+	SAN         []string        `json:"san"`
 	Players     PlayersResponse `json:"players"`
 	LastMove    *MoveInfo       `json:"lastMove,omitempty"`
 }
@@ -113,13 +116,15 @@ type HistoryMove struct {
 
 // GameSummary is intentionally sufficient for a client-side game picker; the
 // full move list remains on the per-game history endpoint. FinalFEN is the
-// position after the last stored move (the initial FEN when there is none).
+// position after the last stored move (the initial FEN when there is none);
+// Termination says how a finished game ended, as in the history.
 type GameSummary struct {
 	GameID       string          `json:"gameId"`
 	InitialFEN   string          `json:"initialFen"`
 	FinalFEN     string          `json:"finalFen"`
 	Result       string          `json:"result,omitempty"`
 	PGNResult    string          `json:"pgnResult"`
+	Termination  string          `json:"termination,omitempty"`
 	StartTimeUTC time.Time       `json:"startTimeUtc"`
 	EndTimeUTC   *time.Time      `json:"endTimeUtc,omitempty"`
 	MoveCount    int             `json:"moveCount"`

internal/server/core/error.go

@@ -16,4 +16,5 @@ const (
 	ErrConflict           = "GAME_CONFLICT"
 	ErrStorageUnavailable = "STORAGE_UNAVAILABLE"
 	ErrRouteNotFound      = "NOT_FOUND"
+	ErrNotConfigured      = "NOT_CONFIGURED"
 )

internal/server/http/auth.go

@@ -35,6 +35,17 @@ type DeleteAccountRequest struct {
 	Password string `json:"password" validate:"required"`
 }
 
+// RecoverRequest asks for a password-reset email.
+type RecoverRequest struct {
+	Identifier string `json:"identifier" validate:"required"` // username or email
+}
+
+// ResetPasswordRequest sets a new password with the token from the email.
+type ResetPasswordRequest struct {
+	Token    string `json:"token" validate:"required"`
+	Password string `json:"password" validate:"required"`
+}
+
 // AuthResponse contains JWT token and user information
 type AuthResponse struct {
 	Token     string    `json:"token"`
@@ -322,3 +333,104 @@ func (h *HTTPHandler) DeleteAccountHandler(c *fiber.Ctx) error {
 
 	return c.SendStatus(fiber.StatusNoContent)
 }
+
+// RecoverHandler emails a password-reset link. The answer is the same whether
+// or not the account exists or has an email, so nothing is revealed; only a
+// missing transport (503) or a delivery failure (502) is reported.
+func (h *HTTPHandler) RecoverHandler(c *fiber.Ctx) error {
+	var req RecoverRequest
+	if err := c.BodyParser(&req); err != nil || strings.TrimSpace(req.Identifier) == "" {
+		return c.Status(fiber.StatusBadRequest).JSON(core.ErrorResponse{
+			Error:   "invalid request body",
+			Code:    core.ErrInvalidRequest,
+			Details: "identifier (username or email) is required",
+		})
+	}
+	if len(req.Identifier) > 254 {
+		return c.Status(fiber.StatusBadRequest).JSON(core.ErrorResponse{
+			Error: "invalid identifier", Code: core.ErrInvalidRequest,
+		})
+	}
+
+	if err := h.svc.RequestPasswordReset(req.Identifier); err != nil {
+		switch {
+		case errors.Is(err, service.ErrMailDisabled):
+			return c.Status(fiber.StatusServiceUnavailable).JSON(core.ErrorResponse{
+				Error: "password recovery is not available on this server", Code: core.ErrNotConfigured,
+			})
+		case errors.Is(err, service.ErrMailFailed):
+			return c.Status(fiber.StatusBadGateway).JSON(core.ErrorResponse{
+				Error: "the reset email could not be sent; try again later", Code: core.ErrInternalError,
+			})
+		case errors.Is(err, service.ErrStorageDisabled), errors.Is(err, service.ErrStorageUnavailable):
+			return c.Status(fiber.StatusServiceUnavailable).JSON(core.ErrorResponse{
+				Error: "account storage unavailable", Code: core.ErrStorageUnavailable,
+			})
+		default:
+			return c.Status(fiber.StatusInternalServerError).JSON(core.ErrorResponse{
+				Error: "failed to start password recovery", Code: core.ErrInternalError,
+			})
+		}
+	}
+	return c.Status(fiber.StatusAccepted).JSON(fiber.Map{
+		"message": "If the account has an email address, a reset link has been sent to it.",
+	})
+}
+
+// ResetPasswordHandler sets a new password from a reset link and signs the
+// user in, returning a session token like login.
+func (h *HTTPHandler) ResetPasswordHandler(c *fiber.Ctx) error {
+	var req ResetPasswordRequest
+	if err := c.BodyParser(&req); err != nil || req.Token == "" || req.Password == "" {
+		return c.Status(fiber.StatusBadRequest).JSON(core.ErrorResponse{
+			Error:   "invalid request body",
+			Code:    core.ErrInvalidRequest,
+			Details: "token and password are required",
+		})
+	}
+	if err := validatePassword(req.Password); err != nil {
+		return c.Status(fiber.StatusBadRequest).JSON(core.ErrorResponse{
+			Error:   "weak password",
+			Code:    core.ErrInvalidRequest,
+			Details: err.Error(),
+		})
+	}
+
+	user, sessionID, err := h.svc.ResetPassword(req.Token, req.Password)
+	if err != nil {
+		switch {
+		case errors.Is(err, service.ErrResetInvalid):
+			return c.Status(fiber.StatusBadRequest).JSON(core.ErrorResponse{
+				Error:   "invalid or expired reset link",
+				Code:    core.ErrInvalidRequest,
+				Details: "request a new link from the sign-in dialog",
+			})
+		case errors.Is(err, service.ErrAuthBusy):
+			return c.Status(fiber.StatusServiceUnavailable).JSON(core.ErrorResponse{
+				Error: "authentication temporarily unavailable", Code: core.ErrResourceLimit,
+			})
+		case errors.Is(err, service.ErrStorageDisabled), errors.Is(err, service.ErrStorageUnavailable):
+			return c.Status(fiber.StatusServiceUnavailable).JSON(core.ErrorResponse{
+				Error: "account storage unavailable", Code: core.ErrStorageUnavailable,
+			})
+		default:
+			return c.Status(fiber.StatusInternalServerError).JSON(core.ErrorResponse{
+				Error: "failed to reset password", Code: core.ErrInternalError,
+			})
+		}
+	}
+
+	token, err := h.svc.GenerateUserToken(user.UserID, sessionID)
+	if err != nil {
+		return c.Status(fiber.StatusInternalServerError).JSON(core.ErrorResponse{
+			Error: "failed to generate token", Code: core.ErrInternalError,
+		})
+	}
+	return c.JSON(AuthResponse{
+		Token:     token,
+		UserID:    user.UserID,
+		Username:  user.Username,
+		Email:     user.Email,
+		ExpiresAt: time.Now().Add(service.SessionTTL),
+	})
+}

internal/server/http/handler.go

@@ -93,10 +93,14 @@ func NewFiberApp(proc *processor.Processor, svc *service.Service, opts Options)
 			TimeZone:   "UTC",
 		}))
 	}
+	// ETag and Content-Disposition are not CORS-safelisted: a browser client
+	// on another origin (the embedded web server's port, in development) can
+	// only revalidate histories and name PGN downloads when they are exposed.
 	app.Use(cors.New(cors.Config{
-		AllowOrigins: "*",
+		AllowOrigins:  "*",
-		AllowMethods: "GET,POST,PUT,DELETE,OPTIONS",
+		AllowMethods:  "GET,POST,PUT,DELETE,OPTIONS",
-		AllowHeaders: "Origin,Content-Type,Accept,Authorization",
+		AllowHeaders:  "Origin,Content-Type,Accept,Authorization,If-None-Match",
+		ExposeHeaders: "ETag,Content-Disposition",
 	}))
 
 	// Health check (no rate limit)
@@ -136,6 +140,33 @@ func NewFiberApp(proc *processor.Processor, svc *service.Service, opts Options)
 		},
 	}), h.LoginHandler)
 
+	// Password recovery: 3 requests a minute per IP, each of which may send
+	// an email; the reset itself is limited like login.
+	auth.Post("/recover", limiter.New(limiter.Config{
+		Max:          3,
+		Expiration:   1 * time.Minute,
+		KeyGenerator: clientIP,
+		LimitReached: func(c *fiber.Ctx) error {
+			return c.Status(fiber.StatusTooManyRequests).JSON(core.ErrorResponse{
+				Error:   "rate limit exceeded",
+				Code:    core.ErrRateLimitExceeded,
+				Details: "3 recovery requests per minute allowed",
+			})
+		},
+	}), h.RecoverHandler)
+	auth.Post("/reset", limiter.New(limiter.Config{
+		Max:          10,
+		Expiration:   1 * time.Minute,
+		KeyGenerator: clientIP,
+		LimitReached: func(c *fiber.Ctx) error {
+			return c.Status(fiber.StatusTooManyRequests).JSON(core.ErrorResponse{
+				Error:   "rate limit exceeded",
+				Code:    core.ErrRateLimitExceeded,
+				Details: "10 password resets per minute allowed",
+			})
+		},
+	}), h.ResetPasswordHandler)
+
 	// Create token validator closure
 	validateToken := svc.ValidateToken
 
@@ -259,6 +290,7 @@ func (h *HTTPHandler) Health(c *fiber.Ctx) error {
 		"status":  status,
 		"time":    time.Now().Unix(),
 		"storage": storageHealth,
+		"mail":    h.svc.MailHealth(),
 		"version": h.version,
 	})
 }

internal/server/http/handler_test.go

@@ -89,6 +89,8 @@ func TestAPIRoutes(t *testing.T) {
 		"GET /api/auth/me",
 		"POST /api/auth/logout",
 		"DELETE /api/auth/me",
+		"POST /api/auth/recover",
+		"POST /api/auth/reset",
 		"POST /api/games",
 		"GET /api/games/:gameId",
 		"GET /api/games/:gameId/history",

internal/server/mail/mail.go

@@ -0,0 +1,259 @@
+// Package mail sends the server's few transactional messages, today the
+// password-reset link. A Sender is an SMTP relay (production), a directory
+// of .eml files (development and tests), or nothing, in which case the
+// features that need mail are off.
+package mail
+
+import (
+	"bytes"
+	"context"
+	"crypto/rand"
+	"crypto/tls"
+	"encoding/hex"
+	"errors"
+	"fmt"
+	"net"
+	"net/mail"
+	"net/smtp"
+	"os"
+	"path/filepath"
+	"strings"
+	"time"
+)
+
+// Message is one plain-text email.
+type Message struct {
+	To      string
+	Subject string
+	Body    string
+}
+
+// Sender delivers messages.
+type Sender interface {
+	Send(ctx context.Context, m Message) error
+	// Describe names the transport for logs, without secrets.
+	Describe() string
+}
+
+// SMTP delivers through a relay. Username and Password are optional: a relay
+// inside the same network usually accepts mail from this host without them.
+// STARTTLS is used when the relay offers it; credentials are only ever sent
+// over TLS (or to localhost), which net/smtp enforces.
+type SMTP struct {
+	Host     string
+	Port     int
+	Username string
+	Password string
+	From     string // "Chess <chess@example.com>" or a bare address
+	// Timeout bounds the whole exchange; 30 seconds when zero.
+	Timeout time.Duration
+}
+
+// Describe names the relay.
+func (s *SMTP) Describe() string {
+	auth := "no authentication"
+	if s.Username != "" {
+		auth = "as " + s.Username
+	}
+	return fmt.Sprintf("smtp %s:%d (%s), from %s", s.Host, s.Port, auth, s.From)
+}
+
+// Send delivers one message through the relay.
+func (s *SMTP) Send(ctx context.Context, m Message) error {
+	from, err := mail.ParseAddress(s.From)
+	if err != nil {
+		return fmt.Errorf("mail from %q: %w", s.From, err)
+	}
+	to, err := mail.ParseAddress(m.To)
+	if err != nil {
+		return fmt.Errorf("mail to %q: %w", m.To, err)
+	}
+	timeout := s.Timeout
+	if timeout <= 0 {
+		timeout = 30 * time.Second
+	}
+	if deadline, ok := ctx.Deadline(); ok {
+		if until := time.Until(deadline); until < timeout {
+			timeout = until
+		}
+	}
+	addr := net.JoinHostPort(s.Host, fmt.Sprint(s.Port))
+	conn, err := (&net.Dialer{Timeout: timeout}).DialContext(ctx, "tcp", addr)
+	if err != nil {
+		return fmt.Errorf("connect to %s: %w", addr, err)
+	}
+	defer conn.Close()
+	if err := conn.SetDeadline(time.Now().Add(timeout)); err != nil {
+		return err
+	}
+
+	client, err := smtp.NewClient(conn, s.Host)
+	if err != nil {
+		return fmt.Errorf("smtp handshake with %s: %w", addr, err)
+	}
+	defer client.Close()
+	if ok, _ := client.Extension("STARTTLS"); ok {
+		if err := client.StartTLS(&tls.Config{ServerName: s.Host, MinVersion: tls.VersionTLS12}); err != nil {
+			return fmt.Errorf("starttls with %s: %w", addr, err)
+		}
+	}
+	if s.Username != "" {
+		if err := client.Auth(smtp.PlainAuth("", s.Username, s.Password, s.Host)); err != nil {
+			return fmt.Errorf("smtp authentication with %s: %w", addr, err)
+		}
+	}
+	if err := client.Mail(from.Address); err != nil {
+		return fmt.Errorf("smtp from: %w", err)
+	}
+	if err := client.Rcpt(to.Address); err != nil {
+		return fmt.Errorf("smtp to: %w", err)
+	}
+	w, err := client.Data()
+	if err != nil {
+		return fmt.Errorf("smtp data: %w", err)
+	}
+	if _, err := w.Write(Format(s.From, m)); err != nil {
+		return fmt.Errorf("smtp write: %w", err)
+	}
+	if err := w.Close(); err != nil {
+		return fmt.Errorf("smtp send: %w", err)
+	}
+	return client.Quit()
+}
+
+// Dir writes each message to a file in a directory instead of sending it,
+// for development and tests. The file holds exactly what SMTP would carry.
+type Dir struct {
+	Path string
+	From string
+}
+
+// Describe names the directory.
+func (d *Dir) Describe() string {
+	return fmt.Sprintf("directory %s, from %s", d.Path, d.From)
+}
+
+// Send writes the message as <unix-nanos>-<random>.eml.
+func (d *Dir) Send(_ context.Context, m Message) error {
+	if _, err := mail.ParseAddress(m.To); err != nil {
+		return fmt.Errorf("mail to %q: %w", m.To, err)
+	}
+	if err := os.MkdirAll(d.Path, 0o700); err != nil {
+		return err
+	}
+	var nonce [4]byte
+	rand.Read(nonce[:])
+	name := fmt.Sprintf("%d-%s.eml", time.Now().UnixNano(), hex.EncodeToString(nonce[:]))
+	return os.WriteFile(filepath.Join(d.Path, name), Format(d.From, m), 0o600)
+}
+
+// Format renders the message as RFC 5322 text with CRLF line ends: headers,
+// a blank line, the UTF-8 body. Header values are kept to one line.
+func Format(from string, m Message) []byte {
+	var nonce [8]byte
+	rand.Read(nonce[:])
+	domain := "localhost"
+	if addr, err := mail.ParseAddress(from); err == nil {
+		if at := strings.LastIndex(addr.Address, "@"); at >= 0 {
+			domain = addr.Address[at+1:]
+		}
+	}
+	var b bytes.Buffer
+	header := func(name, value string) {
+		value = strings.NewReplacer("\r", " ", "\n", " ").Replace(value)
+		fmt.Fprintf(&b, "%s: %s\r\n", name, value)
+	}
+	header("From", from)
+	header("To", m.To)
+	header("Subject", m.Subject)
+	header("Date", time.Now().UTC().Format(time.RFC1123Z))
+	header("Message-ID", fmt.Sprintf("<%d.%s@%s>", time.Now().UnixNano(), hex.EncodeToString(nonce[:]), domain))
+	header("MIME-Version", "1.0")
+	header("Content-Type", "text/plain; charset=utf-8")
+	header("Content-Transfer-Encoding", "8bit")
+	header("Auto-Submitted", "auto-generated")
+	b.WriteString("\r\n")
+	body := strings.ReplaceAll(strings.ReplaceAll(m.Body, "\r\n", "\n"), "\n", "\r\n")
+	b.WriteString(body)
+	if !strings.HasSuffix(body, "\r\n") {
+		b.WriteString("\r\n")
+	}
+	return b.Bytes()
+}
+
+// ErrNoSender is returned by Validate for an empty configuration.
+var ErrNoSender = errors.New("no mail transport configured")
+
+// Config is the server's mail configuration, from its flags. SMTPHost or Dir
+// selects the transport; both empty means no mail.
+type Config struct {
+	SMTPHost         string
+	SMTPPort         int
+	SMTPUser         string
+	SMTPPasswordFile string
+	Dir              string
+	From             string
+}
+
+// Build returns the configured Sender, nil (with ErrNoSender) when nothing is
+// configured, or an error for an inconsistent configuration.
+func (c Config) Build() (Sender, error) {
+	switch {
+	case c.SMTPHost != "" && c.Dir != "":
+		return nil, errors.New("-smtp-host and -mail-dir are exclusive")
+	case c.SMTPHost == "" && c.Dir == "":
+		return nil, ErrNoSender
+	}
+	if c.From == "" {
+		return nil, errors.New("-mail-from is required with a mail transport")
+	}
+	if _, err := mail.ParseAddress(c.From); err != nil {
+		return nil, fmt.Errorf("-mail-from %q: %w", c.From, err)
+	}
+	if c.Dir != "" {
+		if err := os.MkdirAll(c.Dir, 0o700); err != nil {
+			return nil, fmt.Errorf("-mail-dir: %w", err)
+		}
+		return &Dir{Path: c.Dir, From: c.From}, nil
+	}
+	port := c.SMTPPort
+	if port <= 0 {
+		port = 25
+	}
+	s := &SMTP{Host: c.SMTPHost, Port: port, Username: c.SMTPUser, From: c.From}
+	if c.SMTPPasswordFile != "" {
+		secret, err := readSecretFile(c.SMTPPasswordFile)
+		if err != nil {
+			return nil, fmt.Errorf("-smtp-password-file: %w", err)
+		}
+		s.Password = secret
+	}
+	if s.Password != "" && s.Username == "" {
+		return nil, errors.New("-smtp-password-file needs -smtp-user")
+	}
+	return s, nil
+}
+
+// readSecretFile reads a one-line secret from a file that only its owner may
+// read, as the JWT key file is.
+func readSecretFile(path string) (string, error) {
+	info, err := os.Stat(path)
+	if err != nil {
+		return "", err
+	}
+	if !info.Mode().IsRegular() {
+		return "", fmt.Errorf("%s is not a regular file", path)
+	}
+	if info.Mode().Perm()&0o077 != 0 {
+		return "", fmt.Errorf("%s is readable by group or others (mode %04o); use mode 0600", path, info.Mode().Perm())
+	}
+	data, err := os.ReadFile(path)
+	if err != nil {
+		return "", err
+	}
+	secret := strings.TrimRight(string(data), "\r\n")
+	if secret == "" {
+		return "", fmt.Errorf("%s is empty", path)
+	}
+	return secret, nil
+}

internal/server/mail/mail_test.go

@@ -0,0 +1,91 @@
+package mail
+
+import (
+	"context"
+	"errors"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestFormatIsRFC5322WithCRLF(t *testing.T) {
+	text := string(Format("Chess <chess@example.com>", Message{
+		To: "alice@example.com", Subject: "Reset your\npassword", Body: "line one\nline two",
+	}))
+	head, body, ok := strings.Cut(text, "\r\n\r\n")
+	if !ok {
+		t.Fatalf("no header/body separator in %q", text)
+	}
+	for _, want := range []string{
+		"From: Chess <chess@example.com>\r\n", "To: alice@example.com\r\n",
+		"Subject: Reset your password\r\n", "Content-Type: text/plain; charset=utf-8\r\n", "@example.com>\r\n",
+	} {
+		if !strings.Contains(head+"\r\n", want) {
+			t.Errorf("header %q missing in %q", want, head)
+		}
+	}
+	if body != "line one\r\nline two\r\n" {
+		t.Errorf("body = %q", body)
+	}
+	if strings.Contains(text, "\n\n") || strings.Contains(strings.ReplaceAll(text, "\r\n", ""), "\n") {
+		t.Error("bare LF in message")
+	}
+}
+
+func TestDirWritesOneFilePerMessage(t *testing.T) {
+	dir := filepath.Join(t.TempDir(), "mail")
+	d := &Dir{Path: dir, From: "chess@example.com"}
+	if err := d.Send(context.Background(), Message{To: "bob@example.com", Subject: "s", Body: "b"}); err != nil {
+		t.Fatal(err)
+	}
+	if err := d.Send(context.Background(), Message{To: "not an address", Subject: "s", Body: "b"}); err == nil {
+		t.Error("invalid recipient accepted")
+	}
+	entries, err := os.ReadDir(dir)
+	if err != nil || len(entries) != 1 || !strings.HasSuffix(entries[0].Name(), ".eml") {
+		t.Fatalf("entries = %v, %v", entries, err)
+	}
+	data, _ := os.ReadFile(filepath.Join(dir, entries[0].Name()))
+	if !strings.Contains(string(data), "To: bob@example.com\r\n") {
+		t.Errorf("file = %q", data)
+	}
+}
+
+func TestConfigBuild(t *testing.T) {
+	if _, err := (Config{}).Build(); !errors.Is(err, ErrNoSender) {
+		t.Errorf("empty config: %v", err)
+	}
+	for name, c := range map[string]Config{
+		"both transports": {SMTPHost: "h", Dir: "d", From: "a@b.c"},
+		"no from":         {SMTPHost: "h"},
+		"bad from":        {SMTPHost: "h", From: "nope"},
+		"password no user": {SMTPHost: "h", From: "a@b.c", SMTPPasswordFile: func() string {
+			p := filepath.Join(t.TempDir(), "pw")
+			os.WriteFile(p, []byte("secret\n"), 0o600)
+			return p
+		}()},
+	} {
+		if _, err := c.Build(); err == nil {
+			t.Errorf("%s: accepted", name)
+		}
+	}
+	pw := filepath.Join(t.TempDir(), "pw")
+	os.WriteFile(pw, []byte("secret\n"), 0o644)
+	if _, err := (Config{SMTPHost: "h", From: "a@b.c", SMTPUser: "u", SMTPPasswordFile: pw}).Build(); err == nil {
+		t.Error("world-readable password file accepted")
+	}
+	os.Chmod(pw, 0o600)
+	sender, err := (Config{SMTPHost: "mail.internal", From: "Chess <a@b.c>", SMTPUser: "u", SMTPPasswordFile: pw}).Build()
+	if err != nil {
+		t.Fatal(err)
+	}
+	s, ok := sender.(*SMTP)
+	if !ok || s.Port != 25 || s.Password != "secret" || !strings.Contains(s.Describe(), "as u") ||
+		strings.Contains(s.Describe(), "secret") {
+		t.Errorf("smtp = %+v, %q", s, sender.Describe())
+	}
+	if d, err := (Config{Dir: "x", From: "a@b.c"}).Build(); err != nil || d.(*Dir).Path != "x" {
+		t.Errorf("dir = %v, %v", d, err)
+	}
+}

internal/server/processor/processor.go

@@ -674,6 +674,7 @@ func (p *Processor) buildGameResponse(gameID string, g game.View) core.GameRespo
 		State:       g.State.String(),
 		Termination: string(g.Termination),
 		Moves:       g.Moves,
+		SAN:         notateLine(g.FENs, g.Moves),
 		Players: core.PlayersResponse{
 			White: g.WhitePlayer,
 			Black: g.BlackPlayer,
@@ -721,6 +722,27 @@ func (p *Processor) Close() error {
 	return errors.Join(queueErr, engineErr)
 }
 
+// notateLine derives SAN for each live move from the position before it,
+// fens[i] being the position before moves[i]. Each ply stands alone, so a
+// position the core cannot parse leaves only that entry empty (and is logged
+// once, by the shadow check, when the move was made).
+func notateLine(fens, moves []string) []string {
+	san := make([]string, len(moves))
+	for i, uci := range moves {
+		if i >= len(fens) {
+			break
+		}
+		pos, err := chess.ParseFEN(fens[i])
+		if err != nil {
+			continue
+		}
+		if m, err := pos.ParseUCI(uci); err == nil {
+			san[i] = pos.SAN(m)
+		}
+	}
+	return san
+}
+
 // rulesResult is the rules core's verdict on a move, computed alongside the
 // engine's. Stockfish stays authoritative; a disagreement is logged so the
 // core can be trusted, or fixed, before it validates anything.

internal/server/processor/rules_test.go

@@ -2,6 +2,8 @@ package processor
 
 import (
 	"errors"
+	"reflect"
+	"strings"
 	"testing"
 
 	"github.com/lixenwraith/chess/internal/server/chess"
@@ -25,6 +27,33 @@ func TestRulesCheck(t *testing.T) {
 	}
 }
 
+func TestNotateLine(t *testing.T) {
+	line, err := chess.Replay(chess.StartFEN, []string{"e2e4", "e7e5", "g1f3", "b8c6", "f1b5"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	fens := make([]string, 6)
+	for i := range fens {
+		fens[i] = line.Position(i).FEN()
+	}
+	moves := []string{"e2e4", "e7e5", "g1f3", "b8c6", "f1b5"}
+	if got := strings.Join(notateLine(fens, moves), " "); got != "e4 e5 Nf3 Nc6 Bb5" {
+		t.Errorf("SAN = %q", got)
+	}
+	// A ply the core cannot notate leaves only its own entry empty.
+	broken := append([]string(nil), fens...)
+	broken[2] = "not a fen"
+	if got := notateLine(broken, moves); !reflect.DeepEqual(got, []string{"e4", "e5", "", "Nc6", "Bb5"}) {
+		t.Errorf("SAN with a broken position = %q", got)
+	}
+	if got := notateLine(nil, nil); len(got) != 0 {
+		t.Errorf("SAN of no moves = %q", got)
+	}
+	if got := notateLine(fens[:1], moves[:2]); !reflect.DeepEqual(got, []string{"e4", ""}) {
+		t.Errorf("SAN short of positions = %q", got)
+	}
+}
+
 func TestAdjudicateDraw(t *testing.T) {
 	cycle := []string{"g1f3", "g8f6", "f3g1", "f6g8"}
 	line, err := chess.Replay(chess.StartFEN, append(cycle, cycle...))

internal/server/service/history.go

@@ -172,6 +172,7 @@ func (s *Service) GetUserGames(userID string, opts UserGamesOptions) (*core.Game
 			InitialFEN:   record.InitialFEN,
 			Result:       record.Result,
 			PGNResult:    chess.ResultToken(record.Result),
+			Termination:  record.Termination,
 			StartTimeUTC: record.StartTimeUTC,
 			EndTimeUTC:   record.EndTimeUTC,
 			MoveCount:    record.MoveCount,

internal/server/service/history_test.go

@@ -142,7 +142,8 @@ func TestUserGamesCursorAndFilters(t *testing.T) {
 	if err != nil {
 		t.Fatal(err)
 	}
-	if len(page.Games) != 1 || page.Games[0].GameID != finished || page.Games[0].PGNResult != "0-1" {
+	if len(page.Games) != 1 || page.Games[0].GameID != finished || page.Games[0].PGNResult != "0-1" ||
+		page.Games[0].Termination != "checkmate" {
 		t.Fatalf("finished games = %+v", page.Games)
 	}
 	for _, bad := range []UserGamesOptions{

internal/server/service/reset.go

@@ -0,0 +1,208 @@
+package service
+
+import (
+	"context"
+	"crypto/rand"
+	"crypto/sha256"
+	"database/sql"
+	"encoding/base64"
+	"errors"
+	"fmt"
+	"log/slog"
+	"net/url"
+	"strings"
+	"time"
+
+	"github.com/lixenwraith/chess/internal/server/mail"
+	"github.com/lixenwraith/chess/internal/server/storage"
+
+	"github.com/google/uuid"
+)
+
+const (
+	// PasswordResetTTL is how long a reset link works.
+	PasswordResetTTL = time.Hour
+	resetTokenBytes  = 32
+	mailSendTimeout  = 20 * time.Second
+)
+
+var (
+	// ErrMailDisabled reports that no mail transport is configured, so
+	// password recovery is off.
+	ErrMailDisabled = errors.New("password recovery is not configured")
+	// ErrMailFailed reports a delivery failure to the relay.
+	ErrMailFailed = errors.New("could not send the email")
+	// ErrResetInvalid reports an unknown, used, or expired reset token.
+	ErrResetInvalid = errors.New("invalid or expired reset link")
+)
+
+// mailer is the configured transport and the client URL reset links open.
+type mailer struct {
+	sender    mail.Sender
+	publicURL *url.URL
+}
+
+// SetMailer configures password recovery: sender delivers the email and
+// publicURL is the web client's address, which the link opens with
+// ?reset=<token>. A nil sender turns recovery off.
+func (s *Service) SetMailer(sender mail.Sender, publicURL string) error {
+	if sender == nil {
+		s.mail = nil
+		return nil
+	}
+	u, err := url.Parse(publicURL)
+	if err != nil || u.Scheme == "" || u.Host == "" {
+		return fmt.Errorf("public URL %q must be absolute (https://host/chess/web-client/)", publicURL)
+	}
+	s.mail = &mailer{sender: sender, publicURL: u}
+	return nil
+}
+
+// MailHealth reports "ok" when password recovery can send mail, otherwise
+// "disabled".
+func (s *Service) MailHealth() string {
+	if s.mail == nil || s.store == nil {
+		return "disabled"
+	}
+	return "ok"
+}
+
+// NewResetToken returns a fresh reset token and the hash stored for it.
+func NewResetToken() (token string, hash []byte, err error) {
+	raw := make([]byte, resetTokenBytes)
+	if _, err := rand.Read(raw); err != nil {
+		return "", nil, err
+	}
+	token = base64.RawURLEncoding.EncodeToString(raw)
+	return token, hashResetToken(token), nil
+}
+
+func hashResetToken(token string) []byte {
+	sum := sha256.Sum256([]byte(token))
+	return sum[:]
+}
+
+// ResetLink is the web client URL that opens the password form for token.
+func ResetLink(publicURL *url.URL, token string) string {
+	u := *publicURL
+	q := u.Query()
+	q.Set("reset", token)
+	u.RawQuery = q.Encode()
+	u.Fragment = ""
+	return u.String()
+}
+
+// RequestPasswordReset emails a reset link to the account named by
+// identifier (username or email) when it has an email address. It reports
+// success for unknown accounts and accounts without an email, so the request
+// reveals nothing about who is registered; the caller sees the same answer.
+func (s *Service) RequestPasswordReset(identifier string) error {
+	if s.store == nil {
+		return ErrStorageDisabled
+	}
+	if s.mail == nil {
+		return ErrMailDisabled
+	}
+	identifier = strings.ToLower(strings.TrimSpace(identifier))
+	var record *storage.UserRecord
+	var err error
+	if strings.Contains(identifier, "@") {
+		record, err = s.store.GetUserByEmail(identifier)
+	} else {
+		record, err = s.store.GetUserByUsername(identifier)
+	}
+	if err != nil {
+		if errors.Is(err, sql.ErrNoRows) {
+			slog.Info("password reset requested for an unknown account")
+			return nil
+		}
+		return fmt.Errorf("%w: look up user: %v", ErrStorageUnavailable, err)
+	}
+	if record.Email == "" {
+		slog.Info("password reset requested for an account without email", "user_id", record.UserID)
+		return nil
+	}
+
+	token, hash, err := NewResetToken()
+	if err != nil {
+		return fmt.Errorf("generate reset token: %w", err)
+	}
+	now := time.Now().UTC()
+	if err := s.store.CreatePasswordReset(storage.PasswordResetRecord{
+		UserID: record.UserID, TokenHash: hash, CreatedAt: now, ExpiresAt: now.Add(PasswordResetTTL),
+	}); err != nil {
+		return fmt.Errorf("%w: store reset: %v", ErrStorageUnavailable, err)
+	}
+
+	link := ResetLink(s.mail.publicURL, token)
+	ctx, cancel := context.WithTimeout(context.Background(), mailSendTimeout)
+	defer cancel()
+	err = s.mail.sender.Send(ctx, mail.Message{
+		To:      record.Email,
+		Subject: "Reset your chess password",
+		Body: fmt.Sprintf(`Hello %s,
+
+Someone asked to reset the password of your chess account at %s.
+If it was you, open this link within the next hour:
+
+  %s
+
+If you did not ask for this, ignore this message: your password stays as
+it is and nobody else can use the link without this email.
+`, record.Username, s.mail.publicURL.Host, link),
+	})
+	if err != nil {
+		slog.Error("password reset email failed", "user_id", record.UserID, "error", err)
+		return ErrMailFailed
+	}
+	slog.Info("password reset email sent", "user_id", record.UserID)
+	return nil
+}
+
+// ResetPassword sets a new password for the account whose pending reset
+// token this is, ends its other sessions, and signs the user in. The token
+// works once and only until its expiry.
+func (s *Service) ResetPassword(token, password string) (*User, string, error) {
+	if s.store == nil {
+		return nil, "", ErrStorageDisabled
+	}
+	if raw, err := base64.RawURLEncoding.DecodeString(token); err != nil || len(raw) != resetTokenBytes {
+		return nil, "", ErrResetInvalid
+	}
+	now := time.Now().UTC()
+	userID, err := s.store.ConsumePasswordReset(hashResetToken(token), now)
+	if err != nil {
+		if errors.Is(err, sql.ErrNoRows) {
+			return nil, "", ErrResetInvalid
+		}
+		return nil, "", fmt.Errorf("%w: consume reset: %v", ErrStorageUnavailable, err)
+	}
+
+	passwordHash, err := s.hashPassword(password)
+	if err != nil {
+		if errors.Is(err, ErrAuthBusy) {
+			return nil, "", err
+		}
+		return nil, "", fmt.Errorf("failed to hash password: %w", err)
+	}
+	if err := s.store.ResetUserPassword(userID, passwordHash); err != nil {
+		if errors.Is(err, sql.ErrNoRows) {
+			return nil, "", ErrResetInvalid
+		}
+		return nil, "", fmt.Errorf("%w: reset password: %v", ErrStorageUnavailable, err)
+	}
+	record, err := s.store.GetUserByID(userID)
+	if err != nil {
+		return nil, "", fmt.Errorf("%w: look up user: %v", ErrStorageUnavailable, err)
+	}
+	sessionID := uuid.NewString()
+	if err := s.store.CreateSession(storage.SessionRecord{
+		SessionID: sessionID, UserID: userID, CreatedAt: now, ExpiresAt: now.Add(SessionTTL),
+	}); err != nil {
+		return nil, "", fmt.Errorf("%w: create session: %v", ErrStorageUnavailable, err)
+	}
+	slog.Info("password reset completed", "user_id", userID)
+	return &User{
+		UserID: record.UserID, Username: record.Username, Email: record.Email, CreatedAt: record.CreatedAt,
+	}, sessionID, nil
+}

internal/server/service/reset_test.go

@@ -0,0 +1,147 @@
+package service
+
+import (
+	"errors"
+	"os"
+	"path/filepath"
+	"regexp"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/lixenwraith/chess/internal/server/mail"
+	"github.com/lixenwraith/chess/internal/server/storage"
+)
+
+var linkPattern = regexp.MustCompile(`https://example\.test/chess/web-client/\?reset=([A-Za-z0-9_-]{43})`)
+
+func TestPasswordResetFlow(t *testing.T) {
+	svc := newPersistentTestService(t)
+	if svc.MailHealth() != "disabled" {
+		t.Fatal("mail reported before configuration")
+	}
+	if err := svc.RequestPasswordReset("alice"); !errors.Is(err, ErrMailDisabled) {
+		t.Fatalf("recovery without mail: %v", err)
+	}
+	dir := filepath.Join(t.TempDir(), "mail")
+	if err := svc.SetMailer(&mail.Dir{Path: dir, From: "chess@example.test"}, "/chess/"); err == nil {
+		t.Fatal("relative public URL accepted")
+	}
+	if err := svc.SetMailer(&mail.Dir{Path: dir, From: "chess@example.test"}, "https://example.test/chess/web-client/"); err != nil {
+		t.Fatal(err)
+	}
+	if svc.MailHealth() != "ok" {
+		t.Fatal("mail not reported ok")
+	}
+
+	user, sessionID, err := svc.RegisterUser("alice", "Alice@Example.test", "Password1")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, _, err := svc.RegisterUser("bob", "", "Password1"); err != nil {
+		t.Fatal(err)
+	}
+
+	// Unknown accounts and accounts without email get the same answer and no mail.
+	for _, id := range []string{"nobody", "nobody@example.test", "bob"} {
+		if err := svc.RequestPasswordReset(id); err != nil {
+			t.Errorf("recover %q: %v", id, err)
+		}
+	}
+	if entries, _ := os.ReadDir(dir); len(entries) != 0 {
+		t.Fatalf("mail sent for unknown accounts: %d files", len(entries))
+	}
+
+	// By email, case-insensitively; then by username, which replaces the link.
+	if err := svc.RequestPasswordReset("ALICE@example.test"); err != nil {
+		t.Fatal(err)
+	}
+	first := lastMailToken(t, dir)
+	if err := svc.RequestPasswordReset("alice"); err != nil {
+		t.Fatal(err)
+	}
+	token := lastMailToken(t, dir)
+	if token == first {
+		t.Fatal("second request reused the token")
+	}
+	if _, _, err := svc.ResetPassword(first, "Password2"); !errors.Is(err, ErrResetInvalid) {
+		t.Errorf("replaced token: %v", err)
+	}
+	for _, bad := range []string{"", "x", strings.Repeat("A", 43), token + "A"} {
+		if _, _, err := svc.ResetPassword(bad, "Password2"); !errors.Is(err, ErrResetInvalid) {
+			t.Errorf("token %q: %v", bad, err)
+		}
+	}
+
+	reset, newSession, err := svc.ResetPassword(token, "Password2")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if reset.UserID != user.UserID || reset.Username != "alice" || newSession == "" || newSession == sessionID {
+		t.Fatalf("reset returned %+v, session %q", reset, newSession)
+	}
+	if _, _, err := svc.ResetPassword(token, "Password3"); !errors.Is(err, ErrResetInvalid) {
+		t.Errorf("token reused: %v", err)
+	}
+	// The old session is gone, the new one and the new password work.
+	if _, _, err := svc.ValidateToken(mustToken(t, svc, user.UserID, sessionID)); err == nil {
+		t.Error("old session still valid")
+	}
+	if _, _, err := svc.ValidateToken(mustToken(t, svc, user.UserID, newSession)); err != nil {
+		t.Errorf("new session invalid: %v", err)
+	}
+	if _, _, err := svc.AuthenticateUser("alice", "Password1"); !errors.Is(err, ErrInvalidCredentials) {
+		t.Errorf("old password: %v", err)
+	}
+	if _, _, err := svc.AuthenticateUser("alice", "Password2"); err != nil {
+		t.Errorf("new password: %v", err)
+	}
+
+	// An expired link is refused and the cleanup removes it.
+	expired, hash, err := NewResetToken()
+	if err != nil {
+		t.Fatal(err)
+	}
+	past := time.Now().UTC().Add(-time.Minute)
+	if err := svc.store.CreatePasswordReset(storage.PasswordResetRecord{
+		UserID: user.UserID, TokenHash: hash, CreatedAt: past.Add(-time.Hour), ExpiresAt: past,
+	}); err != nil {
+		t.Fatal(err)
+	}
+	if _, _, err := svc.ResetPassword(expired, "Password4"); !errors.Is(err, ErrResetInvalid) {
+		t.Errorf("expired token: %v", err)
+	}
+	if deleted, err := svc.store.DeleteExpiredPasswordResets(); err != nil || deleted != 1 {
+		t.Errorf("expired resets deleted = %d, %v", deleted, err)
+	}
+}
+
+func lastMailToken(t *testing.T, dir string) string {
+	t.Helper()
+	entries, err := os.ReadDir(dir)
+	if err != nil || len(entries) == 0 {
+		t.Fatalf("no mail in %s: %v", dir, err)
+	}
+	data, err := os.ReadFile(filepath.Join(dir, entries[len(entries)-1].Name()))
+	if err != nil {
+		t.Fatal(err)
+	}
+	text := string(data)
+	if !strings.Contains(text, "To: alice@example.test\r\n") || !strings.Contains(text, "Subject: Reset your chess password\r\n") {
+		t.Fatalf("mail = %q", text)
+	}
+	m := linkPattern.FindStringSubmatch(text)
+	if m == nil {
+		t.Fatalf("no reset link in %q", text)
+	}
+	return m[1]
+}
+
+func mustToken(t *testing.T, svc *Service, userID, sessionID string) string {
+	t.Helper()
+	token, err := svc.GenerateUserToken(userID, sessionID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return token
+}

internal/server/service/service.go

@@ -41,6 +41,8 @@ type Service struct {
 
 	integrityMode   IntegrityMode
 	integrityCursor string // last game ID the integrity sweep verified; cleanup goroutine only
+
+	mail *mailer // password recovery; nil when no transport is configured
 }
 
 // New creates a service with optional storage. jwtSecret signs session tokens
@@ -193,6 +195,11 @@ func (s *Service) cleanupExpired() {
 		} else if deleted > 0 {
 			slog.Info("cleanup deleted expired sessions", "count", deleted)
 		}
+		if deleted, err := s.store.DeleteExpiredPasswordResets(); err != nil {
+			slog.Error("cleanup failed to delete expired password resets", "error", err)
+		} else if deleted > 0 {
+			slog.Info("cleanup deleted expired password resets", "count", deleted)
+		}
 	}
 	s.cleanupGames(now)
 	s.checkIntegrity(now)

internal/server/storage/reset.go

@@ -0,0 +1,120 @@
+package storage
+
+import (
+	"database/sql"
+	"errors"
+	"fmt"
+	"log/slog"
+	"time"
+)
+
+// PasswordResetRecord is a pending password reset: the SHA-256 of the token
+// sent to the account's email, and when it stops working.
+type PasswordResetRecord struct {
+	UserID    string
+	TokenHash []byte
+	CreatedAt time.Time
+	ExpiresAt time.Time
+}
+
+// CreatePasswordReset stores a reset for the user, replacing any pending one,
+// so only the latest link works. It returns sql.ErrNoRows for an unknown
+// user.
+func (s *Store) CreatePasswordReset(record PasswordResetRecord) error {
+	if !validUUID(record.UserID) {
+		return sql.ErrNoRows
+	}
+	if len(record.TokenHash) != 32 {
+		return errors.New("token hash must be 32 bytes")
+	}
+	ctx, cancel := opContext()
+	defer cancel()
+	result, err := s.db.ExecContext(ctx, `INSERT INTO password_resets (user_id, token_hash, created_at, expires_at)
+		SELECT user_id, $2, $3, $4 FROM users WHERE user_id = $1
+		ON CONFLICT (user_id) DO UPDATE SET
+			token_hash = excluded.token_hash,
+			created_at = excluded.created_at,
+			expires_at = excluded.expires_at`,
+		record.UserID, record.TokenHash, record.CreatedAt, record.ExpiresAt)
+	if err != nil {
+		return fmt.Errorf("create password reset: %w", err)
+	}
+	if rows, err := result.RowsAffected(); err != nil {
+		return err
+	} else if rows == 0 {
+		return sql.ErrNoRows
+	}
+	slog.Debug("storage password reset created", "user_id", record.UserID, "expires_at", record.ExpiresAt)
+	return nil
+}
+
+// ConsumePasswordReset deletes the reset matching tokenHash and returns its
+// user, or sql.ErrNoRows when none is pending or it has expired. A token
+// works once.
+func (s *Store) ConsumePasswordReset(tokenHash []byte, now time.Time) (string, error) {
+	if len(tokenHash) != 32 {
+		return "", sql.ErrNoRows
+	}
+	ctx, cancel := opContext()
+	defer cancel()
+	var userID string
+	err := s.db.QueryRowContext(ctx,
+		`DELETE FROM password_resets WHERE token_hash = $1 AND expires_at > $2 RETURNING user_id`,
+		tokenHash, now.UTC()).Scan(&userID)
+	if err != nil {
+		return "", err
+	}
+	return userID, nil
+}
+
+// DeleteExpiredPasswordResets removes resets past their expiry.
+func (s *Store) DeleteExpiredPasswordResets() (int64, error) {
+	ctx, cancel := opContext()
+	defer cancel()
+	result, err := s.db.ExecContext(ctx, `DELETE FROM password_resets WHERE expires_at < $1`, time.Now().UTC())
+	if err != nil {
+		return 0, err
+	}
+	deleted, err := result.RowsAffected()
+	if err == nil && deleted > 0 {
+		slog.Debug("storage expired password resets deleted", "count", deleted)
+	}
+	return deleted, err
+}
+
+// ResetUserPassword sets a new password hash and ends the user's sessions in
+// one transaction: whoever held the old password is signed out everywhere.
+// It returns sql.ErrNoRows for an unknown user.
+func (s *Store) ResetUserPassword(userID, passwordHash string) error {
+	if !validUUID(userID) {
+		return sql.ErrNoRows
+	}
+	ctx, cancel := opContext()
+	defer cancel()
+	tx, err := s.db.BeginTx(ctx, nil)
+	if err != nil {
+		return fmt.Errorf("failed to begin transaction: %w", err)
+	}
+	defer tx.Rollback()
+
+	result, err := tx.ExecContext(ctx, `UPDATE users SET password_hash = $2 WHERE user_id = $1`, userID, passwordHash)
+	if err != nil {
+		return fmt.Errorf("update password: %w", err)
+	}
+	if rows, err := result.RowsAffected(); err != nil {
+		return err
+	} else if rows == 0 {
+		return sql.ErrNoRows
+	}
+	if _, err := tx.ExecContext(ctx, `DELETE FROM sessions WHERE user_id = $1`, userID); err != nil {
+		return fmt.Errorf("end sessions: %w", err)
+	}
+	if _, err := tx.ExecContext(ctx, `DELETE FROM password_resets WHERE user_id = $1`, userID); err != nil {
+		return fmt.Errorf("clear password resets: %w", err)
+	}
+	if err := tx.Commit(); err != nil {
+		return err
+	}
+	slog.Debug("storage password reset", "user_id", userID)
+	return nil
+}

internal/server/storage/schema.go

@@ -81,7 +81,7 @@ type MovePersistence struct {
 // schemaVersion is the newest schema this binary understands. Migrations are
 // applied in order inside one transaction; PostgreSQL DDL is transactional, so
 // a failed upgrade leaves the previous version intact.
-const schemaVersion = 3
+const schemaVersion = 4
 
 // migrations[v-1] upgrades the schema from version v-1 to v. Never edit a
 // released migration; append a new one.
@@ -212,8 +212,23 @@ ALTER TABLE games ADD CONSTRAINT games_concession_check CHECK (
 	OR (concession_ply >= 0 AND concession_time_utc IS NOT NULL AND (
 		(concession_result IN ('white_wins', 'black_wins') AND concession_termination = 'resignation')
 		OR (concession_result = 'draw' AND concession_termination = 'agreement'))));
+`,
+
+	// v4: password recovery. One pending reset per account; the token the
+	// email carries is never stored, only its SHA-256, and it expires after
+	// an hour. Consuming a token deletes the row.
+	`
+CREATE TABLE password_resets (
+	user_id    uuid PRIMARY KEY REFERENCES users (user_id) ON DELETE CASCADE,
+	token_hash bytea NOT NULL,
+	created_at timestamptz NOT NULL DEFAULT now(),
+	expires_at timestamptz NOT NULL,
+	CONSTRAINT password_resets_token_hash_key UNIQUE (token_hash),
+	CONSTRAINT password_resets_token_hash_check CHECK (octet_length(token_hash) = 32)
+);
+CREATE INDEX password_resets_expires_at_idx ON password_resets (expires_at);
 `,
 }
 
 // ownedTables lists every table created by migrations, children first.
-var ownedTables = []string{"moves", "games", "sessions", "users", "schema_version"}
+var ownedTables = []string{"moves", "games", "password_resets", "sessions", "users", "schema_version"}

internal/server/webserver/chess-client-web/index.html

@@ -3,86 +3,218 @@
 <head>
     <meta charset="UTF-8">
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <title>Chess Game</title>
+    <meta name="color-scheme" content="dark">
+    <title>Chess</title>
     <link rel="stylesheet" href="style.css">
 </head>
-<body>
+<body data-mode="live">
-<div class="outer-container">
+<div class="app">
-    <div class="container">
+    <header class="topbar">
-        <main>
+        <div class="brand" aria-label="Chess">
-            <div class="game-area">
+            <svg class="brand-mark" viewBox="41 34 430 430" aria-hidden="true" focusable="false">
-                <div class="board-container">
+                <defs>
-                    <div class="board-wrapper">
+                    <linearGradient id="brand-piece" x1="20%" y1="0%" x2="80%" y2="100%">
-                        <div class="coordinates top">
+                        <stop offset="0%" stop-color="#C8CDD6"/>
-                            <span>a</span><span>b</span><span>c</span><span>d</span>
+                        <stop offset="45%" stop-color="#8B929E"/>
-                            <span>e</span><span>f</span><span>g</span><span>h</span>
+                        <stop offset="100%" stop-color="#4F545D"/>
-                        </div>
+                    </linearGradient>
-                        <div class="coordinates left">
+                </defs>
-                            <span>8</span><span>7</span><span>6</span><span>5</span>
+                <g fill="url(#brand-piece)" stroke="#14161A" stroke-width="4" stroke-linejoin="round">
-                            <span>4</span><span>3</span><span>2</span><span>1</span>
+                    <path d="M136 450Q256 465 376 450L346 410Q256 420 166 410Z"/>
-                        </div>
+                    <path d="M166 410Q256 420 346 410L316 370Q256 380 196 370Z"/>
-                        <div id="board"></div>
+                    <path d="M196 370Q256 380 316 370C300 290 286 230 282 205H230C226 230 212 290 196 370Z"/>
-                    </div>
+                </g>
+                <path d="M330 90Q265 96 230 120Q265 144 335 150Z" fill="#111318"/>
+                <g stroke="#F0F2F5" stroke-width="6" stroke-linecap="round">
+                    <path d="M263.17 85V155M299.33 85V155"/>
+                </g>
+                <g fill="url(#brand-piece)" stroke="#14161A" stroke-width="4" stroke-linejoin="round">
+                    <path d="M226 200C150 180 150 70 256 40C290 50 315 65 330 90Q265 96 230 120Q265 144 335 150C335 170 315 190 286 200Z"/>
+                    <rect x="216" y="195" width="80" height="16" rx="8"/>
+                </g>
+            </svg>
+            <span class="brand-name">Chess</span>
+        </div>
+        <div class="health" aria-label="Server status">
+            <span class="dot" id="server-dot" data-status="unknown" title="Server: unknown" role="img" aria-label="Server: unknown"></span>
+            <span class="dot" id="storage-dot" data-status="unknown" title="Storage: unknown" role="img" aria-label="Storage: unknown"></span>
+        </div>
+        <div class="topbar-spacer"></div>
+        <button id="games-btn" class="btn btn-ghost btn-sm" type="button" title="Stored games">
+            <svg class="icon" viewBox="0 0 24 24" aria-hidden="true"><path d="M4 6h16M4 12h16M4 18h10" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"/></svg>
+            <span>My games</span>
+        </button>
+        <button id="auth-btn" class="btn btn-ghost btn-sm" type="button" data-status="anonymous" title="Sign in or register">
+            <span class="dot" id="auth-dot" data-status="anonymous" aria-hidden="true"></span>
+            <span id="auth-label">Sign in</span>
+        </button>
+    </header>
+
+    <main class="workspace">
+        <section class="board-area" aria-label="Board">
+            <div class="board-wrapper">
+                <div class="coordinates files" aria-hidden="true"></div>
+                <div class="coordinates ranks" aria-hidden="true"></div>
+                <div id="board" role="grid" aria-label="Chess board"></div>
+            </div>
+            <div class="toast-host"><div id="toast" class="toast" role="status" aria-live="polite"></div></div>
+        </section>
+
+        <aside class="panel" aria-label="Game panel">
+            <!-- Live game -->
+            <div class="pane pane-live" id="pane-live">
+                <div class="turn-strip" id="turn-strip">
+                    <span class="dot turn-dot" id="turn-dot" data-status="idle" aria-hidden="true"></span>
+                    <span class="turn-text" id="turn-text">No game</span>
+                </div>
+                <div class="controls" role="group" aria-label="Game controls">
+                    <button id="new-game-btn" class="btn btn-primary" type="button" title="New game">New</button>
+                    <button id="undo-btn" class="btn btn-secondary" type="button" disabled>Undo</button>
+                    <button id="draw-btn" class="btn btn-secondary" type="button" title="Offer a draw" disabled>Draw</button>
+                    <button id="resign-btn" class="btn btn-secondary" type="button" title="Resign this game" disabled>Resign</button>
+                </div>
+                <div class="moves" id="live-moves-box">
+                    <div class="move-grid" id="live-moves" aria-label="Moves"></div>
+                    <p class="moves-empty" id="live-moves-empty">Start a game to play Stockfish, or open <strong>My games</strong> to replay one.</p>
+                </div>
+                <div class="toolbar" role="group" aria-label="Export">
+                    <button id="copy-fen-btn" class="btn btn-tool" type="button" title="Copy the current position as FEN" disabled>
+                        <svg class="icon" viewBox="0 0 24 24" aria-hidden="true"><rect x="9" y="9" width="11" height="11" rx="2" fill="none" stroke="currentColor" stroke-width="2"/><path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1" fill="none" stroke="currentColor" stroke-width="2"/></svg>
+                        <span>FEN</span>
+                    </button>
+                    <button id="copy-pgn-btn" class="btn btn-tool" type="button" title="Copy the game as PGN" disabled>
+                        <svg class="icon" viewBox="0 0 24 24" aria-hidden="true"><rect x="9" y="9" width="11" height="11" rx="2" fill="none" stroke="currentColor" stroke-width="2"/><path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1" fill="none" stroke="currentColor" stroke-width="2"/></svg>
+                        <span>PGN</span>
+                    </button>
+                    <button id="replay-live-btn" class="btn btn-tool" type="button" title="Replay this game from the start" disabled>
+                        <svg class="icon" viewBox="0 0 24 24" aria-hidden="true"><path d="M8 5v14l11-7z" fill="currentColor"/></svg>
+                        <span>Replay</span>
+                    </button>
                 </div>
             </div>
 
-            <aside class="info-panel">
+            <!-- Replay -->
-                <div class="status-indicators">
+            <div class="pane pane-replay" id="pane-replay">
-                    <div class="indicator" id="server-indicator" data-tooltip="Server">
+                <div class="replay-head">
-                        <span class="light" data-status="unknown">●</span>
+                    <div class="replay-title-row">
-                    </div>
+                        <span class="badge" id="replay-badge">Replay</span>
-                    <div class="indicator" id="storage-indicator" data-tooltip="Storage">
+                        <span class="replay-result" id="replay-result"></span>
-                        <span class="light" data-status="unknown">●</span>
+                        <span class="replay-ply" id="replay-ply" aria-hidden="true"></span>
-                    </div>
-                    <div class="indicator" id="turn-indicator" data-tooltip="Turn">
-                        <span class="light turn-light" data-status="white">●</span>
-                    </div>
-                    <div class="indicator auth-indicator" id="auth-indicator" data-tooltip="Auth">
-                        <span class="light" data-status="anonymous">●</span>
-                    </div>
-                    <div class="error-flash-overlay" id="error-flash-overlay">
-                        <div class="error-flash-message" id="error-flash-message"></div>
                     </div>
+                    <div class="replay-players" id="replay-players"></div>
+                    <div class="replay-meta" id="replay-meta"></div>
                 </div>
-
+                <div class="moves" id="replay-moves-box">
-                <div class="controls">
+                    <div class="move-grid move-grid-replay" id="replay-moves" aria-label="Moves"></div>
-                    <button id="new-game-btn" class="btn btn-primary">New</button>
+                    <p class="moves-empty" id="replay-moves-empty">Loading…</p>
-                    <button id="undo-btn" class="btn btn-secondary" disabled>Undo</button>
-                    <button id="draw-btn" class="btn btn-secondary" title="Offer a draw" disabled>Draw</button>
-                    <button id="resign-btn" class="btn btn-secondary" title="Resign this game" disabled>Resign</button>
                 </div>
-
+                <div class="replay-nav" role="group" aria-label="Replay controls">
-                <div class="move-history-container">
+                    <button id="replay-first" class="btn btn-nav" type="button" title="First position (Home)" aria-label="First position">
-                    <button class="copy-btn" id="copy-history" title="Copy PGN">
+                        <svg class="icon" viewBox="0 0 24 24" aria-hidden="true"><path d="M6 5v14M18 5l-9 7 9 7z" fill="currentColor" stroke="currentColor" stroke-width="2" stroke-linejoin="round"/></svg>
-                        <svg viewBox="0 0 24 24" width="16" height="16">
+                    </button>
-                            <rect x="9" y="9" width="13" height="13" rx="2" fill="none" stroke="currentColor" stroke-width="2"/>
+                    <button id="replay-prev" class="btn btn-nav" type="button" title="Previous move (←)" aria-label="Previous move">
-                            <path d="M5 15H4a2 2 0 01-2-2V4a2 2 0 012-2h9a2 2 0 012 2v1" fill="none" stroke="currentColor" stroke-width="2"/>
+                        <svg class="icon" viewBox="0 0 24 24" aria-hidden="true"><path d="M16 5l-9 7 9 7z" fill="currentColor" stroke="currentColor" stroke-width="2" stroke-linejoin="round"/></svg>
-                        </svg>
+                    </button>
+                    <button id="replay-play" class="btn btn-nav btn-play" type="button" title="Autoplay (Space)" aria-label="Autoplay" aria-pressed="false">
+                        <svg class="icon icon-play" viewBox="0 0 24 24" aria-hidden="true"><path d="M8 5v14l11-7z" fill="currentColor"/></svg>
+                        <svg class="icon icon-pause" viewBox="0 0 24 24" aria-hidden="true"><path d="M7 5h4v14H7zM13 5h4v14h-4z" fill="currentColor"/></svg>
+                    </button>
+                    <button id="replay-next" class="btn btn-nav" type="button" title="Next move (→)" aria-label="Next move">
+                        <svg class="icon" viewBox="0 0 24 24" aria-hidden="true"><path d="M8 5l9 7-9 7z" fill="currentColor" stroke="currentColor" stroke-width="2" stroke-linejoin="round"/></svg>
+                    </button>
+                    <button id="replay-last" class="btn btn-nav" type="button" title="Last position (End)" aria-label="Last position">
+                        <svg class="icon" viewBox="0 0 24 24" aria-hidden="true"><path d="M18 5v14M6 5l9 7-9 7z" fill="currentColor" stroke="currentColor" stroke-width="2" stroke-linejoin="round"/></svg>
+                    </button>
+                    <label class="speed" title="Autoplay speed">
+                        <span class="visually-hidden">Autoplay speed</span>
+                        <select id="replay-speed">
+                            <option value="2000">0.5×</option>
+                            <option value="1000" selected>1×</option>
+                            <option value="500">2×</option>
+                            <option value="250">4×</option>
+                        </select>
+                    </label>
+                    <button id="replay-flip" class="btn btn-nav" type="button" title="Flip the board (F)" aria-label="Flip the board" aria-pressed="false">
+                        <svg class="icon" viewBox="0 0 24 24" aria-hidden="true"><path d="M7 4v12M7 16l-3-3M7 16l3-3M17 20V8M17 8l-3 3M17 8l3 3" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/></svg>
                     </button>
-                    <div id="move-history" class="move-history">
-                        <div class="move-grid" id="move-grid"></div>
-                    </div>
                 </div>
+                <div class="toolbar" role="group" aria-label="Export at this position">
+                    <button id="replay-copy-fen" class="btn btn-tool" type="button" title="Copy the FEN of this position">
+                        <svg class="icon" viewBox="0 0 24 24" aria-hidden="true"><rect x="9" y="9" width="11" height="11" rx="2" fill="none" stroke="currentColor" stroke-width="2"/><path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1" fill="none" stroke="currentColor" stroke-width="2"/></svg>
+                        <span>FEN</span>
+                    </button>
+                    <button id="replay-copy-pgn" class="btn btn-tool" type="button" title="Copy the PGN up to this position">
+                        <svg class="icon" viewBox="0 0 24 24" aria-hidden="true"><rect x="9" y="9" width="11" height="11" rx="2" fill="none" stroke="currentColor" stroke-width="2"/><path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1" fill="none" stroke="currentColor" stroke-width="2"/></svg>
+                        <span>PGN</span>
+                    </button>
+                    <button id="replay-download" class="btn btn-tool" type="button" title="Download the PGN up to this position">
+                        <svg class="icon" viewBox="0 0 24 24" aria-hidden="true"><path d="M12 4v11M7 10l5 5 5-5M5 19h14" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/></svg>
+                        <span>Save</span>
+                    </button>
+                    <button id="replay-link" class="btn btn-tool" type="button" title="Copy a link to this position">
+                        <svg class="icon" viewBox="0 0 24 24" aria-hidden="true"><path d="M10 14a4 4 0 0 0 5.66 0l3-3a4 4 0 0 0-5.66-5.66l-1.5 1.5M14 10a4 4 0 0 0-5.66 0l-3 3a4 4 0 0 0 5.66 5.66l1.5-1.5" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"/></svg>
+                        <span>Link</span>
+                    </button>
+                </div>
+                <button id="replay-exit" class="btn btn-secondary btn-block" type="button">Back to live game</button>
+                <div id="ply-announcer" class="visually-hidden" aria-live="polite" aria-atomic="true"></div>
+            </div>
+        </aside>
+    </main>
+</div>
 
-            </aside>
+<!-- My games drawer -->
-        </main>
+<div id="games-overlay" class="modal-overlay">
+    <div class="modal games-modal" role="dialog" aria-modal="true" aria-labelledby="games-title">
+        <div class="modal-head">
+            <h2 id="games-title">My games</h2>
+            <button id="games-close" class="btn btn-icon" type="button" aria-label="Close">
+                <svg class="icon" viewBox="0 0 24 24" aria-hidden="true"><path d="M6 6l12 12M18 6L6 18" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"/></svg>
+            </button>
+        </div>
+        <div class="games-filters" id="games-filters">
+            <div class="segmented" role="group" aria-label="Status">
+                <button type="button" class="seg active" data-filter="status" data-value="">All</button>
+                <button type="button" class="seg" data-filter="status" data-value="ongoing">Ongoing</button>
+                <button type="button" class="seg" data-filter="status" data-value="finished">Finished</button>
+            </div>
+            <div class="segmented" role="group" aria-label="Your colour">
+                <button type="button" class="seg active" data-filter="color" data-value="">Any</button>
+                <button type="button" class="seg" data-filter="color" data-value="white">White</button>
+                <button type="button" class="seg" data-filter="color" data-value="black">Black</button>
+            </div>
+        </div>
+        <div class="games-body">
+            <section class="games-section" id="account-games-section">
+                <h3 class="games-heading" id="account-games-heading">Your games</h3>
+                <p class="games-note" id="games-signin-note">Sign in to keep your games and replay them here. Games played anonymously are kept for 24 hours.</p>
+                <ul class="games-list" id="games-list"></ul>
+                <p class="games-status" id="games-status" role="status"></p>
+                <button id="games-more" class="btn btn-secondary btn-block" type="button">Load more</button>
+            </section>
+            <section class="games-section" id="local-games-section">
+                <h3 class="games-heading">On this device</h3>
+                <p class="games-note">Games played here without signing in; the server keeps them for 24 hours after the last move.</p>
+                <ul class="games-list" id="local-games-list"></ul>
+            </section>
+        </div>
     </div>
 </div>
 
 <!-- Auth Modal -->
 <div id="auth-modal-overlay" class="modal-overlay">
-    <div class="modal auth-modal">
+    <div class="modal auth-modal" role="dialog" aria-modal="true" aria-labelledby="auth-title">
-        <div class="auth-tabs">
+        <h2 id="auth-title" class="visually-hidden">Account</h2>
-            <button class="auth-tab active" data-tab="login">Login</button>
+        <div class="auth-tabs" role="tablist">
-            <button class="auth-tab" data-tab="register">Register</button>
+            <button class="auth-tab active" type="button" role="tab" data-tab="login" aria-selected="true">Sign in</button>
+            <button class="auth-tab" type="button" role="tab" data-tab="register" aria-selected="false">Register</button>
         </div>
 
-        <div id="auth-modal-message" class="modal-message"></div>
+        <div id="auth-modal-message" class="modal-message" role="status" aria-live="polite"></div>
 
-        <!-- Login Form -->
         <div id="login-form" class="auth-form">
             <div class="form-group">
-                <label for="login-identifier">Username or Email</label>
+                <label for="login-identifier">Username or email</label>
                 <input type="text" id="login-identifier" autocomplete="username">
             </div>
             <div class="form-group">
@@ -90,13 +222,25 @@
                 <input type="password" id="login-password" autocomplete="current-password">
             </div>
             <div class="modal-buttons">
-                <button id="login-submit-btn" class="btn btn-primary">Login</button>
+                <button id="login-submit-btn" class="btn btn-primary" type="button">Sign in</button>
-                <button id="auth-cancel-btn" class="btn btn-secondary">Cancel</button>
+                <button id="auth-cancel-btn" class="btn btn-secondary" type="button">Cancel</button>
+            </div>
+            <p class="auth-aside hidden" id="forgot-row"><button id="forgot-btn" class="link-btn" type="button">Forgot password?</button></p>
+        </div>
+
+        <div id="recover-form" class="auth-form hidden">
+            <p class="auth-help">Enter your username or email. If the account has an email address, a link to choose a new password is sent to it; the link works for an hour.</p>
+            <div class="form-group">
+                <label for="recover-identifier">Username or email</label>
+                <input type="text" id="recover-identifier" autocomplete="username">
+            </div>
+            <div class="modal-buttons">
+                <button id="recover-submit-btn" class="btn btn-primary" type="button">Send reset link</button>
+                <button id="recover-back-btn" class="btn btn-secondary" type="button">Back</button>
             </div>
         </div>
 
-        <!-- Register Form -->
+        <div id="register-form" class="auth-form hidden">
-        <div id="register-form" class="auth-form" style="display: none;">
             <div class="form-group">
                 <label for="register-username">Username</label>
                 <input type="text" id="register-username" autocomplete="username">
@@ -106,17 +250,37 @@
                 <input type="email" id="register-email" autocomplete="email">
             </div>
             <div class="form-group">
-                <label for="register-password">Password (min 8 chars)</label>
+                <label for="register-password">Password (8+ characters, a letter and a number)</label>
                 <input type="password" id="register-password" autocomplete="new-password">
             </div>
             <div class="modal-buttons">
-                <button id="register-submit-btn" class="btn btn-primary">Register</button>
+                <button id="register-submit-btn" class="btn btn-primary" type="button">Register</button>
-                <button id="auth-cancel-btn-2" class="btn btn-secondary">Cancel</button>
+                <button id="auth-cancel-btn-2" class="btn btn-secondary" type="button">Cancel</button>
             </div>
         </div>
     </div>
 </div>
 
+<!-- Reset Modal: opened by the link in the recovery email (?reset=<token>) -->
+<div id="reset-overlay" class="modal-overlay">
+    <div class="modal auth-modal" role="dialog" aria-modal="true" aria-labelledby="reset-title">
+        <h2 id="reset-title">Choose a new password</h2>
+        <div id="reset-modal-message" class="modal-message" role="status" aria-live="polite"></div>
+        <div class="form-group">
+            <label for="reset-password">New password (8+ characters, a letter and a number)</label>
+            <input type="password" id="reset-password" autocomplete="new-password">
+        </div>
+        <div class="form-group">
+            <label for="reset-password-2">Repeat the password</label>
+            <input type="password" id="reset-password-2" autocomplete="new-password">
+        </div>
+        <div class="modal-buttons">
+            <button id="reset-submit-btn" class="btn btn-primary" type="button">Set password</button>
+            <button id="reset-cancel-btn" class="btn btn-secondary" type="button">Cancel</button>
+        </div>
+    </div>
+</div>
+
 <!-- Account Modal: shown instead of the login modal while signed in -->
 <div id="account-overlay" class="modal-overlay">
     <div class="modal account-modal" role="dialog" aria-modal="true" aria-labelledby="account-title">
@@ -124,8 +288,8 @@
         <div id="account-modal-message" class="modal-message" role="status" aria-live="polite"></div>
         <p class="account-name">Signed in as <strong id="account-username"></strong></p>
         <div class="modal-buttons">
-            <button id="logout-btn" class="btn btn-primary">Log out</button>
+            <button id="logout-btn" class="btn btn-primary" type="button">Sign out</button>
-            <button id="account-cancel-btn" class="btn btn-secondary">Close</button>
+            <button id="account-cancel-btn" class="btn btn-secondary" type="button">Close</button>
         </div>
         <details class="danger-zone" id="delete-account">
             <summary>Delete account</summary>
@@ -137,40 +301,40 @@
                 <input type="password" id="delete-password" autocomplete="current-password">
             </div>
             <div class="modal-buttons">
-                <button id="delete-account-btn" class="btn btn-danger">Delete account</button>
+                <button id="delete-account-btn" class="btn btn-danger" type="button">Delete account</button>
             </div>
         </details>
     </div>
 </div>
 
-<!-- Overlay Modal -->
+<!-- New Game Modal -->
 <div id="modal-overlay" class="modal-overlay">
-    <div class="modal">
+    <div class="modal" role="dialog" aria-modal="true" aria-labelledby="new-game-title">
-        <h2>New Game</h2>
+        <h2 id="new-game-title">New game</h2>
         <div id="new-game-modal-message" class="modal-message" role="status" aria-live="polite"></div>
         <div class="form-group form-row">
-            <span class="group-label" id="player-color-label">Your Color</span>
+            <span class="group-label" id="player-color-label">Your colour</span>
             <div class="radio-group" role="radiogroup" aria-labelledby="player-color-label">
                 <label><input type="radio" name="player-color" value="white" checked><span>White</span></label>
                 <label><input type="radio" name="player-color" value="black"><span>Black</span></label>
             </div>
         </div>
         <div class="form-group">
-            <label for="computer-level">Computer Level: <span id="level-value">10</span></label>
+            <label for="computer-level">Computer level: <span id="level-value">10</span></label>
             <input type="range" id="computer-level" min="0" max="20" value="10">
         </div>
         <div class="form-group">
-            <label for="search-time">Search Time (ms): <span id="time-value">1000</span></label>
+            <label for="search-time">Search time: <span id="time-value">1000</span> ms</label>
             <input type="range" id="search-time" min="100" max="10000" step="100" value="1000">
         </div>
         <div class="form-group">
-            <label for="starting-fen">Starting Position (FEN)</label>
+            <label for="starting-fen">Starting position (FEN)</label>
-            <textarea id="starting-fen" class="fen-input" rows="2"
+            <textarea id="starting-fen" class="fen-input" rows="2" spellcheck="false"
                       placeholder="Enter FEN notation">rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1</textarea>
         </div>
         <div class="modal-buttons">
-            <button id="start-game-btn" class="btn btn-primary">Start Game</button>
+            <button id="start-game-btn" class="btn btn-primary" type="button">Start game</button>
-            <button id="cancel-btn" class="btn btn-secondary">Cancel</button>
+            <button id="cancel-btn" class="btn btn-secondary" type="button">Cancel</button>
         </div>
     </div>
 </div>
@@ -180,8 +344,8 @@
     <div class="modal confirm-modal" role="dialog" aria-modal="true" aria-labelledby="resign-title">
         <h2 id="resign-title">Resign this game?</h2>
         <div class="modal-buttons">
-            <button id="resign-confirm-btn" class="btn btn-primary">Resign</button>
+            <button id="resign-confirm-btn" class="btn btn-primary" type="button">Resign</button>
-            <button id="resign-cancel-btn" class="btn btn-secondary">Cancel</button>
+            <button id="resign-cancel-btn" class="btn btn-secondary" type="button">Cancel</button>
         </div>
     </div>
 </div>
@@ -191,13 +355,13 @@
     <div class="modal promotion-modal" role="dialog" aria-modal="true" aria-labelledby="promotion-title">
         <h2 id="promotion-title">Promote to</h2>
         <div class="promotion-choices">
-            <button class="promotion-choice" data-piece="q" title="Queen (Q)" aria-label="Queen">♛</button>
+            <button class="promotion-choice" type="button" data-piece="q" title="Queen (Q)" aria-label="Queen">♛</button>
-            <button class="promotion-choice" data-piece="r" title="Rook (R)" aria-label="Rook">♜</button>
+            <button class="promotion-choice" type="button" data-piece="r" title="Rook (R)" aria-label="Rook">♜</button>
-            <button class="promotion-choice" data-piece="b" title="Bishop (B)" aria-label="Bishop">♝</button>
+            <button class="promotion-choice" type="button" data-piece="b" title="Bishop (B)" aria-label="Bishop">♝</button>
-            <button class="promotion-choice" data-piece="n" title="Knight (N)" aria-label="Knight">♞</button>
+            <button class="promotion-choice" type="button" data-piece="n" title="Knight (N)" aria-label="Knight">♞</button>
         </div>
         <div class="modal-buttons">
-            <button id="promotion-cancel-btn" class="btn btn-secondary">Cancel</button>
+            <button id="promotion-cancel-btn" class="btn btn-secondary" type="button">Cancel</button>
         </div>
     </div>
 </div>

test/README.md

@@ -38,9 +38,12 @@ The server runs with `-dev`, debug logging, HTTP request logging, and relaxed ra
 It drops the test tables on exit, so it's preferred for clean testing.
 Can be used for all the tests.
 
-Logging can be adjusted without editing the script:
+Logging can be adjusted without editing the script; `WEB_PORT` also serves
+the embedded web client and `MAIL_DIR` turns on password recovery with the
+email written to that directory (both used by the end-to-end suite):
 ```bash
 LOG_LEVEL=info LOG_HTTP=false test/run-test-server.sh bin/chess-server
+WEB_PORT=9090 MAIL_DIR=/tmp/chess-mail test/run-test-server.sh bin/chess-server
 ```
 
 ### Pre-configured Users
@@ -83,6 +86,7 @@ curl -X POST http://localhost:8080/api/games \
 | End States | `test-endstate.sh` | Checkmate, stalemate, terminal custom positions |
 | Replay | `test-replay.sh` | SAN history, PGN export, ETag/304, promotion, FEN validation, cursor-paged listing |
 | Draws & Resignation | `test-draw.sh` | Automatic draws, offers (human and computer), resignation and authorization, long-poll wake-up, concessions and claim control, server version, hand-deleted game row |
+| Web client (end-to-end) | `e2e/` | Playwright in Chromium against the embedded web client: play, My games, replay controls and keyboard, autoplay, FEN/PGN export and download compared with the API, deep links, device list |
 | Test Server | `run-test-server.sh` | Pre-populated test environment |
 
 ## 1. API Functionality Tests (`test-api.sh`)
@@ -216,3 +220,43 @@ unknown route answered with `NOT_FOUND`, `/health` reporting the build, and a
 game whose row is deleted with
 psql (needs `CHESS_TEST_DSN` and `psql`; the server unloads the game and
 stays healthy).
+
+## Web client end-to-end tests (`e2e/`)
+
+Playwright drives the embedded web client in Chromium against a running
+server with PostgreSQL and Stockfish: it plays a short game, lists it under
+My games, replays it with the buttons and the keyboard, autoplays to the end,
+compares the FEN and PGN it exports (copy and download) with the API, follows
+a deep link to a checkmate, steps back through the browser history, replays
+an anonymous game from the device list, checks that a phone-sized viewport
+holds the board and the controls without scrolling, and resets a forgotten
+password through the link in the emailed message (needs `MAIL_DIR`).
+
+Requirements: Node.js 20+ and a Chromium that Playwright can run.
+
+```bash
+# Terminal 1: the test server with the web client and mail to a directory
+WEB_PORT=9090 MAIL_DIR=/tmp/chess-mail test/run-test-server.sh bin/chess-server
+
+# Terminal 2, once
+cd test/e2e && npm install && npx playwright install chromium
+
+# Terminal 2: run
+CHESS_E2E_MAIL_DIR=/tmp/chess-mail npm test   # or, from the repository root: make test-e2e
+```
+
+Environment:
+
+- `CHESS_E2E_WEB` (default `http://localhost:9090`): the web client's origin
+- `CHESS_E2E_API` (default `http://localhost:8080`): the API's origin, used
+  to register users, create games and fetch what the client should export
+- `CHESS_E2E_CHROMIUM`: path to a Chromium binary when
+  `npx playwright install` is not possible (an already installed browser)
+- `CHESS_E2E_MAIL_DIR`: the server's `-mail-dir` (`MAIL_DIR` of the test
+  server); the password-reset test reads the link from the newest file and
+  is skipped when unset
+
+Each test registers its own user or plays anonymously, so the suite can be
+repeated against the same server. The engine plays at level 0 with a 100 ms
+search, so a run takes about ten seconds. On failure Playwright keeps a trace
+under `test/e2e/test-results/`; open it with `npx playwright show-trace`.

test/e2e/.gitignore

@@ -0,0 +1,3 @@
+node_modules
+test-results
+playwright-report

test/e2e/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "chess-web-e2e",
+  "private": true,
+  "description": "Playwright end-to-end tests for the chess web client (see test/README.md)",
+  "scripts": {
+    "test": "playwright test"
+  },
+  "devDependencies": {
+    "@playwright/test": "1.57.0"
+  }
+}

test/e2e/playwright.config.js

@@ -0,0 +1,29 @@
+// Playwright configuration for the web client's end-to-end tests. The server
+// must already run with -serve and PostgreSQL (test/run-test-server.sh with
+// WEB_PORT, or any -dev -serve server): CHESS_E2E_WEB names the client's
+// origin and CHESS_E2E_API the API's. CHESS_E2E_CHROMIUM points at an
+// installed Chromium binary when `npx playwright install chromium` is not an
+// option.
+'use strict';
+const { defineConfig } = require('@playwright/test');
+
+const chromium = process.env.CHESS_E2E_CHROMIUM;
+
+module.exports = defineConfig({
+    testDir: '.',
+    testMatch: '*.spec.js',
+    timeout: 120_000,
+    expect: { timeout: 15_000 },
+    fullyParallel: false,
+    workers: 1,
+    retries: 0,
+    reporter: process.env.CI ? 'github' : 'list',
+    use: {
+        baseURL: process.env.CHESS_E2E_WEB || 'http://localhost:9090',
+        viewport: { width: 980, height: 480 },
+        permissions: ['clipboard-read', 'clipboard-write'],
+        acceptDownloads: true,
+        trace: 'retain-on-failure',
+        launchOptions: chromium ? { executablePath: chromium } : {},
+    },
+});

test/e2e/replay.spec.js

@@ -0,0 +1,288 @@
+// End-to-end: play a short game on the board, open My games, replay it with
+// the controls and the keyboard, autoplay to the end, and compare the
+// exported FEN and PGN with the API. Also the deep link, a checkmate's
+// replay, and the device list for an anonymous visitor.
+'use strict';
+const { test, expect } = require('@playwright/test');
+
+const API = process.env.CHESS_E2E_API || 'http://localhost:8080';
+// Where the server writes password-reset email (-mail-dir); the reset test
+// is skipped without it.
+const MAIL_DIR = process.env.CHESS_E2E_MAIL_DIR || '';
+const fs = require('fs');
+const path = require('path');
+const START_FEN = 'rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1';
+
+// The engine level and search time are set through the sliders' inputs.
+async function startGame(page, { color = 'white' } = {}) {
+    await page.click('#new-game-btn');
+    await expect(page.locator('#modal-overlay')).toHaveClass(/show/);
+    await page.locator('#computer-level').fill('0');
+    await page.locator('#search-time').fill('100');
+    await page.check(`input[name="player-color"][value="${color}"]`);
+    await page.click('#start-game-btn');
+    await expect(page.locator('#modal-overlay')).not.toHaveClass(/show/);
+}
+
+async function move(page, from, to) {
+    await page.click(`[data-square="${from}"]`);
+    await page.click(`[data-square="${to}"]`);
+}
+
+// Waits for the computer's reply: n plies in the list and the board free.
+async function expectPlies(page, n) {
+    await expect(page.locator('#live-moves .move')).toHaveCount(n, { timeout: 60_000 });
+    await expect(page.locator('#turn-text')).not.toContainText('thinking', { timeout: 60_000 });
+}
+
+async function register(page, request) {
+    const username = `e2e${Date.now().toString(36)}${Math.floor(Math.random() * 1000)}`;
+    const response = await request.post(`${API}/api/auth/register`, {
+        data: { username, password: 'Passw0rd123' },
+    });
+    expect(response.status(), await response.text()).toBe(201);
+    const auth = await response.json();
+    // The client restores a session from localStorage on load.
+    await page.addInitScript(token => localStorage.setItem('authToken', token), auth.token);
+    return { ...auth, password: 'Passw0rd123' };
+}
+
+test.describe('web replay', () => {
+    test('play, list, replay, export', async ({ page, request }) => {
+        const user = await register(page, request);
+        await page.goto('/');
+        await expect(page.locator('#auth-label')).toHaveText(user.username);
+
+        await startGame(page);
+        await move(page, 'e2', 'e4');
+        await expectPlies(page, 2);
+        await move(page, 'g1', 'f3');
+        await expectPlies(page, 4);
+        // The live list shows SAN from the server.
+        await expect(page.locator('#live-moves .move').first()).toHaveText('e4');
+        await expect(page.locator('#live-moves .move').nth(2)).toHaveText('Nf3');
+        const gameId = await page.evaluate(() => live.gameId);
+        const liveFen = await page.evaluate(() => live.fen);
+        const history = await (await request.get(`${API}/api/games/${gameId}/history`)).json();
+        expect(history.moves.map(m => m.san)).toEqual(await page.$$eval('#live-moves .move', els => els.map(e => e.textContent)));
+
+        // Copy PGN from the live view: the stored game's export.
+        await page.click('#copy-pgn-btn');
+        await expect(page.locator('#copy-pgn-btn')).toHaveClass(/done/);
+        const copied = await page.evaluate(() => navigator.clipboard.readText());
+        const apiPgn = await (await request.get(`${API}/api/games/${gameId}/pgn`)).text();
+        expect(copied).toBe(apiPgn);
+
+        // My games lists the game with the user's side named.
+        await page.click('#games-btn');
+        await expect(page.locator('#games-overlay')).toHaveClass(/show/);
+        const row = page.locator('#games-list .game-row').first();
+        await expect(row).toContainText('You vs Stockfish L0');
+        await expect(row).toContainText('Ongoing');
+        await expect(row).toHaveClass(/current/);
+        await expect(page).toHaveURL(/\?games$/);
+        await page.click('.seg[data-filter="status"][data-value="finished"]');
+        await expect(page.locator('#games-status')).toContainText('No games match');
+        await page.click('.seg[data-filter="status"][data-value=""]');
+        await expect(page.locator('#games-list .game-row')).toHaveCount(1);
+
+        // Replay from the list opens at the last ply; the live controls hide.
+        await row.click();
+        await expect(page.locator('body')).toHaveAttribute('data-mode', 'replay');
+        await expect(page.locator('#replay-ply')).toHaveText('4 / 4');
+        await expect(page).toHaveURL(new RegExp(`\\?replay=${gameId}&ply=4$`));
+        await expect(page.locator('#pane-live')).toBeHidden();
+        await expect(page.locator('#replay-moves .move[aria-current="true"]')).toHaveText(history.moves[3].san);
+
+        // Backward and forward: buttons, then the keyboard.
+        await page.click('#replay-first');
+        await expect(page.locator('#replay-ply')).toHaveText('0 / 4');
+        await expect(page.locator('#replay-first')).toBeDisabled();
+        await page.keyboard.press('ArrowRight');
+        await page.keyboard.press('ArrowRight');
+        await expect(page.locator('#replay-ply')).toHaveText('2 / 4');
+        await expect(page.locator('#ply-announcer')).toContainText('Ply 2 of 4');
+        await expect(page).toHaveURL(new RegExp(`ply=2$`));
+        await page.keyboard.press('ArrowLeft');
+        await expect(page.locator('#replay-ply')).toHaveText('1 / 4');
+        await page.keyboard.press('End');
+        await expect(page.locator('#replay-ply')).toHaveText('4 / 4');
+        await page.keyboard.press('Home');
+        await expect(page.locator('#replay-ply')).toHaveText('0 / 4');
+        await page.click('#replay-moves .move[data-ply="3"]');
+        await expect(page.locator('#replay-ply')).toHaveText('3 / 4');
+
+        // The exported FEN and PGN at ply 3 match the API.
+        await page.click('#replay-copy-fen');
+        expect(await page.evaluate(() => navigator.clipboard.readText())).toBe(history.moves[2].fenAfterMove);
+        await page.click('#replay-copy-pgn');
+        await expect(page.locator('#replay-copy-pgn')).toHaveClass(/done/);
+        const pgn3 = await (await request.get(`${API}/api/games/${gameId}/pgn?ply=3`)).text();
+        expect(await page.evaluate(() => navigator.clipboard.readText())).toBe(pgn3);
+        const downloadPromise = page.waitForEvent('download');
+        await page.click('#replay-download');
+        const download = await downloadPromise;
+        expect(download.suggestedFilename()).toMatch(/^chess-\d{8}-[0-9a-f]{8}-ply3\.pgn$/);
+        await page.click('#replay-link');
+        expect(await page.evaluate(() => navigator.clipboard.readText()))
+            .toBe(`${new URL(page.url()).origin}/?replay=${gameId}&ply=3`);
+
+        // Autoplay to the end at 4x, then pause state clears.
+        await page.selectOption('#replay-speed', '250');
+        await page.click('#replay-play');
+        await expect(page.locator('#replay-play')).toHaveAttribute('aria-pressed', 'true');
+        await expect(page.locator('#replay-ply')).toHaveText('4 / 4', { timeout: 10_000 });
+        await expect(page.locator('#replay-play')).toHaveAttribute('aria-pressed', 'false');
+
+        // Flip, then back to the live game, which continues where it was.
+        await page.click('#replay-flip');
+        await expect(page.locator('.coordinates.ranks span').first()).toHaveText('1');
+        await page.click('#replay-exit');
+        await expect(page.locator('body')).toHaveAttribute('data-mode', 'live');
+        await expect(page.locator('.coordinates.ranks span').first()).toHaveText('8');
+        expect(await page.evaluate(() => live.fen)).toBe(liveFen);
+        await expect(page.locator('#live-moves .move')).toHaveCount(4);
+        await move(page, 'b1', 'c3');
+        await expectPlies(page, 6);
+
+        // Browser history: back to the replay, back again to the list.
+        await page.goBack();
+        await expect(page.locator('body')).toHaveAttribute('data-mode', 'replay');
+        await page.goBack();
+        await expect(page.locator('#games-overlay')).toHaveClass(/show/);
+        await expect(page.locator('body')).toHaveAttribute('data-mode', 'live');
+    });
+
+    test('deep link to a checkmate replays with the mated king marked', async ({ page, request }) => {
+        // A human-vs-human game over the API: fool's mate.
+        const created = await request.post(`${API}/api/games`, { data: { white: { type: 1 }, black: { type: 1 } } });
+        expect(created.status()).toBe(201);
+        const { gameId } = await created.json();
+        for (const m of ['f2f3', 'e7e5', 'g2g4', 'd8h4']) {
+            const r = await request.post(`${API}/api/games/${gameId}/moves`, { data: { move: m } });
+            expect(r.status(), await r.text()).toBe(200);
+        }
+        await page.goto(`/?replay=${gameId}&ply=2`);
+        await expect(page.locator('body')).toHaveAttribute('data-mode', 'replay');
+        await expect(page.locator('#replay-ply')).toHaveText('2 / 4');
+        await expect(page.locator('#replay-result')).toContainText('0-1');
+        await expect(page.locator('#replay-result')).toContainText('Checkmate');
+        await expect(page.locator('#replay-exit')).toHaveText('Close replay');
+        await expect(page.locator('#replay-moves .move').nth(3)).toHaveText('Qh4#');
+        await page.keyboard.press('End');
+        await expect(page.locator('[data-square="e1"]')).toHaveClass(/mated-king/);
+        await expect(page.locator('[data-square="h4"]')).toHaveClass(/last-move-to/);
+        // Escape leaves the replay; with no live game the start position shows.
+        await page.keyboard.press('Escape');
+        await expect(page.locator('body')).toHaveAttribute('data-mode', 'live');
+        await expect(page.locator('#turn-text')).toHaveText('No game');
+        await expect(page).toHaveURL(/\/$/);
+    });
+
+    test('a phone fits the board and the controls without scrolling', async ({ browser }) => {
+        const context = await browser.newContext({ viewport: { width: 412, height: 780 }, isMobile: true, hasTouch: true });
+        const page = await context.newPage();
+        await page.goto('/');
+        const fits = () => page.evaluate(() => ({
+            w: document.documentElement.scrollWidth <= innerWidth,
+            h: document.documentElement.scrollHeight <= innerHeight,
+        }));
+        expect(await fits()).toEqual({ w: true, h: true });
+        // The controls sit in one row of short labels.
+        await expect(page.locator('#new-game-btn')).toHaveText('New');
+        const [newBox, resignBox] = await Promise.all([
+            page.locator('#new-game-btn').boundingBox(), page.locator('#resign-btn').boundingBox()]);
+        expect(Math.abs(newBox.y - resignBox.y)).toBeLessThan(2);
+        expect(newBox.height).toBeLessThan(50);
+        await expect(page.locator('.pane-live .toolbar')).toBeInViewport();
+        // A replay keeps its controls on screen too.
+        const created = await (await context.request.post(`${API}/api/games`, { data: { white: { type: 1 }, black: { type: 1 } } })).json();
+        await context.request.post(`${API}/api/games/${created.gameId}/moves`, { data: { move: 'e2e4' } });
+        await page.goto(`/?replay=${created.gameId}&ply=1`);
+        await expect(page.locator('body')).toHaveAttribute('data-mode', 'replay');
+        expect(await fits()).toEqual({ w: true, h: true });
+        await expect(page.locator('#replay-exit')).toBeInViewport();
+        await expect(page.locator('#replay-link')).toBeInViewport();
+        await context.close();
+    });
+
+    test('a forgotten password is reset through the emailed link', async ({ page, request }) => {
+        test.skip(!MAIL_DIR, 'CHESS_E2E_MAIL_DIR is not set (start the server with MAIL_DIR)');
+        const username = `reset${Date.now().toString(36)}${Math.floor(Math.random() * 1000)}`;
+        const email = `${username}@example.test`;
+        const created = await request.post(`${API}/api/auth/register`, {
+            data: { username, email, password: 'OldPass123' },
+        });
+        expect(created.status(), await created.text()).toBe(201);
+
+        await page.goto('/');
+        await expect(page.locator('#storage-dot')).toHaveAttribute('data-status', 'ok');
+        await page.click('#auth-btn');
+        // A wrong password keeps the focus in the password field.
+        await page.fill('#login-identifier', username);
+        await page.fill('#login-password', 'wrong');
+        await page.click('#login-submit-btn');
+        await expect(page.locator('#auth-modal-message')).toContainText('Wrong username or password');
+        await expect(page.locator('#login-password')).toBeFocused();
+
+        await expect(page.locator('#forgot-btn')).toBeVisible();
+        await page.click('#forgot-btn');
+        await page.fill('#recover-identifier', email);
+        const mails = () => (fs.existsSync(MAIL_DIR) ? fs.readdirSync(MAIL_DIR) : []);
+        const before = mails().length;
+        await page.click('#recover-submit-btn');
+        await expect(page.locator('#auth-modal-message')).toContainText('on its way');
+        await expect.poll(() => mails().length, { timeout: 10_000 }).toBeGreaterThan(before);
+        const files = fs.readdirSync(MAIL_DIR).map(f => path.join(MAIL_DIR, f))
+            .sort((a, b) => fs.statSync(b).mtimeMs - fs.statSync(a).mtimeMs);
+        const mail = fs.readFileSync(files[0], 'utf8');
+        expect(mail).toContain(`To: ${email}`);
+        const link = /(https?:\/\/\S+\?reset=[A-Za-z0-9_-]+)/.exec(mail)[1];
+        const origin = new URL(page.url()).origin;
+        await page.goto(link.replace(/^https?:\/\/[^/]+/, origin));
+        await expect(page.locator('#reset-overlay')).toHaveClass(/show/);
+        // The token is removed from the address at once.
+        expect(page.url()).not.toContain('reset=');
+        await page.fill('#reset-password', 'NewPass123');
+        await page.fill('#reset-password-2', 'NewPass124');
+        await page.click('#reset-submit-btn');
+        await expect(page.locator('#reset-modal-message')).toContainText('differ');
+        await page.fill('#reset-password-2', 'NewPass123');
+        await page.keyboard.press('Enter');
+        await expect(page.locator('#auth-label')).toHaveText(username);
+        await expect(page.locator('#reset-overlay')).not.toHaveClass(/show/, { timeout: 5_000 });
+        // The old password is gone, the new one and the link are not reusable.
+        const old = await request.post(`${API}/api/auth/login`, { data: { identifier: username, password: 'OldPass123' } });
+        expect(old.status()).toBe(401);
+        const fresh = await request.post(`${API}/api/auth/login`, { data: { identifier: username, password: 'NewPass123' } });
+        expect(fresh.status()).toBe(200);
+        await page.goto(link.replace(/^https?:\/\/[^/]+/, origin));
+        await page.fill('#reset-password', 'NewPass125');
+        await page.fill('#reset-password-2', 'NewPass125');
+        await page.click('#reset-submit-btn');
+        await expect(page.locator('#reset-modal-message')).toContainText('invalid or has expired');
+    });
+
+    test('an anonymous visitor replays from the device list', async ({ page }) => {
+        await page.goto('/');
+        await expect(page.locator('#auth-label')).toHaveText('Sign in');
+        await startGame(page, { color: 'black' });
+        await expectPlies(page, 1);
+        // Black at the bottom while playing Black.
+        await expect(page.locator('.coordinates.ranks span').first()).toHaveText('1');
+        await page.click('#games-btn');
+        await expect(page.locator('#games-signin-note')).toBeVisible();
+        const row = page.locator('#local-games-list .game-row');
+        await expect(row).toHaveCount(1);
+        await expect(row).toContainText('Stockfish L0 vs You');
+        await row.click();
+        await expect(page.locator('body')).toHaveAttribute('data-mode', 'replay');
+        await expect(page.locator('#replay-ply')).toHaveText('1 / 1');
+        // The viewer's side stays at the bottom in the replay.
+        await expect(page.locator('.coordinates.ranks span').first()).toHaveText('1');
+        expect(await page.evaluate(() => replay.history.initialFen)).toBe(START_FEN);
+        await page.click('#replay-exit');
+        await expect(page.locator('#turn-text')).toHaveText('Your move');
+        await expect(page.locator('#turn-dot')).toHaveAttribute('data-status', 'black');
+    });
+});

test/run-test-server.sh

@@ -10,6 +10,11 @@ CHESS_SERVER_EXEC=${1:-"bin/chess-server"}
 export CHESS_DSN="$CHESS_TEST_DSN"
 PID_FILE="/tmp/chess-server_test.pid"
 API_PORT=${API_PORT:-8080}
+# Set WEB_PORT to also serve the embedded web client (for test/e2e), and
+# MAIL_DIR to enable password recovery with the email written to that
+# directory instead of sent.
+WEB_PORT=${WEB_PORT:-}
+MAIL_DIR=${MAIL_DIR:-}
 LOG_LEVEL=${LOG_LEVEL:-debug}
 LOG_HTTP=${LOG_HTTP:-true}
 
@@ -95,7 +100,8 @@ echo ""
 echo "Configuration:"
 echo "  Executable: $CHESS_SERVER_EXEC"
 echo "  Database:   \$CHESS_TEST_DSN (tables dropped on exit)"
-echo "  Port:       $API_PORT"
+echo "  Port:       $API_PORT${WEB_PORT:+ (web client on $WEB_PORT)}"
+echo "  Mail:       ${MAIL_DIR:-off (set MAIL_DIR for password recovery)}"
 echo "  Mode:       Development (relaxed rate limits; PostgreSQL storage)"
 echo "  Log level:  $LOG_LEVEL (HTTP requests: $LOG_HTTP)"
 echo "  Purpose:    Backend for chess-server tests"
@@ -111,10 +117,18 @@ echo "Starting server..."
 echo ""
 
 # Start chess-server in foreground with dev mode and storage
+WEB_FLAGS=()
+[ -n "$WEB_PORT" ] && WEB_FLAGS=(-serve -web-port "$WEB_PORT")
+if [ -n "$MAIL_DIR" ]; then
+    mkdir -p "$MAIL_DIR"
+    WEB_FLAGS+=(-mail-dir "$MAIL_DIR" -mail-from "Chess <chess@localhost>" \
+        -public-url "http://localhost:${WEB_PORT:-9090}/")
+fi
 "$CHESS_SERVER_EXEC" \
 	-dev \
 	-log-level "$LOG_LEVEL" \
 	-log-http="$LOG_HTTP" \
     -api-port "$API_PORT" \
+    "${WEB_FLAGS[@]}" \
     -pid "$PID_FILE" \
     -pid-lock

web/chess-client-wasm/terminal.js

@@ -56,6 +56,13 @@
     const fitAddon = new FitAddon.FitAddon();
     term.loadAddon(fitAddon);
 
+    // The client pages long output by the terminal's size, read from here
+    // (display/termsize_wasm.go).
+    globalThis.chessTerminal = {
+        get rows() { return term.rows; },
+        get cols() { return term.cols; }
+    };
+
     term.open(screenEl);
 
     // WebGL must load after open(); the DOM renderer is the fallback.