refactor(auth): replace dashboard sessions with stateless tokens and session control (#6329)

* refactor(auth): replace dashboard sessions with stateless tokens * feat(auth): harden session issuance and distributed enforcement * fix(proxy): preserve trusted proxy compatibility defaults * refactor: address dashboard auth review feedback * refactor: remove classic frontend and flatten web app
2026-07-20 16:48:43 +08:00
parent 5a6c53d496
commit 31d70fca39
1605 changed files with 17511 additions and 147913 deletions
@@ -0,0 +1,34 @@
+/*
+Copyright (C) 2023-2026 QuantumNous
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as
+published by the Free Software Foundation, either version 3 of the
+License, or (at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+For commercial licensing, please contact support@quantumnous.com
+*/
+import { api } from '@/lib/api'
+
+import type { RankingPeriod, RankingsSnapshot } from './types'
+
+type RankingsResponse = {
+  success: boolean
+  message?: string
+  data: RankingsSnapshot
+}
+
+export async function getRankings(
+  period: RankingPeriod
+): Promise<RankingsResponse> {
+  const res = await api.get('/api/rankings', { params: { period } })
+  return res.data
+}
@@ -0,0 +1,82 @@
+/*
+Copyright (C) 2023-2026 QuantumNous
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as
+published by the Free Software Foundation, either version 3 of the
+License, or (at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+For commercial licensing, please contact support@quantumnous.com
+*/
+import { Link } from '@tanstack/react-router'
+
+import { cn } from '@/lib/utils'
+
+type EntityLinkBaseProps = {
+  className?: string
+  children?: React.ReactNode
+}
+
+type ModelLinkProps = EntityLinkBaseProps & {
+  /** model_name as it appears in the pricing API. Used as the route param. */
+  modelName: string
+}
+
+/**
+ * Link wrapping a model name. Navigates to the existing model details
+ * page (`/pricing/{modelName}`). Renders the model name itself by
+ * default; pass `children` to wrap arbitrary content.
+ *
+ * A subtle persistent underline acts as the link affordance (so
+ * clickability is obvious in lists with dozens of entries) and brightens
+ * on hover.
+ */
+export function ModelLink(props: ModelLinkProps) {
+  return (
+    <Link
+      to='/pricing/$modelId'
+      params={{ modelId: props.modelName }}
+      className={cn(
+        'decoration-foreground/30 hover:decoration-foreground underline decoration-1 underline-offset-4 transition-colors',
+        props.className
+      )}
+    >
+      {props.children ?? props.modelName}
+    </Link>
+  )
+}
+
+type VendorLinkProps = EntityLinkBaseProps & {
+  /** Display name of the vendor (e.g. "Google", "OpenAI"). */
+  vendor: string
+}
+
+/**
+ * Link wrapping a vendor name. Navigates to the pricing page filtered by
+ * that vendor (`/pricing?vendor={vendor}`). Renders the vendor name
+ * itself by default. Uses the same subtle persistent underline as
+ * {@link ModelLink}, scaled for the smaller secondary text it usually
+ * wraps.
+ */
+export function VendorLink(props: VendorLinkProps) {
+  return (
+    <Link
+      to='/pricing'
+      search={{ vendor: props.vendor }}
+      className={cn(
+        'hover:text-foreground underline decoration-current/40 decoration-1 underline-offset-2 transition-colors hover:decoration-current',
+        props.className
+      )}
+    >
+      {props.children ?? props.vendor}
+    </Link>
+  )
+}
@@ -0,0 +1,60 @@
+/*
+Copyright (C) 2023-2026 QuantumNous
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as
+published by the Free Software Foundation, either version 3 of the
+License, or (at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+For commercial licensing, please contact support@quantumnous.com
+*/
+import { cn } from '@/lib/utils'
+
+type GrowthTextProps = {
+  value: number
+  className?: string
+}
+
+/**
+ * Render a period-over-period growth percent as `↑303%`, `↓12.4%`, or
+ * `0%` (when no change). The arrow is encoded in the text so the value
+ * still aligns inside a tabular column.
+ */
+export function GrowthText(props: GrowthTextProps) {
+  const v = props.value
+  if (!Number.isFinite(v) || v === 0) {
+    return (
+      <span
+        className={cn(
+          'text-muted-foreground/80 font-mono tabular-nums',
+          props.className
+        )}
+      >
+        0%
+      </span>
+    )
+  }
+  const isUp = v > 0
+  return (
+    <span
+      className={cn(
+        'font-mono tabular-nums',
+        isUp
+          ? 'text-emerald-600 dark:text-emerald-400'
+          : 'text-rose-600 dark:text-rose-400',
+        props.className
+      )}
+    >
+      {isUp ? '↑' : '↓'}
+      {Math.abs(v).toFixed(Math.abs(v) >= 100 ? 0 : 1)}%
+    </span>
+  )
+}
@@ -0,0 +1,25 @@
+/*
+Copyright (C) 2023-2026 QuantumNous
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as
+published by the Free Software Foundation, either version 3 of the
+License, or (at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+For commercial licensing, please contact support@quantumnous.com
+*/
+export * from './entity-links'
+export * from './growth-text'
+export * from './market-share-section'
+export * from './model-leaderboard'
+export * from './models-section'
+export * from './pulse-section'
+export * from './rankings-hero'
@@ -0,0 +1,310 @@
+/*
+Copyright (C) 2023-2026 QuantumNous
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as
+published by the Free Software Foundation, either version 3 of the
+License, or (at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+For commercial licensing, please contact support@quantumnous.com
+*/
+import { VChart } from '@visactor/react-vchart'
+import { PieChart } from 'lucide-react'
+import { useMemo } from 'react'
+import { useTranslation } from 'react-i18next'
+
+import { useChartTheme } from '@/lib/use-chart-theme'
+import { VCHART_OPTION } from '@/lib/vchart'
+
+import { formatShare, formatTokens } from '../lib/format'
+import type { RankingPeriod, VendorRanking, VendorShareSeries } from '../types'
+import { VendorLink } from './entity-links'
+
+const PERIOD_DESCRIPTIONS: Record<RankingPeriod, string> = {
+  today: 'Token share by model author across the last 24 hours',
+  week: 'Token share by model author across the past few weeks',
+  month: 'Token share by model author across the past month',
+  year: 'Token share by model author across the past year',
+}
+
+/** Stable colour palette for vendors, used in both the share chart and the
+ * legend dots. Falls back to a neutral palette for unknown vendors so that
+ * future additions still render. */
+const VENDOR_COLOURS: Record<string, string> = {
+  OpenAI: '#10a37f',
+  Anthropic: '#d97757',
+  Google: '#4285f4',
+  DeepSeek: '#7c5cff',
+  Alibaba: '#ff9900',
+  xAI: '#1f2937',
+  Meta: '#1877f2',
+  Moonshot: '#ec4899',
+  Zhipu: '#06b6d4',
+  Mistral: '#ff7000',
+  ByteDance: '#3b82f6',
+  Tencent: '#22c55e',
+  MiniMax: '#a855f7',
+  Cohere: '#fb923c',
+  Baidu: '#ef4444',
+  Others: '#94a3b8',
+}
+
+const FALLBACK_PALETTE = [
+  '#0ea5e9',
+  '#22c55e',
+  '#a855f7',
+  '#f97316',
+  '#14b8a6',
+  '#eab308',
+  '#ec4899',
+  '#84cc16',
+  '#6366f1',
+  '#10b981',
+  '#f43f5e',
+  '#0891b2',
+  '#94a3b8',
+]
+
+function buildVendorColourMap(names: string[]): Record<string, string> {
+  const result: Record<string, string> = {}
+  let fallbackIdx = 0
+  for (const name of names) {
+    if (VENDOR_COLOURS[name]) {
+      result[name] = VENDOR_COLOURS[name]
+    } else {
+      result[name] = FALLBACK_PALETTE[fallbackIdx % FALLBACK_PALETTE.length]
+      fallbackIdx += 1
+    }
+  }
+  return result
+}
+
+const MAX_VENDORS_IN_LIST = 12
+
+type MarketShareSectionProps = {
+  history: VendorShareSeries
+  rows: VendorRanking[]
+  period: RankingPeriod
+}
+
+/**
+ * Combined "Market Share" card: a 100%-stacked bar chart showing each
+ * vendor's slice of total token volume, paired below with a two-column
+ * vendor list.
+ */
+export function MarketShareSection(props: MarketShareSectionProps) {
+  const { t } = useTranslation()
+  const { resolvedTheme, themeReady } = useChartTheme()
+  const chartTextColor =
+    resolvedTheme === 'dark'
+      ? 'rgba(255, 255, 255, 0.68)'
+      : 'rgba(15, 23, 42, 0.58)'
+  const chartGridColor =
+    resolvedTheme === 'dark'
+      ? 'rgba(255, 255, 255, 0.12)'
+      : 'rgba(15, 23, 42, 0.12)'
+
+  const colourMap = useMemo(
+    () => buildVendorColourMap(props.history.vendors.map((v) => v.name)),
+    [props.history]
+  )
+
+  const orderedPoints = useMemo(() => {
+    const order = new Map(
+      props.history.vendors.map((v, idx) => [v.name, idx] as const)
+    )
+    return [...props.history.points].sort((a, b) => {
+      const tsCmp = a.ts.localeCompare(b.ts)
+      if (tsCmp !== 0) return tsCmp
+      return (order.get(a.vendor) ?? 999) - (order.get(b.vendor) ?? 999)
+    })
+  }, [props.history])
+
+  const spec = useMemo(() => {
+    if (orderedPoints.length === 0) return null
+    return {
+      type: 'bar' as const,
+      data: [{ id: 'vendor-share', values: orderedPoints }],
+      xField: 'label',
+      yField: 'share',
+      seriesField: 'vendor',
+      stack: true,
+      paddingInner: 0.12,
+      legends: { visible: false },
+      color: { specified: colourMap },
+      axes: [
+        {
+          orient: 'bottom',
+          label: {
+            style: { fill: chartTextColor, fontSize: 10 },
+            autoHide: true,
+            autoLimit: true,
+          },
+          tick: { visible: false },
+        },
+        {
+          orient: 'left',
+          min: 0,
+          max: 1,
+          label: {
+            formatMethod: (val: number | string) =>
+              `${Math.round(Number(val) * 100)}%`,
+            style: { fill: chartTextColor, fontSize: 10 },
+          },
+          grid: {
+            visible: true,
+            style: { lineDash: [3, 3], stroke: chartGridColor },
+          },
+        },
+      ],
+      tooltip: {
+        mark: {
+          content: [
+            {
+              key: (datum: Record<string, unknown>) =>
+                String(datum?.vendor ?? ''),
+              value: (datum: Record<string, unknown>) =>
+                `${(Number(datum?.share) * 100).toFixed(1)}% · ${formatTokens(Number(datum?.tokens) || 0)}`,
+            },
+          ],
+        },
+        dimension: {
+          title: {
+            value: (datum: Record<string, unknown>) =>
+              String(datum?.label ?? ''),
+          },
+          content: [
+            {
+              key: (datum: Record<string, unknown>) =>
+                String(datum?.vendor ?? ''),
+              value: (datum: Record<string, unknown>) =>
+                Number(datum?.share) || 0,
+            },
+          ],
+          updateContent: (
+            array: Array<{ key: string; value: string | number }>
+          ) => {
+            return array
+              .filter((item) => Number(item.value) > 0.001)
+              .sort((a, b) => Number(b.value) - Number(a.value))
+              .map((item) => ({
+                key: item.key,
+                value: `${(Number(item.value) * 100).toFixed(1)}%`,
+              }))
+          },
+        },
+      },
+      animationAppear: { duration: 500 },
+    }
+  }, [chartGridColor, chartTextColor, colourMap, orderedPoints])
+
+  const visible = props.rows.slice(0, MAX_VENDORS_IN_LIST)
+  const half = Math.ceil(visible.length / 2)
+  const left = visible.slice(0, half)
+  const right = visible.slice(half)
+
+  return (
+    <section className='bg-card overflow-hidden rounded-lg border'>
+      {/* Chart block ----------------------------------------------------- */}
+      <header className='px-5 py-4'>
+        <h2 className='text-foreground inline-flex items-center gap-2 text-base font-semibold'>
+          <PieChart className='text-primary size-4' />
+          {t('Market Share')}
+        </h2>
+        <p className='text-muted-foreground mt-1 text-sm'>
+          {t(PERIOD_DESCRIPTIONS[props.period])}
+        </p>
+      </header>
+
+      <div className='px-5 pb-5'>
+        <div className='h-60 sm:h-72'>
+          {themeReady && spec ? (
+            <VChart
+              key={`vendor-share-${resolvedTheme}-${props.period}`}
+              spec={{
+                ...spec,
+                theme: resolvedTheme === 'dark' ? 'dark' : 'light',
+                background: 'transparent',
+              }}
+              option={VCHART_OPTION}
+            />
+          ) : (
+            <div className='text-muted-foreground/80 flex h-full items-center justify-center text-xs'>
+              {t('No history data available')}
+            </div>
+          )}
+        </div>
+      </div>
+
+      {/* Vendor list block ----------------------------------------------- */}
+      <div className='border-t'>
+        <header className='px-5 pt-4 pb-2'>
+          <h3 className='text-foreground text-sm font-semibold'>
+            {t('By model author')}
+          </h3>
+          <p className='text-muted-foreground/80 mt-0.5 text-xs'>
+            {t('Vendors ranked by aggregated token volume')}
+          </p>
+        </header>
+        {visible.length === 0 ? (
+          <div className='text-muted-foreground/80 px-5 py-8 text-center text-sm'>
+            {t('No vendor data available')}
+          </div>
+        ) : (
+          <div className='grid grid-cols-1 gap-x-8 px-5 pt-1 pb-4 md:grid-cols-2'>
+            <VendorList rows={left} colourMap={colourMap} />
+            {right.length > 0 && (
+              <VendorList rows={right} colourMap={colourMap} />
+            )}
+          </div>
+        )}
+      </div>
+    </section>
+  )
+}
+
+function VendorList(props: {
+  rows: VendorRanking[]
+  colourMap: Record<string, string>
+}) {
+  return (
+    <ul>
+      {props.rows.map((vendor) => (
+        <li key={vendor.vendor} className='flex items-center gap-3 py-2.5'>
+          <span className='text-muted-foreground/80 w-6 shrink-0 text-right font-mono text-xs tabular-nums'>
+            {vendor.rank}.
+          </span>
+          <span
+            aria-hidden
+            className='size-2.5 shrink-0 rounded-full'
+            style={{
+              backgroundColor: props.colourMap[vendor.vendor] ?? '#94a3b8',
+            }}
+          />
+          <VendorLink
+            vendor={vendor.vendor}
+            className='text-foreground min-w-0 flex-1 truncate text-sm font-medium'
+          >
+            {vendor.vendor}
+          </VendorLink>
+          <div className='shrink-0 text-right'>
+            <div className='text-foreground font-mono text-sm font-semibold tabular-nums'>
+              {formatTokens(vendor.total_tokens)}
+            </div>
+            <div className='text-muted-foreground/80 font-mono text-[11px] tabular-nums'>
+              {formatShare(vendor.share)}
+            </div>
+          </div>
+        </li>
+      ))}
+    </ul>
+  )
+}
@@ -0,0 +1,139 @@
+/*
+Copyright (C) 2023-2026 QuantumNous
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as
+published by the Free Software Foundation, either version 3 of the
+License, or (at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+For commercial licensing, please contact support@quantumnous.com
+*/
+import { useTranslation } from 'react-i18next'
+
+import { getLobeIcon } from '@/lib/lobe-icon'
+
+import { formatTokens } from '../lib/format'
+import type { ModelRanking } from '../types'
+import { ModelLink, VendorLink } from './entity-links'
+import { GrowthText } from './growth-text'
+
+type ModelLeaderboardProps = {
+  rows: ModelRanking[]
+  /** Density variant. `compact` is used inside per-category sections; the
+   * default fits the larger overall "Top Models" section. */
+  variant?: 'default' | 'compact'
+  /** Optional cap (rows beyond this are dropped). */
+  limit?: number
+}
+
+/**
+ * Two-column model leaderboard list: "rank · model
+ * (with vendor below) · tokens (with growth below)" rendering. Splits
+ * `rows` evenly between the two columns so the visual rhythm matches a
+ * single ranked list rather than two independent lists.
+ *
+ * Both the model name and vendor name are clickable: model jumps to
+ * `/pricing/{modelName}` and vendor jumps to `/pricing?vendor={vendor}`.
+ */
+export function ModelLeaderboard(props: ModelLeaderboardProps) {
+  const limited = props.limit ? props.rows.slice(0, props.limit) : props.rows
+  const half = Math.ceil(limited.length / 2)
+  const left = limited.slice(0, half)
+  const right = limited.slice(half)
+  const variant = props.variant ?? 'default'
+
+  if (limited.length === 0) {
+    return null
+  }
+
+  return (
+    <div className='grid grid-cols-1 gap-x-8 md:grid-cols-2'>
+      <ModelList rows={left} variant={variant} />
+      {right.length > 0 && <ModelList rows={right} variant={variant} />}
+    </div>
+  )
+}
+
+function ModelList(props: {
+  rows: ModelRanking[]
+  variant: 'default' | 'compact'
+}) {
+  const { t } = useTranslation()
+  const compact = props.variant === 'compact'
+  return (
+    <ul>
+      {props.rows.map((row) => (
+        <li
+          key={row.model_name}
+          className={
+            compact
+              ? 'flex items-center gap-3 py-2'
+              : 'flex items-center gap-3 py-2.5'
+          }
+        >
+          <span className='text-muted-foreground/80 w-6 shrink-0 text-right font-mono text-xs tabular-nums'>
+            {row.rank}.
+          </span>
+          <span className='shrink-0'>
+            {getLobeIcon(row.vendor_icon, compact ? 20 : 22)}
+          </span>
+          <div className='min-w-0 flex-1'>
+            <ModelLink
+              modelName={row.model_name}
+              className={
+                compact
+                  ? 'text-foreground block truncate font-mono text-xs font-medium'
+                  : 'text-foreground block truncate font-mono text-sm font-medium'
+              }
+            >
+              {row.model_name}
+            </ModelLink>
+            <p
+              className={
+                compact
+                  ? 'text-muted-foreground/80 truncate text-[11px] italic'
+                  : 'text-muted-foreground/80 truncate text-xs italic'
+              }
+            >
+              by{' '}
+              <VendorLink vendor={row.vendor}>
+                {row.vendor.toLowerCase()}
+              </VendorLink>
+            </p>
+          </div>
+          <div className='shrink-0 text-right'>
+            <div
+              className={
+                compact
+                  ? 'text-foreground font-mono text-xs font-semibold tabular-nums'
+                  : 'text-foreground font-mono text-sm font-semibold tabular-nums'
+              }
+            >
+              {formatTokens(row.total_tokens)}
+              {!compact && (
+                <>
+                  {' '}
+                  <span className='text-muted-foreground/80 font-normal'>
+                    {t('tokens')}
+                  </span>
+                </>
+              )}
+            </div>
+            <GrowthText
+              value={row.growth_pct}
+              className={compact ? 'text-[10px]' : 'text-[11px]'}
+            />
+          </div>
+        </li>
+      ))}
+    </ul>
+  )
+}
@@ -0,0 +1,232 @@
+/*
+Copyright (C) 2023-2026 QuantumNous
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as
+published by the Free Software Foundation, either version 3 of the
+License, or (at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+For commercial licensing, please contact support@quantumnous.com
+*/
+import { VChart } from '@visactor/react-vchart'
+import { BarChart3, Trophy } from 'lucide-react'
+import { useMemo } from 'react'
+import { useTranslation } from 'react-i18next'
+
+import { useChartTheme } from '@/lib/use-chart-theme'
+import { VCHART_OPTION } from '@/lib/vchart'
+
+import { formatTokens } from '../lib/format'
+import type { ModelHistorySeries, ModelRanking, RankingPeriod } from '../types'
+import { ModelLeaderboard } from './model-leaderboard'
+
+const PERIOD_DESCRIPTIONS: Record<RankingPeriod, string> = {
+  today: 'Hourly token usage by model across the last 24 hours',
+  week: 'Weekly token usage by model across the past few weeks',
+  month: 'Daily token usage by model across the past month',
+  year: 'Weekly token usage by model across the past year',
+}
+
+const TOOLTIP_MAX_ROWS = 10
+
+type ModelsSectionProps = {
+  history: ModelHistorySeries
+  rows: ModelRanking[]
+  period: RankingPeriod
+}
+
+/**
+ * Combined "Top Models" card: a stacked bar chart showing token usage by
+ * model over time, paired below with a two-column LLM Leaderboard. The
+ * chart anchors the eye while the leaderboard provides the detailed key.
+ */
+export function ModelsSection(props: ModelsSectionProps) {
+  const { t } = useTranslation()
+  const { resolvedTheme, themeReady } = useChartTheme()
+  const chartTextColor =
+    resolvedTheme === 'dark'
+      ? 'rgba(255, 255, 255, 0.68)'
+      : 'rgba(15, 23, 42, 0.58)'
+  const chartGridColor =
+    resolvedTheme === 'dark'
+      ? 'rgba(255, 255, 255, 0.12)'
+      : 'rgba(15, 23, 42, 0.12)'
+
+  // Order points so the largest model appears at the bottom of every stack.
+  const orderedPoints = useMemo(() => {
+    const order = new Map(
+      props.history.models.map((m, idx) => [m.name, idx] as const)
+    )
+    return [...props.history.points].sort((a, b) => {
+      const tsCmp = a.ts.localeCompare(b.ts)
+      if (tsCmp !== 0) return tsCmp
+      return (order.get(a.model) ?? 999) - (order.get(b.model) ?? 999)
+    })
+  }, [props.history])
+
+  const totalTokens = useMemo(
+    () => props.rows.reduce((s, r) => s + r.total_tokens, 0),
+    [props.rows]
+  )
+
+  const spec = useMemo(() => {
+    if (orderedPoints.length === 0) return null
+    return {
+      type: 'bar' as const,
+      data: [{ id: 'models-history', values: orderedPoints }],
+      xField: 'label',
+      yField: 'tokens',
+      seriesField: 'model',
+      stack: true,
+      legends: { visible: false },
+      axes: [
+        {
+          orient: 'bottom',
+          label: {
+            style: { fill: chartTextColor, fontSize: 10 },
+            autoHide: true,
+            autoLimit: true,
+          },
+          tick: { visible: false },
+        },
+        {
+          orient: 'left',
+          label: {
+            formatMethod: (val: number | string) => formatTokens(Number(val)),
+            style: { fill: chartTextColor, fontSize: 10 },
+          },
+          grid: {
+            visible: true,
+            style: { lineDash: [3, 3], stroke: chartGridColor },
+          },
+        },
+      ],
+      tooltip: {
+        mark: {
+          content: [
+            {
+              key: (datum: Record<string, unknown>) =>
+                String(datum?.model ?? ''),
+              value: (datum: Record<string, unknown>) =>
+                formatTokens(Number(datum?.tokens) || 0),
+            },
+          ],
+        },
+        dimension: {
+          title: {
+            value: (datum: Record<string, unknown>) =>
+              String(datum?.label ?? ''),
+          },
+          content: [
+            {
+              key: (datum: Record<string, unknown>) =>
+                String(datum?.model ?? ''),
+              value: (datum: Record<string, unknown>) =>
+                Number(datum?.tokens) || 0,
+            },
+          ],
+          updateContent: (
+            array: Array<{ key: string; value: string | number }>
+          ) => {
+            array.sort((a, b) => Number(b.value) - Number(a.value))
+            const sum = array.reduce((s, x) => s + (Number(x.value) || 0), 0)
+            const visible = array.slice(0, TOOLTIP_MAX_ROWS)
+            const overflow = array.slice(TOOLTIP_MAX_ROWS)
+            const result = visible.map((item) => ({
+              key: item.key,
+              value: formatTokens(Number(item.value) || 0),
+            }))
+            if (overflow.length > 0) {
+              const otherSum = overflow.reduce(
+                (s, item) => s + (Number(item.value) || 0),
+                0
+              )
+              result.push({
+                key: t('+{{count}} more', { count: overflow.length }),
+                value: formatTokens(otherSum),
+              })
+            }
+            result.unshift({ key: t('Total:'), value: formatTokens(sum) })
+            return result
+          },
+        },
+      },
+      animationAppear: { duration: 500 },
+    }
+  }, [chartGridColor, chartTextColor, orderedPoints, t])
+
+  return (
+    <section className='bg-card overflow-hidden rounded-lg border'>
+      {/* Chart block ----------------------------------------------------- */}
+      <header className='flex items-start justify-between gap-4 px-5 py-4'>
+        <div className='min-w-0 flex-1'>
+          <h2 className='text-foreground inline-flex items-center gap-2 text-base font-semibold'>
+            <BarChart3 className='text-primary size-4' />
+            {t('Top Models')}
+          </h2>
+          <p className='text-muted-foreground mt-1 text-sm'>
+            {t(PERIOD_DESCRIPTIONS[props.period])}
+          </p>
+        </div>
+        <div className='shrink-0 text-right'>
+          <div className='text-foreground font-mono text-2xl font-semibold tabular-nums'>
+            {formatTokens(totalTokens)}
+          </div>
+          <div className='text-muted-foreground/80 text-[10px] font-medium tracking-widest uppercase'>
+            {t('tokens')}
+          </div>
+        </div>
+      </header>
+
+      <div className='px-5 pb-5'>
+        <div className='h-60 sm:h-72'>
+          {themeReady && spec ? (
+            <VChart
+              key={`models-history-${resolvedTheme}-${props.period}`}
+              spec={{
+                ...spec,
+                theme: resolvedTheme === 'dark' ? 'dark' : 'light',
+                background: 'transparent',
+              }}
+              option={VCHART_OPTION}
+            />
+          ) : (
+            <div className='text-muted-foreground/80 flex h-full items-center justify-center text-xs'>
+              {t('No history data available')}
+            </div>
+          )}
+        </div>
+      </div>
+
+      {/* Leaderboard block ----------------------------------------------- */}
+      <div className='border-t'>
+        <header className='px-5 pt-4 pb-2'>
+          <h3 className='text-foreground inline-flex items-center gap-2 text-sm font-semibold'>
+            <Trophy className='size-3.5 text-amber-500' />
+            {t('LLM Leaderboard')}
+          </h3>
+          <p className='text-muted-foreground/80 mt-0.5 text-xs'>
+            {t('Compare the most popular models on the platform')}
+          </p>
+        </header>
+        {props.rows.length === 0 ? (
+          <div className='text-muted-foreground/80 px-5 py-8 text-center text-sm'>
+            {t('No models match the selected filters')}
+          </div>
+        ) : (
+          <div className='px-5 pt-1 pb-4'>
+            <ModelLeaderboard rows={props.rows} />
+          </div>
+        )}
+      </div>
+    </section>
+  )
+}
@@ -0,0 +1,146 @@
+/*
+Copyright (C) 2023-2026 QuantumNous
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as
+published by the Free Software Foundation, either version 3 of the
+License, or (at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+For commercial licensing, please contact support@quantumnous.com
+*/
+import {
+  ArrowDownRight,
+  ArrowUpRight,
+  TrendingDown,
+  TrendingUp,
+} from 'lucide-react'
+import { useTranslation } from 'react-i18next'
+
+import { getLobeIcon } from '@/lib/lobe-icon'
+import { cn } from '@/lib/utils'
+
+import type { RankingMover } from '../types'
+import { ModelLink, VendorLink } from './entity-links'
+
+type PulseSectionProps = {
+  movers: RankingMover[]
+  droppers: RankingMover[]
+}
+
+/**
+ * Rank movement panel: gainers and losers calculated from the previous period.
+ */
+export function PulseSection(props: PulseSectionProps) {
+  const { t } = useTranslation()
+
+  return (
+    <section className='grid grid-cols-1 gap-4 lg:grid-cols-2'>
+      <PulseCard
+        title={t('Trending up')}
+        description={t('Models climbing the leaderboard')}
+        icon={<TrendingUp className='size-4 text-emerald-500' />}
+      >
+        {props.movers.length === 0 ? (
+          <PulseEmpty label={t('No notable climbers right now')} />
+        ) : (
+          <ul>
+            {props.movers.map((row) => (
+              <MoverRow key={row.model_name} row={row} intent='up' />
+            ))}
+          </ul>
+        )}
+      </PulseCard>
+
+      <PulseCard
+        title={t('Trending down')}
+        description={t('Models losing positions')}
+        icon={<TrendingDown className='size-4 text-rose-500' />}
+      >
+        {props.droppers.length === 0 ? (
+          <PulseEmpty label={t('No notable drops right now')} />
+        ) : (
+          <ul>
+            {props.droppers.map((row) => (
+              <MoverRow key={row.model_name} row={row} intent='down' />
+            ))}
+          </ul>
+        )}
+      </PulseCard>
+    </section>
+  )
+}
+
+function PulseCard(props: {
+  title: string
+  description: string
+  icon: React.ReactNode
+  children: React.ReactNode
+}) {
+  return (
+    <div className='bg-card overflow-hidden rounded-lg border'>
+      <header className='border-b px-4 py-3'>
+        <h3 className='text-foreground inline-flex items-center gap-2 text-sm font-semibold'>
+          {props.icon}
+          {props.title}
+        </h3>
+        <p className='text-muted-foreground/80 mt-0.5 text-xs'>
+          {props.description}
+        </p>
+      </header>
+      <div className='py-1'>{props.children}</div>
+    </div>
+  )
+}
+
+function PulseEmpty(props: { label: string }) {
+  return (
+    <div className='text-muted-foreground/80 px-4 py-6 text-center text-xs'>
+      {props.label}
+    </div>
+  )
+}
+
+function MoverRow(props: { row: RankingMover; intent: 'up' | 'down' }) {
+  return (
+    <li className='flex items-center gap-3 px-4 py-2'>
+      <span className='shrink-0'>{getLobeIcon(props.row.vendor_icon, 20)}</span>
+      <div className='min-w-0 flex-1'>
+        <ModelLink
+          modelName={props.row.model_name}
+          className='text-foreground block truncate font-mono text-xs font-medium'
+        >
+          {props.row.model_name}
+        </ModelLink>
+        <p className='text-muted-foreground/80 truncate text-[11px]'>
+          #{props.row.current_rank} ·{' '}
+          <VendorLink vendor={props.row.vendor}>
+            {props.row.vendor.toLowerCase()}
+          </VendorLink>
+        </p>
+      </div>
+      <span
+        className={cn(
+          'inline-flex shrink-0 items-center gap-0.5 font-mono text-xs font-semibold tabular-nums',
+          props.intent === 'up'
+            ? 'text-emerald-600 dark:text-emerald-400'
+            : 'text-rose-600 dark:text-rose-400'
+        )}
+      >
+        {props.intent === 'up' ? (
+          <ArrowUpRight className='size-3' />
+        ) : (
+          <ArrowDownRight className='size-3' />
+        )}
+        {Math.abs(props.row.rank_delta)}
+      </span>
+    </li>
+  )
+}
@@ -0,0 +1,93 @@
+/*
+Copyright (C) 2023-2026 QuantumNous
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as
+published by the Free Software Foundation, either version 3 of the
+License, or (at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+For commercial licensing, please contact support@quantumnous.com
+*/
+import { useTranslation } from 'react-i18next'
+
+import { cn } from '@/lib/utils'
+
+import type { RankingPeriod } from '../types'
+
+const PERIODS: { id: RankingPeriod; labelKey: string }[] = [
+  { id: 'today', labelKey: 'Today' },
+  { id: 'week', labelKey: 'Week' },
+  { id: 'month', labelKey: 'Month' },
+  { id: 'year', labelKey: 'Year' },
+]
+
+type RankingsHeroProps = {
+  period: RankingPeriod
+  onPeriodChange: (period: RankingPeriod) => void
+}
+
+/**
+ * Hero strip for the rankings page. Intentionally minimal — title +
+ * subtitle + period tabs only.
+ */
+export function RankingsHero(props: RankingsHeroProps) {
+  const { t } = useTranslation()
+
+  return (
+    <section className='space-y-5'>
+      <div className='space-y-2'>
+        <h1 className='text-[clamp(1.75rem,4vw,2.5rem)] leading-[1.15] font-bold tracking-tight'>
+          {t('Rankings')}
+        </h1>
+        <p className='text-muted-foreground/80 max-w-2xl text-sm'>
+          {t(
+            'Discover the most-used models and rising vendors on the platform, updated from live usage data.'
+          )}
+        </p>
+      </div>
+
+      {/* Underline tabs for period — clean and unobtrusive. */}
+      <div
+        role='tablist'
+        aria-label={t('Period')}
+        className='border-border/60 flex items-center border-b'
+      >
+        {PERIODS.map((p) => {
+          const isActive = props.period === p.id
+          return (
+            <button
+              key={p.id}
+              role='tab'
+              type='button'
+              aria-selected={isActive}
+              onClick={() => props.onPeriodChange(p.id)}
+              className={cn(
+                'focus-visible:ring-ring/40 relative -mb-px rounded-sm px-3 py-2 text-sm font-medium transition-colors focus-visible:ring-2 focus-visible:outline-none',
+                isActive
+                  ? 'text-foreground'
+                  : 'text-muted-foreground hover:text-foreground'
+              )}
+            >
+              {t(p.labelKey)}
+              <span
+                aria-hidden
+                className={cn(
+                  'bg-foreground absolute inset-x-3 -bottom-px h-[2px] rounded-full transition-opacity',
+                  isActive ? 'opacity-100' : 'opacity-0'
+                )}
+              />
+            </button>
+          )
+        })}
+      </div>
+    </section>
+  )
+}
@@ -0,0 +1,30 @@
+/*
+Copyright (C) 2023-2026 QuantumNous
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as
+published by the Free Software Foundation, either version 3 of the
+License, or (at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+For commercial licensing, please contact support@quantumnous.com
+*/
+import { useQuery } from '@tanstack/react-query'
+
+import { getRankings } from '../api'
+import type { RankingPeriod } from '../types'
+
+export function useRankings(period: RankingPeriod) {
+  return useQuery({
+    queryKey: ['rankings', period],
+    queryFn: () => getRankings(period),
+    staleTime: 5 * 60 * 1000,
+  })
+}
@@ -0,0 +1,137 @@
+/*
+Copyright (C) 2023-2026 QuantumNous
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as
+published by the Free Software Foundation, either version 3 of the
+License, or (at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+For commercial licensing, please contact support@quantumnous.com
+*/
+import { useNavigate, useSearch } from '@tanstack/react-router'
+import { useTranslation } from 'react-i18next'
+
+import { PublicLayout } from '@/components/layout'
+import { PageTransition } from '@/components/page-transition'
+import { Skeleton } from '@/components/ui/skeleton'
+
+import {
+  MarketShareSection,
+  ModelsSection,
+  PulseSection,
+  RankingsHero,
+} from './components'
+import { useRankings } from './hooks/use-rankings'
+import type { RankingPeriod } from './types'
+
+const VALID_PERIODS: RankingPeriod[] = ['today', 'week', 'month', 'year']
+
+export function Rankings() {
+  const { t } = useTranslation()
+  const search = useSearch({ from: '/rankings/' })
+  const navigate = useNavigate()
+
+  const period: RankingPeriod = VALID_PERIODS.includes(
+    search.period as RankingPeriod
+  )
+    ? (search.period as RankingPeriod)
+    : 'week'
+
+  const rankingsQuery = useRankings(period)
+  const snapshot = rankingsQuery.data?.data
+
+  const handlePeriodChange = (next: RankingPeriod) => {
+    navigate({
+      to: '/rankings',
+      search: (prev) => ({ ...prev, period: next }),
+    })
+  }
+
+  return (
+    <PublicLayout showMainContainer={false}>
+      <div className='relative'>
+        <div
+          aria-hidden
+          className='pointer-events-none absolute inset-x-0 top-0 h-[600px] opacity-20 dark:opacity-[0.10]'
+          style={{
+            background: [
+              'radial-gradient(ellipse 60% 50% at 20% 20%, oklch(0.72 0.18 250 / 80%) 0%, transparent 70%)',
+              'radial-gradient(ellipse 50% 40% at 80% 15%, oklch(0.65 0.15 200 / 60%) 0%, transparent 70%)',
+              'radial-gradient(ellipse 40% 35% at 50% 70%, oklch(0.70 0.12 280 / 40%) 0%, transparent 70%)',
+            ].join(', '),
+            maskImage:
+              'linear-gradient(to bottom, black 40%, transparent 100%)',
+            WebkitMaskImage:
+              'linear-gradient(to bottom, black 40%, transparent 100%)',
+          }}
+        />
+        <PageTransition className='relative mx-auto w-full max-w-[1280px] space-y-8 px-3 pt-16 pb-10 sm:px-6 sm:pt-20 sm:pb-12 xl:px-8'>
+          <RankingsHero period={period} onPeriodChange={handlePeriodChange} />
+
+          {rankingsQuery.isLoading ? (
+            <RankingsLoading />
+          ) : !snapshot ? (
+            <RankingsError
+              message={
+                rankingsQuery.error instanceof Error
+                  ? rankingsQuery.error.message
+                  : t('Unable to load rankings data')
+              }
+            />
+          ) : (
+            <>
+              <ModelsSection
+                history={snapshot.models_history}
+                rows={snapshot.models}
+                period={period}
+              />
+
+              <MarketShareSection
+                history={snapshot.vendor_share_history}
+                rows={snapshot.vendors}
+                period={period}
+              />
+
+              <PulseSection
+                movers={snapshot.top_movers}
+                droppers={snapshot.top_droppers}
+              />
+            </>
+          )}
+        </PageTransition>
+      </div>
+    </PublicLayout>
+  )
+}
+
+function RankingsLoading() {
+  return (
+    <div className='space-y-6'>
+      <Skeleton className='h-[420px] w-full rounded-xl' />
+      <Skeleton className='h-[360px] w-full rounded-xl' />
+      <Skeleton className='h-[180px] w-full rounded-xl' />
+    </div>
+  )
+}
+
+function RankingsError(props: { message: string }) {
+  const { t } = useTranslation()
+  return (
+    <div className='bg-card rounded-xl border border-dashed px-6 py-12 text-center'>
+      <h2 className='text-foreground text-base font-semibold'>
+        {t('Unable to load rankings')}
+      </h2>
+      <p className='text-muted-foreground mx-auto mt-2 max-w-md text-sm'>
+        {props.message}
+      </p>
+    </div>
+  )
+}
@@ -0,0 +1,53 @@
+/*
+Copyright (C) 2023-2026 QuantumNous
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as
+published by the Free Software Foundation, either version 3 of the
+License, or (at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+For commercial licensing, please contact support@quantumnous.com
+*/
+// ----------------------------------------------------------------------------
+// Rankings formatting helpers
+// ----------------------------------------------------------------------------
+
+/** Format a token count as `1.2B`, `42M`, `980K`, or `512`. */
+export function formatTokens(value: number): string {
+  if (!Number.isFinite(value) || value <= 0) return '0'
+  if (value >= 1_000_000_000_000)
+    return `${(value / 1_000_000_000_000).toFixed(2)}T`
+  if (value >= 1_000_000_000)
+    return `${(value / 1_000_000_000).toFixed(value >= 10_000_000_000 ? 1 : 2)}B`
+  if (value >= 1_000_000)
+    return `${(value / 1_000_000).toFixed(value >= 10_000_000 ? 1 : 2)}M`
+  if (value >= 1_000)
+    return `${(value / 1_000).toFixed(value >= 10_000 ? 0 : 1)}K`
+  return value.toLocaleString()
+}
+
+/** Format a 0..1 share as a percentage with two decimals. */
+export function formatShare(share: number): string {
+  if (!Number.isFinite(share) || share <= 0) return '0%'
+  if (share < 0.001) return '<0.1%'
+  return `${(share * 100).toFixed(share < 0.01 ? 2 : 1)}%`
+}
+
+/** Format a release date like `Oct 12, 2025`. */
+export function formatReleaseDate(iso: string): string {
+  const ts = Date.parse(iso)
+  if (!Number.isFinite(ts)) return iso
+  return new Date(ts).toLocaleDateString(undefined, {
+    year: 'numeric',
+    month: 'short',
+    day: 'numeric',
+  })
+}
@@ -0,0 +1,19 @@
+/*
+Copyright (C) 2023-2026 QuantumNous
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as
+published by the Free Software Foundation, either version 3 of the
+License, or (at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+For commercial licensing, please contact support@quantumnous.com
+*/
+export * from './format'
@@ -0,0 +1,138 @@
+/*
+Copyright (C) 2023-2026 QuantumNous
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as
+published by the Free Software Foundation, either version 3 of the
+License, or (at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+For commercial licensing, please contact support@quantumnous.com
+*/
+// ----------------------------------------------------------------------------
+// Rankings types
+// ----------------------------------------------------------------------------
+//
+// Shape of the real data shown on the /rankings page.
+
+export type RankingPeriod = 'today' | 'week' | 'month' | 'year'
+
+export type RankingCategoryId =
+  | 'all'
+  | 'programming'
+  | 'roleplay'
+  | 'marketing'
+  | 'translation'
+  | 'science'
+  | 'finance'
+  | 'health'
+  | 'legal'
+  | 'education'
+  | 'productivity'
+  | 'multimodal'
+
+export type ModelRanking = {
+  rank: number
+  /** Previous rank in the same period; undefined means "new". */
+  previous_rank?: number
+  model_name: string
+  vendor: string
+  vendor_icon?: string
+  category: RankingCategoryId
+  /** Total tokens routed through this model in the period. */
+  total_tokens: number
+  /** Share of all tokens served (0..1). */
+  share: number
+  /** Period-over-period change in token volume (%). */
+  growth_pct: number
+}
+
+export type VendorRanking = {
+  rank: number
+  vendor: string
+  vendor_icon?: string
+  total_tokens: number
+  share: number
+  growth_pct: number
+  /** Number of distinct models from this vendor with traffic. */
+  models_count: number
+  /** Top model from this vendor in the period. */
+  top_model: string
+}
+
+export type RankingMover = {
+  model_name: string
+  vendor: string
+  vendor_icon?: string
+  /** Positive = climbed, negative = dropped. */
+  rank_delta: number
+  current_rank: number
+  /** Token-volume change percent. */
+  growth_pct: number
+}
+
+/**
+ * One sample of a model's token usage at a given timestamp.
+ * Flat shape ready to feed VChart's stacked-bar spec.
+ */
+export type ModelHistoryPoint = {
+  ts: string
+  /** Pre-formatted x-axis label (e.g. "May 5", "12:00"). */
+  label: string
+  /** Model display name shown in tooltip / legend. */
+  model: string
+  vendor: string
+  /** Token count routed through the model in this bucket. */
+  tokens: number
+}
+
+export type ModelHistorySeries = {
+  /** Flat points ready for VChart, ordered oldest → newest. */
+  points: ModelHistoryPoint[]
+  /** Models that appear in the series, sorted by total tokens desc. */
+  models: Array<{ name: string; vendor: string; total: number }>
+  /** Bucket count (used for sizing axis ticks). */
+  buckets: number
+}
+
+/**
+ * One sample of a vendor's market share at a given timestamp. `share` is
+ * normalised within the bucket (sums to 1.0 across all vendors at the same
+ * `ts`); `tokens` is preserved for tooltip use.
+ */
+export type VendorSharePoint = {
+  ts: string
+  label: string
+  vendor: string
+  share: number
+  tokens: number
+}
+
+export type VendorShareSeries = {
+  /** Flat points ready for VChart, ordered oldest → newest. */
+  points: VendorSharePoint[]
+  /** Vendors that appear in the series, sorted by aggregate tokens desc. */
+  vendors: Array<{ name: string; total: number; share: number }>
+  buckets: number
+}
+
+export type RankingsSnapshot = {
+  // Overall (all categories) ------------------------------------------------
+  models: ModelRanking[]
+  vendors: VendorRanking[]
+  /** Largest rank gainers in this period. */
+  top_movers: RankingMover[]
+  /** Largest rank losers in this period. */
+  top_droppers: RankingMover[]
+  /** Stacked-bar history of token usage by model over the period. */
+  models_history: ModelHistorySeries
+  /** 100%-stacked area history of token share by vendor over the period. */
+  vendor_share_history: VendorShareSeries
+}