feat: make board description interactable

kevinjosethomas · kevinjosethomas · commit a920f6dd78bb · 2025-07-09T02:40:02.000-04:00
diff --git a/src/components/Analysis/Highlight.tsx b/src/components/Analysis/Highlight.tsx
@@ -1,8 +1,13 @@
 import { MoveTooltip } from './MoveTooltip'
+import { InteractiveDescription } from './InteractiveDescription'
 import { useState, useEffect, useRef } from 'react'
 import { motion, AnimatePresence } from 'framer-motion'
 import { MaiaEvaluation, StockfishEvaluation, ColorSanMapping } from 'src/types'
 
+type DescriptionSegment =
+  | { type: 'text'; content: string }
+  | { type: 'move'; san: string; uci: string }
+
 export const MAIA_MODELS = [
   'maia_kdd_1100',
   'maia_kdd_1200',
@@ -35,7 +40,7 @@ interface Props {
   }
   hover: (move?: string) => void
   makeMove: (move: string) => void
-  boardDescription: string
+  boardDescription: { segments: DescriptionSegment[] }
 }
 
 export const Highlight: React.FC<Props> = ({
@@ -113,17 +118,17 @@ export const Highlight: React.FC<Props> = ({
   }
 
   // Track whether description exists (not its content)
-  const hasDescriptionRef = useRef(!!boardDescription)
+  const hasDescriptionRef = useRef(boardDescription.segments.length > 0)
   const [animationKey, setAnimationKey] = useState(0)
 
   useEffect(() => {
-    const descriptionNowExists = !!boardDescription
+    const descriptionNowExists = boardDescription.segments.length > 0
     // Only trigger animation when presence changes (exists vs doesn't exist)
     if (hasDescriptionRef.current !== descriptionNowExists) {
       hasDescriptionRef.current = descriptionNowExists
       setAnimationKey((prev) => prev + 1)
     }
-  }, [boardDescription])
+  }, [boardDescription.segments.length])
 
   return (
     <div
@@ -267,7 +272,7 @@ export const Highlight: React.FC<Props> = ({
       </div>
       <div className="flex flex-col items-start justify-start bg-background-1/80 p-2 text-sm">
         <AnimatePresence mode="wait">
-          {boardDescription ? (
+          {boardDescription.segments.length > 0 ? (
             <motion.div
               key={animationKey}
               initial={{ opacity: 0, y: 10 }}
@@ -276,9 +281,13 @@ export const Highlight: React.FC<Props> = ({
               transition={{ duration: 0.075 }}
               className="w-full"
             >
-              <p className="w-full whitespace-normal break-words text-[10px] leading-tight text-secondary xl:text-xs xl:leading-tight">
-                {boardDescription}
-              </p>
+              <InteractiveDescription
+                description={boardDescription}
+                colorSanMapping={colorSanMapping}
+                moveEvaluation={moveEvaluation}
+                hover={hover}
+                makeMove={makeMove}
+              />
             </motion.div>
           ) : null}
         </AnimatePresence>
diff --git a/src/components/Analysis/InteractiveDescription.tsx b/src/components/Analysis/InteractiveDescription.tsx
@@ -0,0 +1,96 @@
+import React, { useState } from 'react'
+import { MoveTooltip } from './MoveTooltip'
+import { ColorSanMapping } from 'src/types'
+
+type DescriptionSegment =
+  | { type: 'text'; content: string }
+  | { type: 'move'; san: string; uci: string }
+
+interface Props {
+  description: { segments: DescriptionSegment[] }
+  colorSanMapping: ColorSanMapping
+  moveEvaluation?: {
+    maia?: { policy: { [key: string]: number } }
+    stockfish?: {
+      cp_vec: { [key: string]: number }
+      winrate_vec?: { [key: string]: number }
+      winrate_loss_vec?: { [key: string]: number }
+    }
+  } | null
+  hover: (move?: string) => void
+  makeMove: (move: string) => void
+}
+
+export const InteractiveDescription: React.FC<Props> = ({
+  description,
+  colorSanMapping,
+  moveEvaluation,
+  hover,
+  makeMove,
+}) => {
+  const [tooltipData, setTooltipData] = useState<{
+    move: string
+    position: { x: number; y: number }
+  } | null>(null)
+
+  const handleMouseEnter = (move: string, event: React.MouseEvent) => {
+    hover(move)
+    setTooltipData({
+      move,
+      position: { x: event.clientX, y: event.clientY },
+    })
+  }
+
+  const handleMouseLeave = () => {
+    hover()
+    setTooltipData(null)
+  }
+
+  const renderSegments = () => {
+    return description.segments.map((segment, index) => {
+      if (segment.type === 'text') {
+        return <span key={index}>{segment.content}</span>
+      } else {
+        return (
+          <button
+            key={index}
+            className="cursor-pointer text-primary hover:underline"
+            style={{
+              color: colorSanMapping[segment.uci]?.color ?? '#fff',
+            }}
+            onMouseEnter={(e) => handleMouseEnter(segment.uci, e)}
+            onMouseLeave={handleMouseLeave}
+            onClick={() => makeMove(segment.uci)}
+          >
+            {segment.san}
+          </button>
+        )
+      }
+    })
+  }
+
+  return (
+    <div className="w-full">
+      <p className="w-full whitespace-normal break-words text-[10px] leading-tight text-secondary xl:text-xs xl:leading-tight">
+        {renderSegments()}
+      </p>
+
+      {/* Tooltip */}
+      {tooltipData && moveEvaluation && (
+        <MoveTooltip
+          move={tooltipData.move}
+          colorSanMapping={colorSanMapping}
+          maiaProb={moveEvaluation.maia?.policy[tooltipData.move]}
+          stockfishCp={moveEvaluation.stockfish?.cp_vec[tooltipData.move]}
+          stockfishWinrate={
+            moveEvaluation.stockfish?.winrate_vec?.[tooltipData.move]
+          }
+          stockfishLoss={
+            moveEvaluation.stockfish?.winrate_loss_vec?.[tooltipData.move]
+          }
+          position={tooltipData.position}
+        />
+      )}
+    </div>
+  )
+}
diff --git a/src/components/Analysis/index.ts b/src/components/Analysis/index.ts
@@ -2,6 +2,7 @@ export * from './MoveMap'
 export * from './MovePlot'
 export * from './MoveTooltip'
 export * from './Highlight'
+export * from './InteractiveDescription'
 export * from './Tournament'
 export * from './BlunderMeter'
 export * from './MovesByRating'
diff --git a/src/hooks/useAnalysisController/useBoardDescription.ts b/src/hooks/useAnalysisController/useBoardDescription.ts
@@ -17,7 +17,7 @@ export const useBoardDescription = (
       !moveEvaluation?.maia ||
       moveEvaluation.stockfish.depth < 12
     ) {
-      return ''
+      return { segments: [] }
     }
 
     const fen = currentNode.fen
diff --git a/src/hooks/useAnalysisController/useDescriptionGenerator.ts b/src/hooks/useAnalysisController/useDescriptionGenerator.ts
@@ -4,6 +4,10 @@ import { Chess, PieceSymbol } from 'chess.ts'
 type StockfishEvals = Record<string, number>
 type MaiaEvals = Record<string, number[]>
 
+type DescriptionSegment =
+  | { type: 'text'; content: string }
+  | { type: 'move'; san: string; uci: string }
+
 /* ---------------- phrase banks ---------------- */
 
 const pick = <T>(a: T[]) => a[Math.floor(Math.random() * a.length)]
@@ -53,7 +57,7 @@ const TEMPT_WORD = ['tempting', 'enticing', 'natural-looking']
 
 /* ---------------- constants & helpers ---------------- */
 
-const EPS = 0.08 // “good move” window
+const EPS = 0.08 // "good move" window
 const BLUNDER_GAP = 0.1 // win-rate drop that defines a blunder
 
 const winRate = (p: number) => 1 / (1 + Math.exp(-(p - 1) / 0.8))
@@ -70,7 +74,7 @@ export function describePosition(
   sf: StockfishEvals,
   maia: MaiaEvals,
   whiteToMove: boolean,
-): string {
+): { segments: DescriptionSegment[] } {
   /* ---------- board ---------- */
   const chess = new Chess(fen)
   const legal = new Set<string>()
@@ -79,7 +83,10 @@ export function describePosition(
     .forEach((m) => legal.add(m.from + m.to + (m.promotion ?? '')))
 
   const moves = Object.keys(sf).filter((m) => legal.has(m))
-  if (!moves.length) return 'No legal moves available.'
+  if (!moves.length)
+    return {
+      segments: [{ type: 'text', content: 'No legal moves available.' }],
+    }
 
   if (!whiteToMove) {
     sf = Object.fromEntries(Object.entries(sf).map(([m, v]) => [m, -v]))
@@ -130,12 +137,13 @@ export function describePosition(
       Math.abs(wOpt - w2) <= EPS / 2 && Math.abs(dOpt - d2) <= EPS / 2
   }
 
-  const listWithOpt = sortedGood.slice(0, 3).map(uciToSan).join(', ')
-  const listWithoutOpt = sortedGood
+  const goodMovesList = sortedGood
+    .slice(0, 3)
+    .map((uci) => ({ san: uciToSan(uci), uci }))
+  const goodMovesWithoutOpt = sortedGood
     .filter((m) => m !== opt)
     .slice(0, 3)
-    .map(uciToSan)
-    .join(', ')
+    .map((uci) => ({ san: uciToSan(uci), uci }))
 
   /* ---------- outcome wording ---------- */
   const avgGood = sortedGood.reduce((s, m) => s + seval[m], 0) / nGood
@@ -242,15 +250,25 @@ export function describePosition(
   const prefix = setT === 2 && !bestHarder ? ', however' : ''
   const temptW = pick(TEMPT_WORD)
 
-  let tail = ''
+  let tailSegments: DescriptionSegment[] = []
   if (blunderMove && treach) {
-    tail = ` ${pick(CAREFUL)}${prefix}, this position is highly treacherous! It is easy to go astray with ${temptW} blunders like ${uciToSan(
-      blunderMove,
-    )}.`
+    tailSegments = [
+      {
+        type: 'text',
+        content: ` ${pick(CAREFUL)}${prefix}, this position is highly treacherous! It is easy to go astray with ${temptW} blunders like `,
+      },
+      { type: 'move', san: uciToSan(blunderMove), uci: blunderMove },
+      { type: 'text', content: '.' },
+    ]
   } else if (blunderMove) {
-    tail = ` ${pick(CAREFUL)}${prefix}! There is a ${temptW} blunder in this position: ${uciToSan(
-      blunderMove,
-    )}.`
+    tailSegments = [
+      {
+        type: 'text',
+        content: ` ${pick(CAREFUL)}${prefix}! There is a ${temptW} blunder in this position: `,
+      },
+      { type: 'move', san: uciToSan(blunderMove), uci: blunderMove },
+      { type: 'text', content: '.' },
+    ]
   } else {
     const showTempt = setT < 2 || (setT === 2 && temptLv > 4)
     if (showTempt) {
@@ -261,22 +279,73 @@ export function describePosition(
           Object.entries(aggProb)
             .filter(([m]) => !good.includes(m))
             .sort((a, b) => b[1] - a[1])[0]?.[0] ?? ''
-      const temptSan = temptUci ? uciToSan(temptUci) : ''
+
       const intro = pick(TEMPTING_INTRO)
-      tail = temptSan
-        ? ` ${intro}${prefix} are also ${temptW} alternatives, such as ${temptSan}.`
-        : ` ${intro}${prefix} are also ${temptW} alternatives.`
+      if (temptUci) {
+        tailSegments = [
+          {
+            type: 'text',
+            content: ` ${intro}${prefix} are also ${temptW} alternatives, such as `,
+          },
+          { type: 'move', san: uciToSan(temptUci), uci: temptUci },
+          { type: 'text', content: '.' },
+        ]
+      } else {
+        tailSegments = [
+          {
+            type: 'text',
+            content: ` ${intro}${prefix} are also ${temptW} alternatives.`,
+          },
+        ]
+      }
     }
   }
 
   /* ---------- assemble ---------- */
-  const moveList = bestHarder ? listWithoutOpt : listWithOpt
-  const result =
-    nGood === 1
-      ? `There ${verb} ${abundance} (${moveList}) ${outcome}, and ${pron} ${phrSet}.${tail}`
-      : bestHarder
-        ? `There ${verb} ${abundance} (${moveList}) ${outcome}, and ${pron} ${phrSet}, but the best move (${bestMoveSan}) is ${phrBest}.${tail}`
-        : `There ${verb} ${abundance} (${moveList}) ${outcome}, and ${pron} ${phrSet}.${tail}`
+  const segments: DescriptionSegment[] = []
+
+  // Helper function to create move list segments
+  const createMoveListSegments = (moveList: { san: string; uci: string }[]) => {
+    const moveSegments: DescriptionSegment[] = []
+    moveList.forEach((move, index) => {
+      moveSegments.push({ type: 'move', san: move.san, uci: move.uci })
+      if (index < moveList.length - 1) {
+        moveSegments.push({ type: 'text', content: ', ' })
+      }
+    })
+    return moveSegments
+  }
+
+  // Main description
+  const moveList = bestHarder ? goodMovesWithoutOpt : goodMovesList
+
+  if (nGood === 1) {
+    segments.push(
+      { type: 'text', content: `There ${verb} ${abundance} (` },
+      ...createMoveListSegments(moveList),
+      { type: 'text', content: `) ${outcome}, and ${pron} ${phrSet}.` },
+    )
+  } else if (bestHarder) {
+    segments.push(
+      { type: 'text', content: `There ${verb} ${abundance} (` },
+      ...createMoveListSegments(moveList),
+      {
+        type: 'text',
+        content: `) ${outcome}, and ${pron} ${phrSet}, but the best move (`,
+      },
+      { type: 'move', san: bestMoveSan, uci: opt },
+      { type: 'text', content: `) is ${phrBest}.` },
+    )
+  } else {
+    segments.push(
+      { type: 'text', content: `There ${verb} ${abundance} (` },
+      ...createMoveListSegments(moveList),
+      { type: 'text', content: `) ${outcome}, and ${pron} ${phrSet}.` },
+    )
+  }
+
+  // Add tail segments
+  segments.push(...tailSegments)
 
-  return result
+  return { segments }
 }

Original file line number	Diff line number	Diff line change
`@@ -17,7 +17,7 @@ export const useBoardDescription = (`
`17`	`17`	`!moveEvaluation?.maia \|\|`
`18`	`18`	`moveEvaluation.stockfish.depth < 12`
`19`	`19`	`) {`
`20`		`- return ''`
	`20`	`+ return { segments: [] }`
`21`	`21`	`}`
`22`	`22`
`23`	`23`	`const fen = currentNode.fen`