From 4ce4bdf1aab4f53e1cf8d6ed54c734d3ed9a86c0 Mon Sep 17 00:00:00 2001
From: obchain <riteshnikhoriya94@gmail.com>
Date: Tue, 26 May 2026 18:05:23 +0530
Subject: [PATCH 1/4] chore(frontend): swap lightweight-charts for echarts
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

lightweight-charts ships a mandatory TradingView attribution that the
license forbids removing. Replace with echarts (MIT, tree-shakable,
native candlestick + line + bar). Bundle weight grows from ~52 kB to
~200 kB on the chart route only — the trade for richer chart chrome
and no third-party branding sitting on every screenshot.
---
 frontend/package.json   | 16 ++++++++--------
 frontend/pnpm-lock.yaml | 38 +++++++++++++++++++++++---------------
 2 files changed, 31 insertions(+), 23 deletions(-)

diff --git a/frontend/package.json b/frontend/package.json
index f9b6fea..fdfd13a 100644
--- a/frontend/package.json
+++ b/frontend/package.json
@@ -16,22 +16,22 @@
     "format:check": "prettier --check \"**/*.{ts,tsx,js,jsx,json,md,css}\""
   },
   "dependencies": {
+    "echarts": "^6.1.0",
     "next": "15.1.6",
     "react": "19.0.0",
-    "react-dom": "19.0.0",
-    "lightweight-charts": "4.2.2"
+    "react-dom": "19.0.0"
   },
   "devDependencies": {
+    "@eslint/eslintrc": "3.2.0",
+    "@tailwindcss/postcss": "4.0.17",
     "@types/node": "22.10.7",
     "@types/react": "19.0.7",
     "@types/react-dom": "19.0.3",
-    "@tailwindcss/postcss": "4.0.17",
-    "tailwindcss": "4.0.17",
-    "postcss": "8.5.1",
-    "typescript": "5.7.3",
     "eslint": "9.18.0",
     "eslint-config-next": "15.1.6",
-    "@eslint/eslintrc": "3.2.0",
-    "prettier": "3.4.2"
+    "postcss": "8.5.1",
+    "prettier": "3.4.2",
+    "tailwindcss": "4.0.17",
+    "typescript": "5.7.3"
   }
 }
diff --git a/frontend/pnpm-lock.yaml b/frontend/pnpm-lock.yaml
index 47735e2..eb11966 100644
--- a/frontend/pnpm-lock.yaml
+++ b/frontend/pnpm-lock.yaml
@@ -8,9 +8,9 @@ importers:
 
   .:
     dependencies:
-      lightweight-charts:
-        specifier: 4.2.2
-        version: 4.2.2
+      echarts:
+        specifier: ^6.1.0
+        version: 6.1.0
       next:
         specifier: 15.1.6
         version: 15.1.6(react-dom@19.0.0(react@19.0.0))(react@19.0.0)
@@ -791,6 +791,9 @@ packages:
     resolution: {integrity: sha512-KIN/nDJBQRcXw0MLVhZE9iQHmG68qAVIBg9CqmUYjmQIhgij9U5MFvrqkUL5FbtyyzZuOeOt0zdeRe4UY7ct+A==}
     engines: {node: '>= 0.4'}
 
+  echarts@6.1.0:
+    resolution: {integrity: sha512-q0yaFPggC9FUdsWH4blavRWFmxdrIodbkoKNAjJudAI6CA9gNPxHtV2RcZNEepZVlk4yvBYkOkbk6HIVpIyHZA==}
+
   emoji-regex@9.2.2:
     resolution: {integrity: sha512-L18DaJsXSUk2+42pv8mLs5jJT2hqFkFE4j21wOmgbUqsZ2hL72NsUU785g9RXgo3s0ZNgVl42TiHp3ZtOv/Vyg==}
 
@@ -954,9 +957,6 @@ packages:
     resolution: {integrity: sha512-kVscqXk4OCp68SZ0dkgEKVi6/8ij300KBWTJq32P/dYeWTSwK41WyTxalN1eRmA5Z9UU/LX9D7FWSmV9SAYx6g==}
     engines: {node: '>=0.10.0'}
 
-  fancy-canvas@2.1.0:
-    resolution: {integrity: sha512-nifxXJ95JNLFR2NgRV4/MxVP45G9909wJTEKz5fg/TZS20JJZA6hfgRVh/bC9bwl2zBtBNcYPjiBE4njQHVBwQ==}
-
   fast-deep-equal@3.1.3:
     resolution: {integrity: sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==}
 
@@ -1326,9 +1326,6 @@ packages:
     resolution: {integrity: sha512-6b6gd/RUXKaw5keVdSEtqFVdzWnU5jMxTUjA2bVcMNPLwSQ08Sv/UodBVtETLCn7k4S1Ibxwh7k68IwLZPgKaA==}
     engines: {node: '>= 12.0.0'}
 
-  lightweight-charts@4.2.2:
-    resolution: {integrity: sha512-H5u9BfUeWzOA90QaqAlGjz1tePa7kUihKSOMiE4538/xMuM3k3n6bWYxuZSj9zwIj1PhgY/J5HTA/4lMk/lYYQ==}
-
   locate-path@6.0.0:
     resolution: {integrity: sha512-iPZK6eYjbxRu3uB4/WZ3EsEIMJFMqAoopl3R+zuq0UjcAm/MO6KCweDgPfP3elTztoKP3KtnVHxTn2NHBSDVUw==}
     engines: {node: '>=10'}
@@ -1706,6 +1703,9 @@ packages:
   tsconfig-paths@3.15.0:
     resolution: {integrity: sha512-2Ac2RgzDe/cn48GvOe3M+o82pEFewD3UPbyoUHHdKasHwJKjds4fLXWf/Ux5kATBKN20oaFGu+jbElp1pos0mg==}
 
+  tslib@2.3.0:
+    resolution: {integrity: sha512-N82ooyxVNm6h1riLCoyS9e3fuJ3AMG2zIZs2Gd1ATcSFjSA23Q0fzjjZeh0jbJvWVDZ0cJT8yaNNaaXHzueNjg==}
+
   tslib@2.8.1:
     resolution: {integrity: sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==}
 
@@ -1776,6 +1776,9 @@ packages:
     resolution: {integrity: sha512-rVksvsnNCdJ/ohGc6xgPwyN8eheCxsiLM8mxuE/t/mOVqJewPuO1miLpTHQiRgTKCLexL4MeAFVagts7HmNZ2Q==}
     engines: {node: '>=10'}
 
+  zrender@6.1.0:
+    resolution: {integrity: sha512-oEGMDB6pOP2S6OwRR4PdVv610zrjnA3Bh+JnSG12fYJlBKjtNAoEb5fSUoCOOINlH96I2fU38/A2UpRKs67xYQ==}
+
 snapshots:
 
   '@alloc/quick-lru@5.2.0': {}
@@ -2471,6 +2474,11 @@ snapshots:
       es-errors: 1.3.0
       gopd: 1.2.0
 
+  echarts@6.1.0:
+    dependencies:
+      tslib: 2.3.0
+      zrender: 6.1.0
+
   emoji-regex@9.2.2: {}
 
   enhanced-resolve@5.22.0:
@@ -2779,8 +2787,6 @@ snapshots:
 
   esutils@2.0.3: {}
 
-  fancy-canvas@2.1.0: {}
-
   fast-deep-equal@3.1.3: {}
 
   fast-glob@3.3.1:
@@ -3141,10 +3147,6 @@ snapshots:
       lightningcss-win32-arm64-msvc: 1.29.2
       lightningcss-win32-x64-msvc: 1.29.2
 
-  lightweight-charts@4.2.2:
-    dependencies:
-      fancy-canvas: 2.1.0
-
   locate-path@6.0.0:
     dependencies:
       p-locate: 5.0.0
@@ -3584,6 +3586,8 @@ snapshots:
       minimist: 1.2.8
       strip-bom: 3.0.0
 
+  tslib@2.3.0: {}
+
   tslib@2.8.1: {}
 
   type-check@0.4.0:
@@ -3713,3 +3717,7 @@ snapshots:
   word-wrap@1.2.5: {}
 
   yocto-queue@0.1.0: {}
