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>

tests/unit/hooks/realtime-invalidation.test.ts

@@ -0,0 +1,158 @@
+import { describe, expect, it, vi } from 'vitest';
+import type { QueryClient, QueryKey } from '@tanstack/react-query';
+
+import {
+  subscribeRealtimeInvalidations,
+  type EventMap,
+  type SocketLike,
+} from '@/hooks/realtime-invalidation-core';
+
+/**
+ * Pure-logic tests for the realtime-invalidation subscription helper. The
+ * React hook (`useRealtimeInvalidation`) is just a thin wrapper around this
+ * function — verifying the handler-registration / fire-time-lookup behavior
+ * here is sufficient to lock in the bug fixes:
+ *   1. Re-subscribe storm (caller passing inline literals)
+ *   2. Fresh queryKeys read at fire-time
+ *
+ * The `useSocket` provider fix (don't null-context on disconnect) is verified
+ * separately by manual smoke + the existing socket integration coverage.
+ */
+
+function makeStubSocket() {
+  const listeners = new Map<string, Array<(...args: unknown[]) => void>>();
+  const onCalls: Array<{ event: string }> = [];
+  const offCalls: Array<{ event: string }> = [];
+
+  const socket: SocketLike = {
+    on(event, handler) {
+      onCalls.push({ event });
+      const arr = listeners.get(event) ?? [];
+      arr.push(handler);
+      listeners.set(event, arr);
+    },
+    off(event, handler) {
+      offCalls.push({ event });
+      const arr = listeners.get(event) ?? [];
+      listeners.set(
+        event,
+        arr.filter((h) => h !== handler),
+      );
+    },
+  };
+
+  function emit(event: string, ...args: unknown[]) {
+    for (const h of listeners.get(event) ?? []) h(...args);
+  }
+
+  return { socket, emit, onCalls, offCalls, listeners };
+}
+
+function makeStubQueryClient() {
+  const calls: QueryKey[] = [];
+  const queryClient = {
+    invalidateQueries: vi.fn(({ queryKey }: { queryKey: QueryKey }) => {
+      calls.push(queryKey);
+      return Promise.resolve();
+    }),
+  } as unknown as QueryClient;
+  return { queryClient, calls };
+}
+
+describe('subscribeRealtimeInvalidations', () => {
+  it('registers one .on() per event key', () => {
+    const { socket, onCalls } = makeStubSocket();
+    const { queryClient } = makeStubQueryClient();
+    const map: EventMap = {
+      'client:created': [['clients']],
+      'client:updated': [['clients'], ['clients', 'abc']],
+    };
+
+    subscribeRealtimeInvalidations(socket, Object.keys(map), queryClient, () => map);
+
+    expect(onCalls.map((c) => c.event).sort()).toEqual(['client:created', 'client:updated']);
+  });
+
+  it('invalidates each queryKey for the matching event', () => {
+    const { socket, emit } = makeStubSocket();
+    const { queryClient, calls } = makeStubQueryClient();
+    const map: EventMap = {
+      'client:updated': [['clients'], ['clients', 'abc']],
+    };
+
+    subscribeRealtimeInvalidations(socket, Object.keys(map), queryClient, () => map);
+    emit('client:updated');
+
+    expect(calls).toEqual([['clients'], ['clients', 'abc']]);
+  });
+
+  it('reads the LATEST eventMap at fire time, not at subscription time', () => {
+    // This is the core of the re-subscribe-storm fix: callers can swap in a
+    // new eventMap object without re-subscribing, and the handler still sees
+    // the fresh queryKey list.
+    const { socket, emit } = makeStubSocket();
+    const { queryClient, calls } = makeStubQueryClient();
+
+    let currentMap: EventMap = {
+      'client:updated': [['clients']],
+    };
+    subscribeRealtimeInvalidations(socket, ['client:updated'], queryClient, () => currentMap);
+
+    // First fire: see the original map
+    emit('client:updated');
+    expect(calls).toEqual([['clients']]);
+
+    // Caller re-renders with a fresh literal that includes more queryKeys
+    currentMap = {
+      'client:updated': [['clients'], ['clients', 'abc']],
+    };
+    emit('client:updated');
+
+    expect(calls).toEqual([['clients'], ['clients'], ['clients', 'abc']]);
+  });
+
+  it('cleanup deregisters every handler it registered', () => {
+    const { socket, emit, offCalls, listeners } = makeStubSocket();
+    const { queryClient, calls } = makeStubQueryClient();
+    const map: EventMap = {
+      'a:event': [['a']],
+      'b:event': [['b']],
+    };
+
+    const cleanup = subscribeRealtimeInvalidations(
+      socket,
+      Object.keys(map),
+      queryClient,
+      () => map,
+    );
+
+    cleanup();
+
+    expect(offCalls.map((c) => c.event).sort()).toEqual(['a:event', 'b:event']);
+    // All listeners removed — emitting after cleanup invalidates nothing.
+    emit('a:event');
+    emit('b:event');
+    expect(calls).toEqual([]);
+    // Defensive: the listener list should be empty after cleanup.
+    expect(listeners.get('a:event')?.length ?? 0).toBe(0);
+    expect(listeners.get('b:event')?.length ?? 0).toBe(0);
+  });
+
+  it('silently ignores events that have no entry in the current map', () => {
+    // If the caller swaps an event OUT mid-session, the registered handler
+    // still fires (we don't re-subscribe) but should be a no-op rather than
+    // throw.
+    const { socket, emit } = makeStubSocket();
+    const { queryClient, calls } = makeStubQueryClient();
+
+    let currentMap: EventMap = {
+      'client:updated': [['clients']],
+    };
+    subscribeRealtimeInvalidations(socket, ['client:updated'], queryClient, () => currentMap);
+
+    // Wipe the entry — handler will fire but find nothing to invalidate.
+    currentMap = {};
+    expect(() => emit('client:updated')).not.toThrow();
+    expect(calls).toEqual([]);
+  });
+});