@gloom-sh/terminal 0.0.0-stage → 0.19.0

package/src/plugins/builtin/volatility/pane.tsx

@@ -0,0 +1,254 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { ChartTableHeader, CurveSurface, curveGhostColors, DataTableView, formatPercentAxis, PaneStatusBody, useChartTableSelection,
+  usePaneFooter, usePaneNoticeFooter, usePaneTabs, type DataTableColumn, type StatItem } from "../../../components";
+import { curveStrip, curveSurfaceMinRows } from "../../../components/chart/curve";
+import { dropColumnsToFit } from "../../../components/ui/table-layout";
+import { useAsyncResource } from "../../../react/async-resource";
+import { usePaneRefreshKey } from "../../../components/data-table/table-pane";
+import { usePaneSettingValue, usePluginPaneState } from "../../../public/react";
+import { shownPriceColor } from "../../../theme/colors";
+import { useThemeColors } from "../../../theme/theme-context";
+import type { PaneProps } from "../../../types/plugin";
+import { formatPercentileRank } from "../../../utils/format";
+import { Box, Text } from "../../../ui";
+import { nextHeaderSort, type SortPreference } from "../../../utils/sort-values";
+import { getSharedMarketDataCoordinator } from "../../../market-data/coordinator";
+import { buildQuoteKey, resolveEntryData } from "../../../market-data/selectors";
+import { useLiveQuoteEntries } from "../../../state/hooks/quote-streaming";
+import type { QuoteSubscriptionTarget } from "../../../types/data-provider";
+import { useAutoRefresh } from "../../../react/auto-refresh";
+import { useLiveStreamingSetting } from "../../../state/hooks/live-streaming";
+import { useIndexCloseSettled, useLiveSessionRefresh, useThrottledValue } from "../shared/volatility/live-session";
+import { DAY_SO_FAR_TEXT } from "../../../time-series/session-bar";
+import { getCachedVolatilityData, loadVolatilityData, type VolatilityLoadResult } from "./client";
+import { VOLATILITY_CURVE_INDICES, VOLATILITY_INDICES } from "../shared/volatility-indices";
+import { boardOrder, buildVolatilityData, IMPLIED_CORRELATION_ROWS, termStateLabel, volatilityCurveLookbacks, withLiveVolatilityLevels, type VolatilityBoardRow, type VolatilityIndexId, type VolatilityLiveLevel } from "./model";
+import { VolatilityHistoryChart, VolatilityIndexHistoryChart } from "./charts";
+import { volatilityCurveRows, volatilityCurveSeries, type VolatilityCurveRow } from "./chart-model";
+import { useVolatilityEvidence } from "./evidence";
+
+/** Streamed index levels rebuild the board at most this often. */
+const LIVE_LEVEL_THROTTLE_MS = 1_000;
+const INDEX_LEVEL_REFRESH_MS = 15_000;
+const TABS = [{ value: "curve", label: "Curve" }, { value: "history", label: "History" }, { value: "board", label: "Cross-asset" }];
+const BOARD_COLUMNS: DataTableColumn[] = [
+  { id: "id", label: "Index", width: 8, align: "left" },
+  { id: "label", label: "Name", width: 17, align: "left" },
+  { id: "value", label: "Level", width: 9, align: "right" },
+  { id: "change1d", label: "1D pts", width: 9, align: "right" },
+  { id: "change1dPercent", label: "1D %", width: 9, align: "right" },
+  { id: "percentile1y", label: "1Y pctl", width: 9, align: "right" },
+  { id: "date", label: "As of", width: 12, align: "left" },
+];
+/**
+ * What a narrow board gives up before its dates: the name (the selected row's
+ * name is under the table, and VVIX, SKEW and MOVE repeat their index), then
+ * the change in points beside the change in percent, then the percentile.
+ */
+const BOARD_DROP_ORDER = ["label", "change1d", "percentile1y"];
+const TERM_HISTORY_TARGETS = VOLATILITY_INDICES.filter((definition) => definition.id === "vix" || definition.id === "vix3m");
+const CURVE_COLUMNS: DataTableColumn[] = [
+  { id: "tenor", label: "Tenor", width: 7, align: "left" },
+  { id: "value", label: "IV", title: "Implied volatility", width: 8, align: "right" },
+  { id: "change1w", label: "1W chg", width: 8, align: "right" },
+  { id: "change1m", label: "1M chg", width: 8, align: "right" },
+];
+const CURVE_CAPTION = "IV % by tenor";
+const curveRowKey = (row: VolatilityCurveRow) => row.id;
+// Left and Right step along the tenors, the way the curve reads.
+const curveRowPosition = (row: VolatilityCurveRow) => new Date(row.days * 86_400_000);
+const formatIv = (value: number) => value.toFixed(2);
+const number = (value: number | null | undefined, signed = false) => value == null || !Number.isFinite(value)
+  ? "--" : `${signed && value > 0 ? "+" : ""}${value.toFixed(2)}`;
+const percentile = (value: number | null | undefined) => value == null || !Number.isFinite(value) ? "--" : value.toFixed(0);
+
+export function VolatilityPane({ focused, width, height }: PaneProps) {
+  const colors = useThemeColors();
+  // By the sign the two-decimal text shows, so a move that rounds to zero stays neutral.
+  const signColor = (value: number) => shownPriceColor(value, 2, colors);
+  const [initialTab] = usePaneSettingValue("initialTab", "curve");
+  const [tab, setTab] = usePluginPaneState("activeTabId", initialTab);
+  const [selectedId, setSelectedId] = usePluginPaneState<string | null>("selectedIndexId", "vix");
+  const [sort, setSort] = useState<SortPreference<string>>({ columnId: null, direction: "asc" });
+  const [partial, setPartial] = useState<VolatilityLoadResult | null>(null);
+  const controller = useRef<AbortController | null>(null);
+  const request = useCallback(async (force: boolean) => {
+    controller.current?.abort();
+    const abort = new AbortController();
+    controller.current = abort;
+    return loadVolatilityData(force, undefined, { signal: abort.signal, onSnapshot: (snapshot) => {
+      if (!abort.signal.aborted) setPartial(snapshot);
+    } });
+  }, []);
+  const resource = useAsyncResource(request, { initialData: getCachedVolatilityData });
+  useEffect(() => () => controller.current?.abort(), []);
+  useAutoRefresh(resource.updatedAt, resource.load);
+  const loaded = partial ?? resource.data;
+  // Index levels stream through the shared quote layer for the tab on screen;
+  // the history tab ends on the same VIX and VIX 3M levels as the curve.
+  const liveTargets = useMemo<QuoteSubscriptionTarget[]>(() => (tab === "curve" ? VOLATILITY_CURVE_INDICES
+    : tab === "board" ? VOLATILITY_INDICES.filter((definition) => !(definition.id in IMPLIED_CORRELATION_ROWS)) : TERM_HISTORY_TARGETS)
+    .map((definition) => ({ symbol: definition.symbol, exchange: "", surface: "monitor", visible: true,
+      selected: definition.id === selectedId, weight: 40 })), [tab, selectedId]);
+  const liveStreaming = useLiveStreamingSetting();
+  const { entries: liveEntries } = useLiveQuoteEntries(liveTargets, { liveStreaming });
+  const liveEntriesRef = useRef(liveEntries);
+  liveEntriesRef.current = liveEntries;
+  // Where an index does not stream, its level is re-read every 15 seconds in
+  // session while visible; a streamed level younger than that is left alone.
+  const refreshIndexLevels = useCallback(async () => {
+    const coordinator = getSharedMarketDataCoordinator();
+    const now = Date.now();
+    const quiet = liveTargets.filter((target) => {
+      const quote = resolveEntryData(liveEntriesRef.current.get(buildQuoteKey({ symbol: target.symbol, exchange: "" })));
+      return !quote || now - (quote.receivedAt ?? quote.lastUpdated) >= INDEX_LEVEL_REFRESH_MS;
+    });
+    if (!coordinator || quiet.length === 0) return;
+    await coordinator.loadQuotesBatch(quiet.map((target) => ({ symbol: target.symbol, exchange: "" })), { forceRefresh: true });
+  }, [liveTargets]);
+  // With streaming off the quote layer already polls every minute.
+  const levelRefresh = useLiveSessionRefresh(refreshIndexLevels, INDEX_LEVEL_REFRESH_MS, liveStreaming && liveTargets.length > 0);
+  const liveLevels = useThrottledValue(useMemo(() => {
+    const levels = new Map<VolatilityIndexId, VolatilityLiveLevel>();
+    for (const definition of VOLATILITY_INDICES) {
+      const quote = resolveEntryData(liveEntries.get(buildQuoteKey({ symbol: definition.symbol, exchange: "" })));
+      if (quote && !quote.stale && quote.price > 0 && Number.isFinite(quote.price) && Number.isFinite(quote.lastUpdated)) {
+        levels.set(definition.id, { value: quote.price, observedAt: quote.lastUpdated });
+      }
+    }
+    return levels;
+  }, [liveEntries]), LIVE_LEVEL_THROTTLE_MS);
+  // Rebuilt at most once a second from the loaded daily inputs plus the levels.
+  const result = useMemo(() => !loaded || liveLevels.size === 0 ? loaded
+    : { ...loaded, data: buildVolatilityData(withLiveVolatilityLevels(loaded.inputs, liveLevels)) }, [loaded, liveLevels]);
+  const data = result?.data;
+  // Indices without a level are reported in the notices, not as empty rows;
+  // rows still loading keep their place so the board does not jump.
+  const loading = !!result && result.loaded < result.total;
+  const rows = useMemo(() => {
+    const ordered = boardOrder(data?.board ?? []).filter((row) => row.value != null || (loading && !row.error));
+    if (!sort.columnId) return ordered;
+    const key = sort.columnId as keyof VolatilityBoardRow;
+    return ordered.sort((left, right) => {
+      const a = left[key], b = right[key];
+      if (a == null) return b == null ? 0 : 1;
+      if (b == null) return -1;
+      return (typeof a === "number" && typeof b === "number" ? a - b : String(a).localeCompare(String(b)))
+        * (sort.direction === "asc" ? 1 : -1);
+    });
+  }, [data?.board, sort, loading]);
+  const selected = rows.find((row) => row.id === selectedId) ?? rows[0] ?? null;
+  useVolatilityEvidence(result, tab, selected, resource.loading);
+  const notices = [resource.error, levelRefresh.error, ...(result?.errors ?? []), ...(data?.warnings ?? []),
+    ...(selected?.warnings ?? [])].filter((notice): notice is string => !!notice);
+  usePaneNoticeFooter({ registrationId: "volatility-notices", notices, focused });
+  // From the tab the press finds, so the footer's hint never holds an old one.
+  const cycleTab = useCallback(() => setTab((current) =>
+    TABS[(TABS.findIndex((entry) => entry.value === current) + 1) % TABS.length]!.value), [setTab]);
+  // One binding for every tab and for the loading and failed bodies, where no
+  // table is mounted; the footer binds the `v` hint.
+  usePaneRefreshKey(() => {
+    if (!resource.loading) void resource.reload();
+  }, { focused });
+  const asOf = tab === "history" ? data?.term.termDate : tab === "board" ? selected?.date : data?.curve.date;
+  // A day's level is its close once Cboe settles it (16:15 New York); before
+  // that a streamed level is intraday with its time, and a daily bar of the
+  // session still trading is the day so far.
+  const settled = useIndexCloseSettled(asOf);
+  const streamed = (id: VolatilityIndexId | undefined, date: string | null | undefined) => {
+    const level = id ? liveLevels.get(id) : undefined;
+    return level && date === new Date(level.observedAt).toISOString().slice(0, 10) ? level : null;
+  };
+  const latestLevel = tab === "board" ? streamed(selected?.id, selected?.date)
+    : tab === "curve" && data?.curve.source === "market-history" ? streamed("vix", data.curve.date)
+      : tab === "history" && data?.term.publisher === "Cboe" ? streamed("vix", data.term.termDate) : null;
+  const intraday = latestLevel && !settled ? latestLevel : null;
+  // An isolated print is no close; it keeps its source time.
+  const sparse = tab === "board" && !latestLevel && selected?.sampleSize === 1;
+  const observationTime = intraday ? new Date(intraday.observedAt).toISOString()
+    : sparse ? selected.history.at(-1)?.observedAt : null;
+  const observationBasis = intraday ? "intraday" : sparse ? "observation" : settled ? "close" : DAY_SO_FAR_TEXT;
+  usePaneFooter("volatility", () => ({ info: [
+    ...(resource.loading ? [{ id: "loading", parts: [{ text: "loading volatility", tone: "muted" as const }] }] : []),
+    ...(result?.stale ? [{ id: "stale", parts: [{ text: "stale", tone: "warning" as const }] }] : []),
+    ...(data ? [{ id: "basis", parts: [{ text: observationBasis, tone: "muted" as const }] }] : []),
+    ...(asOf ? [{ id: "date", parts: [{ text: observationTime ? `${observationTime.slice(0, 16).replace("T", " ")} UTC` : asOf, tone: "muted" as const }] }] : []),
+  ], hints: [{ id: "view", key: "v", label: "iew", onPress: cycleTab }] }), [resource.loading, result?.stale, data, asOf, observationTime, observationBasis, cycleTab]);
+  const { strip: tabStrip, rows: tabRows } = usePaneTabs({ tabs: TABS, activeValue: tab, onSelect: setTab, focused, dense: true });
+  const contentHeight = Math.max(5, height - tabRows);
+  // The board needs only its rows; the selected index history takes the rest.
+  const boardHeight = Math.max(5, Math.min(rows.length + 2, Math.floor(contentHeight * 0.62)));
+  const curve = data?.curve;
+  // The week- and month-back curves come from the histories the board already loaded.
+  const lookbacks = useMemo(() => data ? volatilityCurveLookbacks(data) : [], [data]);
+  const curveRows = useMemo(() => curve ? volatilityCurveRows(curve, lookbacks) : [], [curve, lookbacks]);
+  const curveSeries = useMemo(() => curve ? volatilityCurveSeries(curve, lookbacks, {
+    current: curve.termState === "backwardation" ? colors.negative : colors.positive, ghosts: curveGhostColors(colors),
+  }) : [], [colors, curve, lookbacks]);
+  const curveSelectedId = curveRows.some((row) => row.id === selectedId) ? selectedId : curveRows[0]?.id ?? null;
+  useChartTableSelection({ rows: curveRows, getId: curveRowKey, getDate: curveRowPosition, selectedId: curveSelectedId,
+    onSelect: setSelectedId, focused, enabled: tab === "curve" });
+  const curveHeight = Math.max(1, height - tabRows);
+  // The strip's label shares its row with the curve's shape and the point. A
+  // curve with fewer than two closes has neither, so the tenors take the band.
+  const curveBandStrip = curveStrip(curveSeries, formatIv, { caption: "IV %", selectedPointId: curveSelectedId });
+  const curveStats: StatItem[] = curve ? [
+    { id: "structure", label: "Structure", value: termStateLabel(curve.termState) ?? "--",
+      tone: curve.termState === "backwardation" ? "warning" : curve.termState === "contango" ? "positive" : "neutral" },
+    { id: "ratio", label: "3M/30D", value: number(curve.ratio),
+      detail: curve.ratio == null ? undefined : formatPercentileRank(curve.ratioPercentile1y, "1Y") },
+    { id: "spread", label: "Spread", value: `${number(curve.slope, true)} pts` },
+  ] : [];
+  const ready = !!data && (data.board.some((row) => row.value != null) || data.fred.metrics.some((metric) => metric.value != null));
+  const boardColumns = useMemo(() => dropColumnsToFit(BOARD_COLUMNS, width - 1, BOARD_DROP_ORDER), [width]);
+  return <Box width={width} height={height} flexDirection="column" overflow="hidden">
+    {tabStrip}
+    <PaneStatusBody subject="volatility" loading={resource.loading && !ready} error={!ready ? resource.error ?? result?.errors[0] ?? null : null} empty={!resource.loading && !ready}>
+      {data && tab === "curve" && <DataTableView<VolatilityCurveRow> focused={focused} columns={CURVE_COLUMNS} items={curveRows}
+        rootWidth={width} rootHeight={curveHeight}
+        emptyStateTitle="VIX curve unavailable." getItemKey={curveRowKey}
+        selection={{ kind: "id", selectedId: curveSelectedId, getId: curveRowKey, onChange: setSelectedId }}
+        onActivate={(row) => { setSelectedId(row.id); setTab("board"); }}
+        sortColumnId={null} sortDirection="asc"
+        getExportMetadata={() => [["as of", data.curve.date], ["source", data.curve.source === "fred" ? "FRED" : "Cboe"], ["units", "IV percent"], ["warnings", ...notices]]}
+        renderCell={(row, column) => {
+          if (column.id === "tenor") return { text: row.tenor, color: row.value == null ? colors.textMuted : colors.text };
+          if (column.id === "value") return { text: number(row.value), color: row.value == null ? colors.textMuted : colors.warning };
+          const change = column.id === "change1w" ? row.change1w : row.change1m;
+          // Up and down colors, as on every board; the board's 1Y percentile says whether vol is high.
+          return { text: number(change, true), color: change == null ? colors.textMuted : signColor(change) };
+        }}
+        rootBefore={<ChartTableHeader width={width} height={curveHeight} tableRows={curveRows.length} figures={curveStats} chart={curveBandStrip ? {
+          render: (size) => <CurveSurface series={curveSeries} width={size.width} height={size.height} display="chart"
+            caption={CURVE_CAPTION} xScale="log" formatValue={formatIv} formatAxisValue={formatPercentAxis}
+            selectedPointId={curveSelectedId} onSelectedPointChange={(id) => setSelectedId(id)} />,
+          minRows: curveSurfaceMinRows({ series: curveSeries, width, caption: CURVE_CAPTION }),
+          strip: curveBandStrip,
+        } : null} />} />}
+      {data && tab === "history" && <VolatilityHistoryChart term={data.term} width={width} height={contentHeight} focused={focused} />}
+      {data && tab === "board" && <>
+        <DataTableView<VolatilityBoardRow> focused={focused} columns={boardColumns} items={rows} rootWidth={width} rootHeight={boardHeight}
+          emptyStateTitle="Volatility indices unavailable." getItemKey={(row) => row.id} selection={{ kind: "id", selectedId: selected?.id ?? null, getId: (row) => row.id, onChange: setSelectedId }}
+          onActivate={(row) => setSelectedId(row.id)} sortable
+          sortColumnId={sort.columnId} sortDirection={sort.direction}
+          onHeaderClick={(id) => setSort((current) => nextHeaderSort(current, id, { resetTo: { columnId: null, direction: "asc" } }))}
+          onSortChange={(columnId, direction) => setSort({ columnId, direction })}
+          getExportMetadata={() => [["basis", "daily history; sparse observations retain their timestamp"], ["percentile", "one year, at least 200 observations and 300 calendar days"], ["warnings", ...notices]]}
+          renderCell={(row, column) => ({ text: column.id === "id" ? row.id.toUpperCase()
+            : column.id === "label" ? row.label
+            : column.id === "percentile1y" ? percentile(row.percentile1y)
+            : ["value", "change1d", "change1dPercent"].includes(column.id)
+              ? number(row[column.id as "value" | "change1d" | "change1dPercent"], column.id.startsWith("change"))
+              : String(row.date ?? "--"),
+            // Changes take the sign; vol high for its year is the warning a rise used to carry.
+            color: column.id.startsWith("change") && row.change1d != null ? signColor(row.change1d)
+              : column.id === "percentile1y" && row.percentile1y != null && Math.round(row.percentile1y) >= 80 ? colors.warning
+              : row.value == null ? colors.textMuted : colors.text })} />
+        {selected && <>
+          <Box height={1} paddingX={1}><Text fg={colors.textDim}>{`${selected.id.toUpperCase() === selected.label ? selected.label : `${selected.id.toUpperCase()} · ${selected.label}`} · ${selected.unit} · ${selected.date ?? "--"}`}</Text></Box>
+          <VolatilityIndexHistoryChart row={selected} width={width} height={Math.max(3, contentHeight - boardHeight - 1)} focused={focused} />
+        </>}
+      </>}
+    </PaneStatusBody>
+  </Box>;
+}