+
+  zrender@6.1.0:
+    dependencies:
+      tslib: 2.3.0

From 9b374d5e6464b1d143c0d7cd3f0cd8bfc2777f27 Mon Sep 17 00:00:00 2001
From: obchain <riteshnikhoriya94@gmail.com>
Date: Tue, 26 May 2026 18:05:42 +0530
Subject: [PATCH 2/4] feat(frontend): dark/light theme + landing redesign
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- CSS variable palette per [data-theme="dark|light"] (background,
  surface, border, up/down, soft/muted text). Tailwind v4 @theme inline
  binds them so utilities like bg-surface, text-muted, text-up resolve
  via the active theme.
- ThemeProvider holds the React state, syncs to localStorage and writes
  data-theme on <html>; an inline pre-paint script in <head> reads the
  stored / system value before hydration so the page never flashes the
  wrong palette.
- ThemeToggle button sits in the corner of both landing and chart pages.
- Landing: gradient hero, badge above title, link-card per index that
  routes to /chart/{id} on click with a "chart →" hover affordance.
- Sparkline strokes via var(--up) / var(--down) so it flips with the
  theme automatically.
---
 frontend/app/docs/page.tsx          |  2 +-
 frontend/app/globals.css            | 69 +++++++++++++++++++++++++++-
 frontend/app/layout.tsx             | 10 ++++-
 frontend/app/methodology/page.tsx   |  2 +-
 frontend/app/page.tsx               |  2 +-
 frontend/components/Dashboard.tsx   | 27 ++++++-----
 frontend/components/Footer.tsx      |  6 +--
 frontend/components/IndexCard.tsx   | 43 ++++++++++++------
 frontend/components/Sparkline.tsx   |  2 +-
 frontend/components/ThemeToggle.tsx | 56 +++++++++++++++++++++++
 frontend/lib/theme.tsx              | 70 +++++++++++++++++++++++++++++
 11 files changed, 254 insertions(+), 35 deletions(-)
 create mode 100644 frontend/components/ThemeToggle.tsx
 create mode 100644 frontend/lib/theme.tsx

diff --git a/frontend/app/docs/page.tsx b/frontend/app/docs/page.tsx
index 3e9a978..7a86690 100644
--- a/frontend/app/docs/page.tsx
+++ b/frontend/app/docs/page.tsx
@@ -1,7 +1,7 @@
 export default function DocsPage() {
   return (
     <main className="min-h-screen flex items-center justify-center px-6">
-      <p className="text-sm text-foreground/60">api docs — placeholder</p>
+      <p className="text-sm text-muted">api docs — placeholder</p>
     </main>
   );
 }
diff --git a/frontend/app/globals.css b/frontend/app/globals.css
index 349718b..5588bd2 100644
--- a/frontend/app/globals.css
+++ b/frontend/app/globals.css
@@ -1,18 +1,78 @@
 @import "tailwindcss";
 
