@skyhook-io/radar-app 0.2.2 → 0.3.1

package/src/context/ConnectionContext.tsx

@@ -1,7 +1,8 @@
 import { createContext, useContext, useState, useCallback, useEffect, useRef, ReactNode } from 'react'
 import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'
 import type { ContextInfo } from '../types'
-import { getApiBase, getAuthHeaders, getCredentialsMode } from '../api/config'
+import { getApiBase } from '../api/config'
+import { apiFetch } from '../api/client'
 
 export type ConnectionStateType = 'connected' | 'disconnected' | 'connecting'
 
@@ -10,7 +11,7 @@ export interface ConnectionState {
   context: string
   clusterName?: string
   error?: string
-  errorType?: string // auth, network, timeout, unknown
+  errorType?: string // config, auth, rbac, network, timeout, tls, unknown
   progressMessage?: string
 }
 
@@ -26,13 +27,30 @@ interface ConnectionContextValue {
   updateFromSSE: (status: ConnectionState) => void
 }
 
+class ConnectionRetryError extends Error {
+  errorType?: string
+
+  constructor(message: string, errorType?: string) {
+    super(message)
+    this.name = 'ConnectionRetryError'
+    this.errorType = errorType
+  }
+}
+
 const ConnectionContext = createContext<ConnectionContextValue | null>(null)
