Add configurable animation speed setting

Author: Swon404

README.md

@@ -4,7 +4,8 @@ Kid-friendly chess PWA built with React 19 + TypeScript + Vite + vite-plugin-pwa
 
 ## Features (v0.1)
 - Two-player pass-and-play with auto-flip
-- Play the bot with 10 difficulty levels (built-in minimax for 1–5, Stockfish WASM hook for 6–10)
+- Play the bot with 20 difficulty levels in standard chess (built-in minimax for 1-4, external Stockfish API for 5-20 with fallback)
+- Portal Chess bot remains local and supports levels 1-10
 - Per-move timer with configurable seconds (10/30/60/120/off). Timeout forfeits **that move only** — game continues.
 - Tap a piece to see where it can go — legal squares highlighted, captures ringed in red
 - Full undo / takeback stack
@@ -28,7 +29,6 @@ npm test
 Pushed to `main` → GitHub Pages via `.github/workflows/deploy.yml`. Update `base` in `vite.config.ts` if the repo name changes.
 
 ## Roadmap
-- Wire Stockfish WASM into `src/engine/bot/stockfish.ts` for bot levels 6–10
 - Mate-in-1/2 puzzles + daily puzzle
 - Mascot coach with contextual commentary
 - Board themes & kid-friendly piece sets

src/GameContext.tsx

@@ -24,6 +24,10 @@ type Mode =
   | { kind: "portal"; opponent: "two-player" | { kind: "bot"; level: number }; creator: PieceType; adjacencyRule?: boolean; portalMax?: number };
 export interface Players { w: string; b: string; }
 
+interface NewGameOptions {
+  timerSeconds?: number;
+}
+
 /** Build the initial state for Portal Chess (creator-type portals). */
 function portalInitialState(creator: PieceType, adjacencyRule = false, portalMax = 1): GameState {
   const s = initialState();
@@ -50,8 +54,10 @@ interface GameCtx {
 
   select(sq: Square | null): void;
   tryMove(from: Square, to: Square, promotion?: "Q" | "R" | "B" | "N", portalTo?: Square): boolean;
+  lastMoveReplayNonce: number;
+  replayLastMove(): void;
   undo(): void;
-  newGame(mode: Mode, players?: Partial<Players>): void;
+  newGame(mode: Mode, players?: Partial<Players>, opts?: NewGameOptions): void;
   forfeit(): void;
 
   // puzzles
@@ -139,6 +145,7 @@ export function GameProvider({ children }: { children: ReactNode }) {
   const [isBotThinking, setIsBotThinking] = useState(false);
   const [hint, setHint] = useState<Move | null>(null);
   const [paused, setPaused] = useState(false);
+  const [lastMoveReplayNonce, setLastMoveReplayNonce] = useState(0);
   const stateRef = useRef(state);
   useEffect(() => { stateRef.current = state; }, [state]);
   // Track latest store for callbacks that need the freshest settings.
@@ -245,12 +252,19 @@ export function GameProvider({ children }: { children: ReactNode }) {
       try {
         // Compute the bot move and ensure enough time has elapsed so the
         // human's own animation has time to play before the board re-renders
-        // with the bot's response. Teleport animation is 2.0s total
-        // (demat + gap + remat). Slide animation is ~650ms.
+        // with the bot's response. Delay scales with animation-speed setting
+        // so replay/slow modes remain visually readable.
         const prevMove = state.history[state.history.length - 1];
-        const minThinkMs = prevMove?.isPortalEntry ? 2100 : 750;
+        const speed = store.settings.animationSpeed;
+        const thinkDelays =
+          speed === "very-slow"
+            ? { slide: 1650, teleport: 3800 }
+            : speed === "slow"
+              ? { slide: 1200, teleport: 2900 }
+              : { slide: 900, teleport: 2200 };
+        const minThinkMs = prevMove?.isPortalEntry ? thinkDelays.teleport : thinkDelays.slide;
         const t0 = performance.now();
-        const move = await chooseBotMove(state, lvl);
+        const move = await chooseBotMove(state, lvl, { allowExternal: mode.kind === "bot" });
         const elapsed = performance.now() - t0;
         if (elapsed < minThinkMs) {
           await new Promise((r) => setTimeout(r, minThinkMs - elapsed));
@@ -267,7 +281,7 @@ export function GameProvider({ children }: { children: ReactNode }) {
       }
     })();
     return () => { cancelled = true; };
-  }, [state, mode, result.kind, paused]);
+  }, [state, mode, result.kind, paused, store.settings.animationSpeed]);
 
   // Auto-record result when game ends
   const recordedRef = useRef<number>(-1);
