Add move ratings and player performance tracking

Author: Swon404

src/GameContext.tsx

@@ -2,13 +2,19 @@ import {
   createContext, ReactNode, useCallback, useContext, useEffect, useMemo, useReducer, useRef, useState
 } from "react";
 import {
-  GameState, Move, PieceType, Square, initialState, pieceAt
+  Color, GameState, Move, PieceType, Square, initialState, pieceAt
 } from "./engine/board";
 import {
   forfeitMove, gameResult, inCheck, legalMovesFrom, makeMove
 } from "./engine/rules";
 import { toSAN } from "./engine/notation";
 import { chooseBotMove } from "./engine/bot";
+import {
+  evaluateMoveFeedback,
+  type GamePerformanceSummary,
+  type MoveFeedback,
+  summarizeMoveGrades
+} from "./engine/performance";
 import { playSound } from "./engine/sound";
 import {
   load, Profile, recordResult, saveActiveGame, Settings, Store, updateSettings,
@@ -24,6 +30,26 @@ type Mode =
   | { kind: "portal"; opponent: "two-player" | { kind: "bot"; level: number }; creator: PieceType; portalMax?: number };
 export interface Players { w: string; b: string; }
 
+interface RatedMoveFeedback extends MoveFeedback {
+  color: Color;
+  moveNumber: number;
+  playerName: string;
+}
+
+export interface RatedMoveEntry extends RatedMoveFeedback {
+  san: string;
+}
+
+type CachedRatedMoveEntry = Omit<RatedMoveEntry, "playerName">;
+
+interface PlayerGamePerformance extends GamePerformanceSummary {
+  color: Color;
+  playerName: string;
+  addedStars: number;
+  totalStars: number | null;
+  mode: "bot" | "human";
+}
+
 interface NewGameOptions {
   timerSeconds?: number;
 }
@@ -70,6 +96,11 @@ interface GameCtx {
   requestHint(): void;
   clearHint(): void;
 
+  moveFeedback: RatedMoveFeedback | null;
+  clearMoveFeedback(): void;
+  ratedMoves: RatedMoveEntry[];
+  gamePerformance: { w: PlayerGamePerformance | null; b: PlayerGamePerformance | null };
+
   // profile & settings
   setActiveProfile(id: string | null): void;
   addProfile(name: string): Profile;
@@ -155,17 +186,56 @@ export function GameProvider({ children }: { children: ReactNode }) {
   const [hint, setHint] = useState<Move | null>(null);
   const [paused, setPaused] = useState(false);
   const [lastMoveReplayNonce, setLastMoveReplayNonce] = useState(0);
+  const [moveFeedback, setMoveFeedback] = useState<RatedMoveFeedback | null>(null);
+  const [gamePerformance, setGamePerformance] = useState<{ w: PlayerGamePerformance | null; b: PlayerGamePerformance | null }>(blankGamePerformance());
   const stateRef = useRef(state);
   useEffect(() => { stateRef.current = state; }, [state]);
   // Track latest store for callbacks that need the freshest settings.
   const storeRef = useRef(store);
   useEffect(() => { storeRef.current = store; }, [store]);
+  const moveFeedbackTimeoutRef = useRef<number | null>(null);
+  const moveGradesRef = useRef<{ w: number[]; b: number[] }>({ w: [], b: [] });
+  const queuedMoveSoundRef = useRef<"blunder" | "grandmaster" | null>(null);
+  const ratedMoveCacheRef = useRef<Array<CachedRatedMoveEntry | null>>([]);
+
+  useEffect(() => () => {
+    if (moveFeedbackTimeoutRef.current !== null) window.clearTimeout(moveFeedbackTimeoutRef.current);
+  }, []);
 
   const activeProfile = useMemo(
     () => store.profiles.find((p) => p.id === store.settings.activeProfileId) ?? null,
     [store]
   );
 
+  const ratedMoves = useMemo<RatedMoveEntry[]>(() => {
+    const cache = ratedMoveCacheRef.current.slice(0, state.history.length);
+    for (let index = 0; index < state.history.length; index++) {
+      if (cache[index]) continue;
+      const before = stack[index];
+      const after = stack[index + 1];
+      const move = after?.history[index];
+      if (!move || move.from.file < 0) {
+        cache[index] = null;
+        continue;
+      }
+      const feedback = evaluateMoveFeedback(before, move);
+      cache[index] = {
+        ...feedback,
+        color: move.color,
+        moveNumber: index + 1,
+        san: move.san ?? ""
+      };
+    }
+    ratedMoveCacheRef.current = cache;
+    return cache.flatMap((entry) => {
+      if (!entry) return [];
+      return [{
+        ...entry,
+        playerName: entry.color === "w" ? players.w : players.b
+      }];
+    });
+  }, [stack, state.history.length, players]);
+
   const result = useMemo(() => gameResult(state), [state]);
 
   // Clear hint whenever the position changes.
@@ -182,9 +252,14 @@ export function GameProvider({ children }: { children: ReactNode }) {
         // win/loss from the active profile's perspective (white) when vs bot
         const playerIsWhite = botLevelOf(mode) !== null;
         const winnerIsPlayer = playerIsWhite && result.winner === "w";
+        queuedMoveSoundRef.current = null;
         playSound(winnerIsPlayer ? "win" : (botLevelOf(mode) !== null ? "loss" : "win"));
       } else if (result.kind !== "ongoing") {
+        queuedMoveSoundRef.current = null;
         playSound("draw");
+      } else if (queuedMoveSoundRef.current && lastMove) {
+        playSound(queuedMoveSoundRef.current);
+        queuedMoveSoundRef.current = null;
       } else if (isCheck) {
         playSound("check");
       } else if (lastMove?.isPortalEntry) {
@@ -304,6 +379,8 @@ export function GameProvider({ children }: { children: ReactNode }) {
         }
         if (cancelled) return;
         if (move) {
+          const feedback = evaluateMoveFeedback(state, move);
+          queuedMoveSoundRef.current = feedback.grade === 0 ? "blunder" : null;
           const san = toSAN(state, move);
           dispatch({ type: "make", move, san });
         }
@@ -325,23 +402,52 @@ export function GameProvider({ children }: { children: ReactNode }) {
     const winner = result.kind === "checkmate" ? result.winner : null;
     const updated = cloneStore(store);
     const lvl = botLevelOf(mode);
+    const summaries = {
+      w: isHumanControlledColor(mode, "w") ? summarizeMoveGrades(moveGradesRef.current.w) : null,
+      b: isHumanControlledColor(mode, "b") ? summarizeMoveGrades(moveGradesRef.current.b) : null
+    };
+    const nextPerformance = blankGamePerformance();
     if (lvl !== null) {
-      if (!activeProfile) return;
       const outcome: "win" | "loss" | "draw" =
         winner === null ? "draw" : winner === "w" ? "win" : "loss";
-      recordResult(updated, activeProfile.id, { kind: "bot", level: lvl }, outcome);
-      saveActiveGame(updated, activeProfile.id, null);
+      if (activeProfile && summaries.w) {
+        recordResult(updated, activeProfile.id, { kind: "bot", level: lvl }, outcome, {
+          stars: summaries.w.stars,
+          score: summaries.w.score,
+          moveGrades: moveGradesRef.current.w
+        });
+        saveActiveGame(updated, activeProfile.id, null);
+        const refreshed = updated.profiles.find((p) => p.id === activeProfile.id) ?? null;
+        nextPerformance.w = toPlayerGamePerformance("w", players.w, summaries.w, refreshed?.stats.totalStars ?? null, "bot");
+      } else if (summaries.w) {
+        nextPerformance.w = toPlayerGamePerformance("w", players.w, summaries.w, null, "bot");
+      }
     } else {
       // two-player: record vs each named profile if found
       const wProf = updated.profiles.find((p) => p.name === players.w);
       const bProf = updated.profiles.find((p) => p.name === players.b);
       const wOutcome: "win" | "loss" | "draw" = winner === null ? "draw" : winner === "w" ? "win" : "loss";
       const bOutcome: "win" | "loss" | "draw" = winner === null ? "draw" : winner === "b" ? "win" : "loss";
-      if (wProf) recordResult(updated, wProf.id, { kind: "human" }, wOutcome);
-      if (bProf) recordResult(updated, bProf.id, { kind: "human" }, bOutcome);
+      if (wProf && summaries.w) {
+        recordResult(updated, wProf.id, { kind: "human" }, wOutcome, {
+          stars: summaries.w.stars,
+          score: summaries.w.score,
+          moveGrades: moveGradesRef.current.w
+        });
+      }
+      if (bProf && summaries.b) {
+        recordResult(updated, bProf.id, { kind: "human" }, bOutcome, {
+          stars: summaries.b.stars,
+          score: summaries.b.score,
+          moveGrades: moveGradesRef.current.b
+        });
+      }
+      if (summaries.w) nextPerformance.w = toPlayerGamePerformance("w", players.w, summaries.w, wProf?.stats.totalStars ?? null, "human");
+      if (summaries.b) nextPerformance.b = toPlayerGamePerformance("b", players.b, summaries.b, bProf?.stats.totalStars ?? null, "human");
       if (activeProfile) saveActiveGame(updated, activeProfile.id, null);
     }
     setStore(updated);
+    setGamePerformance(nextPerformance);
   }, [result, mode, activeProfile, store, stack.length, players]);
 
   // Persist active game
@@ -375,6 +481,7 @@ export function GameProvider({ children }: { children: ReactNode }) {
 
   const tryMove = useCallback((from: Square, to: Square, promotion?: "Q" | "R" | "B" | "N", portalTo?: Square): boolean => {
     if (paused) return false;
+    const mover = state.turn;
     const candidates = legalMovesFrom(state, from).filter(
       (m) => m.to.file === to.file && m.to.rank === to.rank
     );
@@ -388,23 +495,47 @@ export function GameProvider({ children }: { children: ReactNode }) {
     } else if (candidates.some((m) => m.promotion)) {
       move = candidates.find((m) => m.promotion === (promotion ?? "Q")) ?? candidates[0];
     }
+    const feedback = isHumanControlledColor(mode, mover) ? evaluateMoveFeedback(state, move) : null;
     const san = toSAN(state, move);
     dispatch({ type: "make", move, san });
     setSelected(null);
+    if (feedback) {
+      queuedMoveSoundRef.current = feedback.sound;
+      moveGradesRef.current[mover] = [...moveGradesRef.current[mover], feedback.grade];
+      setGamePerformance(blankGamePerformance());
+      setMoveFeedback({
+        ...feedback,
+        color: mover,
+        moveNumber: state.history.length + 1,
+        playerName: mover === "w" ? players.w : players.b
+      });
+      if (moveFeedbackTimeoutRef.current !== null) window.clearTimeout(moveFeedbackTimeoutRef.current);
+      moveFeedbackTimeoutRef.current = window.setTimeout(() => setMoveFeedback(null), 2100);
+    }
     return true;
-  }, [state, paused]);
+  }, [state, paused, mode, players]);
 
   const replayLastMove = useCallback(() => {
     if (state.history.length === 0) return;
     setLastMoveReplayNonce((n) => n + 1);
   }, [state.history.length]);
 
   const undo = useCallback(() => {
+    const undoCount = botLevelOf(mode) !== null ? 2 : 1;
+    const undoneMoves = state.history.slice(-undoCount);
+    for (const move of undoneMoves) {
+      if (move && move.from.file >= 0 && isHumanControlledColor(mode, move.color)) {
+        moveGradesRef.current[move.color] = moveGradesRef.current[move.color].slice(0, -1);
+      }
+    }
     // Undo twice if playing a bot and it's the human's turn (to remove bot reply + own move).
     dispatch({ type: "undo" });
     if (botLevelOf(mode) !== null) dispatch({ type: "undo" });
     setSelected(null);
-  }, [mode]);
+    queuedMoveSoundRef.current = null;
+    setMoveFeedback(null);
+    setGamePerformance(blankGamePerformance());
+  }, [mode, state.history]);
 
   const newGame = useCallback((m: Mode, p?: Partial<Players>, opts?: NewGameOptions) => {
     if (
@@ -437,6 +568,11 @@ export function GameProvider({ children }: { children: ReactNode }) {
     setSelected(null);
     setPaused(false);
     setLastMoveReplayNonce(0);
+    moveGradesRef.current = { w: [], b: [] };
+    queuedMoveSoundRef.current = null;
+    if (moveFeedbackTimeoutRef.current !== null) window.clearTimeout(moveFeedbackTimeoutRef.current);
+    setMoveFeedback(null);
+    setGamePerformance(blankGamePerformance());
     // Force the clock to use the freshest timer setting — the caller often
     // updates settings immediately before calling newGame (e.g. the New Game
     // screen), so reading storeRef gives us the value they just picked
@@ -457,6 +593,11 @@ export function GameProvider({ children }: { children: ReactNode }) {
     setHint(null);
     setPaused(false);
     setLastMoveReplayNonce(0);
+    moveGradesRef.current = { w: [], b: [] };
+    queuedMoveSoundRef.current = null;
+    if (moveFeedbackTimeoutRef.current !== null) window.clearTimeout(moveFeedbackTimeoutRef.current);
+    setMoveFeedback(null);
+    setGamePerformance(blankGamePerformance());
     if (opts?.noTimer) setTimeLeft(Infinity);
   }, []);
 
@@ -471,6 +612,7 @@ export function GameProvider({ children }: { children: ReactNode }) {
     })();
   }, [state, mode.kind]);
   const clearHint = useCallback(() => setHint(null), []);
