@skyhook-io/k8s-ui 1.8.1 → 1.8.2

package/src/components/dock/useMultilinePasteConfirm.tsx

@@ -0,0 +1,75 @@
+import { useCallback, useRef, useState } from 'react'
+import { ConfirmDialog } from '../ui/ConfirmDialog'
+import type { PasteConfirmInfo, PasteConfirmer } from './terminalClipboard'
+
+// Session-scoped "Don't ask again" — app-wide for the page session (shared across
+// terminal tabs), reset on reload. Deliberately not persisted: a multi-line paste
+// warning re-appearing once per session is cheap, and it avoids a safety net the
+// user silently disabled long ago and forgot.
+let warningSuppressedThisSession = false
+
+/**
+ * Owns the themed confirmation shown before a risky multi-line paste runs in a
+ * terminal. Returns a `confirmPaste` callback to hand to setupTerminalClipboard
+ * and a `pasteDialog` node the host must render. Once the user opts out via
+ * "Don't ask again", pastes proceed without prompting for the rest of the session.
+ */
+export function useMultilinePasteConfirm(): { confirmPaste: PasteConfirmer; pasteDialog: React.ReactNode } {
+  const [pending, setPending] = useState<PasteConfirmInfo | null>(null)
+  const [dontAskAgain, setDontAskAgain] = useState(false)
+  const resolverRef = useRef<((ok: boolean) => void) | null>(null)
+
+  const confirmPaste = useCallback<PasteConfirmer>(
+    (info) => {
+      if (warningSuppressedThisSession) return Promise.resolve(true)
+      // A paste arriving while a dialog is still open supersedes it: decline the
+      // pending one so its promise resolves (the superseded paste is dropped)
+      // rather than leaking, then show the new prompt.
+      resolverRef.current?.(false)
+      return new Promise<boolean>((resolve) => {
+        resolverRef.current = resolve
+        setDontAskAgain(false)
+        setPending(info)
+      })
+    },
+    [],
+  )
+
+  const settle = useCallback(
+    (ok: boolean) => {
+      // Only suppress when the user actually proceeds — cancelling shouldn't
+      // quietly disable the warning.
+      if (ok && dontAskAgain) warningSuppressedThisSession = true
+      resolverRef.current?.(ok)
+      resolverRef.current = null
+      setPending(null)
+    },
+    [dontAskAgain],
+  )
+
+  const pasteDialog = pending ? (
+    <ConfirmDialog
+      open
+      variant="warning"
+      title="Paste multiple lines?"
+      message={`This pastes ${pending.lineCount} lines into the shell — they run immediately.`}
+      details={pending.text}
+      confirmLabel="Paste"
+      cancelLabel="Cancel"
+      onConfirm={() => settle(true)}
+      onClose={() => settle(false)}
+    >
+      <label className="flex items-center gap-2 text-sm text-theme-text-secondary cursor-pointer">
+        <input
+          type="checkbox"
+          checked={dontAskAgain}
+          onChange={(e) => setDontAskAgain(e.target.checked)}
+          className="w-4 h-4 rounded border-theme-border bg-theme-base accent-amber-500"
+        />
+        <span>Don&apos;t ask again this session</span>
+      </label>
+    </ConfirmDialog>
+  ) : null
+
+  return { confirmPaste, pasteDialog }
+}

package/src/components/gitops/GitOpsTableView.tsx

@@ -72,12 +72,23 @@ export type GitOpsMode = 'applications' | 'sources' | 'projects' | 'alerts'
 // the Scope switcher stays hidden until a second category lands. A one-option
 // switcher is just noise (an always-selected pill that can't be changed).
 const AVAILABLE_MODES: GitOpsMode[] = ['applications']
+const GITOPS_COUNT_GROUP_PREFIXES = [
+  'argoproj.io/',
+  'source.toolkit.fluxcd.io/',
+  'kustomize.toolkit.fluxcd.io/',
+  'helm.toolkit.fluxcd.io/',
+  'notification.toolkit.fluxcd.io/',
+]
 export type GitOpsViewMode = 'table' | 'tiles'
 // 'urgency' is the curated DEFAULT order (what needs attention first) — not a
 // column, so no header shows it as active; clicking any header replaces it with
 // that column's own semantics.
 export type SortKey = 'urgency' | 'name' | 'health' | 'sync' | 'lastSync' | 'project'
 
