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.

ui/src/game/Game.svelte

@@ -18,6 +18,7 @@
   import { centre, premiumGrid } from '../lib/premiums';
   import { variantNameKey } from '../lib/variants';
   import { alphabetLetters, hasAlphabet } from '../lib/alphabet';
+  import { hintsLeft } from '../lib/hints';
   import { shareOrDownloadGcg } from '../lib/share';
   import { getCachedGame, setCachedGame, setCachedDraft, type CachedGame } from '../lib/gamecache';
   import { patchLobbyGame } from '../lib/lobbycache';
@@ -132,6 +133,10 @@
   const playable = $derived(!!view && (view.game.status === 'active' || view.game.status === 'open'));
   const isMyTurn = $derived(!!view && playable && view.game.toMove === view.seat);
   const gameOver = $derived(!!view && view.game.status === 'finished');
+  // The hint badge: this game's allowance remaining plus the LIVE global wallet. Reading the
+  // wallet from the profile (not the per-game view snapshot) keeps it correct after a wallet
+  // hint was spent in another game (see lib/hints).
+  const hintCount = $derived(hintsLeft(view, app.profile?.hintBalance ?? 0));
   // RACK_SIZE mirrors the engine's rules.RackSize (7 for every current variant). The exchange
   // gate is only a UX guard: the backend stays the source of truth and rejects an under-supplied
   // exchange regardless (engine rejects when bag.Len() < rules.RackSize).
@@ -154,6 +159,13 @@
     return MOVE_LABELS.has(action) ? t(`move.${action}` as MessageKey) : action;
   }
 
+  // syncWallet adopts the server's authoritative hint-wallet balance into the global profile.
+  // The wallet is global, so keeping it live here (rather than per-game) is what stops the hint
+  // badge from going stale when a wallet hint was spent in another game.
+  function syncWallet(walletBalance: number) {
+    if (app.profile) app.profile.hintBalance = walletBalance;
+  }
+
   async function load() {
     try {
       // Ask for the alphabet table only on a per-variant cache miss (the first open of a
@@ -167,6 +179,7 @@
         gateway.draftGet(id).catch(() => ''),
       ]);
       view = st;
+      syncWallet(st.walletBalance);
       // Seed the unread flag from the authoritative state (the live stream only raises it).
       seedChatUnread(id, st.game.unreadChat);
       moves = hist.moves;
@@ -615,7 +628,16 @@
   // applyMoveResult renders the actor's own just-committed move from the response — the move, the
   // post-move game and the refilled rack — without a follow-up game.state + game.history.
   function applyMoveResult(r: MoveResult) {
-    view = { game: r.game, seat: r.move.player, rack: r.rack, bagLen: r.bagLen, hintsRemaining: view?.hintsRemaining ?? 0 };
+    view = {
+      game: r.game,
+      seat: r.move.player,
+      rack: r.rack,
+      bagLen: r.bagLen,
+      // A move is not a hint, so the per-game allowance and the wallet are unchanged: carry both
+      // forward (their difference is the stable allowance; the badge adds the live wallet).
+      hintsRemaining: view?.hintsRemaining ?? 0,
+      walletBalance: view?.walletBalance ?? 0,
+    };
     // The move result is an authoritative per-viewer view: a nudge the actor just answered by
     // moving is already cleared server-side, so reconcile the unread flag from it.
     seedChatUnread(id, r.game.unreadChat);
@@ -698,7 +720,8 @@
           recenter++;
         }
         if (isCoarse()) zoomed = true;
