gloomberb 0.15.2 → 0.15.4

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

@@ -2,6 +2,8 @@ import type { Quote } from "../../../types/financials";
 import { compareSortValues, type SortDirection } from "../../../utils/sort-values";
 import type { BoardQuoteMap } from "../shared/use-quote-board";
 import { FUTURES_SECTOR_ORDER, type FuturesContract, type FuturesSector } from "./contracts";
+import type { FuturesReturnHorizon } from "./returns";
+import type { FrontReturnsMap } from "./use-front-returns";
 
 export type FuturesTableRow =
   | { type: "header"; sector: FuturesSector }
@@ -14,6 +16,9 @@ export type FuturesColumnId =
   | "price"
   | "change"
   | "changePercent"
+  | "return1w"
+  | "return1m"
+  | "returnYtd"
   | "volume"
   | "prevClose"
   | "time";
@@ -42,11 +47,24 @@ const CONTRACT_MONTH = /\b(Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)[ -](
  * rather than guessed.
  */
 export function futuresContractName(contract: FuturesContract, quote?: Quote | null): string {
-  if (quote?.symbol?.trim().toUpperCase() !== contract.symbol.toUpperCase()) return contract.name;
+  const month = quotedContractMonth(contract, quote);
+  if (!month) return contract.name;
+  return `${contract.name} ${MONTH_NAMES[month.month]} ${String(month.year).slice(-2)}`;
+}
+
+const MONTH_NAMES = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
+
+/** The delivery month the alias's quote names, month 0-11, or null when its name carries none. */
+export function quotedContractMonth(
+  contract: FuturesContract,
+  quote?: Quote | null,
+): { year: number; month: number } | null {
+  if (quote?.symbol?.trim().toUpperCase() !== contract.symbol.toUpperCase()) return null;
   const match = CONTRACT_MONTH.exec(quote.name?.trim() ?? "");
-  if (!match) return contract.name;
-  const month = match[1]!;
-  return `${contract.name} ${month[0]!.toUpperCase()}${month.slice(1).toLowerCase()} ${match[2]!.slice(-2)}`;
+  if (!match) return null;
+  const month = MONTH_NAMES.findIndex((name) => name.toLowerCase() === match[1]!.toLowerCase());
+  const year = match[2]!.length === 2 ? 2000 + Number(match[2]) : Number(match[2]);
+  return { year, month };
 }
 
 function matchesFuturesSearch(contract: FuturesContract, query: string, quote?: Quote | null): boolean {
@@ -60,10 +78,17 @@ function matchesFuturesSearch(contract: FuturesContract, query: string, quote?:
   );
 }
 
+export const FUTURES_RETURN_COLUMNS: Readonly<Partial<Record<FuturesColumnId, FuturesReturnHorizon>>> = {
+  return1w: "1W",
+  return1m: "1M",
+  returnYtd: "YTD",
+};
+
 function getSortValue(
   columnId: FuturesColumnId,
   contract: FuturesContract,
   quotes: BoardQuoteMap,
+  returns?: FrontReturnsMap,
 ): string | number | null {
   const quote = quotes.get(contract.symbol)?.quote;
   switch (columnId) {
@@ -79,6 +104,10 @@ function getSortValue(
       return quote?.change ?? null;
     case "changePercent":
       return quote?.changePercent ?? null;
+    case "return1w":
+    case "return1m":
+    case "returnYtd":
+      return returns?.get(contract.symbol)?.values[FUTURES_RETURN_COLUMNS[columnId]!] ?? null;
     case "volume":
       return quote?.volume ?? null;
     case "prevClose":
@@ -92,12 +121,13 @@ function sortContracts(
   contracts: FuturesContract[],
   sortPreference: FuturesSortPreference,
   quotes: BoardQuoteMap,
+  returns?: FrontReturnsMap,
 ): FuturesContract[] {
   const columnId = sortPreference.columnId;
   if (!columnId) return contracts;
   return [...contracts].sort((left, right) => compareSortValues(
-    getSortValue(columnId, left, quotes),
-    getSortValue(columnId, right, quotes),
+    getSortValue(columnId, left, quotes, returns),
+    getSortValue(columnId, right, quotes, returns),
     sortPreference.direction,
   ));
 }
@@ -107,6 +137,8 @@ export interface BuildFuturesRowsOptions {
   query?: string;
   /** Sectors whose contracts are hidden under their header. */
   collapsed?: ReadonlySet<FuturesSector>;
+  /** Front-contract returns, for sorting on a returns column. */
+  returns?: FrontReturnsMap;
 }
 
 const NO_COLLAPSED_SECTORS: ReadonlySet<FuturesSector> = new Set();
@@ -134,7 +166,7 @@ export function buildFuturesRows(
   const query = options?.query ?? "";
   const collapsed = effectiveCollapsedSectors(options?.collapsed, query);
   for (const sector of FUTURES_SECTOR_ORDER) {
-    const contracts = sortContracts(contractsBySector.get(sector) ?? [], sortPreference, quotes)
+    const contracts = sortContracts(contractsBySector.get(sector) ?? [], sortPreference, quotes, options?.returns)
       .filter((contract) => matchesFuturesSearch(contract, query, quotes.get(contract.symbol)?.quote));
     if (contracts.length === 0) continue;
     rows.push({ type: "header", sector });
@@ -143,13 +175,3 @@ export function buildFuturesRows(
   }
   return rows;
 }
-
-export function nextFuturesSort(
-  current: FuturesSortPreference,
-  columnId: string,
-): FuturesSortPreference {
-  const typed = columnId as FuturesColumnId;
-  if (current.columnId !== typed) return { columnId: typed, direction: "asc" };
-  if (current.direction === "asc") return { columnId: typed, direction: "desc" };
-  return DEFAULT_FUTURES_SORT;
-}

package/src/plugins/builtin/futures/returns.ts

@@ -0,0 +1,132 @@
+import type { PricePoint, Quote } from "../../../types/financials";
+import { calendarMonthsBefore } from "../../../utils/calendar-date";
+import type { FuturesContract } from "./contracts";
+import { quotedContractMonth } from "./model";
+
+export type FuturesReturnHorizon = "1W" | "1M" | "YTD";
+export type FuturesReturnValues = Readonly<Record<FuturesReturnHorizon, number | null>>;
+
+export const NO_FUTURES_RETURNS: FuturesReturnValues = { "1W": null, "1M": null, YTD: null };
+
+const MONTH_CODES = "FGHJKMNQUVXZ";
+const DAY_MS = 86_400_000;
+
+/** Yahoo symbol of one listed contract: LEZ26.CME. */
+export function listedContractSymbol(contract: FuturesContract, year: number, month: number): string {
+  return `${contract.code}${MONTH_CODES[month]}${String(year % 100).padStart(2, "0")}.${contract.venue}`;
+}
+
+/**
+ * A root listing every month never quotes the current month's contract (crude,
+ * gas and products expire the month before delivery) and at most three months
+ * out (Brent trades until two months before delivery).
+ */
+const MONTHLY_FRONT_OFFSETS = [1, 2, 3];
+
+/**
+ * The listed contracts the continuous alias may be quoting. A quote whose name
+ * carries a month is that contract, the one the board already labels the row
+ * with. A name without one (Dutch TTF gas, Brent on some routes) leaves each
+ * month that could be front on a root listing every month, and the price
+ * picks among them.
+ */
+export function frontContractCandidates(contract: FuturesContract, quote: Quote | null | undefined): string[] {
+  const named = quotedContractMonth(contract, quote);
+  if (named) return [listedContractSymbol(contract, named.year, named.month)];
+  if (!contract.everyMonth || !quote || !Number.isFinite(quote.lastUpdated)) return [];
+  const at = new Date(quote.lastUpdated);
+  return MONTHLY_FRONT_OFFSETS.map((offset) => {
+    const month = at.getUTCMonth() + offset;
+    return listedContractSymbol(contract, at.getUTCFullYear() + Math.floor(month / 12), month % 12);
+  });
+}
+
+interface DailyClose {
+  day: string;
+  close: number;
+}
+
+function utcDay(value: Date | string | number): string | null {
+  const date = value instanceof Date ? value : new Date(value);
+  return Number.isFinite(date.getTime()) ? date.toISOString().slice(0, 10) : null;
+}
+
+function shiftDay(day: string, days: number): string {
+  return new Date(Date.parse(`${day}T00:00:00Z`) + days * DAY_MS).toISOString().slice(0, 10);
+}
+
+/** Dated closes, one per day, oldest first. History that crossed a JSON bridge carries string dates. */
+function dailyCloses(history: readonly PricePoint[]): DailyClose[] {
+  const byDay = new Map<string, number>();
+  for (const point of history) {
+    const day = utcDay(point.date as Date | string | number);
+    if (day && Number.isFinite(point.close)) byDay.set(day, point.close);
+  }
+  return [...byDay].sort(([left], [right]) => left.localeCompare(right)).map(([day, close]) => ({ day, close }));
+}
+
+/**
+ * Among contracts that could be front, the one whose latest close sits nearest
+ * the alias's price. Neighbouring months can be a fraction of a percent apart,
+ * so this only decides between candidates; it never vets a named contract.
+ */
+export function pickFrontContract(
+  candidates: ReadonlyArray<{ symbol: string; history: readonly PricePoint[] }>,
+  price: number | null | undefined,
+): string | null {
+  if (candidates.length === 1) return candidates[0]!.symbol;
+  if (price == null || !Number.isFinite(price) || price === 0) return null;
+  let best: { symbol: string; distance: number } | null = null;
+  for (const candidate of candidates) {
+    const latest = dailyCloses(candidate.history).at(-1);
+    if (!latest) continue;
+    const distance = Math.abs(latest.close / price - 1);
+    if (!best || distance < best.distance) best = { symbol: candidate.symbol, distance };
+  }
+  return best?.symbol ?? null;
+}
+
+/**
+ * A baseline further than this before its target date is a hole in the
+ * contract's trading (or a contract listed after the target), not its close.
+ */
+const MAX_BASELINE_GAP_DAYS = 10;
+
+function closeOnOrBefore(closes: readonly DailyClose[], target: string): number | null {
+  const earliest = shiftDay(target, -MAX_BASELINE_GAP_DAYS);
+  for (let index = closes.length - 1; index >= 0; index -= 1) {
+    const bar = closes[index]!;
+    if (bar.day > target) continue;
+    return bar.day >= earliest && bar.close > 0 ? bar.close : null;
+  }
+  return null;
+}
+
+/**
+ * One contract's returns: the latest price against that same contract's close
+ * a week, a calendar month, and a year-end earlier. The continuous alias's own
+ * series jumps at every roll (LE=F fell 6.3% on a July roll day), so its
+ * history is never the baseline. `price` is the live quote, dated `asOf`;
+ * without one the contract's last close stands in.
+ */
+export function frontContractReturns(
+  history: readonly PricePoint[],
+  price: number | null | undefined,
+  asOf: number | null | undefined,
+): FuturesReturnValues {
+  const closes = dailyCloses(history);
+  const live = price != null && Number.isFinite(price) && asOf != null && Number.isFinite(asOf);
+  const latest = live ? price : closes.at(-1)?.close;
+  const latestDay = live ? utcDay(asOf) : closes.at(-1)?.day;
+  if (latest == null || !latestDay) return NO_FUTURES_RETURNS;
+  const change = (target: string) => {
+    const base = closeOnOrBefore(closes, target);
+    return base == null ? null : (latest / base - 1) * 100;
+  };
+  const monthBack = calendarMonthsBefore(new Date(`${latestDay}T00:00:00Z`), 1).toISOString().slice(0, 10);
+  return {
+    "1W": change(shiftDay(latestDay, -7)),
+    "1M": change(monthBack),
+    YTD: change(`${Number(latestDay.slice(0, 4)) - 1}-12-31`),
+  };
+}

package/src/plugins/builtin/futures/table.tsx

@@ -1,13 +1,12 @@
 import type { DataTableCell, DataTableColumn } from "../../../components";
-import { marketStateColor, marketStateLabel } from "../../../market-data/market/status";
 import { colors, priceColor } from "../../../theme/colors";
 import type { Quote } from "../../../types/financials";
 import { TextAttributes } from "../../../ui";
 import { formatCompact, formatNumber, formatPercentRaw } from "../../../utils/format";
-import { marketStatusDot, type BoardQuoteMap } from "../shared/use-quote-board";
-import { formatQuoteTime } from "../world-indices/table";
+import { isBoardRowLoading, renderQuoteBoardCell, type BoardQuoteMap } from "../shared/use-quote-board";
 import { tickDecimals, type FuturesContract } from "./contracts";
-import { futuresContractName, type FuturesColumnId, type FuturesTableRow } from "./model";
+import { FUTURES_RETURN_COLUMNS, futuresContractName, type FuturesColumnId, type FuturesTableRow } from "./model";
+import type { FrontReturnsMap } from "./use-front-returns";
 
 export type FuturesColumn = DataTableColumn & { id: FuturesColumnId };
 
@@ -24,6 +23,9 @@ export const FUTURES_COLUMN_DEFS: readonly FuturesColumnDef[] = [
   { id: "price", label: "Last", description: "Last traded price." },
   { id: "change", label: "Change", description: "Change on the session." },
   { id: "changePercent", label: "Change %", description: "Percent change on the session." },
+  { id: "return1w", label: "1W", description: "Front contract's return over one week." },
+  { id: "return1m", label: "1M", description: "Front contract's return over one month." },
+  { id: "returnYtd", label: "YTD", description: "Front contract's return since the end of last year." },
   { id: "volume", label: "Volume", description: "Contracts traded on the session." },
   { id: "prevClose", label: "Prev close", description: "Previous session close." },
   { id: "time", label: "Time", description: "UTC time of the last quote." },
@@ -36,9 +38,12 @@ const DEFAULT_FUTURES_COLUMN_IDS = FUTURES_COLUMN_DEFS.map((column) => column.id
  * readable contract name; a narrow pane drops them instead of clipping.
  */
 const COLUMN_MIN_PANE_WIDTH: Partial<Record<FuturesColumnId, number>> = {
-  volume: 92,
-  prevClose: 104,
-  time: 114,
+  return1w: 84,
+  return1m: 92,
+  returnYtd: 106,
+  volume: 116,
+  prevClose: 128,
+  time: 140,
 };
 const SESSION_TEXT_MIN_WIDTH = 100;
 
@@ -48,6 +53,9 @@ const COLUMN_WIDTHS: Record<Exclude<FuturesColumnId, "name">, number> = {
   price: 12,
   change: 10,
   changePercent: 9,
+  return1w: 8,
+  return1m: 8,
+  returnYtd: 8,
   volume: 9,
   prevClose: 12,
   // An 8-char TIME UTC header over a 5-char time: the shared table's floating-pane
@@ -99,6 +107,9 @@ const FUTURES_HEADER_LABELS: Record<FuturesColumnId, string> = {
   price: "LAST",
   change: "CHG",
   changePercent: "CHG%",
+  return1w: "1W",
+  return1m: "1M",
+  returnYtd: "YTD",
   volume: "VOL",
   prevClose: "PREV",
   time: "TIME UTC",
@@ -122,7 +133,7 @@ export function resolveFuturesColumnIds(visibleIds?: readonly string[]): Futures
  * magnitude fallback only covers contracts without a declared tick, and reads
  * the previous close so a live price crossing 10 keeps its decimals.
  *
- * ponytail: rates render as decimals, not the 32nds tick notation traders
+ * Rates render as decimals, not the 32nds tick notation traders
  * quote (108'17). Add a tick formatter if rates users ask for it.
  */
 function priceDecimals(price: number, contract: FuturesContract): number {
@@ -134,6 +145,31 @@ function priceDecimals(price: number, contract: FuturesContract): number {
   return 6;
 }
 
+const currencySymbols = new Map<string, string>();
+
+/**
+ * The board prints dollar prices bare. Anything else carries its unit on the
+ * price and on the change, so Dutch TTF gas at 72.071 euros is not read as
+ * dollars beside Henry Hub: US cents (`USX`) as a `c` suffix, other
+ * currencies as their symbol.
+ */
+function currencyMarks(currency: string | undefined): { prefix: string; suffix: string } {
+  const code = currency?.trim().toUpperCase() ?? "";
+  if (!code || code === "USD") return { prefix: "", suffix: "" };
+  if (code === "USX") return { prefix: "", suffix: "c" };
+  let symbol = currencySymbols.get(code);
+  if (symbol === undefined) {
+    try {
+      symbol = new Intl.NumberFormat("en-US", { style: "currency", currency: code, currencyDisplay: "narrowSymbol" })
+        .formatToParts(0).find((part) => part.type === "currency")?.value ?? code;
+    } catch {
+      symbol = code;
+    }
+    currencySymbols.set(code, symbol);
+  }
+  return symbol.length === 1 ? { prefix: symbol, suffix: "" } : { prefix: "", suffix: ` ${symbol}` };
+}
+
 /**
  * Trailing zeros are kept: a EUR contract at 1.1600 has to line up with the
  * 1.3544 pound contract beside it, and with its own "+0.0002" change.
@@ -141,7 +177,8 @@ function priceDecimals(price: number, contract: FuturesContract): number {
 function formatContractPrice(quote: Quote, contract: FuturesContract): string {
   if (!Number.isFinite(quote.price)) return "—";
   const text = formatNumber(quote.price, priceDecimals(quote.previousClose ?? quote.price, contract));
-  return quote.currency === "USX" ? `${text}c` : text;
+  const { prefix, suffix } = currencyMarks(quote.currency);
+  return `${prefix}${text}${suffix}`;
 }
 
 /**
@@ -155,88 +192,60 @@ function formatContractChange(quote: Quote, contract: FuturesContract): string {
     ? priceDecimals(quote.previousClose ?? quote.price, contract)
     : 2;
   const text = formatNumber(Math.abs(quote.change), decimals);
-  return `${quote.change >= 0 ? "+" : "-"}${text}`;
+  const { prefix, suffix } = currencyMarks(quote.currency);
+  return `${quote.change >= 0 ? "+" : "-"}${prefix}${text}${suffix}`;
 }
 
 export function renderFuturesCell(
   row: FuturesTableRow,
   column: FuturesColumn,
-  rowState: { selected: boolean },
   quotes: BoardQuoteMap,
-  options?: { sessionText?: boolean },
+  options?: { sessionText?: boolean; returns?: FrontReturnsMap },
 ): DataTableCell {
   if (row.type === "header") return { text: "" };
 
   const { contract } = row;
   const state = quotes.get(contract.symbol);
   const quote = state?.quote;
-  const selectedColor = rowState.selected ? colors.selectedText : undefined;
-  const dimmed = rowState.selected ? colors.selectedText : colors.textDim;
-  // One row must not mix a loading marker with a no-data marker.
-  const loadingCell = !quote && (state?.loading ?? true);
 
   switch (column.id) {
-    case "status": {
-      if (loadingCell) return { text: "", color: dimmed };
-      if (options?.sessionText) {
-        const marketState = quote?.marketState;
-        return {
-          text: marketState ? marketStateLabel(marketState) : "—",
-          color: rowState.selected
-            ? colors.selectedText
-            : marketState ? marketStateColor(marketState) : colors.textDim,
-        };
-      }
-      const dot = marketStatusDot(quote?.marketState);
-      return { text: dot.char, color: rowState.selected ? colors.selectedText : dot.color };
-    }
     case "code":
       return {
         text: contract.code,
-        color: selectedColor ?? colors.textBright,
+        color: colors.textBright,
         attributes: TextAttributes.BOLD,
       };
     case "name":
-      return { text: futuresContractName(contract, quote), color: selectedColor };
-    case "price":
-      if (loadingCell) return { text: "…", color: dimmed };
-      if (!quote) return { text: "—", color: dimmed };
-      // A retained quote still beats a dash; dim it so stale is visible.
-      return {
-        text: formatContractPrice(quote, contract),
-        color: state?.stale ? dimmed : selectedColor,
-      };
-    case "change":
-      if (loadingCell) return { text: "…", color: dimmed };
-      if (!quote || !Number.isFinite(quote.change)) return { text: "—", color: dimmed };
-      return {
-        text: formatContractChange(quote, contract),
-        color: selectedColor ?? priceColor(quote.change),
-      };
-    case "changePercent":
-      if (loadingCell) return { text: "…", color: dimmed };
-      if (!quote || !Number.isFinite(quote.changePercent)) return { text: "—", color: dimmed };
-      return {
-        text: formatPercentRaw(quote.changePercent),
-        color: selectedColor ?? priceColor(quote.changePercent),
-      };
+      return { text: futuresContractName(contract, quote) };
     case "volume":
-      if (loadingCell) return { text: "…", color: dimmed };
+      if (isBoardRowLoading(state)) return { text: "…", color: colors.textDim };
       if (!quote || quote.volume == null || !Number.isFinite(quote.volume)) {
-        return { text: "—", color: dimmed };
+        return { text: "—", color: colors.textDim };
       }
-      return { text: formatCompact(quote.volume, { fixedDecimals: true }), color: selectedColor ?? colors.textDim };
+      return { text: formatCompact(quote.volume, { fixedDecimals: true }), color: colors.textDim };
+    case "return1w":
+    case "return1m":
+    case "returnYtd": {
+      const returns = options?.returns?.get(contract.symbol);
+      if (isBoardRowLoading(state) || returns?.loading) return { text: "…", color: colors.textDim };
+      const value = returns?.values[FUTURES_RETURN_COLUMNS[column.id]!];
+      if (value == null || !Number.isFinite(value)) return { text: "—", color: colors.textDim };
+      return { text: formatPercentRaw(value), color: priceColor(value) };
+    }
     case "prevClose":
-      if (loadingCell) return { text: "…", color: dimmed };
+      if (isBoardRowLoading(state)) return { text: "…", color: colors.textDim };
       if (!quote || quote.previousClose == null || !Number.isFinite(quote.previousClose)) {
-        return { text: "—", color: dimmed };
+        return { text: "—", color: colors.textDim };
       }
       return {
         text: formatContractPrice({ ...quote, price: quote.previousClose }, contract),
-        color: selectedColor ?? colors.textDim,
+        color: colors.textDim,
       };
-    case "time":
-      if (loadingCell) return { text: "…", color: dimmed };
-      return { text: formatQuoteTime(quote?.lastUpdated), color: dimmed };
+    default:
+      return renderQuoteBoardCell(column.id, state, {
+        sessionText: options?.sessionText,
+        formatPrice: (quoted) => formatContractPrice(quoted, contract),
+        formatChange: (quoted) => formatContractChange(quoted, contract),
+      });
   }
 }

package/src/plugins/builtin/futures/use-front-returns.ts

@@ -0,0 +1,119 @@
+import { useEffect, useMemo, useState } from "react";
+import type { DataProvider } from "../../../types/data-provider";
+import type { PricePoint } from "../../../types/financials";
+import type { BoardQuoteMap } from "../shared/use-quote-board";
+import type { FuturesContract } from "./contracts";
+import {
+  frontContractCandidates,
+  frontContractReturns,
+  NO_FUTURES_RETURNS,
+  pickFrontContract,
+  type FuturesReturnValues,
+} from "./returns";
+
+export interface FrontReturnsState {
+  /** A candidate contract's history is still loading. */
+  loading: boolean;
+  values: FuturesReturnValues;
+}
+
+export type FrontReturnsMap = ReadonlyMap<string, FrontReturnsState>;
+
+/**
+ * The baselines are earlier days' closes, so a contract's history is reused
+ * for half an hour; the live quote moves the returns in between.
+ */
+const HISTORY_TTL_MS = 30 * 60_000;
+/** Forty-odd contracts open at once; a few requests at a time keep the board's quotes first. */
+const HISTORY_CONCURRENCY = 4;
+
+interface CachedHistory {
+  at: number;
+  /** Null when the contract has no history to read (delisted, unknown). */
+  points: readonly PricePoint[] | null;
+}
+
+const historyCache = new Map<string, CachedHistory>();
+const inFlight = new Map<string, Promise<void>>();
+
+function freshHistory(symbol: string, now: number): CachedHistory | undefined {
+  const cached = historyCache.get(symbol);
+  return cached && now - cached.at < HISTORY_TTL_MS ? cached : undefined;
+}
+
+function loadHistory(provider: DataProvider, symbol: string): Promise<void> {
+  const pending = inFlight.get(symbol);
+  if (pending) return pending;
+  const request = provider.getPriceHistory(symbol, "", "1Y")
+    .then((points) => { historyCache.set(symbol, { at: Date.now(), points: points.length > 0 ? points : null }); })
+    .catch(() => { historyCache.set(symbol, { at: Date.now(), points: null }); })
+    .finally(() => { inFlight.delete(symbol); });
+  inFlight.set(symbol, request);
+  return request;
+}
+
+/**
+ * 1W, 1M and YTD returns for each board row, measured on the contract its
+ * quote prices rather than on the continuous alias. Histories load only while
+ * `enabled` (a returns column is on screen and the pane can be seen).
+ */
+export function useFrontContractReturns(
+  contracts: readonly FuturesContract[],
+  quotes: BoardQuoteMap,
+  provider: DataProvider | null | undefined,
+  enabled: boolean,
+): FrontReturnsMap {
+  // Candidates change on a roll, not on a tick: the key keeps the loader still.
+  const candidateKey = contracts
+    .map((contract) => `${contract.symbol}\u001f${frontContractCandidates(contract, quotes.get(contract.symbol)?.quote).join(",")}`)
+    .join("\u001e");
+  const candidates = useMemo(() => new Map(candidateKey.split("\u001e").map((entry) => {
+    const [symbol = "", list = ""] = entry.split("\u001f");
+    return [symbol, list ? list.split(",") : []] as const;
+  })), [candidateKey]);
+  const [version, setVersion] = useState(0);
+  // A board left open overnight reloads once the day turns.
+  const today = new Date().toISOString().slice(0, 10);
+
+  useEffect(() => {
+    if (!enabled || !provider) return;
+    const now = Date.now();
+    const queue = [...new Set([...candidates.values()].flat())].filter((symbol) => !freshHistory(symbol, now));
+    if (queue.length === 0) return;
+    let cancelled = false;
+    const worker = async () => {
+      for (let symbol = queue.shift(); symbol; symbol = queue.shift()) {
+        await loadHistory(provider, symbol);
+        if (!cancelled) setVersion((current) => current + 1);
+      }
+    };
+    void Promise.all(Array.from({ length: Math.min(HISTORY_CONCURRENCY, queue.length) }, worker));
+    return () => {
+      cancelled = true;
+      queue.length = 0;
+    };
+  }, [candidates, enabled, provider, today]);
+
+  return useMemo(() => {
+    const result = new Map<string, FrontReturnsState>();
+    if (!enabled) return result;
+    for (const contract of contracts) {
+      const quote = quotes.get(contract.symbol)?.quote;
+      const symbols = candidates.get(contract.symbol) ?? [];
+      const loaded = symbols.map((symbol) => ({ symbol, cached: historyCache.get(symbol) }));
+      if (loaded.some((entry) => !entry.cached)) {
+        result.set(contract.symbol, { loading: true, values: NO_FUTURES_RETURNS });
+        continue;
+      }
+      const available = loaded.flatMap((entry) => entry.cached?.points ? [{ symbol: entry.symbol, history: entry.cached.points }] : []);
+      const front = pickFrontContract(available, quote?.price);
+      const history = available.find((entry) => entry.symbol === front)?.history;
+      result.set(contract.symbol, {
+        loading: false,
+        values: history ? frontContractReturns(history, quote?.price, quote?.lastUpdated) : NO_FUTURES_RETURNS,
+      });
+    }
+    return result;
+    // `version` re-reads the history cache as loads land.
+  }, [candidates, contracts, enabled, quotes, version]);
+}