From ad866f087cd55fea1f40a9b888ac5b9ca4e44ec9 Mon Sep 17 00:00:00 2001
From: Coredevjay <coredevjay@gmail.com>
Date: Wed, 21 Oct 2026 10:45:19 +0000
Subject: [PATCH] feat(realtime): event bus, fidelity tiers, loading states and
 /status page

Closes #303
Closes #304
Closes #309
Closes #317

- typed realtime event bus with ordering, isolation and snapshot replay
- fidelity tiers with signal detection, hysteresis and topic diffs
- RealtimeView skeleton/state matrix primitives
- /status route (REST snapshot + realtime), linked from Navbar and footer
- restore empty Navbar.tsx and truncated globals.css from before 7a01fc8
---
 README.md                                    |   1 +
 docs/realtime-fidelity.md                    |  34 ++
 src/app/globals.css                          | 356 +++++++++++++++++++
 src/app/status/page.tsx                      |  30 ++
 src/components/layout/Footer.tsx             |   1 +
 src/components/layout/Navbar.tsx             | 152 ++++++++
 src/components/status/ProtocolStatusView.tsx | 106 ++++++
 src/components/ui/RealtimeSkeletons.tsx      |  80 +++++
 src/components/ui/index.ts                   |   1 +
 src/hooks/useRealtimeTopic.ts                |  57 +++
 src/lib/realtime/bus.ts                      |  74 ++++
 src/lib/realtime/client.ts                   |  67 +++-
 src/lib/realtime/fidelity.ts                 | 237 ++++++++++++
 src/lib/realtime/index.ts                    |   4 +
 src/lib/realtime/realtime.test.ts            |  67 ++++
 src/lib/realtime/status.ts                   |  13 +
 src/lib/realtime/topics.ts                   |  35 ++
 17 files changed, 1312 insertions(+), 3 deletions(-)
 create mode 100644 docs/realtime-fidelity.md
 create mode 100644 src/app/status/page.tsx
 create mode 100644 src/components/status/ProtocolStatusView.tsx
 create mode 100644 src/components/ui/RealtimeSkeletons.tsx
 create mode 100644 src/hooks/useRealtimeTopic.ts
 create mode 100644 src/lib/realtime/bus.ts
 create mode 100644 src/lib/realtime/fidelity.ts
 create mode 100644 src/lib/realtime/index.ts
 create mode 100644 src/lib/realtime/realtime.test.ts
 create mode 100644 src/lib/realtime/status.ts
 create mode 100644 src/lib/realtime/topics.ts

diff --git a/README.md b/README.md
index 780aba7..89f1983 100644
--- a/README.md
+++ b/README.md
@@ -29,6 +29,7 @@ this policy.
 | `/` | Landing — live oracle status, recent payouts, protocol stats |
 | `/cover` | Policy purchase flow |
 | `/provide` | LP capital provision + pool allocation |
+| `/status` | Protocol status, maintenance windows and incidents (REST snapshot + realtime) |
 
 ## Quick start
 
