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

2026-10-19 18:15:31 -04:00
1 parent a999177f0c
commit e1fa5242e3
@@ -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 {
@@ -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)
-	fmt.Printf("Username: %s\n", resp.Username)
+	display.Printf("User ID: %s\n", resp.UserID)
+	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)
-	fmt.Printf("Username: %s\n", resp.Username)
+	display.Printf("User ID: %s\n", resp.UserID)
+	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)
-	fmt.Printf("  Username: %s\n", user.Username)
+	display.Printf("  User ID:  %s\n", user.UserID)
+	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
 }
@@ -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
 	}

@@ -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,6 +101,7 @@ func (r *Registry) registerGameCommands() {
 		Description: "List your stored games, newest first (login required)",
 		Usage:       "games [more]",
 		Handler:     gamesHandler,
+		Paged:       true,
 	})

 	r.Register(&Command{
@@ -107,6 +110,7 @@ func (r *Registry) registerGameCommands() {
 		Description: "Print or save a stored game as PGN",
 		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)
-	fmt.Printf("Turn: %s | State: %s | Moves: %d\n", resp.Turn, resp.State, len(resp.Moves))
+	display.Printf("%sJoined game: %s%s\n", display.Green, gameID, display.Reset)
+	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)
@@ -546,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)
-	fmt.Printf("Turn: %s | State: %s | Moves: %d\n",
+	display.Printf("\nFEN: %s\n", game.FEN)
+	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
@@ -576,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)
@@ -630,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
 }

@@ -661,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))
@@ -701,9 +705,9 @@ func gamesHandler(s *session.Session, args []string) error {
 		return nil
 	}

-	fmt.Printf("\n%3s  %-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 i, g := range resp.Games {
-		fmt.Printf("%3d  %-36s  %-20s  %-20s  %-7s  %5d  %s\n", i+1, 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"))
 	}
@@ -761,7 +765,7 @@ func pgnHandler(s *session.Session, args []string) error {
 		display.Println(display.Green, "Saved PGN of %s to %s", describePGNTarget(gameID, ply), path)
 		return nil
 	}
-	fmt.Println()
-	fmt.Print(text)
+	display.Line()
+	display.Write(text)
 	return nil
 }
@@ -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
 	}
@@ -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 {
@@ -43,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)
@@ -89,6 +94,18 @@ func (r *Registry) Execute(input string) {
 		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())
 	}
@@ -101,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
 	}

@@ -173,10 +190,10 @@ 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)
@@ -185,7 +202,8 @@ func (r *Registry) helpHandler(s *session.Session, args []string) error {
 	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
 }

@@ -22,6 +22,7 @@ func (r *Registry) registerReplayCommands() {
 		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",
@@ -122,7 +123,7 @@ func replayHandler(s *session.Session, args []string) error {

 	white, black := s.Replay.Players()
 	display.Println(display.Cyan, "\nReplaying %s", history.GameID)
-	fmt.Printf("%s vs %s  ·  %s  ·  %d plies  ·  started %s\n",
+	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 {
@@ -135,8 +136,8 @@ func replayHandler(s *session.Session, args []string) error {
 		}
 		display.Println(display.Yellow, "%s at ply %d; play continued.", what, c.Ply)
 	}
-	fmt.Println()
-	fmt.Println(s.Replay.Movetext(80))
+	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)
 }
@@ -217,7 +218,7 @@ func fenHandler(s *session.Session, args []string) error {
 	if s.Replay == nil {
 		return errNotReplaying
 	}
-	fmt.Println(s.Replay.FEN())
+	display.Line(s.Replay.FEN())
 	return nil
 }

@@ -241,13 +242,13 @@ func showReplayPosition(s *session.Session) error {
 	if err != nil {
 		return fmt.Errorf("stored position cannot be shown: %w", err)
 	}
-	fmt.Println()
+	display.Line()
 	display.RenderBoard(board)
 	label := r.Label(r.Ply)
 	if r.Ply == 0 {
 		label = "initial position"
 	}
-	fmt.Printf("\nPly %d/%d  %s\n", r.Ply, r.Len(), display.C(display.Cyan, label))
+	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())
 	}
