feat: add text heuristic description of game board

Author: kevinjosethomas

Diff for: src/components/Analysis/Highlight.tsx

@@ -1,5 +1,7 @@
 import { Tooltip } from 'react-tooltip'
+import { useState, useEffect, useRef } from 'react'
 import { MovesByRating } from './MovesByRating'
+import { motion, AnimatePresence } from 'framer-motion'
 import { MaiaEvaluation, StockfishEvaluation, ColorSanMapping } from 'src/types'
 
 interface Props {
@@ -22,6 +24,7 @@ interface Props {
   hover: (move?: string) => void
   makeMove: (move: string) => void
   movesByRating: { [key: string]: number }[] | undefined
+  boardDescription: string
 }
 
 export const Highlight: React.FC<Props> = ({
@@ -32,6 +35,7 @@ export const Highlight: React.FC<Props> = ({
   colorSanMapping,
   recommendations,
   currentMaiaModel,
+  boardDescription,
 }: Props) => {
   const findMatchingMove = (move: string, source: 'maia' | 'stockfish') => {
     if (source === 'maia') {
@@ -97,9 +101,22 @@ export const Highlight: React.FC<Props> = ({
     )
   }
 
+  // Track whether description exists (not its content)
+  const hasDescriptionRef = useRef(!!boardDescription)
+  const [animationKey, setAnimationKey] = useState(0)
+
+  useEffect(() => {
+    const descriptionNowExists = !!boardDescription
+    // Only trigger animation when presence changes (exists vs doesn't exist)
+    if (hasDescriptionRef.current !== descriptionNowExists) {
+      hasDescriptionRef.current = descriptionNowExists
+      setAnimationKey((prev) => prev + 1)
+    }
+  }, [boardDescription])
+
   return (
     <div className="flex h-full w-full flex-col items-start gap-1 overflow-hidden md:flex-row md:gap-0 md:rounded md:border-[0.5px] md:border-white/40">
-      <div className="flex h-full w-full flex-col border-white/40 bg-background-1 md:w-auto md:min-w-[40%] md:border-r-[0.5px]">
+      <div className="flex h-full w-full flex-col border-white/40 bg-background-1 md:w-auto md:min-w-[40%] md:max-w-[40%] md:border-r-[0.5px]">
         <div className="grid grid-cols-2">
           <div className="flex flex-col items-center justify-center gap-1 bg-human-3/5 py-2 md:py-3">
             <p className="text-center text-xs text-human-2 md:text-sm">
@@ -203,6 +220,24 @@ export const Highlight: React.FC<Props> = ({
               })}
           </div>
         </div>
+        <div className="flex flex-col items-start justify-start gap-1 bg-background-1/80 px-3 py-1.5 text-sm">
+          <AnimatePresence mode="wait">
+            {boardDescription ? (
+              <motion.div
+                key={animationKey}
+                initial={{ opacity: 0, y: 10 }}
+                animate={{ opacity: 1, y: 0 }}
+                exit={{ opacity: 0, y: -10 }}
+                transition={{ duration: 0.1 }}
+                className="w-full"
+              >
+                <p className="w-full whitespace-normal break-words text-xs text-secondary">
+                  {boardDescription}
+                </p>
+              </motion.div>
+            ) : null}
+          </AnimatePresence>
+        </div>
       </div>
       <div className="flex h-full w-full flex-col bg-background-1">
         <MovesByRating

Diff for: src/hooks/useAnalysisController/useAnalysisController.ts

@@ -524,6 +524,194 @@ export const useAnalysisController = (game: AnalyzedGame) => {
     return data
   }, [moveEvaluation])
 
+  const boardDescription = useMemo(() => {
+    if (
+      !controller.currentNode ||
+      !moveEvaluation?.stockfish ||
+      !moveEvaluation?.maia ||
+      moveEvaluation.stockfish.depth < 12
+    ) {
+      return ''
+    }
+
+    const isBlackTurn = controller.currentNode.turn === 'b'
+    const playerColor = isBlackTurn ? 'Black' : 'White'
+    const opponent = isBlackTurn ? 'White' : 'Black'
+    const stockfish = moveEvaluation.stockfish
+    const maia = moveEvaluation.maia
+    const topMaiaMove = Object.entries(maia.policy).sort(
+      (a, b) => b[1] - a[1],
+    )[0]
+    const topStockfishMoves = Object.entries(stockfish.cp_vec)
+      .sort((a, b) => (isBlackTurn ? a[1] - b[1] : b[1] - a[1]))
+      .slice(0, 3)
+
+    const cp = stockfish.model_optimal_cp
+    const absCP = Math.abs(cp)
+    const cpAdvantage = cp > 0 ? 'White' : cp < 0 ? 'Black' : 'Neither player'
+    const topStockfishMove = topStockfishMoves[0]
+
+    // Check if top Maia move matches top Stockfish move
+    const maiaMatchesStockfish = topMaiaMove[0] === topStockfishMove[0]
+
+    // Get top few Maia moves and their cumulative probability
+    const top3MaiaMoves = Object.entries(maia.policy)
+      .sort((a, b) => b[1] - a[1])
+      .slice(0, 3)
+    const top3MaiaProbability =
+      top3MaiaMoves.reduce((sum, [_, prob]) => sum + prob, 0) * 100
+
+    // Get second best moves to analyze move clarity
+    const secondBestMaiaMove = top3MaiaMoves[1]
+    const secondBestMaiaProbability = secondBestMaiaMove
+      ? secondBestMaiaMove[1] * 100
+      : 0
+
+    // Calculate spread between first and second-best moves
+    const probabilitySpread = topMaiaMove[1] * 100 - secondBestMaiaProbability
+
+    // Get move classifications
+    const blunderProbability = blunderMeter.blunderMoves.probability
+    const okProbability = blunderMeter.okMoves.probability
+    const goodProbability = blunderMeter.goodMoves.probability
+
+    // Check for patterns in stockfish evaluation
+    const stockfishTop3Spread =
+      topStockfishMoves.length > 2
+        ? Math.abs(topStockfishMoves[0][1] - topStockfishMoves[2][1])
+        : 0
+
+    // Get move spreads to detect sharp positions
+    const moveCpSpread = Object.values(stockfish.cp_relative_vec).reduce(
+      (maxDiff, cp, _, arr) => {
+        const min = Math.min(...arr)
+        const max = Math.max(...arr)
+        return Math.max(maxDiff, max - min)
+      },
+      0,
+    )
+
+    // Calculate position complexity based on distribution of move quality
+    const isPositionComplicated =
+      (blunderProbability > 30 && okProbability > 20 && goodProbability < 50) ||
+      moveCpSpread > 300 ||
+      stockfishTop3Spread > 100
+
+    // Check for tactical position
+    const isTacticalPosition = moveCpSpread > 500 || stockfishTop3Spread > 150
+
+    // Check if there's a clear best move
+    const topMaiaProbability = topMaiaMove[1] * 100
+    const isClearBestMove = topMaiaProbability > 70 || probabilitySpread > 40
+
+    // Check if there are multiple equally good moves
+    const hasMultipleGoodMoves =
+      top3MaiaProbability > 75 && topMaiaProbability < 50
+
+    // Calculate agreement between Maia rating levels
+    const maiaModelsAgree = Object.entries(
+      controller.currentNode.analysis.maia || {},
+    )
+      .filter(([key]) => MAIA_MODELS.includes(key))
+      .every(([_, evaluation]) => {
+        const topMove = Object.entries(evaluation.policy).sort(
+          (a, b) => b[1] - a[1],
+        )[0]
+        return topMove && topMove[0] === topMaiaMove[0]
+      })
+
+    // Check if evaluation is decisive
+    const isDecisiveAdvantage = absCP > 300
+    const isOverwhelming = absCP > 800
+
+    // Check for high blunder probability
+    const isBlunderProne = blunderProbability > 50
+    const isVeryBlunderProne = blunderProbability > 70
+
+    // Check if there's forced play
+    const isForcedPlay = topMaiaProbability > 85 && maiaMatchesStockfish
+
+    // Check if position is balanced but with complexity
+    const isBalancedButComplex = absCP < 50 && isPositionComplicated
+
+    // Generate descriptions
+    let evaluation = ''
+    let suggestion = ''
+
+    // Evaluation description
+    if (isOverwhelming) {
+      evaluation = `${cpAdvantage} is completely winning and should convert without difficulty.`
+    } else if (cp === 0) {
+      evaluation = isBalancedButComplex
+        ? 'The position is balanced but filled with complications.'
+        : 'The position is completely equal.'
+    } else if (absCP < 30) {
+      evaluation = `The evaluation is almost perfectly balanced with only the slightest edge for ${cpAdvantage}.`
+    } else if (absCP < 80) {
+      evaluation = `${cpAdvantage} has a slight but tangible advantage in this position.`
+    } else if (absCP < 150) {
+      evaluation = `${cpAdvantage} has a clear positional advantage that could be decisive with careful play.`
+    } else if (absCP < 300) {
+      evaluation = `${cpAdvantage} has a significant advantage that should be convertible with proper technique.`
+    } else if (absCP < 500) {
+      evaluation = `${cpAdvantage} has a winning position that only requires avoiding major blunders.`
+    } else {
+      evaluation = `${cpAdvantage} has a completely winning position that should be straightforward to convert.`
+    }
+
+    // Suggestion/description of move quality
+    if (isVeryBlunderProne) {
+      suggestion = `This critical position is extremely treacherous with a ${blunderProbability.toFixed(0)}% chance of ${playerColor} making a significant error.`
+    } else if (isBlunderProne && isTacticalPosition) {
+      suggestion = `The sharp tactical nature of this position creates many opportunities for mistakes (${blunderProbability.toFixed(0)}% blunder chance).`
+    } else if (isBlunderProne) {
+      suggestion = `This position is quite treacherous with ${blunderProbability.toFixed(0)}% chance of ${playerColor} making a significant mistake.`
+    } else if (isForcedPlay) {
+      const moveSan = colorSanMapping[topMaiaMove[0]]?.san || topMaiaMove[0]
+      suggestion = `${playerColor} must play ${moveSan}, as all other moves lead to a significantly worse position.`
+    } else if (isTacticalPosition && maiaMatchesStockfish) {
+      const moveSan = colorSanMapping[topMaiaMove[0]]?.san || topMaiaMove[0]
+      suggestion = `The tactical complexity demands precision, with ${moveSan} being the only move that maintains the balance.`
+    } else if (isPositionComplicated && hasMultipleGoodMoves) {
+      suggestion = `This complex position offers several equally promising continuations for ${playerColor}.`
+    } else if (isPositionComplicated) {
+      suggestion = `This is a complex position requiring careful calculation of the many reasonable options.`
+    } else if (isClearBestMove && maiaMatchesStockfish && maiaModelsAgree) {
+      const moveSan = colorSanMapping[topMaiaMove[0]]?.san || topMaiaMove[0]
+      suggestion = `Players of all levels agree ${moveSan} stands out as clearly best in this position.`
+    } else if (isClearBestMove && maiaMatchesStockfish) {
+      const moveSan = colorSanMapping[topMaiaMove[0]]?.san || topMaiaMove[0]
+      suggestion = `${playerColor} should play ${moveSan}, which both human intuition and concrete calculation confirm as best.`
+    } else if (isClearBestMove && maiaModelsAgree) {
+      const moveSan = colorSanMapping[topMaiaMove[0]]?.san || topMaiaMove[0]
+      suggestion = `Human players at all levels strongly prefer ${moveSan} (${topMaiaProbability.toFixed(0)}%), though the engine suggests otherwise.`
+    } else if (isClearBestMove) {
+      const moveSan = colorSanMapping[topMaiaMove[0]]?.san || topMaiaMove[0]
+      suggestion = `Maia strongly suggests ${moveSan} (${topMaiaProbability.toFixed(0)}% likely), though Stockfish calculates a different approach.`
+    } else if (goodProbability > 80) {
+      suggestion = `This is a forgiving position where almost any reasonable move by ${playerColor} maintains the evaluation.`
+    } else if (goodProbability > 60) {
+      suggestion = `Most moves ${playerColor} is likely to consider will maintain the current position assessment.`
+    } else if (maiaMatchesStockfish) {
+      const moveSan = colorSanMapping[topMaiaMove[0]]?.san || topMaiaMove[0]
+      suggestion = `Both human intuition and engine calculation agree that ${moveSan} is the best continuation here.`
+    } else if (hasMultipleGoodMoves) {
+      suggestion = `${playerColor} has several equally strong options, suggesting flexibility in planning.`
+    } else if (top3MaiaProbability < 50) {
+      suggestion = `This unusual position creates difficulties for human calculation, with no clearly favored continuation.`
+    } else {
+      suggestion = `There are several reasonable options for ${playerColor} to consider in this position.`
+    }
+
+    return `${evaluation} ${suggestion}`
+  }, [
+    controller.currentNode,
+    moveEvaluation,
+    blunderMeter,
+    colorSanMapping,
+    MAIA_MODELS,
+  ])
+
   const move = useMemo(() => {
     if (!currentMove) return undefined
 
@@ -559,5 +747,6 @@ export const useAnalysisController = (game: AnalyzedGame) => {
     moveRecommendations,
     moveMap,
     blunderMeter,
+    boardDescription,
   }
 }

Diff for: src/pages/analysis/[...id].tsx

@@ -282,6 +282,7 @@ const Analysis: React.FC<Props> = ({
     moveRecommendations,
     moveMap,
     blunderMeter,
+    boardDescription,
   } = useAnalysisController(analyzedGame)
 
   useEffect(() => {
@@ -600,6 +601,7 @@ const Analysis: React.FC<Props> = ({
               }
               movesByRating={movesByRating}
               colorSanMapping={colorSanMapping}
+              boardDescription={boardDescription}
             />
           </div>
           <div className="flex h-[calc((55vh+4.5rem)/2)] flex-row gap-2">
@@ -728,6 +730,7 @@ const Analysis: React.FC<Props> = ({
                 }
                 movesByRating={movesByRating}
                 colorSanMapping={colorSanMapping}
+                boardDescription={boardDescription}
               />
               <MoveMap
                 moveMap={moveMap}