# 0001. Cross-tab QueryClient sync via `@tanstack/query-broadcast-client-experimental`

## Status

Accepted

## Context

The SeaHaven admin SPA is frequently used with multiple browser tabs open
against the same work-order board (e.g. a dispatcher triaging the board in one
tab while editing a work order in another). Each tab owns its own TanStack
Query `QueryClient` cache, so a mutation performed in one tab (status change,
dispatch creation, comment, vendor patch, etc.) does not invalidate or update
the cache in sibling tabs. Users were seeing stale board/detail data until a
manual refresh or the next background refetch.

We need a way to keep `QueryClient` caches roughly in sync across tabs of the
same origin, without introducing a new state-management layer (Redux is
disallowed by this repo's conventions) or a server-push mechanism.

## Decision

Use TanStack's own experimental broadcast client,
[`@tanstack/query-broadcast-client-experimental`](https://tanstack.com/query),
wired up in a single dedicated setup module,
`src/lib/query/setup-query-broadcast.ts`. The module:

- Exposes `startQueryBroadcast(queryClient, userId)` and
  `stopQueryBroadcast(queryClient)`.
- Keys `broadcastQueryClient` to an **account-scoped** channel
  (`seahaven-admin-query:${userId}`), so tabs belonging to different accounts
  on the same origin do not share cache traffic.
- Disposes the prior subscription (the unsubscribe returned by
  `broadcastQueryClient`) and clears the `QueryClient` when the authenticated
  user changes or the session ends.
- No-ops the BroadcastChannel outside the browser (SSR/build) and under Vitest
  (`import.meta.env.MODE === "test"`).
- Is started after authentication (`AuthProvider` session restore + login
  success) and stopped on logout and HTTP 401 session clear — not at
  `QueryClient` module load.

This piggybacks on the query cache we already have (no parallel store), uses
the library that owns the `QueryClient` we already depend on, and keeps the
integration isolated to auth/session boundaries.

### Alternatives considered

- **Custom `BroadcastChannel` + manual `queryClient.invalidateQueries` calls**
  — full control over payloads, but requires hand-rolling
  serialization/versioning of query keys and mutation results, and keeping
  every future mutation hook wired to broadcast. More code to own and more
  surface area for subtle cache-desync bugs.
- **Constant channel from module load** — simplest wiring, but shares one
  channel across all sessions on the origin; after logout/login or multi-account
  use, cached work-order/vendor data can leak into the next session. Rejected.
- **No cross-tab sync** — simplest option, but leaves the stale-tab UX problem
  unresolved; users would need to manually refresh or wait for
  `refetchOnWindowFocus`/`staleTime` to catch up, which is not reliable enough
  for a live dispatch board.
- **Full WebSocket-based real-time sync** — solves both cross-tab and
  cross-user staleness, but is a materially larger investment (server-side
  push infra, connection lifecycle, auth over the socket) that is out of scope
  for the current admin SPA and not justified by the actual problem (same
  browser, same user, same origin).

## Consequences

- **Positive**: sibling tabs for the same authenticated account reflect
  mutations (status changes, dispatch actions, comments, patches) without a
  manual refresh; logout/401 tear down the broadcaster and clear sensitive
  cache so the next account cannot inherit prior data.
- **Risk — package lifecycle**: the dependency is explicitly "experimental" in
  the TanStack ecosystem; its API may change or be deprecated between minor
  versions. `@tanstack/query-broadcast-client-experimental`,
  `@tanstack/react-query`, and `@tanstack/react-query-devtools` are pinned to
  the **exact same version** in `package.json` (no `^` range). All three
  resolve to the identical `@tanstack/query-core` version at that pin, which
  keeps the `QueryClient` type used by the broadcast helpers structurally
  identical to the one constructed in `query-client.ts` — a caret range lets
  npm resolve the broadcast client and React Query against two different
  `query-core` versions independently, which breaks `QueryClient` type
  identity (TS2322) even though both packages build fine in isolation. Bump
  all three together and re-evaluate on every TanStack Query upgrade.
- **Risk — same-origin only**: `BroadcastChannel` only syncs tabs on the same
  origin; it does not sync across different users/sessions or devices. Account
  scoping further limits sync to tabs of the same `userId`.
- **Rollback plan**: remove the `@tanstack/query-broadcast-client-experimental`
  dependency from `package.json`, delete `setup-query-broadcast.ts`, and remove
  the `startQueryBroadcast` / `stopQueryBroadcast` call sites in auth and
  `api.ts`. No other code depends on it, so rollback is isolated with no data
  migration.