gloomberb 0.16.0 → 0.16.2

package/src/plugins/builtin/futures-curve/model.ts

@@ -5,13 +5,28 @@ import { compositeAxisTicks } from "../../../components/chart/composite/format";
 import type { CompositeAxisDomain } from "../../../components/chart/composite/types";
 import { FUTURES_CONTRACTS, tickDecimals } from "../futures/contracts";
 import { formatPercentileRank } from "../../../utils/format";
+import { cryptoPairCoin, isFuturesSymbol } from "../shared/crypto-pair";
+import { parseReportTime } from "../../../utils/utc-time";
 import { compareSortValues, type SortDirection } from "../../../utils/sort-values";
 
+/**
+ * CME crypto futures have a curve but no FUT board row, so their name and tick
+ * live here rather than in the catalogue the board lists. Outright ticks:
+ * BTC $5, ETH $0.50, SOL $0.05, XRP $0.0005 (each $25 a contract).
+ */
+const CRYPTO_CURVE_ROOTS: readonly { code: string; name: string; tick: number }[] = [
+  { code: "BTC", name: "Bitcoin", tick: 5 }, { code: "ETH", name: "Ether", tick: 0.5 },
+  { code: "SOL", name: "Solana", tick: 0.05 }, { code: "XRP", name: "XRP", tick: 0.0005 },
+];
+const rootLabel = (code: string, name: string) => name === code ? code : `${code} ${name}`;
+
 export const CURVE_ROOTS = [
-  ...FUTURES_CONTRACTS.filter((row) => row.curve !== false).map((row) => ({ value: row.code, label: `${row.code} ${row.name}` })),
+  ...FUTURES_CONTRACTS.filter((row) => row.curve !== false).map((row) => ({ value: row.code, label: rootLabel(row.code, row.name) })),
   { value: "VX", label: "VX VIX Futures" },
+  ...CRYPTO_CURVE_ROOTS.map((row) => ({ value: row.code, label: rootLabel(row.code, row.name) })),
 ];
 
