fix: address PR #319 review feedback — health validation, error handling, queryClient decoupling

- Rust: Replace fragile body.contains("status") with proper JSON
  deserialization validating status=="healthy", model_loaded (bool),
  and gpu_available (bool) to prevent misidentifying non-Voicebox services

- Frontend: Validate health response has Voicebox-specific fields before
  marking server as ready during fallback polling

- Frontend: Discriminate port-in-use errors (poll for external server) from
  real startup failures (missing sidecar, signing issues) — surface errors
  immediately with a startupError state and Retry button in the UI

- Frontend: Set explicit startup-error state when 2-minute polling timeout
  expires so the loading screen shows actionable feedback instead of hanging

- Architecture: Extract QueryClient to standalone side-effect-free module
  (lib/queryClient.ts) to decouple serverStore from React bootstrap entrypoint

app/src/App.tsx

@@ -4,6 +4,8 @@ import voiceboxLogo from '@/assets/voicebox-logo.png';
 import ShinyText from '@/components/ShinyText';
 import { TitleBarDragRegion } from '@/components/TitleBarDragRegion';
 import { useAutoUpdater } from '@/hooks/useAutoUpdater';
+import { apiClient } from '@/lib/api/client';
+import type { HealthResponse } from '@/lib/api/types';
 import { TOP_SAFE_AREA_PADDING } from '@/lib/constants/ui';
 import { cn } from '@/lib/utils/cn';
 import { usePlatform } from '@/platform/PlatformContext';
@@ -11,6 +13,33 @@ import { router } from '@/router';
 import { useLogStore } from '@/stores/logStore';
 import { useServerStore } from '@/stores/serverStore';
 
