feat(ui): warn visitors when the chain data on screen is not current

Completes the health work: /api/health knew the node had fallen behind, but
every page still rendered a plausible height with no hint that it was an hour
stale. The banner is what makes that visible to someone who is not watching the
API.

Two judgement calls are deliberate. A one- or two-block lag stays silent —
that is ordinary propagation, and a banner that appears every few minutes
teaches people to ignore it, which leaves us exactly where we started. And a
503 from /api/health is parsed rather than treated as a failed request: that
status IS the answer when the node is behind, so discarding it would swallow
the one case the endpoint exists to report.

Strings are added in English and Spanish; the other six locales fall back to
English until translated, which the i18n layer already handles.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: NateIsern

src/components/layout.tsx

@@ -2,6 +2,7 @@ import { Outlet } from 'react-router-dom'
 import { AppSidebar } from './app-sidebar'
 import { SidebarInset, SidebarProvider } from './ui/sidebar'
 import { SiteHeader } from './site/header'
+import { NodeHealthBanner } from './node-health-banner'
 import { PWAInstallPrompt } from './pwa-install-prompt'
 import { Toaster } from './ui/sonner'
 
@@ -12,6 +13,7 @@ export function Layout() {
         <AppSidebar />
         <SidebarInset>
           <SiteHeader />
+          <NodeHealthBanner />
           <div className="flex flex-1 flex-col gap-4 p-3 pt-4 sm:p-4 md:p-6 lg:p-8">
             <Outlet />
           </div>

src/components/node-health-banner.tsx

@@ -0,0 +1,42 @@
+import { AlertTriangle } from 'lucide-react'
+import { useNodeHealth } from '@/hooks/use-node-health'
+import { decideHealthBanner } from '@/lib/node-health-banner'
+import { useTranslations } from '@/lib/i18n'
+import { cn } from '@/lib/utils'
+
+/**
+ * Tells the visitor when the chain data on screen may not be current.
+ *
+ * Without this, a node that stopped following the chain looks identical to a
+ * healthy one: every page renders a plausible height and nothing indicates it
+ * is an hour stale. Renders nothing at all while the node is on the tip — see
+ * `decideHealthBanner` for when it is considered worth interrupting for.
+ */
+export function NodeHealthBanner() {
+  const t = useTranslations('nodeHealth')
+  const { data, isLoading } = useNodeHealth()
+  const decision = decideHealthBanner(isLoading ? undefined : data)
+
+  if (!decision) {
+    return null
+  }
+
+  return (
+    <div
+      role="status"
+      aria-live="polite"
+      className={cn(
+        'flex items-center gap-2 border-b px-3 py-2 text-sm sm:px-4 md:px-6 lg:px-8',
+        decision.tone === 'danger'
+          ? 'border-destructive/30 bg-destructive/10 text-destructive'
+          : 'border-amber-500/30 bg-amber-500/10 text-amber-700 dark:text-amber-400',
+      )}
+    >
+      <AlertTriangle className="size-4 shrink-0" aria-hidden="true" />
+      <span>
+        {t(decision.messageKey)}
+        {decision.lagBlocks > 0 ? ` ${t('lagSuffix').replace('{blocks}', String(decision.lagBlocks))}` : ''}
+      </span>
+    </div>
+  )
+}

src/hooks/use-node-health.ts

@@ -0,0 +1,41 @@
+import { useQuery, type UseQueryResult } from '@tanstack/react-query'
+import { useNetwork } from '@/contexts/network-context'
+import type { NodeHealthSummary } from '@/lib/node-health-banner'
+
+/**
+ * Reads `/api/health` — whether the tip the explorer is serving is still the
+ * chain's tip.
+ *
+ * Note the deliberate handling of 503: that status IS the answer when the node
+ * has fallen behind, and its body carries the detail. Treating a non-2xx as a
+ * failed request (the pattern used elsewhere for optional data) would swallow
+ * exactly the case this endpoint exists to report. Only a genuinely unreachable
+ * endpoint resolves to `null`.
+ */
+export function useNodeHealth(): UseQueryResult<NodeHealthSummary | null> {
+  const { currentNetwork } = useNetwork()
+
+  return useQuery<NodeHealthSummary | null>({
+    queryKey: ['node-health', currentNetwork],
+    queryFn: async (): Promise<NodeHealthSummary | null> => {
+      try {
+        const response = await fetch(`/api/health?network=${currentNetwork}`, {
+          headers: { Accept: 'application/json' },
+        })
+        const body = (await response.json()) as Partial<NodeHealthSummary> | null
+        if (!body || typeof body.status !== 'string') {
+          return null
+        }
+        return { status: body.status, lagBlocks: Number(body.lagBlocks ?? 0) }
+      } catch {
+        // Network error / unparseable body: health is not established.
+        return null
+      }
+    },
+    // Fixed cadence: this is an availability probe, not live chain data, and it
+    // must keep polling at the same rate when the chain has gone quiet.
+    refetchInterval: 60_000,
+    staleTime: 30_000,
+    retry: 1,
+  })
+}

src/lib/node-health-banner.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, it } from 'vitest'
+import { decideHealthBanner, LAGGING_BANNER_THRESHOLD } from './node-health-banner'
+
+/**
+ * The banner is the user-facing half of /api/health: it exists so a visitor is
+ * never shown a frozen chain that looks current. It must be loud when we are
+ * demonstrably behind and silent otherwise — a banner that cries wolf during
+ * ordinary block propagation gets ignored, which is the same failure as not
+ * having one.
+ */
+
+describe('decideHealthBanner', () => {
+  it('says nothing when the node is on the chain tip', () => {
+    expect(decideHealthBanner({ status: 'ok', lagBlocks: 0 })).toBeNull()
+  })
+
+  it('says nothing while the health of the node is still unknown to the page', () => {
+    expect(decideHealthBanner(undefined)).toBeNull()
+  })
+
+  it('stays silent for a one-block lag, which is ordinary propagation', () => {
+    expect(decideHealthBanner({ status: 'lagging', lagBlocks: 1 })).toBeNull()
+  })
+
+  it('warns once the lag grows past the threshold', () => {
+    const decision = decideHealthBanner({ status: 'lagging', lagBlocks: LAGGING_BANNER_THRESHOLD })
+    expect(decision).not.toBeNull()
+    expect(decision?.tone).toBe('warning')
+    expect(decision?.messageKey).toBe('lagging')
+  })
+
+  it('raises a danger banner when the node has stopped following the chain', () => {
+    const decision = decideHealthBanner({ status: 'stalled', lagBlocks: 69 })
+    expect(decision?.tone).toBe('danger')
+    expect(decision?.messageKey).toBe('stalled')
+    expect(decision?.lagBlocks).toBe(69)
+  })
+
+  it('warns when health cannot be established rather than staying silent', () => {
+    const decision = decideHealthBanner({ status: 'unknown', lagBlocks: 0 })
+    expect(decision?.tone).toBe('warning')
+    expect(decision?.messageKey).toBe('unknown')
+  })
+
+  it('warns when the health endpoint itself cannot be reached', () => {
+    const decision = decideHealthBanner(null)
+    expect(decision?.tone).toBe('warning')
+    expect(decision?.messageKey).toBe('unreachable')
+  })
+})