diff --git a/docs/realtime-fidelity.md b/docs/realtime-fidelity.md
new file mode 100644
index 0000000..deda9c2
--- /dev/null
+++ b/docs/realtime-fidelity.md
@@ -0,0 +1,34 @@
+# Realtime runbook
+
+## Event bus (`src/lib/realtime/bus.ts`)
+The client decodes inbound `{ topic, payload }` messages and publishes them to a module-scoped typed bus. Consumers (hooks, stores, analytics) subscribe to the bus via `useRealtimeTopic`, never to the socket.
+
+- Topic ids and payload types live in `topics.ts`.
+- Snapshot topics replay their latest value to late subscribers (`getSnapshot`).
+- Per-topic arrival order is preserved; re-entrant publishes are queued, not nested.
+- A throwing handler is caught and logged (no payload) and never blocks other handlers.
+- Max 100 handlers per topic; subscribing the same handler twice (StrictMode) is a no-op.
+
+## View status matrix (`RealtimeView`)
+| status | shows | indicator |
+|---|---|---|
+| `empty` | skeleton (sized to final content) | — |
+| `live` | data | Live |
+| `disconnected` | last data | Offline — showing last values |
+| `reconnecting` | last data | Reconnecting… |
+| `polling` | data | Updating periodically (realtime off) |
+
+Skeletons render only for `empty`; a refresh of present data never re-shows them. Shimmer follows the global reduced-motion policy.
+
+## Fidelity tiers (`src/lib/realtime/fidelity.ts`)
+| tier | topics | coalescing | transport |
+|---|---|---|---|
+| `full` | oracle_update, protocol_status, network_health | none | websocket |
+| `lite` | oracle_update, protocol_status | oracle_update ≥ 5 s | websocket |
+| `minimal` | protocol_status (via polling) | — | polling |
+
+Selection (`selectTier`): `saveData` / `2g` / battery < 15% (not charging) → `minimal`; `3g`, battery < 30%, ≤ 2 GB memory or ≤ 2 cores → `lite`; otherwise `full`. Missing signals assume unconstrained; SSR renders `full`.
+
+Hysteresis: a downgrade applies after 3 s of a stable candidate, an upgrade after 30 s. Tier changes are sent to the client as subscribe/unsubscribe deltas (`syncTopics`), and the full set is re-sent on every reconnect. Topics registered with `critical: true` in `useRealtimeTopic` are never dropped by a downgrade.
+
+Manual override: `fidelityController.setOverride("lite" | null)` (dev console / panel); the active tier is `fidelityController.getTier()`.
diff --git a/src/app/globals.css b/src/app/globals.css
index e69de29..2ddc5f6 100644
--- a/src/app/globals.css
+++ b/src/app/globals.css
@@ -0,0 +1,356 @@
+@import url("https://fonts.googleapis.com/css2?family=Syne:wght@400;500;600;700;800&family=Inter:wght@300;400;500;600&family=JetBrains+Mono:wght@400;500&display=swap");
+
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+/* ── Refract Design Tokens ─────────────────────────────────────────────────── */
+  --pm-text:    237 233 248;
+  --pm-muted:   123 111 168;
+  --pm-muted-2: 74 64 112;
+
+  /* Alph
+
+  /* Brand — violet */
+  --pm-violet:     139 92 246;
+  --pm-violet-2:   124 58 237;
+  --pm-violet-dim: 139 92 246;
+  --pm-violet-glow: 139 92 246;
+
+  /* Status */
+  --pm-safe:   16 185 129;   /* covered */
+  --pm-risk:   245 158 11;   /* at risk */
+  --pm-danger: 239 68 68;    /* triggered */
+
+  /* Text */
+  --pm-text:    237 233 248;
+  --pm-muted:   123 111 168;
+  --pm-muted-2: 74 64 112;
+
+  /* Alpha levels for tokens that are always used at a fixed opacity */
+  --pm-border-a:     0.15;
+  --pm-border-2-a:   0.3;
+  --pm-violet-dim-a: 0.12;
+  --pm-safe-bg-a:    0.1;
+  --pm-risk-bg-a:    0.1;
+  --pm-danger-bg-a:  0.1;
+
+  /* Radius */
+  --pm-r:    8px;
+  --pm-r-lg: 16px;
+  --pm-r-xl: 24px;
+
+  /* Motion tokens — named durations & easings (single source of truth).
+     All CSS animations/transitions should reference these instead of
+     scattering literal durations across files. */
+  --pm-duration-fast:   0.15s;
+  --pm-duration-base:   0.2s;
+  --pm-duration-slow:   0.4s;
+  --pm-duration-slower: 0.5s;
+  --pm-duration-spin:   0.6s;
+  --pm-duration-pulse:  2s;
+  --pm-ease-standard:   ease;
+  --pm-ease-out:        ease-out;
+  --pm-ease-linear:     linear;
+}
+
+/* ── Base ────────────────────────────────────────────────────────────────── */
+*, *::before, *::after { box-sizing: border-box; }
+html, body { background: rgb(var(--pm-bg)); color: rgb(var(--pm-text)); }
+
+body {
+  font-family: "Inter", system-ui, sans-serif;
+  font-size: 14px;
+  line-height: 1.6;
+  -webkit-font-smoothing: antialiased;
+  min-height: 100vh;
+}
+
+.font-display { font-family: "Syne", sans-serif; }
+.font-mono    { font-family: "JetBrains Mono", monospace; }
+
+/* ── Scrollbar ───────────────────────────────────────────────────────────── */
+::-webkit-scrollbar { width: 4px; }
+::-webkit-scrollbar-track { background: rgb(var(--pm-surface)); }
+::-webkit-scrollbar-thumb { background: rgb(var(--pm-surface-3)); border-radius: 2px; }
+
+/* ── Layout utilities ────────────────────────────────────────────────────── */
+.pm-panel {
+  background: rgb(var(--pm-surface));
+  border: 1px solid rgb(var(--pm-border) / var(--pm-border-a));
+  border-radius: var(--pm-r-lg);
+}
+
+.pm-divider { border: none; border-top: 1px solid rgb(var(--pm-border) / var(--pm-border-a)); }
+
+/* ── Status tags ─────────────────────────────────────────────────────────── */
+.pm-tag {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  padding: 3px 10px;
+  border-radius: 100px;
+  font-size: 11px;
+  font-weight: 600;
+  letter-spacing: 0.03em;
+}
+
+.pm-tag-safe   { background: rgb(var(--pm-safe) / var(--pm-safe-bg-a));       color: rgb(var(--pm-safe)); }
+.pm-tag-risk   { background: rgb(var(--pm-risk) / var(--pm-risk-bg-a));       color: rgb(var(--pm-risk)); }
+.pm-tag-danger { background: rgb(var(--pm-danger) / var(--pm-danger-bg-a));   color: rgb(var(--pm-danger)); }
+.pm-tag-violet { background: rgb(var(--pm-violet) / var(--pm-violet-dim-a));  color: rgb(var(--pm-violet)); }
+
+/* ── Buttons ─────────────────────────────────────────────────────────────── */
+.pm-btn {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: 8px;
+  padding: 10px 20px;
+  border-radius: var(--pm-r);
+  font-size: 14px;
+  font-weight: 600;
+  cursor: pointer;
+  border: none;
+  outline: none;
+  transition: all var(--pm-duration-base);
+  white-space: nowrap;
+}
+
+.pm-btn-primary {
+  background: rgb(var(--pm-violet));
+  color: white;
+}
+.pm-btn-primary:hover { background: rgb(var(--pm-violet-2)); transform: translateY(-1px); }
+
+.pm-btn-outline {
+  background: transparent;
+  color: rgb(var(--pm-violet));
+  border: 1px solid rgb(var(--pm-border-2) / var(--pm-border-2-a));
+}
+.pm-btn-outline:hover { background: rgb(var(--pm-violet) / var(--pm-violet-dim-a)); }
+
+.pm-btn-ghost {
+  background: transparent;
+  color: rgb(var(--pm-muted));
+  border: 1px solid rgb(var(--pm-border) / var(--pm-border-a));
+}
+.pm-btn-ghost:hover { color: rgb(var(--pm-text)); border-color: rgb(var(--pm-border-2) / var(--pm-border-2-a)); }
+
+/* ── Inputs ──────────────────────────────────────────────────────────────── */
+.pm-input {
+  width: 100%;
+  background: rgb(var(--pm-surface-2));
+  border: 1px solid rgb(var(--pm-border) / var(--pm-border-a));
+  border-radius: var(--pm-r);
+  color: rgb(var(--pm-text));
+  padding: 10px 14px;
+  font-size: 14px;
+  outline: none;
+  transition: border-color var(--pm-duration-base);
+}
+.pm-input:focus { border-color: rgb(var(--pm-violet)); }
+.pm-input::placeholder { color: rgb(var(--pm-muted-2)); }
+
+/* ── Slider ──────────────────────────────────────────────────────────────── */
+.pm-slider {
+  -webkit-appearance: none;
+  width: 100%;
+  height: 4px;
+  background: linear-gradient(
+    to right,
+    rgb(var(--pm-violet)) var(--pct, 50%),
+    rgb(var(--pm-surface-3)) var(--pct, 50%)
+  );
+  border-radius: 2px;
+  cursor: pointer;
+  outline: none;
+}
+.pm-slider::-webkit-slider-thumb {
+  -webkit-appearance: none;
+  width: 16px;
+  height: 16px;
+  background: rgb(var(--pm-violet));
+  border-radius: 50%;
+  cursor: pointer;
+  box-shadow: 0 0 0 4px rgb(var(--pm-violet) / 0.2);
+}
+
+/* ── Risk heat gradient (signature element) ──────────────────────────────── */
+.risk-heat-low    { background: linear-gradient(135deg, rgb(var(--pm-safe) / 0.08), transparent 70%); }
+.risk-heat-medium { background: linear-gradient(135deg, rgb(var(--pm-risk) / 0.08), transparent 70%); }
+.risk-heat-high   { background: linear-gradient(135deg, rgb(var(--pm-danger) / 0.08),  transparent 70%); }
+
+/* ── Motion ────────────────────────────────────────────────────────────────
+   Documented motion policy for Refract.
+
+   Decision (issue #37): framer-motion is NOT adopted. It was a declared
+   production dependency with zero imports, so it has been removed from
+   package.json and the README stack. All motion is expressed with the CSS
+   keyframes/transitions below, driven by the named tokens in :root.
+
+   Reduced-motion policy (single documented rule):
+   - JS side: `usePrefersReducedMotion` (src/hooks/usePrefersReducedMotion.ts)
+     is the single source of truth for components that need to branch in JS.
+   - CSS side: the `@media (prefers-reduced-motion: reduce)` override at the
+     bottom of this file is the belt-and-braces fallback that neutralises
+     every animation/transition declared here.
+   No component may animate without going through one of these two paths.
+   Motion is never required to convey state (e.g. the Counter value is
+   readable instantly under reduced motion).
+   ─────────────────────────────────────────────────────────────────────────── */
+
+/* ── Animations ──────────────────────────────────────────────────────────── */
+/* `fadeUp` is defined once here (issue #39); tailwind.config.ts references
+ * this keyframe via `animation.fade-up` instead of redeclaring it, so this
+ * file is the single source of truth for the animation. */
+@keyframes fadeUp {
+  from { opacity: 0; transform: translateY(16px); }
+  to   { opacity: 1; transform: translateY(0); }
+}
+.animate-fade-up { animation: fadeUp var(--pm-duration-slow) var(--pm-ease-standard) forwards; }
+
+@keyframes shieldPulse {
+  0%   { box-shadow: 0 0 0 0 rgb(var(--pm-violet) / 0.4); }
+  70%  { box-shadow: 0 0 0 16px rgb(var(--pm-violet) / 0); }
+  100% { box-shadow: 0 0 0 0 rgb(var(--pm-violet) / 0); }
+}
+.pm-glow { animation: shieldPulse var(--pm-duration-pulse) infinite; }
+
+@keyframes spin {
+  to { transform: rotate(360deg); }
+}
+.pm-spin { animation: spin var(--pm-duration-spin) var(--pm-ease-linear) infinite; }
+
+/* pmShimmer supersedes the old `shimmer` keyframes that used to live in
+   tailwind.config.ts (issue #39) — one shimmer source only. */
+@keyframes pmShimmer {
+  0%   { background-position: -200% 0; }
+  100% { background-position: 200% 0; }
+}
+.pm-shimmer {
+  background: linear-gradient(
+    90deg,
+    var(--pm-surface-2) 25%,
+    var(--pm-surface-3) 50%,
+    var(--pm-surface-2) 75%
+  );
+  background-size: 200% 100%;
+  animation: pmShimmer 1.4s var(--pm-ease-linear) infinite;
+}
+
+/* ── Coverage card ───────────────────────────────────────────────────────── */
+.coverage-card {
+  background: rgb(var(--pm-surface));
+  border: 1px solid rgb(var(--pm-border) / var(--pm-border-a));
+  border-radius: var(--pm-r-xl);
+  padding: 28px;
+  cursor: pointer;
+  transition: all 0.25s;
+  position: relative;
+  overflow: hidden;
+}
+.coverage-card:hover {
+  border-color: rgb(var(--pm-border-2) / var(--pm-border-2-a));
+  transform: translateY(-2px);
+  box-shadow: 0 8px 32px rgb(var(--pm-violet) / 0.12);
+}
+.coverage-card.selected {
+  border-color: rgb(var(--pm-violet));
+  background: rgb(var(--pm-surface-2));
+}
+
+/* ── Pool gauge ──────────────────────────────────────────────────────────── */
+.pool-gauge-track {
+  width: 100%;
+  height: 6px;
+  background: rgb(var(--pm-surface-3));
+  border-radius: 3px;
+  overflow: hidden;
+}
+.pool-gauge-fill {
+  height: 100%;
+  border-radius: 3px;
+  background: linear-gradient(90deg, rgb(var(--pm-violet)), rgb(var(--pm-safe)));
+  transition: width 0.5s ease;
+}
+
+/* ── Noise overlay (subtle texture) ─────────────────────────────────────── */
+.pm-noise::before {
+  content: "";
+  position: absolute;
+  inset: 0;
+  background-image: url("data:image/svg+xml,%3Csvg viewBox='0 0 200 200' xmlns='http://www.w3.org/2000/svg'%3E%3Cfilter id='noise'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.65' numOctaves='3' stitchTiles='stitch'/%3E%3C/filter%3E%3Crect width='100%25' height='100%25' filter='url(%23noise)' opacity='0.03'/%3E%3C/svg%3E");
+  pointer-events: none;
+  opacity: 0.4;
+}
+
+/* ── Accessibility: focus states ────────────────────────────────────────── */
+a, button, input, [tabindex] {
+  outline: none;
+}
+a:focus-visible,
+button:focus-visible,
+input:focus-visible,
+[tabindex]:focus-visible {
+  outline: 2px solid rgb(var(--pm-violet));
+  outline-offset: 2px;
+  border-radius: 4px;
+}
+
+.pm-skip-link {
+  position: absolute;
+  left: 16px;
+  top: -48px;
+  z-index: 100;
+  background: rgb(var(--pm-violet));
+  color: #fff;
+  padding: 10px 18px;
+  border-radius: var(--pm-r);
+  font-size: 13px;
+  font-weight: 600;
+  text-decoration: none;
+  transition: top 0.15s ease;
+}
+.pm-skip-link:focus {
+  top: 16px;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+    scroll-behavior: auto !important;
+  }
+}
+
+/* ── Loading skeleton ────────────────────────────────────────────────────── */
+
+x 18px;
+  border-radius: var(--pm-r);
+  font-size: 13px;
+  font-weight: 600;
+  text-decoration: none;
+  transition: top 0.15s ease;
+}
+.pm-skip-link:focus {
+  top: 16px;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+    scroll-behavior: auto !important;
+  }
+}
+
+/* ── Loading skeleton ────────────────────────────────────────────────────── */
+
+.pm-skeleton {
+  background: linear-gradient(90deg, var(--pm-surface-2) 25%, var(--pm-surface-3) 50%, var(--pm-surface-2) 75%);
+  background-size: 200% 100%;
+  animation: pmShimmer 1.4s var(--pm-ease-linear) infinite;
+}
diff --git a/src/app/status/page.tsx b/src/app/status/page.tsx
new file mode 100644
index 0000000..893759e
--- /dev/null
+++ b/src/app/status/page.tsx
@@ -0,0 +1,30 @@
+import type { Metadata } from "next";
+import { Navbar, Footer } from "@/components/layout";
+import { Container } from "@/components/ui";
+import { ProtocolStatusView } from "@/components/status/ProtocolStatusView";
+import { fetchProtocolStatus } from "@/lib/realtime/status";
+
+export const metadata: Metadata = {
+  title: "Status",
+  description: "Current Refract Protocol status, scheduled maintenance and recent incidents.",
+};
+
+export const dynamic = "force-dynamic";
+
+export default async function StatusPage() {
+  const initial = await fetchProtocolStatus();
+  return (
+    <>
+      <Navbar />
+      <main className="py-12">
+        <Container>
+          <h1 className="mb-8 font-display text-3xl font-extrabold text-pm-text">
+            Protocol status
+          </h1>
+          <ProtocolStatusView initial={initial} />
+        </Container>
+      </main>
+      <Footer />
+    </>
+  );
+}
diff --git a/src/components/layout/Footer.tsx b/src/components/layout/Footer.tsx
index 3325583..c23f2b7 100644
--- a/src/components/layout/Footer.tsx
+++ b/src/components/layout/Footer.tsx
@@ -5,6 +5,7 @@ const FOOTER_LINKS = [
   { label: "Provide Capital", href: "/provide" },
   { label: "Dashboard", href: "/dashboard" },
   { label: "Contracts", href: "/transparency" },
+  { label: "Status", href: "/status" },
   { label: "GitHub", href: "https://github.com/Refract-Protocol" },
 ];
 
