feat: Socket.IO client integration for persistent WS state updates

package.json

@@ -13,7 +13,9 @@
     "simulate": "node scripts/mock-webhook.js"
   },
   "dependencies": {
-    "@next/swc-win32-x64-msvc": "^14.2.4",
+    "@dnd-kit/core": "^6.3.1",
+    "@dnd-kit/sortable": "^10.0.0",
+    "@dnd-kit/utilities": "^3.2.2",
     "@stellar/freighter-api": "^6.0.1",
     "@stellar/stellar-sdk": "^11.3.0",
     "clsx": "^2.1.1",
@@ -32,6 +34,7 @@
     "react-i18next": "^15.5.3",
     "recharts": "2.12.7",
     "shepherd.js": "13.0.3",
+    "socket.io-client": "^4.8.3",
     "tailwind-merge": "^2.3.0",
     "zod": "^4.4.3"
   },

src/app/layout.tsx

@@ -10,6 +10,7 @@ import { ErrorProvider } from '@/components/ErrorModal';
 import { ThemeProvider } from '@/context/ThemeContext';
 import { I18nProvider } from '@/i18n';
 import { NetworkProvider } from '@/context/NetworkContext';
+import { SocketIOProvider } from '@/context/SocketIOContext';
 
 const inter = Inter({ subsets: ['latin'] });
 
@@ -30,15 +31,17 @@ export default function RootLayout({ children }: RootLayoutProps): ReactElement
           <AlertProvider>
             <ThemeProvider>
               <NetworkProvider>
-                <WalletProvider>
-                  <RoleProvider>
-                    <ErrorProvider>
-                      <ToastProvider>
-                        {children}
-                      </ToastProvider>
-                    </ErrorProvider>
-                  </RoleProvider>
-                </WalletProvider>
+                  <WalletProvider>
+                    <RoleProvider>
+                      <SocketIOProvider>
+                        <ErrorProvider>
+                          <ToastProvider>
+                            {children}
+                          </ToastProvider>
+                        </ErrorProvider>
+                      </SocketIOProvider>
+                    </RoleProvider>
+                  </WalletProvider>
               </NetworkProvider>
             </ThemeProvider>
           </AlertProvider>

src/components/VoteButton/__tests__/VoteButton.test.tsx

