@skyhook-io/radar-app 1.14.5 → 1.15.0

package/src/api/client.ts

@@ -1,4 +1,7 @@
+import { canonicalResourceGroup } from '@skyhook-io/k8s-ui/utils/api-resources'
+import { knownKindForPluralWithGroup, pluralToKind } from '@skyhook-io/k8s-ui/utils/navigation'
 import { useEffect, useRef } from 'react'
+import type { KueueAdmissionResponse } from '@skyhook-io/k8s-ui/types/scheduling'
 import type {
   AppHistory,
   AppRow,
@@ -56,7 +59,7 @@ import type {
 } from '../types'
 import type { GitOpsOperationResponse } from '../types/gitops'
 import { apiUrl, getApiBase, getAuthHeaders, getCredentialsMode, getBasename, routePath, stripBasename } from './config'
-import { apiVersionToGroup, pluralToKind } from '../utils/navigation'
+import { apiVersionToGroup } from '../utils/navigation'
 import type { DeploymentMode } from '../types'
 
 // Auto-refresh cadences (ms) — named constants for each polled hook's
@@ -723,10 +726,14 @@ export function useResourceAudit(
   kind: string,
   namespace: string,
   name: string,
+  group?: string,
 ) {
+  const params = new URLSearchParams();
+  if (group) params.set("group", group);
+  const query = params.toString();
   return useQuery<AuditFinding[]>({
-    queryKey: ["audit", "resource", kind, namespace, name],
-    queryFn: () => fetchJSON(`/audit/resource/${kind}/${namespace}/${name}`),
+    queryKey: ["audit", "resource", kind, group ?? "", namespace, name],
+    queryFn: () => fetchJSON(`/audit/resource/${kind}/${namespace}/${name}${query ? `?${query}` : ""}`),
     staleTime: 30000,
   });
 }
@@ -1597,6 +1604,37 @@ export function useClusterInfo() {
 export type InstallMethod =
   "homebrew" | "krew" | "scoop" | "direct" | "desktop";
 
+export interface WhatsNewState {
+  currentVersion: string;
+  // "server": seenVersion / priorInstall are authoritative (local installs).
+  // "browser": the client keeps its own record (in-cluster).
+  storage: "server" | "browser";
+  seenVersion?: string;
+  priorInstall?: boolean;
+}
+
+export function useWhatsNewState(enabled: boolean) {
+  return useQuery<WhatsNewState>({
+    queryKey: ["whats-new", getApiBase()],
+    queryFn: () => fetchJSON("/whats-new"),
+    enabled,
+    // Refetched on focus (the app default is off), so another tab's
+    // acknowledgment clears this tab's dot.
+    staleTime: 0,
+    refetchOnWindowFocus: true,
+    retry: false,
+  });
+}
+
+export async function markWhatsNewSeen(version: string): Promise<void> {
+  const response = await apiFetch(`${getApiBase()}/whats-new/seen`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ version }),
+  });
+  if (!response.ok) throw new ApiError(`HTTP ${response.status}`, response.status);
+}
+
 export interface VersionInfo {
   currentVersion: string;
   latestVersion?: string;
@@ -2808,30 +2846,6 @@ export function useChanges(options: UseChangesOptions = {}) {
   });
 }
 
