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.

ui/src/gen/fbs/scrabblefb.ts

@@ -5,6 +5,8 @@ export { Ack } from './scrabblefb/ack.js';
 export { AlphabetEntry } from './scrabblefb/alphabet-entry.js';
 export { BannerCampaign } from './scrabblefb/banner-campaign.js';
 export { BannerInfo } from './scrabblefb/banner-info.js';
+export { BestMoveTile } from './scrabblefb/best-move-tile.js';
+export { BestMoveView } from './scrabblefb/best-move-view.js';
 export { BlockList } from './scrabblefb/block-list.js';
 export { BlockStatus } from './scrabblefb/block-status.js';
 export { ChatList } from './scrabblefb/chat-list.js';

ui/src/gen/fbs/scrabblefb/best-move-tile.ts

@@ -0,0 +1,68 @@
+// automatically generated by the FlatBuffers compiler, do not modify
+
+import * as flatbuffers from 'flatbuffers';
+
+export class BestMoveTile {
+  bb: flatbuffers.ByteBuffer|null = null;
+  bb_pos = 0;
+  __init(i:number, bb:flatbuffers.ByteBuffer):BestMoveTile {
+  this.bb_pos = i;
+  this.bb = bb;
+  return this;
+}
+
+static getRootAsBestMoveTile(bb:flatbuffers.ByteBuffer, obj?:BestMoveTile):BestMoveTile {
+  return (obj || new BestMoveTile()).__init(bb.readInt32(bb.position()) + bb.position(), bb);
+}
+
+static getSizePrefixedRootAsBestMoveTile(bb:flatbuffers.ByteBuffer, obj?:BestMoveTile):BestMoveTile {
+  bb.setPosition(bb.position() + flatbuffers.SIZE_PREFIX_LENGTH);
+  return (obj || new BestMoveTile()).__init(bb.readInt32(bb.position()) + bb.position(), bb);
+}
+
+letter():string|null
+letter(optionalEncoding:flatbuffers.Encoding):string|Uint8Array|null
+letter(optionalEncoding?:any):string|Uint8Array|null {
+  const offset = this.bb!.__offset(this.bb_pos, 4);
+  return offset ? this.bb!.__string(this.bb_pos + offset, optionalEncoding) : null;
+}
+
+value():number {
+  const offset = this.bb!.__offset(this.bb_pos, 6);
+  return offset ? this.bb!.readInt32(this.bb_pos + offset) : 0;
+}
+
+blank():boolean {
+  const offset = this.bb!.__offset(this.bb_pos, 8);
+  return offset ? !!this.bb!.readInt8(this.bb_pos + offset) : false;
+}
+
+static startBestMoveTile(builder:flatbuffers.Builder) {
+  builder.startObject(3);
+}
+
+static addLetter(builder:flatbuffers.Builder, letterOffset:flatbuffers.Offset) {
+  builder.addFieldOffset(0, letterOffset, 0);
+}
+
+static addValue(builder:flatbuffers.Builder, value:number) {
+  builder.addFieldInt32(1, value, 0);
+}
+
+static addBlank(builder:flatbuffers.Builder, blank:boolean) {
+  builder.addFieldInt8(2, +blank, +false);
+}
+
+static endBestMoveTile(builder:flatbuffers.Builder):flatbuffers.Offset {
+  const offset = builder.endObject();
+  return offset;
+}
+
+static createBestMoveTile(builder:flatbuffers.Builder, letterOffset:flatbuffers.Offset, value:number, blank:boolean):flatbuffers.Offset {
+  BestMoveTile.startBestMoveTile(builder);
+  BestMoveTile.addLetter(builder, letterOffset);
+  BestMoveTile.addValue(builder, value);
+  BestMoveTile.addBlank(builder, blank);
+  return BestMoveTile.endBestMoveTile(builder);
+}
+}

ui/src/gen/fbs/scrabblefb/best-move-view.ts