package/src/plugins/builtin/volatility/series.ts

@@ -0,0 +1,119 @@
+import { apiClient } from "../../../api-client";
+import type { SeriesAttribution, SeriesDefinition } from "../../../series/types";
+import { loadVolatilityTermHistory } from "./client";
+import { DVOL_COINS, dvolSeriesId, loadDvol, type DvolCurrency } from "./dvol";
+import { IMPLIED_CORRELATION_ROWS, type VolatilityTermHistory } from "./model";
+import { VOLATILITY_INDICES } from "../shared/volatility-indices";
+
+/** VIX and VIX 3M come from FRED's daily closes, listed with the other FRED series. */
+const FRED_LISTED = new Set(["vix", "vix3m"]);
+const CORRELATION = IMPLIED_CORRELATION_ROWS as Readonly<Record<string, string>>;
+
+const BOARD_NAMES: Readonly<Record<string, string>> = {
+  vxn: "Nasdaq 100 volatility index",
+  rvx: "Russell 2000 volatility index",
+  ovx: "Oil volatility index",
+  gvz: "Gold volatility index",
+  vxeem: "Emerging markets volatility index",
+  vxewz: "Brazil volatility index",
+  vxapl: "Apple volatility index",
+  vxazn: "Amazon volatility index",
+  vxgog: "Alphabet volatility index",
+  vxgs: "Goldman Sachs volatility index",
+  vxibm: "IBM volatility index",
+  cor1m: "S&P 500 implied correlation, 1 month",
+  cor3m: "S&P 500 implied correlation, 3 months",
+};
+
+async function loadImpliedCorrelation(code: string) {
+  const { series } = await apiClient.impliedVolatility<{ series: Array<{ id: string; observations: Array<{ date: string; value: number }> }> }>(
+    "implied-correlation",
+  );
+  const match = series.find((entry) => entry.id === code);
+  if (!match) throw new Error(`${code} history is unavailable.`);
+  return match.observations.filter((row) => Number.isFinite(row.value) && row.value > 0)
+    .map((row) => ({ date: row.date, value: row.value }));
+}
+
+/**
+ * Who a chart of the ratio cites: the publisher of its latest closes and the
+ * formula, with FRED named when it fills dates Cboe's closes do not reach.
+ */
+function termAttribution(term: VolatilityTermHistory): SeriesAttribution | undefined {
+  if (!term.publisher) return undefined;
+  if (term.publisher === "FRED") return { source: "FRED, VIX 3M / VIX (VXVCLS / VIXCLS)", publisher: "FRED" };
+  const filled = term.ratioHistory.some((point) => point.publisher === "FRED");
+  return filled ? { source: "Cboe, VIX 3M / VIX (FRED for earlier dates)", publisher: "Cboe, FRED" }
+    : { source: "Cboe, VIX 3M / VIX", publisher: "Cboe" };
+}
+
+/**
+ * Deribit's volatility index for a coin: each UTC day's close, today's
+ * latest print last, and refreshed through the day.
+ */
+function dvolSeries(currency: DvolCurrency): SeriesDefinition {
+  const coin = DVOL_COINS[currency];
+  return {
+    id: dvolSeriesId(currency),
+    name: `${coin} volatility index (DVOL)`,
+    unit: "index",
+    frequency: "daily",
+    group: "Volatility",
+    tags: ["volatility", "DVOL", "Deribit", "crypto", "implied volatility", currency, `${currency}-USD`, coin.toLowerCase()],
+    description: `Deribit's DVOL for ${currency}: the 30-day implied volatility its ${currency} options price, in vol points, daily since March 2021.`,
+    url: `https://www.deribit.com/statistics/${currency}/volatility-index`,
+    refreshMs: 5 * 60_000,
+    load: async ({ signal }) => {
+      const payload = await loadDvol(currency, signal ? { signal } : {});
+      return { points: payload.observations, attribution: { source: `Deribit DVOL (${currency})`, publisher: "Deribit" } };
+    },
+  };
+}
+
+/** Every index on the curve and the board, by its own close; implied correlation from its daily history. */
+export const VOLATILITY_SERIES: readonly SeriesDefinition[] = [
+  ...VOLATILITY_INDICES.filter((index) => !FRED_LISTED.has(index.id)).map((index): SeriesDefinition => {
+    const name = BOARD_NAMES[index.id] ?? index.label;
+    const tags = ["volatility", index.symbol.replace("^", "")];
+    const code = CORRELATION[index.id];
+    return code
+      ? {
+        id: `volatility:${index.id}`,
+        name,
+        unit: "index",
+        frequency: "daily",
+        group: "Volatility",
+        tags: [...tags, "correlation"],
+        load: async () => ({ points: await loadImpliedCorrelation(code) }),
+      }
+      : {
+        id: `volatility:${index.id}`,
+        name,
+        unit: "index",
+        frequency: "daily",
+        group: "Volatility",
+        tags,
+        expression: `${index.symbol}:close`,
+      };
+  }),
+  {
+    id: "volatility:vix-term-ratio",
+    name: "VIX 3M / VIX ratio",
+    unit: "ratio",
+    frequency: "daily",
+    group: "Volatility",
+    tags: ["term structure", "contango", "backwardation", "VIX"],
+    description: "VIX 3M over VIX on each date both closed, from Cboe's daily closes and FRED's before them; above 1 is contango.",
+    load: async ({ start, signal }) => {
+      const { term, warning } = await loadVolatilityTermHistory({ ...(start ? { start } : {}), ...(signal ? { signal } : {}) });
+      const attribution = termAttribution(term);
+      return {
+        points: term.ratioHistory.map((point) => ({ date: point.date, value: point.value })),
+        ...(warning ? { warning } : {}),
+        ...(attribution ? { attribution } : {}),
+      };
+    },
+  },
+  dvolSeries("BTC"),
+  dvolSeries("ETH"),
+];

