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.

pkg/fbs/scrabble.fbs

@@ -240,6 +240,12 @@ table StateView {
   bag_len:int;
   hints_remaining:int;
   alphabet:[AlphabetEntry];
+  // wallet_balance is the requesting player's global hint-wallet balance, sent apart from
+  // hints_remaining (which folds the wallet in with the per-game allowance) so the client can
+  // separate the two: the per-game allowance remaining is hints_remaining - wallet_balance, and
+  // the wallet is a single global figure the client keeps live across games (added trailing —
+  // backward-compatible).
+  wallet_balance:int;
 }
 
 // GameActionRequest carries just a game id (pass / resign / hint / history).
@@ -290,10 +296,14 @@ table ComplaintRequest {
   note:string;
 }
 
-// HintResult is the top-ranked move plus the remaining hint budget.
+// HintResult is the top-ranked move plus the remaining hint budget. wallet_balance is the
+// global hint-wallet balance after spending (see StateView.wallet_balance), so the client
+// refreshes its live wallet and re-derives the per-game allowance (added trailing —
+// backward-compatible).
 table HintResult {
   move:MoveRecord;
   hints_remaining:int;
+  wallet_balance:int;
 }
 
 // DraftRequest saves the player's client-side composition for a game: a single
@@ -458,14 +468,39 @@ table LinkResult {
   session:Session;
 }
 
+// BestMoveTile is one letter cell of a best-move word: its concrete letter (the designated
+// letter for a blank), its tile point value (0 for a blank) and whether it is a blank. It
+// lets the client render the word as game tiles without the variant's alphabet table.
+table BestMoveTile {
+  letter:string;
+  value:int;
+  blank:bool;
+}
+
+// BestMoveView is an account's highest-scoring single play within one game variant: the
+// variant label, the play's total score (matching max_word_points for that variant) and its
+// main word as ordered tiles.
+table BestMoveView {
+  variant:string;
+  score:int;
+  word:[BestMoveTile];
+}
+
 // StatsView is a durable account's lifetime statistics (games-played and win-rate
-// are derived client-side).
+// are derived client-side). best_moves breaks the best move down per variant, carrying the
+// word itself; it is empty for an account with no recorded play and lists only variants the
+// account has played (added trailing — backward-compatible).
 table StatsView {
   wins:int;
   losses:int;
   draws:int;
   max_game_points:int;
   max_word_points:int;
+  best_moves:[BestMoveView];
+  // moves is the player's lifetime play count (tile placements); hints_used is their lifetime
+  // hint count. The screen shows the hint share = hints_used / moves (added trailing).
+  moves:int;
+  hints_used:int;
 }
 
 // TargetRequest names a single counterpart account (friend request/cancel/unfriend,

pkg/fbs/scrabblefb/BestMoveTile.go

