feat(stats): best-move word, moves & hint-share, and a hint-count fix (#81)

The statistics screen gains real depth, plus a hint-count bug fix found along the way.

- Best move per variant: the screen shows the actual best-move word (drawn as game
  tiles; a wildcard shows its letter but no value), broken down by game variant, empty
  variants omitted. New account_best_move table, written at game finish.
- Moves & hint share: two new lifetime tiles — the player's play count and the share of
  plays that used a hint — from summed account_stats counters (moves, hints_used).
  Honest-AI games are excluded, like the rest of the stats.
- Hint-count fix: the in-game hint badge no longer goes stale across games. The global
  wallet now rides the wire apart from the per-game allowance (wallet_balance on
  StateView/HintResult/StatsView), so the client reads the live wallet rather than a
  per-game snapshot; game_players.hints_used now counts every hint (allowance + wallet),
  its true per-game total.
- Account merge: sums the new moves/hints_used counters and merges the per-variant best
  moves (higher score kept), which it previously dropped.
- Admin: the user card shows Moves and Hints used.
- UI polish: tab/label wording, game-over text, and e2e selectors hardened against label
  changes.

All wire additions are trailing (backward-compatible). Docs (ARCHITECTURE, FUNCTIONAL +ru,
UISN_DESIGN) updated in step.

gateway/internal/backendclient/api.go

@@ -162,6 +162,7 @@ type StateResp struct {
 	Rack           []int               `json:"rack"`
 	BagLen         int                 `json:"bag_len"`
 	HintsRemaining int                 `json:"hints_remaining"`
+	WalletBalance  int                 `json:"wallet_balance"`
 	Alphabet       []AlphabetEntryJSON `json:"alphabet,omitempty"`
 }
 
@@ -331,6 +332,7 @@ func (c *Client) ChatPost(ctx context.Context, userID, gameID, body, clientIP st
 type HintResultResp struct {
 	Move           MoveRecordResp `json:"move"`
 	HintsRemaining int            `json:"hints_remaining"`
+	WalletBalance  int            `json:"wallet_balance"`
 }
 
 // EvalResultResp is an unlimited move preview. Dir is the orientation the backend

gateway/internal/backendclient/api_social.go

@@ -47,13 +47,33 @@ type BlockListResp struct {
 	Blocked []AccountRefResp `json:"blocked"`
 }
 
-// StatsResp is a durable account's lifetime statistics.
+// StatsResp is a durable account's lifetime statistics. BestMoves breaks the best move
+// down per variant, carrying the word itself; it is absent for an account with no recorded
+// play and lists only variants the account has played.
 type StatsResp struct {
-	Wins          int `json:"wins"`
-	Losses        int `json:"losses"`
-	Draws         int `json:"draws"`
-	MaxGamePoints int `json:"max_game_points"`
-	MaxWordPoints int `json:"max_word_points"`
+	Wins          int            `json:"wins"`
+	Losses        int            `json:"losses"`
+	Draws         int            `json:"draws"`
+	MaxGamePoints int            `json:"max_game_points"`
+	MaxWordPoints int            `json:"max_word_points"`
+	Moves         int            `json:"moves"`
+	HintsUsed     int            `json:"hints_used"`
+	BestMoves     []BestMoveResp `json:"best_moves"`
+}
+
+// BestMoveResp is one variant's best play: the variant label, the play's total score and
+// its main word as ordered tiles (letter, value, blank — value 0 for a blank).
+type BestMoveResp struct {
+	Variant string             `json:"variant"`
+	Score   int                `json:"score"`
+	Word    []BestMoveTileResp `json:"word"`
+}
+
+// BestMoveTileResp is one letter cell of a best-move word.
+type BestMoveTileResp struct {
+	Letter string `json:"letter"`
+	Value  int    `json:"value"`
+	Blank  bool   `json:"blank"`
 }
 
 // InvitationInviteeResp is one invitee's seat and response with their name.

gateway/internal/transcode/encode.go

@@ -223,6 +223,7 @@ func toWireState(s backendclient.StateResp) wire.StateView {
 		Rack:           s.Rack,
 		BagLen:         s.BagLen,
 		HintsRemaining: s.HintsRemaining,
+		WalletBalance:  s.WalletBalance,
 		Alphabet:       alphabet,
 	}
 }
@@ -278,6 +279,7 @@ func encodeHintResult(r backendclient.HintResultResp) []byte {
 	fb.HintResultStart(b)
 	fb.HintResultAddMove(b, move)
 	fb.HintResultAddHintsRemaining(b, int32(r.HintsRemaining))
+	fb.HintResultAddWalletBalance(b, int32(r.WalletBalance))
 	b.Finish(fb.HintResultEnd(b))
 	return b.FinishedBytes()
 }

gateway/internal/transcode/encode_social.go

@@ -91,15 +91,63 @@ func encodeRedeemResult(r backendclient.RedeemResultResp) []byte {
 	return b.FinishedBytes()
 }
 
-// encodeStats builds a StatsView payload.
+// buildBestMoveTile builds a BestMoveTile table and returns its offset.
+func buildBestMoveTile(b *flatbuffers.Builder, t backendclient.BestMoveTileResp) flatbuffers.UOffsetT {
+	letter := b.CreateString(t.Letter)
+	fb.BestMoveTileStart(b)
+	fb.BestMoveTileAddLetter(b, letter)
+	fb.BestMoveTileAddValue(b, int32(t.Value))
+	fb.BestMoveTileAddBlank(b, t.Blank)
+	return fb.BestMoveTileEnd(b)
+}
+
+// buildBestMove builds a BestMoveView table — its word tile vector first, per the
+// bottom-up rule — and returns its offset.
+func buildBestMove(b *flatbuffers.Builder, m backendclient.BestMoveResp) flatbuffers.UOffsetT {
+	tiles := make([]flatbuffers.UOffsetT, len(m.Word))
+	for i, t := range m.Word {
+		tiles[i] = buildBestMoveTile(b, t)
+	}
+	fb.BestMoveViewStartWordVector(b, len(tiles))
+	for i := len(tiles) - 1; i >= 0; i-- {
+		b.PrependUOffsetT(tiles[i])
+	}
+	word := b.EndVector(len(tiles))
+	variant := b.CreateString(m.Variant)
+	fb.BestMoveViewStart(b)
+	fb.BestMoveViewAddVariant(b, variant)
+	fb.BestMoveViewAddScore(b, int32(m.Score))
+	fb.BestMoveViewAddWord(b, word)
+	return fb.BestMoveViewEnd(b)
+}
+
+// encodeStats builds a StatsView payload, embedding the per-variant best moves (each a
+// BestMoveView with its word tiles) when present.
 func encodeStats(r backendclient.StatsResp) []byte {
-	b := flatbuffers.NewBuilder(64)
+	b := flatbuffers.NewBuilder(256)
+	var bestMoves flatbuffers.UOffsetT
+	if len(r.BestMoves) > 0 {
+		offs := make([]flatbuffers.UOffsetT, len(r.BestMoves))
+		for i, m := range r.BestMoves {
+			offs[i] = buildBestMove(b, m)
+		}
+		fb.StatsViewStartBestMovesVector(b, len(offs))
+		for i := len(offs) - 1; i >= 0; i-- {
+			b.PrependUOffsetT(offs[i])
+		}
+		bestMoves = b.EndVector(len(offs))
+	}
 	fb.StatsViewStart(b)
 	fb.StatsViewAddWins(b, int32(r.Wins))
 	fb.StatsViewAddLosses(b, int32(r.Losses))
 	fb.StatsViewAddDraws(b, int32(r.Draws))
 	fb.StatsViewAddMaxGamePoints(b, int32(r.MaxGamePoints))
 	fb.StatsViewAddMaxWordPoints(b, int32(r.MaxWordPoints))
+	fb.StatsViewAddMoves(b, int32(r.Moves))
+	fb.StatsViewAddHintsUsed(b, int32(r.HintsUsed))
+	if len(r.BestMoves) > 0 {
+		fb.StatsViewAddBestMoves(b, bestMoves)
+	}
 	b.Finish(fb.StatsViewEnd(b))
 	return b.FinishedBytes()
 }

gateway/internal/transcode/transcode_social_test.go

@@ -194,7 +194,12 @@ func TestStatsRoundTrip(t *testing.T) {
 		if r.URL.Path != "/api/v1/user/stats" {
 			t.Errorf("unexpected path %q", r.URL.Path)
 		}
-		_, _ = w.Write([]byte(`{"wins":5,"losses":3,"draws":1,"max_game_points":420,"max_word_points":90}`))
+		_, _ = w.Write([]byte(`{"wins":5,"losses":3,"draws":1,"max_game_points":420,"max_word_points":90,` +
+			`"moves":248,"hints_used":12,` +
+			`"best_moves":[{"variant":"scrabble_en","score":90,"word":[` +
+			`{"letter":"c","value":3,"blank":false},` +
+			`{"letter":"a","value":0,"blank":true},` +
+			`{"letter":"t","value":1,"blank":false}]}]}`))
 	})
 	defer cleanup()
 