package/src/plugins/builtin/world-indices/client.ts

@@ -0,0 +1,58 @@
+import type { DataProvider } from "../../../types/data-provider";
+import type { Quote } from "../../../types/financials";
+import type { IndexEntry } from "./indices";
+import { errorMessage } from "../../../utils/errors";
+import { isNoProviderMessage } from "../../../sources/provider-errors";
+
+/** What a row says in place of figures the feed does not carry. */
+export const NOT_IN_FEED = "not available from the feed";
+
+/** Whether the feed has no quote for a symbol, as opposed to a quote that failed to load. */
+export function isFeedGap(error: string | null | undefined): boolean {
+  return !!error && isNoProviderMessage(error);
+}
+
+export interface WorldIndexQuoteResult {
+  quotes: Map<string, Quote | null>;
+  /** Failures to load: a timeout, an outage. A symbol the feed simply lacks is in `gaps`. */
+  errors: string[];
+  /** Symbols the feed has no quote for. They are a data gap, so their rows say so rather than carry an error. */
+  gaps: Set<string>;
+}
+
+export async function loadWorldIndexQuotes(
+  entries: readonly IndexEntry[],
+  provider: DataProvider,
+): Promise<WorldIndexQuoteResult> {
+  const quotes = new Map<string, Quote | null>();
+  const errors: string[] = [];
+  const gaps = new Set<string>();
+  const fail = (symbol: string, error: unknown) => {
+    const message = errorMessage(error);
+    if (isFeedGap(message)) gaps.add(symbol);
+    else errors.push(`${symbol}: ${message}`);
+  };
+  if (provider.getQuotesBatch) {
+    const results = await provider.getQuotesBatch(
+      entries.map((entry) => ({ symbol: entry.symbol, exchange: "" })),
+    );
+    const bySymbol = new Map(results.map((result) => [result.target.symbol, result]));
+    for (const entry of entries) {
+      const result = bySymbol.get(entry.symbol);
+      quotes.set(entry.symbol, result?.quote ?? null);
+      if (result?.error) fail(entry.symbol, result.error);
+      else if (!result?.quote) errors.push(`${entry.symbol}: quote unavailable`);
+    }
+    return { quotes, errors, gaps };
+  }
+
+  await Promise.all(entries.map(async (entry) => {
+    try {
+      quotes.set(entry.symbol, await provider.getQuote(entry.symbol, ""));
+    } catch (error) {
+      quotes.set(entry.symbol, null);
+      fail(entry.symbol, error);
+    }
+  }));
+  return { quotes, errors, gaps };
+}