diff --git a/src/components/layout/Navbar.tsx b/src/components/layout/Navbar.tsx
index e69de29..27c549b 100644
--- a/src/components/layout/Navbar.tsx
+++ b/src/components/layout/Navbar.tsx
@@ -0,0 +1,152 @@
+"use client";
+
+import { useEffect, useRef, useState } from "react";
+import Link from "next/link";
+import { usePathname } from "next/navigation";
+import { cn } from "@/lib/cn";
+
+const NAV_LINKS = [
+  { label: "Coverage", href: "/cover" },
+  { label: "Provide Capital", href: "/provide" },
+  { label: "Dashboard", href: "/dashboard" },
+  { label: "Status", href: "/status" },
+];
+
+interface NavbarProps {
+  /** Right-aligned slot, typically the wallet connect button. */
+  right?: React.ReactNode;
+}
+
+export function Navbar({ right }: NavbarProps) {
+  const pathname = usePathname();
+  const [menuOpen, setMenuOpen] = useState(false);
+  const menuButtonRef = useRef<HTMLButtonElement>(null);
+
+  useEffect(() => {
+    if (!menuOpen) return;
+    function onEscape(e: KeyboardEvent) {
+      if (e.key !== "Escape") return;
+      setMenuOpen(false);
+      menuButtonRef.current?.focus();
+    }
+    document.addEventListener("keydown", onEscape);
+    return () => document.removeEventListener("keydown", onEscape);
+  }, [menuOpen]);
+
+  return (
+    <nav
+      className="sticky top-0 z-50 border-b border-pm-border bg-[rgba(7,5,15,0.85)] backdrop-blur-xl"
+      aria-label="Primary"
+    >
+      <div className="mx-auto flex h-16 max-w-[1200px] items-center justify-between px-4 sm:px-6 lg:px-7">
+        <div className="flex items-center gap-9">
+          <Link href="/" className="flex items-center gap-2.5" aria-label="Refract home">
+            <div
+              className="flex h-8 w-8 items-center justify-center rounded-lg"
+              style={{
+                background: "linear-gradient(135deg,#8b5cf6,#5b21b6)",
+                boxShadow: "0 0 16px rgba(139,92,246,0.4)",
+              }}
+            >
+              <span className="text-base text-white" aria-hidden="true">⬡</span>
+            </div>
+            <span className="font-display text-lg font-extrabold tracking-tight text-pm-text">Refract</span>
+          </Link>
+
+          <div className="hidden items-center gap-8 md:flex">
+            {NAV_LINKS.map((item) => {
+              const active = pathname === item.href;
+              return (
+                <Link
+                  key={item.label}
+                  href={item.href}
+                  aria-current={active ? "page" : undefined}
+                  className={cn(
+                    "text-sm font-medium transition-colors",
+                    active ? "text-pm-violet" : "text-pm-text/55 hover:text-pm-text"
+                  )}
+                >
+                  {item.label}
+                </Link>
+              );
+            })}
+          </div>
+        </div>
+
+        <div className="hidden items-center gap-3 md:flex">
+          <button
+            type="button"
+            onClick={() => window.dispatchEvent(new CustomEvent("refract:open-command-palette"))}
+            className="flex items-center gap-2 rounded-lg border border-white/[0.08] bg-white/[0.03] px-3 py-1.5 text-xs text-pm-text/55 transition-all hover:border-pm-violet/30 hover:bg-pm-violet/[0.05] hover:text-pm-text"
+            aria-label="Search and quick commands (Cmd+K)"
+          >
+            <span>Search</span>
+            <kbd className="rounded border border-white/[0.1] bg-white/[0.04] px-1.5 py-0.5 text-[10px] font-mono text-pm-text/40">
+              ⌘K
+            </kbd>
+          </button>
+          {right}
+        </div>
+
+        <button
+          ref={menuButtonRef}
+          type="button"
+          className="flex h-9 w-9 items-center justify-center rounded-md border border-pm-border text-pm-text md:hidden"
+          aria-expanded={menuOpen}
+          aria-controls="mobile-nav"
+          aria-label={menuOpen ? "Close menu" : "Open menu"}
+          onClick={() => setMenuOpen((v) => !v)}
+        >
+          <span aria-hidden="true" className="relative block h-3.5 w-4">
+            <span
+              className={cn(
+                "absolute left-0 top-0 h-[1.5px] w-4 bg-current transition-transform",
+                menuOpen && "translate-y-[6.5px] rotate-45"
+              )}
+            />
+            <span
+              className={cn(
+                "absolute left-0 top-1/2 h-[1.5px] w-4 -translate-y-1/2 bg-current transition-opacity",
+                menuOpen && "opacity-0"
+              )}
+            />
+            <span
+              className={cn(
+                "absolute left-0 bottom-0 h-[1.5px] w-4 bg-current transition-transform",
+                menuOpen && "-translate-y-[6.5px] -rotate-45"
+              )}
+            />
+          </span>
+        </button>
+      </div>
+
+      {menuOpen && (
+        <div
+          id="mobile-nav"
+          className="border-t border-pm-border bg-pm-bg px-4 pb-5 pt-3 md:hidden animate-fade-up"
+        >
+          <div className="flex flex-col gap-1">
+            {NAV_LINKS.map((item) => {
+              const active = pathname === item.href;
+              return (
+                <Link
+                  key={item.label}
+                  href={item.href}
+                  aria-current={active ? "page" : undefined}
+                  onClick={() => setMenuOpen(false)}
+                  className={cn(
+                    "rounded-md px-3 py-2.5 text-sm font-medium",
+                    active ? "bg-pm-violet/10 text-pm-violet" : "text-pm-text/70"
+                  )}
+                >
+                  {item.label}
+                </Link>
+              );
+            })}
+          </div>
+          {right && <div className="mt-4 flex flex-col gap-2 border-t border-pm-border pt-4">{right}</div>}
+        </div>
+      )}
+    </nav>
+  );
+}
diff --git a/src/components/status/ProtocolStatusView.tsx b/src/components/status/ProtocolStatusView.tsx
new file mode 100644
index 0000000..600f7c3
--- /dev/null
+++ b/src/components/status/ProtocolStatusView.tsx
@@ -0,0 +1,106 @@
+"use client";
+
+import { useEffect, useState } from "react";
+
+import { Badge, Card, RealtimeView, Skeleton, TextBlockSkeleton } from "@/components/ui";
+import { useRealtimeTopic } from "@/hooks/useRealtimeTopic";
+import { ACTIVE_NETWORK } from "@/lib/network";
+import type { ProtocolStatus, ProtocolStatusLevel } from "@/lib/realtime";
+import { fetchProtocolStatus } from "@/lib/realtime/status";
+
+const LEVEL_COPY: Record<
+  ProtocolStatusLevel,
+  { label: string; icon: string; description: string }
+> = {
+  healthy: { label: "Healthy", icon: "✓", description: "All systems are operating normally." },
+  degraded: {
+    label: "Degraded",
+    icon: "!",
+    description: "Some data may be delayed or temporarily unavailable.",
+  },
+  maintenance: {
+    label: "Maintenance",
+    icon: "⚙",
+    description: "Scheduled maintenance is in progress.",
+  },
+  unknown: {
+    label: "Unknown",
+    icon: "?",
+    description: "We can't determine protocol status right now.",
+  },
+};
+
+const formatTime = (iso: string) =>
+  Number.isNaN(Date.parse(iso))
+    ? "—"
+    : new Date(iso).toLocaleString(undefined, { dateStyle: "medium", timeStyle: "short" });
+
+export function ProtocolStatusView({ initial }: { initial?: ProtocolStatus }) {
+  const [snapshot, setSnapshot] = useState<ProtocolStatus | undefined>(initial);
+  const { data: live, status } = useRealtimeTopic("protocol_status", { initial });
+
+  // REST snapshot: first paint when nothing was server-rendered, and refetch on network switch.
+  useEffect(() => {
+    let cancelled = false;
+    void fetchProtocolStatus().then((s) => !cancelled && setSnapshot(s));
+    return () => {
+      cancelled = true;
+    };
+  }, [ACTIVE_NETWORK.id]);
+
+  const current = live ?? snapshot;
+  // Never show a banner that belongs to another environment.
+  const data =
+    current && (!current.network || current.network === ACTIVE_NETWORK.id) ? current : undefined;
+  const copy = LEVEL_COPY[data?.level ?? "unknown"];
+
+  return (
+    <RealtimeView
+      status={data ? (status === "empty" ? "polling" : status) : "empty"}
+      skeleton={
+        <Card>
+          <Skeleton height={28} width={160} className="mb-3" />
+          <TextBlockSkeleton lines={2} />
+        </Card>
+      }
+    >
+      <Card>
+        <div className="mb-2 flex flex-wrap items-center gap-3">
+          <h2 className="text-xl font-semibold text-pm-text" data-testid="status-level">
+            <span aria-hidden="true">{copy.icon} </span>
+            {copy.label}
+          </h2>
+          <Badge>{ACTIVE_NETWORK.label}</Badge>
+        </div>
+        <p className="text-sm text-pm-text/60">{copy.description}</p>
+        {data?.maintenance && (
+          <div
+            className="mt-4 rounded-lg border border-pm-border p-3 text-sm text-pm-text/80"
+            role="note"
+          >
+            <strong>Maintenance window:</strong> {formatTime(data.maintenance.startsAt)} –{" "}
+            {formatTime(data.maintenance.endsAt)}
+            {data.maintenance.message && (
+              <p className="mt-1 text-pm-text/60">{data.maintenance.message}</p>
+            )}
+          </div>
+        )}
+        <p className="mt-4 text-xs text-pm-text/45">
+          Last updated {data ? formatTime(data.updatedAt) : "—"}
+        </p>
+        {data?.incidents && data.incidents.length > 0 && (
+          <ul
+            className="mt-4 flex flex-col gap-2 text-sm text-pm-text/70"
+            aria-label="Recent incidents"
+          >
+            {data.incidents.map((i) => (
+              <li key={i.id}>
+                {i.title} — {formatTime(i.at)} ({i.resolved ? "resolved" : "ongoing"})
+              </li>
+            ))}
+          </ul>
+        )}
+      </Card>
+    </RealtimeView>
+  );
+}
diff --git a/src/components/ui/RealtimeSkeletons.tsx b/src/components/ui/RealtimeSkeletons.tsx
new file mode 100644
index 0000000..a66fca1
--- /dev/null
+++ b/src/components/ui/RealtimeSkeletons.tsx
@@ -0,0 +1,80 @@
+"use client";
+
+import type { ReactNode } from "react";
+
+import { useReducedMotion } from "@/hooks/usePrefersReducedMotion";
+import type { RealtimeViewStatus } from "@/lib/realtime";
+import { cn } from "@/lib/cn";
+import { Skeleton } from "./Skeleton";
+
+/**
+ * State matrix for realtime-backed views (status -> presentation):
+ *
+ * | status       | content            | indicator                       |
+ * |--------------|--------------------|---------------------------------|
+ * | empty        | skeleton (no data) | none                            |
+ * | live         | data               | "Live"                          |
+ * | disconnected | data (kept)        | "Offline — showing last values" |
+ * | reconnecting | data (kept)        | "Reconnecting…"                 |
+ * | polling      | data               | "Updating periodically"         |
+ */
+const STATUS_LABEL: Record<Exclude<RealtimeViewStatus, "empty">, string> = {
+  live: "Live",
+  disconnected: "Offline — showing last values",
+  reconnecting: "Reconnecting…",
+  polling: "Updating periodically",
+};
+
+interface RealtimeViewProps {
+  status: RealtimeViewStatus;
+  /** Skeleton sized to match the final content so layout does not shift. */
+  skeleton: ReactNode;
+  children: ReactNode;
+  className?: string;
+}
+
+/**
+ * Renders the skeleton only for a genuinely empty state; once data exists it
+ * stays on screen through disconnects/reconnects (no flicker on refresh).
+ */
+export function RealtimeView({ status, skeleton, children, className }: RealtimeViewProps) {
+  const reduced = useReducedMotion();
+  if (status === "empty") {
+    return (
+      <div
+        role="status"
+        aria-label="Loading"
+        aria-busy="true"
+        data-reduced-motion={reduced}
+        className={className}
+      >
+        {skeleton}
+      </div>
+    );
+  }
+  return (
+    <div className={className}>
+      <p role="status" className="mb-2 text-[11px] text-pm-text/45" data-status={status}>
+        {STATUS_LABEL[status]}
+      </p>
+      {children}
+    </div>
+  );
+}
+
+/** Block of `lines` text-row skeletons with a fixed height, for card/list bodies. */
+export function TextBlockSkeleton({
+  lines = 3,
+  lineHeight = 14,
+}: {
+  lines?: number;
+  lineHeight?: number;
+}) {
+  return (
+    <div className="flex flex-col gap-2.5" style={{ minHeight: lines * (lineHeight + 10) }}>
+      {Array.from({ length: lines }).map((_, i) => (
+        <Skeleton key={i} height={lineHeight} width={i === lines - 1 ? "60%" : "100%"} />
+      ))}
+    </div>
+  );
+}
diff --git a/src/components/ui/index.ts b/src/components/ui/index.ts
index 663cd8e..3b28ad7 100644
--- a/src/components/ui/index.ts
+++ b/src/components/ui/index.ts
@@ -9,3 +9,4 @@ export { Container } from "./Container";
 export { AddressInput } from "./AddressInput";
 export { LiveCountdown } from "./LiveCountdown";
 export { RelativeDate } from "./RelativeDate";
