gloomberb 0.18.3 → 0.18.4

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

@@ -5,7 +5,7 @@ import { curveStrip, curveSurfaceMinRows } from "../../../components/chart/curve
 import { isAccessDenied } from "../../../api-client/errors";
 import type { FuturesContract } from "../../../api-client/futures-curve";
 import { futuresTickText } from "../../../market-data/futures-contract";
-import { useAsyncResource, usePaneSettingValue, usePluginPaneState, useShortcut } from "../../../public/react";
+import { useAssetData, useAsyncResource, usePaneSettingValue, usePluginPaneState, useShortcut } from "../../../public/react";
 import { usePaneInstance, usePaneTitle } from "../../../state/app/context";
 import { useThemeColors } from "../../../theme/theme-context";
 import type { PaneProps } from "../../../types/plugin";
@@ -16,8 +16,8 @@ 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 { basisSpotSymbol, curveAsOfDate, curveAxisPrice, curveBasisPercent, curveBasisRows, curveChangeText, curveContractChanges, curveContractCode, curvePrice, curveRank, curveSpot, curveSpotLabel, curveSpotSource, curveSpreadLabel, curveTimestamp, curveTitle, curveUnitLabel, DEFAULT_CURVE_HORIZON, futuresCurveSeries, newestQuote, normalizeCurveRoot, paneCurveRoot, sortCurveContracts, thinContractCount, thinContractsNotice, unsupportedCurveRootMessage, type CurveContractChanges, type CurveSpot } from "./model";
+import { getCachedFuturesCurve, loadCurveSpotBars, loadFuturesCurve, loadFuturesCurveAsOf } from "./client";
+import { BASIS_CONVENTION, basisSpotSymbol, blankBasisNote, curveAsOfDate, curveAxisPrice, curveBasisPercent, curveBasisRows, curveChangeText, curveContractChanges, curveContractCode, curvePrice, curveRank, curveSpot, curveSpotLabel, curveSpotSource, curveSpreadBasis, curveSpreadLabel, curveTimestamp, curveTitle, curveUnitLabel, DEFAULT_CURVE_HORIZON, futuresCurveSeries, newestQuote, noTradeChangeNote, normalizeCurveRoot, paneCurveRoot, shortDatedBasis, shortDatedBasisNote, sortCurveContracts, thinSpreadNotice, unsupportedCurveRootMessage, type CurveContractChanges, type CurveSpot } from "./model";
 
 const TABS = [{ value: "curve", label: "Curve" }, { value: "contracts", label: "Contracts" }];
 // One column order for every root. SETTLE is the exchange settlement for the
@@ -61,6 +61,8 @@ const BASIS_CURVE_COLUMNS: DataTableColumn[] = [
   ...CURVE_COLUMNS.slice(4),
 ];
 const BASIS_DROP_ORDER = ["percentile", "volume", "change1m", "oi", "settle", "change1w", "vsSpot", "expiry"];
+// Inside a week of expiry Vs Spot is the figure to read, so a curve with such a contract keeps it.
+const SHORT_DATED_DROP_ORDER = BASIS_DROP_ORDER.filter((id) => id !== "vsSpot");
 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;
@@ -71,8 +73,12 @@ const contractKey = (row: FuturesContract) => row.symbol;
 const contractDate = (row: FuturesContract) => new Date(row.expiration);
 const sentenceCase = (text: string) => text.charAt(0).toUpperCase() + text.slice(1);
 
-/** The footer's spot, naming the quote's own listing and feed; a narrow footer gives those up before the price and its time. */
+/**
+ * The footer's latest spot, naming what the quote is and its feed; a narrow footer gives those up before the price
+ * and its time. Each basis reads the spot in its own trade's minute, so a quote gone stale only says so.
+ */
 function spotSegment(spot: CurveSpot, root: string, clock: number): PaneFooterSegment {
+  if (spot.status !== "ok") return { id: "spot", parts: [{ text: spot.reason ?? `no ${spot.symbol} quote`, tone: "warning" }] };
   const label = curveSpotLabel(spot, root, clock);
   const source = curveSpotSource(spot);
   return { id: "spot", parts: [{ text: source ? `${label} (${source})` : label, tone: "muted" }], ...source ? { variants: [[{ text: label, tone: "muted" }]] } : {} };
@@ -128,6 +134,12 @@ function FuturesCurveView({ width, height, focused, root, ownsTitle }: PaneProps
     return () => clearInterval(timer);
   }, [basisActive]);
   const spotState = spotSymbol ? spotQuotes.get(spotSymbol) : undefined;
+  // Each trade is read against the spot's one-minute bar of its own minute, fetched again whenever the curve is.
+  const assetData = useAssetData();
+  const barsLoader = useMemo(() => basisActive && spotSymbol && assetData
+    ? (force: boolean) => loadCurveSpotBars(spotSymbol, assetData, force) : null,
+  [assetData, basisActive, spotSymbol, resource.updatedAt]);
+  const spotBars = useAsyncResource(barsLoader, { keepPreviousData: true });
   // 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]);