@@ -0,0 +1,90 @@
+// Code generated by the FlatBuffers compiler. DO NOT EDIT.
+
+package scrabblefb
+
+import (
+	flatbuffers "github.com/google/flatbuffers/go"
+)
+
+type BestMoveTile struct {
+	_tab flatbuffers.Table
+}
+
+func GetRootAsBestMoveTile(buf []byte, offset flatbuffers.UOffsetT) *BestMoveTile {
+	n := flatbuffers.GetUOffsetT(buf[offset:])
+	x := &BestMoveTile{}
+	x.Init(buf, n+offset)
+	return x
+}
+
+func FinishBestMoveTileBuffer(builder *flatbuffers.Builder, offset flatbuffers.UOffsetT) {
+	builder.Finish(offset)
+}
+
+func GetSizePrefixedRootAsBestMoveTile(buf []byte, offset flatbuffers.UOffsetT) *BestMoveTile {
+	n := flatbuffers.GetUOffsetT(buf[offset+flatbuffers.SizeUint32:])
+	x := &BestMoveTile{}
+	x.Init(buf, n+offset+flatbuffers.SizeUint32)
+	return x
+}
+
+func FinishSizePrefixedBestMoveTileBuffer(builder *flatbuffers.Builder, offset flatbuffers.UOffsetT) {
+	builder.FinishSizePrefixed(offset)
+}
+
+func (rcv *BestMoveTile) Init(buf []byte, i flatbuffers.UOffsetT) {
+	rcv._tab.Bytes = buf
+	rcv._tab.Pos = i
+}
+
+func (rcv *BestMoveTile) Table() flatbuffers.Table {
+	return rcv._tab
+}
+
+func (rcv *BestMoveTile) Letter() []byte {
+	o := flatbuffers.UOffsetT(rcv._tab.Offset(4))
+	if o != 0 {
+		return rcv._tab.ByteVector(o + rcv._tab.Pos)
+	}
+	return nil
+}
+
+func (rcv *BestMoveTile) Value() int32 {
+	o := flatbuffers.UOffsetT(rcv._tab.Offset(6))
+	if o != 0 {
+		return rcv._tab.GetInt32(o + rcv._tab.Pos)
+	}
+	return 0
+}
+
+func (rcv *BestMoveTile) MutateValue(n int32) bool {
+	return rcv._tab.MutateInt32Slot(6, n)
+}
+
+func (rcv *BestMoveTile) Blank() bool {
+	o := flatbuffers.UOffsetT(rcv._tab.Offset(8))
+	if o != 0 {
+		return rcv._tab.GetBool(o + rcv._tab.Pos)
+	}
+	return false
+}
+
+func (rcv *BestMoveTile) MutateBlank(n bool) bool {
+	return rcv._tab.MutateBoolSlot(8, n)
+}
+
+func BestMoveTileStart(builder *flatbuffers.Builder) {
+	builder.StartObject(3)
+}
+func BestMoveTileAddLetter(builder *flatbuffers.Builder, letter flatbuffers.UOffsetT) {
+	builder.PrependUOffsetTSlot(0, flatbuffers.UOffsetT(letter), 0)
+}
+func BestMoveTileAddValue(builder *flatbuffers.Builder, value int32) {
+	builder.PrependInt32Slot(1, value, 0)
+}
+func BestMoveTileAddBlank(builder *flatbuffers.Builder, blank bool) {
+	builder.PrependBoolSlot(2, blank, false)
+}
+func BestMoveTileEnd(builder *flatbuffers.Builder) flatbuffers.UOffsetT {
+	return builder.EndObject()
+}

pkg/fbs/scrabblefb/BestMoveView.go

@@ -0,0 +1,101 @@
+// Code generated by the FlatBuffers compiler. DO NOT EDIT.
+
+package scrabblefb
+
+import (
+	flatbuffers "github.com/google/flatbuffers/go"
+)
+
+type BestMoveView struct {
+	_tab flatbuffers.Table
+}
+
+func GetRootAsBestMoveView(buf []byte, offset flatbuffers.UOffsetT) *BestMoveView {
+	n := flatbuffers.GetUOffsetT(buf[offset:])
+	x := &BestMoveView{}
+	x.Init(buf, n+offset)
+	return x
+}
+
+func FinishBestMoveViewBuffer(builder *flatbuffers.Builder, offset flatbuffers.UOffsetT) {
+	builder.Finish(offset)
+}
+
+func GetSizePrefixedRootAsBestMoveView(buf []byte, offset flatbuffers.UOffsetT) *BestMoveView {
+	n := flatbuffers.GetUOffsetT(buf[offset+flatbuffers.SizeUint32:])
+	x := &BestMoveView{}
+	x.Init(buf, n+offset+flatbuffers.SizeUint32)
+	return x
+}
+
+func FinishSizePrefixedBestMoveViewBuffer(builder *flatbuffers.Builder, offset flatbuffers.UOffsetT) {
+	builder.FinishSizePrefixed(offset)
+}
+
+func (rcv *BestMoveView) Init(buf []byte, i flatbuffers.UOffsetT) {
+	rcv._tab.Bytes = buf
+	rcv._tab.Pos = i
+}
+
+func (rcv *BestMoveView) Table() flatbuffers.Table {
+	return rcv._tab
+}
+
+func (rcv *BestMoveView) Variant() []byte {
+	o := flatbuffers.UOffsetT(rcv._tab.Offset(4))
+	if o != 0 {
+		return rcv._tab.ByteVector(o + rcv._tab.Pos)
+	}
+	return nil
+}
+
+func (rcv *BestMoveView) Score() int32 {
+	o := flatbuffers.UOffsetT(rcv._tab.Offset(6))
+	if o != 0 {
+		return rcv._tab.GetInt32(o + rcv._tab.Pos)
+	}
+	return 0
+}
+
+func (rcv *BestMoveView) MutateScore(n int32) bool {
+	return rcv._tab.MutateInt32Slot(6, n)
+}
+
+func (rcv *BestMoveView) Word(obj *BestMoveTile, j int) bool {
+	o := flatbuffers.UOffsetT(rcv._tab.Offset(8))
+	if o != 0 {
+		x := rcv._tab.Vector(o)
+		x += flatbuffers.UOffsetT(j) * 4
+		x = rcv._tab.Indirect(x)
+		obj.Init(rcv._tab.Bytes, x)
+		return true
+	}
+	return false
+}
+
+func (rcv *BestMoveView) WordLength() int {
+	o := flatbuffers.UOffsetT(rcv._tab.Offset(8))
+	if o != 0 {
+		return rcv._tab.VectorLen(o)
+	}
+	return 0
+}
+
+func BestMoveViewStart(builder *flatbuffers.Builder) {
+	builder.StartObject(3)
+}
+func BestMoveViewAddVariant(builder *flatbuffers.Builder, variant flatbuffers.UOffsetT) {
+	builder.PrependUOffsetTSlot(0, flatbuffers.UOffsetT(variant), 0)
+}
+func BestMoveViewAddScore(builder *flatbuffers.Builder, score int32) {
+	builder.PrependInt32Slot(1, score, 0)
+}
+func BestMoveViewAddWord(builder *flatbuffers.Builder, word flatbuffers.UOffsetT) {
+	builder.PrependUOffsetTSlot(2, flatbuffers.UOffsetT(word), 0)
+}
+func BestMoveViewStartWordVector(builder *flatbuffers.Builder, numElems int) flatbuffers.UOffsetT {
+	return builder.StartVector(4, numElems, 4)
+}
+func BestMoveViewEnd(builder *flatbuffers.Builder) flatbuffers.UOffsetT {
+	return builder.EndObject()
+}

