@skyhook-io/k8s-ui 1.8.8 → 1.8.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skyhook-io/k8s-ui",
-  "version": "1.8.8",
+  "version": "1.8.9",
   "repository": {
     "type": "git",
     "url": "https://github.com/skyhook-io/radar",

package/src/components/applications/ApplicationsView.tsx

@@ -6,6 +6,7 @@ import { StatusDot, mapHealthToTone } from '../ui/status-tone'
 import { Tooltip } from '../ui/Tooltip'
 import { EmptyState } from '../ui/EmptyState'
 import { SearchBox } from '../ui/SearchBox'
+import { useFilterState, defineFilterSchema } from '../../filter-state'
 import { PageHeader } from '../ui/PageHeader'
 import { SummaryTile, type SummaryTone } from '../ui/SummaryTile'
 import { Facet, type FacetTone } from '../ui/Facet'
@@ -101,14 +102,29 @@ export interface ApplicationsViewProps {
   headerActions?: ReactNode
 }
 
+const APPS_FILTER_SCHEMA = defineFilterSchema({
+  health: { param: 'health', type: 'set' },
+  class: { param: 'class', type: 'set' },
+  type: { param: 'type', type: 'set' },
+  env: { param: 'env', type: 'set' },
+  source: { param: 'source', type: 'set' },
+  q: { param: 'q', type: 'text' },
+  system: { param: 'system', type: 'boolean' },
+})
+
 export function ApplicationsView({ entries: allEntries, variant, onSelect, title = 'Applications', description, emptySlot, headerActions }: ApplicationsViewProps) {
-  const [textFilter, setTextFilter] = useState('')
-  const [fHealth, setFHealth] = useState<Set<AppHealth>>(new Set())
-  const [fEnv, setFEnv] = useState<Set<string>>(new Set())
-  const [fSource, setFSource] = useState<Set<AppSource>>(new Set())
-  const [fClass, setFClass] = useState<Set<AppWorkloadClass>>(new Set())
-  const [fType, setFType] = useState<Set<AppCategory>>(new Set())
-  const [showSystem, setShowSystem] = useState(false)
+  // Facets + search + show-system live in the URL (shareable, bookmarkable) via
+  // the shared filter-state contract. Sort stays local: it's a compound
+  // {key, dir} view-preference, not a result-narrowing filter, so it isn't
+  // forced into the filter vocabulary.
+  const filters = useFilterState(APPS_FILTER_SCHEMA)
+  const textFilter = filters.values.q
+  const fHealth = filters.values.health as Set<AppHealth>
+  const fEnv = filters.values.env
+  const fSource = filters.values.source as Set<AppSource>
+  const fClass = filters.values.class as Set<AppWorkloadClass>
+  const fType = filters.values.type as Set<AppCategory>
+  const showSystem = filters.values.system
   const [sort, setSort] = useState<{ key: SortKey; dir: SortDir } | null>(null)
 
   // The Show-system toggle keys off per-entry workload namespaces, which only
@@ -244,12 +260,6 @@ export function ApplicationsView({ entries: allEntries, variant, onSelect, title
     return { health, env, source, workloadClass, category }
   }, [all])
 
-  const toggle = <T,>(set: Set<T>, setter: (s: Set<T>) => void, v: T) => {
-    const next = new Set(set)
-    next.has(v) ? next.delete(v) : next.add(v)
-    setter(next)
-  }
-
   // asc → desc → off (null = default health-worst-first sort).
   const onSort = (key: SortKey) => {
     setSort((prev) => {
@@ -267,20 +277,14 @@ export function ApplicationsView({ entries: allEntries, variant, onSelect, title
   // Clickable status tile wired to the health facet — tap to filter to that tier.
   const healthTile = (h: AppHealth, tone: SummaryTone) =>
     counts.health[h] ? (
-      <SummaryTile key={h} label={HEALTH_META[h].label} value={counts.health[h]} tone={tone} active={fHealth.has(h)} onClick={() => toggle(fHealth, setFHealth, h)} />
+      <SummaryTile key={h} label={HEALTH_META[h].label} value={counts.health[h]} tone={tone} active={fHealth.has(h)} onClick={() => filters.toggle('health', h)} />
     ) : null
 
   // showSystem lives in the Filters rail, so Clear resets it too (and its
   // non-default ON state counts as an active filter that surfaces the button).
-  const anyFilterActive = !!(textFilter || fHealth.size || fClass.size || fType.size || fSource.size || fEnv.size || showSystem)
+  const anyFilterActive = filters.isActive
   const clearAllFilters = () => {
-    setTextFilter('')
-    setFHealth(new Set())
-    setFClass(new Set())
-    setFType(new Set())
-    setFSource(new Set())
-    setFEnv(new Set())
-    setShowSystem(false)
+    filters.clearAll()
   }
 
   return (
@@ -326,14 +330,14 @@ export function ApplicationsView({ entries: allEntries, variant, onSelect, title
             )}
           </div>
           <div className="flex-1 overflow-y-auto">
-            <Facet icon={HeartPulse} title="Availability" options={HEALTH_ORDER.map((h) => ({ value: h, label: HEALTH_META[h].label, count: counts.health[h] ?? 0, tone: HEALTH_TONE[h] }))} selected={fHealth} onToggle={(v) => toggle(fHealth, setFHealth, v)} />
-            <Facet icon={Layers} title="Class" options={CLASS_ORDER.map((c) => ({ value: c, label: CLASS_META[c].label, count: counts.workloadClass[c] ?? 0 }))} selected={fClass} onToggle={(v) => toggle(fClass, setFClass, v)} />
-            <Facet icon={Shapes} title="Type" options={CATEGORY_ORDER.map((c) => ({ value: c, label: CATEGORY_META[c].label, count: counts.category[c] ?? 0, tooltip: CATEGORY_META[c].tooltip }))} selected={fType} onToggle={(v) => toggle(fType, setFType, v)} />
-            <Facet icon={Globe} title="Environment" info={<EnvHint />} options={envOptions} selected={fEnv} onToggle={(v) => toggle(fEnv, setFEnv, v)} />
-            <Facet icon={Tag} title="Source" options={SOURCE_ORDER.map((s) => ({ value: s, label: SOURCE_META[s].label, count: counts.source[s] ?? 0 }))} selected={fSource} onToggle={(v) => toggle(fSource, setFSource, v)} />
+            <Facet icon={HeartPulse} title="Availability" options={HEALTH_ORDER.map((h) => ({ value: h, label: HEALTH_META[h].label, count: counts.health[h] ?? 0, tone: HEALTH_TONE[h] }))} selected={fHealth} onToggle={(v) => filters.toggle('health', v)} />
+            <Facet icon={Layers} title="Class" options={CLASS_ORDER.map((c) => ({ value: c, label: CLASS_META[c].label, count: counts.workloadClass[c] ?? 0 }))} selected={fClass} onToggle={(v) => filters.toggle('class', v)} />
+            <Facet icon={Shapes} title="Type" options={CATEGORY_ORDER.map((c) => ({ value: c, label: CATEGORY_META[c].label, count: counts.category[c] ?? 0, tooltip: CATEGORY_META[c].tooltip }))} selected={fType} onToggle={(v) => filters.toggle('type', v)} />
+            <Facet icon={Globe} title="Environment" info={<EnvHint />} options={envOptions} selected={fEnv} onToggle={(v) => filters.toggle('env', v)} />
+            <Facet icon={Tag} title="Source" options={SOURCE_ORDER.map((s) => ({ value: s, label: SOURCE_META[s].label, count: counts.source[s] ?? 0 }))} selected={fSource} onToggle={(v) => filters.toggle('source', v)} />
             {systemCount > 0 && (
               <label className="flex cursor-pointer items-center gap-2 border-b border-theme-border px-3 py-2 text-[11px] text-theme-text-secondary hover:bg-theme-hover">
-                <input type="checkbox" checked={showSystem} onChange={(e) => setShowSystem(e.target.checked)} className="accent-skyhook-500" />
+                <input type="checkbox" checked={showSystem} onChange={(e) => filters.setBoolean('system', e.target.checked)} className="accent-skyhook-500" />
                 <span>Show system namespaces</span>
                 <span className="ml-auto tabular-nums text-theme-text-tertiary">{systemCount}</span>
               </label>
@@ -346,7 +350,7 @@ export function ApplicationsView({ entries: allEntries, variant, onSelect, title
           <div className="flex shrink-0 items-center gap-3 border-b border-theme-border px-4 py-3">
             <SearchBox
               value={textFilter}
-              onChange={setTextFilter}
+              onChange={(v) => filters.setString('q', v)}
               scope="applications"
               shortcutId="applications-search"
               className="max-w-md flex-1"

package/src/components/checks/ChecksView.tsx

@@ -2,6 +2,7 @@ import { useEffect, useMemo, useRef, useState, type ReactNode } from 'react'
 import { createPortal } from 'react-dom'
 import { ChevronDown, ChevronRight, ExternalLink, EyeOff, MoreHorizontal, Search, ShieldCheck, Wrench, X } from 'lucide-react'
 import { ClusterName, EmptyState, FilterPill, DistributionBar, DistributionLegendChip } from '../ui'
+import { useFilterState, defineFilterSchema } from '../../filter-state'
 import type { CheckMeta, CheckReference } from '../audit'
 import { CHECK_SEVERITIES, CHECK_SEVERITY_RANK, type Check, type CheckSeverity, type EffectiveCheckFinding, type CheckResourceRef } from './types'
 import {
@@ -79,11 +80,24 @@ interface FleetCheck {
   clusters: Check[]
 }
 
+const CHECKS_FILTER_SCHEMA = defineFilterSchema({
+  severity: { param: 'severity', type: 'set' },
+  category: { param: 'category', type: 'set' },
+  framework: { param: 'framework', type: 'set' },
+  q: { param: 'q', type: 'text' },
+})
+
 export function ChecksView({ checks, catalog, anyData, resourceHref, onResourceClick, clusterLabel, clusterLabelById, clusterFilter: clusterFilterProp, onClusterFilterChange, emptyAction, onHideCheck, onHideCategory }: ChecksViewProps) {
-  const [severityFilter, setSeverityFilter] = useState<Set<CheckSeverity>>(new Set())
-  const [categoryFilter, setCategoryFilter] = useState<Set<string>>(new Set())
-  const [frameworkFilter, setFrameworkFilter] = useState<Set<string>>(new Set())
-  const [search, setSearch] = useState('')
+  // Severity / category / framework / search live in the URL (shareable,
+  // bookmarkable audit links) via the shared filter-state contract. The cluster
+  // facet is deliberately NOT here — it's a host-controlled seam (see
+  // onClusterFilterChange) for the multi-cluster/fleet case and isn't shown in
+  // single-cluster OSS, so it stays on its own controlled/internal path.
+  const filters = useFilterState(CHECKS_FILTER_SCHEMA)
+  const severityFilter = filters.values.severity as Set<CheckSeverity>
+  const categoryFilter = filters.values.category
+  const frameworkFilter = filters.values.framework
+  const search = filters.values.q
   const [openId, setOpenId] = useState<string | null>(null)
 
   // Cluster facet is controlled when the host opts in (onClusterFilterChange);
@@ -209,13 +223,10 @@ export function ChecksView({ checks, catalog, anyData, resourceHref, onResourceC
       return next
     })
 
-  const hasFilters = severityFilter.size > 0 || categoryFilter.size > 0 || frameworkFilter.size > 0 || clusterFilter.size > 0 || search !== ''
+  const hasFilters = filters.isActive || clusterFilter.size > 0
   const clearAll = () => {
-    setSeverityFilter(new Set())
-    setCategoryFilter(new Set())
-    setFrameworkFilter(new Set())
+    filters.clearAll()
     setClusterFilter(new Set())
-    setSearch('')
   }
 
   return (
@@ -239,13 +250,13 @@ export function ChecksView({ checks, catalog, anyData, resourceHref, onResourceC
               type="text"
               placeholder="Search checks…"
               value={search}
-              onChange={(e) => setSearch(e.target.value)}
+              onChange={(e) => filters.setString('q', e.target.value)}
               className="w-64 rounded-lg border border-theme-border-light bg-theme-base py-1.5 pl-9 pr-8 text-sm text-theme-text-primary placeholder-theme-text-disabled focus:outline-none focus:ring-2 focus:ring-[var(--color-radar-accent)]"
             />
             {search && (
               <button
                 type="button"
-                onClick={() => setSearch('')}
+                onClick={() => filters.setString('q', '')}
                 aria-label="Clear search"
                 className="absolute right-2 top-1/2 -translate-y-1/2 rounded p-0.5 text-theme-text-tertiary hover:text-theme-text-primary"
               >
@@ -259,17 +270,17 @@ export function ChecksView({ checks, catalog, anyData, resourceHref, onResourceC
 
         <div className="flex flex-wrap items-center gap-1.5">
           {CHECK_SEVERITIES.map((s) => (
-            <CheckSeverityChip key={s} severity={s} count={totals[s]} active={severityFilter.has(s)} onClick={() => toggle(setSeverityFilter, s)} />
+            <CheckSeverityChip key={s} severity={s} count={totals[s]} active={severityFilter.has(s)} onClick={() => filters.toggle('severity', s)} />
           ))}
           <span className="mx-1.5 h-5 w-px bg-theme-border" />
           {CATEGORIES.map((c) => (
-            <FilterPill key={c} label={c} active={categoryFilter.has(c)} onClick={() => toggle(setCategoryFilter, c)} />
+            <FilterPill key={c} label={c} active={categoryFilter.has(c)} onClick={() => filters.toggle('category', c)} />
           ))}
           {frameworks.length > 0 && (
             <>
               <span className="mx-1.5 h-5 w-px bg-theme-border" />
               {frameworks.map((fw) => (
-                <FilterPill key={fw} label={fw} active={frameworkFilter.has(fw)} onClick={() => toggle(setFrameworkFilter, fw)} />
+                <FilterPill key={fw} label={fw} active={frameworkFilter.has(fw)} onClick={() => filters.toggle('framework', fw)} />
               ))}
             </>
           )}

package/src/components/gitops/GitOpsTableView.tsx

@@ -32,10 +32,10 @@ import { FacetSection, FacetButton } from '../ui/Facet'
 import { SortableTh, TH_CLASS, type SortDir } from '../ui/SortableTh'
 import { DistributionBar } from '../ui/DistributionBar'
 import { RowActionMenu, type RowActionItem } from '../ui/RowActionMenu'
-import { PaneLoader } from '../ui/PaneLoader'
 import { getGitOpsResourceStatus } from './detail-helpers'
 import { isArgoSuspendedByRadar } from '../resources/resource-utils-argo'
 import { toggleSet } from './GitOpsGraphFilterRail'
+import { useFilterState, defineFilterSchema } from '../../filter-state'
 import { parseContextName } from '../../utils/context-name'
 
 // =============================================================================
@@ -273,6 +273,16 @@ export interface GitOpsTableViewProps {
 
 // ----- Main component --------------------------------------------------------
 
+const GITOPS_FILTER_SCHEMA = defineFilterSchema({
+  q: { param: 'q', type: 'text' },
+  sync: { param: 'sync', type: 'set' },
+  health: { param: 'health', type: 'set' },
+  project: { param: 'project', type: 'set' },
+  automation: { param: 'automation', type: 'set' },
+  labels: { param: 'labels', type: 'set' },
+  lifecycle: { param: 'lifecycle', type: 'single', default: 'all' },
+})
+
 export function GitOpsTableView({
   rows: allRowsInput,
   loading,
@@ -300,27 +310,24 @@ export function GitOpsTableView({
   const searchInputRef = useRef<HTMLInputElement>(null)
   const [mode, setMode] = useState<GitOpsMode>('applications')
   const [viewMode, setViewMode] = useState<GitOpsViewMode>('table')
-  const [search, setSearch] = useState('')
-  const [syncFilters, setSyncFilters] = useState<Set<string>>(new Set())
-  const [healthFilters, setHealthFilters] = useState<Set<string>>(new Set())
-  const [projectFilters, setProjectFilters] = useState<Set<string>>(new Set())
+  // Sync / health / project / automation / labels / lifecycle + search live in
+  // the URL (shareable, bookmarkable) via the shared filter-state contract.
+  // Deliberate divergences kept on their own state: `namespace` (entangled with
+  // the host globalNamespaces seam + the header scope pill — a separate product
+  // decision), `sort` (a compound view-preference, not a filter), and the
+  // destination filter (host-controlled, below).
+  const filters = useFilterState(GITOPS_FILTER_SCHEMA)
+  const search = filters.values.q
+  const syncFilters = filters.values.sync
+  const healthFilters = filters.values.health
+  const projectFilters = filters.values.project
+  const labelFilters = filters.values.labels
+  const automationFilters = filters.values.automation as Set<'auto' | 'manual' | 'suspended'>
+  const lifecycleFilter = filters.values.lifecycle as 'all' | 'terminating' | 'active'
+  const toggleAutomation = useCallback((value: 'auto' | 'manual' | 'suspended') => filters.toggle('automation', value), [filters.toggle])
   const [namespaceFilters, setNamespaceFilters] = useState<Set<string>>(new Set())
-  const [labelFilters, setLabelFilters] = useState<Set<string>>(new Set())
   const [showLabelsDropdown, setShowLabelsDropdown] = useState(false)
   const [labelSearch, setLabelSearch] = useState('')
-  // Auto-sync / Manual / Suspended are INDEPENDENT row attributes (a Flux app can
-  // be auto-reconciling AND suspended), so this is a multi-select facet like Sync
-  // and Health — not the old single-select that conflated the mode (auto vs
-  // manual) with the orthogonal suspended state.
-  const [automationFilters, setAutomationFilters] = useState<Set<'auto' | 'manual' | 'suspended'>>(new Set())
-  const toggleAutomation = useCallback((value: 'auto' | 'manual' | 'suspended') => {
-    setAutomationFilters((prev) => {
-      const next = new Set(prev)
-      next.has(value) ? next.delete(value) : next.add(value)
-      return next
-    })
-  }, [])
-  const [lifecycleFilter, setLifecycleFilter] = useState<'all' | 'terminating' | 'active'>('all')
   const [sort, setSort] = useState<{ key: SortKey; dir: SortDir } | null>({ key: 'urgency', dir: 'asc' })
   // 3-state cycle: natural direction → reversed → off. The first click uses each
   // column's natural direction (SORT_DEFAULT_DIR — e.g. Last Sync is newest-first)
@@ -468,16 +475,12 @@ export function GitOpsTableView({
   const terminatingCount = useMemo(() => allRows.filter((row) => row.terminating).length, [allRows])
 
   const clearAllFilters = useCallback(() => {
-    setSearch('')
-    setSyncFilters(new Set())
-    setHealthFilters(new Set())
-    setProjectFilters(new Set())
+    filters.clearAll()
     setNamespaceFilters(new Set())
-    setLabelFilters(new Set())
-    setAutomationFilters(new Set())
-    setLifecycleFilter('all')
     onClearNamespaces?.()
     onDestinationFilterChange?.('all')
+    // filters.clearAll is a stable ref from the hook.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [onClearNamespaces, onDestinationFilterChange])
 
   // True when nothing is filtered at all — backs the Total tile's active state.
@@ -531,6 +534,12 @@ export function GitOpsTableView({
 
   const showCrossClusterTile = typeof crossClusterCount === 'number' && mode === 'applications'
 
+  // First fetch, nothing to show yet. Drives the shape-stable loading
+  // treatment: tiles pulse instead of reading "0" (a false zero), the table
+  // area renders skeleton rows, and the filter rail holds its loaded height
+  // with section stubs — so the settled layout doesn't reflow into place.
+  const initialLoading = Boolean(loading) && allRowsInput.length === 0
+
   // Header tiles unify with the facet rail: each STATUS tile toggles its own
   // dimension and composes with the other facets + search (clicking "Out of
   // sync" adds sync=OutOfSync without wiping an active health filter or your
@@ -552,8 +561,8 @@ export function GitOpsTableView({
       value: statusSummary.outOfSync,
       tone: 'warning',
       active: syncFilters.size === 1 && syncFilters.has('OutOfSync'),
-      apply: () => setSyncFilters(new Set(['OutOfSync'])),
-      clear: () => setSyncFilters(new Set()),
+      apply: () => filters.setSet('sync', ['OutOfSync']),
+      clear: () => filters.setSet('sync', []),
     },
     {
       key: 'degraded',
@@ -561,8 +570,8 @@ export function GitOpsTableView({
       value: statusSummary.degraded,
       tone: 'error',
       active: healthFilters.size === 1 && healthFilters.has('Degraded'),
-      apply: () => setHealthFilters(new Set(['Degraded'])),
-      clear: () => setHealthFilters(new Set()),
+      apply: () => filters.setSet('health', ['Degraded']),
+      clear: () => filters.setSet('health', []),
     },
     {
       key: 'suspended',
@@ -570,8 +579,8 @@ export function GitOpsTableView({
       value: statusSummary.suspended,
       tone: 'warning',
       active: automationFilters.size === 1 && automationFilters.has('suspended'),
-      apply: () => setAutomationFilters(new Set(['suspended'])),
-      clear: () => setAutomationFilters(new Set()),
+      apply: () => filters.setSet('automation', ['suspended']),
+      clear: () => filters.setSet('automation', []),
     },
     {
       key: 'reconciling',
@@ -579,8 +588,8 @@ export function GitOpsTableView({
       value: syncCounts.get('Reconciling') ?? 0,
       tone: 'info',
       active: syncFilters.size === 1 && syncFilters.has('Reconciling'),
-      apply: () => setSyncFilters(new Set(['Reconciling'])),
-      clear: () => setSyncFilters(new Set()),
+      apply: () => filters.setSet('sync', ['Reconciling']),
+      clear: () => filters.setSet('sync', []),
     },
     ...(showCrossClusterTile
       ? [
@@ -615,6 +624,7 @@ export function GitOpsTableView({
                   value={tile.value}
                   tone={tile.tone}
                   active={tile.active}
+                  loading={initialLoading}
                   onClick={() => {
                     if (tile.active) tile.clear?.()
                     else tile.apply?.()
@@ -631,25 +641,26 @@ export function GitOpsTableView({
         }`}
       >
       <GitOpsFilterSidebar
+        loading={initialLoading}
         side={filtersSide}
         mode={mode}
         onModeChange={setMode}
         modeCounts={modeCounts}
         syncCounts={syncCounts}
         syncFilters={syncFilters}
-        onToggleSync={(value) => toggleSet(syncFilters, setSyncFilters, value)}
+        onToggleSync={(value) => filters.toggle('sync', value)}
         healthCounts={healthCounts}
         healthFilters={healthFilters}
-        onToggleHealth={(value) => toggleSet(healthFilters, setHealthFilters, value)}
+        onToggleHealth={(value) => filters.toggle('health', value)}
         automationFilters={automationFilters}
         automationCounts={automationCounts}
         onToggleAutomation={toggleAutomation}
         lifecycleFilter={lifecycleFilter}
-        onLifecycleFilterChange={setLifecycleFilter}
+        onLifecycleFilterChange={(v) => filters.setString('lifecycle', v)}
         terminatingCount={terminatingCount}
         projects={projects}
         projectFilters={projectFilters}
-        onToggleProject={(value) => toggleSet(projectFilters, setProjectFilters, value)}
+        onToggleProject={(value) => filters.toggle('project', value)}
         namespaces={rowNamespaces}
         namespaceFilters={namespaceFilters}
         onToggleNamespace={(value) => toggleSet(namespaceFilters, setNamespaceFilters, value)}
@@ -678,7 +689,7 @@ export function GitOpsTableView({
               <input
                 ref={searchInputRef}
                 value={search}
-                onChange={(e) => setSearch(e.target.value)}
+                onChange={(e) => filters.setString('q', e.target.value)}
                 placeholder="Search applications, repos, paths..."
                 className="h-8 w-full rounded-md border border-theme-border bg-theme-base pl-8 pr-3 text-sm text-theme-text-primary placeholder:text-theme-text-tertiary focus:outline-none focus:ring-1 focus:ring-blue-500/50"
               />
@@ -698,8 +709,8 @@ export function GitOpsTableView({
               <LabelsDropdown
                 labels={labels}
                 activeLabels={labelFilters}
-                onToggle={(value) => toggleSet(labelFilters, setLabelFilters, value)}
-                onClear={() => setLabelFilters(new Set())}
+                onToggle={(value) => filters.toggle('labels', value)}
+                onClear={() => filters.setSet('labels', [])}
                 open={showLabelsDropdown}
                 onOpenChange={setShowLabelsDropdown}
                 search={labelSearch}
@@ -754,8 +765,8 @@ export function GitOpsTableView({
             <div className="flex h-full items-center justify-center text-sm text-theme-text-secondary">
               {modeLabel(mode)} view is queued behind the application list.
             </div>
-          ) : loading && filteredRows.length === 0 ? (
-            <PaneLoader label="Loading GitOps applications…" className="h-full" />
+          ) : initialLoading ? (
+            <GitOpsTableSkeleton />
           ) : error ? (
             <div className="p-4 text-sm text-red-500">Failed to load GitOps applications: {error.message}</div>
           ) : filteredRows.length === 0 ? (
@@ -805,7 +816,62 @@ export function GitOpsTableView({
 // GitOpsTableView's visual language and not generally useful elsewhere.
 // =============================================================================
 
+// Shape-stable loading stand-ins. Both mirror the loaded anatomy so data
+// resolves in place: rows appear inside the table frame, facets inside the
+// rail — no half-height rail dangling next to a centered spinner, no layout
+// jump when the response lands.
+function GitOpsTableSkeleton() {
+  return (
+    <div aria-live="polite" aria-label="Loading GitOps applications…" className="divide-y divide-theme-border-light">
+      {Array.from({ length: 10 }, (_, i) => (
+        <div key={i} className="flex items-center gap-6 px-4 py-3" style={{ opacity: 1 - i * 0.09 }}>
+          <div className="min-w-0 flex-[2] space-y-2">
+            <div className="h-4 w-2/3 animate-pulse rounded bg-theme-hover" />
+            <div className="h-3 w-1/2 animate-pulse rounded bg-theme-hover" />
+          </div>
+          <div className="hidden h-4 flex-1 animate-pulse rounded bg-theme-hover md:block" />
+          <div className="h-5 w-20 animate-pulse rounded-full bg-theme-hover" />
+          <div className="h-5 w-20 animate-pulse rounded-full bg-theme-hover" />
+          <div className="hidden h-4 flex-[1.5] animate-pulse rounded bg-theme-hover lg:block" />
+        </div>
+      ))}
+    </div>
+  )
+}
+
+function GitOpsSidebarSkeleton() {
+  // Section stubs sized like the loaded rail (Sync ~4 rows, Health ~5,
+  // Automation ~3, Projects/Namespaces a few each) so the rail keeps its
+  // height while counts are unknown — showing real facet buttons with "0"
+  // counts would be false zeros.
+  const sections: Array<[string, number]> = [
+    ['Sync', 4],
+    ['Health', 5],
+    ['Automation', 3],
+    ['Projects', 4],
+    ['Namespaces', 4],
+  ]
+  return (
+    <div aria-hidden>
+      {sections.map(([title, rows]) => (
+        <div key={title} className="border-b border-theme-border-light px-3 py-3">
+          <div className="mb-2 h-3 w-24 animate-pulse rounded bg-theme-hover" />
+          <div className="space-y-1.5">
+            {Array.from({ length: rows }, (_, i) => (
+              <div key={i} className="flex items-center justify-between px-1.5 py-1">
+                <div className="h-3.5 animate-pulse rounded bg-theme-hover" style={{ width: `${52 - i * 6}%` }} />
+                <div className="h-3.5 w-6 animate-pulse rounded bg-theme-hover" />
+              </div>
+            ))}
+          </div>
+        </div>
+      ))}
+    </div>
+  )
+}
+
 function GitOpsFilterSidebar({
+  loading,
   side,
   mode,
   onModeChange,
@@ -853,6 +919,8 @@ function GitOpsFilterSidebar({
   namespaceFilters: Set<string>
   onToggleNamespace: (value: string) => void
   onClear: () => void
+  /** Initial fetch in flight — hold the rail's shape with section stubs. */
+  loading?: boolean
 }) {
   return (
     <aside
@@ -867,6 +935,10 @@ function GitOpsFilterSidebar({
         </button>
       </div>
       <div className="flex-1 overflow-y-auto">
+        {loading ? (
+          <GitOpsSidebarSkeleton />
+        ) : (
+          <>
         {AVAILABLE_MODES.length > 1 && (
         <GitOpsFilterSection icon={GitBranch} title="Scope">
           <div className="grid grid-cols-2 gap-1">
@@ -960,6 +1032,8 @@ function GitOpsFilterSidebar({
             />
           ))}
         </GitOpsFilterSection>
+          </>
+        )}
       </div>
     </aside>
   )

package/src/components/ui/SummaryTile.tsx

@@ -12,12 +12,16 @@ export function SummaryTile({
   tone = 'neutral',
   onClick,
   active = false,
+  loading = false,
 }: {
   label: string
   value: number
   tone?: SummaryTone
   onClick?: () => void
   active?: boolean
+  /** First fetch in flight — render a pulse instead of the value. A tile
+   *  that reads "0" while loading is a false zero, not a count. */
+  loading?: boolean
 }) {
   const toneClass = {
     neutral: 'text-theme-text-primary',
@@ -33,7 +37,11 @@ export function SummaryTile({
     error: 'border-red-500',
     info: 'border-sky-500',
   }[tone]
-  const value$ = <div className={`text-sm font-semibold ${toneClass}`}>{value}</div>
+  const value$ = loading ? (
+    <div className="my-1 h-3.5 w-8 animate-pulse rounded bg-theme-hover" aria-hidden />
+  ) : (
+    <div className={`text-sm font-semibold ${toneClass}`}>{value}</div>
+  )
   const label$ = <div className="text-xs text-theme-text-tertiary">{label}</div>
   if (!onClick) {
     return (

package/src/filter-state/filter-state-core.test.ts

@@ -0,0 +1,98 @@
+import { describe, it, expect } from 'vitest'
+import {
+  decodeFilters,
+  defineFilterSchema,
+  withField,
+  withToggle,
+  withCleared,
+  isFilterActive,
+} from './filter-state-core'
+
+const schema = defineFilterSchema({
+  ns: { param: 'namespace', type: 'set' },
+  sev: { param: 'severity', type: 'set' },
+  q: { param: 'q', type: 'text' },
+  group: { param: 'group', type: 'single', default: 'none' },
+  managed: { param: 'managed', type: 'boolean' },
+})
+
+const p = (s = '') => new URLSearchParams(s)
+
+describe('filter-state core', () => {
+  it('decodes params by type', () => {
+    const v = decodeFilters(schema, p('namespace=argocd,default&severity=high&q=foo&managed=1'))
+    expect([...v.ns]).toEqual(['argocd', 'default'])
+    expect([...v.sev]).toEqual(['high'])
+    expect(v.q).toBe('foo')
+    expect(v.managed).toBe(true)
+  })
+
+  it('applies string defaults when the param is absent', () => {
+    const v = decodeFilters(schema, p(''))
+    expect(v.group).toBe('none')
+    expect(v.q).toBe('')
+    expect(v.managed).toBe(false)
+    expect(v.ns.size).toBe(0)
+  })
+
+  it('toggles a set member and omits the param when empty (empty = all)', () => {
+    const added = withToggle(schema, p(''), 'ns', 'argocd')
+    expect(added.toString()).toBe('namespace=argocd')
+    const removed = withToggle(schema, added, 'ns', 'argocd')
+    expect(removed.toString()).toBe('')
+  })
+
+  it('composes successive toggles (each sees the previous result)', () => {
+    let params = p('')
+    params = withToggle(schema, params, 'ns', 'a')
+    params = withToggle(schema, params, 'ns', 'b')
+    expect([...decodeFilters(schema, params).ns].sort()).toEqual(['a', 'b'])
+  })
+
+  it('withField replaces a set wholesale and clears when empty', () => {
+    const set = withField(schema, p('namespace=x'), 'ns', new Set(['a', 'b']))
+    expect([...decodeFilters(schema, set).ns]).toEqual(['a', 'b'])
+    expect(withField(schema, set, 'ns', new Set<string>()).toString()).toBe('')
+  })
+
+  it('omits a string param when equal to its default', () => {
+    expect(withField(schema, p(''), 'group', 'namespace').toString()).toBe('group=namespace')
+    expect(withField(schema, p('group=namespace'), 'group', 'none').toString()).toBe('')
+  })
+
+  it('encodes a boolean as =1 and omits false', () => {
+    expect(withField(schema, p(''), 'managed', true).toString()).toBe('managed=1')
+    expect(withField(schema, p('managed=1'), 'managed', false).toString()).toBe('')
+  })
+
+  it('clears one field or all schema fields, leaving unrelated params', () => {
+    const one = withCleared(schema, p('namespace=a&severity=high&keep=yes'), ['ns'])
+    const oneV = decodeFilters(schema, one)
+    expect(oneV.ns.size).toBe(0)
+    expect(oneV.sev.size).toBe(1)
+    expect(one.get('keep')).toBe('yes')
+    expect(withCleared(schema, p('namespace=a&severity=high&keep=yes')).toString()).toBe('keep=yes')
+  })
+
+  it('isFilterActive is true only when a field diverges from its default', () => {
+    expect(isFilterActive(schema, decodeFilters(schema, p('q=foo')))).toBe(true)
+    expect(isFilterActive(schema, decodeFilters(schema, p('group=none')))).toBe(false)
+    expect(isFilterActive(schema, decodeFilters(schema, p('')))).toBe(false)
+  })
+
+  it('writes set values sorted, so the URL is canonical regardless of order', () => {
+    const a = withToggle(schema, withToggle(schema, p(''), 'ns', 'zebra'), 'ns', 'alpha')
+    expect(a.get('namespace')).toBe('alpha,zebra')
+  })
+
+  it('decodes an empty string param (?group=) as the default', () => {
+    expect(decodeFilters(schema, p('group=')).group).toBe('none')
+    expect(decodeFilters(schema, p('q=')).q).toBe('')
+  })
+
+  it('defineFilterSchema rejects duplicate URL params', () => {
+    expect(() =>
+      defineFilterSchema({ a: { param: 'x', type: 'set' }, b: { param: 'x', type: 'set' } }),
+    ).toThrow(/duplicate/)
+  })
+})

package/src/filter-state/filter-state-core.ts

@@ -0,0 +1,138 @@
+// Pure URL <-> filter-state transforms. No React, no router, no window — just
+// URLSearchParams in, URLSearchParams / typed values out. This is the behavioral
+// contract every list view shares; keeping it pure makes it exhaustively
+// testable and keeps the React hook a thin wrapper.
+
+export interface FilterFieldDef {
+  /** URL query-param name. Stable — this is a durable, shareable public API. */
+  param: string
+  /**
+   * - 'set'     multi-select; comma-list. Empty ⇒ param omitted ⇒ "all" (no
+   *             narrowing). Values must not contain commas (k8s identifiers and
+   *             controlled enums never do). Written sorted, so the URL is
+   *             canonical regardless of selection order. Value: Set<string>.
+   * - 'text'    free-text search; written with history `replace` (no entry per
+   *             keystroke). Omitted when empty / equal to `default`. Value: string.
+   * - 'single'  single choice (enum / dropdown, incl. tri-state all|yes|no);
+   *             pushes a history entry. Omitted when equal to `default`. Value:
+   *             string.
+   * - 'boolean' two-state flag; `param=1` when true, omitted when false. For
+   *             three states use 'single' with an enum default. Value: boolean.
+   */
+  type: 'set' | 'text' | 'single' | 'boolean'
+  /** Default for 'text'/'single' (omitted from the URL when the value equals it). */
+  default?: string
+}
+
+export type FilterSchema = Record<string, FilterFieldDef>
+
+type FieldValue<F extends FilterFieldDef> = F['type'] extends 'set'
+  ? Set<string>
+  : F['type'] extends 'boolean'
+    ? boolean
+    : string
+
+export type FilterValues<S extends FilterSchema> = { [K in keyof S]: FieldValue<S[K]> }
+
+/** Keys of a schema whose field is one of the given kinds — for type-safe setters. */
+export type FieldKeysOfType<S extends FilterSchema, T extends FilterFieldDef['type']> = {
+  [K in keyof S]: S[K]['type'] extends T ? K : never
+}[keyof S]
+
+/**
+ * Identity helper that preserves literal types (so `values.x` is precisely typed)
+ * and validates the schema — duplicate URL params would silently clobber each
+ * other, so we fail loudly at module load.
+ */
+export function defineFilterSchema<const S extends FilterSchema>(schema: S): S {
+  const seen = new Set<string>()
+  for (const key in schema) {
+    const { param } = schema[key]
+    if (seen.has(param)) throw new Error(`defineFilterSchema: duplicate URL param "${param}"`)
+    seen.add(param)
+  }
+  return schema
+}
+
+export function decodeFilters<S extends FilterSchema>(schema: S, params: URLSearchParams): FilterValues<S> {
+  const out = {} as FilterValues<S>
+  for (const key in schema) {
+    const def = schema[key]
+    const raw = params.get(def.param)
+    if (def.type === 'set') {
+      ;(out[key] as Set<string>) = new Set((raw ?? '').split(',').filter(Boolean))
+    } else if (def.type === 'boolean') {
+      ;(out[key] as boolean) = raw === '1'
+    } else {
+      // text / single: an empty param (?f=) reads as the default, same as omission.
+      ;(out[key] as string) = raw ? raw : (def.default ?? '')
+    }
+  }
+  return out
+}
+
+/** Write one field into `params` in place. Read (decode) and write agree exactly. */
+function writeField(params: URLSearchParams, def: FilterFieldDef, value: Set<string> | string | boolean): void {
+  if (def.type === 'set') {
+    const set = value as Set<string>
+    if (set.size === 0) params.delete(def.param)
+    else params.set(def.param, [...set].sort().join(','))
+  } else if (def.type === 'boolean') {
+    if (value) params.set(def.param, '1')
+    else params.delete(def.param)
+  } else {
+    const str = value as string
+    if (!str || str === (def.default ?? '')) params.delete(def.param)
+    else params.set(def.param, str)
+  }
+}
+
+/** Return new params with one field set to `value`. */
+export function withField<S extends FilterSchema>(
+  schema: S,
+  params: URLSearchParams,
+  key: keyof S,
+  value: Set<string> | string | boolean,
+): URLSearchParams {
+  const next = new URLSearchParams(params)
+  writeField(next, schema[key], value)
+  return next
+}
+
+/** Return new params with one member added to / removed from a 'set' field. */
+export function withToggle<S extends FilterSchema>(
+  schema: S,
+  params: URLSearchParams,
+  key: keyof S,
+  value: string,
+): URLSearchParams {
+  const next = new URLSearchParams(params)
+  const cur = new Set((next.get(schema[key].param) ?? '').split(',').filter(Boolean))
+  if (cur.has(value)) cur.delete(value)
+  else cur.add(value)
+  writeField(next, schema[key], cur)
+  return next
+}
+
+/** Default (empty) value for a field, used to reset it. */
+export function emptyValue(def: FilterFieldDef): Set<string> | string | boolean {
+  return def.type === 'set' ? new Set<string>() : def.type === 'boolean' ? false : (def.default ?? '')
+}
+
+/** Return new params with the given schema fields cleared (all of them if omitted). */
+export function withCleared<S extends FilterSchema>(schema: S, params: URLSearchParams, keys?: (keyof S)[]): URLSearchParams {
+  const next = new URLSearchParams(params)
+  for (const key of keys ?? (Object.keys(schema) as (keyof S)[])) next.delete(schema[key].param)
+  return next
+}
+
+export function isFilterActive<S extends FilterSchema>(schema: S, values: FilterValues<S>): boolean {
+  for (const key in schema) {
+    const def = schema[key]
+    const v = values[key]
+    if (def.type === 'set' && (v as Set<string>).size > 0) return true
+    if (def.type === 'boolean' && (v as boolean)) return true
+    if ((def.type === 'text' || def.type === 'single') && (v as string) !== (def.default ?? '')) return true
+  }
+  return false
+}

package/src/filter-state/filter-state.tsx

@@ -0,0 +1,127 @@
+import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState, type ReactNode } from 'react'
+import {
+  decodeFilters,
+  isFilterActive,
+  withCleared,
+  withField,
+  withToggle,
+  emptyValue,
+  type FieldKeysOfType,
+  type FilterSchema,
+  type FilterValues,
+} from './filter-state-core'
+
+// Shared filter-state contract for Radar's list views (OSS + Hub).
+//
+// The consolidation center is BEHAVIOR, not components: one place owns how a
+// view's filters serialize to the URL, what "cleared" means, and how defaults
+// encode — so every list view is shareable/bookmarkable and behaves the same,
+// whether it renders as a facet sidebar or a compact bar.
+//
+// URL is the single source of truth (no localStorage of filter values — that
+// goes stale across clusters/orgs). Router-agnostic + app-agnostic: this never
+// imports react-router or reads window; the host injects a FilterLocation
+// adapter over its own router. All transforms live in ./filter-state-core (pure,
+// exhaustively tested); this file is only the React glue.
+
+/** A reactive view of the URL query string, injected by the host app. */
+export interface FilterLocation {
+  /** Current query params — reactive (sourced from the app's router hook). */
+  searchParams: URLSearchParams
+  /**
+   * Apply an update. The updater receives the LATEST params (not a captured
+   * snapshot), so rapid successive toggles compose instead of clobbering.
+   * `replace` avoids a history entry per keystroke (used for text fields).
+   */
+  update: (updater: (prev: URLSearchParams) => URLSearchParams, opts?: { replace?: boolean }) => void
+}
+
+const FilterLocationContext = createContext<FilterLocation | null>(null)
+
+/**
+ * Wrap the app subtree once with the host's router adapter, e.g.
+ *   const [searchParams, setSearchParams] = useSearchParams()
+ *   <FilterLocationProvider value={{ searchParams, update: setSearchParams }}>
+ */
+export function FilterLocationProvider({ value, children }: { value: FilterLocation; children: ReactNode }) {
+  return <FilterLocationContext.Provider value={value}>{children}</FilterLocationContext.Provider>
+}
+
+export function useFilterLocation(): FilterLocation {
+  const ctx = useContext(FilterLocationContext)
+  if (!ctx) throw new Error('useFilterState requires a <FilterLocationProvider> ancestor')
+  return ctx
+}
+
+export interface FilterState<S extends FilterSchema> {
+  values: FilterValues<S>
+  /** Any field diverges from its default (⇒ show a "Clear all" affordance). */
+  isActive: boolean
+  /** Add/remove one value in a 'set' field. */
+  toggle: (key: FieldKeysOfType<S, 'set'>, value: string) => void
+  /** Replace a 'set' field wholesale. */
+  setSet: (key: FieldKeysOfType<S, 'set'>, values: string[]) => void
+  /** Set a 'text' or 'single' field. 'text' replaces history; 'single' pushes it. */
+  setString: (key: FieldKeysOfType<S, 'text' | 'single'>, value: string) => void
+  setBoolean: (key: FieldKeysOfType<S, 'boolean'>, value: boolean) => void
+  /** Reset one field to its default. */
+  clear: (key: keyof S) => void
+  /** Reset every field in the schema (leaves unrelated params untouched). */
+  clearAll: () => void
+}
+
+export function useFilterState<S extends FilterSchema>(schema: S): FilterState<S> {
+  const ctx = useContext(FilterLocationContext)
+
+  // Graceful fallback: without a provider, keep filter state locally (still
+  // works, just not URL-synced). This lets a shared view adopt the contract
+  // before every host has wired a FilterLocationBridge — a host that hasn't
+  // (e.g. Radar Hub, until it picks up a published build) keeps its prior local
+  // behavior instead of crashing. A one-time warning flags the missing wiring.
+  const [localParams, setLocalParams] = useState(() => new URLSearchParams())
+  const warned = useRef(false)
+  useEffect(() => {
+    if (!ctx && !warned.current) {
+      warned.current = true
+      console.warn('[k8s-ui] useFilterState: no <FilterLocationProvider> ancestor — filters are local, not URL-synced.')
+    }
+  }, [ctx])
+  const fallback = useMemo<FilterLocation>(
+    () => ({ searchParams: localParams, update: (u) => setLocalParams((prev) => u(new URLSearchParams(prev))) }),
+    [localParams],
+  )
+  const { searchParams, update } = ctx ?? fallback
+
+  // Depend on the serialized string, not the URLSearchParams object identity, so
+  // a router adapter that returns a mutated/unstable instance can't stale the memo.
+  const paramsKey = searchParams.toString()
+  const values = useMemo(() => decodeFilters(schema, new URLSearchParams(paramsKey)), [schema, paramsKey])
+  const isActive = useMemo(() => isFilterActive(schema, values), [schema, values])
+
+  const toggle = useCallback(
+    (key: FieldKeysOfType<S, 'set'>, value: string) => update((prev) => withToggle(schema, prev, key, value)),
+    [schema, update],
+  )
+  const setSet = useCallback(
+    (key: FieldKeysOfType<S, 'set'>, vals: string[]) => update((prev) => withField(schema, prev, key, new Set(vals))),
+    [schema, update],
+  )
+  const setString = useCallback(
+    (key: FieldKeysOfType<S, 'text' | 'single'>, v: string) =>
+      // Typing into a search box shouldn't spam history; picking an enum should be
+      // a real back-step. 'text' replaces, 'single' pushes.
+      update((prev) => withField(schema, prev, key, v), { replace: schema[key].type === 'text' }),
+    [schema, update],
+  )
+  const setBoolean = useCallback(
+    (key: FieldKeysOfType<S, 'boolean'>, v: boolean) => update((prev) => withField(schema, prev, key, v)),
+    [schema, update],
+  )
+  const clear = useCallback(
+    (key: keyof S) => update((prev) => withField(schema, prev, key, emptyValue(schema[key]))),
+    [schema, update],
+  )
+  const clearAll = useCallback(() => update((prev) => withCleared(schema, prev)), [schema, update])
+
+  return { values, isActive, toggle, setSet, setString, setBoolean, clear, clearAll }
+}

package/src/filter-state/index.ts

@@ -0,0 +1,16 @@
+export {
+  FilterLocationProvider,
+  useFilterLocation,
+  useFilterState,
+} from './filter-state'
+export type { FilterLocation, FilterState } from './filter-state'
+export {
+  defineFilterSchema,
+  decodeFilters,
+  withField,
+  withToggle,
+  withCleared,
+  emptyValue,
+  isFilterActive,
+} from './filter-state-core'
+export type { FilterFieldDef, FilterSchema, FilterValues, FieldKeysOfType } from './filter-state-core'

package/src/index.ts

@@ -61,6 +61,10 @@ export * from './components/namespace-switcher'
 // segments into one unit (OSS header + Radar Hub cluster top bar)
 export * from './components/scope-pill'
 
+// Filter-state contract — shared URL-synced filter state for list views (OSS +
+// Hub), router-agnostic via an injected FilterLocation adapter
+export * from './filter-state'
+
 // Applications (shared host-agnostic list + detail shell for the deployable-
 // software surface; OSS renders single-cluster, Cloud adds the fleet layer)
 export * from './components/applications'