Add debug-only Stockfish loading phase messages

Author: ashtonanderson

src/contexts/StockfishEngineContext.tsx

@@ -11,6 +11,49 @@ import { StockfishStatus, StockfishEngine } from 'src/types'
 import Engine from 'src/lib/engine/stockfish'
 
 const STOCKFISH_LOADING_TOAST_DELAY_MS = 800
+const STOCKFISH_DEBUG_LOADING_KEY = 'maia.stockfishDebugLoading'
+
+const isTruthy = (value: string | null | undefined): boolean => {
+  if (!value) return false
+  return ['1', 'true', 'yes', 'on'].includes(value.toLowerCase())
+}
+
+const isStockfishDebugLoadingEnabled = (): boolean => {
+  if (typeof window !== 'undefined') {
+    try {
+      const localValue = window.localStorage.getItem(STOCKFISH_DEBUG_LOADING_KEY)
+      if (localValue !== null) return isTruthy(localValue)
+    } catch {
+      // ignore localStorage access failures
+    }
+  }
+
+  return isTruthy(process.env.NEXT_PUBLIC_STOCKFISH_DEBUG_LOADING)
+}
+
+const getStockfishLoadingLabel = (
+  engine: Engine | null,
+  debugLoadingEnabled: boolean,
+): string => {
+  if (!debugLoadingEnabled) {
+    return 'Loading Stockfish...'
+  }
+
+  if (!engine) return 'Loading Stockfish...'
+
+  switch (engine.initializationPhase) {
+    case 'checking-cache':
+      return 'Checking local Stockfish cache...'
+    case 'downloading-nnue':
+      return 'Downloading Stockfish model weights...'
+    case 'loading-nnue':
+      return 'Loading Stockfish from local cache...'
+    case 'loading-module':
+      return 'Starting Stockfish engine...'
+    default:
+      return 'Loading Stockfish...'
+  }
+}
 
 let sharedClientStockfishEngine: Engine | null = null
 