pkg/fbs/scrabblefb/HintResult.go

@@ -66,8 +66,20 @@ func (rcv *HintResult) MutateHintsRemaining(n int32) bool {
 	return rcv._tab.MutateInt32Slot(6, n)
 }
 
+func (rcv *HintResult) WalletBalance() int32 {
+	o := flatbuffers.UOffsetT(rcv._tab.Offset(8))
+	if o != 0 {
+		return rcv._tab.GetInt32(o + rcv._tab.Pos)
+	}
+	return 0
+}
+
+func (rcv *HintResult) MutateWalletBalance(n int32) bool {
+	return rcv._tab.MutateInt32Slot(8, n)
+}
+
 func HintResultStart(builder *flatbuffers.Builder) {
-	builder.StartObject(2)
+	builder.StartObject(3)
 }
 func HintResultAddMove(builder *flatbuffers.Builder, move flatbuffers.UOffsetT) {
 	builder.PrependUOffsetTSlot(0, flatbuffers.UOffsetT(move), 0)
@@ -75,6 +87,9 @@ func HintResultAddMove(builder *flatbuffers.Builder, move flatbuffers.UOffsetT)
 func HintResultAddHintsRemaining(builder *flatbuffers.Builder, hintsRemaining int32) {
 	builder.PrependInt32Slot(1, hintsRemaining, 0)
 }
+func HintResultAddWalletBalance(builder *flatbuffers.Builder, walletBalance int32) {
+	builder.PrependInt32Slot(2, walletBalance, 0)
+}
 func HintResultEnd(builder *flatbuffers.Builder) flatbuffers.UOffsetT {
 	return builder.EndObject()
 }

pkg/fbs/scrabblefb/StateView.go

@@ -144,8 +144,20 @@ func (rcv *StateView) AlphabetLength() int {
 	return 0
 }
 
+func (rcv *StateView) WalletBalance() int32 {
+	o := flatbuffers.UOffsetT(rcv._tab.Offset(16))
+	if o != 0 {
+		return rcv._tab.GetInt32(o + rcv._tab.Pos)
+	}
+	return 0
+}
+
+func (rcv *StateView) MutateWalletBalance(n int32) bool {
+	return rcv._tab.MutateInt32Slot(16, n)
+}
+
 func StateViewStart(builder *flatbuffers.Builder) {
-	builder.StartObject(6)
+	builder.StartObject(7)
 }
 func StateViewAddGame(builder *flatbuffers.Builder, game flatbuffers.UOffsetT) {
 	builder.PrependUOffsetTSlot(0, flatbuffers.UOffsetT(game), 0)
@@ -171,6 +183,9 @@ func StateViewAddAlphabet(builder *flatbuffers.Builder, alphabet flatbuffers.UOf
 func StateViewStartAlphabetVector(builder *flatbuffers.Builder, numElems int) flatbuffers.UOffsetT {
 	return builder.StartVector(4, numElems, 4)
 }
+func StateViewAddWalletBalance(builder *flatbuffers.Builder, walletBalance int32) {
+	builder.PrependInt32Slot(6, walletBalance, 0)
+}
 func StateViewEnd(builder *flatbuffers.Builder) flatbuffers.UOffsetT {
 	return builder.EndObject()
 }

pkg/fbs/scrabblefb/StatsView.go

@@ -101,8 +101,52 @@ func (rcv *StatsView) MutateMaxWordPoints(n int32) bool {
 	return rcv._tab.MutateInt32Slot(12, n)
 }
 
+func (rcv *StatsView) BestMoves(obj *BestMoveView, j int) bool {
+	o := flatbuffers.UOffsetT(rcv._tab.Offset(14))
+	if o != 0 {
+		x := rcv._tab.Vector(o)
+		x += flatbuffers.UOffsetT(j) * 4
+		x = rcv._tab.Indirect(x)
+		obj.Init(rcv._tab.Bytes, x)
+		return true
+	}
+	return false
+}
+
+func (rcv *StatsView) BestMovesLength() int {
+	o := flatbuffers.UOffsetT(rcv._tab.Offset(14))
+	if o != 0 {
+		return rcv._tab.VectorLen(o)
+	}
+	return 0
+}
+
+func (rcv *StatsView) Moves() int32 {
+	o := flatbuffers.UOffsetT(rcv._tab.Offset(16))
+	if o != 0 {
+		return rcv._tab.GetInt32(o + rcv._tab.Pos)
+	}
+	return 0
+}
+
+func (rcv *StatsView) MutateMoves(n int32) bool {
+	return rcv._tab.MutateInt32Slot(16, n)
+}
+
+func (rcv *StatsView) HintsUsed() int32 {
+	o := flatbuffers.UOffsetT(rcv._tab.Offset(18))
+	if o != 0 {
+		return rcv._tab.GetInt32(o + rcv._tab.Pos)
+	}
+	return 0
+}
+
+func (rcv *StatsView) MutateHintsUsed(n int32) bool {
+	return rcv._tab.MutateInt32Slot(18, n)
+}
+
 func StatsViewStart(builder *flatbuffers.Builder) {
-	builder.StartObject(5)
+	builder.StartObject(8)
 }
 func StatsViewAddWins(builder *flatbuffers.Builder, wins int32) {
 	builder.PrependInt32Slot(0, wins, 0)
@@ -119,6 +163,18 @@ func StatsViewAddMaxGamePoints(builder *flatbuffers.Builder, maxGamePoints int32
 func StatsViewAddMaxWordPoints(builder *flatbuffers.Builder, maxWordPoints int32) {
 	builder.PrependInt32Slot(4, maxWordPoints, 0)
 }
+func StatsViewAddBestMoves(builder *flatbuffers.Builder, bestMoves flatbuffers.UOffsetT) {
+	builder.PrependUOffsetTSlot(5, flatbuffers.UOffsetT(bestMoves), 0)
+}
+func StatsViewStartBestMovesVector(builder *flatbuffers.Builder, numElems int) flatbuffers.UOffsetT {
+	return builder.StartVector(4, numElems, 4)
+}
+func StatsViewAddMoves(builder *flatbuffers.Builder, moves int32) {
+	builder.PrependInt32Slot(6, moves, 0)
+}
+func StatsViewAddHintsUsed(builder *flatbuffers.Builder, hintsUsed int32) {
+	builder.PrependInt32Slot(7, hintsUsed, 0)
+}
 func StatsViewEnd(builder *flatbuffers.Builder) flatbuffers.UOffsetT {
 	return builder.EndObject()
 }

pkg/wire/build.go

@@ -89,6 +89,7 @@ type StateView struct {
 	Rack           []int
 	BagLen         int
 	HintsRemaining int
+	WalletBalance  int
 	Alphabet       []AlphabetEntry
 }
 
@@ -250,6 +251,7 @@ func BuildStateView(b *flatbuffers.Builder, s StateView) flatbuffers.UOffsetT {
 	fb.StateViewAddRack(b, rack)
 	fb.StateViewAddBagLen(b, int32(s.BagLen))
 	fb.StateViewAddHintsRemaining(b, int32(s.HintsRemaining))
+	fb.StateViewAddWalletBalance(b, int32(s.WalletBalance))
 	if hasAlphabet {
 		fb.StateViewAddAlphabet(b, alphabet)
 	}