+  const clearMoveFeedback = useCallback(() => setMoveFeedback(null), []);
 
   const setActiveProfile = useCallback((id: string | null) => {
     const updated = cloneStore(store);
@@ -530,6 +672,7 @@ export function GameProvider({ children }: { children: ReactNode }) {
     loadPosition,
     recordPuzzleSolved, recordPuzzleAttempt,
     hint, requestHint, clearHint,
+    moveFeedback, clearMoveFeedback, ratedMoves, gamePerformance,
     setActiveProfile, addProfile, removeProfile, renamePlayer, updateSetting
   };
 
@@ -548,13 +691,47 @@ function cloneStore(s: Store): Store {
         ...p.stats,
         byBotLevel: { ...p.stats.byBotLevel },
         badges: p.stats.badges.slice(),
-        puzzleProgress: { ...(p.stats.puzzleProgress ?? {}) }
+        puzzleProgress: { ...(p.stats.puzzleProgress ?? {}) },
+        performanceHistory: (p.stats.performanceHistory ?? []).map((record) => ({
+          ...record,
+          moveGrades: record.moveGrades?.slice()
+        }))
       }
     })),
     settings: { ...s.settings },
     savedGames: { ...s.savedGames }
   };
 }
 
+function isHumanControlledColor(mode: Mode, color: Color): boolean {
+  if (mode.kind === "bot") return color === "w";
+  if (mode.kind === "portal") {
+    if (typeof mode.opponent === "string") return true;
+    return color === "w";
+  }
+  return true;
+}
+
+function blankGamePerformance(): { w: PlayerGamePerformance | null; b: PlayerGamePerformance | null } {
+  return { w: null, b: null };
+}
+
+function toPlayerGamePerformance(
+  color: Color,
+  playerName: string,
+  summary: GamePerformanceSummary,
+  totalStars: number | null,
+  mode: "bot" | "human"
+): PlayerGamePerformance {
+  return {
+    ...summary,
+    color,
+    playerName,
+    addedStars: summary.stars,
+    totalStars,
+    mode
+  };
+}
+
 // Unused re-exports to keep bundler happy for tree-shaking consumers.
 export type { Profile, Settings, Store };