+const AUTO_RETRY_INITIAL_DELAY_MS = 10000
+const AUTO_RETRY_MAX_DELAY_MS = 60000
+
+export function shouldAutoRetryConnection(errorType?: string): boolean {
+  return errorType !== 'config' && errorType !== 'rbac'
+}
 
 async function fetchConnectionStatus(): Promise<ConnectionStatusResponse> {
-  const response = await fetch(`${getApiBase()}/connection`, {
-    credentials: getCredentialsMode(),
-    headers: getAuthHeaders(),
-  })
+  // apiFetch handles a 401 globally (re-auth redirect). These endpoints are
+  // no longer auth-exempt, so a session that expires while the connection-
+  // error screen is parked open must route through that path rather than
+  // surfacing as a misleading "cannot connect to cluster" error.
+  const response = await apiFetch(`${getApiBase()}/connection`)
   if (!response.ok) {
     throw new Error('Failed to fetch connection status')
   }
@@ -40,14 +58,12 @@ async function fetchConnectionStatus(): Promise<ConnectionStatusResponse> {
 }
 
 async function retryConnection(): Promise<ConnectionState> {
-  const response = await fetch(`${getApiBase()}/connection/retry`, {
+  const response = await apiFetch(`${getApiBase()}/connection/retry`, {
     method: 'POST',
-    credentials: getCredentialsMode(),
-    headers: getAuthHeaders(),
   })
   if (!response.ok) {
-    const error = await response.json().catch(() => ({ error: 'Unknown error' }))
-    throw new Error(error.error || `HTTP ${response.status}`)
+    const error = await response.json().catch(() => ({ error: 'Unknown error' })) as { error?: string; errorType?: string }
+    throw new ConnectionRetryError(error.error || `HTTP ${response.status}`, error.errorType)
   }
   return response.json()
 }
@@ -59,9 +75,29 @@ export function ConnectionProvider({ children }: { children: ReactNode }) {
     context: '',
   })
   const [contexts, setContexts] = useState<ContextInfo[]>([])
+  const [isAutoRetrying, setIsAutoRetrying] = useState(false)
   // Track if SSE has started delivering connection_state events
   // Once SSE is active, it becomes the authoritative source for connection state
   const sseActiveRef = useRef(false)
+  // Track whether we've reached 'connected' at least once. Distinguishes the
+  // initial connect (bootstrap queries already fetched while 'connecting') from
+  // a reconnect after a drop (cache may be stale across the gap).
+  const hasConnectedRef = useRef(false)
+  const autoRetryInFlightRef = useRef(false)
+  const autoRetryDelayRef = useRef(AUTO_RETRY_INITIAL_DELAY_MS)
+  const manualRetryPendingRef = useRef(false)
+  // Whether the QueryClient already held data when this provider mounted. A host
+  // can share one client across cluster-scoped RadarApp mounts (see RadarApp's
+  // `queryClient` prop); that client may carry another cluster's data under
+  // identical keys, so a warm-at-mount cache must be fully refreshed on first
+  // connect. A cold cache (standalone, or a per-cluster remount) takes the cheap
+  // error-only path. Snapshot synchronously before this provider's own query
+  // registers — ConnectionProvider is the outermost provider, so a fresh client
+  // is genuinely empty here.
+  const cacheWarmAtMountRef = useRef<boolean | null>(null)
+  if (cacheWarmAtMountRef.current === null) {
+    cacheWarmAtMountRef.current = queryClient.getQueryCache().getAll().length > 0
+  }
 
   // Fetch initial connection status
   // Poll while connecting to get progress updates (SSE not established yet)
@@ -97,6 +133,7 @@ export function ConnectionProvider({ children }: { children: ReactNode }) {
   const retryMutation = useMutation({
     mutationFn: retryConnection,
     onMutate: () => {
+      manualRetryPendingRef.current = true
       // Reset SSE active flag - polling can provide state until SSE reconnects
       sseActiveRef.current = false
       // Set connecting state while retrying
@@ -104,7 +141,6 @@ export function ConnectionProvider({ children }: { children: ReactNode }) {
         ...prev,
         state: 'connecting',
         error: undefined,
-        errorType: undefined,
         progressMessage: 'Connecting to cluster...',
       }))
     },
@@ -115,16 +151,94 @@ export function ConnectionProvider({ children }: { children: ReactNode }) {
       queryClient.invalidateQueries()
     },
     onError: (error: Error) => {
-      setConnection(prev => ({
-        ...prev,
-        state: 'disconnected',
-        error: error.message,
-        progressMessage: undefined,
-      }))
+      const retryError = error as ConnectionRetryError
+      setConnection(prev => {
+        if (sseActiveRef.current && prev.state === 'connected') return prev
+        return {
+          ...prev,
+          state: 'disconnected',
+          error: error.message,
+          errorType: retryError.errorType || prev.errorType,
+          progressMessage: undefined,
+        }
+      })
+    },
+    onSettled: () => {
+      manualRetryPendingRef.current = false
     },
   })
+  useEffect(() => {
+    manualRetryPendingRef.current = retryMutation.isPending
+  }, [retryMutation.isPending])
+
+  useEffect(() => {
+    if (connection.state !== 'disconnected' || !shouldAutoRetryConnection(connection.errorType)) {
+      autoRetryDelayRef.current = AUTO_RETRY_INITIAL_DELAY_MS
+      return
+    }
+    let stopped = false
+    let retryTimeout: number | undefined
+
+    const scheduleRetry = () => {
+      retryTimeout = window.setTimeout(() => {
+        if (stopped) return
+        if (manualRetryPendingRef.current || autoRetryInFlightRef.current) {
+          scheduleRetry()
+          return
+        }
+
+        autoRetryInFlightRef.current = true
+        setIsAutoRetrying(true)
+        let recovered = false
+        retryConnection()
+          .then((result) => {
+            if (stopped) return
+            recovered = true
+            autoRetryDelayRef.current = AUTO_RETRY_INITIAL_DELAY_MS
+            sseActiveRef.current = false
+            setConnection(result)
+            queryClient.removeQueries()
+            queryClient.invalidateQueries()
+          })
+          .catch((error: Error) => {
+            if (stopped) return
+            const retryError = error as ConnectionRetryError
+            setConnection(prev => {
+              if (sseActiveRef.current && prev.state === 'connected') return prev
+              return {
+                ...prev,
+                state: 'disconnected',
+                error: error.message || prev.error,
+                errorType: retryError.errorType || prev.errorType,
+                progressMessage: undefined,
+              }
+            })
+            autoRetryDelayRef.current = Math.min(autoRetryDelayRef.current * 2, AUTO_RETRY_MAX_DELAY_MS)
+            // Keep the visible disconnected state until a retry succeeds.
+          })
+          .finally(() => {
+            autoRetryInFlightRef.current = false
+            setIsAutoRetrying(false)
+            if (!stopped && !recovered) {
+              scheduleRetry()
+            }
+          })
+      }, autoRetryDelayRef.current)
+    }
+
+    scheduleRetry()
+
+    return () => {
+      stopped = true
+      if (retryTimeout !== undefined) {
+        window.clearTimeout(retryTimeout)
+      }
+    }
+  }, [connection.errorType, connection.state, queryClient])
 
   const retry = useCallback(() => {
+    if (retryMutation.isPending || autoRetryInFlightRef.current) return
+    manualRetryPendingRef.current = true
     retryMutation.mutate()
   }, [retryMutation])
 
@@ -143,9 +257,20 @@ export function ConnectionProvider({ children }: { children: ReactNode }) {
       return status
     })
 