src/lib/node-health-banner.ts

@@ -0,0 +1,59 @@
+/**
+ * Should the page tell the visitor that the chain data may not be current?
+ *
+ * The server decides WHETHER the node is healthy (`/api/health`); this decides
+ * whether that verdict is worth interrupting the visitor for. The distinction
+ * matters: a node one block behind during normal propagation is not an outage,
+ * and a banner that appears every few minutes teaches people to ignore it —
+ * which leaves us exactly where we started, serving a frozen chain that looks
+ * current.
+ */
+
+export type NodeHealthStatus = 'ok' | 'lagging' | 'stalled' | 'unknown'
+
+export interface NodeHealthSummary {
+  status: NodeHealthStatus
+  lagBlocks: number
+}
+
+export interface HealthBannerDecision {
+  tone: 'warning' | 'danger'
+  /** Suffix of the `nodeHealth.*` translation key to render. */
+  messageKey: 'lagging' | 'stalled' | 'unknown' | 'unreachable'
+  lagBlocks: number
+}
+
+/** Blocks behind before an otherwise-healthy lag is worth mentioning. */
+export const LAGGING_BANNER_THRESHOLD = 3
+
+/**
+ * @param health the parsed `/api/health` body, `null` when the endpoint could
+ *   not be reached, or `undefined` while the first request is still in flight.
+ */
+export function decideHealthBanner(
+  health: NodeHealthSummary | null | undefined,
+): HealthBannerDecision | null {
+  // Nothing known yet — say nothing rather than flash a warning on every load.
+  if (health === undefined) {
+    return null
+  }
+
+  // The health endpoint is the one thing that reports staleness; if it cannot be
+  // reached we cannot claim the data is current.
+  if (health === null) {
+    return { tone: 'warning', messageKey: 'unreachable', lagBlocks: 0 }
+  }
+
+  switch (health.status) {
+    case 'stalled':
+      return { tone: 'danger', messageKey: 'stalled', lagBlocks: health.lagBlocks }
+    case 'unknown':
+      return { tone: 'warning', messageKey: 'unknown', lagBlocks: health.lagBlocks }
+    case 'lagging':
+      return health.lagBlocks >= LAGGING_BANNER_THRESHOLD
+        ? { tone: 'warning', messageKey: 'lagging', lagBlocks: health.lagBlocks }
+        : null
+    default:
+      return null
+  }
+}

src/messages/en.json

@@ -1,4 +1,9 @@
 {
+  "nodeHealth.stalled": "This explorer's node has stopped following the chain. The data shown is out of date.",
+  "nodeHealth.lagging": "This explorer's node is catching up. Recent blocks may be missing.",
+  "nodeHealth.unknown": "Cannot confirm this explorer's node is on the chain tip. The data shown may be out of date.",
+  "nodeHealth.unreachable": "Cannot check whether this explorer's data is current.",
+  "nodeHealth.lagSuffix": "({blocks} blocks behind)",
   "nav.home": "Home",
   "nav.search": "Search",
   "nav.blocks": "Blocks",

src/messages/es.json

@@ -1,4 +1,9 @@
 {
+  "nodeHealth.stalled": "El nodo de este explorador ha dejado de seguir la cadena. Los datos mostrados están desactualizados.",
+  "nodeHealth.lagging": "El nodo de este explorador se está poniendo al día. Puede que falten bloques recientes.",
+  "nodeHealth.unknown": "No se puede confirmar que el nodo de este explorador esté en la punta de la cadena. Los datos pueden estar desactualizados.",
+  "nodeHealth.unreachable": "No se puede comprobar si los datos de este explorador están actualizados.",
+  "nodeHealth.lagSuffix": "({blocks} bloques por detrás)",
   "nav.home": "Inicio",
   "nav.search": "Buscar",
   "nav.blocks": "Bloques",