@@ -347,16 +361,27 @@ export function GameProvider({ children }: { children: ReactNode }) {
     return true;
   }, [state, paused]);
 
+  const replayLastMove = useCallback(() => {
+    if (state.history.length === 0) return;
+    setLastMoveReplayNonce((n) => n + 1);
+  }, [state.history.length]);
+
   const undo = useCallback(() => {
     // 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]);
 
-  const newGame = useCallback((m: Mode, p?: Partial<Players>) => {
+  const newGame = useCallback((m: Mode, p?: Partial<Players>, opts?: NewGameOptions) => {
     clearActiveSession();
     noTimerRef.current = false;
+    if (opts?.timerSeconds !== undefined && opts.timerSeconds !== storeRef.current.settings.timerSeconds) {
+      const updated = cloneStore(storeRef.current);
+      updateSettings(updated, { timerSeconds: opts.timerSeconds });
+      setStore(updated);
+      storeRef.current = updated;
+    }
     setMode(m);
     const defaultW = activeProfile?.name ?? "White";
     const defaultB =
@@ -370,11 +395,12 @@ export function GameProvider({ children }: { children: ReactNode }) {
     dispatch({ type: "new", initial: fresh });
     setSelected(null);
     setPaused(false);
+    setLastMoveReplayNonce(0);
     // 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
     // instead of the stale closure-captured one.
-    const t = storeRef.current.settings.timerSeconds;
+    const t = opts?.timerSeconds ?? storeRef.current.settings.timerSeconds;
     setTimeLeft(t > 0 ? t : Infinity);
   }, [activeProfile]);
 
@@ -389,6 +415,7 @@ export function GameProvider({ children }: { children: ReactNode }) {
     setSelected(null);
     setHint(null);
     setPaused(false);
+    setLastMoveReplayNonce(0);
     if (opts?.noTimer) setTimeLeft(Infinity);
   }, []);
 
@@ -398,10 +425,10 @@ export function GameProvider({ children }: { children: ReactNode }) {
 
   const requestHint = useCallback(() => {
     (async () => {
-      const best = await chooseBotMove(state, 5);
+      const best = await chooseBotMove(state, 5, { allowExternal: mode.kind === "bot" });
       if (best) setHint(best);
     })();
-  }, [state]);
+  }, [state, mode.kind]);
   const clearHint = useCallback(() => setHint(null), []);
 
   const setActiveProfile = useCallback((id: string | null) => {
@@ -458,7 +485,7 @@ export function GameProvider({ children }: { children: ReactNode }) {
   const value: GameCtx = {
     store, activeProfile, state, mode, players, selected, legalFromSelected, timeLeft, isBotThinking, result,
     paused, togglePause,
-    select, tryMove, undo, newGame, forfeit,
+    select, tryMove, lastMoveReplayNonce, replayLastMove, undo, newGame, forfeit,
     loadPosition,
     recordPuzzleSolved, recordPuzzleAttempt,
     hint, requestHint, clearHint,

src/components/Board.tsx

@@ -19,9 +19,21 @@ interface PendingPromo {
 }
 
 export function Board({ flipped = false }: Props) {
-  const { state, selected, legalFromSelected, select, tryMove, result, store, hint } = useGame();
+  const {
+    state,
+    selected,
+    legalFromSelected,
+    select,
+    tryMove,
+    result,
+    store,
+    mode,
+    hint,
+    lastMoveReplayNonce
+  } = useGame();
   const theme = store.settings.theme;
   const pieceSet = store.settings.pieceSet;
+  const animationSpeed = store.settings.animationSpeed;
   const [pending, setPending] = useState<PendingPromo | null>(null);
 
   const ranks = flipped ? [0, 1, 2, 3, 4, 5, 6, 7] : [7, 6, 5, 4, 3, 2, 1, 0];
@@ -56,10 +68,11 @@ export function Board({ flipped = false }: Props) {
   const wPortals = state.portals?.w ?? [];
   const bPortals = state.portals?.b ?? [];
   const isTeleportMove = !!lastMove?.isPortalEntry;
+  const rotateBlackForFixedBoard = mode.kind === "two-player" && !store.settings.autoFlip;
 
   return (
     <>
-      <div className={`board board-theme-${theme} piece-set-${pieceSet}`}>
+      <div className={`board board-theme-${theme} piece-set-${pieceSet} anim-speed-${animationSpeed}`}>
         {ranks.map((r) => (
           <div key={r} className="board-row">
             {files.map((f) => {
@@ -109,7 +122,7 @@ export function Board({ flipped = false }: Props) {
                   ["--slide-dx" as string]: `${sign * df * 100}%`,
                   ["--slide-dy" as string]: `${sign * dr * 100}%`
                 };
-                slideKey = `slide-${moveIndex}`;
+                slideKey = `slide-${moveIndex}-${lastMoveReplayNonce}`;
               }
               const isRematerializeHere =
                 isTeleportMove &&
@@ -138,7 +151,7 @@ export function Board({ flipped = false }: Props) {
                   )}
                   {piece && (
                     <span
-                      key={isRematerializeHere ? `remat-${moveIndex}` : slideKey}
+                      key={isRematerializeHere ? `remat-${moveIndex}-${lastMoveReplayNonce}` : slideKey}
                       className={
                         isRematerializeHere
                           ? "piece-wrap piece-rematerialize"
@@ -148,20 +161,30 @@ export function Board({ flipped = false }: Props) {
                       }
                       style={slideStyle}
                     >
-                      <Piece color={piece.color} type={piece.type} set={pieceSet} />
+                      <Piece
+                        color={piece.color}
+                        type={piece.type}
+                        set={pieceSet}
+                        rotate={rotateBlackForFixedBoard && piece.color === "b"}
+                      />
                     </span>
                   )}
                   {isDematerializeHere && lastMove && (
                     <span
-                      key={`demat-${moveIndex}`}
+                      key={`demat-${moveIndex}-${lastMoveReplayNonce}`}
                       className="piece-wrap piece-dematerialize"
                       aria-hidden="true"
                     >
-                      <Piece color={lastMove.color} type={lastMove.piece} set={pieceSet} />
+                      <Piece
+                        color={lastMove.color}
+                        type={lastMove.piece}
+                        set={pieceSet}
+                        rotate={rotateBlackForFixedBoard && lastMove.color === "b"}
+                      />
                     </span>
                   )}
                   {isLastTo && lastMove?.captured && store.settings.explodeOnCapture && (
-                    <span key={`boom-${moveIndex}`} className="boom" aria-hidden="true">
+                    <span key={`boom-${moveIndex}-${lastMoveReplayNonce}`} className="boom" aria-hidden="true">
                       <span className="boom-core">💥</span>
                       <span className="boom-bit b1">✨</span>
                       <span className="boom-bit b2">⭐</span>

src/components/Controls.tsx

@@ -1,7 +1,19 @@
 import { useGame } from "../GameContext";
 
 export function Controls() {
-  const { undo, newGame, mode, result, state, requestHint, hint, clearHint, paused, togglePause } = useGame();
+  const {
+    undo,
+    newGame,
+    mode,
+    result,
+    state,
+    requestHint,
+    hint,
+    clearHint,
+    paused,
+    togglePause,
+    replayLastMove
+  } = useGame();
   const statusText =
     result.kind === "ongoing"
       ? paused
@@ -37,6 +49,13 @@ export function Controls() {
         >
           {hint ? "Hide hint" : "💡 Hint"}
         </button>
+        <button
+          onClick={replayLastMove}
+          disabled={state.history.length === 0}
+          title="Replay the latest move animation"
+        >
+          ↺ Replay
+        </button>
         <button onClick={() => undo()} disabled={state.history.length === 0}>Undo</button>
         <button onClick={() => newGame(mode)}>New Game</button>
       </div>

src/components/Piece.tsx

@@ -12,26 +12,28 @@ interface Props {
   color: Color;
   type: PieceType;
   set: PieceSet;
+  rotate?: boolean;
 }
 
-export function Piece({ color, type, set }: Props) {
+export function Piece({ color, type, set, rotate = false }: Props) {
+  const faceClass = rotate ? "piece-face-180" : "";
   if (set === "classic") {
     return (
-      <span className={`piece-glyph piece-${color}`}>
+      <span className={`piece-glyph piece-${color} ${faceClass}`}>
         {GLYPH[color + type]}
       </span>
     );
   }
   if (set === "emoji") {
     return (
-      <span className={`piece-mc piece-${color}`}>
+      <span className={`piece-mc piece-${color} ${faceClass}`}>
         <MinecraftPiece color={color} type={type} />
       </span>
     );
   }
   // modern + neon both use SVG; neon gets a filter via CSS on the parent.
   return (
-    <span className={`piece-svg piece-${color}`}>
+    <span className={`piece-svg piece-${color} ${faceClass}`}>
       <PieceSVG color={color} type={type} />
     </span>
   );

src/engine/bot.ts

@@ -64,21 +64,27 @@ function minimax(state: GameState, depth: number, alpha: number, beta: number, m
   }
 }
 
+interface BotOptions {
+  allowExternal?: boolean;
+}
+
 /**
- * Choose a move for the bot at a given difficulty (1-10).
- * Levels 1-5 use the built-in minimax with increasing depth and decreasing randomness.
- * Levels 6-10 delegate to Stockfish WASM (lazy-loaded) — falls back to depth-4 minimax
- * if Stockfish isn't available (e.g. offline first-load).
+ * Choose a move for the bot at a given difficulty (1-20).
+ * Levels 1-4 use the built-in minimax with increasing depth and decreasing randomness.
+ * Levels 5-20 can delegate to an external Stockfish API when enabled; if unavailable,
+ * fall back to local minimax.
  */
-export async function chooseBotMove(state: GameState, level: number): Promise<Move | null> {
+export async function chooseBotMove(state: GameState, level: number, opts?: BotOptions): Promise<Move | null> {
   const moves = allLegalMoves(state);
   if (moves.length === 0) return null;
   const me = state.turn;
+  const normalizedLevel = Math.max(1, Math.min(20, Math.round(level)));
+  const canUseExternal = opts?.allowExternal !== false && !state.portals;
 
-  if (level >= 6) {
+  if (canUseExternal && normalizedLevel >= 5) {
     try {
       const { stockfishBestMove } = await import("./bot/stockfish");
-      const best = await stockfishBestMove(state, level);
+      const best = await stockfishBestMove(state, normalizedLevel);
       if (best) return best;
     } catch {
       // fall through to local minimax
@@ -90,15 +96,15 @@ export async function chooseBotMove(state: GameState, level: number): Promise<Mo
   // Level 1: ~80% random, prefer simple captures otherwise.
   // Level 2: ~50% random, depth-1 search the rest.
   // Level 3: depth-2, occasional blunder.
-  // Level 4: depth-3 clean.
-  // Level 5: depth-3 + capture ordering.
-  // Level 6-10 fallback: depth-4.
-  const blunderChance = { 1: 0.8, 2: 0.5, 3: 0.15, 4: 0.03, 5: 0 }[level as 1 | 2 | 3 | 4 | 5] ?? 0;
-  const depth = level <= 2 ? 1 : level <= 3 ? 2 : level <= 5 ? 3 : 4;
+  // Level 4: depth-2 clean.
+  // Level 5+: deterministic minimax fallback if external engine is unavailable.
+  const blunderChanceByLevel: Record<number, number> = { 1: 0.8, 2: 0.5, 3: 0.15, 4: 0.03 };
+  const blunderChance = blunderChanceByLevel[normalizedLevel] ?? 0;
+  const depth = normalizedLevel <= 2 ? 1 : normalizedLevel <= 4 ? 2 : normalizedLevel <= 8 ? 3 : 4;
 
   if (rng() < blunderChance) {
     const captures = moves.filter((m) => m.captured);
-    if (level === 1 || captures.length === 0) return randomChoice(moves, rng);
+    if (normalizedLevel === 1 || captures.length === 0) return randomChoice(moves, rng);
     return randomChoice(captures, rng);
   }