-:root {
-  --background: #0a0a0a;
+@custom-variant dark (&:where([data-theme="dark"], [data-theme="dark"] *));
+@custom-variant light (&:where([data-theme="light"], [data-theme="light"] *));
+
+:root,
+[data-theme="dark"] {
+  --background: #07070a;
   --foreground: #ededed;
+  --surface: rgba(255, 255, 255, 0.02);
+  --surface-2: rgba(255, 255, 255, 0.04);
+  --border-subtle: rgba(255, 255, 255, 0.06);
+  --border: rgba(255, 255, 255, 0.1);
+  --border-strong: rgba(255, 255, 255, 0.18);
+  --muted: rgba(237, 237, 237, 0.55);
+  --soft: rgba(237, 237, 237, 0.35);
+  --soft-2: rgba(237, 237, 237, 0.22);
+  --up: #4ade80;
+  --down: #f87171;
+  --up-soft: rgba(74, 222, 128, 0.12);
+  --down-soft: rgba(248, 113, 113, 0.12);
+  --bg-radial-1: rgba(74, 222, 128, 0.06);
+  --bg-radial-2: rgba(248, 113, 113, 0.05);
+  --tooltip-bg: rgba(20, 20, 20, 0.95);
+  --grid: rgba(255, 255, 255, 0.04);
+}
+
+[data-theme="light"] {
+  --background: #fafafa;
+  --foreground: #0a0a0c;
+  --surface: rgba(10, 10, 12, 0.03);
+  --surface-2: rgba(10, 10, 12, 0.05);
+  --border-subtle: rgba(10, 10, 12, 0.06);
+  --border: rgba(10, 10, 12, 0.1);
+  --border-strong: rgba(10, 10, 12, 0.2);
+  --muted: rgba(10, 10, 12, 0.65);
+  --soft: rgba(10, 10, 12, 0.45);
+  --soft-2: rgba(10, 10, 12, 0.28);
+  --up: #16a34a;
+  --down: #dc2626;
+  --up-soft: rgba(22, 163, 74, 0.1);
+  --down-soft: rgba(220, 38, 38, 0.1);
+  --bg-radial-1: rgba(22, 163, 74, 0.05);
+  --bg-radial-2: rgba(220, 38, 38, 0.04);
+  --tooltip-bg: rgba(252, 252, 252, 0.98);
+  --grid: rgba(10, 10, 12, 0.07);
 }
 
 @theme inline {
   --color-background: var(--background);
   --color-foreground: var(--foreground);
+  --color-surface: var(--surface);
+  --color-surface-2: var(--surface-2);
+  --color-border-subtle: var(--border-subtle);
+  --color-border: var(--border);
+  --color-border-strong: var(--border-strong);
+  --color-muted: var(--muted);
+  --color-soft: var(--soft);
+  --color-soft-2: var(--soft-2);
+  --color-up: var(--up);
+  --color-down: var(--down);
+  --color-up-soft: var(--up-soft);
+  --color-down-soft: var(--down-soft);
 }
 
+html,
 body {
   background: var(--background);
   color: var(--foreground);
+}
+
+body {
+  background-image: radial-gradient(at 20% 0%, var(--bg-radial-1), transparent 50%),
+    radial-gradient(at 80% 0%, var(--bg-radial-2), transparent 50%);
+  background-attachment: fixed;
   font-family:
     ui-sans-serif,
     system-ui,
@@ -21,4 +81,9 @@ body {
     Roboto,
     sans-serif;
   -webkit-font-smoothing: antialiased;
+  color-scheme: dark;
+}
+
+[data-theme="light"] body {
+  color-scheme: light;
 }
diff --git a/frontend/app/layout.tsx b/frontend/app/layout.tsx
index 1276c0d..019a6c8 100644
--- a/frontend/app/layout.tsx
+++ b/frontend/app/layout.tsx
@@ -1,4 +1,5 @@
 import type { Metadata } from "next";
+import { ThemeProvider, themeInitScript } from "@/lib/theme";
 import "./globals.css";
 
 export const metadata: Metadata = {
@@ -12,8 +13,13 @@ export default function RootLayout({
   children: React.ReactNode;
 }>) {
   return (
-    <html lang="en">
-      <body>{children}</body>
+    <html lang="en" suppressHydrationWarning>
+      <head>
+        <script dangerouslySetInnerHTML={{ __html: themeInitScript }} />
+      </head>
+      <body className="bg-background text-foreground">
+        <ThemeProvider>{children}</ThemeProvider>
+      </body>
     </html>
   );
 }
diff --git a/frontend/app/methodology/page.tsx b/frontend/app/methodology/page.tsx
index 09b2982..1edda61 100644
--- a/frontend/app/methodology/page.tsx
+++ b/frontend/app/methodology/page.tsx
@@ -1,7 +1,7 @@
 export default function MethodologyPage() {
   return (
     <main className="min-h-screen flex items-center justify-center px-6">
-      <p className="text-sm text-foreground/60">methodology — placeholder</p>
+      <p className="text-sm text-muted">methodology — placeholder</p>
     </main>
   );
 }
diff --git a/frontend/app/page.tsx b/frontend/app/page.tsx
index 89fb5e6..380caa5 100644
--- a/frontend/app/page.tsx
+++ b/frontend/app/page.tsx
@@ -3,7 +3,7 @@ import { Footer } from "@/components/Footer";
 
 export default function HomePage() {
   return (
-    <main className="flex min-h-screen flex-col">
+    <main className="relative flex min-h-screen flex-col">
       <div className="flex flex-1 items-center justify-center py-16">
         <Dashboard />
       </div>
diff --git a/frontend/components/Dashboard.tsx b/frontend/components/Dashboard.tsx
index e59648c..4c42471 100644
--- a/frontend/components/Dashboard.tsx
+++ b/frontend/components/Dashboard.tsx
@@ -4,6 +4,7 @@ import { useEffect, useState } from "react";
 import { fetchHistory, fetchLatest, type IndexId } from "@/lib/api";
 import { useIndexTicks, type ConnState } from "@/lib/useIndexTicks";
 import { IndexCard } from "./IndexCard";
+import { ThemeToggle } from "./ThemeToggle";
 
 interface IndexBootstrap {
   initialValue: number | null;
@@ -56,11 +57,18 @@ export function Dashboard() {
   }, []);
 
   return (
-    <section className="mx-auto w-full max-w-3xl px-6">
-      <header className="mb-10 text-center">
-        <h1 className="text-4xl font-semibold tracking-tight">VolX</h1>
-        <p className="mt-2 text-sm text-foreground/60">
-          Crypto volatility index. 60-second cadence, multi-venue blend.
+    <section className="mx-auto w-full max-w-4xl px-6">
+      <div className="absolute top-4 right-4">
+        <ThemeToggle />
+      </div>
+      <header className="mb-12 flex flex-col items-center text-center">
+        <span className="rounded-full border border-border-subtle bg-surface px-3 py-1 text-[10px] uppercase tracking-[0.25em] text-soft">
+          crypto volatility index
+        </span>
+        <h1 className="mt-5 text-6xl font-semibold tracking-tight">VolX</h1>
+        <p className="mt-3 max-w-md text-sm text-muted">
+          BVOL + EVOL — 30-day implied volatility for BTC and ETH, computed every 60 seconds from
+          multi-venue options data.
         </p>
         <ConnStatus state={state} bootErr={bootErr} />
       </header>
@@ -88,17 +96,16 @@ export function Dashboard() {
 function ConnStatus({ state, bootErr }: { state: ConnState; bootErr: string | null }) {
   if (bootErr) {
     return (
-      <p className="mt-3 text-xs text-rose-400/80">
+      <p className="mt-3 text-xs text-down/80">
         api unreachable — start the local pipeline (`docker compose up` + engine).
       </p>
     );
   }
   const label = state === "open" ? "live" : state === "connecting" ? "connecting" : "reconnecting";
-  const color =
-    state === "open" ? "bg-emerald-400" : state === "connecting" ? "bg-amber-400" : "bg-rose-400";
+  const dotCls = state === "open" ? "bg-up" : "bg-amber-400";
   return (
-    <div className="mt-3 inline-flex items-center gap-2 text-[11px] uppercase tracking-widest text-foreground/40">
-      <span className={`inline-block h-1.5 w-1.5 rounded-full ${color}`} />
+    <div className="mt-3 inline-flex items-center gap-2 text-[11px] uppercase tracking-widest text-soft">
+      <span className={`inline-block h-1.5 w-1.5 rounded-full ${dotCls}`} />
       {label}
     </div>
   );
diff --git a/frontend/components/Footer.tsx b/frontend/components/Footer.tsx
index d63ce01..983b530 100644
--- a/frontend/components/Footer.tsx
+++ b/frontend/components/Footer.tsx
@@ -2,18 +2,18 @@ import Link from "next/link";
 
 export function Footer() {
   return (
-    <footer className="mt-16 border-t border-white/5 px-6 py-6 text-xs text-foreground/40">
+    <footer className="mt-16 border-t border-border-subtle px-6 py-6 text-xs text-soft">
       <div className="mx-auto flex max-w-3xl flex-wrap items-center justify-between gap-3">
         <span>VolX — crypto volatility index</span>
         <nav className="flex gap-5">
-          <Link href="/methodology" className="transition-colors hover:text-foreground/80">
+          <Link href="/methodology" className="transition-colors hover:text-foreground">
             methodology
           </Link>
           <a
             href="https://github.com/obchain/volx"
             target="_blank"
             rel="noreferrer"
-            className="transition-colors hover:text-foreground/80"
+            className="transition-colors hover:text-foreground"
           >
             github
           </a>
diff --git a/frontend/components/IndexCard.tsx b/frontend/components/IndexCard.tsx
index 5e80642..4601740 100644
--- a/frontend/components/IndexCard.tsx
+++ b/frontend/components/IndexCard.tsx
@@ -1,5 +1,6 @@
 "use client";
 
+import Link from "next/link";
 import { Sparkline } from "./Sparkline";
 import type { IndexId } from "@/lib/api";
 import type { Tick } from "@/lib/useIndexTicks";
@@ -12,6 +13,11 @@ interface IndexCardProps {
   history: number[];
 }
 
+const LABEL: Record<IndexId, string> = {
+  bvol: "Bitcoin Volatility",
+  evol: "Ethereum Volatility",
+};
+
 export function IndexCard({ id, liveTick, initialValue, initialTs, history }: IndexCardProps) {
   const value = liveTick?.value ?? initialValue;
   const tsMs = liveTick?.ts ?? (initialTs ? Date.parse(initialTs) : null);
@@ -26,15 +32,23 @@ export function IndexCard({ id, liveTick, initialValue, initialTs, history }: In
   const tone = deltaPct === null ? "neutral" : deltaPct >= 0 ? "up" : "down";
 
   return (
-    <div className="rounded-2xl border border-white/10 bg-white/[0.02] p-6 backdrop-blur-sm">
+    <Link
+      href={`/chart/${id}`}
+      className="group relative block overflow-hidden rounded-2xl border border-border-subtle bg-surface p-6 transition-colors hover:border-border-strong"
+    >
       <div className="flex items-baseline justify-between">
-        <span className="text-xs uppercase tracking-widest text-foreground/50">{id}</span>
-        <span className="text-[10px] uppercase tracking-wider text-foreground/40">
-          {confidence !== null ? `confidence ${confidence.toFixed(2)}` : "—"}
+        <div className="flex items-baseline gap-2">
+          <span className="text-xs font-medium uppercase tracking-[0.2em] text-foreground">
+            {id}
+          </span>
+          <span className="text-[10px] text-soft-2">{LABEL[id]}</span>
+        </div>
+        <span className="text-[10px] uppercase tracking-wider text-soft">
+          {confidence !== null ? `c ${confidence.toFixed(2)}` : "—"}
         </span>
       </div>
 
-      <div className="mt-3 flex items-baseline gap-3">
+      <div className="mt-4 flex items-baseline gap-3">
         <span className="text-5xl font-semibold tabular-nums tracking-tight">
           {value !== null ? value.toFixed(2) : "—"}
         </span>
@@ -42,25 +56,26 @@ export function IndexCard({ id, liveTick, initialValue, initialTs, history }: In
           <span
             className={
               tone === "up"
-                ? "text-sm text-emerald-400"
+                ? "text-sm font-medium text-up"
                 : tone === "down"
-                  ? "text-sm text-rose-400"
-                  : "text-sm text-foreground/40"
+                  ? "text-sm font-medium text-down"
+                  : "text-sm text-soft"
             }
           >
             {deltaPct >= 0 ? "+" : ""}
-            {deltaPct.toFixed(2)}% 1h
+            {deltaPct.toFixed(2)}%<span className="ml-1 text-soft-2">1h</span>
           </span>
         )}
       </div>
 
-      <div className="mt-4">
-        <Sparkline values={history} className="w-full" />
+      <div className="mt-5">
+        <Sparkline values={history} className="w-full" height={64} />
       </div>
 
-      <div className="mt-3 text-[11px] text-foreground/40">
-        {tsMs ? `last tick ${new Date(tsMs).toLocaleTimeString()}` : "no data"}
+      <div className="mt-4 flex items-center justify-between text-[11px]">
+        <span className="text-soft">{tsMs ? new Date(tsMs).toLocaleTimeString() : "no data"}</span>
+        <span className="text-soft transition-colors group-hover:text-foreground">chart →</span>
       </div>
-    </div>
+    </Link>
   );
 }
diff --git a/frontend/components/Sparkline.tsx b/frontend/components/Sparkline.tsx
index 5f4ae31..ed59406 100644
--- a/frontend/components/Sparkline.tsx
+++ b/frontend/components/Sparkline.tsx
@@ -48,7 +48,7 @@ export function Sparkline({ values, width = 240, height = 56, className }: Spark
     >
       <polyline
         fill="none"
-        stroke={up ? "rgb(74, 222, 128)" : "rgb(248, 113, 113)"}
+        stroke={up ? "var(--up)" : "var(--down)"}
         strokeWidth={STROKE}
         points={points}
       />
diff --git a/frontend/components/ThemeToggle.tsx b/frontend/components/ThemeToggle.tsx
new file mode 100644
index 0000000..cf38f29
--- /dev/null
+++ b/frontend/components/ThemeToggle.tsx
@@ -0,0 +1,56 @@
+"use client";
+
+import { useTheme } from "@/lib/theme";
+
+export function ThemeToggle() {
+  const { theme, toggle } = useTheme();
+  const dark = theme === "dark";
+  return (
+    <button
+      type="button"
+      onClick={toggle}
+      aria-label={dark ? "Switch to light theme" : "Switch to dark theme"}
+      title={dark ? "Switch to light" : "Switch to dark"}
+      className="inline-flex h-8 w-8 items-center justify-center rounded-md border border-border-subtle bg-surface text-soft transition-colors hover:text-foreground"
+    >
+      {dark ? <MoonIcon /> : <SunIcon />}
+    </button>
+  );
+}
+
+function MoonIcon() {
+  return (
+    <svg
+      width="14"
+      height="14"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.8"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <path d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z" />
+    </svg>
+  );
+}
+
+function SunIcon() {
+  return (
+    <svg
+      width="14"
+      height="14"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.8"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <circle cx="12" cy="12" r="4" />
+      <path d="M12 2v2M12 20v2M4.93 4.93l1.41 1.41M17.66 17.66l1.41 1.41M2 12h2M20 12h2M4.93 19.07l1.41-1.41M17.66 6.34l1.41-1.41" />
+    </svg>
+  );
+}
diff --git a/frontend/lib/theme.tsx b/frontend/lib/theme.tsx
new file mode 100644
index 0000000..0310ad5
--- /dev/null
+++ b/frontend/lib/theme.tsx
@@ -0,0 +1,70 @@
+"use client";
+
+import { createContext, useContext, useEffect, useState, type ReactNode } from "react";
+
+export type Theme = "light" | "dark";
+const STORAGE_KEY = "volx:theme";
+
+interface ThemeCtx {
+  theme: Theme;
+  setTheme: (next: Theme) => void;
+  toggle: () => void;
+}
+
+const ThemeContext = createContext<ThemeCtx | null>(null);
+
+function readInitialTheme(): Theme {
+  if (typeof window === "undefined") return "dark";
+  const stored = window.localStorage.getItem(STORAGE_KEY);
+  if (stored === "light" || stored === "dark") return stored;
+  return window.matchMedia("(prefers-color-scheme: light)").matches ? "light" : "dark";
+}
+
+export function ThemeProvider({ children }: { children: ReactNode }) {
+  // Initial state matches the value the pre-paint script set on <html>.
+  const [theme, setThemeState] = useState<Theme>(() => {
+    if (typeof document === "undefined") return "dark";
+    const attr = document.documentElement.getAttribute("data-theme");
+    return attr === "light" ? "light" : "dark";
+  });
+
+  useEffect(() => {
+    document.documentElement.setAttribute("data-theme", theme);
+    window.localStorage.setItem(STORAGE_KEY, theme);
+    // Notify non-React consumers (the ECharts instance) that the theme
+    // changed; they listen for this custom event and re-read CSS vars.
+    window.dispatchEvent(new CustomEvent("volx:theme", { detail: theme }));
+  }, [theme]);
+
+  const setTheme = (next: Theme) => setThemeState(next);
+  const toggle = () => setThemeState((t) => (t === "dark" ? "light" : "dark"));
+
+  return (
+    <ThemeContext.Provider value={{ theme, setTheme, toggle }}>{children}</ThemeContext.Provider>
+  );
+}
+
+export function useTheme() {
+  const ctx = useContext(ThemeContext);
+  if (!ctx) throw new Error("useTheme must be used inside <ThemeProvider>");
+  return ctx;
+}
+
+// Inline script string injected into <head> by the root layout. Runs
+// before React hydrates so the page paints with the right theme and
+// avoids the "flash of wrong theme" effect.
+export const themeInitScript = `
+(function() {
+  try {
+    var s = localStorage.getItem(${JSON.stringify(STORAGE_KEY)});
+    var t = s === "light" || s === "dark"
+      ? s
+      : (matchMedia("(prefers-color-scheme: light)").matches ? "light" : "dark");
+    document.documentElement.setAttribute("data-theme", t);
+  } catch (e) {
+    document.documentElement.setAttribute("data-theme", "dark");
+  }
+})();
+`;
+
+export { readInitialTheme };

From 75ad6b15b96bb31c53466e1ee7fe0e39029ae35c Mon Sep 17 00:00:00 2001
From: obchain <riteshnikhoriya94@gmail.com>
Date: Tue, 26 May 2026 18:06:19 +0530
Subject: [PATCH 3/4] feat(frontend): /chart/[index] candle chart with
 timeframe toggle
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Full-screen detail page per issue #27. Renders a candle + volume chart
with a CoinGecko-style hero (6xl value, delta pill, live indicator),
6-stat strip (open/close/high/low/ticks/avg conf), and a 12-col grid
with chart in col-span-9 and a right rail (about / live snapshot /
window) that collapses below the chart at <xl.

Chart chrome:
- timeframe pill (1h / 1d / 7d / 30d / 90d / all) maps to (interval,
  limit) and refetches history; auto-refresh every 60 s matches the
  engine cadence so bar rolls catch up without a manual switch
- area-gradient under closes for a "filled" feel without hiding candles
- adaptive EMA overlay (period scales with bar count)
- mark-line at last close with a pill label
- crosshair + tooltip pills with backdrop blur and OHLC + range + Δ%
- axis labels rendered at 12 px / 0.9 opacity (was 10 px / 0.35) so
  the price ladder is actually readable
- ECharts palette keyed off the React-state theme rather than CSS-var
  reads, sidestepping the race with ThemeProvider's data-theme write
  on toggle

Page validates {bvol|evol} via notFound() so /chart/foo 404s.
REST history extended to interval="1m" for the 1 h timeframe.
---
 frontend/app/chart/[index]/page.tsx |  13 +-
 frontend/components/Chart.tsx       | 644 ++++++++++++++++++++++++++++
 frontend/lib/api.ts                 |   2 +-
 frontend/lib/timeframes.ts          |  28 ++
 4 files changed, 684 insertions(+), 3 deletions(-)
 create mode 100644 frontend/components/Chart.tsx
 create mode 100644 frontend/lib/timeframes.ts

diff --git a/frontend/app/chart/[index]/page.tsx b/frontend/app/chart/[index]/page.tsx
index 1a4471a..93d7e93 100644
--- a/frontend/app/chart/[index]/page.tsx
+++ b/frontend/app/chart/[index]/page.tsx
@@ -1,10 +1,19 @@
+import { notFound } from "next/navigation";
+import { Chart } from "@/components/Chart";
+import type { IndexId } from "@/lib/api";
+
 type Params = Promise<{ index: string }>;
 
+const ALLOWED: readonly IndexId[] = ["bvol", "evol"] as const;
+
 export default async function ChartPage({ params }: { params: Params }) {
   const { index } = await params;
+  if (!ALLOWED.includes(index as IndexId)) {
+    notFound();
+  }
   return (
-    <main className="min-h-screen flex items-center justify-center px-6">
-      <p className="text-sm text-foreground/60">chart — {index} — placeholder</p>
+    <main className="min-h-screen">
+      <Chart id={index as IndexId} />
     </main>
   );
 }
diff --git a/frontend/components/Chart.tsx b/frontend/components/Chart.tsx
new file mode 100644
index 0000000..976b875
--- /dev/null
+++ b/frontend/components/Chart.tsx
@@ -0,0 +1,644 @@
+"use client";
+
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import * as echarts from "echarts/core";
+import { CandlestickChart, BarChart, LineChart } from "echarts/charts";
+import { MarkLineComponent } from "echarts/components";
+import {
+  GridComponent,
+  TooltipComponent,
+  DataZoomComponent,
+  AxisPointerComponent,
+} from "echarts/components";
+import { CanvasRenderer } from "echarts/renderers";
+import { fetchHistory, type HistoryBar, type IndexId } from "@/lib/api";
+import { useIndexTicks } from "@/lib/useIndexTicks";
+import { useTheme } from "@/lib/theme";
+import { DEFAULT_TIMEFRAME, TIMEFRAMES, TIMEFRAME_SPEC, type Timeframe } from "@/lib/timeframes";
+import { ThemeToggle } from "./ThemeToggle";
+
+echarts.use([
+  CandlestickChart,
+  BarChart,
+  LineChart,
+  GridComponent,
+  TooltipComponent,
+  DataZoomComponent,
+  AxisPointerComponent,
+  MarkLineComponent,
+  CanvasRenderer,
+]);
+
+interface ChartProps {
+  id: IndexId;
+}
+
+const NAME: Record<IndexId, string> = {
+  bvol: "Bitcoin Volatility",
+  evol: "Ethereum Volatility",
+};
+
+interface Stats {
+  open: number;
+  close: number;
+  high: number;
+  low: number;
+  changePct: number;
+  totalTicks: number;
+  avgConfidence: number;
+}
+
+function computeStats(bars: HistoryBar[]): Stats | null {
+  if (bars.length === 0) return null;
+  const open = bars[0]!.open;
+  const close = bars[bars.length - 1]!.close;
+  let high = -Infinity;
+  let low = Infinity;
+  let totalTicks = 0;
+  let confSum = 0;
+  let confCount = 0;
+  for (const b of bars) {
+    if (b.high > high) high = b.high;
+    if (b.low < low) low = b.low;
+    totalTicks += b.count;
+    if (b.avg_confidence > 0) {
+      confSum += b.avg_confidence * b.count;
+      confCount += b.count;
+    }
+  }
+  const changePct = open === 0 ? 0 : ((close - open) / open) * 100;
+  const avgConfidence = confCount === 0 ? 0 : confSum / confCount;
+  return { open, close, high, low, changePct, totalTicks, avgConfidence };
+}
+
+// ECharts colors are hardcoded per theme rather than read from CSS vars.
+// Reading vars introduces a race with the ThemeProvider effect that writes
+// `data-theme` on <html> — if the chart redraws before the attribute lands,
+// the canvas paints with the old palette. Driving the palette from the
+// React-state theme value sidesteps that ordering.
+type ChartPalette = {
+  up: string;
+  down: string;
+  upGlow: string;
+  downGlow: string;
+  text: string;
+  textStrong: string;
+  textMuted: string;
+  grid: string;
+  gridStrong: string;
+  tooltipBg: string;
+  tooltipBorder: string;
+  lineColor: string;
+  lineGradTop: string;
+  lineGradBot: string;
+  ema: string;
+};
+
+function readChartTheme(theme: "dark" | "light"): ChartPalette {
+  if (theme === "light") {
+    return {
+      up: "#16a34a",
+      down: "#dc2626",
+      upGlow: "rgba(22,163,74,0.35)",
+      downGlow: "rgba(220,38,38,0.35)",
+      text: "rgba(10,10,12,0.95)",
+      textStrong: "rgba(10,10,12,1)",
+      textMuted: "rgba(10,10,12,0.7)",
+      grid: "rgba(10,10,12,0.06)",
+      gridStrong: "rgba(10,10,12,0.12)",
+      tooltipBg: "rgba(255,255,255,0.98)",
+      tooltipBorder: "rgba(10,10,12,0.15)",
+      lineColor: "#6366f1",
+      lineGradTop: "rgba(99,102,241,0.22)",
+      lineGradBot: "rgba(99,102,241,0.0)",
+      ema: "rgba(234,88,12,0.85)",
+    };
+  }
+  return {
+    up: "#4ade80",
+    down: "#f87171",
+    upGlow: "rgba(74,222,128,0.45)",
+    downGlow: "rgba(248,113,113,0.45)",
+    text: "rgba(237,237,237,0.95)",
+    textStrong: "rgba(255,255,255,1)",
+    textMuted: "rgba(237,237,237,0.7)",
+    grid: "rgba(255,255,255,0.05)",
+    gridStrong: "rgba(255,255,255,0.12)",
+    tooltipBg: "rgba(15,15,18,0.97)",
+    tooltipBorder: "rgba(255,255,255,0.12)",
+    lineColor: "#a78bfa",
+    lineGradTop: "rgba(167,139,250,0.32)",
+    lineGradBot: "rgba(167,139,250,0.0)",
+    ema: "rgba(251,146,60,0.9)",
+  };
+}
+
+// Simple EMA. Used for the trend overlay on the candle chart.
+function computeEMA(values: number[], period: number): (number | "-")[] {
+  if (values.length === 0) return [];
+  const k = 2 / (period + 1);
+  const out: (number | "-")[] = [];
+  let prev: number | null = null;
+  for (let i = 0; i < values.length; i++) {
+    if (i < period - 1) {
+      out.push("-");
+      continue;
+    }
+    if (prev === null) {
+      let sum = 0;
+      for (let j = 0; j <= i; j++) sum += values[j]!;
+      prev = sum / period;
+      out.push(prev);
+      continue;
+    }
+    prev = values[i]! * k + prev * (1 - k);
+    out.push(prev);
+  }
+  return out;
+}
+
+export function Chart({ id }: ChartProps) {
+  const containerRef = useRef<HTMLDivElement | null>(null);
+  const chartRef = useRef<echarts.ECharts | null>(null);
+  const barsRef = useRef<HistoryBar[]>([]);
+  const [timeframe, setTimeframe] = useState<Timeframe>(DEFAULT_TIMEFRAME);
+  const [stats, setStats] = useState<Stats | null>(null);
+  const [loadErr, setLoadErr] = useState<string | null>(null);
+  const { theme } = useTheme();
+
+  const { state: wsState, ticks } = useIndexTicks([id]);
+  const liveTick = ticks[id];
+
+  useEffect(() => {
+    if (!containerRef.current) return;
+    const chart = echarts.init(containerRef.current, undefined, { renderer: "canvas" });
+    chartRef.current = chart;
+    const ro = new ResizeObserver(() => chart.resize());
+    ro.observe(containerRef.current);
+    return () => {
+      ro.disconnect();
+      chart.dispose();
+      chartRef.current = null;
+    };
+  }, []);
+
+  const draw = useCallback(
+    (bars: HistoryBar[]) => {
+      if (!chartRef.current) return;
+      const t = readChartTheme(theme);
+      const ohlc = bars.map((b) => [b.open, b.close, b.low, b.high]);
+      const closes = bars.map((b) => b.close);
+      const ema = computeEMA(closes, Math.min(20, Math.max(4, Math.floor(bars.length / 6))));
+      const volumes = bars.map((b) => ({
+        value: b.count,
+        itemStyle: {
+          color: b.close >= b.open ? t.up : t.down,
+          opacity: 0.65,
+          borderRadius: [2, 2, 0, 0],
+        },
+      }));
+      const labels = bars.map((b) => b.ts);
+      const lastClose = closes[closes.length - 1];
+
+      chartRef.current.setOption(
+        {
+          animation: true,
+          animationDuration: 250,
+          backgroundColor: "transparent",
+          textStyle: {
+            color: t.text,
+            fontFamily: "ui-sans-serif, system-ui",
+            fontSize: 12,
+          },
+          grid: [
+            { left: 64, right: 22, top: 14, height: "64%" },
+            { left: 64, right: 22, top: "76%", height: "18%" },
+          ],
+          xAxis: [
+            {
+              type: "category",
+              data: labels,
+              axisLine: { lineStyle: { color: t.gridStrong } },
+              axisLabel: {
+                color: t.text,
+                fontSize: 11,
+                fontWeight: 500,
+                margin: 12,
+                hideOverlap: true,
+                formatter: (v: string) => {
+                  const d = new Date(v);
+                  if (isNaN(d.getTime())) return v;
+                  const h = String(d.getHours()).padStart(2, "0");
+                  const m = String(d.getMinutes()).padStart(2, "0");
+                  const day = String(d.getDate()).padStart(2, "0");
+                  const mon = d.toLocaleString("en", { month: "short" });
+                  return `${day} ${mon}  ${h}:${m}`;
+                },
+              },
+              splitLine: { show: false },
+              axisTick: { show: false },
+              boundaryGap: true,
+            },
+            {
+              type: "category",
+              gridIndex: 1,
+              data: labels,
+              axisLine: { lineStyle: { color: t.gridStrong } },
+              axisLabel: { show: false },
+              axisTick: { show: false },
+              splitLine: { show: false },
+            },
+          ],
+          yAxis: [
+            {
+              scale: true,
+              position: "right",
+              axisLine: { show: false },
+              splitLine: { lineStyle: { color: t.grid, type: "dashed" } },
+              axisLabel: {
+                color: t.text,
+                fontSize: 12,
+                fontWeight: 600,
+                margin: 10,
+                formatter: (v: number) => v.toFixed(2),
+              },
+            },
+            {
+              scale: true,
+              gridIndex: 1,
+              position: "right",
+              axisLine: { show: false },
+              splitLine: { show: false },
+              axisLabel: {
+                color: t.textMuted,
+                fontSize: 11,
+                fontWeight: 500,
+                margin: 10,
+                formatter: (v: number) => (v >= 1000 ? `${(v / 1000).toFixed(1)}k` : v.toFixed(0)),
+              },
+              max: (value: { max: number }) => Math.ceil(value.max * 1.1),
+            },
+          ],
+          axisPointer: {
+            link: [{ xAxisIndex: "all" }],
+            lineStyle: { color: t.gridStrong, width: 1, type: "solid" },
+            label: {
+              backgroundColor: t.tooltipBg,
+              borderColor: t.tooltipBorder,
+              borderWidth: 1,
+              color: t.textStrong,
+              fontSize: 11,
+              fontWeight: 600,
+              padding: [4, 8],
+              shadowBlur: 8,
+              shadowColor: "rgba(0,0,0,0.25)",
+            },
+          },
+          tooltip: {
+            trigger: "axis",
+            backgroundColor: t.tooltipBg,
+            borderColor: t.tooltipBorder,
+            borderWidth: 1,
+            padding: [10, 12],
+            extraCssText: `border-radius:10px;backdrop-filter:blur(10px);box-shadow:0 8px 24px rgba(0,0,0,0.35)`,
+            textStyle: { color: t.text, fontSize: 12 },
+            axisPointer: { type: "cross" },
+            formatter: (params: unknown) => {
+              const arr = params as Array<{
+                seriesType: string;
+                value: number[] | number;
+                axisValue: string;
+              }>;
+              const candle = arr.find((p) => p.seriesType === "candlestick");
+              if (!candle || !Array.isArray(candle.value)) return "";
+              const [, open, close, low, high] = candle.value;
+              const change = ((close - open) / open) * 100;
+              const range = high - low;
+              const sign = change >= 0 ? "+" : "";
+              return `
+                <div style="font-size:10px;color:${t.textMuted};letter-spacing:0.05em;text-transform:uppercase;margin-bottom:8px">${candle.axisValue}</div>
+                <div style="display:grid;grid-template-columns:auto auto;gap:4px 16px;font-size:12px;font-weight:500">
+                  <span style="color:${t.textMuted}">open</span><span style="color:${t.textStrong};font-variant-numeric:tabular-nums">${open.toFixed(2)}</span>
+                  <span style="color:${t.textMuted}">high</span><span style="color:${t.textStrong};font-variant-numeric:tabular-nums">${high.toFixed(2)}</span>
+                  <span style="color:${t.textMuted}">low</span><span style="color:${t.textStrong};font-variant-numeric:tabular-nums">${low.toFixed(2)}</span>
+                  <span style="color:${t.textMuted}">close</span><span style="color:${t.textStrong};font-variant-numeric:tabular-nums">${close.toFixed(2)}</span>
+                  <span style="color:${t.textMuted}">range</span><span style="font-variant-numeric:tabular-nums">${range.toFixed(2)}</span>
+                  <span style="color:${t.textMuted}">change</span><span style="color:${change >= 0 ? t.up : t.down};font-weight:600;font-variant-numeric:tabular-nums">${sign}${change.toFixed(2)}%</span>
+                </div>`;
+            },
+          },
+          dataZoom: [{ type: "inside", xAxisIndex: [0, 1], start: 0, end: 100 }],
+          series: [
+            // Area-gradient under closes — gives the chart a "filled" look without
+            // hiding the candles. Drawn first so candles render on top.
+            {
+              type: "line",
+              name: "close",
+              data: closes,
+              smooth: 0.3,
+              symbol: "none",
+              lineStyle: { color: t.lineColor, width: 1.4, opacity: 0.55 },
+              areaStyle: {
+                color: new echarts.graphic.LinearGradient(0, 0, 0, 1, [
+                  { offset: 0, color: t.lineGradTop },
+                  { offset: 1, color: t.lineGradBot },
+                ]),
+              },
+              z: 1,
+              tooltip: { show: false },
+            },
+            // EMA trend overlay.
+            {
+              type: "line",
+              name: "ema",
+              data: ema,
+              smooth: true,
+              symbol: "none",
+              lineStyle: {
+                color: t.ema,
+                width: 1.5,
+                opacity: 0.85,
+                type: "solid",
+              },
+              z: 2,
+              tooltip: { show: false },
+            },
+            // Candles. Glow via shadow.
+            {
+              type: "candlestick",
+              name: id.toUpperCase(),
+              data: ohlc,
+              itemStyle: {
+                color: t.up,
+                color0: t.down,
+                borderColor: t.up,
+                borderColor0: t.down,
+                borderWidth: 1,
+                shadowBlur: 6,
+                shadowColor: t.upGlow,
+              },
+              barMaxWidth: 14,
+              z: 3,
+              markLine:
+                lastClose !== undefined
+                  ? {
+                      symbol: "none",
+                      silent: true,
+                      lineStyle: {
+                        color: t.lineColor,
+                        type: "dashed",
+                        width: 1,
+                        opacity: 0.7,
+                      },
+                      label: {
+                        color: t.textStrong,
+                        backgroundColor: t.tooltipBg,
+                        borderColor: t.tooltipBorder,
+                        borderWidth: 1,
+                        padding: [3, 6],
+                        borderRadius: 4,
+                        fontSize: 11,
+                        fontWeight: 600,
+                        formatter: lastClose.toFixed(2),
+                        position: "insideEndTop",
+                      },
+                      data: [{ yAxis: lastClose }],
+                    }
+                  : undefined,
+            },
+            {
+              type: "bar",
+              name: "ticks",
+              xAxisIndex: 1,
+              yAxisIndex: 1,
+              data: volumes,
+              barMaxWidth: 14,
+            },
+          ],
+        },
+        true,
+      );
+    },
+    [id, theme],
+  );
+
+  useEffect(() => {
+    let cancelled = false;
+    const spec = TIMEFRAME_SPEC[timeframe];
+    setLoadErr(null);
+    const run = async () => {
+      try {
+        const hist = await fetchHistory(id, spec.interval, spec.limit);
+        if (cancelled) return;
+        barsRef.current = hist.bars;
+        setStats(computeStats(hist.bars));
+        draw(hist.bars);
+      } catch (e) {
+        if (!cancelled) setLoadErr(e instanceof Error ? e.message : String(e));
+      }
+    };
+    run();
+    const handle = window.setInterval(run, 60_000);
+    return () => {
+      cancelled = true;
+      window.clearInterval(handle);
+    };
+  }, [id, timeframe, draw]);
+
+  // Redraw when theme flips so ECharts picks up the new CSS-var values.
+  useEffect(() => {
+    if (barsRef.current.length > 0) draw(barsRef.current);
+  }, [theme, draw]);
+
+  // Live tick → patch last candle in place.
+  useEffect(() => {
+    if (!liveTick || !chartRef.current || barsRef.current.length === 0) return;
+    const last = barsRef.current[barsRef.current.length - 1]!;
+    const newLast: HistoryBar = {
+      ...last,
+      high: Math.max(last.high, liveTick.value),
+      low: Math.min(last.low, liveTick.value),
+      close: liveTick.value,
+    };
+    barsRef.current[barsRef.current.length - 1] = newLast;
+    setStats(computeStats(barsRef.current));
+    chartRef.current.setOption({
+      series: [{ data: barsRef.current.map((b) => [b.open, b.close, b.low, b.high]) }],
+    });
+  }, [liveTick]);
+
+  const value = liveTick?.value ?? stats?.close;
+  const live = wsState === "open";
+
+  const headerDelta = useMemo<{ label: string; tone: "up" | "down" } | null>(() => {
+    if (!stats) return null;
+    const sign = stats.changePct >= 0 ? "+" : "";
+    return {
+      label: `${sign}${stats.changePct.toFixed(2)}%`,
+      tone: stats.changePct >= 0 ? "up" : "down",
+    };
+  }, [stats]);
+
+  return (
+    <div className="mx-auto w-full max-w-screen-2xl px-4 py-5 sm:px-6 lg:px-10">
+      <section className="flex flex-col gap-2">
+        <div className="flex items-center justify-between">
+          <div className="flex items-center gap-2 text-[10px] uppercase tracking-[0.25em] text-soft">
+            <span>VolX</span>
+            <span className="text-soft-2">/</span>
+            <span className="text-muted">{id}</span>
+            <span className="text-soft-2">— {NAME[id]}</span>
+          </div>
+          <ThemeToggle />
+        </div>
+        <div className="flex flex-wrap items-end justify-between gap-4">
+          <div className="flex items-end gap-4">
+            <span className="text-5xl font-semibold tabular-nums tracking-tight sm:text-6xl">
+              {value !== undefined ? value.toFixed(2) : "—"}
+            </span>
+            {headerDelta && (
+              <span
+                className={
+                  headerDelta.tone === "up"
+                    ? "mb-1 inline-flex rounded-full bg-up-soft px-2.5 py-0.5 text-sm font-medium text-up"
+                    : "mb-1 inline-flex rounded-full bg-down-soft px-2.5 py-0.5 text-sm font-medium text-down"
+                }
+              >
+                {headerDelta.label} {timeframe}
+              </span>
+            )}
+          </div>
+          <div className="flex items-center gap-3 text-[10px] uppercase tracking-widest text-soft">
+            <span className="inline-flex items-center gap-1.5">
+              <span
+                className={`inline-block h-1.5 w-1.5 rounded-full ${
+                  live ? "bg-up" : "bg-amber-400"
+                }`}
+              />
+              {live ? "live" : wsState}
+            </span>
+            <span className="text-soft-2">•</span>
+            <span>60 s cadence</span>
+          </div>
+        </div>
+      </section>
+
+      <section className="mt-5 grid grid-cols-2 gap-3 rounded-xl border border-border-subtle bg-surface p-4 sm:grid-cols-3 md:grid-cols-6">
+        <Stat label="open" value={stats?.open?.toFixed(2)} />
+        <Stat label="close" value={stats?.close?.toFixed(2)} />
+        <Stat label="high" value={stats?.high?.toFixed(2)} />
+        <Stat label="low" value={stats?.low?.toFixed(2)} />
+        <Stat label="ticks" value={stats?.totalTicks?.toString()} />
+        <Stat label="avg conf" value={stats?.avgConfidence?.toFixed(2)} />
+      </section>
+
+      <section className="mt-5 grid grid-cols-12 gap-4">
+        <div className="col-span-12 xl:col-span-9">
+          <div className="mb-3 flex items-center justify-between gap-2">
+            <nav className="inline-flex overflow-x-auto rounded-lg border border-border-subtle bg-surface p-0.5 text-xs">
+              {TIMEFRAMES.map((tf) => (
+                <button
+                  key={tf}
+                  type="button"
+                  onClick={() => setTimeframe(tf)}
+                  className={
+                    tf === timeframe
+                      ? "rounded-md bg-surface-2 px-3 py-1 text-foreground"
+                      : "rounded-md px-3 py-1 text-soft transition-colors hover:text-foreground"
+                  }
+                >
+                  {tf}
+                </button>
+              ))}
+            </nav>
+            <span className="text-[10px] uppercase tracking-widest text-soft-2">
+              {TIMEFRAME_SPEC[timeframe].interval} bars
+            </span>
+          </div>
+          <div className="relative overflow-hidden rounded-2xl border border-border-subtle bg-surface">
+            <div
+              ref={containerRef}
+              className="aspect-[16/9] w-full min-h-[420px] xl:aspect-[21/9] xl:min-h-[560px]"
+            />
+            {loadErr && (
+              <p className="absolute inset-0 flex items-center justify-center text-xs text-down/80">
+                history fetch failed: {loadErr}
+              </p>
+            )}
+          </div>
+        </div>
+
+        <aside className="col-span-12 flex flex-col gap-3 xl:col-span-3">
+          <RailCard title="About this index">
+            <p className="text-xs leading-relaxed text-muted">
+              {id === "bvol"
+                ? "30-day implied volatility for BTC, computed from a strip of OTM Deribit options via the CBOE-style variance integral. Updated every 60 seconds."
+                : "30-day implied volatility for ETH, computed from a strip of OTM Deribit options via the CBOE-style variance integral. Updated every 60 seconds."}
+            </p>
+          </RailCard>
+
+          <RailCard title="Live snapshot">
+            <Row k="last value" v={value !== undefined ? value.toFixed(2) : "—"} />
+            <Row
+              k="confidence"
+              v={
+                liveTick?.confidence !== undefined
+                  ? liveTick.confidence.toFixed(2)
+                  : stats?.avgConfidence !== undefined
+                    ? stats.avgConfidence.toFixed(2)
+                    : "—"
+              }
+            />
+            <Row k="last tick" v={liveTick ? new Date(liveTick.ts).toLocaleTimeString() : "—"} />
+            <Row k="cadence" v="60 s" />
+          </RailCard>
+
+          <RailCard title="Window">
+            <Row k="bars" v={String(barsRef.current.length)} />
+            <Row k="interval" v={TIMEFRAME_SPEC[timeframe].interval} />
+            <Row k="change" v={headerDelta ? headerDelta.label : "—"} tone={headerDelta?.tone} />
+          </RailCard>
+        </aside>
+      </section>
+
+      <footer className="mt-6 flex flex-wrap items-center justify-between gap-2 text-[11px] text-soft">
+        <span>data source: deribit options · CBOE-style variance integral</span>
+        <span>
+          {liveTick
+            ? `updated ${new Date(liveTick.ts).toLocaleTimeString()}`
+            : stats
+              ? "history bootstrap"
+              : "loading…"}
+        </span>
+      </footer>
+    </div>
+  );
+}
+
+function Stat({ label, value }: { label: string; value?: string }) {
+  return (
+    <div className="flex flex-col gap-0.5">
+      <span className="text-[10px] uppercase tracking-widest text-soft-2">{label}</span>
+      <span className="text-base font-medium tabular-nums sm:text-lg">{value ?? "—"}</span>
+    </div>
+  );
+}
+
+function RailCard({ title, children }: { title: string; children: React.ReactNode }) {
+  return (
+    <div className="rounded-xl border border-border-subtle bg-surface p-4">
+      <h3 className="mb-3 text-[10px] uppercase tracking-widest text-soft">{title}</h3>
+      <div className="flex flex-col gap-1.5">{children}</div>
+    </div>
+  );
+}
+
+function Row({ k, v, tone }: { k: string; v: string; tone?: "up" | "down" }) {
+  const valueCls = tone === "up" ? "text-up" : tone === "down" ? "text-down" : "text-foreground";
+  return (
+    <div className="flex items-baseline justify-between text-xs">
+      <span className="text-soft">{k}</span>
+      <span className={`tabular-nums ${valueCls}`}>{v}</span>
+    </div>
+  );
+}
diff --git a/frontend/lib/api.ts b/frontend/lib/api.ts
index f599de4..1c42b55 100644
--- a/frontend/lib/api.ts
+++ b/frontend/lib/api.ts
@@ -75,7 +75,7 @@ export async function fetchLatest(id: IndexId): Promise<LatestResponse> {
 
 export async function fetchHistory(
   id: IndexId,
-  interval: "5m" | "1h" | "1d",
+  interval: "1m" | "5m" | "1h" | "1d",
   limit: number,
 ): Promise<HistoryResponse> {
   const url = `/v1/index/${id}/history?interval=${interval}&limit=${limit}`;
diff --git a/frontend/lib/timeframes.ts b/frontend/lib/timeframes.ts
new file mode 100644
index 0000000..0e5c155
--- /dev/null
+++ b/frontend/lib/timeframes.ts
@@ -0,0 +1,28 @@
+// Timeframe → REST history interval + limit. Bars math:
+//   1m × 60   = 1 h
+//   5m × 288  = 1 d
+//   1h × 168  = 7 d
+//   1h × 720  = 30 d
+//   1d × 90   = 90 d
+//   1d × 5000 = ~14 y (effectively "all" within the API's 10000 cap)
+
+export const TIMEFRAMES = ["1h", "1d", "7d", "30d", "90d", "all"] as const;
+export type Timeframe = (typeof TIMEFRAMES)[number];
+
+export type HistoryInterval = "1m" | "5m" | "1h" | "1d";
+
+export const DEFAULT_TIMEFRAME: Timeframe = "1d";
+
+interface TimeframeSpec {
+  interval: HistoryInterval;
+  limit: number;
+}
+
+export const TIMEFRAME_SPEC: Record<Timeframe, TimeframeSpec> = {
+  "1h": { interval: "1m", limit: 60 },
+  "1d": { interval: "5m", limit: 288 },
+  "7d": { interval: "1h", limit: 168 },
+  "30d": { interval: "1h", limit: 720 },
+  "90d": { interval: "1d", limit: 90 },
+  all: { interval: "1d", limit: 5000 },
+};

From 9ee6cea98f2fb8fddad817056d3ac5721ccd77d0 Mon Sep 17 00:00:00 2001
From: obchain <riteshnikhoriya94@gmail.com>
Date: Tue, 26 May 2026 18:13:02 +0530
Subject: [PATCH 4/4] fix(frontend): address review on chart page
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- HIGH-1: live tick redraws via the full draw() path so the candle,
  area-gradient line, EMA overlay, and mark-line all stay in sync.
  The prior partial setOption([{ data: ohlc }]) targeted series[0]
  by position, which is the close-area line — the candle (series[2])
  silently kept stale data and the line series was corrupted with
  OHLC arrays.
- HIGH-2: introduce latestTickRef and apply it to the last bar after
  every history refetch. Previously the 60 s refetch race condition
  overwrote tick patches with the server snapshot (which lacked the
  in-flight tick), erasing the live candle for the next minute.
- MED-1: hoist draw into drawRef so the history-effect deps shrink
  to [id, timeframe]. A theme flip no longer cancels and restarts the
  history interval, eliminating the redundant API round-trip on every
  toggle. Theme-redraw effect reads drawRef.current directly so it
  still picks up the fresh palette.
---
 frontend/components/Chart.tsx | 57 +++++++++++++++++++++++++++--------
 1 file changed, 45 insertions(+), 12 deletions(-)

diff --git a/frontend/components/Chart.tsx b/frontend/components/Chart.tsx
index 976b875..1730ca9 100644
--- a/frontend/components/Chart.tsx
+++ b/frontend/components/Chart.tsx
@@ -161,6 +161,9 @@ export function Chart({ id }: ChartProps) {
   const containerRef = useRef<HTMLDivElement | null>(null);
   const chartRef = useRef<echarts.ECharts | null>(null);
   const barsRef = useRef<HistoryBar[]>([]);
+  // Held outside React state so the periodic history fetch can re-apply
+  // the freshest tick after replacing `barsRef.current`.
+  const latestTickRef = useRef<{ value: number; ts: number } | null>(null);
   const [timeframe, setTimeframe] = useState<Timeframe>(DEFAULT_TIMEFRAME);
   const [stats, setStats] = useState<Stats | null>(null);
   const [loadErr, setLoadErr] = useState<string | null>(null);
@@ -422,6 +425,33 @@ export function Chart({ id }: ChartProps) {
     [id, theme],
   );
 
+  // `draw` is captured in a ref so the long-lived interval effect below can
+  // read the latest function without taking `draw` as a dependency. Without
+  // this, a `theme` flip recreates `draw`, which would cancel the interval
+  // and trigger a redundant history refetch on every toggle.
+  const drawRef = useRef(draw);
+  useEffect(() => {
+    drawRef.current = draw;
+  }, [draw]);
+
+  // Re-applies the latest WS tick to the last bar in `barsRef`. Used after
+  // a history refetch overwrites the bar set — if the tick is fresher than
+  // the server-side last bar, patch it back so the painted candle keeps
+  // up.
+  const applyLatestTickToLastBar = () => {
+    const tick = latestTickRef.current;
+    if (!tick || barsRef.current.length === 0) return;
+    const last = barsRef.current[barsRef.current.length - 1]!;
+    const lastBarMs = Date.parse(last.ts);
+    if (Number.isNaN(lastBarMs) || tick.ts < lastBarMs) return;
+    barsRef.current[barsRef.current.length - 1] = {
+      ...last,
+      high: Math.max(last.high, tick.value),
+      low: Math.min(last.low, tick.value),
+      close: tick.value,
+    };
+  };
+
   useEffect(() => {
     let cancelled = false;
     const spec = TIMEFRAME_SPEC[timeframe];
@@ -431,8 +461,9 @@ export function Chart({ id }: ChartProps) {
         const hist = await fetchHistory(id, spec.interval, spec.limit);
         if (cancelled) return;
         barsRef.current = hist.bars;
-        setStats(computeStats(hist.bars));
-        draw(hist.bars);
+        applyLatestTickToLastBar();
+        setStats(computeStats(barsRef.current));
+        drawRef.current(barsRef.current);
       } catch (e) {
         if (!cancelled) setLoadErr(e instanceof Error ? e.message : String(e));
       }
@@ -443,28 +474,30 @@ export function Chart({ id }: ChartProps) {
       cancelled = true;
       window.clearInterval(handle);
     };
-  }, [id, timeframe, draw]);
+  }, [id, timeframe]);
 
-  // Redraw when theme flips so ECharts picks up the new CSS-var values.
+  // Redraw when theme flips so ECharts picks up the new palette.
   useEffect(() => {
-    if (barsRef.current.length > 0) draw(barsRef.current);
-  }, [theme, draw]);
+    if (barsRef.current.length > 0) drawRef.current(barsRef.current);
+  }, [theme]);
 
-  // Live tick → patch last candle in place.
+  // Live tick → patch last candle in place + redraw via `drawRef` so every
+  // close-dependent series (line area, EMA overlay, mark-line) stays in
+  // sync with the candle. Targeting one series by index would silently
+  // overwrite the wrong layer because partial-option series merge by
+  // position, not by id, unless every series carries an explicit id.
   useEffect(() => {
     if (!liveTick || !chartRef.current || barsRef.current.length === 0) return;
+    latestTickRef.current = { value: liveTick.value, ts: liveTick.ts };
     const last = barsRef.current[barsRef.current.length - 1]!;
-    const newLast: HistoryBar = {
+    barsRef.current[barsRef.current.length - 1] = {
       ...last,
       high: Math.max(last.high, liveTick.value),
       low: Math.min(last.low, liveTick.value),
       close: liveTick.value,
     };
-    barsRef.current[barsRef.current.length - 1] = newLast;
     setStats(computeStats(barsRef.current));
-    chartRef.current.setOption({
-      series: [{ data: barsRef.current.map((b) => [b.open, b.close, b.low, b.high]) }],
-    });
+    drawRef.current(barsRef.current);
   }, [liveTick]);
 
   const value = liveTick?.value ?? stats?.close;