@@ -63,6 +106,12 @@ export const StockfishEngineContextProvider: React.FC<{
   const [error, setError] = useState<string | null>(
     () => engineRef.current?.initializationError ?? null,
   )
+  const [debugLoadingEnabled] = useState<boolean>(() =>
+    isStockfishDebugLoadingEnabled(),
+  )
+  const [loadingLabel, setLoadingLabel] = useState<string>(() =>
+    getStockfishLoadingLabel(engineRef.current, debugLoadingEnabled),
+  )
   const toastId = useRef<string | null>(null)
   const loadingToastTimerRef = useRef<number | null>(null)
 
@@ -90,6 +139,11 @@ export const StockfishEngineContextProvider: React.FC<{
       const engine = engineRef.current
       if (!engine) return
 
+      setLoadingLabel((prev) => {
+        const next = getStockfishLoadingLabel(engine, debugLoadingEnabled)
+        return prev === next ? prev : next
+      })
+
       if (engine.initializationError) {
         setStatus('error')
         setError(engine.initializationError)
@@ -105,7 +159,7 @@ export const StockfishEngineContextProvider: React.FC<{
     const interval = setInterval(checkEngineStatus, 100)
 
     return () => clearInterval(interval)
-  }, [])
+  }, [debugLoadingEnabled])
 
   // Toast notifications for Stockfish engine status
   useEffect(() => {
@@ -123,18 +177,25 @@ export const StockfishEngineContextProvider: React.FC<{
 
   useEffect(() => {
     if (status === 'loading') {
-      if (
-        toastId.current ||
-        loadingToastTimerRef.current !== null ||
-        typeof window === 'undefined'
-      ) {
+      if (typeof window === 'undefined') {
+        return
+      }
+
+      if (toastId.current) {
+        toastId.current = toast.loading(loadingLabel, { id: toastId.current })
+        return
+      }
+
+      if (loadingToastTimerRef.current !== null) {
         return
       }
 
       loadingToastTimerRef.current = window.setTimeout(() => {
         loadingToastTimerRef.current = null
         if (!toastId.current && engineRef.current && !engineRef.current.ready) {
-          toastId.current = toast.loading('Loading Stockfish Engine...')
+          toastId.current = toast.loading(
+            getStockfishLoadingLabel(engineRef.current, debugLoadingEnabled),
+          )
         }
       }, STOCKFISH_LOADING_TOAST_DELAY_MS)
       return
@@ -166,7 +227,7 @@ export const StockfishEngineContextProvider: React.FC<{
         toast.error(message)
       }
     }
-  }, [status, error])
+  }, [status, error, loadingLabel, debugLoadingEnabled])
 
   const contextValue = useMemo(
     () => ({

src/lib/engine/stockfish.ts

@@ -5,6 +5,14 @@ import { StockfishEvaluation } from 'src/types'
 import { StockfishModelStorage } from './stockfishStorage'
 
 const DEFAULT_NNUE_FETCH_TIMEOUT_MS = 30000
+type StockfishInitPhase =
+  | 'idle'
+  | 'loading-module'
+  | 'checking-cache'
+  | 'downloading-nnue'
+  | 'loading-nnue'
+  | 'ready'
+  | 'error'
 
 class Engine {
   private fen: string
@@ -25,6 +33,7 @@ class Engine {
   private evaluationGenerator: AsyncGenerator<StockfishEvaluation> | null
   private initError: string | null
   private initInFlight: boolean
+  private initPhase: StockfishInitPhase
 
   constructor() {
     this.fen = ''
@@ -39,6 +48,7 @@ class Engine {
     this.evaluationGenerator = null
     this.initError = null
     this.initInFlight = false
+    this.initPhase = 'idle'
 
     this.onMessage = this.onMessage.bind(this)
 
@@ -48,7 +58,10 @@ class Engine {
     }
 
     this.initInFlight = true
-    setupStockfish()
+    this.initPhase = 'loading-module'
+    setupStockfish((phase) => {
+      this.initPhase = phase
+    })
       .then((stockfish: StockfishWeb) => {
         this.stockfish = stockfish
         stockfish.uci('uci')
@@ -59,13 +72,15 @@ class Engine {
         this.initError = null
         this.isReady = true
         this.nnueLoaded = true
+        this.initPhase = 'ready'
       })
       .catch((error) => {
         console.error('Failed to initialize Stockfish:', error)
         this.initError =
           error instanceof Error ? error.message : 'Unknown initialization error'
         this.isReady = false
         this.nnueLoaded = false
+        this.initPhase = 'error'
       })
       .finally(() => {
         this.initInFlight = false
@@ -84,6 +99,10 @@ class Engine {
     return this.initInFlight
   }
 
+  get initializationPhase(): StockfishInitPhase {
+    return this.initPhase
+  }
+
   async *streamEvaluations(
     fen: string,
     legalMoveCount: number,
@@ -401,12 +420,14 @@ const loadNnueModel = async (
   modelUrl: string,
   storage: StockfishModelStorage,
   timeoutMs: number,
+  onNetworkFetchStart?: () => void,
 ): Promise<ArrayBuffer> => {
   const cachedModel = await storage.getModel(modelUrl)
   if (cachedModel) {
     return cachedModel
   }
 
+  onNetworkFetchStart?.()
   const response = await fetchWithTimeout(modelUrl, timeoutMs)
   if (!response.ok) {
     throw new Error(
@@ -419,7 +440,10 @@ const loadNnueModel = async (
   return buffer
 }
 
-const setupStockfish = async (): Promise<StockfishWeb> => {
+const setupStockfish = async (
+  onPhaseChange?: (phase: StockfishInitPhase) => void,
+): Promise<StockfishWeb> => {
+  onPhaseChange?.('loading-module')
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   const makeModule: any = await import('lila-stockfish-web/sf17-79.js')
   const instance: StockfishWeb = await makeModule.default({
@@ -438,12 +462,25 @@ const setupStockfish = async (): Promise<StockfishWeb> => {
   const nnue0Url = `${nnueBaseUrl}/${instance.getRecommendedNnue(0)}`
   const nnue1Url = `${nnueBaseUrl}/${instance.getRecommendedNnue(1)}`
   const timeoutMs = getNnueFetchTimeoutMs()
+  let downloadStarted = false
 
   try {
+    onPhaseChange?.('checking-cache')
     const buffers = await Promise.all([
-      loadNnueModel(nnue0Url, storage, timeoutMs),
-      loadNnueModel(nnue1Url, storage, timeoutMs),
+      loadNnueModel(nnue0Url, storage, timeoutMs, () => {
+        if (!downloadStarted) {
+          downloadStarted = true
+          onPhaseChange?.('downloading-nnue')
+        }
+      }),
+      loadNnueModel(nnue1Url, storage, timeoutMs, () => {
+        if (!downloadStarted) {
+          downloadStarted = true
+          onPhaseChange?.('downloading-nnue')
+        }
+      }),
     ])
+    onPhaseChange?.('loading-nnue')
     instance.setNnueBuffer(new Uint8Array(buffers[0]), 0)
     instance.setNnueBuffer(new Uint8Array(buffers[1]), 1)
     return instance