+/**
+ * Validate that a health response has the expected Voicebox-specific shape.
+ * Prevents misidentifying an unrelated service on the same port.
+ */
+function isVoiceboxHealthResponse(health: HealthResponse): boolean {
+  return (
+    health?.status === 'healthy' &&
+    typeof health.model_loaded === 'boolean' &&
+    typeof health.gpu_available === 'boolean'
+  );
+}
+
+/**
+ * Check whether a startup error indicates the port is occupied by an external
+ * server (which we should try to reuse via health-check polling) vs. a real
+ * failure (missing sidecar, signing issue, etc.) that should surface immediately.
+ */
+function isPortInUseError(error: unknown): boolean {
+  const msg = error instanceof Error ? error.message : String(error);
+  return (
+    msg.includes('already in use') ||
+    msg.includes('port') ||
+    msg.includes('EADDRINUSE') ||
+    msg.includes('address already in use')
+  );
+}
+
 const LOADING_MESSAGES = [
   'Warming up tensors...',
   'Calibrating synthesizer engine...',
@@ -37,6 +66,7 @@ const LOADING_MESSAGES = [
 function App() {
   const platform = usePlatform();
   const [serverReady, setServerReady] = useState(false);
+  const [startupError, setStartupError] = useState<string | null>(null);
   const [loadingMessageIndex, setLoadingMessageIndex] = useState(0);
   const serverStartingRef = useRef(false);
 
@@ -122,6 +152,46 @@ function App() {
         serverStartingRef.current = false;
         // @ts-expect-error - adding property to window
         window.__voiceboxServerStartedByApp = false;
+
+        // Only fall back to health-check polling when the error indicates the
+        // port is occupied (likely an external server). For real failures
+        // (missing sidecar, signing issues, etc.) surface the error immediately.
+        if (!isPortInUseError(error)) {
+          const msg = error instanceof Error ? error.message : String(error);
+          console.error('Real startup failure — not polling:', msg);
+          setStartupError(msg);
+          return;
+        }
+
+        // Fall back to polling: the server may already be running externally
+        // (e.g. started via python/uvicorn/Docker). Poll the health endpoint
+        // until it responds with a valid Voicebox payload, then transition to
+        // the main UI.
+        console.log('Falling back to health-check polling...');
+        const pollInterval = setInterval(async () => {
+          try {
+            const health = await apiClient.getHealth();
+            if (!isVoiceboxHealthResponse(health)) {
+              console.log('Health response is not from a Voicebox server, keep polling...');
+              return;
+            }
+            console.log('External Voicebox server detected via health check');
+            clearInterval(pollInterval);
+            setServerReady(true);
+          } catch {
+            // Server not ready yet, keep polling
+          }
+        }, 2000);
+
+        // Stop polling after 2 minutes and surface the failure
+        setTimeout(() => {
+          clearInterval(pollInterval);
+          serverStartingRef.current = false;
+          setStartupError(
+            'Could not connect to a Voicebox server within 2 minutes. ' +
+              'Please check that the server is running and try again.',
+          );
+        }, 120_000);
       });
 
     // Cleanup: stop server on actual unmount (not StrictMode remount)
@@ -168,15 +238,34 @@ function App() {
               className="w-48 h-48 object-contain animate-fade-in-scale relative z-10"
             />
           </div>
-          <div className="animate-fade-in-delayed">
-            <ShinyText
-              text={LOADING_MESSAGES[loadingMessageIndex]}
-              className="text-lg font-medium text-muted-foreground"
-              speed={2}
-              color="hsl(var(--muted-foreground))"
-              shineColor="hsl(var(--foreground))"
-            />
-          </div>
+          {startupError ? (
+            <div className="animate-fade-in-delayed max-w-md mx-auto space-y-3">
+              <p className="text-lg font-medium text-destructive">Server startup failed</p>
+              <p className="text-sm text-muted-foreground">{startupError}</p>
+              <button
+                type="button"
+                className="mt-2 px-4 py-2 text-sm rounded-md bg-primary text-primary-foreground hover:bg-primary/90 transition-colors"
+                onClick={() => {
+                  setStartupError(null);
+                  serverStartingRef.current = false;
+                  // Trigger a re-mount of the effect by toggling state
+                  window.location.reload();
+                }}
+              >
+                Retry
+              </button>
+            </div>
+          ) : (
+            <div className="animate-fade-in-delayed">
+              <ShinyText
+                text={LOADING_MESSAGES[loadingMessageIndex]}
+                className="text-lg font-medium text-muted-foreground"
+                speed={2}
+                color="hsl(var(--muted-foreground))"
+                shineColor="hsl(var(--foreground))"
+              />
+            </div>
+          )}
         </div>
       </div>
     );

app/src/components/Generation/FloatingGenerateBox.tsx

@@ -125,22 +125,22 @@ export function FloatingGenerateBox({
   }, [watchedEngine, setSelectedEngine]);
 
   // Sync generation form language, engine, and effects with selected profile
-  type EngineValue = 'qwen' | 'luxtts' | 'chatterbox' | 'chatterbox_turbo' | 'tada' | 'kokoro' | 'qwen_custom_voice';
   useEffect(() => {
     if (selectedProfile?.language) {
       form.setValue('language', selectedProfile.language as LanguageCode);
     }
-    // Auto-switch engine to match the profile
-    const engine = selectedProfile?.default_engine ?? selectedProfile?.preset_engine;
-    if (engine) {
-      form.setValue('engine', engine as EngineValue);
-    } else if (selectedProfile && selectedProfile.voice_type !== 'preset') {
-      // Cloned/designed profile with no default — ensure a compatible (non-preset) engine
-      const currentEngine = form.getValues('engine');
-      const presetEngines = new Set(['kokoro', 'qwen_custom_voice']);
-      if (presetEngines.has(currentEngine)) {
-        form.setValue('engine', 'qwen');
-      }
+    // Auto-switch engine if profile has a default
+    if (selectedProfile?.default_engine) {
+      form.setValue(
+        'engine',
+        selectedProfile.default_engine as
+          | 'qwen'
+          | 'luxtts'
+          | 'chatterbox'
+          | 'chatterbox_turbo'
+          | 'tada'
+          | 'kokoro',
+      );
     }
     // Pre-fill effects from profile defaults
     if (

app/src/components/VoiceProfiles/ProfileCard.tsx

@@ -25,10 +25,9 @@ const ENGINE_DISPLAY_NAMES: Record<string, string> = {
 
 interface ProfileCardProps {
   profile: VoiceProfileResponse;
-  disabled?: boolean;
 }
 
-export function ProfileCard({ profile, disabled }: ProfileCardProps) {
+export function ProfileCard({ profile }: ProfileCardProps) {
   const [deleteDialogOpen, setDeleteDialogOpen] = useState(false);
 
   const deleteProfile = useDeleteProfile();
@@ -41,12 +40,6 @@ export function ProfileCard({ profile, disabled }: ProfileCardProps) {
   const isSelected = selectedProfileId === profile.id;
 
   const handleSelect = () => {
-    // If disabled but already selected, bounce the selection to re-trigger engine auto-switch
-    if (disabled && isSelected) {
-      setSelectedProfileId(null);
-      setTimeout(() => setSelectedProfileId(profile.id), 0);
-      return;
-    }
     setSelectedProfileId(isSelected ? null : profile.id);
   };
 
@@ -87,9 +80,8 @@ export function ProfileCard({ profile, disabled }: ProfileCardProps) {
     <>
       <Card
         className={cn(
-          'cursor-pointer transition-all flex flex-col h-[162px]',
-          disabled ? 'opacity-40 hover:opacity-60' : 'hover:shadow-md',
-          isSelected && !disabled && 'ring-2 ring-accent shadow-md',
+          'cursor-pointer hover:shadow-md transition-all flex flex-col h-[162px]',
+          isSelected && 'ring-2 ring-accent shadow-md',
         )}
         onClick={handleSelect}
         tabIndex={0}

app/src/components/VoiceProfiles/ProfileList.tsx

@@ -1,5 +1,4 @@
-import { Info, Mic, Sparkles } from 'lucide-react';
-import { useEffect, useRef } from 'react';
+import { Mic, Music, Sparkles } from 'lucide-react';
 import { Button } from '@/components/ui/button';
 import { Card, CardContent } from '@/components/ui/card';
 import { useProfiles } from '@/lib/hooks/useProfiles';
@@ -10,31 +9,16 @@ import { ProfileForm } from './ProfileForm';
 /** Engines that use preset (built-in) voices instead of cloned profiles. */
 const PRESET_ENGINES = new Set(['kokoro', 'qwen_custom_voice']);
 
+/** Human-readable engine names for empty state messages. */
+const ENGINE_NAMES: Record<string, string> = {
+  kokoro: 'Kokoro',
+  qwen_custom_voice: 'Qwen CustomVoice',
+};
+
 export function ProfileList() {
   const { data: profiles, isLoading, error } = useProfiles();
   const setDialogOpen = useUIStore((state) => state.setProfileDialogOpen);
   const selectedEngine = useUIStore((state) => state.selectedEngine);
-  const selectedProfileId = useUIStore((state) => state.selectedProfileId);
-  const cardRefs = useRef<Map<string, HTMLDivElement>>(new Map());
-
-  // Scroll to the selected profile after engine/sort changes
-  useEffect(() => {
-    if (!selectedProfileId) return;
-    let timeoutId: ReturnType<typeof setTimeout> | null = null;
-    const rafId = requestAnimationFrame(() => {
-      const el = cardRefs.current.get(selectedProfileId);
-      if (!el) return;
-
-      // Temporarily apply scroll-margin so it doesn't land flush at the top
-      el.style.scrollMarginTop = '180px';
-      el.scrollIntoView({ behavior: 'smooth', block: 'nearest', inline: 'nearest' });
-      timeoutId = setTimeout(() => { el.style.scrollMarginTop = ''; }, 500);
-    });
-    return () => {
-      cancelAnimationFrame(rafId);
-      if (timeoutId) clearTimeout(timeoutId);
-    };
-  }, [selectedProfileId, selectedEngine]);
 
   if (isLoading) {
     return null;
@@ -51,18 +35,10 @@ export function ProfileList() {
   const allProfiles = profiles || [];
   const isPresetEngine = PRESET_ENGINES.has(selectedEngine);
 
-  /** Whether a profile is supported by the currently selected engine. */
-  const isSupported = (p: (typeof allProfiles)[number]) =>
-    isPresetEngine
-      ? p.voice_type === 'preset' && p.preset_engine === selectedEngine
-      : p.voice_type !== 'preset';
-
-  // Sort so supported profiles come first
-  const sortedProfiles = [...allProfiles].sort(
-    (a, b) => (isSupported(a) ? 0 : 1) - (isSupported(b) ? 0 : 1),
-  );
-
-  const hasUnsupported = sortedProfiles.some((p) => !isSupported(p));
+  // Filter profiles based on selected engine
+  const filteredProfiles = isPresetEngine
+    ? allProfiles.filter((p) => p.voice_type === 'preset' && p.preset_engine === selectedEngine)
+    : allProfiles.filter((p) => p.voice_type !== 'preset');
 
   return (
     <div className="flex flex-col">
@@ -80,26 +56,29 @@ export function ProfileList() {
               </Button>
             </CardContent>
           </Card>
+        ) : filteredProfiles.length === 0 && isPresetEngine ? (
+          <Card>
+            <CardContent className="flex flex-col items-center justify-center py-12">
+              <Music className="h-12 w-12 text-muted-foreground mb-4" />
+              <p className="text-muted-foreground mb-2">
+                No {ENGINE_NAMES[selectedEngine] ?? selectedEngine} voices created yet.
+              </p>
+              <p className="text-sm text-muted-foreground mb-4">
+                Create a profile to choose a specific voice before generating.
+              </p>
+              <Button onClick={() => setDialogOpen(true)}>
+                <Sparkles className="mr-2 h-4 w-4" />
+                Create {ENGINE_NAMES[selectedEngine] ?? selectedEngine} Voice
+              </Button>
+            </CardContent>
+          </Card>
         ) : (
           <div className="flex gap-4 overflow-x-auto p-1 pb-1 lg:grid lg:grid-cols-3 lg:auto-rows-auto lg:overflow-x-visible lg:pb-[150px]">
-            {sortedProfiles.map((profile) => (
-              <div
-                key={profile.id}
-                className="shrink-0 w-[200px] lg:w-auto lg:shrink"
-                ref={(el) => {
-                  if (el) cardRefs.current.set(profile.id, el);
-                  else cardRefs.current.delete(profile.id);
-                }}
-              >
-                <ProfileCard profile={profile} disabled={!isSupported(profile)} />
+            {filteredProfiles.map((profile) => (
+              <div key={profile.id} className="shrink-0 w-[200px] lg:w-auto lg:shrink">
+                <ProfileCard profile={profile} />
               </div>
             ))}
-            {hasUnsupported && (
-              <div className="col-span-full flex items-center gap-2 text-xs text-muted-foreground py-2">
-                <Info className="h-3.5 w-3.5 shrink-0" />
-                <span>Only supported voice profiles can be selected for the current model.</span>
-              </div>
-            )}
           </div>
         )}
       </div>

app/src/lib/hooks/useGenerationForm.ts

@@ -10,7 +10,6 @@ import { useGeneration } from '@/lib/hooks/useGeneration';
 import { useModelDownloadToast } from '@/lib/hooks/useModelDownloadToast';
 import { useGenerationStore } from '@/stores/generationStore';
 import { useServerStore } from '@/stores/serverStore';
-import { useUIStore } from '@/stores/uiStore';
 
 const generationSchema = z.object({
   text: z.string().min(1, '').max(50000),
@@ -46,7 +45,6 @@ export function useGenerationForm(options: UseGenerationFormOptions = {}) {
   const maxChunkChars = useServerStore((state) => state.maxChunkChars);
   const crossfadeMs = useServerStore((state) => state.crossfadeMs);
   const normalizeAudio = useServerStore((state) => state.normalizeAudio);
-  const selectedEngine = useUIStore((state) => state.selectedEngine);
   const [downloadingModelName, setDownloadingModelName] = useState<string | null>(null);
   const [downloadingDisplayName, setDownloadingDisplayName] = useState<string | null>(null);
 
@@ -64,7 +62,7 @@ export function useGenerationForm(options: UseGenerationFormOptions = {}) {
       seed: undefined,
       modelSize: '1.7B',
       instruct: '',
-      engine: (selectedEngine as GenerationFormValues['engine']) || 'qwen',
+      engine: 'qwen',
       ...options.defaultValues,
     },
   });

app/src/lib/queryClient.ts

@@ -0,0 +1,19 @@
+import { QueryClient } from '@tanstack/react-query';
+
+/**
+ * Shared QueryClient instance used across the app.
+ *
+ * Extracted into its own side-effect-free module so it can be imported from
+ * both the React bootstrap (main.tsx) and non-React code (stores, utilities)
+ * without pulling in ReactDOM or other bootstrap side effects.
+ */
+export const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      staleTime: 1000 * 60 * 5, // 5 minutes
+      gcTime: 1000 * 60 * 10, // 10 minutes (formerly cacheTime)
+      retry: 1,
+      refetchOnWindowFocus: false,
+    },
+  },
+});

app/src/main.tsx

@@ -1,20 +1,10 @@
-import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { QueryClientProvider } from '@tanstack/react-query';
 // import { ReactQueryDevtools } from '@tanstack/react-query-devtools';
 import React from 'react';
 import ReactDOM from 'react-dom/client';
 import App from './App';
 import './index.css';
-
-const queryClient = new QueryClient({
-  defaultOptions: {
-    queries: {
-      staleTime: 1000 * 60 * 5, // 5 minutes
-      gcTime: 1000 * 60 * 10, // 10 minutes (formerly cacheTime)
-      retry: 1,
-      refetchOnWindowFocus: false,
-    },
-  },
-});
+import { queryClient } from './lib/queryClient';
 
 ReactDOM.createRoot(document.getElementById('root')!).render(
   <React.StrictMode>

app/src/stores/serverStore.ts

@@ -1,5 +1,6 @@
 import { create } from 'zustand';
 import { persist } from 'zustand/middleware';
+import { queryClient } from '@/lib/queryClient';
 
 interface ServerStore {
   serverUrl: string;
@@ -30,11 +31,25 @@ interface ServerStore {
   setCustomModelsDir: (dir: string | null) => void;
 }
 
+/**
+ * Invalidate all React Query caches so stale data from the previous
+ * server is not shown. Called when the server URL changes.
+ */
+function invalidateAllServerData() {
+  queryClient.invalidateQueries();
+}
+
 export const useServerStore = create<ServerStore>()(
   persist(
-    (set) => ({
+    (set, get) => ({
       serverUrl: 'http://127.0.0.1:17493',
-      setServerUrl: (url) => set({ serverUrl: url }),
+      setServerUrl: (url) => {
+        const prev = get().serverUrl;
+        set({ serverUrl: url });
+        if (url !== prev) {
+          invalidateAllServerData();
+        }
+      },
 
       isConnected: false,
       setIsConnected: (connected) => set({ isConnected: connected }),

backend/routes/profiles.py

@@ -4,7 +4,6 @@ import io
 import json as _json
 import logging
 import tempfile
-from datetime import datetime
 from pathlib import Path
 
 from fastapi import APIRouter, Depends, File, Form, HTTPException, UploadFile

tauri/src-tauri/src/main.rs

@@ -53,6 +53,41 @@ fn find_voicebox_pid_on_port(port: u16) -> Option<u32> {
     None
 }
 
+/// Check if a Voicebox server is responding on the given port.
+///
+/// Sends an HTTP GET to `/health` and returns `true` only if the response
+/// is valid JSON matching the Voicebox `HealthResponse` schema — specifically
+/// `status` must be `"healthy"`, and both `model_loaded` and `gpu_available`
+/// must be present as booleans. This prevents misidentifying an unrelated
+/// service that happens to expose a `/health` endpoint.
+#[allow(dead_code)] // Used in platform-specific cfg blocks
+fn check_health(port: u16) -> bool {
+    let url = format!("http://127.0.0.1:{}/health", port);
+    match reqwest::blocking::Client::builder()
+        .timeout(std::time::Duration::from_secs(3))
+        .build()
+    {
+        Ok(client) => match client.get(&url).send() {
+            Ok(resp) => {
+                if !resp.status().is_success() {
+                    return false;
+                }
+                // Parse as JSON and validate Voicebox-specific fields
+                match resp.json::<serde_json::Value>() {
+                    Ok(body) => {
+                        body.get("status").and_then(|v| v.as_str()) == Some("healthy")
+                            && body.get("model_loaded").map(|v| v.is_boolean()).unwrap_or(false)
+                            && body.get("gpu_available").map(|v| v.is_boolean()).unwrap_or(false)
+                    }
+                    Err(_) => false,
+                }
+            }
+            Err(_) => false,
+        },
+        Err(_) => false,
+    }
+}
+
 struct ServerState {
     child: Mutex<Option<tauri_plugin_shell::process::CommandChild>>,
     server_pid: Mutex<Option<u32>>,
@@ -80,7 +115,8 @@ async fn start_server(
         return Ok(format!("http://127.0.0.1:{}", SERVER_PORT));
     }
 
-    // Check if a voicebox server is already running on our port (from previous session with keep_running=true)
+    // Check if a voicebox server is already running on our port (from previous session with keep_running=true,
+    // or an externally started server e.g. via `python`, `uvicorn`, Docker, etc.)
     #[cfg(unix)]
     {
         use std::process::Command;
@@ -101,6 +137,20 @@ async fn start_server(
                             *state.server_pid.lock().unwrap() = Some(pid);
                             return Ok(format!("http://127.0.0.1:{}", SERVER_PORT));
                         }
+                    } else {
+                        // Process name doesn't contain "voicebox" — could be an external
+                        // Python/uvicorn/Docker server. Verify via HTTP health check.
+                        println!("Port {} in use by '{}' (PID: {}), checking if it's a Voicebox server...", SERVER_PORT, command, pid_str);
+                        if check_health(SERVER_PORT) {
+                            println!("Health check passed — reusing external server on port {}", SERVER_PORT);
+                            return Ok(format!("http://127.0.0.1:{}", SERVER_PORT));
+                        }
+                        println!("Health check failed — port is occupied by a non-Voicebox process");
+                        return Err(format!(
+                            "Port {} is already in use by another application ({}). \
+                             Close it or change the Voicebox server port.",
+                            SERVER_PORT, command
+                        ));
                     }
                 }
             }
@@ -114,18 +164,24 @@ async fn start_server(
             &format!("127.0.0.1:{}", SERVER_PORT).parse().unwrap(),
             std::time::Duration::from_secs(1),
         ).is_ok() {
-            // Port is in use — check if it's a voicebox process
+            // Port is in use — check if it's a voicebox process by name first
             if let Some(pid) = find_voicebox_pid_on_port(SERVER_PORT) {
                 println!("Found existing voicebox-server on port {} (PID: {}), reusing it", SERVER_PORT, pid);
                 *state.server_pid.lock().unwrap() = Some(pid);
                 return Ok(format!("http://127.0.0.1:{}", SERVER_PORT));
-            } else {
-                return Err(format!(
-                    "Port {} is already in use by another application. \
-                     Close the other application or change the Voicebox port.",
-                    SERVER_PORT
-                ));
             }
+            // Process name doesn't match — could be an external Python/Docker server.
+            // Verify via HTTP health check before giving up.
+            println!("Port {} in use by unknown process, checking if it's a Voicebox server...", SERVER_PORT);
+            if check_health(SERVER_PORT) {
+                println!("Health check passed — reusing external server on port {}", SERVER_PORT);
+                return Ok(format!("http://127.0.0.1:{}", SERVER_PORT));
+            }
+            return Err(format!(
+                "Port {} is already in use by another application. \
+                 Close the other application or change the Voicebox port.",
+                SERVER_PORT
+            ));
         }
     }