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/hooks/realtime-invalidation-core.ts

@@ -0,0 +1,52 @@
+import type { QueryClient, QueryKey } from '@tanstack/react-query';
+
+/** Minimum surface of socket.io's client we use here. Kept loose so the
+ *  helper can be unit-tested with a stub object without dragging the full
+ *  socket.io dependency into the test runtime. */
+export interface SocketLike {
+  on(event: string, handler: (...args: unknown[]) => void): unknown;
+  off(event: string, handler: (...args: unknown[]) => void): unknown;
+}
+
+export type EventMap = Record<string, QueryKey[]>;
+
+/**
+ * Pure subscription logic for `useRealtimeInvalidation`. Registers one
+ * handler per event key. Each handler reads the latest eventMap from the
+ * supplied getter so callers can pass a fresh object literal on every render
+ * without re-subscribing.
+ *
+ * Returns a cleanup function that removes the registered handlers.
+ *
+ * Lives in its own JSX-free file so it can be unit-tested under vitest's
+ * node environment without dragging the React provider into the bundle.
+ */
+export function subscribeRealtimeInvalidations(
+  socket: SocketLike,
+  eventKeys: string[],
+  queryClient: Pick<QueryClient, 'invalidateQueries'>,
+  getEventMap: () => EventMap,
+): () => void {
+  const handlers: Array<{ event: string; handler: (...args: unknown[]) => void }> = [];
+
+  for (const event of eventKeys) {
+    const handler = () => {
+      // Read the LATEST map at fire-time — not at subscription time — so
+      // callers passing inline `{ 'client:created': [...] }` literals don't
+      // bind a stale snapshot if they re-render.
+      const queryKeys = getEventMap()[event];
+      if (!queryKeys) return;
+      for (const key of queryKeys) {
+        queryClient.invalidateQueries({ queryKey: key });
+      }
+    };
+    socket.on(event, handler);
+    handlers.push({ event, handler });
+  }
+
+  return () => {
+    for (const { event, handler } of handlers) {
+      socket.off(event, handler);
+    }
+  };
+}