[harshil-2096]

Summary

Closes AGE-2575

Changes

How was this tested?

Checklist

• I have read the contributing guidelines
• pnpm build, pnpm test, pnpm typecheck, pnpm lint:ci, and pnpm format:check pass locally
• Tests added/updated where it makes sense
• No hand-edits to generated code (packages/trueforge-sdk, python/trueforge_sdk, .github/fern/openapi/openapi.json, docs/openapi.json) — fork PRs omit SDK regen; maintainers regenerate after merge
• Docs / .env.example updated if configuration or behavior changed

---

Note

Medium Risk
Changes how capabilities are fetched and cached at the root of the UI tree; incorrect cache scoping on server swap could show wrong tenant flags, though new tests explicitly guard that path.

Overview
Introduces @tanstack/react-query in @truefoundry/trueforge-ui with a dedicated per-ServerProvider query client (ServerQueryClientContext), so host apps are not required to wrap the UI in QueryClientProvider and their own React Query setup is not overridden.

Capabilities loading in ServerProvider moves from manual useEffect + cancelable fetches to useQuery with keepPreviousData on server swap (avoids gated UI flicker) and invalidateQueries for refresh (failed refreshes still keep last known data). When the server prop changes, the client is rescoped via a scoped queryKeyHashFn so cached data from the previous server is never reused.

Adds queryClient.ts (defaults: 30s stale time, no focus/reconnect refetch or retries, explicit mount/unmount) and a queryKeys catalog for upcoming cached server reads. Bundles mark React Query as external; tests cover offline resume, isolated clients outside ServerProvider, server swap cache isolation, and a draft selector assertion that waits for capabilities after the async load change.

^{Reviewed by Cursor Bugbot for commit 5e01952. Bugbot is set up for automated code reviews on this repo. Configure here.}

[changeset-bot]

🦋 Changeset detected

Latest commit: e4ecb1a

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@truefoundry/trueforge-ui	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 5e01952. Configure here.}