@@ -138,8 +150,9 @@ function FuturesCurveView({ width, height, focused, root, ownsTitle }: PaneProps
     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 basis = useMemo(() => curveBasisRows(basisActive ? data?.contracts ?? [] : [], spot), [basisActive, data, spot]);
-  const thinCount = useMemo(() => thinContractCount(basis.values()), [basis]);
+  // Until the bars first answer there is nothing to say: no reason, only blank cells.
+  const bars = basisActive ? spotBars.data : null;
+  const basis = useMemo(() => curveBasisRows(basisActive ? data?.contracts ?? [] : [], bars), [basisActive, bars, data]);
   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(() => {
@@ -151,13 +164,20 @@ function FuturesCurveView({ width, height, focused, root, ownsTitle }: PaneProps
   useChartTableSelection({ rows: curveRows, getId: contractKey, getDate: contractDate, selectedId, onSelect: setSelected,
     focused, enabled: curveTab });
   // The highlighted row carries the selected contract's price and rank.
-  const slopeDate = data?.slope.asOf && curveTimestamp(data.slope.asOf) !== curveTimestamp(newest) ? curveTimestamp(data.slope.asOf) : null;
+  // The spread says which prices it subtracts (settlements or two last trades made together); a server that does not say is dated.
+  const spreadBasis = data ? curveSpreadBasis(data.slope, newest) : null;
+  const slopeDate = !spreadBasis && data?.slope.asOf && curveTimestamp(data.slope.asOf) !== curveTimestamp(newest) ? curveTimestamp(data.slope.asOf) : null;
+  // A thin spread makes no curve call: it and the roll yield read from it take the warning tone and give no rank.
+  const thin = data?.slope.state === "thin";
+  const spreadRank = data && !thin ? curveRank(data.slope.percentile, data.slope.samples) : null;
+  const thinSpread = data ? thinSpreadNotice(data) : null;
   const statItems: StatItem[] = data ? [
     { id: "roll", label: "Ann. roll yield", value: signedPercent(data.slope.annualizedRollYield),
-      detail: curveRank(data.slope.rollPercentile, data.slope.samples) },
+      ...thin ? { tone: "warning" as const } : { detail: curveRank(data.slope.rollPercentile, data.slope.samples) } },
     // Named by the contracts it subtracts: the front is the first month the market trades, not always the first row.
     { id: "spread", label: curveSpreadLabel(data.slope), value: data.slope.value == null ? "--" : curvePrice(data.slope.value, root),
-      detail: [data.slope.state, curveRank(data.slope.percentile, data.slope.samples), slopeDate].filter(Boolean).join(" · ") },
+      ...thin ? { tone: "warning" as const } : {},
+      detail: [data.slope.state, spreadBasis, spreadRank, slopeDate].filter(Boolean).join(" · ") },
     ...data.spec ? [{ id: "contract", label: "Contract", value: data.spec.size, detail: `tick ${futuresTickText(data.spec)}` }] : [],
   ] : [];
   const { strip: tabStrip, rows: tabRows } = usePaneTabs({ tabs: TABS, activeValue: tab, onSelect: setTab, focused, dense: true, queryBarWidth: width });
@@ -168,6 +188,7 @@ function FuturesCurveView({ width, height, focused, root, ownsTitle }: PaneProps
   const settleLabel = data?.settlementDate ? `SETTLE ${data.settlementDate.slice(5)}` : "SETTLE";
   // Cash-settled roots (ES, CL's Brent, VX) have no first notice day to show.
   const noNotice = !data?.contracts.some((row) => row.firstNotice);
+  const shortDated = curveTab && curveRows.some((row) => shortDatedBasis(basis.get(row.symbol)));
   const columns = useMemo(() => {
     // Labelled before fitting: a dated header is wider than the column's numbers.
     const shown = (list: DataTableColumn[]) => list.filter((entry) => !(settlesOnly && entry.id === "price") && !(noNotice && entry.id === "notice"))
@@ -175,9 +196,9 @@ function FuturesCurveView({ width, height, focused, root, ownsTitle }: PaneProps
     // A curve that only settles keeps its settlement: it is the price.
     const order = (list: string[]) => settlesOnly ? list.filter((id) => id !== "settle") : list;
     return !curveTab ? fitChartTableColumns(shown(COLUMNS), width, order(CONTRACTS_DROP_ORDER))
-      : basisActive ? fitChartTableColumns(shown(BASIS_CURVE_COLUMNS), width, order(BASIS_DROP_ORDER))
+      : basisActive ? fitChartTableColumns(shown(BASIS_CURVE_COLUMNS), width, order(shortDated ? SHORT_DATED_DROP_ORDER : BASIS_DROP_ORDER))
         : fitChartTableColumns(shown(CURVE_COLUMNS), width, order(CURVE_DROP_ORDER));
-  }, [basisActive, curveTab, noNotice, settleLabel, settlesOnly, width]);
+  }, [basisActive, curveTab, noNotice, settleLabel, settlesOnly, shortDated, width]);
   const formatValue = useCallback((value: number) => curvePrice(value, root), [root]);
   const formatChange = useCallback((value: number) => curveChangeText(value, root), [root]);
   const unit = data ? curveUnitLabel(data) : null;
@@ -212,11 +233,16 @@ function FuturesCurveView({ width, height, focused, root, ownsTitle }: PaneProps
   };
   // A past date with no archived curve says why in the body, not behind the warning.
   const emptyPast = !!requestedDate && !!data && !data.contracts.length;
-  // Thin contracts join the data warnings: the info row has no room for them beside the quote times.
+  // The basis notes the report prints under its table: the convention, why a cell is blank, and which rates spot noise swamps.
+  const basisNotes = basisActive && bars ? [BASIS_CONVENTION, blankBasisNote(tableRows, basis), shortDatedBasisNote(tableRows, basis)]
+    .filter((note): note is string => !!note) : [];
   // A long in these can be assigned delivery: the hedge a trader rolls before first notice.
   const delivering = data?.contracts.filter((row) => row.inDelivery).map((row) => curveContractCode(row.symbol)) ?? [];
+  // A blank Change on Contracts says why, as a blank basis does: no trade since the settlement it is measured from.
+  const untraded = data && !requestedDate && columns.some((entry) => entry.id === "change")
+    ? noTradeChangeNote(tableRows, data, { count: true }) : null;
   usePaneNoticeFooter({ registrationId: "futures-curve:notices", focused,
-    notices: emptyPast ? [] : [...data?.gaps ?? [], ...thinCount ? [thinContractsNotice(thinCount)] : [],
+    notices: emptyPast ? [] : [...data?.gaps ?? [], ...thinSpread ? [thinSpread] : [], ...basisNotes, ...untraded ? [untraded] : [],
       ...delivering.length ? [`${delivering.join(", ")} ${delivering.length === 1 ? "is" : "are"} past first notice.`] : []] });
   const delay = Math.max(0, ...(data?.contracts.map((row) => row.delayMinutes ?? 0) ?? []));
   usePaneStatusFooter({ registrationId: "futures-curve", loading: resource.loading, error: resource.error,
@@ -227,8 +253,7 @@ function FuturesCurveView({ width, height, focused, root, ownsTitle }: PaneProps
     info: data ? [
       ...splitDelayedStatus({ id: "source", parts: [{ text: `${requestedDate ? "daily archive" : data.source === "cboe" ? "settlement" : delay > 0 ? `${delay}m delayed` : "dated quotes"} · ${unit ?? "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 ? [spot.status === "ok" ? spotSegment(spot, root, clock)
-        : { id: "spot", parts: [{ text: `Basis blank: ${spot.reason}`, tone: "warning" as const }] }] : []),
+      ...(spot ? [spotSegment(spot, root, clock)] : []),
     ] : [],
   });
   const tableChromeRows = chartTableChromeRows(columns, width);
@@ -250,7 +275,7 @@ function FuturesCurveView({ width, height, focused, root, ownsTitle }: PaneProps
     if (column.id === "price") {
       const lastTrade = requestedDate && row.settlement != null ? null : row.price;
       // Beside its settlement the last trade is the secondary price; without one it is the row's price.
-      return { text: curvePrice(lastTrade, root), color: curveTab && (row.stale || basis.get(row.symbol)?.thin) ? colors.warning
+      return { text: curvePrice(lastTrade, root), color: curveTab && row.stale ? colors.warning
         : row.settlement != null ? colors.textMuted : undefined };
     }
     if (column.id === "change") {
@@ -263,7 +288,11 @@ function FuturesCurveView({ width, height, focused, root, ownsTitle }: PaneProps
     }
     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 };
+      const text = column.id === "vsSpot" ? curveBasisPercent(cell?.vsSpotPct ?? null, 2) : curveBasisPercent(cell?.annualisedBasisPct ?? null, 1);
+      // The figure to read is in the text colour, the other greyed: the annualised rate, until a week before
+      // expiry, where spot noise swings it by whole points and Vs Spot leads.
+      const lead = column.id === "vsSpot" ? shortDatedBasis(cell) : !shortDatedBasis(cell);
+      return { text, color: lead && text !== "--" ? undefined : 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) };

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

@@ -1,9 +1,11 @@
+import { logFailure } from "../../../utils/log-failure";
 import { MarketDataCoordinator } from "../../../market-data/coordinator";
 import type { QueryEntry } from "../../../market-data/result-types";
 import { resolveEntryData } from "../../../market-data/selectors";
 import type { DataProvider } from "../../../types/data-provider";
 import type { Quote } from "../../../types/financials";
-import { fxLegReferenceRate, fxLegs, liveFxLegEntry, type FxLeg } from "./live-legs";
+import { quoteChangeBasis, type QuoteChangeBasis } from "../../../market-data/market/change-basis";
+import { fxLegMoveReference, fxLegs, liveFxLegEntry, type FxLeg } from "./live-legs";
 
 /** One USD leg as the board reads it: the rate it draws and where that rate came from. */
 export interface FxLegReading {
@@ -13,10 +15,13 @@ export interface FxLegReading {
   /** The pair quote, only when the rate is its own: it then says what the rate is (live or delayed, its session). */
   quote: Quote | null;
   /**
-   * USD per unit at the pair's previous close, only when the rate is the pair
-   * quote's: a loaded rate has no previous close to read against.
+   * USD per unit at the pair quote's previous daily close, for the rate drawn
+   * whether it is the quote's or a loaded rate of the same FX trading day
+   * (fxLegMoveReference); null when the quote is stale or has none.
    */
   reference: number | null;
+  /** The close `reference` is, as `quote` names it ("vs Wed 21 Oct close"). */
+  changeBasis?: QuoteChangeBasis | null;
   /** Why the leg has no rate, when it has none. */
   error: string | null;
 }
@@ -25,9 +30,9 @@ export interface FxLegReading {
  * The board's USD legs, read once the way the pane reads them, through the
  * same market data coordinator over the same service: each leg's loaded rate
  * (`loadFxRate`, dated by the shared FX cache), replaced by its pair quote when
- * that quote is current and at least as new. Only a pair quote brings the
- * previous close a cross's move is read against. A leg with neither has no
- * rate, never parity.
+ * that quote is current and at least as new. The pair quote brings the
+ * previous close a cross's move is read against, for either rate. A leg with
+ * neither has no rate, never parity.
  */
 export async function loadFxBoard(
   currencies: readonly string[],
@@ -42,18 +47,20 @@ export async function loadFxBoard(
       Promise.all(legs.map((leg) => coordinator.loadFxRate(leg.currency, { forceRefresh }))),
       // A pair quote only refines a loaded rate, so a failed batch leaves the loaded rates.
       coordinator.loadQuotesBatch(legs.map((leg) => ({ symbol: leg.symbol, exchange: "" })), { forceRefresh })
-        .catch((): QueryEntry<Quote>[] => []),
+        .catch(logFailure("fx-matrix.client", "Load FX pair quotes failed", [] as QueryEntry<Quote>[])),
     ]);
     return new Map(legs.map((leg, index) => {
       const rate = rates[index]!;
       const quote = quotes[index];
       const live = liveFxLegEntry(leg, quote, rate);
       const entry = live ?? (resolveEntryData(rate) != null ? rate : null);
+      const close = fxLegMoveReference(leg, quote, entry);
       return [leg.currency, {
         leg,
         entry,
         quote: live ? resolveEntryData(quote) : null,
-        reference: live ? fxLegReferenceRate(leg, quote) : null,
+        reference: close?.rate ?? null,
+        changeBasis: close ? quoteChangeBasis(close.quote) : null,
         error: entry ? null : rate.error?.message ?? "No rate came back.",
       }] as const;
     }));

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

@@ -1,4 +1,5 @@
-import type { HeadlessPaneDefinition, HeadlessRowsResult } from "../../../types/plugin";
+import type { HeadlessPaneColumn, HeadlessPaneDefinition, HeadlessRowsResult } from "../../../types/plugin";
+import { combinedChangeBasisLabel } from "../../../market-data/market/change-basis";
 import { resolveEntryData } from "../../../market-data/selectors";
 import { formatPercentRaw } from "../../../utils/format";
 import { formatUtcTime } from "../../../utils/utc-time";
@@ -10,6 +11,26 @@ import { FX_MATRIX_REPORT_OPTIONS, fxMatrixReportNotices } from "./settings";
 
 const iso = (time: number | null | undefined) => time != null && Number.isFinite(time) ? new Date(time).toISOString() : null;
 
+const MOVE_COLUMN: HeadlessPaneColumn = { key: "movePercent", header: "Move", align: "right", format: (value) => typeof value === "number" ? formatPercentRaw(value) : "—" };
+const CROSS_COLUMNS: HeadlessPaneColumn[] = [
+  { key: "pair", header: "Pair" },
+  { key: "rate", header: "Rate", align: "right", format: (value) => typeof value === "number" ? formatRate(value) : "—" },
+  MOVE_COLUMN,
+  { key: "asOf", header: "As of", shrink: false, format: (value) => typeof value === "string" ? formatUtcTime(value) : "—" },
+  { key: "stale", header: "Status", format: (value, row) => (
+    row.rate == null ? "unavailable" : value ? "stale" : row.asOf == null ? "time unknown" : "current"
+  ) },
+];
+
+/**
+ * The columns with the move's header naming its close, as `quote` names a
+ * pair's (`Move vs Wed 21 Oct close`), in the text report; exports keep
+ * `Move`, so a column read by its name stays where it was.
+ */
+function crossColumns(basis: string | null): HeadlessPaneColumn[] {
+  return basis ? CROSS_COLUMNS.map((column) => column === MOVE_COLUMN ? { ...column, textHeader: `Move ${basis}` } : column) : CROSS_COLUMNS;
+}
+
 /** USD per unit, USD itself as 1; null for a leg with no usable rate. */
 function usdPerUnit(readings: ReadonlyMap<string, FxLegReading>, currency: string): number | null {
   if (currency === "USD") return 1;
@@ -22,9 +43,10 @@ function usdPerUnit(readings: ReadonlyMap<string, FxLegReading>, currency: strin
  * reads: one unit of `base` buys `rate` of `quote`, through the USD legs. Each
  * leg is dated as the pane dates it for `fn` and `shot` (`fxRateObservations`),
  * a cross as `fx <PAIR>` dates one (`fxPairObservation`): as old as its older
- * leg, stale when either leg is. It moves only when both legs carry a previous
- * close, the pane's tint rule. The report itself is dated by the legs, so its
- * closing line is the one the pane's capture ends with.
+ * leg, stale when either leg is. It moves from both legs' previous daily
+ * closes, the pane's tint rule, and the Move header names that close. The
+ * report itself is dated by the legs, so its closing line is the one the
+ * pane's capture ends with.
  */
 export function projectFxCrosses(
   currencies: readonly FxCurrency[],
@@ -69,12 +91,15 @@ export function projectFxCrosses(
     };
   }));
 
+  // The closes the moves are read from: one day for a board read at once, "vs mixed closes" otherwise.
+  const moveBasis = combinedChangeBasisLabel(currencies.map((currency) => readings.get(currency)?.changeBasis));
   const unavailable = currencies.filter((currency) => !rates.has(currency));
   const errors = unavailable.flatMap((currency) => {
     const error = readings.get(currency)?.error;
     return error ? [`${currency}: ${error}`] : [];
   });
   return {
+    columns: crossColumns(moveBasis),
     rows,
     ...(rows.length === 0 ? { empty: "One currency has no crosses. Add another, such as --currencies USD,EUR." } : {}),
     complete: unavailable.length === 0,
@@ -86,7 +111,8 @@ export function projectFxCrosses(
       currencies,
       unit: "quote currency per one unit of the base currency",
       method: "the base currency's USD rate divided by the quote currency's; the two legs' observation times can differ",
-      movePercent: "the cross against both legs' previous closes; empty where a leg has no current pair quote",
+      movePercent: "the cross against both legs' previous daily closes, from each pair's quote; empty where a leg has no current pair quote",
+      ...(moveBasis ? { changeBasis: moveBasis } : {}),
       legs: currencies.filter((currency) => currency !== "USD").map((currency) => {
         const reading = readings.get(currency);
         const observation = observed.get(currency);
@@ -119,15 +145,7 @@ export const fxMatrixHeadless: HeadlessPaneDefinition<"rows"> = {
     screenshotReadiness: "live-dom",
   },
   options: [...FX_MATRIX_REPORT_OPTIONS],
-  columns: [
-    { key: "pair", header: "Pair" },
-    { key: "rate", header: "Rate", align: "right", format: (value) => typeof value === "number" ? formatRate(value) : "—" },
-    { key: "movePercent", header: "Move", align: "right", format: (value) => typeof value === "number" ? formatPercentRaw(value) : "—" },
-    { key: "asOf", header: "As of", shrink: false, format: (value) => typeof value === "string" ? formatUtcTime(value) : "—" },
-    { key: "stale", header: "Status", format: (value, row) => (
-      row.rate == null ? "unavailable" : value ? "stale" : row.asOf == null ? "time unknown" : "current"
-    ) },
-  ],
+  columns: CROSS_COLUMNS,
   // Ask Gloom gets every cross of all 45 currencies inside its result limit:
   // the pair names both codes, and each leg's feed and delay are in metadata.
   compact: (result) => ({

package/src/plugins/builtin/fx-matrix/index.tsx

@@ -1,3 +1,4 @@
+import { logFailure } from "../../../utils/log-failure";
 import { useCallback, useMemo, useRef, useState, type ReactNode } from "react";
 import {
   DataTableView,
@@ -24,7 +25,7 @@ import { fxRateObservations } from "../shared/fx-rate-freshness";
 import { useLiveQuoteEntries } from "../../../state/hooks/quote-streaming";
 import { useAutoRefresh, useUpdatedAgo } from "../../../react/auto-refresh";
 import { useLiveStreamingSetting } from "../../../state/hooks/live-streaming";
-import { fxLegQuoteKey, fxLegReferenceRate, fxLegTargets, fxLegs, fxLegsBehind, liveFxLegEntry } from "./live-legs";
+import { fxLegMoveReference, fxLegQuoteKey, fxLegReferenceRate, fxLegTargets, fxLegs, fxLegsBehind, liveFxLegEntry } from "./live-legs";
 import { CURRENCY_FLAG_REGIONS, FX_CURRENCIES, formatRate, resolveCurrencies, type FxCurrency } from "./pairs";
 import { crossMovePercent, directionTint, nextTintLevel } from "./direction";
 import { fxMatrixSettings } from "./settings";
@@ -91,20 +92,21 @@ function FxMatrixPane({ focused, width, height }: PaneProps) {
     }
     return references;
   }, [legEntries, legs, rates]);
-  // A cell's direction is its cross against the pair's previous close. Only a
-  // leg whose rate is the live quote's and whose quote carries a previous close
-  // counts, USD (the base) as 1: the first rate this pane drew is no daily
-  // reference, and a snapshot rate or a stale quote has no previous close to
-  // read against.
+  // A cell's direction is its cross against the pairs' previous daily closes,
+  // USD (the base) as 1: each leg's pair quote's close, whether the rate drawn
+  // is that quote's or a snapshot rate of the same FX trading day
+  // (fxLegMoveReference). The first rate this pane drew is no daily reference,
+  // and a stale quote has no close to read against.
   const directionReferences = useMemo(() => {
+    const coordinator = getSharedMarketDataCoordinator();
     const references = new Map<string, number>([["USD", 1]]);
     for (const leg of legs) {
-      if (!liveEntries.has(leg.currency)) continue;
-      const reference = fxLegReferenceRate(leg, legEntries.get(fxLegQuoteKey(leg)));
-      if (reference != null) references.set(leg.currency, reference);
+      const drawn = liveEntries.get(leg.currency) ?? coordinator?.getFxEntry(leg.currency);
+      const reference = fxLegMoveReference(leg, legEntries.get(fxLegQuoteKey(leg)), drawn);
+      if (reference) references.set(leg.currency, reference.rate);
     }
     return references;
-  }, [legEntries, legs, liveEntries]);
+  }, [legEntries, legs, liveEntries, snapshotRates]);
   // The step each cell showed last, which a tick near a boundary keeps.
   const tintLevels = useRef(new Map<string, number>());
   // Export the provenance of this render's rates, even if a provider response
@@ -156,7 +158,7 @@ function FxMatrixPane({ focused, width, height }: PaneProps) {
     if (!coordinator) return;
     for (const currency of codes) {
       if (currency === "USD") continue;
-      void coordinator.loadFxRate(currency, { forceRefresh: true }).catch(() => {});
+      void coordinator.loadFxRate(currency, { forceRefresh: true }).catch(logFailure("fx-matrix", "Refresh FX rate failed"));
     }
   }, []);
   const refresh = useCallback(() => reload(currencies), [currencies, reload]);

package/src/plugins/builtin/fx-matrix/live-legs.ts

@@ -3,6 +3,7 @@ import { buildQuoteKey, resolveEntryData } from "../../../market-data/selectors"
 import type { QuoteSubscriptionTarget } from "../../../types/data-provider";
 import type { Quote } from "../../../types/financials";
 import { isStreamCarryingQuote } from "../shared/use-quote-board";
+import { fxTradingDay } from "../../../utils/fx-market-hours";
 
 /** Currencies the market quotes as USD per unit; the rest quote as units per USD. */
 const USD_QUOTED = new Set(["EUR", "GBP", "AUD", "NZD"]);
@@ -92,3 +93,24 @@ export function fxLegReferenceRate(leg: FxLeg, entry: QueryEntry<Quote> | undefi
   if (close == null || !Number.isFinite(close) || close <= 0) return null;
   return leg.inverted ? 1 / close : close;
 }
+
+/**
+ * What a leg's move is read against: its pair quote's previous daily close
+ * (USD per unit), the close `quote` measures the pair from, whichever rate
+ * the board draws. A loaded rate a minute newer than the quote moves from the
+ * same close, so it reads against it too, as long as it is of the quote's FX
+ * trading day. Null when the quote is stale or carries no previous close, or
+ * when the drawn rate is of a later trading day (or undated) than the quote.
+ */
+export function fxLegMoveReference(
+  leg: FxLeg,
+  entry: QueryEntry<Quote> | undefined,
+  drawn: Pick<QueryEntry<number>, "asOf"> | null | undefined,
+): { rate: number; quote: Quote } | null {
+  const quote = resolveEntryData(entry);
+  const rate = fxLegReferenceRate(leg, entry);
+  if (!quote || quote.stale === true || rate == null || !Number.isFinite(quote.lastUpdated)) return null;
+  const drawnAt = drawn?.asOf;
+  if (drawnAt == null || !Number.isFinite(drawnAt) || fxTradingDay(drawnAt) !== fxTradingDay(quote.lastUpdated)) return null;
+  return { rate, quote };
+}

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

@@ -16,6 +16,7 @@ function currencyName(code: string): string | null {
     const name = currencyNames.of(code);
     return name && name !== code ? name : null;
   } catch {
+    // Intentional ignore: runtimes without currency display names keep the currency code as the picker label.
     currencyNames = null;
     return null;
   }
@@ -98,5 +99,5 @@ export const FX_MATRIX_REPORT_OPTIONS: readonly PaneReportOptionDef[] = [{
 /** A report of the default board says it is only the majors, and how to choose others. */
 export function fxMatrixReportNotices(settings: Readonly<Record<string, unknown>>): string[] {
   if (settings.currencies != null) return [];
-  return [`Showing the ${MAJOR_CURRENCIES.length} majors. Choose others with --currencies USD,ZAR,NGN; gloomberb catalog FXC lists all ${FX_CURRENCIES.length}.`];
+  return [`Showing the ${MAJOR_CURRENCIES.length} majors. Choose others with --currencies USD,ZAR,NGN; gloom catalog FXC lists all ${FX_CURRENCIES.length}.`];
 }

package/src/plugins/builtin/gpu/headless.ts

@@ -7,6 +7,7 @@ import {
   gpuLabel, gpuNoMatch, gpuPrice, gpuProvenanceLabel, gpuRows, gpuSource, gpuTab,
 } from "./model";
 import { quoteFreshnessFields } from "../shared/report-freshness";
+import { countOf, freePreviewNote } from "../shared/free-preview";
 import { getRegularSessionDisplay } from "../../../market-data/market/status";
 
 const observationRow = (row: GpuObservation) => ({ gpu: gpuLabel(row), source: gpuSource(row), basis: gpuBasisLabel(row.basis),
@@ -73,8 +74,12 @@ export const gpuHeadless: HeadlessPaneDefinition<"bundle"> = {
     const previews = await fetchGpuModelPreviews(gpuPreviewModels(board, tab === "equities" ? gpuEquityModels(selected) : [selected]), ctx.apiClient);
     const rows = [...board.rows, ...previews];
     const previewed = [...new Set(previews.map((row) => row.gpuModel))];
-    const notes = previewed.length ? [`${previewed.join(" and ")} ${previewed.length > 1 ? "are" : "is"} not on the free board: ${previewed.length > 1 ? "their" : "its"} latest free rows stand in. Pro adds every provider and the 1D, 7D and 30D moves.`]
-      : board.access?.locked && !model && tab === "board" ? ["The free board shows three rows; name a GPU (GPU H100) for its latest free rows, or upgrade to Pro for every GPU."] : [];
+    // What the free view leaves to Pro is the report's Pro line, never a note or an error.
+    const locks = previewed.length
+      ? [freePreviewNote({ shows: `the latest rows of ${previewed.join(" and ")}, which the free board leaves out`, adds: "every provider and the 1D, 7D and 30D moves" })]
+      : board.access?.locked && !model && tab === "board"
+        ? [freePreviewNote({ shows: `${countOf(board.rows.length, "board row")}, or the latest rows of a GPU you name (GPU H100)`, adds: "every GPU and provider, with the 1D, 7D and 30D moves" })]
+        : [];
     if (tab === "equities") {
       const related = gpuEquityRows(rows, selected, !!board.access?.locked);
       const histories = await loadGpuEquityHistory(ctx.marketData);
@@ -97,12 +102,12 @@ export const gpuHeadless: HeadlessPaneDefinition<"bundle"> = {
         { key: "gpu", header: "GPU" }, { key: "gpuSource", header: "GPU list series", format: (value: unknown, row: HeadlessPaneRow) => typeof value === "string" ? value : String(row.gpuGap ?? "-") },
         { key: "gpuPrice", header: "$/GPU-hr", align: "right" as const, format: (value: unknown, row: HeadlessPaneRow) => locked(value, row, price) },
         { key: "gpuChange7d", header: "GPU 7D", align: "right" as const, format: (value: unknown, row: HeadlessPaneRow) => locked(value, row, percent) },
-      ], rows: equities }], complete: !board.access?.locked, metadata, notes, errors: [...board.gaps, ...histories.flatMap((entry) => entry.error ? [entry.error] : [])],
+      ], rows: equities }], complete: !board.access?.locked, metadata, errors: [...locks, ...board.gaps, ...histories.flatMap((entry) => entry.error ? [entry.error] : [])],
       unavailableSymbols: equities.filter((row) => row.price == null || row.change5d == null).map((row) => row.symbol) };
     }
     const boardRows = gpuRows(rows, model).map((row) => ({ ...observationRow(row), change1d: row.change1d, change7d: row.change7d,
       change30d: row.change30d, stale: row.stale, sample: row.stats ?? null, ...(gpuChangesLocked(row) ? { changesLocked: true } : {}) }));
     return { sections: [{ title: "GPU rental prices", columns, rows: boardRows, empty: `No ${model ? `${model} ` : ""}rental prices have been observed yet.` }],
-      freshness, complete: !board.access?.locked, metadata, notes, errors: board.gaps };
+      freshness, complete: !board.access?.locked, metadata, errors: [...locks, ...board.gaps] };
   },
 };

package/src/plugins/builtin/help/index.tsx

@@ -267,8 +267,17 @@ function HelpPane({ focused, width, height }: PaneProps) {
         entry("place", ["Enter", "Arrows"], "With a tool picked, Enter starts it at the cursor, the arrows move its end, and Enter finishes it."),
         entry("drawings", ["[", "]"], "With a drawing tool picked, pick a drawing."),
         entry("colour", ["c", "Backspace"], "Cycle the drawing colour, or delete the picked drawing (the last one while a drawing tool is picked)."),
-        entry("zoom-pointer", ["Ctrl+Scroll"], "Zoom around the pointer."),
-        entry("zoom-keys", ["+/-", "0"], "Zoom the focused chart in or out, or reset it."),
+        entry("zoom-pointer", shortcutDisplayMode === "terminal" ? ["Ctrl+Scroll"] : ["Ctrl+Scroll", "Pinch"], "Zoom time around the pointer."),
+        entry("time-axis", ["Drag"], "On the time axis, zoom time: left zooms in, right zooms out. Double-click fits it again."),
+        entry("value-axis", ["Drag", "Scroll"], "On a value axis, stretch or squeeze that panel's values. Dragging the plot then moves them too."),
+        entry("value-fit", ["Double-click", "Auto"], "Fit a hand-scaled panel's values again, from its axis or the Auto button at its foot."),
+        entry("zoom-keys", ["+/-", "0"], "Zoom the focused chart in or out, or reset it, values included."),
+        shortcutDisplayMode === "terminal"
+          ? entry("panel-height", ["Shift+Up/Down"], "Make the top panel taller or shorter; Reset Panel Heights in the pane menu puts back the split.")
+          : entry("panel-height", ["Drag", "Shift+Up/Down"], "Drag the line between two panels to resize them, double-click it for the default split; Shift+Up and Shift+Down resize the top panel."),
+        entry("panel-max", ["Double-click"], "Double-click a panel to give it the whole chart, and again to show every panel."),
+        entry("tools-hide", ["Shift+T"], "Hide the drawing tools to a single button, or show them again."),
+        entry("legend-fold", ["Shift+L"], "Fold the legend to its first series and a count of the rest, or open it again."),
       ],
     },
     {
@@ -334,7 +343,7 @@ function HelpPane({ focused, width, height }: PaneProps) {
             )}
 
             <Box flexDirection="column" gap={1}>
-              <SectionHeading title="How To Use Gloomberb" />
+              <SectionHeading title="How To Use Gloom" />
               <Box flexDirection="column">
                 <Text fg={colors.textDim} wrapText>{t("Click anything to use it; the keys shown beside actions are shortcuts.")}</Text>
                 <Text fg={colors.textDim} wrapText>
@@ -413,6 +422,7 @@ export const helpModule: PluginModule = {
       name: "Help",
       icon: "?",
       component: HelpPane,
+      reportFreshness: { status: "not-a-feed", basis: "documentation" },
       defaultPosition: "right",
       defaultMode: "floating",
       defaultFloatingSize: { width: 88, height: 32 },

package/src/plugins/builtin/holders/beneficial-model.ts

@@ -1,7 +1,7 @@
 import type { BeneficialOwnerFiling, BeneficialOwnerStatus } from "../../../api-client/beneficial-owners";
 import type { DataTableColumn } from "../../../components";
 import type { HolderRecord } from "../../../types/financials";
-import { clipToDisplayWidth, displayWidth, formatCompact } from "../../../utils/format";
+import { clipToDisplayWidth, displayWidth, formatCompact, MISSING_VALUE } from "../../../utils/format";
 import { compareSortValues, type SortDirection } from "../../../utils/sort-values";
 import { matchFilerToHolder, type Holder13FMatch } from "./thirteenf-match";
 
@@ -98,11 +98,8 @@ export function thirteenFAction(holder: HolderRecord | undefined): ThirteenFActi
     if (changeShares > 0 && prior === 0) return { label: "NEW", value: Number.POSITIVE_INFINITY };
     if (prior > 0) return { label: signedPercent(changeShares / prior), value: changeShares / prior };
   }
-  if (changePercent != null && Number.isFinite(changePercent)) {
-    // The Table tab reads a provider's change the same way: a fraction up to 1, percent points above.
-    const fraction = Math.abs(changePercent) <= 1 ? changePercent : changePercent / 100;
-    return { label: signedPercent(fraction), value: fraction };
-  }
+  // A holder record's change is a fraction of the prior position, as the Table tab reads it.
+  if (changePercent != null && Number.isFinite(changePercent)) return { label: signedPercent(changePercent), value: changePercent };
   return null;
 }
 
@@ -166,9 +163,9 @@ export function stakeToday(
   return { percent, sharesOutstanding };
 }
 
-/** `about 49.4% on 35.26M sh today`. */
-export function formatStakeToday(today: StakeToday): string {
-  return `about ${formatClassPercent(today.percent)} on ${formatCompact(today.sharesOutstanding)} sh today`;
+/** `about 49.4% on 35.26M sh today`, or `as of 2026-09-03` for a count dated by its filing. */
+export function formatStakeToday(today: StakeToday, sharesOutstandingAsOf?: string | null): string {
+  return `about ${formatClassPercent(today.percent)} on ${formatCompact(today.sharesOutstanding)} sh ${sharesOutstandingAsOf ? `as of ${sharesOutstandingAsOf}` : "today"}`;
 }
 
 function beneficialFormLabel(filing: Pick<BeneficialOwnerFiling, "kind" | "amendment">): string {
@@ -308,7 +305,7 @@ export function formatPercentOfClass(
 ): string {
   const value = row.filing.percentOfClass;
   const mark = marker ? stakeMarker(row.stake) : "";
-  if (value == null) return mark || "-";
+  if (value == null) return mark || MISSING_VALUE;
   return mark ? `${formatClassPercent(value)} ${mark}` : formatClassPercent(value);
 }
 
@@ -320,7 +317,7 @@ export function formatPointChange(value: number | null): string {
 }
 
 export function formatOwnerShares(value: number | null): string {
-  return value == null ? "-" : formatCompact(value);
+  return value == null ? MISSING_VALUE : formatCompact(value);
 }
 
 /**

package/src/plugins/builtin/holders/beneficial-report.ts

@@ -14,7 +14,7 @@ import {
   type BeneficialSortPreference,
 } from "./beneficial-model";
 import { buildRows } from "./table-model";
-import { formatCompact } from "../../../utils/format";
+import { formatCompact, MISSING_VALUE } from "../../../utils/format";
 
 /** What `holders --form` lists: the 13F table, or the 13D/13G beneficial owners. */
 export type HolderForm = "13f" | "13d" | "13g" | "all";
@@ -53,7 +53,7 @@ export const BENEFICIAL_REPORT_COLUMNS = [
     align: "right" as const,
     format: (value: unknown, row: Record<string, unknown>) => {
       const marker = stakeMarker(row.status === "below-threshold" || row.status === "exited" ? row.status : null);
-      if (typeof value !== "number") return marker || "-";
+      if (typeof value !== "number") return marker || MISSING_VALUE;
       return marker ? `${formatClassPercent(value)} ${marker}` : formatClassPercent(value);
     },
   },
@@ -76,9 +76,9 @@ export const BENEFICIAL_REPORT_COLUMNS = [
     align: "right" as const,
     format: (value: unknown) => formatOwnerShares(typeof value === "number" ? value : null),
   },
-  { key: "eventDate", header: "Event", format: (value: unknown) => typeof value === "string" ? value : "-" },
+  { key: "eventDate", header: "Event", format: (value: unknown) => typeof value === "string" ? value : MISSING_VALUE },
   { key: "filingDate", header: "Filed" },
-  { key: "thirteenF", header: "13F", align: "right" as const, format: (value: unknown) => typeof value === "string" ? value : "-" },
+  { key: "thirteenF", header: "13F", align: "right" as const, format: (value: unknown) => typeof value === "string" ? value : MISSING_VALUE },
 ];
 
 /** The 13D/13G columns these rows fill: `% Today` only when a report's base is no longer today's count. */
@@ -94,10 +94,11 @@ export function beneficialReportColumns(rows: readonly BeneficialReportRow[]): t
 export function beneficialReportLegend(
   rows: readonly BeneficialReportRow[],
   sharesOutstanding: number | null | undefined,
+  sharesOutstandingAsOf?: string | null,
 ): string | null {
   if (rows.length === 0) return null;
   const today = sharesOutstanding != null && rows.some((row) => row.percentToday != null)
-    ? `; % Today is the same shares over ${formatCompact(sharesOutstanding)} shares outstanding today`
+    ? `; % Today is the same shares over ${formatCompact(sharesOutstanding)} shares outstanding ${sharesOutstandingAsOf ? `as of ${sharesOutstandingAsOf}` : "today"}`
     : "";
   const others = rows.some((row) => row.otherPersons > 0) ? " +N after a name: other reporting persons on the same report." : "";
   return `% Class is as filed${today}.${others}`;