feat(desktop): replace Zustand nav with wouter URL routing

Use browser history for page navigation in desktop and web admin, with
deep-linkable search params for server filters and client selection.

Signed-off-by: crimsonsunset <jsangio1@gmail.com>

Author: crimsonsunset

apps/desktop/package.json

@@ -32,6 +32,7 @@
     "react": "^19.1.0",
     "react-dom": "^19.1.0",
     "react-i18next": "^17.0.8",
+    "wouter": "^3.10.0",
     "zustand": "^5.0.9"
   },
   "devDependencies": {

apps/desktop/src/App.tsx

@@ -1,5 +1,6 @@
 import { useState, useEffect, useCallback } from 'react';
 import { useTranslation } from 'react-i18next';
+import { Route, Switch, Redirect, useLocation } from 'wouter';
 import { Sun, Moon, Download, X } from 'lucide-react';
 import { AppShell, Sidebar, SidebarItem, SidebarSection } from '@mcpmux/ui';
 import { ThemeProvider } from '@/components/ThemeProvider';
@@ -19,12 +20,11 @@ import {
   useViewSpace,
   useTheme,
   useAnalyticsEnabled,
-  useActiveNav,
-  useNavigateTo,
   useSetPendingSettingsSection,
   useIsLoading,
 } from '@/stores';
-import { NAV_ZONES, NAV_SETTINGS } from '@/lib/navigation';
+import { NAV_ZONES, NAV_SETTINGS, navItemFromPath } from '@/lib/navigation';
+import { useNavigate } from '@/hooks/use-navigate.hook';
 import { spaceAccentColor } from '@/lib/spaceAccent';
 import { DashboardPage } from '@/features/dashboard';
 import { RegistryPage } from '@/features/registry';
@@ -101,8 +101,8 @@ function AppContent() {
 
   useDataSync();
 
-  const activeNav = useActiveNav();
-  const navigateTo = useNavigateTo();
+  const [location] = useLocation();
+  const navigate = useNavigate();
   const setPendingSettingsSection = useSetPendingSettingsSection();
   const [availableUpdate, setAvailableUpdate] = useState<{ version: string } | null>(null);
 
@@ -183,8 +183,8 @@ function AppContent() {
   useAnalytics();
 
   useEffect(() => {
-    capture('page_viewed', { page: activeNav });
-  }, [activeNav]);
+    capture('page_viewed', { page: navItemFromPath(location) });
+  }, [location]);
 
   const [gatewayUrl, setGatewayUrl] = useState<string | null>(null);
   const loadGatewayUrl = useCallback(async () => {
@@ -234,8 +234,8 @@ function AppContent() {
           icon={<NAV_SETTINGS.icon className="h-4 w-4" />}
           label={t(NAV_SETTINGS.labelKey)}
           hint={t(NAV_SETTINGS.hintKey)}
-          active={activeNav === NAV_SETTINGS.key}
-          onClick={() => navigateTo(NAV_SETTINGS.key)}
+          active={location === NAV_SETTINGS.path}
+          onClick={() => navigate(NAV_SETTINGS.key)}
           data-testid={NAV_SETTINGS.testId}
         />
       }
@@ -249,8 +249,8 @@ function AppContent() {
               label={t(entry.labelKey)}
               hint={t(entry.hintKey)}
               title={entry.labelTitleKey ? t(entry.labelTitleKey) : undefined}
-              active={activeNav === entry.key}
-              onClick={() => navigateTo(entry.key)}
+              active={location === entry.path}
+              onClick={() => navigate(entry.key)}
               data-testid={entry.testId}
             />
           ))}
@@ -264,7 +264,7 @@ function AppContent() {
       <div className="flex items-center gap-4">
         <button
           type="button"
-          onClick={() => navigateTo('dashboard')}
+          onClick={() => navigate('dashboard')}
           className="flex items-center gap-1.5 transition-colors hover:text-[rgb(var(--foreground))]"
           data-testid="statusbar-gateway"
           title={tDashboard('statusbar.gatewayTitle')}
@@ -353,9 +353,8 @@ function AppContent() {
               </span>
               <button
                 onClick={() => {
-                  // Land on (and flash) the Updates section, not the top of Settings.
                   setPendingSettingsSection('updates');
-                  navigateTo('settings');
+                  navigate('settings');
                   setAvailableUpdate(null);
                 }}
                 className="font-medium text-blue-500 underline underline-offset-2 hover:text-blue-400"
@@ -374,15 +373,20 @@ function AppContent() {
           </div>
         )}
         <StaleBuildBanner />
-        {activeNav === 'dashboard' && <DashboardPage />}
-        {activeNav === 'registry' && <RegistryPage />}
-        {activeNav === 'servers' && <ServersPage />}
-        {activeNav === 'spaces' && <SpacesPage />}
-        {activeNav === 'featuresets' && <FeatureSetsPage />}
-        {activeNav === 'workspaces' && <WorkspacesPage />}
-        {activeNav === 'clients' && <ClientsPage />}
-        {activeNav === 'builtin-servers' && <BuiltinServersPage />}
-        {activeNav === 'settings' && <SettingsPage />}
+        <Switch>
+          <Route path="/">
+            <Redirect to="/dashboard" />
+          </Route>
+          <Route path="/dashboard" component={DashboardPage} />
+          <Route path="/registry" component={RegistryPage} />
+          <Route path="/servers" component={ServersPage} />
+          <Route path="/spaces" component={SpacesPage} />
+          <Route path="/featuresets" component={FeatureSetsPage} />
+          <Route path="/workspaces" component={WorkspacesPage} />
+          <Route path="/clients" component={ClientsPage} />
+          <Route path="/builtin-servers" component={BuiltinServersPage} />
+          <Route path="/settings" component={SettingsPage} />
+        </Switch>
       </div>
     </AppShell>
   );

apps/desktop/src/components/ConnectionCard.tsx

@@ -11,7 +11,8 @@ import {
   Sliders,
 } from 'lucide-react';
 import { Card, Button } from '@mcpmux/ui';
-import { useViewSpace, useNavigateTo, useSetPendingSettingsSection } from '@/stores';
+import { useViewSpace, useSetPendingSettingsSection } from '@/stores';
+import { useNavigate } from '@/hooks/use-navigate.hook';
 import { useGatewayControl } from '@/features/gateway/useGatewayControl';
 import { useGatewayEvents } from '@/hooks/useDomainEvents';
 import {
@@ -41,7 +42,7 @@ function extractPort(url: string | null): string {
 export function ConnectionCard() {
   const { t } = useTranslation('dashboard');
   const viewSpace = useViewSpace();
-  const navigateTo = useNavigateTo();
+  const navigate = useNavigate();
   const setPendingSettingsSection = useSetPendingSettingsSection();
   const gatewayControl = useGatewayControl();
 
@@ -192,9 +193,8 @@ export function ConnectionCard() {
             <button
               type="button"
               onClick={() => {
-                // Land on (and flash) the Gateway section where the port lives.
                 setPendingSettingsSection('gateway');
-                navigateTo('settings');
+                navigate('settings');
               }}
               className="group inline-flex items-center gap-1 text-xs text-[rgb(var(--muted))] hover:text-[rgb(var(--foreground))] transition-colors"
               data-testid="connection-port-settings-link"
@@ -255,7 +255,7 @@ export function ConnectionCard() {
         {pendingApprovals > 0 && (
           <button
             type="button"
-            onClick={() => navigateTo('clients')}
+            onClick={() => navigate('clients')}
             className="w-full flex items-center justify-between gap-3 rounded-lg border border-amber-300/60 dark:border-amber-700/60 bg-amber-50 dark:bg-amber-900/20 px-4 py-2.5 text-left hover:bg-amber-100/80 dark:hover:bg-amber-900/30 transition-colors"
             data-testid="connection-pending-approvals"
           >

apps/desktop/src/components/StatTile.tsx

@@ -1,6 +1,6 @@
 import { ArrowUpRight } from 'lucide-react';
 import type { LucideIcon } from 'lucide-react';
-import { useNavigateTo } from '@/stores';
+import { useNavigate } from '@/hooks/use-navigate.hook';
 import type { NavItem } from '@/stores/types';
 
 export interface StatTileProps {
@@ -30,11 +30,11 @@ export function StatTile({
   navTarget,
   navHint,
 }: StatTileProps) {
-  const navigateTo = useNavigateTo();
+  const navigate = useNavigate();
   return (
     <button
       type="button"
-      onClick={() => navigateTo(navTarget)}
+      onClick={() => navigate(navTarget)}
       title={navHint}
       data-testid={testId}
       className="group relative overflow-hidden rounded-xl border border-[rgb(var(--border-subtle))] bg-[rgb(var(--card))] p-4 text-left shadow transition-all duration-200 hover:-translate-y-0.5 hover:border-[rgb(var(--border))] hover:shadow-md"

apps/desktop/src/components/ViewerIdentity.tsx

@@ -9,14 +9,14 @@ import { MachineProfileEditor } from '@/components/machine-profile-editor';
 import { ServerIcon } from '@/components/ServerIcon';
 import { useViewerIdentity } from '@/hooks/use-viewer-identity.hook';
 import { NAV_SETTINGS } from '@/lib/navigation';
-import { useNavigateTo } from '@/stores';
+import { useNavigate } from '@/hooks/use-navigate.hook';
 
 /**
  * Blocking modal for first-time viewer device naming.
  */
 export function ViewerIdentityModal() {
   const { t } = useTranslation(['common', 'settings']);
-  const navigateTo = useNavigateTo();
+  const navigate = useNavigate();
   const {
     name,
     hints,
@@ -51,7 +51,7 @@ export function ViewerIdentityModal() {
     if (name) {
       closePrompt();
     }
-    navigateTo(NAV_SETTINGS.key);
+    navigate(NAV_SETTINGS.key);
   };
 
   const errorMessage =

apps/desktop/src/features/clients/ClientsPage.tsx

@@ -1,4 +1,5 @@
 import { useEffect, useMemo, useState, useCallback } from 'react';
+import { useSearch, useLocation } from 'wouter';
 import { useTranslation } from 'react-i18next';
 import type { TFunction } from 'i18next';
 import { useClientEvents, useOAuthClientEventListener } from '@/lib/backend/events';
@@ -43,12 +44,9 @@ import {
   type FeatureSet,
 } from '@/lib/api/featureSets';
 import { Card, CardContent, Button, useToast, ToastContainer, useConfirm } from '@mcpmux/ui';
-import {
-  useDefaultSpace,
-  useNavigateTo,
-  usePendingClientId,
-  useSetPendingClientId,
-} from '@/stores';
+import { useDefaultSpace } from '@/stores';
+import { useNavigate } from '@/hooks/use-navigate.hook';
+import { NAV_PATH_MAP } from '@/lib/navigation';
 
 // Bundled icons for well-known AI clients.
 const CLIENT_ICON_ASSETS: Record<string, string> = {
@@ -130,9 +128,10 @@ export default function ClientsPage() {
 
   const { toasts, success, error: showError, info, dismiss } = useToast();
   const { confirm, ConfirmDialogElement } = useConfirm();
-  const pendingClientId = usePendingClientId();
-  const setPendingClientId = useSetPendingClientId();
-  const navigateTo = useNavigateTo();
+  const search = useSearch();
+  const [, setLocation] = useLocation();
+  const selectClientId = new URLSearchParams(search).get('select');
+  const navigate = useNavigate();
   const defaultSpace = useDefaultSpace();
 
   const loadClients = async () => {
@@ -167,14 +166,14 @@ export default function ClientsPage() {
   }, []);
 
   useEffect(() => {
-    if (!pendingClientId || isLoading) return;
-    const client = clients.find((c) => c.client_id === pendingClientId);
+    if (!selectClientId || isLoading) return;
+    const client = clients.find((c) => c.client_id === selectClientId);
     if (client) {
       openPanel(client);
-      setPendingClientId(null);
+      setLocation(NAV_PATH_MAP.clients, { replace: true });
     }
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [pendingClientId, isLoading, clients]);
+  }, [selectClientId, isLoading, clients]);
 
   useClientEvents(
     useCallback(
@@ -273,7 +272,7 @@ export default function ClientsPage() {
               <p className="mt-2 max-w-2xl text-base text-[rgb(var(--muted))]">
                 {t('subtitlePrefix')}{' '}
                 <button
-                  onClick={() => navigateTo('workspaces')}
+                  onClick={() => navigate('workspaces')}
                   className="font-medium text-[rgb(var(--accent))] hover:underline"
                   data-testid="clients-workspaces-link"
                 >
@@ -405,7 +404,7 @@ export default function ClientsPage() {
             onRevoke={() => handleRevoke(selected)}
             onOpenWorkspaces={() => {
               setSelected(null);
-              navigateTo('workspaces');
+              navigate('workspaces');
             }}
             onToastError={showError}
             onToastSuccess={success}

apps/desktop/src/features/dashboard/DashboardQuickLinks.tsx

@@ -3,7 +3,7 @@ import { FolderOpen, Globe, Monitor, Search, Settings, ShoppingBasket } from 'lu
 import { McpNavIcon } from '@/components/McpNavIcon';
 import { useTranslation } from 'react-i18next';
 import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@mcpmux/ui';
-import { useNavigateTo } from '@/stores';
+import { useNavigate } from '@/hooks/use-navigate.hook';
 import type { NavItem } from '@/stores/types';
 
 type QuickLinkConfig = {
@@ -77,7 +77,7 @@ const QUICK_LINK_CONFIG: QuickLinkConfig[] = [
  * Compact navigation grid covering every sidebar destination except Dashboard.
  */
 export function DashboardQuickLinks() {
-  const navigateTo = useNavigateTo();
+  const navigate = useNavigate();
   const { t: tNav } = useTranslation('nav');
   const { t: tDashboard } = useTranslation('dashboard');
 
@@ -93,7 +93,7 @@ export function DashboardQuickLinks() {
             <button
               key={link.nav}
               type="button"
-              onClick={() => navigateTo(link.nav)}
+              onClick={() => navigate(link.nav)}
               data-testid={link.testId}
               className="flex items-start gap-3 rounded-lg border border-[rgb(var(--border-subtle))] px-3 py-2.5 text-left transition-colors hover:border-[rgb(var(--primary))/30] hover:bg-[rgb(var(--surface-hover))]"
             >

apps/desktop/src/features/dashboard/DashboardServerHealth.tsx

@@ -4,7 +4,7 @@ import type { TFunction } from 'i18next';
 import { AlertCircle, CheckCircle2, KeyRound, Loader2, Settings2 } from 'lucide-react';
 import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@mcpmux/ui';
 import { ServerLogViewer } from '@/components/ServerLogViewer';
-import { useNavigateTo, useSetPendingServersFilter } from '@/stores';
+import { useNavigate } from '@/hooks/use-navigate.hook';
 import type { AttentionKind, AttentionServer } from './dashboard.helpers';
 
 interface DashboardServerHealthProps {
@@ -53,8 +53,7 @@ export function DashboardServerHealth({
   isLoading,
 }: DashboardServerHealthProps) {
   const { t } = useTranslation('dashboard');
-  const navigateTo = useNavigateTo();
-  const setPendingServersFilter = useSetPendingServersFilter();
+  const navigate = useNavigate();
   const hasIssues = attentionServers.length > 0;
   const [logServer, setLogServer] = useState<{ id: string; name: string } | null>(null);
 
@@ -124,8 +123,11 @@ export function DashboardServerHealth({
           <button
             type="button"
             onClick={() => {
-              if (hasIssues) setPendingServersFilter('error');
-              navigateTo('servers');
+              if (hasIssues) {
+                navigate('servers', { filter: 'error' });
+                return;
+              }
+              navigate('servers');
             }}
             className="mt-4 text-sm font-medium text-primary-500 hover:text-primary-400"
             data-testid="dashboard-view-all-servers"

apps/desktop/src/features/dashboard/GetStartedStrip.tsx

@@ -1,12 +1,12 @@
 import { Compass, Monitor, Server, ArrowRight } from 'lucide-react';
-import { useNavigateTo } from '@/stores';
+import { useNavigate } from '@/hooks/use-navigate.hook';
 import type { NavItem } from '@/stores/types';
 
 /**
  * Three-step onboarding shown until the Space has its first installed server.
  */
 export function GetStartedStrip() {
-  const navigateTo = useNavigateTo();
+  const navigate = useNavigate();
   const steps = [
     {
       n: 1,
@@ -43,7 +43,7 @@ export function GetStartedStrip() {
           <button
             key={s.n}
             type="button"
-            onClick={() => navigateTo(s.nav)}
+            onClick={() => navigate(s.nav)}
             className="group flex items-start gap-3 p-4 text-left transition-colors hover:bg-[rgb(var(--primary))]/10"
           >
             <span className="flex h-8 w-8 flex-shrink-0 items-center justify-center rounded-lg bg-[rgb(var(--primary))]/15 text-sm font-bold text-[rgb(var(--primary))]">

apps/desktop/src/features/dashboard/SetUpFolderCard.tsx

@@ -1,20 +1,21 @@
 import { ArrowRight, FolderPlus } from 'lucide-react';
-import { useNavigateTo, useSetPendingWorkspaceNew } from '@/stores';
+import { useNavigate } from '@/hooks/use-navigate.hook';
+import { useSetPendingWorkspaceNew } from '@/stores';
 
 /**
  * Per-folder setup entry point. ConnectionCard connects an app to the
  * gateway globally; this routes into the Workspaces walkthrough to map a
  * specific project and write its per-folder config.
  */
 export function SetUpFolderCard() {
-  const navigateTo = useNavigateTo();
+  const navigate = useNavigate();
   const openWizard = useSetPendingWorkspaceNew();
   return (
     <button
       type="button"
       onClick={() => {
         openWizard(true);
-        navigateTo('workspaces');
+        navigate('workspaces');
       }}
       data-testid="dashboard-setup-folder"
       className="group flex w-full items-center gap-3 rounded-xl border border-[rgb(var(--border-subtle))] bg-[rgb(var(--card))] p-4 text-left shadow transition-all duration-200 hover:-translate-y-0.5 hover:border-[rgb(var(--border))] hover:shadow-md"