package/src/plugins/builtin/world-indices/footer.ts

@@ -0,0 +1,25 @@
+import { usePaneFooter, type PaneFooterSegment } from "../../../components";
+import { usePaneRefreshKey } from "../../../components/data-table/table-pane";
+import {
+  boardErrorMessage,
+  quoteBoardFooterInfo,
+  quoteBoardStatus,
+  type BoardQuoteMap,
+} from "../shared/use-quote-board";
+
+export function useWorldIndicesFooter(quotes: BoardQuoteMap, onRefresh: () => void, focused: boolean) {
+  const status = quoteBoardStatus(quotes);
+  const errorMessage = boardErrorMessage(quotes);
+
+  usePaneRefreshKey(onRefresh, { focused });
+
+  usePaneFooter(
+    "world-indices",
+    () => {
+      const info: PaneFooterSegment[] = quoteBoardFooterInfo(status);
+      if (errorMessage) info.push({ id: "reason", parts: [{ text: errorMessage, tone: "warning" }] });
+      return { info };
+    },
+    [errorMessage, focused, onRefresh, status.latestTs, status.loading, status.savedAt, status.stale, status.unavailable],
+  );
+}

package/src/plugins/builtin/world-indices/headless.ts

@@ -0,0 +1,148 @@
+import type { DataProvider } from "../../../types/data-provider";
+import type {
+  HeadlessBundleResult,
+  HeadlessPaneDefinition,
+  HeadlessPaneLoadArgs,
+} from "../../../types/plugin";
+import { formatNumber, formatPercentRaw } from "../../../utils/format";
+import { EXTENDED_SESSION_LABELS, getQuoteSessionFields, marketStateLabel, type ExtendedSession } from "../../../market-data/market/status";
+import type { MarketState } from "../../../types/financials";
+import { loadWorldIndexQuotes, NOT_IN_FEED, type WorldIndexQuoteResult } from "./client";
+import {
+  getIndicesByRegion,
+  REGION_LABELS,
+  REGION_ORDER,
+  WORLD_INDICES,
+  type IndexEntry,
+} from "./indices";
+import { quoteFreshnessFields } from "../shared/report-freshness";
+
+/** A row for an index the feed does not carry has no figures to print; its last column says why. */
+const isGap = (row: Record<string, unknown>) => row.unavailable === true;
+
+const COLUMNS = [
+  { key: "shortName", header: "Index", shrink: false },
+  { key: "name", header: "Name" },
+  {
+    key: "price",
+    header: "Last",
+    align: "right" as const,
+    format: (value: unknown, row: Record<string, unknown>) => isGap(row) ? "" : value == null
+      ? "-"
+      : formatNumber(Number(value), 2),
+  },
+  {
+    key: "change",
+    header: "Change",
+    align: "right" as const,
+    format: (value: unknown, row: Record<string, unknown>) => isGap(row) ? "" : value == null ? "-" : `${Number(value) >= 0 ? "+" : ""}${formatNumber(Number(value), 2)}`,
+  },
+  {
+    key: "changePercent",
+    header: "Change %",
+    align: "right" as const,
+    format: (value: unknown, row: Record<string, unknown>) => isGap(row) ? "" : value == null ? "-" : formatPercentRaw(Number(value)),
+  },
+  {
+    key: "marketState",
+    header: "Session",
+    shrink: false,
+    format: (value: unknown, row: Record<string, unknown>) => isGap(row) ? "" : typeof value === "string" && value ? marketStateLabel(value as MarketState) ?? value : "-",
+  },
+  {
+    key: "lastUpdated",
+    header: "Updated",
+    shrink: false,
+    format: (value: unknown, row: Record<string, unknown>) => {
+      const time = value == null ? Number.NaN : Number(value);
+      return Number.isFinite(time) ? `${new Date(time).toISOString().slice(0, 16).replace("T", " ")} UTC` : isGap(row) ? NOT_IN_FEED : "-";
+    },
+  },
+];
+
+/** A pre-market or after-hours print and its move from the regular close, for a row that has one. */
+function extendedColumn(session: ExtendedSession) {
+  return {
+    key: "extendedPrice",
+    header: EXTENDED_SESSION_LABELS[session],
+    align: "right" as const,
+    format: (value: unknown, row: Record<string, unknown>) => row.extendedSession === session && typeof value === "number"
+      ? `${formatNumber(value, 2)} ${formatPercentRaw(typeof row.extendedChangePercent === "number" ? row.extendedChangePercent : undefined)}`
+      : isGap(row) ? "" : "-",
+  };
+}
+
+/** The table's columns, with an extended column after Change % only where a row has such a print. */
+function sectionColumns(rows: readonly Record<string, unknown>[]) {
+  const sessions = (["PRE", "POST"] as const).filter((session) => rows.some((row) => row.extendedSession === session));
+  return sessions.length === 0 ? COLUMNS : [...COLUMNS.slice(0, 5), ...sessions.map(extendedColumn), ...COLUMNS.slice(5)];
+}
+
+function projectWorldIndicesHeadless(
+  entries: readonly IndexEntry[],
+  loaded: WorldIndexQuoteResult,
+): HeadlessBundleResult {
+  const grouped = getIndicesByRegion(entries);
+  const isGapEntry = (entry: IndexEntry) => loaded.gaps.has(entry.symbol) && !loaded.quotes.get(entry.symbol);
+  return {
+    sections: REGION_ORDER.flatMap((region) => {
+      const regionEntries = grouped.get(region) ?? [];
+      if (regionEntries.length === 0) return [];
+      const rows = regionEntries.map((entry) => {
+        const quote = loaded.quotes.get(entry.symbol);
+        // Last and Change are the regular session, as `ticker` reads them.
+        const { price, change, changePercent, ...extended } = getQuoteSessionFields(quote);
+        return {
+          ...quoteFreshnessFields(quote),
+          ...entry,
+          price,
+          unit: "index points",
+          currency: quote?.currency ?? null,
+          change,
+          changePercent,
+          ...extended,
+          marketState: quote?.marketState ?? null,
+          lastUpdated: quote?.lastUpdated ?? null,
+          ...(isGapEntry(entry) ? { unavailable: true } : {}),
+        };
+      });
+      return [{ title: REGION_LABELS[region], columns: sectionColumns(rows), rows }];
+    }),
+    errors: loaded.errors,
+    // A symbol the feed lacks is a gap in the data, not a failure: its row says so, and the report is not whole.
+    ...(entries.some(isGapEntry) ? { unavailableSymbols: entries.filter(isGapEntry).map((entry) => entry.symbol) } : {}),
+    metadata: {
+      requested: entries.length,
+      available: [...loaded.quotes.values()].filter(Boolean).length,
+    },
+  };
+}
+
+interface WorldIndicesHeadlessDependencies {
+  load(
+    args: HeadlessPaneLoadArgs,
+    entries: readonly IndexEntry[],
+    provider: DataProvider,
+  ): Promise<WorldIndexQuoteResult>;
+}
+
+const defaultDependencies: WorldIndicesHeadlessDependencies = {
+  load: (_args, entries, provider) => loadWorldIndexQuotes(entries, provider),
+};
+
+function createWorldIndicesHeadless(
+  dependencies: WorldIndicesHeadlessDependencies = defaultDependencies,
+): HeadlessPaneDefinition<"bundle"> {
+  return {
+    shape: "bundle",
+    argument: { kind: "none" },
+    options: [],
+    describe: "World Equity Indices",
+    async load(args, ctx) {
+      const loaded = await dependencies.load(args, WORLD_INDICES, ctx.marketData);
+      return projectWorldIndicesHeadless(WORLD_INDICES, loaded);
+    },
+  };
+}
+
+export const worldIndicesHeadless = createWorldIndicesHeadless();