-    // If we just connected, invalidate queries to fetch fresh data
     if (status.state === 'connected') {
-      queryClient.invalidateQueries()
+      const firstConnect = !hasConnectedRef.current
+      hasConnectedRef.current = true
+      // A reconnect after a drop (cache stale across the gap), or a first connect
+      // onto a client that already carried data at mount (shared across clusters),
+      // refreshes the whole cache. A clean first connect only needs to recover the
+      // bootstrap queries that 503'd while the cluster was still 'connecting'
+      // (status === 'error'); the rest already fetched fresh during 'connecting',
+      // so re-fetching the whole cache there would double-load every endpoint.
+      if (!firstConnect || cacheWarmAtMountRef.current) {
+        queryClient.invalidateQueries()
+      } else {
+        queryClient.invalidateQueries({ predicate: (q) => q.state.status === 'error' })
+      }
     }
   }, [queryClient])
 
@@ -153,7 +278,7 @@ export function ConnectionProvider({ children }: { children: ReactNode }) {
     connection,
     contexts,
     retry,
-    isRetrying: retryMutation.isPending,
+    isRetrying: retryMutation.isPending || isAutoRetrying,
     updateFromSSE,
   }
 

package/src/context/DiagnoseCustomization.tsx

@@ -0,0 +1,93 @@
+// Slot-based injection of a resource-level "Diagnose" action, and of the
+// consent card's trust copy.
+//
+// Lets an embedding host (e.g. Radar Hub) inject a "Diagnose with AI" button
+// into every resource detail action bar — without forking WorkloadView or the
+// shared ResourceActionsBar. The host returns whatever node should render in
+// the action bar's right-aligned universal-actions area, given the resource
+// context.
+//
+// Default (no provider): Radar renders no Diagnose button — OSS stays
+// agent-free.
+import { createContext, useContext, useMemo } from 'react';
+import type { ReactNode } from 'react';
+
+/** Render prop for the resource-level Diagnose action. */
+export type RenderDiagnoseAction = (ctx: {
+  kind: string;
+  namespace: string;
+  name: string;
+  /** Coarse health of the resource (from its status badge), so the entry point can
+   *  adapt: an urgent "Diagnose" on a problem vs. a quiet "ask AI" when fine/unknown. */
+  health?: "problem" | "healthy" | "unknown";
+}) => ReactNode;
+
+/**
+ * Trust copy for the first-run consent card.
+ *
+ * The card makes concrete, checkable claims about *where* the agent runs,
+ * *whose* model account it bills, and *where* the transcript is stored. Those
+ * claims are only true of OSS's bring-your-own-local-CLI agent. A host that
+ * runs the agent anywhere else (Radar Cloud runs it as a sandboxed Job under a
+ * managed key) MUST supply its own copy — shipping OSS's over a different data
+ * flow states the opposite of what happens.
+ *
+ * Radar owns the card's chrome (icon, layout, Approve/Cancel) either way; a
+ * host only replaces the claims.
+ */
+export type DiagnoseConsentCopy = {
+  title: string;
+  body: ReactNode;
+  /** Detail list under the body; each entry is rendered as its own "•" row. */
+  bullets?: ReactNode[];
+  /** Label for the settings link. `null` hides it — for hosts with one fixed
+   *  agent and no isolation choice, where it would open an empty dialog. */
+  settingsLabel?: string | null;
+  approveLabel?: string;
+};
+
+// One context for the whole customization seam — the values are host config
+// set once at mount, so per-value re-render isolation buys nothing.
+export interface DiagnoseCustomization {
+  renderAction: RenderDiagnoseAction | undefined;
+  consentCopy: DiagnoseConsentCopy | undefined;
+  // undefined = default (CustomEvent → Radar's own Settings dialog);
+  // null = hide the settings affordances.
+  onOpenSettings: (() => void) | null | undefined;
+}
+
+const DEFAULTS: DiagnoseCustomization = {
+  renderAction: undefined,
+  consentCopy: undefined,
+  onOpenSettings: undefined,
+};
+
+const DiagnoseCustomizationContext = createContext<DiagnoseCustomization>(DEFAULTS);
+
+export function DiagnoseCustomizationProvider({
+  value,
+  consentCopy,
+  onOpenSettings,
+  children,
+}: {
+  value: RenderDiagnoseAction | undefined;
+  consentCopy?: DiagnoseConsentCopy;
+  /** Where "AI settings" affordances lead. Omit for Radar's own Settings
+   *  dialog; pass `null` to hide them. */
+  onOpenSettings?: (() => void) | null;
+  children: ReactNode;
+}) {
+  const ctx = useMemo(
+    () => ({ renderAction: value, consentCopy, onOpenSettings }),
+    [value, consentCopy, onOpenSettings],
+  );
+  return (
+    <DiagnoseCustomizationContext.Provider value={ctx}>
+      {children}
+    </DiagnoseCustomizationContext.Provider>
+  );
+}
+
+export function useDiagnoseCustomization(): DiagnoseCustomization {
+  return useContext(DiagnoseCustomizationContext);
+}