@@ -0,0 +1,88 @@
+// automatically generated by the FlatBuffers compiler, do not modify
+
+import * as flatbuffers from 'flatbuffers';
+
+import { BestMoveTile } from '../scrabblefb/best-move-tile.js';
+
+
+export class BestMoveView {
+  bb: flatbuffers.ByteBuffer|null = null;
+  bb_pos = 0;
+  __init(i:number, bb:flatbuffers.ByteBuffer):BestMoveView {
+  this.bb_pos = i;
+  this.bb = bb;
+  return this;
+}
+
+static getRootAsBestMoveView(bb:flatbuffers.ByteBuffer, obj?:BestMoveView):BestMoveView {
+  return (obj || new BestMoveView()).__init(bb.readInt32(bb.position()) + bb.position(), bb);
+}
+
+static getSizePrefixedRootAsBestMoveView(bb:flatbuffers.ByteBuffer, obj?:BestMoveView):BestMoveView {
+  bb.setPosition(bb.position() + flatbuffers.SIZE_PREFIX_LENGTH);
+  return (obj || new BestMoveView()).__init(bb.readInt32(bb.position()) + bb.position(), bb);
+}
+
+variant():string|null
+variant(optionalEncoding:flatbuffers.Encoding):string|Uint8Array|null
+variant(optionalEncoding?:any):string|Uint8Array|null {
+  const offset = this.bb!.__offset(this.bb_pos, 4);
+  return offset ? this.bb!.__string(this.bb_pos + offset, optionalEncoding) : null;
+}
+
+score():number {
+  const offset = this.bb!.__offset(this.bb_pos, 6);
+  return offset ? this.bb!.readInt32(this.bb_pos + offset) : 0;
+}
+
+word(index: number, obj?:BestMoveTile):BestMoveTile|null {
+  const offset = this.bb!.__offset(this.bb_pos, 8);
+  return offset ? (obj || new BestMoveTile()).__init(this.bb!.__indirect(this.bb!.__vector(this.bb_pos + offset) + index * 4), this.bb!) : null;
+}
+
+wordLength():number {
+  const offset = this.bb!.__offset(this.bb_pos, 8);
+  return offset ? this.bb!.__vector_len(this.bb_pos + offset) : 0;
+}
+
+static startBestMoveView(builder:flatbuffers.Builder) {
+  builder.startObject(3);
+}
+
+static addVariant(builder:flatbuffers.Builder, variantOffset:flatbuffers.Offset) {
+  builder.addFieldOffset(0, variantOffset, 0);
+}
+
+static addScore(builder:flatbuffers.Builder, score:number) {
+  builder.addFieldInt32(1, score, 0);
+}
+
+static addWord(builder:flatbuffers.Builder, wordOffset:flatbuffers.Offset) {
+  builder.addFieldOffset(2, wordOffset, 0);
+}
+
+static createWordVector(builder:flatbuffers.Builder, data:flatbuffers.Offset[]):flatbuffers.Offset {
+  builder.startVector(4, data.length, 4);
+  for (let i = data.length - 1; i >= 0; i--) {
+    builder.addOffset(data[i]!);
+  }
+  return builder.endVector();
+}
+
+static startWordVector(builder:flatbuffers.Builder, numElems:number) {
+  builder.startVector(4, numElems, 4);
+}
+
+static endBestMoveView(builder:flatbuffers.Builder):flatbuffers.Offset {
+  const offset = builder.endObject();
+  return offset;
+}
+
+static createBestMoveView(builder:flatbuffers.Builder, variantOffset:flatbuffers.Offset, score:number, wordOffset:flatbuffers.Offset):flatbuffers.Offset {
+  BestMoveView.startBestMoveView(builder);
+  BestMoveView.addVariant(builder, variantOffset);
+  BestMoveView.addScore(builder, score);
+  BestMoveView.addWord(builder, wordOffset);
+  return BestMoveView.endBestMoveView(builder);
+}
+}

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/gen/fbs/scrabblefb/stats-view.ts