@@ -11,9 +11,6 @@ jest.mock('@/services/contractClient', () => ({
 jest.mock('@/context/RoleContext', () => ({
   useRole: jest.fn(),
 }));
-jest.mock('@/context/NetworkContext', () => ({
-  useNetwork: jest.fn(),
-}));
 jest.mock('@/components/Toast');
 jest.mock('@/utils/logger', () => ({
   appendAuditEvent: jest.fn(() => Promise.resolve()),
@@ -39,6 +36,7 @@ import { useNetwork } from '@/context/NetworkContext';
 const mockCastVote = castVote as jest.MockedFunction<typeof castVote>;
 const mockUseRole = useRole as jest.MockedFunction<typeof useRole>;
 const mockUseToast = useToast as jest.MockedFunction<typeof useToast>;
+const mockUseNetwork = useNetwork as jest.MockedFunction<typeof useNetwork>;
 const mockShowToast = jest.fn();
 const mockRefreshRole = jest.fn();
 

src/context/SocketIOContext.tsx

@@ -0,0 +1,31 @@
+'use client';
+
+import {
+  createContext,
+  useContext,
+  type ReactNode,
+} from 'react';
+import { useSocketIO, type UseSocketIOResult } from '@/hooks/useSocketIO';
+
+const SocketIOContext = createContext<UseSocketIOResult | null>(null);
+
+export function SocketIOProvider({ children }: { children: ReactNode }) {
+  const socket = useSocketIO({
+    autoConnect: true,
+    invalidateOnEvent: true,
+  });
+
+  return (
+    <SocketIOContext.Provider value={socket}>
+      {children}
+    </SocketIOContext.Provider>
+  );
+}
+
+export function useSocketIOContext(): UseSocketIOResult {
+  const ctx = useContext(SocketIOContext);
+  if (!ctx) {
+    throw new Error('useSocketIOContext must be used within a SocketIOProvider');
+  }
+  return ctx;
+}

src/hooks/__tests__/useSocketIO.test.ts

@@ -0,0 +1,160 @@
+import { renderHook, act } from '@testing-library/react';
+import type { Socket } from 'socket.io-client';
+import { useSocketIO } from '@/hooks/useSocketIO';
+import {
+  getSocket,
+  resetSocketClientForTests,
+} from '@/services/socketClient';
+
+type MockedSocket = jest.Mocked<Pick<Socket, 'on' | 'off' | 'emit' | 'disconnect' | 'connect' | 'removeAllListeners'>> & {
+  onAny: jest.Mock;
+  connected: boolean;
+  auth: Record<string, unknown>;
+};
+
+function getMockedSocket(): MockedSocket {
+  return getSocket() as unknown as MockedSocket;
+}
+
+jest.mock('socket.io-client', () => {
+  const mockSocket: MockedSocket = {
+    on: jest.fn(),
+    off: jest.fn(),
+    emit: jest.fn(),
+    disconnect: jest.fn(),
+    connect: jest.fn(),
+    removeAllListeners: jest.fn(),
+    connected: false,
+    auth: {},
+    onAny: jest.fn(),
+  };
+  return {
+    io: jest.fn(() => mockSocket),
+  };
+});
+
+const mockUseEvents = jest.fn().mockReturnValue({
+  emit: jest.fn(),
+  timeline: [],
+  clear: jest.fn(),
+});
+
+jest.mock('@/hooks/useEvents', () => ({
+  useEvents: (opts?: { maxEvents?: number }) => mockUseEvents(opts),
+}));
+
+const mockInvalidateChainState = jest.fn();
+jest.mock('@/hooks/useChainState', () => ({
+  invalidateChainState: (...args: unknown[]) => mockInvalidateChainState(...args),
+}));
+
+const OLD_ENV = process.env;
+
+beforeEach(() => {
+  jest.resetModules();
+  process.env = { ...OLD_ENV };
+  process.env.NEXT_PUBLIC_SOCKET_IO_URL = 'http://localhost:3001';
+});
+
+afterEach(() => {
+  process.env = OLD_ENV;
+  resetSocketClientForTests();
+  jest.clearAllMocks();
+});
+
+describe('useSocketIO', () => {
+  it('returns initial disconnected status', () => {
+    const { result } = renderHook(() => useSocketIO({ autoConnect: false }));
+    expect(result.current.status).toBe('disconnected');
+    expect(result.current.isConnected).toBe(false);
+    expect(result.current.lastEvent).toBeNull();
+  });
+
+  it('connects on autoConnect by default', () => {
+    renderHook(() => useSocketIO());
+    expect(getSocket()).not.toBeNull();
+  });
+
+  it('respects autoConnect=false', () => {
+    renderHook(() => useSocketIO({ autoConnect: false }));
+    expect(getSocket()).toBeNull();
+  });
+
+  it('connect function triggers connection', () => {
+    const { result } = renderHook(() => useSocketIO({ autoConnect: false }));
+    act(() => { result.current.connect(); });
+    expect(getSocket()).not.toBeNull();
+  });
+
+  it('disconnect function disconnects', () => {
+    const { result } = renderHook(() => useSocketIO({ autoConnect: true }));
+    act(() => { result.current.disconnect(); });
+    expect(getSocket()).toBeNull();
+  });
+
+  it('receives lastEvent when Socket.IO event fires', () => {
+    const { result } = renderHook(() =>
+      useSocketIO({ autoConnect: true, invalidateOnEvent: false }),
+    );
+
+    const socket = getMockedSocket();
+    const onAnyCalls = (socket.onAny as jest.Mock).mock.calls;
+    const onAnyHandler = onAnyCalls[0]?.[0];
+
+    act(() => {
+      if (onAnyHandler) onAnyHandler('vote:cast', { prId: 42 });
+    });
+
+    expect(result.current.lastEvent).toEqual({
+      event: 'vote:cast',
+      data: { prId: 42 },
+    });
+  });
+
+  it('calls invalidateChainState on events', () => {
+    renderHook(() => useSocketIO({ autoConnect: true, invalidateOnEvent: true }));
+
+    const socket = getMockedSocket();
+    const onAnyCalls = (socket.onAny as jest.Mock).mock.calls;
+    const onAnyHandler = onAnyCalls[0]?.[0];
+
+    act(() => {
+      if (onAnyHandler) onAnyHandler('pr:update', { id: 42 });
+    });
+
+    expect(mockInvalidateChainState).toHaveBeenCalledWith(
+      expect.arrayContaining(['prs', 'dashboard']),
+      'websocket',
+    );
+  });
+
+  it('invokes useEvents emit when events arrive', () => {
+    const mockEmit = jest.fn();
+    mockUseEvents.mockReturnValue({ emit: mockEmit, timeline: [], clear: jest.fn() });
+
+    renderHook(() => useSocketIO({ autoConnect: true }));
+
+    const socket = getMockedSocket();
+    const onAnyCalls = (socket.onAny as jest.Mock).mock.calls;
+    const onAnyHandler = onAnyCalls[0]?.[0];
+
+    act(() => {
+      if (onAnyHandler) onAnyHandler('reputation:change', { score: 100 });
+    });
+
+    expect(mockEmit).toHaveBeenCalledWith(
+      expect.objectContaining({ type: 'reputation_change', resource: 'socket.io' }),
+    );
+  });
+
+  it('updateToken calls socket client updateAuthToken', () => {
+    const { result } = renderHook(() => useSocketIO({ autoConnect: true }));
+
+    const socket = getMockedSocket();
+
+    act(() => { result.current.updateToken('new-token'); });
+
+    expect(socket.disconnect as jest.Mock).toHaveBeenCalled();
+    expect(socket.connect as jest.Mock).toHaveBeenCalled();
+  });
+});