package/src/context/NavCustomization.tsx

@@ -13,11 +13,86 @@
 import { createContext, useContext } from 'react';
 import type { ReactNode } from 'react';
 
+/**
+ * Per-cluster destinations an embedded host can take over with its own
+ * fleet-scoped pages. See `fleetTakeoverHref`. 'issues' | 'gitops' | 'checks'
+ * are also Radar view names (so route entry redirects too); 'certs' is
+ * card-only (Radar has no certs view).
+ */
+export type FleetTakeoverTarget = 'issues' | 'gitops' | 'checks' | 'certs';
+
 interface NavCustomizationBase {
   /** Replaces Radar's Skyhook/radar logo + wordmark. */
   brandSlot?: ReactNode;
   /** Replaces the ContextSwitcher (kubeconfig-context picker). */
   contextSlot?: ReactNode;
+  /**
+   * When set, a "Compare across clusters" option is added to the Compare
+   * button in resource action bars. The host returns the URL that should
+   * be navigated to (via window.location.assign — typically a hub fleet
+   * route). Standalone Radar omits this and the compare action stays
+   * single-cluster.
+   */
+  crossClusterCompareHref?: (ref: {
+    kind: string;
+    namespace: string;
+    name: string;
+    group?: string;
+  }) => string;
+  /**
+   * Lets an embedded host (e.g. Radar Cloud) take over selected per-cluster
+   * destinations with its OWN fleet pages scoped to this cluster, instead of
+   * Radar rendering them inline. Given a semantic target the host returns the
+   * URL to navigate to, or `undefined`/omits the hook to let Radar render its
+   * own view as usual (standalone OSS does the latter for everything).
+   *
+   * This is how the Home dashboard's "fleet-shaped" cards reach the host's
+   * canonical surfaces rather than a second, diverging per-cluster copy:
+   *   - 'issues'  → the Active Issues panel + cluster-health issues count
+   *   - 'gitops'  → the GitOps controllers card
+   *   - 'checks'  → the Cluster Audit card (and any route to /audit; legacy
+   *                 `clusterChecksHref` folded in here)
+   *   - 'certs'   → the Certificate Health card
+   *
+   * View-shaped targets (issues / gitops / checks) are honored for every entry:
+   * in-app nav (Home cards, ⌘K, "view all") hands straight to the host from
+   * `setMainView` via `onHostNavigate` (smooth same-document hand-off, no
+   * intermediate /<view> mount); a direct /<view> URL (bookmark/deep link)
+   * funnels through a redirect effect that uses `window.location.replace` so
+   * the transient URL stays out of history. 'certs' has no Radar view, so only
+   * the card consults it. `onHostNavigate` is optional — without it everything
+   * falls back to `window.location` (a hard reload).
+   */
+  fleetTakeoverHref?: (target: FleetTakeoverTarget) => string | undefined;
+  /**
+   * @deprecated Superseded by `fleetTakeoverHref('checks')`. Kept so consumers
+   * still on the pre-1.7 hook keep working (App.tsx folds it into the 'checks'
+   * target) — this makes adding `fleetTakeoverHref` an additive, non-breaking
+   * change. Remove in a major release once all consumers have migrated.
+   */
+  clusterChecksHref?: () => string;
+  /**
+   * Optional smooth navigator for host-owned URLs. When the host takes a
+   * destination over (`fleetTakeoverHref`, `crossClusterCompareHref`), Radar
+   * would otherwise hand off via `window.location` — a full document reload
+   * that cold-boots the host (white flash, re-auth, chrome teardown). A host
+   * that can navigate SAME-DOCUMENT (e.g. Radar Cloud's cross-tree swap with a
+   * View Transition) passes this so the hand-off morphs instead of reloading.
+   * Omitted → Radar falls back to `window.location` (hard nav), so standalone
+   * OSS / other hosts are unaffected.
+   */
+  onHostNavigate?: (url: string) => void;
+  /**
+   * Chrome level for embedded hosts. Default ('full', or omitted) renders
+   * Radar's top bar + the view-switcher. 'none' suppresses BOTH — the host
+   * drives view navigation and cluster/namespace scope from its OWN chrome, and
+   * Radar renders just the active view's content full-bleed. Radar Hub uses this
+   * to surface per-cluster views (Topology / Resources / Traffic / Cost) that
+   * don't aggregate to the fleet as native cloud destinations under one chrome,
+   * gated by a cluster picker — instead of a second, redundant in-cluster nav.
+   * Only meaningful with `embedded: true`.
+   */
+  chrome?: 'full' | 'none';
 }
 
 /**

package/src/context/TimelineSource.tsx

@@ -0,0 +1,50 @@
+// Provides the active timeline data source to the timeline wrappers.
+//
+// Radar's binary never sets a source, so the default is the local event store
+// (GET {apiBase}/changes) — unchanged OSS behavior. A host embedding RadarApp
+// behind a proxy that serves retained history passes `timelineSource` on
+// RadarApp; this provider resolves it once and hands the timeline wrappers a
+// source-agnostic `useEvents` hook.
+//
+// Default (no provider): the local source, so components work standalone.
+import { createContext, useContext, useMemo, Fragment } from 'react'
+import type { ReactNode } from 'react'
+import {
+  localSource,
+  resolveTimelineSource,
+  type TimelineSource,
+  type TimelineSourceConfig,
+} from '../api/timelineSource'
+
+const TimelineSourceContext = createContext<TimelineSource>(localSource)
+
+export function TimelineSourceProvider({
+  config,
+  children,
+}: {
+  config?: TimelineSourceConfig
+  children: ReactNode
+}) {
+  // Resolve from the config's two fields, not the object: a host passing a
+  // fresh config literal each render must not re-resolve the source.
+  const mode = config?.mode
+  const maxRangeDays = config?.maxRangeDays
+  const source = useMemo(
+    () => resolveTimelineSource(mode === 'retained' ? { mode, maxRangeDays } : undefined),
+    [mode, maxRangeDays],
+  )
+  return (
+    <TimelineSourceContext.Provider value={source}>
+      {/* Key the subtree on the source mode. `useEvents` is a hook, and the local
+          vs retained sources are different hook functions with different internal
+          hook counts; a host flipping `timelineSource` mode mid-session would
+          otherwise corrupt React's hook order. Remounting on the flip keeps the
+          hook sequence consistent. */}
+      <Fragment key={mode ?? 'local'}>{children}</Fragment>
+    </TimelineSourceContext.Provider>
+  )
+}
+
+export function useTimelineSource(): TimelineSource {
+  return useContext(TimelineSourceContext)
+}