@@ -2,6 +2,9 @@
 
 import * as flatbuffers from 'flatbuffers';
 
+import { BestMoveView } from '../scrabblefb/best-move-view.js';
+
+
 export class StatsView {
   bb: flatbuffers.ByteBuffer|null = null;
   bb_pos = 0;
@@ -45,8 +48,28 @@ maxWordPoints():number {
   return offset ? this.bb!.readInt32(this.bb_pos + offset) : 0;
 }
 
+bestMoves(index: number, obj?:BestMoveView):BestMoveView|null {
+  const offset = this.bb!.__offset(this.bb_pos, 14);
+  return offset ? (obj || new BestMoveView()).__init(this.bb!.__indirect(this.bb!.__vector(this.bb_pos + offset) + index * 4), this.bb!) : null;
+}
+
+bestMovesLength():number {
+  const offset = this.bb!.__offset(this.bb_pos, 14);
+  return offset ? this.bb!.__vector_len(this.bb_pos + offset) : 0;
+}
+
+moves():number {
+  const offset = this.bb!.__offset(this.bb_pos, 16);
+  return offset ? this.bb!.readInt32(this.bb_pos + offset) : 0;
+}
+
+hintsUsed():number {
+  const offset = this.bb!.__offset(this.bb_pos, 18);
+  return offset ? this.bb!.readInt32(this.bb_pos + offset) : 0;
+}
+
 static startStatsView(builder:flatbuffers.Builder) {
-  builder.startObject(5);
+  builder.startObject(8);
 }
 
 static addWins(builder:flatbuffers.Builder, wins:number) {
@@ -69,18 +92,45 @@ static addMaxWordPoints(builder:flatbuffers.Builder, maxWordPoints:number) {
   builder.addFieldInt32(4, maxWordPoints, 0);
 }
 
+static addBestMoves(builder:flatbuffers.Builder, bestMovesOffset:flatbuffers.Offset) {
+  builder.addFieldOffset(5, bestMovesOffset, 0);
+}
+
+static createBestMovesVector(builder:flatbuffers.Builder, data:flatbuffers.Offset[]):flatbuffers.Offset {
+  builder.startVector(4, data.length, 4);
+  for (let i = data.length - 1; i >= 0; i--) {
+    builder.addOffset(data[i]!);
+  }
+  return builder.endVector();
+}
+
+static startBestMovesVector(builder:flatbuffers.Builder, numElems:number) {
+  builder.startVector(4, numElems, 4);
+}
+
+static addMoves(builder:flatbuffers.Builder, moves:number) {
+  builder.addFieldInt32(6, moves, 0);
+}
+
+static addHintsUsed(builder:flatbuffers.Builder, hintsUsed:number) {
+  builder.addFieldInt32(7, hintsUsed, 0);
+}
+
 static endStatsView(builder:flatbuffers.Builder):flatbuffers.Offset {
   const offset = builder.endObject();
   return offset;
 }
 
-static createStatsView(builder:flatbuffers.Builder, wins:number, losses:number, draws:number, maxGamePoints:number, maxWordPoints:number):flatbuffers.Offset {
+static createStatsView(builder:flatbuffers.Builder, wins:number, losses:number, draws:number, maxGamePoints:number, maxWordPoints:number, bestMovesOffset:flatbuffers.Offset, moves:number, hintsUsed:number):flatbuffers.Offset {
   StatsView.startStatsView(builder);
   StatsView.addWins(builder, wins);
   StatsView.addLosses(builder, losses);
   StatsView.addDraws(builder, draws);
   StatsView.addMaxGamePoints(builder, maxGamePoints);
   StatsView.addMaxWordPoints(builder, maxWordPoints);
+  StatsView.addBestMoves(builder, bestMovesOffset);
+  StatsView.addMoves(builder, moves);
+  StatsView.addHintsUsed(builder, hintsUsed);
   return StatsView.endStatsView(builder);
 }
 }