@@ -208,6 +213,23 @@ func TestStatsRoundTrip(t *testing.T) {
 	if st.Wins() != 5 || st.Losses() != 3 || st.Draws() != 1 || st.MaxGamePoints() != 420 || st.MaxWordPoints() != 90 {
 		t.Fatalf("stats decoded wrong: %+v", st)
 	}
+	if st.Moves() != 248 || st.HintsUsed() != 12 {
+		t.Fatalf("moves/hints decoded wrong: moves=%d hints=%d", st.Moves(), st.HintsUsed())
+	}
+	if st.BestMovesLength() != 1 {
+		t.Fatalf("best moves length = %d, want 1", st.BestMovesLength())
+	}
+	var bm fb.BestMoveView
+	st.BestMoves(&bm, 0)
+	if string(bm.Variant()) != "scrabble_en" || bm.Score() != 90 || bm.WordLength() != 3 {
+		t.Fatalf("best move decoded wrong: variant=%q score=%d wordLen=%d", bm.Variant(), bm.Score(), bm.WordLength())
+	}
+	// The middle tile is a blank: it carries its designated letter but scores 0.
+	var tile fb.BestMoveTile
+	bm.Word(&tile, 1)
+	if string(tile.Letter()) != "a" || tile.Value() != 0 || !tile.Blank() {
+		t.Fatalf("blank tile decoded wrong: letter=%q value=%d blank=%v", tile.Letter(), tile.Value(), tile.Blank())
+	}
 }
 
 func TestGcgRoundTrip(t *testing.T) {

gateway/internal/transcode/transcode_test.go

@@ -59,7 +59,7 @@ func TestGameStateRoundTripForwardsUserID(t *testing.T) {
 		if r.URL.Path != "/api/v1/user/games/g-1/state" {
 			t.Errorf("unexpected path %q", r.URL.Path)
 		}
-		_, _ = w.Write([]byte(`{"game":{"id":"g-1","variant":"scrabble_en","status":"active","players":2,"to_move":1,"seats":[{"seat":0,"account_id":"u-7","score":5}]},"seat":0,"rack":[0,1],"bag_len":80,"hints_remaining":1}`))
+		_, _ = w.Write([]byte(`{"game":{"id":"g-1","variant":"scrabble_en","status":"active","players":2,"to_move":1,"seats":[{"seat":0,"account_id":"u-7","score":5}]},"seat":0,"rack":[0,1],"bag_len":80,"hints_remaining":4,"wallet_balance":3}`))
 	})
 	defer cleanup()
 