package/src/contexts/CapabilitiesContext.tsx

@@ -1,6 +1,6 @@
 import { createContext, useContext, useMemo, ReactNode } from 'react'
 import { useCapabilities, useNamespaceCapabilities } from '../api/client'
-import type { Capabilities, ResourcePermissions } from '../types'
+import { OPTIONAL_RESOURCE_KINDS, type Capabilities, type ResourcePermissions } from '../types'
 
 // Default capabilities for local development (when running locally, all features work)
 const defaultCapabilities: Capabilities = {
@@ -12,6 +12,12 @@ const defaultCapabilities: Capabilities = {
   secretsUpdate: true,
   helmWrite: true,
   nodeWrite: true,
+  workloadWrites: {
+    deployments: true,
+    daemonSets: true,
+    statefulSets: true,
+    rollouts: true,
+  },
   mcpEnabled: true,
   // Default to 'local' for the loading window so the UI renders the
   // OSS standalone shape until /api/capabilities resolves. Both
@@ -30,6 +36,12 @@ const restrictedCapabilities: Capabilities = {
   secretsUpdate: false,
   helmWrite: false,
   nodeWrite: false,
+  workloadWrites: {
+    deployments: false,
+    daemonSets: false,
+    statefulSets: false,
+    rollouts: false,
+  },
   mcpEnabled: false,
   deployment: { mode: 'local' },
 }
@@ -79,6 +91,14 @@ export function useCanPortForward(): boolean {
   return useContext(CapabilitiesContext).portForward
 }
 
+// True when Radar runs as a local binary (live port-forward is possible). When
+// false (in-cluster / Radar Cloud) a live forward can't bind a usable local
+// listener, so the UI offers a copy-paste `kubectl port-forward` command instead.
+// Defaults to local during the capabilities-loading window (see defaultCapabilities).
+export function useIsLocalDeployment(): boolean {
+  return useContext(CapabilitiesContext).deployment?.mode === 'local'
+}
+
 export function useCanViewSecrets(): boolean {
   return useContext(CapabilitiesContext).secrets
 }
@@ -100,12 +120,17 @@ export function useResourcePermissions(): ResourcePermissions | undefined {
   return useContext(CapabilitiesContext).resources
 }
 
+// See OPTIONAL_RESOURCE_KINDS for why these are filtered.
+function isOptionalKind(kind: string): boolean {
+  return (OPTIONAL_RESOURCE_KINDS as ReadonlyArray<string>).includes(kind)
+}
+
 export function useRestrictedResources(): string[] {
   const resources = useContext(CapabilitiesContext).resources
   return useMemo(() => {
     if (!resources) return []
     return Object.entries(resources)
-      .filter(([, allowed]) => !allowed)
+      .filter(([kind, allowed]) => !allowed && !isOptionalKind(kind))
       .map(([kind]) => kind)
   }, [resources])
 }
@@ -113,13 +138,11 @@ export function useRestrictedResources(): string[] {
 export function useHasLimitedAccess(): boolean {
   const resources = useContext(CapabilitiesContext).resources
   if (!resources) return false
-  return Object.values(resources).some(allowed => !allowed)
+  return Object.entries(resources).some(([kind, allowed]) => !allowed && !isOptionalKind(kind))
 }
 
-// Namespace-scoped capability hooks: lazily re-check exec/logs/portForward
-// scoped to a specific namespace when global RBAC checks denied them.
-// Falls back to global capability values while the namespace check is loading
-// or when all capabilities are already granted.
+// Namespace-scoped capability hooks. A concrete namespace gets its own
+// capability check; callers use global capability values until it resolves.
 export function useNamespacedCapabilities(namespace: string | undefined) {
   const globalCaps = useContext(CapabilitiesContext)
   const { data: nsCaps, error } = useNamespaceCapabilities(namespace, globalCaps)
@@ -132,5 +155,6 @@ export function useNamespacedCapabilities(namespace: string | undefined) {
     canExec: nsCaps?.exec ?? globalCaps.exec,
     canViewLogs: nsCaps?.logs ?? globalCaps.logs,
     canPortForward: nsCaps?.portForward ?? globalCaps.portForward,
-  }), [globalCaps.exec, globalCaps.logs, globalCaps.portForward, nsCaps])
+    workloadWrites: nsCaps?.workloadWrites ?? globalCaps.workloadWrites,
+  }), [globalCaps.exec, globalCaps.logs, globalCaps.portForward, globalCaps.workloadWrites, nsCaps])
 }

