fix(hint): stop the hint count going stale across games

The in-game hint badge re-fetched on entry and, for a game where it was the
player's turn, showed a too-high count that "reset" (e.g. back to 11) — the
wallet hint spent in another game was not reflected.

Root cause: the server sends one hints_remaining = per-game allowance + global
wallet, and the client cached that combined number per game. The wallet is
global, so spending a wallet hint in one game left every other game's cached
count stale (a my-turn game holds the stalest value: the opponent-moved delta
preserves the old number, whereas a game you just moved in re-cached a fresh
one). The backend allowance-then-wallet spend order was already correct.

Fix: split the two. StateView/HintResult gain a trailing wallet_balance field
(the global wallet alone); the client derives the per-game allowance as
hints_remaining - wallet_balance (stable, cacheable) and reads the wallet live
from the profile, refreshing it from every state/hint response. The badge is
allowance + live wallet, so a wallet hint anywhere updates every game at once.

- wire: scrabble.fbs StateView/HintResult + pkg/wire.BuildStateView (the single
  encoder for both the gateway transcode and the backend's event StateView),
  gateway encode + resp structs, regen.
- backend: game StateView/HintResult + service (GameState/Hint) + eventwire +
  notify PlayerState/encode + server DTOs.
- ui: lib/hints.ts (pure hintsLeft), Game.svelte (badge + syncWallet on
  load/hint, carry wallet_balance through applyMoveResult), codec/model, mock.
- docs: ARCHITECTURE §Hint.

Tests: hints.ts unit (incl. the staleness case), TestHintPolicy extended
(wallet_balance + allowance-first), gateway state/hint round-trips.

backend/internal/game/eventwire.go

@@ -74,6 +74,7 @@ func playerState(v StateView, names []string, includeAlphabet bool) (notify.Play
 		Rack:           rack,
 		BagLen:         v.BagLen,
 		HintsRemaining: v.HintsRemaining,
+		WalletBalance:  v.WalletBalance,
 	}
 	if includeAlphabet {
 		tab, err := engine.AlphabetTable(v.Game.Variant)

backend/internal/game/service.go

@@ -1042,7 +1042,7 @@ func (svc *Service) Hint(ctx context.Context, gameID, accountID uuid.UUID) (Hint
 		}
 		walletAfter--
 	}
-	return HintResult{Move: move, HintsRemaining: hintsRemaining(pre.HintsPerPlayer, used, walletAfter)}, nil
+	return HintResult{Move: move, HintsRemaining: hintsRemaining(pre.HintsPerPlayer, used, walletAfter), WalletBalance: walletAfter}, nil
 }
 
 // Candidates returns the to-move player's legal plays for a seated player on
@@ -1130,6 +1130,7 @@ func (svc *Service) GameState(ctx context.Context, gameID, accountID uuid.UUID)
 		Rack:           g.Hand(seat),
 		BagLen:         g.BagLen(),
 		HintsRemaining: hintsRemaining(pre.HintsPerPlayer, pre.Seats[seat].HintsUsed, acc.HintBalance),
+		WalletBalance:  acc.HintBalance,
 	}, nil
 }
 

backend/internal/game/types.go

@@ -194,10 +194,13 @@ type MoveResult struct {
 }
 
 // HintResult is a revealed hint and the requesting player's remaining hint
-// budget (per-seat allowance plus profile wallet) after spending one.
+// budget (per-seat allowance plus profile wallet) after spending one. WalletBalance is
+// the global wallet alone, so the client can keep its live wallet authoritative and
+// re-derive the per-game allowance (HintsRemaining - WalletBalance).
 type HintResult struct {
 	Move           engine.MoveRecord
 	HintsRemaining int
+	WalletBalance  int
 }
 
 // EvalResult previews a tentative play without committing it. Dir is the
@@ -220,6 +223,9 @@ type StateView struct {
 	Rack           []string
 	BagLen         int
 	HintsRemaining int
+	// WalletBalance is the player's global hint-wallet balance alone (HintsRemaining folds
+	// it in with the per-game allowance), so the client keeps the wallet live across games.
+	WalletBalance int
 }
 
 // HistoryMove is one decoded journal row, independent of any dictionary.