@@ -77,8 +77,8 @@ func TestGameStateRoundTripForwardsUserID(t *testing.T) {
 		t.Fatalf("handler: %v", err)
 	}
 	st := fb.GetRootAsStateView(payload, 0)
-	if st.BagLen() != 80 || st.RackLength() != 2 || st.HintsRemaining() != 1 {
-		t.Fatalf("state decoded wrong: bag=%d rack=%d hints=%d", st.BagLen(), st.RackLength(), st.HintsRemaining())
+	if st.BagLen() != 80 || st.RackLength() != 2 || st.HintsRemaining() != 4 || st.WalletBalance() != 3 {
+		t.Fatalf("state decoded wrong: bag=%d rack=%d hints=%d wallet=%d", st.BagLen(), st.RackLength(), st.HintsRemaining(), st.WalletBalance())
 	}
 	game := st.Game(nil)
 	if game == nil || string(game.Id()) != "g-1" || string(game.Variant()) != "scrabble_en" || game.ToMove() != 1 {
@@ -317,7 +317,7 @@ func TestHintRoundTrip(t *testing.T) {
 		if r.URL.Path != "/api/v1/user/games/g-3/hint" {
 			t.Errorf("unexpected path %q", r.URL.Path)
 		}
-		_, _ = w.Write([]byte(`{"move":{"player":0,"action":"play","words":["CAT"],"score":9},"hints_remaining":2}`))
+		_, _ = w.Write([]byte(`{"move":{"player":0,"action":"play","words":["CAT"],"score":9},"hints_remaining":2,"wallet_balance":1}`))
 	})
 	defer cleanup()
 
@@ -328,8 +328,8 @@ func TestHintRoundTrip(t *testing.T) {
 		t.Fatalf("handler: %v", err)
 	}
 	hr := fb.GetRootAsHintResult(payload, 0)
-	if hr.HintsRemaining() != 2 {
-		t.Errorf("hints remaining = %d, want 2", hr.HintsRemaining())
+	if hr.HintsRemaining() != 2 || hr.WalletBalance() != 1 {
+		t.Errorf("hint decoded wrong: hints=%d wallet=%d", hr.HintsRemaining(), hr.WalletBalance())
 	}
 	var move fb.MoveRecord
 	hr.Move(&move)