package/src/filter/FilterLocationBridge.tsx

@@ -0,0 +1,30 @@
+import { useCallback, useMemo, useRef, type ReactNode } from 'react';
+import { useSearchParams } from 'react-router-dom';
+import { FilterLocationProvider, type FilterLocation } from '@skyhook-io/k8s-ui';
+
+// Adapts OSS Radar's react-router search params to the app-agnostic
+// FilterLocation seam that @skyhook-io/k8s-ui's useFilterState reads. Mounted
+// once inside the router; every list view's shared filter state flows through
+// it, keeping the URL the single source of truth. (Radar Hub provides its own
+// bridge over its router — k8s-ui itself never depends on react-router.)
+export function FilterLocationBridge({ children }: { children: ReactNode }) {
+  const [searchParams, setSearchParams] = useSearchParams();
+
+  // React Router's functional updater is NOT state-queued: two updates in one
+  // tick can both read the same params and clobber. Advance a ref synchronously
+  // so successive filter changes (e.g. toggling two facets fast) compose.
+  const latest = useRef(searchParams);
+  latest.current = searchParams;
+
+  const update = useCallback<FilterLocation['update']>(
+    (updater, opts) => {
+      const next = updater(new URLSearchParams(latest.current));
+      latest.current = next;
+      setSearchParams(next, opts);
+    },
+    [setSearchParams],
+  );
+
+  const value = useMemo<FilterLocation>(() => ({ searchParams, update }), [searchParams, update]);
+  return <FilterLocationProvider value={value}>{children}</FilterLocationProvider>;
+}