+export { RealtimeView, TextBlockSkeleton } from "./RealtimeSkeletons";
diff --git a/src/hooks/useRealtimeTopic.ts b/src/hooks/useRealtimeTopic.ts
new file mode 100644
index 0000000..2930f43
--- /dev/null
+++ b/src/hooks/useRealtimeTopic.ts
@@ -0,0 +1,57 @@
+"use client";
+
+import { useEffect, useState } from "react";
+
+import { useFeatureFlag } from "@/lib/flags/useFeatureFlag";
+import { fidelityController, realtimeBus, realtimeClient } from "@/lib/realtime";
+import type { ConnectionState } from "@/lib/realtime/client";
+import type { RealtimeTopic, RealtimeTopics, RealtimeViewStatus } from "@/lib/realtime";
+
+/** Maps data presence and transport state to the shared view-status enum. */
+export function deriveViewStatus(
+  hasData: boolean,
+  enabled: boolean,
+  conn: ConnectionState
+): RealtimeViewStatus {
+  if (!hasData) return "empty";
+  if (!enabled) return "polling";
+  if (conn === "connected") return "live";
+  if (conn === "reconnecting") return "reconnecting";
+  return "disconnected";
+}
+
+interface Options<T extends RealtimeTopic> {
+  /** REST snapshot used for first paint and as the fallback when realtime is off. */
+  initial?: RealtimeTopics[T];
+  /** Keep this topic subscribed even when the fidelity tier would drop it (e.g. claim settlement). */
+  critical?: boolean;
+}
+
+/**
+ * Subscribes to a topic through the event bus (never the socket directly).
+ * Late mounts read the bus snapshot; `status` is the single enum views map to
+ * presentation, so components never inspect transport internals.
+ */
+export function useRealtimeTopic<T extends RealtimeTopic>(topic: T, options: Options<T> = {}) {
+  const enabled = useFeatureFlag("realtime-oracle");
+  const [data, setData] = useState<RealtimeTopics[T] | undefined>(options.initial);
+  const [conn, setConn] = useState<ConnectionState>("idle");
+
+  useEffect(() => {
+    if (!enabled) return;
+    const snap = realtimeBus.getSnapshot(topic);
+    if (snap !== undefined) setData(snap);
+    const offBus = realtimeBus.subscribe(topic, setData);
+    setConn(realtimeClient.getConnectionState());
+    const offConn = realtimeClient.onConnectionChange(setConn);
+    const release = options.critical ? fidelityController.requireTopic(topic) : () => {};
+    realtimeClient.connect();
+    return () => {
+      offBus();
+      offConn();
+      release();
+    };
+  }, [enabled, topic, options.critical]);
+
+  return { data, status: deriveViewStatus(data !== undefined, enabled, conn), enabled };
+}
diff --git a/src/lib/realtime/bus.ts b/src/lib/realtime/bus.ts
new file mode 100644
index 0000000..877d02d
--- /dev/null
+++ b/src/lib/realtime/bus.ts
@@ -0,0 +1,74 @@
+import { SNAPSHOT_TOPICS, type RealtimeTopic, type RealtimeTopics } from "./topics";
+
+type BusHandler<T extends RealtimeTopic> = (payload: RealtimeTopics[T]) => void;
+
+const MAX_HANDLERS_PER_TOPIC = 100;
+
+/**
+ * Typed pub/sub between the realtime client (which decodes and validates) and
+ * in-app consumers. Per-topic arrival order is preserved, one throwing handler
+ * never blocks the others, and snapshot topics replay their latest value to
+ * late subscribers.
+ */
+export class RealtimeBus {
+  private handlers = new Map<RealtimeTopic, Set<BusHandler<never>>>();
+  private latest = new Map<RealtimeTopic, unknown>();
+  private queues = new Map<RealtimeTopic, unknown[]>();
+  private draining = new Set<RealtimeTopic>();
+
+  publish<T extends RealtimeTopic>(topic: T, payload: RealtimeTopics[T]): void {
+    if (SNAPSHOT_TOPICS.has(topic)) this.latest.set(topic, payload);
+    const queue = this.queues.get(topic) ?? [];
+    queue.push(payload);
+    this.queues.set(topic, queue);
+    // Re-entrant publishes are queued and delivered after the current event.
+    if (this.draining.has(topic)) return;
+    this.draining.add(topic);
+    try {
+      while (queue.length) {
+        const next = queue.shift() as RealtimeTopics[T];
+        for (const handler of [...(this.handlers.get(topic) ?? [])]) {
+          try {
+            (handler as BusHandler<T>)(next);
+          } catch {
+            console.error(`[realtime] handler for "${topic}" threw`);
+          }
+        }
+      }
+    } finally {
+      this.draining.delete(topic);
+    }
+  }
+
+  subscribe<T extends RealtimeTopic>(topic: T, handler: BusHandler<T>): () => void {
+    let set = this.handlers.get(topic);
+    if (!set) this.handlers.set(topic, (set = new Set()));
+    if (set.size >= MAX_HANDLERS_PER_TOPIC && !set.has(handler as BusHandler<never>)) {
+      console.error(`[realtime] handler limit reached for "${topic}"`);
+      return () => {};
+    }
+    // Set semantics make a StrictMode double-registration of the same handler a no-op.
+    set.add(handler as BusHandler<never>);
+    return () => {
+      this.handlers.get(topic)?.delete(handler as BusHandler<never>);
+    };
+  }
+
+  /** Latest value of a snapshot topic, or undefined if none has arrived. */
+  getSnapshot<T extends RealtimeTopic>(topic: T): RealtimeTopics[T] | undefined {
+    return this.latest.get(topic) as RealtimeTopics[T] | undefined;
+  }
+
+  handlerCount(topic: RealtimeTopic): number {
+    return this.handlers.get(topic)?.size ?? 0;
+  }
+
+  reset(): void {
+    this.handlers.clear();
+    this.latest.clear();
+    this.queues.clear();
+    this.draining.clear();
+  }
+}
+
+export const realtimeBus = new RealtimeBus();
diff --git a/src/lib/realtime/client.ts b/src/lib/realtime/client.ts
index 8be8d3c..e2ec7e5 100644
--- a/src/lib/realtime/client.ts
+++ b/src/lib/realtime/client.ts
@@ -1,6 +1,11 @@
-import { API_BASE_URL } from "@/lib/api/client";
+import { API_BASE_URL } from "../api/client";
+import { realtimeBus } from "./bus";
+import type { RealtimeTopic, RealtimeTopics } from "./topics";
 
 type Handler = (payload: unknown) => void;