@@ -2,11 +2,15 @@

 package command

-import "fmt"
+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 {
-	fmt.Print(text)
+	display.Write(text)
 	return fmt.Errorf("files cannot be saved from the browser; the PGN is printed above")
 }
@@ -40,7 +40,7 @@ func RenderBoard(asciiBoard string) {
 				Print(Reset, "%c", char)
 			}
 		}
-		fmt.Println()
+		fmt.Fprintln(Out)
 	}
 }

@@ -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
@@ -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))
 }
@@ -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
+}
@@ -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())
+	}
+}
@@ -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
+	}
+}
@@ -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
+	}
+}
@@ -18,8 +18,11 @@ type Session struct {
 	Client        *api.Client
 	// 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
-	Verbose bool
+	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 ""
@@ -16,4 +16,5 @@ const (
 	ErrConflict           = "GAME_CONFLICT"
 	ErrStorageUnavailable = "STORAGE_UNAVAILABLE"
 	ErrRouteNotFound      = "NOT_FOUND"
+	ErrNotConfigured      = "NOT_CONFIGURED"
 )
@@ -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),
+	})
+}
@@ -140,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

@@ -263,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,
 	})
 }
@@ -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",
@@ -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
+}
@@ -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)
+	}
+}
@@ -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
+}
@@ -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
+}
@@ -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)
@@ -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
+}
@@ -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"}
@@ -93,6 +93,7 @@ const games = {
 const ui = {
    healthTimer: null,
    storage: 'unknown',
+    mail: 'unknown',    // "ok" when the server emails password-reset links
    toastTimer: null,
    historyCache: new Map(), // gameId -> {etag, history}
 };
@@ -211,6 +212,22 @@ function describeResult(state, termination) {
    return 'Game over';
 }

+// shortResult is the outcome in a few words, for the narrow turn strip.
+function shortResult(state, termination) {
+    const winner = state === 'white wins' ? 'White' : 'Black';
+    switch (termination) {
+        case 'resignation': return `${winner} wins · resigned`;
+        case 'checkmate': return `${winner} wins · mate`;
+        case 'stalemate': return 'Draw · stalemate';
+        case 'insufficient_material': return 'Draw · material';
+        case 'threefold_repetition': return 'Draw · repetition';
+        case 'fifty_move_rule': return 'Draw · 50 moves';
+        case 'agreement': return 'Draw · agreed';
+    }
+    if (state === 'white wins' || state === 'black wins') return `${winner} wins`;
+    return 'Draw';
+}
+
 function terminationLabel(termination) {
    switch (termination) {
        case 'checkmate': return 'Checkmate';
@@ -358,6 +375,11 @@ function setStorageStatus(status) {
    updateLiveTools();
 }

+function setMailStatus(status) {
+    ui.mail = status;
+    $('forgot-row').classList.toggle('hidden', status !== 'ok');
+}
+
 function startHealthCheck() {
    const checkHealth = async () => {
        try {
@@ -366,6 +388,7 @@ function startHealthCheck() {
                const health = await response.json();
                setServerStatus(health.status === 'healthy' ? 'healthy' : 'degraded');
                setStorageStatus(health.storage || 'unknown');
+                setMailStatus(health.mail || 'disabled');
            } else {
                handleApiError('health check', null, response);
                setStorageStatus('unknown');
@@ -551,7 +574,8 @@ async function deleteAccount() {
 // re-entrancy from the Enter-key handler and stops edits mid-request.
 function setAuthModalBusy(busy) {
    auth.busy = busy;
-    for (const id of ['login-submit-btn', 'register-submit-btn', 'auth-cancel-btn', 'auth-cancel-btn-2']) {
+    for (const id of ['login-submit-btn', 'register-submit-btn', 'auth-cancel-btn', 'auth-cancel-btn-2',
+        'forgot-btn', 'recover-submit-btn', 'recover-back-btn']) {
        $(id).disabled = busy;
    }
    document.querySelectorAll('.auth-tab').forEach(t => t.disabled = busy);
@@ -560,7 +584,7 @@ function setAuthModalBusy(busy) {

 function showAuthModal() {
    $('auth-modal-overlay').classList.add('show');
-    $('login-identifier').focus();
+    switchAuthTab('login');
    document.removeEventListener('keydown', handleAuthModalKeydown);
    document.addEventListener('keydown', handleAuthModalKeydown);
 }
@@ -584,50 +608,72 @@ function handleAuthModalKeydown(e) {
        hideAuthModal();
    } else if (e.key === 'Enter') {
        e.preventDefault();
-        if (!$('login-form').classList.contains('hidden')) handleLogin(); else handleRegister();
+        ({ login: handleLogin, register: handleRegister, recover: handleRecover })[activeAuthForm()]();
    }
 }

+// The auth modal shows one of three forms: sign in, register, or password
+// recovery (reached from the sign-in form, without a tab).
 function switchAuthTab(tab) {
    document.querySelectorAll('.auth-tab').forEach(t => {
        const active = t.dataset.tab === tab;
        t.classList.toggle('active', active);
        t.setAttribute('aria-selected', active ? 'true' : 'false');
    });
+    document.querySelector('.auth-tabs').classList.toggle('hidden', tab === 'recover');
    $('login-form').classList.toggle('hidden', tab !== 'login');
    $('register-form').classList.toggle('hidden', tab !== 'register');
+    $('recover-form').classList.toggle('hidden', tab !== 'recover');
    clearModalMessage('auth-modal-message');
-    $(tab === 'login' ? 'login-identifier' : 'register-username').focus();
+    $({ login: 'login-identifier', register: 'register-username', recover: 'recover-identifier' }[tab]).focus();
 }

-async function submitAuth(path, body, failure) {
+function activeAuthForm() {
+    if (!$('login-form').classList.contains('hidden')) return 'login';
+    if (!$('register-form').classList.contains('hidden')) return 'register';
+    return 'recover';
+}
+
+// Returns the focus to a field after a failed request: the request disabled
+// the fields, which drops the focus to the page, and a retyped password
+// would otherwise go nowhere.
+function refocus(id, select = true) {
+    const el = $(id);
+    if (!el) return;
+    el.focus();
+    if (select && typeof el.select === 'function') el.select();
+}
+
+async function submitAuth(path, body, failure, focusId) {
    setAuthModalBusy(true);
    clearModalMessage('auth-modal-message');

+    const fail = message => {
+        setModalMessage('auth-modal-message', message, 'error');
+        setAuthModalBusy(false);
+        refocus(focusId);
+        return null;
+    };
+
    let response;
    try {
        response = await apiJSON('POST', path, body);
    } catch (error) {
-        const errorInfo = handleApiError(path, error);
-        setModalMessage('auth-modal-message', errorInfo.statusMessage, 'error');
-        setAuthModalBusy(false);
-        return null;
+        return fail(handleApiError(path, error).statusMessage);
    }

    if (!response.ok) {
        const err = await parseErrorResponse(response);
-        setModalMessage('auth-modal-message', err.details || err.error || failure, 'error');
-        setAuthModalBusy(false);
-        return null;
+        if (response.status === 401) return fail('Wrong username or password');
+        if (response.status === 429) return fail('Too many attempts. Wait a minute and try again.');
+        return fail(err.details || err.error || failure);
    }

    try {
        return await response.json();
    } catch (error) {
        console.error(`${path}: response OK but JSON parse failed:`, error);
-        setModalMessage('auth-modal-message', 'Unexpected response from server', 'error');
-        setAuthModalBusy(false);
-        return null;
+        return fail('Unexpected response from server');
    }
 }

@@ -637,15 +683,156 @@ async function handleLogin() {
    const password = $('login-password').value;
    if (!identifier || !password) {
        setModalMessage('auth-modal-message', 'Fill in both fields', 'error');
+        refocus(identifier ? 'login-password' : 'login-identifier', false);
        return;
    }
-    const result = await submitAuth('/api/auth/login', { identifier, password }, 'Sign-in failed');
+    const result = await submitAuth('/api/auth/login', { identifier, password }, 'Sign-in failed', 'login-password');
    if (!result) return;
    setSignedIn(result.userId, result.username, result.token);
    setModalMessage('auth-modal-message', `Signed in as ${result.username}`, 'success');
    setTimeout(hideAuthModal, MODAL_SUCCESS_DISPLAY_MS);
 }

+// The server's password rule, checked first for a quicker answer.
+function passwordProblem(password) {
+    if (password.length < 8) return 'Password needs at least 8 characters';
+    if (!/[a-zA-Z]/.test(password) || !/[0-9]/.test(password)) return 'Password needs a letter and a number';
+    return '';
+}
+
+// Asks for a reset link. The server answers the same whether or not the
+// account exists, so the message is the same too.
+async function handleRecover() {
+    if (auth.busy) return;
+    const identifier = $('recover-identifier').value.trim();
+    if (!identifier) {
+        setModalMessage('auth-modal-message', 'Enter your username or email', 'error');
+        refocus('recover-identifier', false);
+        return;
+    }
+    setAuthModalBusy(true);
+    clearModalMessage('auth-modal-message');
+    let response;
+    try {
+        response = await apiJSON('POST', '/api/auth/recover', { identifier });
+    } catch (error) {
+        setModalMessage('auth-modal-message', handleApiError('recover', error).statusMessage, 'error');
+        setAuthModalBusy(false);
+        refocus('recover-identifier');
+        return;
+    }
+    setAuthModalBusy(false);
+    if (response.status === 202) {
+        setModalMessage('auth-modal-message', 'If the account has an email address, a reset link is on its way. Check your inbox.', 'success');
+        $('recover-identifier').value = '';
+        $('recover-back-btn').focus();
+        return;
+    }
+    const err = await parseErrorResponse(response);
+    let message = err.error || 'Could not send the link';
+    if (response.status === 429) message = 'Too many requests. Wait a minute and try again.';
+    else if (response.status === 503 && err.code === 'NOT_CONFIGURED') message = 'This server cannot send email; ask its administrator for a reset link.';
+    setModalMessage('auth-modal-message', message, 'error');
+    refocus('recover-identifier');
+}
+
+// --- reset: the link in the recovery email opens the client with ?reset=<token>
+
+const reset = { token: null, busy: false };
+
+function openResetModal(token) {
+    reset.token = token;
+    reset.busy = false;
+    $('reset-password').value = '';
+    $('reset-password-2').value = '';
+    clearModalMessage('reset-modal-message');
+    $('reset-overlay').classList.add('show');
+    document.removeEventListener('keydown', handleResetKeydown);
+    document.addEventListener('keydown', handleResetKeydown);
+    $('reset-password').focus();
+}
+
+function closeResetModal() {
+    if (reset.busy) return;
+    reset.token = null;
+    $('reset-overlay').classList.remove('show');
+    $('reset-password').value = '';
+    $('reset-password-2').value = '';
+    document.removeEventListener('keydown', handleResetKeydown);
+}
+
+function setResetBusy(busy) {
+    reset.busy = busy;
+    for (const id of ['reset-password', 'reset-password-2', 'reset-submit-btn', 'reset-cancel-btn']) {
+        $(id).disabled = busy;
+    }
+}
+
+function handleResetKeydown(e) {
+    if (reset.busy) {
+        if (e.key === 'Enter' || e.key === 'Escape') e.preventDefault();
+        return;
+    }
+    if (e.key === 'Escape') {
+        e.preventDefault();
+        closeResetModal();
+    } else if (e.key === 'Enter') {
+        e.preventDefault();
+        submitReset();
+    }
+}
+
+async function submitReset() {
+    if (reset.busy || !reset.token) return;
+    const password = $('reset-password').value;
+    const again = $('reset-password-2').value;
+    const weak = passwordProblem(password);
+    if (weak) {
+        setModalMessage('reset-modal-message', weak, 'error');
+        refocus('reset-password');
+        return;
+    }
+    if (password !== again) {
+        setModalMessage('reset-modal-message', 'The two passwords differ', 'error');
+        refocus('reset-password-2');
+        return;
+    }
+    setResetBusy(true);
+    clearModalMessage('reset-modal-message');
+    let response;
+    try {
+        response = await apiJSON('POST', '/api/auth/reset', { token: reset.token, password });
+    } catch (error) {
+        setResetBusy(false);
+        setModalMessage('reset-modal-message', handleApiError('reset', error).statusMessage, 'error');
+        refocus('reset-password');
+        return;
+    }
+    if (!response.ok) {
+        const err = await parseErrorResponse(response);
+        setResetBusy(false);
+        setModalMessage('reset-modal-message', response.status === 400
+            ? (err.details && err.error === 'weak password' ? err.details : 'This link is invalid or has expired. Ask for a new one from Sign in.')
+            : (err.error || `Server error (${response.status})`), 'error');
+        refocus('reset-password');
+        return;
+    }
+    let result;
+    try {
+        result = await response.json();
+    } catch {
+        setResetBusy(false);
+        setModalMessage('reset-modal-message', 'Unexpected response from server', 'error');
+        return;
+    }
+    setSignedIn(result.userId, result.username, result.token);
+    setModalMessage('reset-modal-message', `Password changed — signed in as ${result.username}`, 'success');
+    setTimeout(() => {
+        setResetBusy(false);
+        closeResetModal();
+    }, MODAL_SUCCESS_DISPLAY_MS * 2);
+}
+
 async function handleRegister() {
    if (auth.busy) return;
    const username = $('register-username').value.trim();
@@ -655,17 +842,15 @@ async function handleRegister() {
        setModalMessage('auth-modal-message', 'Username and password required', 'error');
        return;
    }
-    if (password.length < 8) {
-        setModalMessage('auth-modal-message', 'Password needs at least 8 characters', 'error');
-        return;
-    }
-    if (!/[a-zA-Z]/.test(password) || !/[0-9]/.test(password)) {
-        setModalMessage('auth-modal-message', 'Password needs a letter and a number', 'error');
+    const weak = passwordProblem(password);
+    if (weak) {
+        setModalMessage('auth-modal-message', weak, 'error');
+        refocus('register-password');
        return;
    }
    const body = { username, password };
    if (email) body.email = email;
-    const result = await submitAuth('/api/auth/register', body, 'Registration failed');
+    const result = await submitAuth('/api/auth/register', body, 'Registration failed', 'register-password');
    if (!result) return;
    setSignedIn(result.userId, result.username, result.token);
    setModalMessage('auth-modal-message', `Account created, welcome ${result.username}`, 'success');
@@ -1344,26 +1529,32 @@ function updateTurnStrip() {
    const dot = $('turn-dot');
    const text = $('turn-text');
    let status = 'idle', label = 'No game';
+    let title = '';
    if (!live.gameId) {
        status = 'idle';
        label = 'No game';
    } else if (live.state === 'pending' || live.isLocked) {
        status = 'thinking';
-        label = 'Computer thinking…';
+        label = 'Thinking…';
+        title = 'The computer is thinking';
    } else if (isGameOver(live.state)) {
        status = live.state === 'white wins' ? 'white-wins' : live.state === 'black wins' ? 'black-wins' : live.state;
-        label = describeResult(live.state, live.termination);
+        label = shortResult(live.state, live.termination);
+        title = describeResult(live.state, live.termination);
    } else if (live.state === 'stuck') {
        status = 'stuck';
-        label = 'Engine error — undo or start a new game';
+        label = 'Engine error';
+        title = 'Engine error — undo or start a new game';
    } else {
+        // The dot shows the side to move; the text says whose it is.
        status = live.turn === 'w' ? 'white' : 'black';
        const side = live.turn === 'w' ? 'White' : 'Black';
-        label = live.turn === playerColor() ? `Your move (${side})` : `Computer to move (${side})`;
+        label = live.turn === playerColor() ? 'Your move' : 'Computer';
+        title = `${side} to move: ${live.turn === playerColor() ? 'you' : 'the computer'}`;
    }
    dot.dataset.status = status;
    text.textContent = label;
-    $('turn-strip').title = label;
+    $('turn-strip').title = title || label;
 }

 // Draw needs a game in progress with the board free; resigning only needs
@@ -2144,6 +2335,11 @@ function bindEvents() {
    });
    $('login-submit-btn').addEventListener('click', handleLogin);
    $('register-submit-btn').addEventListener('click', handleRegister);
+    $('forgot-btn').addEventListener('click', () => switchAuthTab('recover'));
+    $('recover-back-btn').addEventListener('click', () => switchAuthTab('login'));
+    $('recover-submit-btn').addEventListener('click', handleRecover);
+    $('reset-submit-btn').addEventListener('click', submitReset);
+    $('reset-cancel-btn').addEventListener('click', closeResetModal);
    $('auth-cancel-btn').addEventListener('click', hideAuthModal);
    $('auth-cancel-btn-2').addEventListener('click', hideAuthModal);
    $('logout-btn').addEventListener('click', handleLogoutClick);
@@ -2198,6 +2394,18 @@ document.addEventListener('DOMContentLoaded', async () => {
    updateTurnStrip();
    updateGameControls();
    startHealthCheck();
+    // A reset link: take the token off the address before anything else, so
+    // it is neither kept in history nor shared with a copied link.
+    const params = new URLSearchParams(location.search);
+    const resetToken = params.get('reset');
+    if (resetToken !== null) {
+        params.delete('reset');
+        const query = params.toString();
+        try {
+            history.replaceState({ chess: true }, '', location.pathname + (query ? `?${query}` : ''));
+        } catch { /* history blocked */ }
+    }
    await restoreAuthSession();
    await applyURL();
+    if (resetToken) openResetModal(resetToken);
 });
@@ -10,7 +10,31 @@
 <body data-mode="live">
 <div class="app">
    <header class="topbar">
-        <div class="brand" aria-label="Chess"><span class="brand-mark" aria-hidden="true">♞</span><span class="brand-name">Chess</span></div>
+        <div class="brand" aria-label="Chess">
+            <svg class="brand-mark" viewBox="41 34 430 430" aria-hidden="true" focusable="false">
+                <defs>
+                    <linearGradient id="brand-piece" x1="20%" y1="0%" x2="80%" y2="100%">
+                        <stop offset="0%" stop-color="#C8CDD6"/>
+                        <stop offset="45%" stop-color="#8B929E"/>
+                        <stop offset="100%" stop-color="#4F545D"/>
+                    </linearGradient>
+                </defs>
+                <g fill="url(#brand-piece)" stroke="#14161A" stroke-width="4" stroke-linejoin="round">
+                    <path d="M136 450Q256 465 376 450L346 410Q256 420 166 410Z"/>
+                    <path d="M166 410Q256 420 346 410L316 370Q256 380 196 370Z"/>
+                    <path d="M196 370Q256 380 316 370C300 290 286 230 282 205H230C226 230 212 290 196 370Z"/>
+                </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>
@@ -44,7 +68,7 @@
                    <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">New game</button>
+                    <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>
@@ -201,6 +225,19 @@
                <button id="login-submit-btn" class="btn btn-primary" type="button">Sign in</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>

        <div id="register-form" class="auth-form hidden">
@@ -224,6 +261,26 @@
    </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">
@@ -125,9 +125,9 @@ button { cursor: pointer; }
 }

 .brand-mark {
-    font-size: 1.35rem;
-    line-height: 1;
-    color: var(--periwinkle);
+    width: 1.5rem;
+    height: 1.5rem;
+    flex: none;
 }

 .health {
@@ -722,6 +722,7 @@ input[type="range"]:focus-visible { outline: 2px solid var(--periwinkle); outlin
 .auth-form input[type="text"],
 .auth-form input[type="email"],
 .auth-form input[type="password"],
+#reset-overlay input[type="password"],
 .account-form input[type="password"] {
    width: 100%;
    padding: 0.5rem 0.6rem;
@@ -740,7 +741,7 @@ input[type="range"]:focus-visible { outline: 2px solid var(--periwinkle); outlin
    word-wrap: break-word;
 }

-.fen-input:focus, .auth-form input:focus, .account-form input:focus {
+.fen-input:focus, .auth-form input:focus, .account-form input:focus, #reset-overlay input:focus {
    outline: none;
    border-color: var(--royal);
 }
@@ -754,6 +755,33 @@ input[type="range"]:focus-visible { outline: 2px solid var(--periwinkle); outlin

 .auth-modal, .account-modal { max-width: 360px; }

+.auth-aside {
+    margin: 0.9rem 0 0;
+    text-align: center;
+    font-size: 0.85rem;
+}
+
+.auth-help {
+    margin: 0 0 0.9rem;
+    font-size: 0.85rem;
+    line-height: 1.45;
+    color: var(--muted);
+}
+
+.link-btn {
+    padding: 0;
+    background: none;
+    border: none;
+    color: var(--periwinkle);
+    text-decoration: underline;
+    text-underline-offset: 2px;
+    cursor: pointer;
+}
+
+.link-btn:hover { color: var(--fg); }
+.link-btn:focus-visible { outline: 2px solid var(--periwinkle); outline-offset: 2px; border-radius: 2px; }
+.auth-form input[type="password"]#reset-password, .auth-form input[type="password"]#reset-password-2 { width: 100%; }
+
 .auth-tabs {
    display: flex;
    margin-bottom: 0.9rem;
@@ -1007,7 +1035,7 @@ input[type="range"]:focus-visible { outline: 2px solid var(--periwinkle); outlin

 /* --- Stacked layout (board over panel) -------------------------------- */

-@media (max-width: 978px) {
+@media (min-width: 641px) and (max-width: 978px) {
    :root {
        --panel-width: clamp(360px, 45vw, 440px);
        --panel-height: 230px;
@@ -1036,12 +1064,18 @@ input[type="range"]:focus-visible { outline: 2px solid var(--periwinkle); outlin

    .pane {
        display: grid;
-        grid-template-columns: clamp(150px, 18.4vw, 180px) 1fr;
+        grid-template-columns: clamp(150px, 18.4vw, 180px) minmax(0, 1fr);
        grid-template-rows: min-content 1fr;
        gap: 0.5rem 0.75rem;
        padding: 0.6rem;
    }

+    .pane > * { min-width: 0; }
+    .toolbar .btn-tool { min-width: 0; overflow: hidden; }
+    /* Four export buttons in the narrow right column: icons only. */
+    .pane-replay .toolbar .btn-tool span { display: none; }
+    .pane-replay .toolbar .btn-tool .icon { width: 1.2rem; height: 1.2rem; }
+
    body[data-mode="replay"] .pane-live, body[data-mode="live"] .pane-replay { display: none; }

    .pane-live .turn-strip { grid-column: 1; grid-row: 1; }
@@ -1086,19 +1120,111 @@ input[type="range"]:focus-visible { outline: 2px solid var(--periwinkle); outlin
    .btn-tool { font-size: 0.74rem; padding: 0.3rem 0.2rem; }
 }

-@media (max-width: 530px) {
+/* --- Phone layout: full-width rows, edge to edge ------------------------ */
+
+@media (max-width: 640px) {
    :root {
-        --panel-width: min(92vw, 440px);
-        --board-edge: max(240px, min(min(92vw, 440px), calc(100vh - 332px)));
-        --board-pad: 12px;
+        /* Reserve under the board: top bar 40 + gap 6 + turn strip 32 +
+           controls 36 + move list 96 + toolbar 36 + gaps and padding 26 =
+           276. Small viewport units, so the browser's bars never cover the
+           panel. The replay pane is taller (head, navigation, export, exit),
+           so a replay reserves more and the board gives way on a short
+           screen rather than the controls dropping below the fold. */
+        --board-edge: max(240px, min(100vw, calc(100svh - 284px)));
+        --board-pad: 14px;
+        --panel-width: 100%;
+        --panel-height: auto;
+        --topbar-height: 2.5rem;
+    }
+
+    body { overflow-y: auto; overflow-x: hidden; }
+    body[data-mode="replay"] { --board-edge: max(240px, min(100vw, calc(100svh - 372px))); }
+
+    /* The app is exactly the viewport, so the panel and its move list shrink
+       to fit; only when their minimums do not fit does the page scroll. */
+    .app { padding: 0; gap: 6px; height: 100svh; min-height: 100svh; overflow: visible; }
+
+    .topbar {
+        border-radius: 0;
+        border-left: none;
+        border-right: none;
+        border-top: none;
+        padding: 0 0.6rem;
    }

    .brand-name, #games-btn span, #auth-label { display: none; }
-    /* Icon-only export row in the replay pane: four buttons in 190px. */
-    .pane-replay .toolbar .btn-tool span { display: none; }
-    .pane-replay .toolbar .btn-tool .icon { width: 1.2rem; height: 1.2rem; }
-    #games-btn, #auth-btn { padding: 0.35rem 0.5rem; }
-    .pane { grid-template-columns: 140px 1fr; }
+    #games-btn, #auth-btn { padding: 0.35rem 0.55rem; }
+
+    .workspace {
+        flex: 1 1 auto;
+        min-height: 0;
+        flex-direction: column;
+        justify-content: flex-start;
+        gap: 6px;
+        overflow: visible;
+    }
+
+    .board-area { flex: none; }
+
+    .board-area { padding: var(--board-pad) 6px 6px 16px; }
+    .board-wrapper {
+        width: calc(var(--board-edge) - 22px);
+        height: calc(var(--board-edge) - 22px);
+    }
+    .coordinates.ranks { left: -14px; }
+    .coordinates.files { top: -15px; }
+
+    .panel {
+        display: flex;
+        flex-direction: column;
+        width: 100%;
+        flex: 1 1 auto;
+        min-height: 0;
+        height: auto;
+        border-radius: 0;
+        border-left: none;
+        border-right: none;
+        border-bottom: none;
+    }
+
+    .pane, .pane-live, .pane-replay {
+        display: flex;
+        flex: 1 1 auto;
+        flex-direction: column;
+        gap: 0.4rem;
+        padding: 0.5rem 0.6rem 0.6rem;
+        height: auto;
+    }
+
+    .pane > * { min-width: 0; }
+
+    .turn-strip { min-height: 2rem; padding: 0.25rem 0.6rem; }
+
+    .pane-live .controls {
+        grid-template-columns: repeat(4, 1fr);
+        grid-template-rows: auto;
+        gap: 0.35rem;
+    }
+    .pane-live .controls .btn { padding: 0.5rem 0.2rem; font-size: 0.85rem; min-height: 2.25rem; height: auto; }
+
+    .moves { flex: 1 1 auto; min-height: 96px; }
+    .move-grid { grid-template-columns: 2.2rem 1fr 1fr; font-size: 0.9rem; }
+
+    .toolbar .btn-tool { padding: 0.45rem 0.3rem; font-size: 0.82rem; min-width: 0; }
+
+    /* Replay: head, list, navigation, export and exit as rows. */
+    .pane-replay .replay-head { padding: 0.35rem 0.6rem; }
+    .pane-replay .replay-meta { display: none; }
+    .pane-replay .replay-nav {
+        display: grid;
+        grid-template-columns: repeat(5, 1fr) 1.4fr 1fr;
+        gap: 0.3rem;
+    }
+    .pane-replay .replay-nav .speed { margin: 0; }
+    .pane-replay .replay-nav .speed select { width: 100%; }
+    .pane-replay .btn-nav { width: 100%; height: 2.2rem; }
+    .pane-replay #replay-exit { padding: 0.5rem; font-size: 0.85rem; }
+
    .games-modal { padding: 0.75rem; }
    .game-row { gap: 0.5rem; padding: 0.4rem; }
    .mini-board { width: 56px; height: 56px; }
@@ -1106,6 +1232,13 @@ input[type="range"]:focus-visible { outline: 2px solid var(--periwinkle); outlin
    .modal-overlay { padding: 0.5rem; }
 }

+/* Very narrow phones: icon-only export buttons. */
+@media (max-width: 380px) {
+    .pane-replay .toolbar .btn-tool span { display: none; }
+    .pane-replay .toolbar .btn-tool .icon { width: 1.2rem; height: 1.2rem; }
+    .pane-live .controls .btn { font-size: 0.8rem; }
+}
+
 /* --- Motion ---------------------------------------------------------- */

@media (prefers-reduced-motion: reduce) {