src/components/Board.tsx

@@ -41,7 +41,9 @@ export function Board({ flipped = false }: Props) {
     store,
     mode,
     hint,
-    lastMoveReplayNonce
+    lastMoveReplayNonce,
+    moveFeedback,
+    clearMoveFeedback
   } = useGame();
   const theme = store.settings.theme;
   const pieceSet = store.settings.pieceSet;
@@ -251,13 +253,29 @@ export function Board({ flipped = false }: Props) {
                       <span className="boom-bit b6">⭐</span>
                     </span>
                   )}
+                  {isLastTo && moveFeedback && (
+                    <span className={`move-rating-badge grade-${moveFeedback.grade}`} aria-hidden="true">
+                      {moveFeedback.emoji}
+                    </span>
+                  )}
                 </button>
               );
             })}
           </div>
         ))}
       </div>
 
+      {moveFeedback && store.settings.showMoveRatingPopup && (
+        <div className={`move-rating-toast grade-${moveFeedback.grade}`} role="status" aria-live="polite">
+          <button className="move-rating-dismiss" onClick={clearMoveFeedback} aria-label="Dismiss move rating">✕</button>
+          <div className="move-rating-emoji" aria-hidden="true">{moveFeedback.emoji}</div>
+          <div className="move-rating-copy">
+            <strong>{moveFeedback.playerName}: {moveFeedback.label}</strong>
+            <span>{moveFeedback.title} · {moveFeedback.score}/100</span>
+          </div>
+        </div>
+      )}
+
       {pending && (
         <div className="modal-overlay" onClick={() => setPending(null)}>
           <div className={`modal promo-picker piece-set-${pieceSet}`} onClick={(e) => e.stopPropagation()}>