+/** A root typed as an argument, a stored pane setting or a request: every listed root, crypto included. */
 export function normalizeCurveRoot(value: unknown): string | null {
   if (typeof value !== "string") return null;
   const raw = value.trim().toUpperCase().replace(/=F$/, "");
@@ -19,6 +34,26 @@ export function normalizeCurveRoot(value: unknown): string | null {
   return CURVE_ROOTS.some((row) => row.value === root) ? root : null;
 }
 
+/** What a root nothing lists is told, with roots that work. */
+export function unsupportedCurveRootMessage(value: unknown): string {
+  const examples = ["ES", "CL", "GC", "ZN"].filter((root) => CURVE_ROOTS.some((row) => row.value === root));
+  return `Unsupported futures root: ${String(value)}. Try ${examples.join(", ")}.`;
+}
+
+/**
+ * The root for the ticker under the cursor, when CTM is opened without an
+ * argument. The crypto roots are also US ticker symbols (Grayscale's mini
+ * trusts are BTC and ETH), so a bare one is the equity's, never the future's:
+ * only a futures symbol (BTC=F) or a coin pair (BTC-USD) names the crypto curve.
+ */
+export function curveRootForTicker(ticker: unknown): string | null {
+  if (typeof ticker !== "string") return null;
+  const coin = cryptoPairCoin(ticker);
+  if (coin) return CRYPTO_CURVE_ROOTS.some((row) => row.code === coin) ? coin : null;
+  const root = normalizeCurveRoot(ticker);
+  return root && CRYPTO_CURVE_ROOTS.some((row) => row.code === root) && !isFuturesSymbol(ticker) ? null : root;
+}
+
 /**
  * Treasury futures trade in fractions of a 32nd (ZT to 1/256, ZF 1/128, ZN
  * 1/64, ZB and UB 1/32), so the catalogue leaves their tick unset. A root
@@ -32,7 +67,7 @@ function curvePriceDecimals(root: string): number {
   const rateTick = RATE_TICKS[root];
   if (rateTick != null) return tickDecimals(rateTick);
   if (root === "VX") return 4;
-  const tick = FUTURES_CONTRACTS.find((row) => row.code === root)?.tick;
+  const tick = FUTURES_CONTRACTS.find((row) => row.code === root)?.tick ?? CRYPTO_CURVE_ROOTS.find((row) => row.code === root)?.tick;
   return tick == null ? 5 : Math.max(2, tickDecimals(tick));
 }
 
@@ -155,17 +190,166 @@ const CHANGE_COLUMNS: Readonly<Record<string, CurveLookback>> = { change1w: "1W"
 
 type CurveSortKey = "symbol" | "expiration" | "price" | "change" | "openInterest" | "volume" | "percentile" | "asOf";
 
+const BASIS_COLUMNS: Readonly<Record<string, "vsSpotPct" | "annualisedBasisPct">> = { vsSpot: "vsSpotPct", annBasis: "annualisedBasisPct" };
+
 export function sortCurveContracts(rows: readonly FuturesContract[], id: string, direction: SortDirection,
-  changes?: CurveContractChanges): FuturesContract[] {
+  changes?: CurveContractChanges, basis?: CurveBasisRows): FuturesContract[] {
   const keys: Record<string, CurveSortKey> = { symbol: "symbol", expiry: "expiration", price: "price", change: "change", oi: "openInterest", volume: "volume", percentile: "percentile", asOf: "asOf" };
   const key = keys[id] ?? "expiration";
   const lookback = CHANGE_COLUMNS[id];
-  const value = (row: FuturesContract) => lookback ? changes?.get(row.symbol)?.[lookback] ?? null : row[key] ?? null;
+  const basisKey = BASIS_COLUMNS[id];
+  const value = (row: FuturesContract) => lookback ? changes?.get(row.symbol)?.[lookback] ?? null
+    : basisKey ? basis?.get(row.symbol)?.[basisKey] ?? null : row[key] ?? null;
   return [...rows].sort((a, b) => compareSortValues(value(a), value(b), direction));
 }
 
 const DAY_MS = 86_400_000;
 
+/**
+ * The quote each crypto root's basis is measured against: the terminal's USD
+ * pair, the same quote every other pane shows, not the CME reference rate, so
+ * a small gap to settlement is expected. A root missing here has no basis
+ * columns; add its spot symbol to give it some.
+ */
+const BASIS_SPOT_SYMBOLS: ReadonlyMap<string, string> = new Map([
+  ["BTC", "BTC-USD"], ["ETH", "ETH-USD"], ["SOL", "SOL-USD"], ["XRP", "XRP-USD"],
+]);
+
+export function basisSpotSymbol(root: string): string | null {
+  return BASIS_SPOT_SYMBOLS.get(root) ?? null;
+}
+
+/** Crypto trades around the clock, so a spot quote older than this no longer prices a live future. */
+const SPOT_STALE_MS = 10 * 60_000;
+/** A free account's quote is held back on purpose; that delay is not staleness, so it is allowed on top. */
+const DELAYED_SPOT_MS = 15 * 60_000;
+
+/** The spot a curve's basis uses, or why there is none. `asOf` is the quote's own time, never the fetch's. */
+export interface CurveSpot {
+  symbol: string;
+  price: number | null;
+  /** UTC ISO instant of the quote. */
+  asOf: string | null;
+  status: "ok" | "stale" | "missing";
+  reason: string | null;
+}
+
+export interface SpotQuote {
+  price: number;
+  lastUpdated: number;
+  stale?: boolean;
+  dataSource?: string;
+}
+
+const positive = (value: unknown): value is number => typeof value === "number" && Number.isFinite(value) && value > 0;
+
+function quoteAge(ms: number): string {
+  const minutes = Math.floor(ms / 60_000);
+  if (minutes < 60) return `${minutes}m`;
+  const hours = Math.floor(minutes / 60);
+  return hours < 48 ? `${hours}h` : `${Math.floor(hours / 24)}d`;
+}
+
+/** Judges one spot quote at `now`: usable, older than the rule allows, or absent. */
+export function curveSpot(symbol: string, quote: SpotQuote | null | undefined, now: number): CurveSpot {
+  if (!quote || !positive(quote.price)) return { symbol, price: null, asOf: null, status: "missing", reason: `no ${symbol} quote` };
+  const time = quote.lastUpdated;
+  if (!Number.isFinite(time) || time <= 0) {
+    return { symbol, price: quote.price, asOf: null, status: "stale", reason: `${symbol} quote has no time` };
+  }
+  const asOf = new Date(time).toISOString().replace(".000Z", "Z");
+  const age = now - time;
+  const limit = SPOT_STALE_MS + (quote.dataSource === "delayed" ? DELAYED_SPOT_MS : 0);
+  if (age > limit) return { symbol, price: quote.price, asOf, status: "stale", reason: `${symbol} quote is ${quoteAge(age)} old` };
+  if (quote.stale === true) return { symbol, price: quote.price, asOf, status: "stale", reason: `${symbol} quote is stale` };
+  return { symbol, price: quote.price, asOf, status: "ok", reason: null };
+}
+
+/** How far the contract trades over (positive) or under spot, in percent. */
+export function vsSpotPct(futures: number | null | undefined, spot: number | null | undefined): number | null {
+  return positive(futures) && positive(spot) ? (futures / spot - 1) * 100 : null;
+}
+
+/** Calendar days from the UTC date of the spot's timestamp to the contract's expiration date. */
+export function daysToExpiry(spotTime: number, expiration: string): number | null {
+  const expiry = Date.parse(`${expiration}T00:00:00Z`);
+  if (!Number.isFinite(spotTime) || !Number.isFinite(expiry)) return null;
+  const spotDay = Date.parse(`${new Date(spotTime).toISOString().slice(0, 10)}T00:00:00Z`);
+  return Math.round((expiry - spotDay) / DAY_MS);
+}
+
+/** The premium over spot as a yearly rate, on a 365-day year. Blank on or past expiry, where it has no meaning. */
+export function annualisedBasisPct(futures: number | null | undefined, spot: number | null | undefined, days: number | null): number | null {
+  if (!positive(futures) || !positive(spot) || days == null || !Number.isFinite(days) || days <= 0) return null;
+  return (futures / spot - 1) * 365 / days * 100;
+}
+
+/** A contract that printed longer than this before the spot quote is too old to read against it. */
+const CONTRACT_PRINT_MAX_AGE_MS = 60 * 60_000;
+
+export interface ContractBasis {
+  vsSpotPct: number | null;
+  annualisedBasisPct: number | null;
+  /** Priced and not flagged stale, but its last print is over an hour before spot: a thin month. */
+  thin: boolean;
+}
+
+const NO_BASIS: ContractBasis = { vsSpotPct: null, annualisedBasisPct: null, thin: false };
+
+/**
+ * One contract's basis. Blank without a usable spot, and for a contract whose
+ * own price is missing or stale: an old future against a live spot misleads.
+ * So does a print more than an hour older than the spot (`thin`): the server's
+ * stale flag allows two sessions, which a quote that moves all day outruns. A
+ * date-only `asOf` is UTC midnight of that date, one that cannot be read
+ * counts as old, and a print newer than the spot is never old (the spot of a
+ * delayed feed trails the futures).
+ */
+export function contractBasis(row: Pick<FuturesContract, "price" | "stale" | "expiration" | "asOf">, spot: CurveSpot): ContractBasis {
+  if (spot.status !== "ok" || spot.asOf == null || row.stale) return NO_BASIS;
+  const vs = vsSpotPct(row.price, spot.price);
+  if (vs == null) return NO_BASIS;
+  const spotTime = Date.parse(spot.asOf);
+  const printed = parseReportTime(row.asOf)?.time ?? null;
+  if (printed == null || spotTime - printed > CONTRACT_PRINT_MAX_AGE_MS) return { ...NO_BASIS, thin: true };
+  return { vsSpotPct: vs, annualisedBasisPct: annualisedBasisPct(row.price, spot.price, daysToExpiry(spotTime, row.expiration)), thin: false };
+}
+
+/** A basis in percent, signed; one that rounds to zero stays unsigned. */
+export function curveBasisPercent(value: number | null, decimals: number): string {
+  if (value == null) return "--";
+  const text = Math.abs(value).toFixed(decimals);
+  return /[1-9]/.test(text) ? `${value > 0 ? "+" : "-"}${text}%` : `${text}%`;
+}
+
+/** The footer's spot: `spot BTC-USD 67,250.10 · 07:25 UTC`, with the date when the quote is not from today. */
+export function curveSpotLabel(spot: CurveSpot, root: string, now: number): string {
+  const decimals = curvePriceDecimals(root);
+  const price = spot.price == null ? "--" : spot.price.toLocaleString("en-US", { minimumFractionDigits: decimals, maximumFractionDigits: decimals });
+  const stamp = curveTimestamp(spot.asOf);
+  const today = new Date(now).toISOString().slice(0, 10);
+  return `spot ${spot.symbol} ${price} · ${spot.asOf?.startsWith(today) ? stamp.slice(11) : stamp} UTC`;
+}
+
+/** The basis columns' sort values, which live beside the contract rather than on it. */
+export type CurveBasisRows = ReadonlyMap<string, ContractBasis>;
+
+export function curveBasisRows(rows: readonly FuturesContract[], spot: CurveSpot | null): CurveBasisRows {
+  return new Map(rows.map((row) => [row.symbol, spot ? contractBasis(row, spot) : NO_BASIS]));
+}
+
+/** The contracts a good spot left blank for their old print. */
+export function thinContractCount(basis: Iterable<ContractBasis>): number {
+  let count = 0;
+  for (const row of basis) if (row.thin) count += 1;
+  return count;
+}
+
+/** The footer warning that thin contracts have no basis: the pane's `!` notice, which keeps the footer row for the quote times. */
+export function thinContractsNotice(count: number): string {
+  return `Basis blank on ${count} thin contract${count === 1 ? "" : "s"} (last print over 1h before spot)`;
+}
+
 /** A past date for the as-of view: empty (or "latest") for the live curve, else YYYY-MM-DD no later than today. */
 export function curveAsOfDate(value: unknown, now = new Date()): string {
   const date = typeof value === "string" ? value.trim() : "";

package/src/plugins/builtin/futures-curve/pane.tsx

@@ -1,5 +1,6 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { chartTableChromeRows, ChartTableHeader, CurveSurface, curveGhostColors, DataTableView, Notice, PaneStatusBody, QueryBar, useChartTableSelection, usePaneNoticeFooter, usePaneStatusFooter, usePaneTabs, type DataTableColumn, type StatItem } from "../../../components";
+import { fitChartTableColumns } from "../../../components/chart-table";
 import { curveStrip, curveSurfaceMinRows } from "../../../components/chart/curve";
 import { isAccessDenied } from "../../../api-client/errors";
 import type { FuturesContract } from "../../../api-client/futures-curve";
@@ -13,8 +14,9 @@ import { nextHeaderSort, type SortDirection } from "../../../utils/sort-values";
 import { useAutoRefresh } from "../../../react/auto-refresh";
 import { futuresSessionRefreshInterval } from "../shared/futures-session";
 import { useResearchCloudSession } from "../shared/research-cloud-session";
+import { useQuoteBoard } from "../shared/use-quote-board";
 import { getCachedFuturesCurve, loadFuturesCurve, loadFuturesCurveAsOf } from "./client";
-import { curveAsOfDate, curveAxisPrice, curveChangeText, curveContractChanges, curvePrice, curveRank, curveTimestamp, DEFAULT_CURVE_HORIZON, futuresCurveSeries, newestQuote, normalizeCurveRoot, sortCurveContracts, type CurveContractChanges } from "./model";
+import { basisSpotSymbol, curveAsOfDate, curveAxisPrice, curveBasisPercent, curveBasisRows, curveChangeText, curveContractChanges, curvePrice, curveRank, curveSpot, curveSpotLabel, curveTimestamp, DEFAULT_CURVE_HORIZON, futuresCurveSeries, newestQuote, normalizeCurveRoot, sortCurveContracts, thinContractCount, thinContractsNotice, unsupportedCurveRootMessage, type CurveContractChanges } from "./model";
 
 const TABS = [{ value: "curve", label: "Curve" }, { value: "contracts", label: "Contracts" }];
 const COLUMNS: DataTableColumn[] = [
@@ -38,6 +40,19 @@ const CURVE_COLUMNS: DataTableColumn[] = [
   { id: "change1m", label: "VS 1M", width: 10, align: "right" },
   ...COLUMNS.slice(4, -1),
 ];
+// A crypto curve also reads against spot. Its widths are the tightest each column
+// holds (BTCV26.CME, 128000.00), so the two new columns fit beside the rest, and
+// a narrow pane drops the least useful ones before a number would be clipped.
+const BASIS_CURVE_COLUMNS: DataTableColumn[] = [
+  { ...CURVE_COLUMNS[0]!, width: 10 }, CURVE_COLUMNS[1]!, { ...CURVE_COLUMNS[2]!, width: 10 },
+  { id: "vsSpot", label: "VS SPOT", width: 9, align: "right" },
+  { id: "annBasis", label: "ANN BASIS", width: 11, align: "right" },
+  ...CURVE_COLUMNS.slice(3),
+];
+const BASIS_DROP_ORDER = ["percentile", "volume", "change1m", "oi"];
+const NO_SYMBOLS: string[] = [];
+/** The spot's age is judged against the clock, so a quote that stops moving still goes stale on screen. */
+const SPOT_CLOCK_MS = 30_000;
 const signedPercent = (value: number | null) => value == null ? "--" : formatPercentRaw(value);
 const integer = (value: number | null) => value == null ? "--" : value.toLocaleString("en-US");
 const contractKey = (row: FuturesContract) => row.symbol;
@@ -50,7 +65,7 @@ export function FuturesCurvePane(props: PaneProps) {
   const requested = pane?.settings?.root ?? pane?.params?.root ?? "ES";
   const root = normalizeCurveRoot(requested);
   return root ? <FuturesCurveView key={root} {...props} root={root} />
-    : <PaneStatusBody error={`Unsupported futures root: ${String(requested)}`} subject="futures curve" />;
+    : <PaneStatusBody error={unsupportedCurveRootMessage(requested)} subject="futures curve" />;
 }
 
 function FuturesCurveView({ width, height, focused, root }: PaneProps & { root: string }) {
@@ -79,6 +94,23 @@ function FuturesCurveView({ width, height, focused, root }: PaneProps & { root:
   // A pending date change must never relabel the previous curve as the new one.
   const data = resource.data?.date === requestedDate ? resource.data.payload : null;
   usePaneTitle(`CTM ${root}`);
+  const curveTab = tab === "curve";
+  // The Curve tab of a crypto root reads against spot; a past date has no spot history.
+  const spotSymbol = basisSpotSymbol(root);
+  const basisActive = curveTab && !requestedDate && spotSymbol != null;
+  const spotSymbols = useMemo(() => basisActive ? [spotSymbol] : NO_SYMBOLS, [basisActive, spotSymbol]);
+  const { quotes: spotQuotes } = useQuoteBoard(spotSymbols);
+  const [clock, setClock] = useState(() => Date.now());
+  useEffect(() => {
+    if (!basisActive) return;
+    setClock(Date.now());
+    const timer = setInterval(() => setClock(Date.now()), SPOT_CLOCK_MS);
+    return () => clearInterval(timer);
+  }, [basisActive]);
+  const spotState = spotSymbol ? spotQuotes.get(spotSymbol) : undefined;
+  // Until the first answer there is nothing to say: no reason, only blank cells.
+  const spot = useMemo(() => !basisActive || !spotSymbol || !spotState || spotState.loading && !spotState.quote ? null
+    : curveSpot(spotSymbol, spotState.quote, clock), [basisActive, clock, spotState, spotSymbol]);
   const staleCount = data?.contracts.filter((row) => row.stale).length ?? 0;
   const newest = data ? newestQuote(data.contracts) : null;
   // A past curve is named by the session it holds: a weekend or holiday date shows the session before it.
@@ -86,8 +118,9 @@ function FuturesCurveView({ width, height, focused, root }: PaneProps & { root:
     requestedDate ? Date.parse(`${requestedDate}T00:00:00Z`) : Date.now(), requestedDate ? data.asOf ?? requestedDate : undefined) : [],
   [data, colors, horizon, requestedDate]);
   const changes = useMemo<CurveContractChanges>(() => data ? curveContractChanges(data) : new Map(), [data]);
-  const rows = useMemo(() => sortCurveContracts(data?.contracts ?? [], sort.columnId, sort.direction, changes), [data, sort, changes]);
-  const curveTab = tab === "curve";
+  const basis = useMemo(() => curveBasisRows(basisActive ? data?.contracts ?? [] : [], spot), [basisActive, data, spot]);
+  const thinCount = useMemo(() => thinContractCount(basis.values()), [basis]);
+  const rows = useMemo(() => sortCurveContracts(data?.contracts ?? [], sort.columnId, sort.direction, changes, basis), [data, sort, changes, basis]);
   // The curve tab lists the contracts the chart plots; Contracts keeps every one.
   const curveRows = useMemo(() => {
     const charted = new Set(curves[0]?.points.map((point) => point.id));
@@ -108,7 +141,8 @@ function FuturesCurveView({ width, height, focused, root }: PaneProps & { root:
   const { strip: tabStrip, rows: tabRows } = usePaneTabs({ tabs: TABS, activeValue: tab, onSelect: setTab, focused, dense: true });
   // The query bar takes one row below the tabs, and a refused date one more.
   const bodyHeight = Math.max(1, height - tabRows - 1 - (dateError ? 1 : 0));
-  const columns = curveTab ? CURVE_COLUMNS : COLUMNS;
+  const columns = useMemo(() => !curveTab ? COLUMNS : basisActive ? fitChartTableColumns(BASIS_CURVE_COLUMNS, width, BASIS_DROP_ORDER) : CURVE_COLUMNS,
+    [basisActive, curveTab, width]);
   const formatValue = useCallback((value: number) => curvePrice(value, root), [root]);
   const formatChange = useCallback((value: number) => curveChangeText(value, root), [root]);
   const caption = `${sentenceCase(data?.quoteUnit ?? data?.currency ?? "price")} by contract month`;
@@ -142,7 +176,9 @@ function FuturesCurveView({ width, height, focused, root }: PaneProps & { root:
   };
   // A past date with no archived curve says why in the body, not behind the warning.
   const emptyPast = !!requestedDate && !!data && !data.contracts.length;
-  usePaneNoticeFooter({ registrationId: "futures-curve:notices", focused, notices: emptyPast ? [] : data?.gaps ?? [] });
+  // Thin contracts join the data warnings: the info row has no room for them beside the quote times.
+  usePaneNoticeFooter({ registrationId: "futures-curve:notices", focused,
+    notices: emptyPast ? [] : [...data?.gaps ?? [], ...thinCount ? [thinContractsNotice(thinCount)] : []] });
   const delay = Math.max(0, ...(data?.contracts.map((row) => row.delayMinutes ?? 0) ?? []));
   usePaneStatusFooter({ registrationId: "futures-curve", loading: resource.loading, error: resource.error,
     hints: [
@@ -152,6 +188,8 @@ function FuturesCurveView({ width, height, focused, root }: PaneProps & { root:
     info: data ? [
       { id: "source", parts: [{ text: `${requestedDate ? "daily archive" : data.source === "cboe" ? "settlement" : delay > 0 ? `${delay}m delayed` : "dated quotes"} · ${data.quoteUnit ?? data.currency ?? "units unavailable"} · ${curveTimestamp(newest)}${newest?.includes("T") ? " UTC" : ""}`, tone: "muted" }] },
       ...(staleCount ? [{ id: "stale", parts: [{ text: `${staleCount} of ${data.contracts.length} stale`, tone: "warning" as const }] }] : []),
+      ...(spot ? [{ id: "spot", parts: [spot.status === "ok" ? { text: curveSpotLabel(spot, root, clock), tone: "muted" as const }
+        : { text: `Basis blank: ${spot.reason}`, tone: "warning" as const }] }] : []),
     ] : [],
   });
   const tableChromeRows = chartTableChromeRows(columns, width);
@@ -166,8 +204,8 @@ function FuturesCurveView({ width, height, focused, root }: PaneProps & { root:
   const renderCell = useCallback((row: FuturesContract, column: DataTableColumn) => {
     if (column.id === "symbol") return { text: row.symbol };
     if (column.id === "expiry") return { text: row.expiration, color: colors.textMuted };
-    // Without the AS OF column, a stale quote shows on its price.
-    if (column.id === "price") return { text: curvePrice(row.price, root), color: curveTab && row.stale ? colors.warning : undefined };
+    // Without the AS OF column, a stale quote shows on its price, and so does a print too old for the spot.
+    if (column.id === "price") return { text: curvePrice(row.price, root), color: curveTab && (row.stale || basis.get(row.symbol)?.thin) ? colors.warning : undefined };
     if (column.id === "change") {
       const text = curveChangeText(row.change ?? null, root);
       return { text, color: text.startsWith("+") ? colors.positive : text.startsWith("-") && /[1-9]/.test(text) ? colors.negative : colors.textMuted };
@@ -176,11 +214,15 @@ function FuturesCurveView({ width, height, focused, root }: PaneProps & { root:
       const change = changes.get(row.symbol)?.[column.id === "change1w" ? "1W" : "1M"] ?? null;
       return { text: curveChangeText(change, root), color: colors.textMuted };
     }
+    if (column.id === "vsSpot" || column.id === "annBasis") {
+      const cell = basis.get(row.symbol);
+      return { text: column.id === "vsSpot" ? curveBasisPercent(cell?.vsSpotPct ?? null, 2) : curveBasisPercent(cell?.annualisedBasisPct ?? null, 1), color: colors.textMuted };
+    }
     if (column.id === "percentile") return { text: row.samples < 2 || row.percentile == null ? "--" : row.percentile.toFixed(0) };
     if (column.id === "oi") return { text: integer(row.openInterest) };
     if (column.id === "volume") return { text: integer(row.volume) };
     return { text: curveTimestamp(row.asOf), color: row.stale ? colors.warning : colors.textMuted };
-  }, [changes, colors, curveTab, root]);
+  }, [basis, changes, colors, curveTab, root]);
   return <Box width={width} height={height} flexDirection="column">
     {tabStrip}
     <QueryBar width={width} filters={[{

package/src/plugins/builtin/fx-matrix/direction.ts

@@ -0,0 +1,81 @@
+import { colors } from "../../../theme/colors";
+import { blendHex, contrastRatio } from "../../../theme/color-utils";
+
+/** A cross that moved at least this many percent from its previous close earns the step. */
+export const TINT_THRESHOLDS = [0.05, 0.15, 0.3, 0.6, 1] as const;
+/**
+ * A step holds until the move falls this far below the threshold that earned
+ * it: a fifth of the threshold, and never less than 0.02% (about 2 pips on
+ * EUR/USD, the size a quote jitters between ticks).
+ */
+const RELEASE_BAND_SHARE = 0.2;
+const RELEASE_BAND_MIN = 0.02;
+/** How far each step leans toward the theme's up or down colour. */
+const TINT_STRENGTH = [0.14, 0.2, 0.27, 0.35, 0.44] as const;
+const MIN_TEXT_CONTRAST = 4.5;
+
+/**
+ * The cross's move since the previous close, in percent: the row currency
+ * against the column currency, so a positive move is the row currency gaining.
+ * Each rate and reference is USD per unit.
+ */
+export function crossMovePercent(
+  rowRate: number,
+  rowReference: number,
+  columnRate: number,
+  columnReference: number,
+): number | null {
+  const move = (rowRate / rowReference / (columnRate / columnReference) - 1) * 100;
+  return Number.isFinite(move) ? move : null;
+}
+
+/**
+ * The signed tint step (0 for none, 1 to 5 up, -1 to -5 down) of a move.
+ * `held` is the step the cell showed last: it stays while the move is still
+ * within the release band of its threshold, so a rate ticking around a
+ * boundary does not flicker between two shades. A move of the other sign
+ * starts afresh.
+ */
+export function tintLevel(movePercent: number, held = 0): number {
+  const sign = Math.sign(movePercent);
+  if (sign === 0) return 0;
+  const size = Math.abs(movePercent);
+  const earned = TINT_THRESHOLDS.filter((threshold) => size >= threshold).length;
+  const kept = sign === Math.sign(held) ? Math.abs(held) : 0;
+  const heldThreshold = kept > 0 ? TINT_THRESHOLDS[kept - 1]! : 0;
+  const holds = kept > earned && size >= heldThreshold - Math.max(heldThreshold * RELEASE_BAND_SHARE, RELEASE_BAND_MIN);
+  const level = holds ? kept : earned;
+  return level === 0 ? 0 : sign * level;
+}
+
+/** The step a cell shows now, remembering it under `key` for the next tick; null forgets it. */
+export function nextTintLevel(held: Map<string, number>, key: string, movePercent: number | null): number {
+  const level = movePercent === null ? 0 : tintLevel(movePercent, held.get(key) ?? 0);
+  if (level === 0) held.delete(key);
+  else held.set(key, level);
+  return level;
+}
+
+const tints = new Map<string, string | undefined>();
+
+/**
+ * A cell background for a tint step: the theme's own up or down colour
+ * blended into `background`. The strength comes down from the step's until
+ * `text` reads as well on it as on the plain background (4.5 to 1 where the
+ * theme allows), so the numbers stay the primary element in every theme.
+ */
+export function directionTint(level: number, surface: { background: string; text: string }): string | undefined {
+  if (level === 0) return undefined;
+  const hue = level > 0 ? colors.positive : colors.negative;
+  const key = `${level}|${hue}|${surface.background}|${surface.text}`;
+  if (tints.has(key)) return tints.get(key);
+  const floor = Math.min(MIN_TEXT_CONTRAST, contrastRatio(surface.text, surface.background) * 0.9);
+  let tint: string | undefined;
+  for (let strength = TINT_STRENGTH[Math.abs(level) - 1]!; strength > 0; strength = Math.round((strength - 0.02) * 100) / 100) {
+    const candidate = blendHex(surface.background, hue, strength);
+    if (contrastRatio(surface.text, candidate) >= floor) { tint = candidate; break; }
+  }
+  if (tints.size > 512) tints.clear();
+  tints.set(key, tint);
+  return tint;
+}