fix(realtime): keep socket through reconnects, stop re-subscribe storm

Two correctness bugs in the real-time stack — both silent failures, both
session-wide once they trigger.

(1) `SocketProvider` was setting the React context to null on every
`disconnect` event. socket.io's built-in reconnection re-establishes the
underlying transport and replays handlers, but the React tree had
already lost its reference to the socket — so every `useSocket()`
consumer saw null until a session/port change forced a remount. Effect:
after the first transient drop (laptop sleep, wifi blip, server
restart), realtime invalidation and toasts went dead session-wide with
no user-visible signal.

Fix: keep the socket reference stable for the lifetime of the
session+port, and surface a separate `isConnected` boolean for any UI
that wants to render an offline indicator. Exposed as a new
`useIsSocketConnected()` hook; `useSocket()` signature is unchanged.

(2) `useRealtimeInvalidation` captured `eventMap` as a useEffect
dependency. Every caller passes a fresh `{ ... }` object literal on each
render, so the effect re-ran every render → `socket.off`/`socket.on`
storm on pages with many subscribed events.

Fix: extract the subscription logic into a pure helper
(`realtime-invalidation-core.ts`, JSX-free for vitest). The hook now
keeps the latest map in a ref and only re-subscribes when the SET of
event names changes (joined-keys signature, not object identity). The
handler reads `ref.current` at fire time, so callers still see fresh
queryKey lists without re-binding.

Helper is unit-tested with a stub socket: registration count,
fire-time map lookup, cleanup deregistration, missing-event safety.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

src/providers/socket-provider.tsx

@@ -13,7 +13,20 @@ import { io, type Socket } from 'socket.io-client';
 import { useSession } from '@/lib/auth/client';
 import { usePortStore } from '@/stores/ui-store';
 
-const SocketContext = createContext<Socket | null>(null);
+interface SocketContextValue {
+  /** Stable socket instance reference. Persists across reconnects — socket.io's
+   *  built-in reconnection re-establishes the underlying transport without
+   *  changing the JS object, so this stays valid as long as the session and
+   *  port are unchanged. Consumers should NOT null-check this for "is online";
+   *  use `isConnected` instead. */
+  socket: Socket | null;
+  /** Live transport state. Flips false on disconnect and back to true on
+   *  reconnect. Use this if you need to surface offline UX; the socket itself
+   *  stays subscribed to the same event handlers. */
+  isConnected: boolean;
+}
+
+const SocketContext = createContext<SocketContextValue>({ socket: null, isConnected: false });
 
 /** Returns true once the component has mounted on the client. Avoids calling
  *  better-auth's `useSession()` (which dispatches React hooks via nanostores)
@@ -32,7 +45,9 @@ export function SocketProvider({ children }: { children: ReactNode }) {
   return hasMounted ? (
     <SocketProviderClient>{children}</SocketProviderClient>
   ) : (
-    <SocketContext.Provider value={null}>{children}</SocketContext.Provider>
+    <SocketContext.Provider value={{ socket: null, isConnected: false }}>
+      {children}
+    </SocketContext.Provider>
   );
 }
 
@@ -40,9 +55,14 @@ function SocketProviderClient({ children }: { children: ReactNode }) {
   const { data: session } = useSession();
   const currentPortId = usePortStore((s) => s.currentPortId);
   const [socket, setSocket] = useState<Socket | null>(null);
+  const [isConnected, setIsConnected] = useState(false);
 
   useEffect(() => {
-    if (!session?.user || !currentPortId) return;
+    if (!session?.user || !currentPortId) {
+      setSocket(null);
+      setIsConnected(false);
+      return;
+    }
 
     const s = io(process.env.NEXT_PUBLIC_APP_URL!, {
       path: '/socket.io/',
@@ -51,18 +71,38 @@ function SocketProviderClient({ children }: { children: ReactNode }) {
       transports: ['websocket', 'polling'],
     });
 
-    s.on('connect', () => setSocket(s));
-    s.on('disconnect', () => setSocket(null));
+    // Set the socket reference immediately and keep it stable across the
+    // session+port lifetime. socket.io reconnects internally; the same
+    // instance survives transient drops, and any handlers registered via
+    // `socket.on(...)` stay attached. Previously we set/unset `socket` on
+    // connect/disconnect, which made the React context flip to null on every
+    // network blip and silently killed every `useRealtimeInvalidation`
+    // subscription session-wide.
+    setSocket(s);
+
+    s.on('connect', () => setIsConnected(true));
+    s.on('disconnect', () => setIsConnected(false));
 
     return () => {
       s.disconnect();
       setSocket(null);
+      setIsConnected(false);
     };
   }, [session?.user, currentPortId]);
 
-  return <SocketContext.Provider value={socket}>{children}</SocketContext.Provider>;
+  return (
+    <SocketContext.Provider value={{ socket, isConnected }}>{children}</SocketContext.Provider>
+  );
 }
 
-export function useSocket() {
-  return useContext(SocketContext);
+/** Returns the Socket.IO client instance. The reference is stable for the
+ *  duration of a session+port, even across transient disconnects. */
+export function useSocket(): Socket | null {
+  return useContext(SocketContext).socket;
+}
+
+/** True while the socket transport is connected. Flips false on disconnect,
+ *  back to true on reconnect. Useful for surfacing an "offline" indicator. */
+export function useIsSocketConnected(): boolean {
+  return useContext(SocketContext).isConnected;
 }