package/src/hooks/useClusterLoadState.ts

@@ -0,0 +1,73 @@
+import { useEffect, useMemo, useRef } from 'react'
+import { useQueryClient } from '@tanstack/react-query'
+import { useDashboard, type DashboardResponse } from '../api/client'
+import { dashboardClusterLoadState, idleClusterLoadState, type ClusterLoadState } from '../types/clusterLoadState'
+
+interface UseClusterLoadStateArgs {
+  namespaces: string[]
+  mainView: string
+  chromeless: boolean
+  contentReady: boolean
+  onClusterLoadStateChange?: (state: ClusterLoadState) => void
+}
+
+interface UseClusterLoadStateResult {
+  clusterLoadState: ClusterLoadState
+  showHomeClusterLoadFallback: boolean
+  // The dashboard's first fetch is still in flight (no data yet). In this phase a
+  // center "Loading dashboard…" splash is shown, so the topbar label would be
+  // redundant — callers can suppress it and keep just the status dot.
+  clusterLoadInitial: boolean
+}
+
+// Tracks cluster-data warmup (deferred/partial dashboard load) once the main
+// connection is usable. Standalone / embedded-with-chrome render it in Radar's
+// topbar; chromeless hosts (Radar Hub) receive it via onClusterLoadStateChange;
+// a chromeless host without a callback gets a fallback row on Home.
+export function useClusterLoadState({
+  namespaces,
+  mainView,
+  chromeless,
+  contentReady,
+  onClusterLoadStateChange,
+}: UseClusterLoadStateArgs): UseClusterLoadStateResult {
+  const showHomeClusterLoadFallback = chromeless && !onClusterLoadStateChange && mainView === 'home'
+  const needsClusterLoadState =
+    contentReady && (!chromeless || Boolean(onClusterLoadStateChange) || mainView === 'home')
+
+  // Off Home, stop observing once warmup has settled so we don't keep refetching
+  // /dashboard on other views. `enabled: false` makes the observer inactive,
+  // which also drops it from the SSE-driven invalidateQueries(['dashboard'])
+  // refetches — a stopped refetchInterval alone would not. Home stays live via
+  // HomeView's own observer; returning Home or changing scope re-arms, since
+  // `enabled` is derived from the current cached (re)load state.
+  const queryClient = useQueryClient()
+  const cached = queryClient.getQueryState<DashboardResponse>(['dashboard', namespaces])
+  const warmupSettled =
+    cached?.status === 'error' || (cached?.data != null && !dashboardClusterLoadState(cached.data).loading)
+  const enabled = needsClusterLoadState && (mainView === 'home' || !warmupSettled)
+
+  const { data, isPending, isError } = useDashboard(namespaces, { enabled })
+
+  const clusterLoadState = useMemo<ClusterLoadState>(() => {
+    if (!needsClusterLoadState || isError) return idleClusterLoadState
+    if (data) return dashboardClusterLoadState(data)
+    if (isPending) return { loading: true, message: 'Loading dashboard…', pendingKinds: [] }
+    return idleClusterLoadState
+  }, [needsClusterLoadState, isError, data, isPending])
+
+  // Ref the host callback so an unmemoized prop doesn't churn emits, and so the
+  // unmount reset fires only on real unmount (not on every callback identity change).
+  const emitRef = useRef(onClusterLoadStateChange)
+  useEffect(() => {
+    emitRef.current = onClusterLoadStateChange
+  })
+  useEffect(() => {
+    emitRef.current?.(clusterLoadState)
+  }, [clusterLoadState])
+  useEffect(() => () => emitRef.current?.(idleClusterLoadState), [])
+
+  const clusterLoadInitial = clusterLoadState.loading && !data
+
+  return { clusterLoadState, showHomeClusterLoadFallback, clusterLoadInitial }
+}