+type ConnectionListener = (state: ConnectionState) => void;
+
+export type ConnectionState = "idle" | "connected" | "reconnecting";
 
 const MAX_BACKOFF_MS = 30_000;
 const BASE_BACKOFF_MS = 1_000;
@@ -20,6 +25,47 @@ class RealtimeClient {
   private attempt = 0;
   private closedByUser = false;
   private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  private wireTopics = new Set<string>();
+  private listeners = new Set<ConnectionListener>();
+  private state: ConnectionState = "idle";
+
+  getConnectionState(): ConnectionState {
+    return this.state;
+  }
+
+  onConnectionChange(listener: ConnectionListener): () => void {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  private setState(next: ConnectionState): void {
+    if (this.state === next) return;
+    this.state = next;
+    this.listeners.forEach((l) => l(next));
+  }
+
+  /**
+   * Applies the wire-level topic set as a diff (subscribe/unsubscribe deltas).
+   * The full set is re-sent on every (re)connect so a tier change or a
+   * reconnect never loses a topic.
+   */
+  syncTopics(topics: ReadonlySet<string>): void {
+    const prev = this.wireTopics;
+    this.wireTopics = new Set(topics);
+    if (this.socket?.readyState !== 1) return;
+    for (const t of topics) if (!prev.has(t)) this.send({ action: "subscribe", topic: t });
+    for (const t of prev) if (!topics.has(t)) this.send({ action: "unsubscribe", topic: t });
+  }
+
+  private send(msg: unknown): void {
+    try {
+      this.socket?.send(JSON.stringify(msg));
+    } catch {
+      // Socket closing — the reconnect path re-sends the full topic set.
+    }
+  }
 
   connect(): void {
     if (typeof WebSocket === "undefined" || this.socket) return;
@@ -38,18 +84,32 @@ class RealtimeClient {
 
     this.socket.addEventListener("open", () => {
       this.attempt = 0;
+      this.setState("connected");
+      for (const t of this.wireTopics) this.send({ action: "subscribe", topic: t });
     });
     this.socket.addEventListener("message", (event) => {
       try {
-        const { topic, payload } = JSON.parse(event.data as string) as { topic: string; payload: unknown };
+        const { topic, payload } = JSON.parse(event.data as string) as {
+          topic: string;
+          payload: unknown;
+        };
         this.handlers.get(topic)?.forEach((handler) => handler(payload));
+        // Decoded events fan out through the bus so consumers never own a socket subscription.
+        if (typeof topic === "string" && payload !== null && typeof payload === "object") {
+          realtimeBus.publish(topic as RealtimeTopic, payload as RealtimeTopics[RealtimeTopic]);
+        }
       } catch {
         // Malformed message — ignore, don't crash the connection.
       }
     });
     this.socket.addEventListener("close", () => {
       this.socket = null;
-      if (!this.closedByUser) this.scheduleReconnect();
+      if (!this.closedByUser) {
+        this.setState("reconnecting");
+        this.scheduleReconnect();
+      } else {
+        this.setState("idle");
+      }
     });
     this.socket.addEventListener("error", () => {
       this.socket?.close();
@@ -81,6 +141,7 @@ class RealtimeClient {
     if (this.reconnectTimer) clearTimeout(this.reconnectTimer);
     this.socket?.close();
     this.socket = null;
+    this.setState("idle");
   }
 }
 
diff --git a/src/lib/realtime/fidelity.ts b/src/lib/realtime/fidelity.ts
new file mode 100644
index 0000000..2c5a5ef
--- /dev/null
+++ b/src/lib/realtime/fidelity.ts
@@ -0,0 +1,237 @@
+import { realtimeClient } from "./client";
+import type { RealtimeTopic } from "./topics";
+
+export type FidelityTier = "full" | "lite" | "minimal";
+
+export interface FidelityProfile {
+  /** Topics held on the wire in this tier. */
+  topics: readonly RealtimeTopic[];
+  /** Minimum ms between delivered events per volatile topic (0 = deliver all). */
+  coalesceMs: Partial<Record<RealtimeTopic, number>>;
+  transport: "websocket" | "polling";
+}
+
+/** Declarative tier definitions — mirrored in docs/realtime-fidelity.md. */
+export const FIDELITY_PROFILES: Record<FidelityTier, FidelityProfile> = {
+  full: {
+    topics: ["oracle_update", "protocol_status", "network_health"],
+    coalesceMs: {},
+    transport: "websocket",
+  },
+  lite: {
+    topics: ["oracle_update", "protocol_status"],
+    coalesceMs: { oracle_update: 5_000 },
+    transport: "websocket",
+  },
+  minimal: { topics: ["protocol_status"], coalesceMs: {}, transport: "polling" },
+};
+
+export const TIER_ORDER: readonly FidelityTier[] = ["full", "lite", "minimal"];
+
+/** Hold times before a tier change is applied, so a flapping connection does not thrash. */
+export const DOWNGRADE_HOLD_MS = 3_000;
+export const UPGRADE_HOLD_MS = 30_000;
+
+export interface FidelitySignals {
+  effectiveType?: string;
+  saveData?: boolean;
+  batteryLevel?: number;
+  charging?: boolean;
+  deviceMemory?: number;
+  hardwareConcurrency?: number;
+}
+
+/** Pure tier selection from signals; missing signals assume an unconstrained client. */
+export function selectTier(s: FidelitySignals): FidelityTier {
+  if (s.saveData || s.effectiveType === "slow-2g" || s.effectiveType === "2g") return "minimal";
+  const lowBattery = s.batteryLevel !== undefined && s.batteryLevel < 0.15 && !s.charging;
+  const weakDevice =
+    (s.deviceMemory !== undefined && s.deviceMemory <= 2) ||
+    (s.hardwareConcurrency !== undefined && s.hardwareConcurrency <= 2);
+  if (lowBattery) return "minimal";
+  if (
+    s.effectiveType === "3g" ||
+    weakDevice ||
+    (s.batteryLevel !== undefined && s.batteryLevel < 0.3 && !s.charging)
+  ) {
+    return "lite";
+  }
+  return "full";
+}
+
+type NavigatorSignals = Navigator & {
+  connection?: {
+    effectiveType?: string;
+    saveData?: boolean;
+    addEventListener?: Navigator["addEventListener"];
+    removeEventListener?: Navigator["removeEventListener"];
+  };
+  deviceMemory?: number;
+  getBattery?: () => Promise<{
+    level: number;
+    charging: boolean;
+    addEventListener: EventTarget["addEventListener"];
+    removeEventListener: EventTarget["removeEventListener"];
+  }>;
+};
+
+/** SSR-safe, never throws. */
+export function readSignals(
+  battery?: { level: number; charging: boolean } | null
+): FidelitySignals {
+  if (typeof navigator === "undefined") return {};
+  const nav = navigator as NavigatorSignals;
+  try {
+    return {
+      effectiveType: nav.connection?.effectiveType,
+      saveData: nav.connection?.saveData,
+      deviceMemory: nav.deviceMemory,
+      hardwareConcurrency: nav.hardwareConcurrency,
+      batteryLevel: battery?.level,
+      charging: battery?.charging,
+    };
+  } catch {
+    return {};
+  }
+}
+
+type TierListener = (tier: FidelityTier) => void;
+
+/**
+ * Owns the active tier. Candidate tiers from signals are applied only after a
+ * hold period (hysteresis); manual override applies immediately. Topic changes
+ * are pushed to the client as a diff and are applied synchronously, so two
+ * rapid changes cannot interleave.
+ */
+export class FidelityController {
+  private tier: FidelityTier = "full";
+  private override: FidelityTier | null = null;
+  private pending: { tier: FidelityTier; timer: ReturnType<typeof setTimeout> } | null = null;
+  private required = new Map<RealtimeTopic, number>();
+  private listeners = new Set<TierListener>();
+  private battery: {
+    level: number;
+    charging: boolean;
+    addEventListener: EventTarget["addEventListener"];
+    removeEventListener: EventTarget["removeEventListener"];
+  } | null = null;
+  private teardown: (() => void)[] = [];
+  private started = false;
+
+  getTier(): FidelityTier {
+    return this.override ?? this.tier;
+  }
+
+  getOverride(): FidelityTier | null {
+    return this.override;
+  }
+
+  onChange(listener: TierListener): () => void {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  /** Topics a currently-visible critical action needs; never dropped by a downgrade. */
+  requireTopic(topic: RealtimeTopic): () => void {
+    this.required.set(topic, (this.required.get(topic) ?? 0) + 1);
+    this.applyTopics();
+    let released = false;
+    return () => {
+      if (released) return;
+      released = true;
+      const n = (this.required.get(topic) ?? 1) - 1;
+      if (n <= 0) this.required.delete(topic);
+      else this.required.set(topic, n);
+      this.applyTopics();
+    };
+  }
+
+  setOverride(tier: FidelityTier | null): void {
+    this.override = tier;
+    this.clearPending();
+    this.applyTopics();
+    this.emit();
+  }
+
+  /** Feed new signals; applies the resulting tier after the hysteresis hold. */
+  evaluate(signals: FidelitySignals): void {
+    const candidate = selectTier(signals);
+    if (candidate === this.tier) return this.clearPending();
+    if (this.pending?.tier === candidate) return;
+    this.clearPending();
+    const downgrade = TIER_ORDER.indexOf(candidate) > TIER_ORDER.indexOf(this.tier);
+    this.pending = {
+      tier: candidate,
+      timer: setTimeout(
+        () => {
+          this.pending = null;
+          this.tier = candidate;
+          this.applyTopics();
+          this.emit();
+        },
+        downgrade ? DOWNGRADE_HOLD_MS : UPGRADE_HOLD_MS
+      ),
+    };
+  }
+
+  start(): () => void {
+    if (this.started || typeof navigator === "undefined") return () => {};
+    this.started = true;
+    const nav = navigator as NavigatorSignals;
+    const reevaluate = () => this.evaluate(readSignals(this.battery));
+    const conn = nav.connection;
+    conn?.addEventListener?.("change", reevaluate);
+    this.teardown.push(() => conn?.removeEventListener?.("change", reevaluate));
+    // Re-assert the topic set on every (re)connect; the client also re-sends it.
+    this.teardown.push(realtimeClient.onConnectionChange(() => this.applyTopics()));
+    try {
+      void nav
+        .getBattery?.()
+        .then((b) => {
+          if (!this.started) return;
+          this.battery = b;
+          b.addEventListener("levelchange", reevaluate);
+          b.addEventListener("chargingchange", reevaluate);
+          this.teardown.push(() => {
+            b.removeEventListener("levelchange", reevaluate);
+            b.removeEventListener("chargingchange", reevaluate);
+          });
+          reevaluate();
+        })
+        .catch(() => {});
+    } catch {
+      // Battery API unavailable — assume unconstrained.
+    }
+    reevaluate();
+    return () => this.stop();
+  }
+
+  stop(): void {
+    this.started = false;
+    this.clearPending();
+    this.teardown.forEach((fn) => fn());
+    this.teardown = [];
+    this.battery = null;
+  }
+
+  private clearPending(): void {
+    if (this.pending) clearTimeout(this.pending.timer);
+    this.pending = null;
+  }
+
+  private applyTopics(): void {
+    const profile = FIDELITY_PROFILES[this.getTier()];
+    const topics = new Set<string>(profile.transport === "websocket" ? profile.topics : []);
+    this.required.forEach((_, t) => topics.add(t));
+    realtimeClient.syncTopics(topics);
+  }
+
+  private emit(): void {
+    const tier = this.getTier();
+    this.listeners.forEach((l) => l(tier));
+  }
+}
+
+export const fidelityController = new FidelityController();
diff --git a/src/lib/realtime/index.ts b/src/lib/realtime/index.ts
new file mode 100644
index 0000000..9fcd89d
--- /dev/null
+++ b/src/lib/realtime/index.ts
@@ -0,0 +1,4 @@
+export { realtimeClient } from "./client";
+export { realtimeBus, RealtimeBus } from "./bus";
+export * from "./topics";
+export * from "./fidelity";
diff --git a/src/lib/realtime/realtime.test.ts b/src/lib/realtime/realtime.test.ts
new file mode 100644
index 0000000..9a38381
--- /dev/null
+++ b/src/lib/realtime/realtime.test.ts
@@ -0,0 +1,67 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { RealtimeBus } from "./bus";
+import { FidelityController, selectTier, DOWNGRADE_HOLD_MS, UPGRADE_HOLD_MS } from "./fidelity";
+import { realtimeClient } from "./client";
+
+describe("RealtimeBus", () => {
+  it("fans out in order, isolates throwing handlers, replays snapshots and tears down", () => {
+    vi.spyOn(console, "error").mockImplementation(() => {});
+    const bus = new RealtimeBus();
+    const seen: number[] = [];
+    bus.subscribe("oracle_update", () => {
+      throw new Error("boom");
+    });
+    const off = bus.subscribe("oracle_update", (p) => seen.push(p.price));
+    bus.publish("oracle_update", { price: 1, updatedAt: "" });
+    bus.publish("oracle_update", { price: 2, updatedAt: "" });
+    expect(seen).toEqual([1, 2]);
+    expect(bus.getSnapshot("oracle_update")?.price).toBe(2);
+    off();
+    expect(bus.handlerCount("oracle_update")).toBe(1);
+  });
+
+  it("delivers re-entrant publishes after the current event", () => {
+    const bus = new RealtimeBus();
+    const order: number[] = [];
+    bus.subscribe("oracle_update", (p) => {
+      order.push(p.price);
+      if (p.price === 1) bus.publish("oracle_update", { price: 2, updatedAt: "" });
+      order.push(p.price * 10);
+    });
+    bus.publish("oracle_update", { price: 1, updatedAt: "" });
+    expect(order).toEqual([1, 10, 2, 20]);
+  });
+});
+
+describe("fidelity", () => {
+  beforeEach(() => vi.useFakeTimers());
+  afterEach(() => vi.useRealTimers());
+
+  it("selects tiers and tolerates missing signals", () => {
+    expect(selectTier({})).toBe("full");
+    expect(selectTier({ saveData: true })).toBe("minimal");
+    expect(selectTier({ effectiveType: "3g" })).toBe("lite");
+    expect(selectTier({ batteryLevel: 0.1, charging: false })).toBe("minimal");
+  });
+
+  it("applies hysteresis and syncs topic diffs without leaking timers", () => {
+    const sync = vi.spyOn(realtimeClient, "syncTopics").mockImplementation(() => {});
+    const c = new FidelityController();
+    c.evaluate({ effectiveType: "2g" });
+    c.evaluate({}); // flap back before the hold elapses
+    vi.advanceTimersByTime(DOWNGRADE_HOLD_MS);
+    expect(c.getTier()).toBe("full");
+    c.evaluate({ effectiveType: "2g" });
+    vi.advanceTimersByTime(DOWNGRADE_HOLD_MS);
+    expect(c.getTier()).toBe("minimal");
+    expect([...sync.mock.lastCall![0]]).toEqual([]);
+    const release = c.requireTopic("oracle_update");
+    expect([...sync.mock.lastCall![0]]).toEqual(["oracle_update"]);
+    release();
+    c.evaluate({});
+    vi.advanceTimersByTime(UPGRADE_HOLD_MS);
+    expect(c.getTier()).toBe("full");
+    expect(vi.getTimerCount()).toBe(0);
+  });
+});
diff --git a/src/lib/realtime/status.ts b/src/lib/realtime/status.ts
new file mode 100644
index 0000000..ea11a0c
--- /dev/null
+++ b/src/lib/realtime/status.ts
@@ -0,0 +1,13 @@
+import { apiRequest } from "@/lib/api/client";
+import { ACTIVE_NETWORK } from "@/lib/network";
+import type { ProtocolStatus } from "./topics";
+
+/** REST snapshot; falls back to "unknown" so the page is useful with the backend (or realtime) down. */
+export async function fetchProtocolStatus(): Promise<ProtocolStatus> {
+  try {
+    const status = await apiRequest<ProtocolStatus>("/status");
+    return { ...status, network: status.network ?? ACTIVE_NETWORK.id };
+  } catch {
+    return { level: "unknown", updatedAt: new Date().toISOString(), network: ACTIVE_NETWORK.id };
+  }
+}
diff --git a/src/lib/realtime/topics.ts b/src/lib/realtime/topics.ts
new file mode 100644
index 0000000..2e326bb
--- /dev/null
+++ b/src/lib/realtime/topics.ts
@@ -0,0 +1,35 @@
+/** Status of the protocol as announced by the backend (REST snapshot or realtime push). */
+export type ProtocolStatusLevel = "healthy" | "degraded" | "maintenance" | "unknown";
+
+export interface MaintenanceWindow {
+  startsAt: string;
+  endsAt: string;
+  message?: string;
+}
+
+export interface ProtocolStatus {
+  level: ProtocolStatusLevel;
+  updatedAt: string;
+  network?: string;
+  maintenance?: MaintenanceWindow | null;
+  incidents?: { id: string; title: string; at: string; resolved: boolean }[];
+}
+
+/** Topic identifiers and payload shapes of the realtime contract. */
+export interface RealtimeTopics {
+  oracle_update: { price: number; updatedAt: string };
+  protocol_status: ProtocolStatus;
+  network_health: { level: ProtocolStatusLevel; updatedAt: string };
+}
+
+export type RealtimeTopic = keyof RealtimeTopics;
+
+/** Topics that carry the current state and are replayed to late subscribers. */
+export const SNAPSHOT_TOPICS: ReadonlySet<RealtimeTopic> = new Set<RealtimeTopic>([
+  "oracle_update",
+  "protocol_status",
+  "network_health",
+]);
+
+/** Single status enum shared by realtime-backed views. */
+export type RealtimeViewStatus = "empty" | "live" | "disconnected" | "reconnecting" | "polling";