+function isGitOpsCountKey(key: string): boolean {
+  return GITOPS_COUNT_GROUP_PREFIXES.some((prefix) => key.startsWith(prefix))
+}
+
 // Row-level actions surfaced from the table's three-dot menu. The set
 // mirrors what the detail page exposes today; callers wire the mutations
 // + dialogs and dispatch via `onRowAction`. Argo-only actions (refresh,
@@ -180,6 +191,7 @@ export interface GitOpsTableViewProps {
   // counts keyed "group/Kind" — e.g. "argoproj.io/Application" → 17. Drives
   // the Scope-section mode tabs and the empty-state check.
   counts: Record<string, number>
+  countsUnavailable?: string[]
   // Caller refresh — typically invalidates its useQuery + refetches.
   onRefresh?: () => void
   // Row click — caller routes to its own detail page. When the host also
@@ -262,6 +274,7 @@ export function GitOpsTableView({
   loading,
   error,
   counts,
+  countsUnavailable,
   onRefresh,
   onRowClick,
   rowHrefFor,
@@ -356,7 +369,14 @@ export function GitOpsTableView({
     projects: counts['argoproj.io/AppProject'] ?? 0,
     alerts: counts['notification.toolkit.fluxcd.io/Alert'] ?? 0,
   }
-  const totalGitOps = Object.values(counts).reduce((sum, n) => sum + n, 0)
+  const totalGitOps = Object.entries(counts).reduce(
+    (sum, [key, n]) => sum + (isGitOpsCountKey(key) ? n : 0),
+    0,
+  )
+  const hasUnavailableGitOpsCounts = useMemo(
+    () => (countsUnavailable ?? []).some(isGitOpsCountKey),
+    [countsUnavailable],
+  )
 
   const projects = useMemo(
     () => countValues(allRows.map((row) => row.project).filter(Boolean)),
@@ -484,7 +504,7 @@ export function GitOpsTableView({
   // Also require zero actual rows: the cold-cache retry can populate `rows`
   // before the separate counts map catches up, and a populated table must not
   // be hidden behind a "nothing here" screen.
-  if (totalGitOps === 0 && allRowsInput.length === 0 && !loading && !hasGlobalNamespaceFilter) {
+  if (totalGitOps === 0 && allRowsInput.length === 0 && !loading && !hasGlobalNamespaceFilter && !hasUnavailableGitOpsCounts) {
     return (
       <div className="flex h-full min-h-0 flex-1 items-start justify-center bg-theme-base px-4 pb-4 pt-[22vh]">
         <div className="rounded-lg border border-theme-border bg-theme-surface p-8 text-center">

package/src/components/resources/ResourcesSidebar.tsx

@@ -34,7 +34,8 @@ export interface ResourcesSidebarProps {
   onSelectedKindChange: (kind: SelectedKindInfo) => void
   onKindChange?: () => void
   apiResources?: APIResource[]
-  resourceCounts?: Record<string, number>
+  resourceCounts?: Record<string, number | null>
+  resourceUnavailable?: string[]
   resourceForbidden?: string[]
   pinned?: PinnedItem[]
   togglePin?: (item: PinnedItem) => void
@@ -176,6 +177,7 @@ export function ResourcesSidebar({
   onKindChange,
   apiResources,
   resourceCounts,
+  resourceUnavailable,
   resourceForbidden,
   pinned = [],
   togglePin = () => {},
@@ -257,11 +259,11 @@ export function ResourcesSidebar({
     }))
   }, [categories])
 
-  // null for a key means "not loaded yet" (rendered as a placeholder
-  // dash in the badge). 0 means "the API replied and confirmed there
-  // are zero of this kind". Don't conflate them — otherwise the
-  // sidebar shows a confident "0" for every kind while the count
-  // payload is still in flight.
+  const unavailableKinds = useMemo(() => new Set(resourceUnavailable ?? []), [resourceUnavailable])
+
+  // null for a key means "count unknown/unavailable" (rendered as a
+  // placeholder dash in the badge). 0 means "the API replied and
+  // confirmed there are zero of this kind".
   const counts = useMemo(() => {
     const results: Record<string, number | null> = {}
     if (!resourceCounts) {
@@ -273,15 +275,16 @@ export function ResourcesSidebar({
     }
     for (const resource of resourcesToCount) {
       const key = resource.group ? `${resource.group}/${resource.kind}` : resource.kind
-      const v = resourceCounts[key]
-      // Treat missing keys in a present resourceCounts payload as
-      // "the API replied and didn't include this kind" → 0. Treat the
-      // entire payload being absent as "not loaded" → null (handled
-      // above).
-      results[key] = v ?? 0
+      if (unavailableKinds.has(key)) {
+        results[key] = null
+      } else if (key in resourceCounts) {
+        results[key] = resourceCounts[key] ?? null
+      } else {
+        results[key] = 0
+      }
     }
     return results
-  }, [resourcesToCount, resourceCounts])
+  }, [resourcesToCount, resourceCounts, unavailableKinds])
 
   // Track which resource kinds returned 403 Forbidden
   const forbiddenKinds = useMemo(() => {

package/src/components/resources/ResourcesView.tsx

@@ -1813,6 +1813,20 @@ export interface ResourceQueryResult {
   dataUpdatedAt?: number
 }
 
+export interface LargeListGuardState {
+  kind: string
+  count?: number
+  reason?: 'too-many' | 'count-unavailable'
+  limit: number
+  namespaces: string[]
+}
+
+function formatLargeListScope(namespaces: string[]): string {
+  if (namespaces.length === 0) return 'all namespaces'
+  if (namespaces.length === 1) return namespaces[0]
+  return `${namespaces.length.toLocaleString()} namespaces`
+}
+
 interface ResourcesViewProps {
   namespaces: string[]
   selectedResource?: SelectedResource | null
@@ -1826,8 +1840,10 @@ interface ResourcesViewProps {
   // Lightweight counts for sidebar badges (from /api/resource-counts)
   resourceCounts?: Record<string, number>
   resourceForbidden?: string[]
+  resourceUnavailable?: string[]
   // Single query for the currently selected kind's full data
   selectedKindQuery?: ResourceQueryResult
+  largeListGuard?: LargeListGuardState | null
   topPodMetrics?: TopPodMetrics[]
   topNodeMetrics?: TopNodeMetrics[]
   certExpiry?: Record<string, { expired?: boolean; daysLeft: number }>
@@ -2042,7 +2058,9 @@ export function ResourcesView({
   resourceQueries: resourceQueriesProp,
   resourceCounts: resourceCountsProp,
   resourceForbidden: resourceForbiddenProp,
+  resourceUnavailable: resourceUnavailableProp,
   selectedKindQuery: selectedKindQueryProp,
+  largeListGuard,
   topPodMetrics,
   topNodeMetrics,
   certExpiry,
@@ -3237,22 +3255,29 @@ export function ResourcesView({
   const counts = useMemo(() => {
     if (useNewCountsMode) {
       // resourceCountsProp uses "group/Kind" keys for CRDs, "Kind" for core — same format as sidebar
-      const results: Record<string, number> = {}
+      const unavailableKinds = new Set(resourceUnavailableProp ?? [])
+      const results: Record<string, number | null> = {}
       for (const resource of resourcesToCount) {
         const key = resource.group ? `${resource.group}/${resource.kind}` : resource.kind
-        results[key] = resourceCountsProp![key] ?? 0
+        if (unavailableKinds.has(key)) {
+          results[key] = null
+        } else if (key in resourceCountsProp!) {
+          results[key] = resourceCountsProp![key]
+        } else {
+          results[key] = 0
+        }
       }
       return results
     }
     // Legacy: derive counts from full query data
-    const results: Record<string, number> = {}
+    const results: Record<string, number | null> = {}
     resourcesToCount.forEach((resource, index) => {
       const data = resourceQueries[index]?.data
       const key = resource.group ? `${resource.group}/${resource.kind}` : resource.kind
       results[key] = Array.isArray(data) ? data.length : 0
     })
     return results
-  }, [useNewCountsMode, resourcesToCount, resourceCountsProp, resourceQueries])
+  }, [useNewCountsMode, resourcesToCount, resourceCountsProp, resourceUnavailableProp, resourceQueries])
 
   // Track which resource kinds returned 403 Forbidden
   const forbiddenKinds = useMemo(() => {
@@ -3987,6 +4012,7 @@ export function ResourcesView({
           apiResources={apiResourcesProp}
           resourceCounts={counts}
           resourceForbidden={Array.from(forbiddenKinds)}
+          resourceUnavailable={resourceUnavailableProp}
           pinned={pinned}
           togglePin={togglePin}
           isPinned={isPinned}
@@ -4484,6 +4510,26 @@ export function ResourcesView({
               <p className="text-theme-text-secondary font-medium">Access Restricted</p>
               <p className="text-sm mt-1">Insufficient permissions to list {selectedKind.kind} resources</p>
             </div>
+          ) : largeListGuard ? (
+            <div className="absolute inset-0 flex flex-col items-center justify-center text-theme-text-tertiary px-6 text-center">
+              <AlertTriangle className="w-8 h-8 text-amber-400 mb-2" />
+              <p className="text-theme-text-secondary font-medium">
+                {largeListGuard.reason === 'count-unavailable'
+                  ? `${largeListGuard.kind} count unavailable`
+                  : `Too many ${largeListGuard.kind.toLowerCase()} to show`}
+              </p>
+              <p className="text-sm mt-1 max-w-xl">
+                {largeListGuard.reason === 'count-unavailable'
+                  ? 'Radar could not verify this list is small enough to load. Choose a namespace or smaller namespace set to try again.'
+                  : `${largeListGuard.count?.toLocaleString()} ${largeListGuard.kind.toLowerCase()} are in the current scope. Choose a namespace or smaller namespace set to load this view.`}
+              </p>
+              <p className="text-xs mt-2 text-theme-text-disabled">
+                Radar limits full table loads to {largeListGuard.limit.toLocaleString()} resources to keep the UI responsive.
+              </p>
+              <p className="text-xs mt-2 text-theme-text-disabled">
+                Scope: {formatLargeListScope(largeListGuard.namespaces)}
+              </p>
+            </div>
           ) : filteredResources.length === 0 ? (
             <div className="absolute inset-0 flex flex-col items-center justify-center text-theme-text-tertiary">
               <p>No {selectedKind.kind} found</p>

package/src/components/resources/index.ts

@@ -16,6 +16,6 @@ export * from './resource-utils-trivy'
 export * from './resource-utils-traefik'
 export * from './resource-utils-velero'
 export { ResourcesView, ResourcesViewDataContext } from './ResourcesView'
-export type { ResourceQueryResult, ExtraColumn } from './ResourcesView'
+export type { ResourceQueryResult, ExtraColumn, LargeListGuardState } from './ResourcesView'
 export { ResourcesSidebar } from './ResourcesSidebar'
 export type { ResourcesSidebarProps, SelectedKindInfo, PinnedItem } from './ResourcesSidebar'

package/src/hooks/useKeyboardShortcuts.tsx

@@ -1,4 +1,5 @@
 import { createContext, useContext, useCallback, useEffect, useMemo, useRef, useState, type ReactNode } from 'react'
+import { isMac as isMacPlatform } from '../utils/platform'
 
 export type ShortcutScope = 'global' | 'topology' | 'resources' | 'timeline' | 'helm' | 'gitops' | 'traffic' | 'applications' | 'audit' | 'drawer'
 
@@ -78,7 +79,7 @@ interface KeyMatcher {
   altKey?: boolean
 }
 
-const isMac = typeof navigator !== 'undefined' && /Mac|iPhone|iPad/.test(navigator.platform)
+const isMac = isMacPlatform()
 
 function parseKeys(keys: string): KeyMatcher {
   // Multi-key sequence (space-separated, e.g. "g g")

package/src/utils/applications.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest'
-import { compareVersions, appGroupLagMessage, matchWorkloadAcrossInstances, foldAppGroups, identityEnvInferred, type AppGroupFoldEntry } from './applications'
+import { compareVersions, appGroupingExplainer, APP_IDENTITY_ANNOTATION, appGroupLagMessage, matchWorkloadAcrossInstances, foldAppGroups, identityEnvInferred, type AppGroupFoldEntry } from './applications'
 
 describe('compareVersions', () => {
   it('orders semver', () => {
@@ -205,3 +205,40 @@ describe('foldAppGroups', () => {
     expect(grouped.map((r) => r.kind)).toEqual(['group'])
   })
 })
+
+describe('appGroupingExplainer', () => {
+  it('declared origins fold across clusters with no fix needed', () => {
+    for (const source of ['explicit', 'argo-path', 'argo-appset', 'flux-source']) {
+      const e = appGroupingExplainer({ key: 'k', env: 'prod', confidence: 'high', evidence: '', source })
+      expect(e.folds).toBe(true)
+      expect(e.fix).toBeUndefined()
+    }
+  })
+
+  it('NAME sources stay per-cluster and tell the user how to fold', () => {
+    for (const source of ['label', 'name-stem', 'namespace', undefined]) {
+      const e = appGroupingExplainer({ key: 'k', env: 'prod', confidence: 'high', evidence: '', source })
+      expect(e.folds).toBe(false)
+      expect(e.fix).toContain(APP_IDENTITY_ANNOTATION)
+    }
+  })
+})
+
+describe('foldAppGroups pathKey disambiguation', () => {
+  const fleetEntry = (key: string, env: string, pathKey: string): AppGroupFoldEntry => ({
+    row: { key, name: 'billing', identity: { key: 'billing', env, confidence: 'high', evidence: 'e', portable: true, source: 'argo-path', pathKey } },
+    health: 'healthy', versions: [], ready: 1, desired: 1, kinds: { Deployment: 1 }, classComposition: [{ cls: 'service', count: 1 }],
+  })
+  const opts = { localScope: (e: AppGroupFoldEntry) => e.row.key }
+
+  it('folds same-name portable rows that share a pathKey', () => {
+    const rows = foldAppGroups([fleetEntry('cl-a', 'dev', 'apps/billing'), fleetEntry('cl-b', 'prod', 'apps/billing')], new Set(), false, opts)
+    expect(rows.filter((r) => r.kind === 'group').length).toBe(1)
+  })
+
+  it('does NOT fold same-name portable rows with different pathKeys (two teams, two paths)', () => {
+    const rows = foldAppGroups([fleetEntry('cl-a', 'dev', 'teamA/billing'), fleetEntry('cl-b', 'prod', 'teamB/billing')], new Set(), false, opts)
+    expect(rows.filter((r) => r.kind === 'group').length).toBe(0)
+    expect(rows.filter((r) => r.kind === 'instance').length).toBe(2)
+  })
+})

package/src/utils/applications.ts

@@ -53,6 +53,63 @@ export interface AppIdentity {
   evidence: string
   /** True when the key is backed by declared upstream identity and can group across clusters. */
   portable?: boolean
+  /** Machine-readable provenance tier (radar applications_identity.go):
+   *  explicit | argo-path | argo-appset | flux-source (declared origins, portable)
+   *  · label | name-stem | namespace (NAMEs, per-cluster). */
+  source?: string
+  /** Declared source-path stem (argo-path / flux-source only). The display `key`
+   *  is the name stem; this disambiguates same-name/different-path apps in the
+   *  portable cross-cluster fold. */
+  pathKey?: string
+}
+
+/** The user-set annotation that forces cross-cluster grouping — the canonical
+ *  answer to "how do I make this fold?" for non-GitOps apps. */
+export const APP_IDENTITY_ANNOTATION = 'app.skyhook.io/app'
+
+/** Whether a Source is a declared cross-cluster origin (mirrors the hub's
+ *  isDeclaredPortableSource). NAMEs collide across clusters and stay per-cluster. */
+export function isDeclaredAppSource(source?: string): boolean {
+  return source === 'explicit' || source === 'argo-path' || source === 'argo-appset' || source === 'flux-source'
+}
+
+/** A short label for how an app's identity was determined, by Source — the
+ *  plain-language "grouped by …" phrase shown in the identity tooltip. */
+export function appSourceLabel(source?: string): string {
+  switch (source) {
+    case 'explicit':
+      return `the ${APP_IDENTITY_ANNOTATION} annotation`
+    case 'argo-path':
+      return 'its Argo CD source path'
+    case 'argo-appset':
+      return 'its ApplicationSet (env fan-out)'
+    case 'flux-source':
+      return 'its Flux source'
+    case 'addon':
+      return 'a shared add-on name + chart/image'
+    case 'label':
+      return 'the app.kubernetes.io/name label'
+    case 'name-stem':
+      return 'a shared name + image'
+    case 'namespace':
+      return 'a shared namespace + image'
+    default:
+      return 'its workload grouping'
+  }
+}
+
+/** The explainer for "why isn't this grouped across clusters, and how do I fix
+ *  it?" — drives the per-cluster row hint. `folds` is true when the identity is a
+ *  declared origin (folds cross-cluster); otherwise `fix` says what to add. */
+export function appGroupingExplainer(identity?: AppIdentity): { folds: boolean; how: string; fix?: string } {
+  const folds = isDeclaredAppSource(identity?.source)
+  return {
+    folds,
+    how: `Grouped by ${appSourceLabel(identity?.source)}.`,
+    fix: folds
+      ? undefined
+      : `This app only has a per-cluster name, which can't prove two clusters run the same app. To fold it across clusters, set ${APP_IDENTITY_ANNOTATION} on its workloads in each cluster (same value), or deploy it via Argo CD / Flux with the environment in the source path.`,
+  }
 }
 
 export interface AppRow {
@@ -474,6 +531,12 @@ export interface FoldAppGroupsOptions<T extends AppGroupFoldEntry> {
    *  should include the cluster id so local name/repo evidence cannot merge
    *  unrelated clusters. Portable identities ignore the scope. */
   localScope?: (entry: T) => string | undefined
+  /** Per-member env slices for the env ladder. A fleet member spans several
+   *  per-cluster envs, so the host supplies them (cluster-coverage derived,
+   *  authoritative) rather than the single `identity.env` — which the hub can
+   *  stale when it joins the same overlay key across clusters. Defaults to the
+   *  member's single identity env. */
+  envsOf?: (entry: T) => Array<{ env: string; health: AppHealth }>
 }
 
 export function foldAppGroups<T extends AppGroupFoldEntry>(
@@ -489,7 +552,10 @@ export function foldAppGroups<T extends AppGroupFoldEntry>(
     if (!id) return null
     const scope = options.localScope?.(e)
     if (!scope) return id.key
-    return id.portable ? `portable:${id.key}` : `local:${scope}:${id.key}`
+    // A declared-PATH identity displays its name stem as the key but carries the
+    // path stem in pathKey; two different apps can share a name while declaring
+    // different paths, so disambiguate the portable cross-cluster fold by pathKey.
+    return id.portable ? `portable:${id.key}${id.pathKey ? `:${id.pathKey}` : ''}` : `local:${scope}:${id.key}`
   }
   const byGroup = new Map<string, T[]>()
   for (const e of entries) {
@@ -518,15 +584,20 @@ export function foldAppGroups<T extends AppGroupFoldEntry>(
     let desired = 0
     let health: AppHealth = 'unknown'
     for (const m of members) {
-      const env = m.row.identity!.env
       const v = newest(m)
-      const cur = cellMap.get(env)
-      if (!cur) {
-        cellMap.set(env, { env, health: m.health, version: v, count: 1, firstKey: m.row.key })
-      } else {
-        cur.count++
-        if ((HEALTH_RANK[m.health] ?? 0) > (HEALTH_RANK[cur.health] ?? 0)) cur.health = m.health
-        if (v && (!cur.version || compareVersions(v, cur.version) === 1)) cur.version = v
+      // A fleet member spans several per-cluster envs; the host supplies them so
+      // the ladder reflects every env, not just the member's (possibly stale)
+      // single identity env. Default: the one identity env.
+      const slices = options.envsOf?.(m) ?? [{ env: m.row.identity!.env, health: m.health }]
+      for (const slice of slices) {
+        const cur = cellMap.get(slice.env)
+        if (!cur) {
+          cellMap.set(slice.env, { env: slice.env, health: slice.health, version: v, count: 1, firstKey: m.row.key })
+        } else {
+          cur.count++
+          if ((HEALTH_RANK[slice.health] ?? 0) > (HEALTH_RANK[cur.health] ?? 0)) cur.health = slice.health
+          if (v && (!cur.version || compareVersions(v, cur.version) === 1)) cur.version = v
+        }
       }
       if ((HEALTH_RANK[m.health] ?? 0) > (HEALTH_RANK[health] ?? 0)) health = m.health
       ready += m.ready
@@ -672,3 +743,127 @@ export function newestTag(versions: string[]): string | undefined {
   }
   return best
 }
+
+// -----------------------------------------------------------------------------
+// Applications list entry model — the per-row shape the shared list core renders.
+// Discriminated on `variant` so the OSS single-cluster row and the Cloud fleet
+// row (one row spanning several clusters) carry their own fields with no loose
+// optional-superset overlap. The base carries everything the facet rail, fold,
+// counts, and sort read; the variant arms carry only what their instance-row
+// renderer needs. Both arms satisfy AppGroupFoldEntry, so foldAppGroups is shared.
+// -----------------------------------------------------------------------------
+
+export interface AppEntryBase {
+  row: AppRow
+  health: AppHealth
+  versions: string[]
+  kinds: Record<string, number>
+  workloadClass: AppWorkloadClass
+  /** Distinct contained classes — the inclusive facet-matching set. */
+  classSet: AppWorkloadClass[]
+  classComposition: { cls: AppWorkloadClass; count: number }[]
+  category: AppCategory
+  ready: number
+  desired: number
+  /** ready/desired as a fraction for sorting; -1 when nothing is desired. */
+  readyRatio: number
+  source: AppSource
+}
+
+export interface SingleAppEntry extends AppEntryBase {
+  variant: 'single'
+  namespace: string
+  namespaces: string[]
+  env: string
+  envInferred: boolean
+}
+
+/** One environment instance within a fleet row (env name + worst health across
+ *  its clusters + whether the env was inferred from the namespace). */
+export interface EnvSlice {
+  env: string
+  health: AppHealth
+  inferred: boolean
+}
+
+/** A cluster this fleet row's app runs in. */
+export interface AppClusterRef {
+  id: string
+  name: string
+  health: AppHealth
+}
+
+export interface FleetAppEntry extends AppEntryBase {
+  variant: 'fleet'
+  envs: EnvSlice[]
+  clusters: AppClusterRef[]
+  /** True when the app runs different versions across its clusters/envs. */
+  versionSkew: boolean
+}
+
+export type AppEntry = SingleAppEntry | FleetAppEntry
+
+/** Build a single-cluster list entry from a wire row. The env is resolved via
+ *  the server's identity classification (authoritative) with a namespace
+ *  heuristic fallback for plain rows. */
+export function buildSingleAppEntry(row: AppRow, discoveredEnvs?: ReadonlySet<string>): SingleAppEntry {
+  const kinds: Record<string, number> = {}
+  let ready = 0
+  let desired = 0
+  for (const wl of row.workloads || []) {
+    kinds[wl.kind] = (kinds[wl.kind] ?? 0) + 1
+    ready += wl.ready ?? 0
+    desired += wl.desired ?? 0
+  }
+  const namespace = namespaceOf(row)
+  // The server's identity classification carries the authoritative env (label/
+  // declared/discovered); plain rows fall back to the trio + discovered-token
+  // namespace heuristic.
+  const resolved = resolveEnv(undefined, namespace, discoveredEnvs)
+  const env = row.identity?.env ?? resolved.env
+  const inferred = row.identity ? identityEnvInferred(row.identity) : resolved.inferred
+  return {
+    variant: 'single',
+    row,
+    health: healthOf(row.health),
+    versions: Array.from(new Set((row.versions || []).filter(Boolean))),
+    namespace,
+    namespaces: namespacesOf(row),
+    env,
+    envInferred: inferred,
+    kinds,
+    workloadClass: workloadClassOf(row.workload_class),
+    classSet: classSetOf(row),
+    classComposition: classCompositionOf(row),
+    category: categoryOf(row.category),
+    ready,
+    desired,
+    readyRatio: desired > 0 ? ready / desired : -1,
+    source: sourceOf(row.tier),
+  }
+}
+
+/** The text an entry matches free-text search against — name, key, namespace,
+ *  source/class/category labels, versions, env, workload kinds + identity. Pure
+ *  and exported so the list core and tests share one definition. */
+export function searchTextForEntry(e: AppEntry): string {
+  const workloadText = (e.row.workloads || []).flatMap((wl) => [wl.kind, wl.namespace, wl.name, wl.version])
+  const envParts = e.variant === 'single' ? [e.env || 'unlabeled'] : e.envs.map((s) => s.env || 'unlabeled')
+  const nsParts = e.variant === 'single' ? [e.namespace] : e.clusters.map((c) => c.name)
+  return [
+    e.row.name,
+    e.row.key,
+    ...nsParts,
+    SOURCE_META[e.source].label,
+    CLASS_META[e.workloadClass].label,
+    ...e.classSet.map((c) => CLASS_META[c].label),
+    CATEGORY_META[e.category].label,
+    ...e.versions,
+    ...envParts,
+    ...Object.keys(e.kinds),
+    ...workloadText,
+  ]
+    .filter(Boolean)
+    .join(' ')
+    .toLowerCase()
+}

package/src/utils/platform.ts

@@ -0,0 +1,4 @@
+/** True when running on a macOS / iOS platform (drives ⌘ vs Ctrl conventions). */
+export function isMac(): boolean {
+  return typeof navigator !== 'undefined' && /Mac|iPhone|iPad/.test(navigator.platform)
+}