-// Children changes for a parent workload (e.g., ReplicaSets and Pods under a Deployment)
-export function useResourceChildren(
-  kind: string,
-  namespace: string,
-  name: string,
-  timeRange: TimeRange = "1h",
-) {
-  const sinceDate = getTimeRangeDate(timeRange);
-  const params = new URLSearchParams();
-  if (sinceDate) {
-    params.set("since", sinceDate.toISOString());
-  }
-
-  return useQuery<TimelineEvent[]>({
-    queryKey: ["resource-children", kind, namespace, name, timeRange],
-    queryFn: () =>
-      fetchJSON(
-        `/changes/${kind}/${namespace}/${name}/children?${params.toString()}`,
-      ),
-    enabled: Boolean(kind && namespace && name),
-    refetchInterval: 15000, // Refresh every 15 seconds
-  });
-}
-
 export interface ResourceEventsResult {
   k8sEvents: TimelineEvent[];
   updates: TimelineEvent[];
@@ -2850,10 +2864,12 @@ export function useResourceEvents(
   kind: string,
   namespace: string,
   name: string,
+  group?: string,
 ): ResourceEventsResult {
   // The timeline store keys events by their K8s Kind (singular PascalCase, e.g. "Pod"),
   // but callers pass the URL-form kind ("pods").
-  const singularKind = pluralToKind(kind);
+  const singularKind = knownKindForPluralWithGroup(kind, group ?? "") ?? pluralToKind(kind);
+  const resolvedGroup = canonicalResourceGroup(singularKind, group);
   const since = new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString();
 
   // Include managed resources — when viewing a specific resource (e.g. a Pod owned
@@ -2864,18 +2880,19 @@ export function useResourceEvents(
     p.set("namespace", namespace);
     p.set("kind", singularKind);
     p.set("name", name);
+    if (resolvedGroup !== undefined) p.set("group", resolvedGroup);
     p.set("include_managed", "true");
     p.set("since", since);
     return p;
   };
 
-  const enabled = Boolean(kind && namespace && name);
+  const enabled = Boolean(kind && namespace && name && resolvedGroup !== undefined);
 
   // K8s events: high limit so the full set is always returned. The number of
   // distinct K8s events per resource is naturally bounded — kubelet/controllers
   // dedupe via Reason+InvolvedObject and bump count.
   const k8sQuery = useQuery<TimelineEvent[]>({
-    queryKey: ["resource-events", "k8s", singularKind, namespace, name],
+    queryKey: ["resource-events", "k8s", singularKind, resolvedGroup, namespace, name],
     queryFn: async () => {
       const params = baseParams();
       params.set("sources", "k8s_event");
@@ -2889,7 +2906,7 @@ export function useResourceEvents(
   // Resource updates (informer diffs + historical): bounded so a flapping
   // resource doesn't return an unbounded payload.
   const updatesQuery = useQuery<TimelineEvent[]>({
-    queryKey: ["resource-events", "updates", singularKind, namespace, name],
+    queryKey: ["resource-events", "updates", singularKind, resolvedGroup, namespace, name],
     queryFn: async () => {
       const params = baseParams();
       params.set("sources", "informer,historical");
@@ -3272,9 +3289,9 @@ export type PrometheusTimeRange =
   "10m" | "30m" | "1h" | "3h" | "6h" | "12h" | "24h" | "48h" | "7d" | "14d";
 
 // PVC usage at a moment in time, derived from kubelet_volume_stats_*.
-// HasData=false silently indicates the CSI driver doesn't report or Prom
-// isn't scraping kubelet endpoints — UI should hide the gauge in that case.
 export interface PrometheusPVCUsage {
+  // Hub packages the frontend independently from per-cluster agent upgrades.
+  status?: "available" | "no_series" | "invalid_data" | "query_failed";
   namespace: string;
   name: string;
   used: number;
@@ -3364,6 +3381,7 @@ export interface RightsizingScanCoverage {
   workloadsWithData: number;
   batches: number;
   completedBatches: number;
+  attemptedBatches: number;
   restrictedKinds?: string[];
   unavailableKinds?: string[];
   partiallyCachedKinds?: string[];
@@ -3371,6 +3389,11 @@ export interface RightsizingScanCoverage {
 }
 
 export interface RightsizingScanResponse {
+  scanId: string;
+  scanStatus: 'running' | 'finished' | 'cancelled' | 'timed_out';
+  deadlineAt: string;
+  expiresAt?: string;
+  pollAfterSeconds?: number;
   state: RightsizingScanState;
   scannedAt: string;
   window: string;
@@ -3629,7 +3652,6 @@ export function usePrometheusClusterMetrics(
   });
 }
 
-// Fetch PVC usage. hasData=false when no series — UI should hide the gauge.
 export function usePrometheusPVCUsage(
   namespace: string,
   name: string,
@@ -3640,7 +3662,10 @@ export function usePrometheusPVCUsage(
     queryFn: () => fetchJSON(`/prometheus/pvc/${namespace}/${name}`),
     enabled: enabled && Boolean(namespace && name),
     staleTime: 60000,
-    refetchInterval: 120000,
+    refetchInterval: (query) =>
+      isForbiddenError(query.state.error) ? false : 120000,
+    retry: (failureCount, error) =>
+      !isForbiddenError(error) && failureCount < 1,
   });
 }
 
@@ -3663,55 +3688,83 @@ export function usePrometheusRightsizing(
 
 const RIGHTSIZING_SCAN_CACHE_TIME = 5 * 60 * 1000;
 
-export function getRightsizingScanCacheConfig(
-  namespaces: string[],
-  context = "",
-): {
-  namespaceKey: string;
-  queryKey: readonly ["prometheus-rightsizing-scan", string, string];
-  queryFn: typeof skipToken;
-  gcTime: number;
-} {
-  const namespaceKey = [...namespaces].sort().join(",");
+export function getRightsizingScanCacheConfig(namespaces: string[], context = "", identity = "") {
+  const namespaceKey = [...new Set(namespaces)].sort().join(",");
   return {
     namespaceKey,
-    queryKey: ["prometheus-rightsizing-scan", context, namespaceKey] as const,
-    queryFn: skipToken,
+    queryKey: ["prometheus-rightsizing-scan", getApiBase(), identity, context, namespaceKey] as const,
     gcTime: RIGHTSIZING_SCAN_CACHE_TIME,
   };
 }
 
-// A fleet rightsizing scan is intentionally manual. It can query seven days of
-// Prometheus history for many containers, so navigation alone must never run it.
+// Navigation retrieves a retained scan; only an explicit POST starts work.
 export function useRightsizingScan(namespaces: string[], context = "") {
   const queryClient = useQueryClient();
-  const { namespaceKey, ...snapshotOptions } = getRightsizingScanCacheConfig(
-    namespaces,
-    context,
-  );
-  const scanScope = { namespaceKey, queryKey: snapshotOptions.queryKey };
-  const snapshot = useQuery<RightsizingScanResponse>(snapshotOptions);
+  const { data: auth } = useAuthMe();
+  const identity = JSON.stringify([auth?.username, [...(auth?.groups ?? [])].sort()]);
+  const { namespaceKey, ...cache } = getRightsizingScanCacheConfig(namespaces, context, identity);
+  const scope = JSON.stringify(cache.queryKey);
+  const currentScope = useRef(scope);
+  currentScope.current = scope;
+  const previous = useRef<{ scope: string; result: RightsizingScanResponse } | null>(null);
+  const params = new URLSearchParams();
+  if (namespaceKey) params.set('namespaces', namespaceKey);
+  const path = `/prometheus/rightsizing/scan?${params}`;
+  const snapshot = useQuery<RightsizingScanResponse | null>({
+    ...cache,
+    enabled: Boolean(context && auth),
+    queryFn: ({ signal }) => fetchJSON(path, { signal }),
+    refetchOnMount: 'always',
+    retry: (count, error) => !(error instanceof ApiError && [403, 404, 409].includes(error.status)) && count < 1,
+    refetchInterval: (query) => !query.state.error && query.state.data?.scanStatus === 'running' ? 5000 : false,
+  });
   const mutation = useMutation({
-    mutationFn: async (startedScope: typeof scanScope) => {
-      const params = new URLSearchParams();
-      if (startedScope.namespaceKey)
-        params.set("namespaces", startedScope.namespaceKey);
-      const query = params.toString();
-      return fetchJSON<RightsizingScanResponse>(
-        `/prometheus/rightsizing/scan${query ? `?${query}` : ""}`,
-        {
-          method: "POST",
-        },
-      );
+    mutationFn: async (started: { scope: string; path: string; queryKey: typeof cache.queryKey; previousScanId?: string }) => {
+      await queryClient.cancelQueries({ queryKey: started.queryKey });
+      if (currentScope.current !== started.scope) throw new Error('Scan scope changed; run the scan again.');
+      return fetchJSON<RightsizingScanResponse>(started.path, { method: 'POST' });
+    },
+    onSuccess: (result, started) => queryClient.setQueryData(started.queryKey, result),
+    onError: (_error, started) => {
+      // A lost POST response may still have started a scan. Read before retrying.
+      void queryClient.invalidateQueries({ queryKey: started.queryKey });
+    },
+  });
+  const stop = useMutation({
+    mutationFn: async (started: { id: string; scope: string; queryKey: typeof cache.queryKey }) => {
+      await queryClient.cancelQueries({ queryKey: started.queryKey });
+      if (currentScope.current !== started.scope) throw new Error('Scan scope changed.');
+      return fetchJSON<RightsizingScanResponse>(`/prometheus/rightsizing/scan/${encodeURIComponent(started.id)}`, { method: 'DELETE' });
     },
-    onSuccess: (result, startedScope) =>
-      queryClient.setQueryData(startedScope.queryKey, result),
+    onSuccess: (result, started) => queryClient.setQueryData(started.queryKey, result),
   });
+  const inaccessible = snapshot.error instanceof ApiError && [403, 404, 409].includes(snapshot.error.status);
+  const current = inaccessible ? null : snapshot.data;
+  useEffect(() => {
+    if (inaccessible) {
+      previous.current = null;
+      queryClient.setQueryData(cache.queryKey, null);
+    } else if (current && current.coverage.workloadsEvaluated > 0) {
+      previous.current = { scope, result: current };
+    }
+  }, [current, inaccessible, scope, queryClient, cache.queryKey]);
+  const showingPrevious = current?.scanStatus === 'running' && current.coverage.workloadsEvaluated === 0 && previous.current?.scope === scope;
+  const startRecovered = current && current.scanId !== mutation.variables?.previousScanId;
+  const stopRecovered = current && (current.scanId !== stop.variables?.id || current.scanStatus !== 'running');
   return {
-    ...mutation,
-    data: snapshot.data,
-    mutate: () => mutation.mutate(scanScope),
-    mutateAsync: () => mutation.mutateAsync(scanScope),
+    data: showingPrevious ? previous.current!.result : current,
+    progress: current,
+    showingPrevious,
+    isStarting: mutation.isPending,
+    isPending: mutation.isPending || current?.scanStatus === 'running',
+    isLoading: snapshot.isLoading,
+    statusError: snapshot.error,
+    error: snapshot.error || (stop.variables?.scope === scope && !stopRecovered ? stop.error : null) || (mutation.variables?.scope === scope && !startRecovered ? mutation.error : null),
+    reset: () => { mutation.reset(); stop.reset(); },
+    mutateAsync: () => mutation.mutateAsync({ scope, path, queryKey: cache.queryKey, previousScanId: current?.scanId }),
+    retryStatus: () => snapshot.refetch(),
+    stop: () => { if (!mutation.isPending && current?.scanStatus === 'running') stop.mutate({ id: current.scanId, scope, queryKey: cache.queryKey }); },
+    isStopping: stop.isPending,
   };
 }
 
@@ -6443,6 +6496,18 @@ export function useContexts() {
   });
 }
 
+// Where a remote Argo Application or Flux object (spec.kubeConfig) deploys:
+// the destination's host for display, and the kubeconfig contexts that reach it.
+export function useGitOpsDestination(kind: string, namespace: string, name: string, enabled: boolean) {
+  return useQuery<{ server: string; contexts: string[] }>({
+    queryKey: ["gitops-destination", kind, namespace, name],
+    queryFn: () => fetchJSON(`/gitops/destination/${encodeURIComponent(kind)}/${encodeURIComponent(namespace)}/${encodeURIComponent(name)}`),
+    enabled,
+    staleTime: 60000,
+    retry: false,
+  });
+}
+
 // Session counts for context switch confirmation
 export interface SessionCounts {
   portForwards: number;
@@ -6737,6 +6802,8 @@ export function useImageFilesystem(
 // Response from workload pods endpoint
 export interface WorkloadPodsResponse {
   pods: WorkloadPodInfo[];
+  total: number;
+  truncated: boolean;
 }
 
 // Response from workload logs endpoint (non-streaming)
@@ -6754,10 +6821,12 @@ export interface WorkloadLogsResponse {
 }
 
 export interface WorkloadRun {
+  group: string;
   kind: string;
   namespace: string;
   name: string;
   phase: string;
+  deleting?: boolean;
   active: boolean;
   startedAt?: string;
   finishedAt?: string;
@@ -6771,6 +6840,7 @@ export interface WorkloadRun {
   parallelism?: number;
   progress?: string;
   template?: string;
+  jobset?: JobSetMember;
   launcher?: {
     kind: string;
     namespace?: string;
@@ -6784,17 +6854,51 @@ export interface WorkloadRun {
   podPending?: number;
 }
 
+export interface JobSetMember {
+  replicatedJob?: string;
+  replicatedJobReplicas?: string;
+  jobIndex?: string;
+  globalReplicas?: string;
+  globalIndex?: string;
+  groupName?: string;
+  groupReplicas?: string;
+  groupIndex?: string;
+  restartAttempt?: string;
+  jobRestartAttempt?: string;
+}
+
 export interface WorkloadRunsResponse {
+  collection: "runs" | "members";
+  filteredTotal?: number;
+  selected?: WorkloadRun;
   runs: WorkloadRun[];
+  total: number;
+  truncated: boolean;
 }
 
 // Fetch pods for a workload
-export function useWorkloadPods(kind: string, namespace: string, name: string) {
+export function useWorkloadPods(
+  kind: string,
+  namespace: string,
+  name: string,
+  options?: { limit?: number; refetchInterval?: number | false; ownerUID?: string; nodeType?: string; workerGroup?: string },
+) {
+  const limit = options?.limit;
+  const params = new URLSearchParams();
+  if (limit) params.set('limit', String(limit));
+  for (const key of ['ownerUID', 'nodeType', 'workerGroup'] as const) {
+    if (options?.[key]) params.set(key, options[key]);
+  }
+  const queryString = params.size ? `?${params}` : '';
+  const ownerKey = options?.ownerUID ? [options.ownerUID, options.nodeType ?? '', options.workerGroup ?? ''] : [];
   return useQuery<WorkloadPodsResponse>({
-    queryKey: ["workload-pods", kind, namespace, name],
-    queryFn: () => fetchJSON(`/workloads/${kind}/${namespace}/${name}/pods`),
+    queryKey: ["workload-pods", kind, namespace, name, limit ?? 0, ...ownerKey],
+    queryFn: () =>
+      fetchJSON(`/workloads/${kind}/${namespace}/${name}/pods${queryString}`),
     enabled: Boolean(kind && namespace && name),
     staleTime: 10000, // 10 seconds - pods can change
+    refetchInterval: options?.refetchInterval ?? false,
+    retry: options?.ownerUID ? (count, error) => !(error instanceof ApiError && error.status === 409) && count < 2 : undefined,
   });
 }
 
@@ -6803,16 +6907,22 @@ export function useWorkloadRuns(
   namespace: string,
   name: string,
   enabled = true,
-  options?: { refetchActive?: boolean; clusterScoped?: boolean },
+  options?: { refetchActive?: boolean; clusterScoped?: boolean; role?: string; search?: string; state?: string; selected?: string },
 ) {
   const clusterScoped = options?.clusterScoped ?? false;
   const ns = clusterScoped ? "_" : namespace;
   const params = new URLSearchParams();
   if (clusterScoped) params.set("clusterScoped", "true");
+  for (const key of ["role", "search", "state", "selected"] as const) { if (options?.[key]) params.set(key, options[key]); }
   const queryString = params.toString();
 
   return useQuery<WorkloadRunsResponse>({
-    queryKey: ["workload-runs", kind, namespace, name, clusterScoped],
+    queryKey: ["workload-runs", kind, namespace, name, clusterScoped, options?.role ?? '', options?.search ?? '', options?.state ?? '', options?.selected ?? ''],
+    placeholderData: (previous, query) => {
+      if (previous?.collection !== 'members') return undefined
+      const identity = ["workload-runs", kind, namespace, name, clusterScoped, options?.role ?? '', options?.search ?? '', options?.state ?? '']
+      return identity.every((value, index) => query?.queryKey[index] === value) ? previous : undefined
+    },
     queryFn: () =>
       fetchJSON(
         `/workloads/${kind}/${ns}/${name}/runs${queryString ? `?${queryString}` : ""}`,
@@ -6821,11 +6931,29 @@ export function useWorkloadRuns(
     staleTime: 10000,
     refetchInterval: options?.refetchActive
       ? (query) =>
-          query.state.data?.runs?.some((run) => run.active) ? 5000 : 30000
+          query.state.data?.selected?.active || query.state.data?.runs?.some((run) => run.active) ? 5000 : 30000
       : false,
   });
 }
 
+export function useKueueAdmission(namespace: string, name: string, uid: string | undefined, options?: { isJob?: boolean; isRayJob?: boolean; hinted?: boolean; terminal?: boolean }) {
+  const group = options?.isRayJob ? 'ray.io' : options?.isJob ? 'batch' : 'jobset.x-k8s.io'
+  const kind = options?.isRayJob ? 'rayjobs' : options?.isJob ? 'jobs' : 'jobsets'
+  return useQuery<KueueAdmissionResponse>({
+    queryKey: ['kueue-admission', group, kind, namespace, name, uid],
+    queryFn: () => fetchJSON(`/kueue/admission/${kind}/${encodeURIComponent(namespace)}/${encodeURIComponent(name)}?group=${group}`),
+    enabled: Boolean(namespace && name && uid),
+    staleTime: 5000,
+    refetchInterval: (query) => {
+      if (query.state.error instanceof ApiError && query.state.error.status < 500) return false
+      if (query.state.data?.uid === uid && query.state.data?.installed === false) return false
+      if ((options?.isJob || options?.isRayJob) && (options.terminal || (!options.hinted && !query.state.data?.workloads.length))) return 30000
+      return 5000
+    },
+    retry: (count, error) => !(error instanceof ApiError && error.status < 500) && count < 2,
+  })
+}
+
 // Fetch logs for a workload (non-streaming)
 export function useWorkloadLogs(
   kind: string,
@@ -7119,3 +7247,64 @@ export function useDiagnostics(enabled: boolean) {
     gcTime: 0,
   });
 }
+
+export interface JobSetUsage {
+  runningPods: number
+  reportingPods: number
+  stalePods: number
+  cpu: number | null
+  memory: number | null
+  cpuRequest: number
+  memoryRequest: number
+  observedAt?: string
+  extendedRequests?: Record<string, string>
+}
+export interface JobSetResources {
+  uid: string
+  total: JobSetUsage
+  members: Record<string, JobSetUsage>
+  source: string
+  unavailable?: string
+}
+export function useJobSetResources(namespace: string, name: string, uid: string | undefined, options: { role: string; search: string; state: string }) {
+  const params = new URLSearchParams()
+  for (const key of ["role", "search", "state"] as const) if (options[key]) params.set(key, options[key])
+  return useQuery<JobSetResources>({
+    queryKey: ['jobset-resources', namespace, name, uid, params.toString()],
+    queryFn: ({ signal }) => fetchJSON(`/jobsets/${namespace}/${name}/resources?${params}`, { signal }),
+    enabled: Boolean(namespace && name && uid),
+    staleTime: 25000,
+    refetchInterval: 30000,
+    retry: false,
+  })
+}
+
+
+export interface KueueProvisioningResponse {
+  uid: string
+  installed: boolean
+  total: number
+  truncated: boolean
+  requests: Array<{
+    apiVersion: string
+    kind: string
+    metadata: { name: string; namespace: string; uid: string; generation?: number; creationTimestamp?: string; deletionTimestamp?: string }
+    spec: { provisioningClassName: string }
+    status?: { conditions: Array<{ type: string; status: string; reason?: string; message?: string; observedGeneration?: number }> }
+  }>
+}
+
+export function useKueueProvisioning(namespace: string, name: string, uid: string | undefined, enabled: boolean) {
+  return useQuery<KueueProvisioningResponse>({
+    queryKey: ['kueue-provisioning', namespace, name, uid],
+    queryFn: () => fetchJSON(`/kueue/provisioning/${encodeURIComponent(namespace)}/${encodeURIComponent(name)}`),
+    enabled: enabled && Boolean(namespace && name && uid),
+    staleTime: 5000,
+    refetchInterval: query => {
+      if (query.state.error instanceof ApiError && query.state.error.status < 500) return false
+      if (query.state.data?.uid === uid && query.state.data?.installed === false) return false
+      return 10000
+    },
+    retry: (count, error) => !(error instanceof ApiError && error.status < 500) && count < 2,
+  })
+}

package/src/api/preferences.test.ts

@@ -0,0 +1,54 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+describe('preference persistence by installation', () => {
+  beforeEach(() => { vi.resetModules() })
+  afterEach(() => { vi.unstubAllGlobals() })
+
+  it('keeps shared OSS theme and pins in the browser without writing the server', async () => {
+    const fetchMock = vi.fn().mockResolvedValue(new Response(JSON.stringify({ preferenceStorage: 'browser' })))
+    vi.stubGlobal('fetch', fetchMock)
+    const { persistPreferences } = await import('./preferences')
+    await persistPreferences({ theme: 'light' })
+    await persistPreferences({ pinnedKinds: [{ name: 'pods', kind: 'Pod', group: '' }] })
+    expect(fetchMock).toHaveBeenCalledTimes(1)
+    expect(fetchMock.mock.calls[0][0]).toBe('/api/settings')
+    expect(fetchMock.mock.calls[0][1].method).toBeUndefined()
+  })
+
+  it('preserves local and Cloud persistence through configured API helpers', async () => {
+    const fetchMock = vi.fn().mockImplementation(async () => new Response('{}'))
+    vi.stubGlobal('fetch', fetchMock)
+    const config = await import('./config')
+    config.setApiBase('/c/example/api')
+    config.setAuthHeadersProvider(() => ({ Authorization: 'test-header' }))
+    config.setCredentialsMode('include')
+    const { persistPreferences } = await import('./preferences')
+    await persistPreferences({ theme: 'light' })
+    expect(fetchMock).toHaveBeenLastCalledWith('/c/example/api/settings', expect.objectContaining({
+      method: 'PUT', credentials: 'include',
+      headers: { 'Content-Type': 'application/json', Authorization: 'test-header' },
+      body: JSON.stringify({ theme: 'light' }),
+    }))
+  })
+
+  it('never assumes permission to write when the settings read fails', async () => {
+    const fetchMock = vi.fn().mockResolvedValue(new Response('denied', { status: 403 }))
+    vi.stubGlobal('fetch', fetchMock)
+    const { persistPreferences } = await import('./preferences')
+    await expect(persistPreferences({ theme: 'light' })).rejects.toThrow('403')
+    expect(fetchMock).toHaveBeenCalledTimes(1)
+  })
+
+  it('does not send a pending change to another instance after navigation', async () => {
+    let finish!: (response: Response) => void
+    const fetchMock = vi.fn().mockReturnValue(new Promise<Response>((resolve) => { finish = resolve }))
+    vi.stubGlobal('fetch', fetchMock)
+    const config = await import('./config')
+    const { persistPreferences } = await import('./preferences')
+    const saving = persistPreferences({ theme: 'light' })
+    config.setApiBase('/c/other/api')
+    finish(new Response('{}'))
+    await saving
+    expect(fetchMock).toHaveBeenCalledTimes(1)
+  })
+})

package/src/api/preferences.ts

@@ -0,0 +1,38 @@
+import { apiUrl, getApiBase, getAuthHeaders, getCredentialsMode } from './config'
+import type { PinnedKind } from '../hooks/useFavorites'
+
+interface Preferences {
+  theme?: 'light' | 'dark'
+  pinnedKinds?: PinnedKind[]
+  preferenceStorage?: 'browser'
+}
+
+let request: { base: string; promise: Promise<Preferences> } | undefined
+
+export function loadPreferences(): Promise<Preferences> {
+  const base = getApiBase()
+  if (!request || request.base !== base) {
+    const promise = fetch(apiUrl('/settings'), { credentials: getCredentialsMode(), headers: getAuthHeaders() })
+      .then((res) => {
+        if (!res.ok) throw new Error(`Failed to load preferences: HTTP ${res.status}`)
+        return res.json() as Promise<Preferences>
+      })
+    request = { base, promise }
+    promise.catch(() => { if (request?.promise === promise) request = undefined })
+  }
+  return request.promise
+}
+
+export async function persistPreferences(patch: Pick<Preferences, 'theme' | 'pinnedKinds'>): Promise<void> {
+  const base = getApiBase()
+  const preferences = await loadPreferences()
+  if (base !== getApiBase() || preferences.preferenceStorage === 'browser') return
+  const res = await fetch(apiUrl('/settings'), {
+    method: 'PUT',
+    credentials: getCredentialsMode(),
+    headers: { 'Content-Type': 'application/json', ...getAuthHeaders() },
+    body: JSON.stringify(patch),
+  })
+  if (!res.ok) throw new Error(`Failed to save preferences: HTTP ${res.status}`)
+  if (request?.base === base) request = undefined
+}

package/src/api/usage-data.fixtures.ts

@@ -0,0 +1,33 @@
+import type { UsageDataStatus, UsageReport } from './usage-data'
+
+// Test-only: a report and status shaped like the server's.
+export function exampleReport(patch: Partial<UsageReport> = {}): UsageReport {
+  return {
+    schema: 3,
+    version: '1.15.0', os: 'darwin', arch: 'arm64', installMethod: 'homebrew', mode: 'local',
+    periodStart: '2026-09-23', periodEnd: '2026-09-24',
+    setup: {
+      authMode: 'none', timelineStorage: 'memory', mcpEnabled: true, prometheus: 'none',
+      costSource: 'auto', browsers: ['chrome'],
+    },
+    engagement: { sessions: 2, activeMinutes: '20-49' },
+    views: {}, actions: {}, mcpTools: {}, uiEvents: {}, errors: {},
+    clusters: {
+      contexts: '5-9', used: 1,
+      shapes: [{ kubernetesVersion: '1.33', platform: 'eks', nodes: '10-19', integrations: ['argo-cd'] }],
+    },
+    ...patch,
+  }
+}
+
+export function exampleStatus(patch: Partial<UsageDataStatus> = {}): UsageDataStatus {
+  return {
+    state: 'undecided', source: 'default', canChange: true,
+    developmentBuild: false,
+    preview: exampleReport(),
+    firstRunPrompt: false,
+    ask: true,
+    shared: false,
+    ...patch,
+  }
+}