backend/internal/inttest/game_test.go

@@ -408,6 +408,15 @@ func TestHintPolicy(t *testing.T) {
 	if _, err := svc.Hint(ctx, g.ID, seats[0]); err != nil { // spends the allowance
 		t.Fatalf("first hint: %v", err)
 	}
+	// The allowance is spent before the wallet: with an empty wallet, the state now reports no
+	// hints left and a zero wallet, so the per-game allowance (HintsRemaining-WalletBalance) is 0.
+	st, err := svc.GameState(ctx, g.ID, seats[0])
+	if err != nil {
+		t.Fatalf("state: %v", err)
+	}
+	if st.HintsRemaining != 0 || st.WalletBalance != 0 {
+		t.Errorf("after allowance hint: hints=%d wallet=%d, want 0/0", st.HintsRemaining, st.WalletBalance)
+	}
 	if _, err := svc.Hint(ctx, g.ID, seats[0]); !errors.Is(err, game.ErrNoHintsLeft) {
 		t.Fatalf("second hint = %v, want ErrNoHintsLeft", err)
 	}
@@ -416,8 +425,9 @@ func TestHintPolicy(t *testing.T) {
 	if err != nil {
 		t.Fatalf("wallet hint: %v", err)
 	}
-	if res.HintsRemaining != 1 {
-		t.Errorf("hints remaining = %d, want 1", res.HintsRemaining)
+	// The allowance stays exhausted; the wallet dropped 2->1, and WalletBalance carries it alone.
+	if res.HintsRemaining != 1 || res.WalletBalance != 1 {
+		t.Errorf("wallet hint: hints=%d wallet=%d, want 1/1", res.HintsRemaining, res.WalletBalance)
 	}
 
 	off, err := svc.Create(ctx, game.CreateParams{

backend/internal/notify/encode.go

@@ -83,6 +83,7 @@ func buildStateView(b *flatbuffers.Builder, s PlayerState) flatbuffers.UOffsetT
 		Rack:           s.Rack,
 		BagLen:         s.BagLen,
 		HintsRemaining: s.HintsRemaining,
+		WalletBalance:  s.WalletBalance,
 		Alphabet:       alphabet,
 	})
 }

backend/internal/notify/payload.go

@@ -56,6 +56,7 @@ type PlayerState struct {
 	Rack           []int
 	BagLen         int
 	HintsRemaining int
+	WalletBalance  int
 	Alphabet       []AlphabetLetter
 }
 

backend/internal/server/dto.go

@@ -140,6 +140,7 @@ type stateDTO struct {
 	Rack           []int              `json:"rack"`
 	BagLen         int                `json:"bag_len"`
 	HintsRemaining int                `json:"hints_remaining"`
+	WalletBalance  int                `json:"wallet_balance"`
 	Alphabet       []alphabetEntryDTO `json:"alphabet,omitempty"`
 }
 
@@ -291,6 +292,7 @@ func stateDTOFrom(v game.StateView, includeAlphabet bool) (stateDTO, error) {
 		Rack:           rack,
 		BagLen:         v.BagLen,
 		HintsRemaining: v.HintsRemaining,
+		WalletBalance:  v.WalletBalance,
 	}
 	if includeAlphabet {
 		tab, err := engine.AlphabetTable(v.Game.Variant)

backend/internal/server/handlers_game.go

@@ -20,6 +20,7 @@ import (
 type hintResultDTO struct {
 	Move           moveRecordDTO `json:"move"`
 	HintsRemaining int           `json:"hints_remaining"`
+	WalletBalance  int           `json:"wallet_balance"`
 }
 
 // evalResultDTO is an unlimited move preview: legality, score, the words formed
@@ -185,6 +186,7 @@ func (s *Server) handleHint(c *gin.Context) {
 	c.JSON(http.StatusOK, hintResultDTO{
 		Move:           moveRecordDTOFrom(h.Move),
 		HintsRemaining: h.HintsRemaining,
+		WalletBalance:  h.WalletBalance,
 	})
 }