-        view = { ...view, hintsRemaining: h.hintsRemaining };
+        view = { ...view, hintsRemaining: h.hintsRemaining, walletBalance: h.walletBalance };
+        syncWallet(h.walletBalance);
         recompute();
       }
     } catch (e) {
@@ -1107,10 +1130,10 @@
   <TapConfirm
     triggerClass="tab"
     label={t('game.hint')}
-    disabled={busy || !isMyTurn || !connection.online || (view?.hintsRemaining ?? 0) <= 0}
+    disabled={busy || !isMyTurn || !connection.online || hintCount <= 0}
     onconfirm={doHint}
   >
-    <span class="sq">🛟{#if (view?.hintsRemaining ?? 0) > 0}<span class="badge">{view?.hintsRemaining}</span>{/if}</span>
+    <span class="sq">🛟{#if hintCount > 0}<span class="badge">{hintCount}</span>{/if}</span>
     <span class="lbl">{t('game.hint')}</span>
   </TapConfirm>
   {#if placement.pending.length > 0}

ui/src/gen/fbs/scrabblefb/hint-result.ts

@@ -33,8 +33,13 @@ hintsRemaining():number {
   return offset ? this.bb!.readInt32(this.bb_pos + offset) : 0;
 }
 
+walletBalance():number {
+  const offset = this.bb!.__offset(this.bb_pos, 8);
+  return offset ? this.bb!.readInt32(this.bb_pos + offset) : 0;
+}
+
 static startHintResult(builder:flatbuffers.Builder) {
-  builder.startObject(2);
+  builder.startObject(3);
 }
 
 static addMove(builder:flatbuffers.Builder, moveOffset:flatbuffers.Offset) {
@@ -45,15 +50,20 @@ static addHintsRemaining(builder:flatbuffers.Builder, hintsRemaining:number) {
   builder.addFieldInt32(1, hintsRemaining, 0);
 }
 
+static addWalletBalance(builder:flatbuffers.Builder, walletBalance:number) {
+  builder.addFieldInt32(2, walletBalance, 0);
+}
+
 static endHintResult(builder:flatbuffers.Builder):flatbuffers.Offset {
   const offset = builder.endObject();
   return offset;
 }
 
-static createHintResult(builder:flatbuffers.Builder, moveOffset:flatbuffers.Offset, hintsRemaining:number):flatbuffers.Offset {
+static createHintResult(builder:flatbuffers.Builder, moveOffset:flatbuffers.Offset, hintsRemaining:number, walletBalance:number):flatbuffers.Offset {
   HintResult.startHintResult(builder);
   HintResult.addMove(builder, moveOffset);
   HintResult.addHintsRemaining(builder, hintsRemaining);
+  HintResult.addWalletBalance(builder, walletBalance);
   return HintResult.endHintResult(builder);
 }
 }

ui/src/gen/fbs/scrabblefb/state-view.ts

@@ -69,8 +69,13 @@ alphabetLength():number {
   return offset ? this.bb!.__vector_len(this.bb_pos + offset) : 0;
 }
 
+walletBalance():number {
+  const offset = this.bb!.__offset(this.bb_pos, 16);
+  return offset ? this.bb!.readInt32(this.bb_pos + offset) : 0;
+}
+
 static startStateView(builder:flatbuffers.Builder) {
-  builder.startObject(6);
+  builder.startObject(7);
 }
 
 static addGame(builder:flatbuffers.Builder, gameOffset:flatbuffers.Offset) {
@@ -121,12 +126,16 @@ static startAlphabetVector(builder:flatbuffers.Builder, numElems:number) {
   builder.startVector(4, numElems, 4);
 }
 
+static addWalletBalance(builder:flatbuffers.Builder, walletBalance:number) {
+  builder.addFieldInt32(6, walletBalance, 0);
+}
+
 static endStateView(builder:flatbuffers.Builder):flatbuffers.Offset {
   const offset = builder.endObject();
   return offset;
 }
 
-static createStateView(builder:flatbuffers.Builder, gameOffset:flatbuffers.Offset, seat:number, rackOffset:flatbuffers.Offset, bagLen:number, hintsRemaining:number, alphabetOffset:flatbuffers.Offset):flatbuffers.Offset {
+static createStateView(builder:flatbuffers.Builder, gameOffset:flatbuffers.Offset, seat:number, rackOffset:flatbuffers.Offset, bagLen:number, hintsRemaining:number, alphabetOffset:flatbuffers.Offset, walletBalance:number):flatbuffers.Offset {
   StateView.startStateView(builder);
   StateView.addGame(builder, gameOffset);
   StateView.addSeat(builder, seat);
@@ -134,6 +143,7 @@ static createStateView(builder:flatbuffers.Builder, gameOffset:flatbuffers.Offse
   StateView.addBagLen(builder, bagLen);
   StateView.addHintsRemaining(builder, hintsRemaining);
   StateView.addAlphabet(builder, alphabetOffset);
+  StateView.addWalletBalance(builder, walletBalance);
   return StateView.endStateView(builder);
 }
 }

ui/src/lib/codec.ts

@@ -383,6 +383,7 @@ function decodeStateViewTable(v: fb.StateView): StateView {
     rack,
     bagLen: v.bagLen(),
     hintsRemaining: v.hintsRemaining(),
+    walletBalance: v.walletBalance(),
   };
 }
 
@@ -409,7 +410,7 @@ export function decodeMoveResult(buf: Uint8Array): MoveResult {
 export function decodeHintResult(buf: Uint8Array): HintResult {
   const r = fb.HintResult.getRootAsHintResult(new ByteBuffer(buf));
   const m = r.move();
-  return { move: m ? decodeMove(m) : emptyMove(), hintsRemaining: r.hintsRemaining() };
+  return { move: m ? decodeMove(m) : emptyMove(), hintsRemaining: r.hintsRemaining(), walletBalance: r.walletBalance() };
 }
 
 export function decodeEvalResult(buf: Uint8Array): EvalResult {

ui/src/lib/gamecache.test.ts

@@ -22,7 +22,7 @@ function gameView(id: string): GameView {
 }
 
 function view(id: string, rack: string[] = ['A', 'B']): StateView {
-  return { game: gameView(id), seat: 0, rack, bagLen: 50, hintsRemaining: 1 };
+  return { game: gameView(id), seat: 0, rack, bagLen: 50, hintsRemaining: 1, walletBalance: 0 };
 }
 
 function move(player: number): MoveRecord {

ui/src/lib/gamedelta.test.ts

@@ -27,7 +27,7 @@ function move(player: number): MoveRecord {
 }
 
 function cache(moveCount: number, seat = 0, over = false): CachedGame {
-  const view: StateView = { game: gameView(moveCount, over), seat, rack: ['a', 'b'], bagLen: 50, hintsRemaining: 1 };
+  const view: StateView = { game: gameView(moveCount, over), seat, rack: ['a', 'b'], bagLen: 50, hintsRemaining: 1, walletBalance: 0 };
   return { view, moves: [] };
 }
 
@@ -37,7 +37,7 @@ function delta(moveCount: number, player: number, bagLen = 47): MoveDelta {
 
 describe('seedInitialState', () => {
   it('wraps an initial view with an empty journal', () => {
-    const view: StateView = { game: gameView(0), seat: 1, rack: ['x'], bagLen: 80, hintsRemaining: 2 };
+    const view: StateView = { game: gameView(0), seat: 1, rack: ['x'], bagLen: 80, hintsRemaining: 2, walletBalance: 0 };
     expect(seedInitialState(view)).toEqual({ view, moves: [] });
   });
 });
@@ -152,12 +152,12 @@ describe('applyOpponentJoined', () => {
       { seat: 0, accountId: 'me', displayName: 'Me', score: 0, hintsUsed: 0, isWinner: false },
       { seat: 1, accountId: 'opp', displayName: 'Opp', score: 0, hintsUsed: 0, isWinner: false },
     ] };
-    return { game, seat: 0, rack: ['x'], bagLen: 90, hintsRemaining: 0 };
+    return { game, seat: 0, rack: ['x'], bagLen: 90, hintsRemaining: 0, walletBalance: 0 };
   }
 
   it("adopts the joined seats and status while preserving the cached rack and moves", () => {
     // The cached open game is still "searching": empty seats, status open, the starter's own rack.
-    const cached: CachedGame = { view: { game: { ...gameView(2), status: 'open', seats: [] }, seat: 0, rack: ['a', 'b'], bagLen: 50, hintsRemaining: 1 }, moves: [move(0)] };
+    const cached: CachedGame = { view: { game: { ...gameView(2), status: 'open', seats: [] }, seat: 0, rack: ['a', 'b'], bagLen: 50, hintsRemaining: 1, walletBalance: 0 }, moves: [move(0)] };
     const res = applyOpponentJoined(cached, joinedState());
     expect(res?.view.game.status).toBe('active');
     expect(res?.view.game.seats).toHaveLength(2);

ui/src/lib/hints.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from 'vitest';
+import { hintsLeft } from './hints';
+
+// view carries only the two fields hintsLeft reads.
+const view = (hintsRemaining: number, walletBalance: number) => ({ hintsRemaining, walletBalance });
+
+describe('hintsLeft', () => {
+  it('is zero without a view', () => {
+    expect(hintsLeft(null, 5)).toBe(0);
+  });
+
+  it('adds the per-game allowance to the live wallet (fresh view)', () => {
+    // hints_remaining 4 = allowance 1 + wallet 3; live wallet matches the snapshot → 1 + 3.
+    expect(hintsLeft(view(4, 3), 3)).toBe(4);
+  });
+
+  it('reflects the LIVE wallet, not the per-game snapshot (the staleness fix)', () => {
+    // The view was fetched when the wallet was 3 (allowance 1), but a wallet hint was since spent
+    // in another game, so the live wallet is 2: the count must drop to 1 + 2 = 3, not stay at 4.
+    expect(hintsLeft(view(4, 3), 2)).toBe(3);
+  });
+
+  it('shows just the wallet when the per-game allowance is used up', () => {
+    // allowance 0 (hints_remaining 3 == snapshot wallet 3); live wallet 3 → 0 + 3.
+    expect(hintsLeft(view(3, 3), 3)).toBe(3);
+  });
+
+  it('clamps a non-negative allowance and wallet', () => {
+    expect(hintsLeft(view(2, 3), 0)).toBe(0);
+    expect(hintsLeft(view(1, 0), -5)).toBe(1);
+  });
+});

ui/src/lib/hints.ts

@@ -0,0 +1,26 @@
+// Hint-count derivation, kept out of the .svelte component so it is unit-testable.
+//
+// The badge shows the per-game hint allowance remaining plus the player's global hint
+// wallet. The server's hints_remaining folds the two together, but the wallet is global —
+// shared across every game — so caching the combined number per game makes it go stale the
+// moment a wallet hint is spent in another game. We therefore split it: the per-game
+// allowance is hints_remaining - wallet_balance (both from the same fetch, so it is stable
+// and cacheable), and the wallet is read live from the global profile, never the per-game
+// snapshot.
+
+import type { StateView } from './model';
+
+/**
+ * hintsLeft is the hint count for the badge: the per-game allowance remaining (the view's
+ * hints_remaining minus the wallet snapshot baked into that same view) plus the live global
+ * wallet balance. Passing the live wallet (not view.walletBalance) is what keeps the count
+ * correct when a wallet hint was spent in another game since this view was fetched.
+ */
+export function hintsLeft(
+  view: Pick<StateView, 'hintsRemaining' | 'walletBalance'> | null,
+  walletBalance: number,
+): number {
+  if (!view) return 0;
+  const allowance = Math.max(0, view.hintsRemaining - view.walletBalance);
+  return allowance + Math.max(0, walletBalance);
+}

ui/src/lib/mock/client.ts

@@ -295,7 +295,10 @@ export class MockGateway implements GatewayClient {
       seat: this.mySeat(g),
       rack: [...g.rack],
       bagLen: g.bagLen,
-      hintsRemaining: g.hintsRemaining,
+      // g.hintsRemaining is the per-game allowance; the wallet is the shared profile balance.
+      // hints_remaining folds the two together (as the backend does), walletBalance is the wallet.
+      hintsRemaining: g.hintsRemaining + this.profile.hintBalance,
+      walletBalance: this.profile.hintBalance,
     };
   }
 
@@ -395,8 +398,11 @@ export class MockGateway implements GatewayClient {
 
   async hint(gameId: string): Promise<HintResult> {
     const g = this.game(gameId);
-    if (g.hintsRemaining <= 0) throw new GatewayError('hint_unavailable');
-    g.hintsRemaining -= 1;
+    if (g.hintsRemaining <= 0 && this.profile.hintBalance <= 0) throw new GatewayError('hint_unavailable');
+    // Spend the per-game allowance first, then the shared wallet — mirroring the backend, so a
+    // wallet hint in one game lowers the count shown in every other game (the bug this fixes).
+    if (g.hintsRemaining > 0) g.hintsRemaining -= 1;
+    else this.profile.hintBalance -= 1;
     const letter = g.rack.find((l) => l !== '?') ?? 'A';
     return {
       move: {
@@ -411,7 +417,8 @@ export class MockGateway implements GatewayClient {
         score: valueForLetter(g.view.variant, letter),
         total: 0,
       },
-      hintsRemaining: g.hintsRemaining,
+      hintsRemaining: g.hintsRemaining + this.profile.hintBalance,
+      walletBalance: this.profile.hintBalance,
     };
   }
 

ui/src/lib/model.ts

@@ -67,13 +67,17 @@ export interface MoveRecord {
   total: number;
 }
 
-/** A seated player's private view of a game. */
+/** A seated player's private view of a game. hintsRemaining folds the per-game allowance
+ *  together with the global wallet; walletBalance is the wallet alone, so the client can
+ *  derive the per-game allowance (hintsRemaining - walletBalance) and keep the wallet live
+ *  across games (see lib/hints). */
 export interface StateView {
   game: GameView;
   seat: number;
   rack: string[];
   bagLen: number;
   hintsRemaining: number;
+  walletBalance: number;
 }
 
 export interface MoveResult {
@@ -87,6 +91,7 @@ export interface MoveResult {
 export interface HintResult {
   move: MoveRecord;
   hintsRemaining: number;
+  walletBalance: number;
 }
 
 export interface EvalResult {

ui/src/lib/preload.test.ts

@@ -34,7 +34,7 @@ function gameView(id: string, status: GameView['status'] = 'active'): GameView {
 }
 
 function stateView(id: string): StateView {
-  return { game: gameView(id), seat: 0, rack: ['A', 'B'], bagLen: 50, hintsRemaining: 1 };
+  return { game: gameView(id), seat: 0, rack: ['A', 'B'], bagLen: 50, hintsRemaining: 1, walletBalance: 0 };
 }
 
 beforeEach(() => {