gloomberb 0.18.3 → 0.18.5

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

@@ -1,14 +1,40 @@
+import type { PaneTemplateContext, ShortcutArgError } from "../../../types/plugin";
+import { findNamedCollection, unknownCollectionArgError } from "../../../portfolio/collection-name";
 import type { PluginModule } from "../plugin-module";
 import { exposureHeadless } from "./headless";
 import { ExposurePane } from "./pane";
 
+const SOURCE = /^(PORT|WATCH):(.+)$/i;
+
+/**
+ * `EXPO PORT:Book` names a portfolio, and `WATCH:Watchlist` a watchlist, by
+ * name or id in any case, as `fn EXPO` reads them. The pane keeps its source
+ * by id (`PORT:book`), so the name is rewritten to the id it names.
+ */
+function sourceInput(arg: string, context: PaneTemplateContext): string {
+  const source = SOURCE.exec(arg.trim());
+  if (!source) return arg;
+  const prefix = source[1]!.toUpperCase();
+  const match = findNamedCollection(prefix === "PORT" ? context.config.portfolios : context.config.watchlists, source[2]);
+  return match ? `${prefix}:${match.id}` : arg;
+}
+
+/** `EXPO PORT:Nope` or `EXPO WATCH:Nope` names a portfolio or watchlist nothing has; tickers and weights are read by the pane. */
+function unknownSourceArg(arg: string, context: PaneTemplateContext): ShortcutArgError | null {
+  const source = SOURCE.exec(arg.trim());
+  if (!source) return null;
+  return source[1]!.toUpperCase() === "PORT"
+    ? unknownCollectionArgError(source[2]!, context.config.portfolios, "portfolio", (name) => `PORT:${name}`)
+    : unknownCollectionArgError(source[2]!, context.config.watchlists, "watchlist", (name) => `WATCH:${name}`);
+}
+
 export const exposureModule: PluginModule = {
   panes: [{ id: "exposure", name: "Exposure", icon: "E", component: ExposurePane, defaultPosition: "right", defaultMode: "floating", defaultFloatingSize: { width: 138, height: 31 }, tableExport: true, headless: exposureHeadless,
     personalData: "holdings",
     portableShare: { private: { params: true, settings: true, state: true } } }],
   paneTemplates: [{ id: "exposure-pane", paneId: "exposure", label: "Exposure", description: "Pro scenario exposures across holdings, geographic revenue and supply chains, with source evidence and portfolio concentrations.",
     keywords: ["exposure", "scenario", "stress", "portfolio", "supply", "country", "tariff", "pro"],
-    shortcut: { prefix: "EXPO", argKind: "text", argOptional: true, argPlaceholder: "AAPL=60% NVDA=40%" }, headless: exposureHeadless,
-    createInstance: (_context, options) => ({ params: { input: options?.arg ?? "" } }),
+    shortcut: { prefix: "EXPO", argKind: "text", argOptional: true, argPlaceholder: "AAPL=60% NVDA=40%", argError: unknownSourceArg }, headless: exposureHeadless,
+    createInstance: (context, options) => ({ params: { input: sourceInput(options?.arg ?? "", context) } }),
   }],
 };

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

@@ -1,12 +1,31 @@
 import type { ExposureBasis, ExposureComponent, ExposureExtensionObservation, ExposureHolding, ExposurePayload, ExposureRange, ExposureScenario } from "../../../api-client/exposure";
+import { quarterLabel } from "../shared/earnings-report";
 import { humanLabel } from "../shared/research-cells";
 
 export const TABS = [{ value: "table", label: "Table" }, { value: "drivers", label: "Drivers" }, { value: "paths", label: "Paths" }, { value: "portfolio", label: "Portfolio" }];
 export const DEFAULT_SCENARIO: ExposureScenario = { id: "taiwan-disruption", label: "Taiwan disruption", shocks: [{ id: "taiwan", kind: "country", target: "TW", changePct: -100 }] };
+/**
+ * The ids of Gloom Cloud's scenario library, which the catalog lists for
+ * `--scenario`. A report reads the library itself, so an id added there runs
+ * before it is listed here.
+ */
+export const LIBRARY_SCENARIO_IDS = ["taiwan-disruption", "china-demand", "europe-demand", "china-semiconductor-ban", "china-tariff",
+  "oil-up", "rates-up", "usd-up", "tsmc-outage", "microsoft-capex"] as const;
 export const basisLabel = (basis: string | null) => basis?.replaceAll("_", " ") ?? "Unknown basis";
 const pct = (value: number) => `${value.toFixed(1)}%`;
 export const rangeText = (range: ExposureRange | null) => !range ? "Unknown" : range.low === range.high ? pct(range.low) : `${range.low.toFixed(1)} to ${range.high.toFixed(1)}%`;
 export const fraction = (value: number) => pct(value * 100);
+/** "1 hop", "2 hops". */
+export const hopsText = (count: number) => `${count} hop${count === 1 ? "" : "s"}`;
+/**
+ * A reporting period as the tables word it. The server keys a quarter by its end date (`quarter:2026-07-31`), which
+ * reads as the month it ends in, Jul 2026, as the earnings events label a quarter; a date or a source's own words
+ * stay as they are.
+ */
+export function periodText(period: string): string {
+  const quarter = /^quarter:(\d{4}-\d{2}(?:-\d{2})?)$/.exec(period);
+  return quarter ? quarterLabel(quarter[1]) : period;
+}
 
 /** A weighted list is entirely explicit. Never silently fill missing weights or normalize shorts. */
 export function parseHoldings(text: string): ExposureHolding[] {
@@ -71,7 +90,7 @@ export function exposureCellText(row: ExposureRow, column: "label" | "basis" | "
     // What the number rests on, in words: disclosed by the company, estimated by a chain, or not visible.
     case "classification": return `${humanLabel(row.classification)}${row.incomplete && row.classification !== "unknown" ? " · partial" : ""}`;
     case "impact": return row.impact ? rangeText(row.impact) : "--";
-    case "period": return row.period ?? "--";
+    case "period": return row.period ? periodText(row.period) : "--";
     case "weight": return fraction(row.weight ?? 0);
   }
 }

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

@@ -8,6 +8,7 @@ import { useAppSelector, useAsyncResource, useAutoRefresh, useMarketData, usePan
 import { useThemeColors } from "../../../theme/theme-context";
 import type { PaneProps } from "../../../types/plugin";
 import { Box, ScrollBox, Text, useRendererHost, useUiCapabilities } from "../../../ui";
+import { withCountryFlag } from "../../../components/ui/country-flag";
 import { logFailure } from "../../../utils/log-failure";
 import { SignInWall } from "../cloud/auth-actions";
 import { CLOUD_PLAN_KEY, useCloudUpgradeAction } from "../shared/cloud-upgrade";
@@ -19,7 +20,7 @@ import { ExposurePathDiagram, ExposureRanges } from "./charts";
 import { fetchExposure, fetchScenarios, validateExposure } from "./client";
 import { ExposureEditor, type ExposureInputs } from "./editor";
 import { portfolioHoldings, watchlistHoldings } from "./holdings";
-import { basisLabel, DEFAULT_SCENARIO, exposureCellText, fraction, parseCustomScenario, parseHoldings, pathRows, portfolioRows, rangeText, tableRows, TABS, type ExposureRow } from "./model";
+import { basisLabel, DEFAULT_SCENARIO, exposureCellText, fraction, hopsText, parseCustomScenario, parseHoldings, pathRows, periodText, portfolioRows, rangeText, tableRows, TABS, type ExposureRow } from "./model";
 import { useExposureEvidence } from "./evidence";
 import { driverRows, driverScope, driverUnits, driverValue } from "./drivers";
 
@@ -28,7 +29,7 @@ function EvidenceItem({ item }: { item: ExposureEvidence }) {
   const host = useRendererHost();
   return <Box flexDirection="column" paddingY={1}>
     <KeyValueRow labelWidth={20} label="Evidence" value={`${item.tier} · ${item.asOf ?? "undated"}`} detail={item.confidence === null ? undefined : `${Math.round(item.confidence * 100)}% confidence`} />
-    <KeyValueRow labelWidth={20} label="Period / units" value={`${item.period ?? "unknown"} · ${item.units}${item.currency ? ` ${item.currency}` : ""}`} />
+    <KeyValueRow labelWidth={20} label="Period / units" value={`${item.period ? periodText(item.period) : "unknown"} · ${item.units}${item.currency ? ` ${item.currency}` : ""}`} />
     {item.revision ? <KeyValueRow labelWidth={20} label="Revision" value={item.revision} /> : null}
     {item.quote ? <Text fg={colors.textBright}>{item.quote}</Text> : <Text fg={colors.textDim}>{item.tier === "user" ? "User-supplied assumption" : "Structured observation; no verbatim quote"}</Text>}
     {item.url ? <ActionRow label="Open primary evidence" onPress={() => void host.openExternal(item.url!)} /> : null}
@@ -48,7 +49,7 @@ function ExposureDetail({ row, data, width }: { row: ExposureRow | null; data: E
       {Object.entries(row.driver.dimensions ?? {}).map(([key, value]) => <KeyValueRow key={key} labelWidth={20} label={humanLabel(key)} value={value} />)}
       {row.driver.evidence.map(item => <EvidenceItem key={item.id} item={item} />)}
     </> : row ? <>
-      <KeyValueRow labelWidth={20} label="Basis / period" value={`${basisLabel(row.basis)} · ${row.period ?? "unknown"}`} />
+      <KeyValueRow labelWidth={20} label="Basis / period" value={`${basisLabel(row.basis)} · ${row.period ? periodText(row.period) : "unknown"}`} />
       <KeyValueRow labelWidth={20} label={row.concentration ? "Gross exposure" : "Exposure"} value={rangeText(row.exposure)} detail={`${row.classification}${row.incomplete ? " · incomplete bound" : ""}`} />
       <KeyValueRow labelWidth={20} label={row.concentration ? "Signed exposure" : "Operating stress"} value={rangeText(row.impact)} detail={row.concentration ? "NAV-weighted operating exposure; not a scenario change" : "Estimated change in the stated denominator"} />
       {row.components.map(component => <Box key={component.id} flexDirection="column" paddingY={1}>
@@ -212,7 +213,11 @@ export function ExposurePane({ width, height, focused }: PaneProps) {
       case "value": return { text: row.driver ? driverValue(row.driver) : "--", value: row.driver?.value ?? null, color: colors.textBright };
       case "units": return { text: row.driver ? driverUnits(row.driver) : "", color: colors.textDim };
       case "scope": return { text: row.driver ? driverScope(row.driver) : "", color: colors.textDim };
-      case "label": return { text: exposureCellText(row, "label"), color: unknown ? colors.textDim : colors.text };
+      case "label": {
+        const cell = { text: exposureCellText(row, "label"), color: unknown ? colors.textDim : colors.text };
+        // Grouped by country, each target leads with its flag on the desktop and the web.
+        return concentration && view === "country" ? withCountryFlag(cell, row.label, desktop) : cell;
+      }
       case "basis": return row.basis ? { text: exposureCellText(row, "basis"), color: colors.textDim } : missingCell(colors);
       case "exposure": return row.exposure ? { text: exposureCellText(row, "exposure"), value: row.exposure.high, color: colors.textBright } : { text: exposureCellText(row, "exposure"), value: null, color: colors.textMuted };
       // Disclosed figures stand out; estimates read plainly, and the word says which is which.
@@ -244,7 +249,7 @@ export function ExposurePane({ width, height, focused }: PaneProps) {
   const query = <QueryBar width={width} filters={[
     { id: "scenario", label: "Scenario", value: scenarioId, options: [...(library.data ?? [DEFAULT_SCENARIO]).map(s => ({ value: s.id ?? (snapshot ? "captured" : "custom"), label: s.label })), { value: "custom", label: "Custom" }].filter((s, i, all) => all.findIndex(v => v.value === s.value) === i), onChange: (value: string) => { if (value === "custom") setEditing(true); else setScenarioId(value); } },
     ...(tab === "portfolio" ? [{ id: "group", label: "View", value: view, options: [{ value: "stress", label: "Stress" }, { value: "country", label: "Country" }, { value: "supplier", label: "Supplier" }, { value: "customer", label: "Customer" }], onChange: setView }] : []),
-  ]} meta={tab === "drivers" ? "Company disclosures" : tab === "portfolio" ? "NAV-weighted operating exposure" : `${data?.depth ?? inputs.depth} hops`} />;
+  ]} meta={tab === "drivers" ? "Company disclosures" : tab === "portfolio" ? "NAV-weighted operating exposure" : hopsText(data?.depth ?? inputs.depth)} />;
   if (!data && isCloudSessionRequired(resource.error) && !editing) return <SignInWall placement="exposure-signin" action="analyze exposures" needsVerification={session.needsVerification} />;
   return <Box width={width} height={height} flexDirection="column">
     {strip}

package/src/plugins/builtin/fear-greed/index.tsx

@@ -63,7 +63,7 @@ export const fearGreedPlugin: GloomPlugin = {
     },
   ],
 
-  // `gloomberb fear-greed`, as before the plugin moved out of the host. Runs
+  // `gloom fear-greed`, as before the plugin moved out of the host. Runs
   // without the pane cache attached when invoked from the CLI, so it always
   // fetches, which is what a CLI call wants anyway.
   cliCommands: [

package/src/plugins/builtin/filing-events/index.tsx

@@ -22,7 +22,7 @@ function filingEventsLockNote(lock: PaneLock): Promise<string> {
     does: "it reads each 8-K and sums up what it said and who it names",
     shows: "them",
     free: [{
-      text: (ticker, company) => `gloomberb fn SEC ${ticker} lists ${company}'s recent filings, 8-Ks among them, each with its filing date and its items by number and name.`,
+      text: (ticker, company) => `gloom fn SEC ${ticker} lists ${company}'s recent filings, 8-Ks among them, each with its filing date and its items by number and name.`,
       answers: (symbol, context) => filesForm(symbol, "8-K", context),
     }],
   });

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

@@ -274,6 +274,7 @@ export function FuturesPane({ focused, width, height }: PaneProps) {
     noQuotes,
     status.latestTs,
     status.loading,
+    status.savedAt,
     status.stale,
     status.unavailable,
   ]);

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

@@ -4,6 +4,8 @@ import { compareSortValues, type SortDirection } from "../../../utils/sort-value
 import type { BoardQuoteMap } from "../shared/use-quote-board";
 import { FUTURES_SECTOR_ORDER, type FuturesContract, type FuturesSector } from "../../../market-data/futures-board";
 import { futuresPriceUnit } from "../../../market-data/futures-contract";
+import { contractMonthLabel } from "../../../utils/contract-month";
+import { quoteDotMarketState } from "../../../market-data/market/status";
 import type { FuturesReturnHorizon } from "./returns";
 import type { FuturesTermsMap } from "./use-board-terms";
 import type { FrontReturnsMap } from "./use-front-returns";
@@ -41,20 +43,20 @@ export function futuresRowId(row: FuturesTableRow): string {
   return row.type === "header" ? `header-${row.sector}` : row.contract.symbol;
 }
 
-/** "Nov 26" or "Futures,Nov-2026"; a hyphen takes only a whole year, since "Futures,Nov-20" is 2026 cut short. */
+/** "Nov 2026", "Nov 26" or "Futures,Nov-2026"; a hyphen takes only a whole year, since "Futures,Nov-20" is 2026 cut short. */
 const CONTRACT_MONTH = /\b(Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)(?: (\d{4}|\d{2})|-(\d{4}))$/i;
 
 /**
  * The alias stays the row identity while its quoted contract rolls, so the
  * label is the catalog name plus the quoted contract's month ("30-Year T-Bond
- * Dec 26"). Quote names arrive as "Crude Oil Nov 26", "Corn Futures,Dec-2026"
- * or cut off mid-month ("Futures,Dec-"); a month without a year is dropped
- * rather than guessed.
+ * Dec 2026"). Quote names arrive as "Crude Oil Nov 2026", "Crude Oil Nov 26",
+ * "Corn Futures,Dec-2026" or cut off mid-month ("Futures,Dec-"); a month
+ * without a year is dropped rather than guessed.
  */
 export function futuresContractName(contract: FuturesContract, quote?: Quote | null): string {
   const month = quotedContractMonth(contract, quote);
   if (!month) return contract.name;
-  return `${contract.name} ${MONTH_NAMES[month.month]} ${String(month.year).slice(-2)}`;
+  return `${contract.name} ${contractMonthLabel(month.year, month.month)}`;
 }
 
 const MONTH_NAMES = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
@@ -82,9 +84,9 @@ function dayMonth(date: string): string {
  * The row's headline: the contract its quote prices, as futuresContractName
  * words it: the root's front month until its roll date. Two notes follow,
  * each from the day's facts. Once the continuous symbol has rolled while the
- * nearer month still trades, that month's last trade: "WTI Crude Oil Dec 26,
+ * nearer month still trades, that month's last trade: "WTI Crude Oil Dec 2026,
  * rolled (Nov expires 20 Oct)". When the day's volume put another month first,
- * that month: "WTI Crude Oil Nov 26, Dec most active". The terms only add a
+ * that month: "WTI Crude Oil Nov 2026, Dec most active". The terms only add a
  * note when they name the month the quote prices, so a roll between the two
  * loads never mixes months, and place the month when the quote's name carries
  * none. A name column too narrow for a note drops it, the last one first.
@@ -104,7 +106,7 @@ export function futuresContractHeadline(
   const month = agree ? quoted ?? termsMonth : quoted;
   if (!month) return contract.name;
   const priced = `${month.year}-${String(month.month + 1).padStart(2, "0")}`;
-  const plain = `${contract.name} ${MONTH_NAMES[month.month]} ${String(month.year).slice(-2)}`;
+  const plain = `${contract.name} ${contractMonthLabel(month.year, month.month)}`;
   if (!agree) return plain;
   const notes: Array<{ text: string; min: string }> = [];
   const nearest = terms?.nearest;
@@ -117,7 +119,7 @@ export function futuresContractHeadline(
   if (active && /^\d{4}-\d{2}$/.test(active.deliveryMonth) && active.deliveryMonth !== priced) {
     // Another year's month says which year it is.
     const name = MONTH_NAMES[Number(active.deliveryMonth.slice(5, 7)) - 1];
-    const label = active.deliveryMonth.slice(0, 4) === String(month.year) ? name : `${name} ${active.deliveryMonth.slice(2, 4)}`;
+    const label = active.deliveryMonth.slice(0, 4) === String(month.year) ? name : `${name} ${active.deliveryMonth.slice(0, 4)}`;
     notes.push({ text: `, ${label} most active`, min: `, ${label} most active` });
   }
   // The month the quote prices leads, so a column that clips the tail still shows it; a note keeps its place
@@ -168,7 +170,7 @@ function getSortValue(
     case "unit":
       return futuresUnitLabel(contract, terms?.get(contract.symbol)?.terms);
     case "status":
-      return quote?.marketState === "REGULAR" ? 0 : 1;
+      return quoteDotMarketState(quote) === "REGULAR" ? 0 : 1;
     case "code":
       return contract.code;
     case "name":

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

@@ -1,5 +1,5 @@
 import type { PricePoint, Quote } from "../../../types/financials";
-import { calendarMonthsBefore } from "../../../utils/calendar-date";
+import { periodReturn } from "../../../market-data/market/period-return";
 import type { FuturesContract } from "../../../market-data/futures-board";
 import { quotedContractMonth } from "./model";
 
@@ -9,7 +9,6 @@ export type FuturesReturnValues = Readonly<Record<FuturesReturnHorizon, number |
 export const NO_FUTURES_RETURNS: FuturesReturnValues = { "1W": null, "1M": null, YTD: null };
 
 const MONTH_CODES = "FGHJKMNQUVXZ";
-const DAY_MS = 86_400_000;
 
 /** Gloom symbol of one listed contract: LEZ26.CME. */
 function listedContractSymbol(contract: FuturesContract, year: number, month: number): string {
@@ -51,10 +50,6 @@ function utcDay(value: Date | string | number): string | null {
   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>();
@@ -86,25 +81,10 @@ export function pickFrontContract(
   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
+ * on or before the same date a week and a calendar month earlier, and its
+ * last close of the year before (periodReturn). 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.
@@ -116,17 +96,9 @@ export function frontContractReturns(
 ): 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`),
-  };
+  const liveDay = live ? utcDay(asOf) : null;
+  const latest = live && liveDay ? { day: liveDay, close: price } : closes.at(-1);
+  if (!latest) return NO_FUTURES_RETURNS;
+  const change = (period: FuturesReturnHorizon) => periodReturn(closes, period, latest)?.percent ?? null;
+  return { "1W": change("1W"), "1M": change("1M"), YTD: change("YTD") };
 }

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

@@ -1,5 +1,5 @@
 import type { DataTableCell, DataTableColumn } from "../../../components";
-import { colors, priceColor } from "../../../theme/colors";
+import { colors, shownPriceColor } from "../../../theme/colors";
 import type { Quote } from "../../../types/financials";
 import { TextAttributes } from "../../../ui";
 import { formatCompact, formatNumber, formatPercentRaw } from "../../../utils/format";
@@ -43,7 +43,7 @@ const DEFAULT_FUTURES_COLUMN_IDS = FUTURES_COLUMN_DEFS.map((column) => column.id
  * which the change in percent still gives. The previous close (the last price
  * less the change) goes first, then each row's quote time (the status line
  * dates the newest), which leaves a 1280-pixel shot room for "WTI Crude Oil
- * Dec 26, rolled (Nov expires 20 Oct)".
+ * Dec 2026, rolled (Nov expires 20 Oct)".
  */
 const COLUMN_MIN_PANE_WIDTH: Partial<Record<FuturesColumnId, number>> = {
   change: 100,
@@ -253,7 +253,7 @@ export function renderFuturesCell(
       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) };
+      return { text: formatPercentRaw(value), color: shownPriceColor(value, 2) };
     }
     case "prevClose":
       if (isBoardRowLoading(state)) return { text: "…", color: colors.textDim };

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

@@ -1,10 +1,12 @@
+import { logFailure } from "../../../utils/log-failure";
 import { apiClient } from "../../../api-client";
 import type { FuturesCurvePayload } from "../../../api-client/futures-curve";
 import { createPluginCache } from "../../../data/plugin-cache";
 import { isFuturesContractSpec } from "../../../market-data/futures-contract";
 import { loadCloudResource, unavailableOnServer } from "../shared/cloud-resource";
-import type { DataProvider } from "../../../types/data-provider";
-import { archivedFuturesCurve, curveLookbackDate, curveSpot, normalizeCurveRoot, unsupportedCurveRootMessage, withTradedExpirations, type CurveSpot } from "./model";
+import type { AssetDataProvider, DataProvider } from "../../../types/data-provider";
+import type { TimeRange } from "../../../time-series/range";
+import { archivedFuturesCurve, curveLookbackDate, curveSpot, normalizeCurveRoot, spotBarsFromHistory, unsupportedCurveRootMessage, withSettleChanges, withTradedExpirations, type CurveSpot, type SpotBar } from "./model";
 
 export const futuresCurveCache = createPluginCache<FuturesCurvePayload>({
   kind: "futures-curve", source: "gloom-cloud", schemaVersion: 1,
@@ -53,26 +55,31 @@ export function validateFuturesCurve(data: FuturesCurvePayload, root: string): F
   const slope = data.slope;
   if (![slope.value, slope.annualizedRollYield].every(finiteOrNull)
     || ![slope.percentile, slope.rollPercentile].every(rank) || !Number.isInteger(slope.samples) || slope.samples < 0
-    || slope.asOf !== null && !timestamp(slope.asOf)) throw new Error("The server returned an invalid futures spread");
+    || slope.asOf !== null && !timestamp(slope.asOf)
+    || slope.basis != null && slope.basis !== "last" && slope.basis !== "settle"
+    || slope.thinSymbol != null && typeof slope.thinSymbol !== "string") throw new Error("The server returned an invalid futures spread");
   return data;
 }
 
+/** A live curve as every reader takes it: expiring on last trading days, its changes against the settlement shown. */
+const liveCurve = (data: FuturesCurvePayload) => withSettleChanges(withTradedExpirations(data));
+
 export async function fetchFuturesCurve(root: string, client: Pick<typeof apiClient, "getCloudFuturesCurve"> = apiClient): Promise<FuturesCurvePayload> {
   const normalized = normalizeCurveRoot(root);
   if (!normalized) throw new Error(unsupportedCurveRootMessage(root));
-  try { return withTradedExpirations(validateFuturesCurve(await client.getCloudFuturesCurve(normalized), normalized)); }
+  try { return liveCurve(validateFuturesCurve(await client.getCloudFuturesCurve(normalized), normalized)); }
   catch (error) { throw unavailableOnServer(error, "Futures curves are not available yet."); }
 }
 
 export function getCachedFuturesCurve(root: string): FuturesCurvePayload | null {
   const cached = futuresCurveCache.get(root, { allowExpired: true });
   // The pane revalidates this copy on mount; only the source or a failed refresh makes it stale.
-  return cached?.data ? withTradedExpirations(cached.data) : null;
+  return cached?.data ? liveCurve(cached.data) : null;
 }
 
 export async function loadFuturesCurve(root: string, force = false): Promise<FuturesCurvePayload> {
   const { payload, stale, refreshError } = await loadCloudResource(futuresCurveCache, root, () => fetchFuturesCurve(root), { force });
-  return { ...withTradedExpirations(payload), stale: stale || payload.stale, gaps: [...payload.gaps, ...(refreshError ? [refreshError] : [])] };
+  return { ...liveCurve(payload), stale: stale || payload.stale, gaps: [...payload.gaps, ...(refreshError ? [refreshError] : [])] };
 }
 
 /** The archived curve on a past date with the curves a week and a month before it. */
@@ -83,8 +90,8 @@ export async function loadFuturesCurveAsOf(root: string, date: string,
   try {
     const [curve, week, month] = await Promise.all([
       client.getCloudFuturesCurveAsOf(normalized, date),
-      client.getCloudFuturesCurveAsOf(normalized, curveLookbackDate(date, 7)).catch(() => null),
-      client.getCloudFuturesCurveAsOf(normalized, curveLookbackDate(date, 30)).catch(() => null),
+      client.getCloudFuturesCurveAsOf(normalized, curveLookbackDate(date, 7)).catch(logFailure("futures-curve.client", "Load week comparison curve failed", null)),
+      client.getCloudFuturesCurveAsOf(normalized, curveLookbackDate(date, 30)).catch(logFailure("futures-curve.client", "Load month comparison curve failed", null)),
     ]);
     if (!curve || curve.root !== normalized || !Array.isArray(curve.contracts) || !Array.isArray(curve.gaps)
       || curve.contracts.some((row) => !row || typeof row.symbol !== "string" || !Number.isFinite(row.price)
@@ -101,5 +108,29 @@ export async function loadFuturesCurveAsOf(root: string, date: string,
  * A failed read is a missing spot, never a failed report: the curve stands without its basis.
  */
 export async function loadCurveSpot(symbol: string, provider: Pick<DataProvider, "getQuote">, now = Date.now()): Promise<CurveSpot> {
-  return curveSpot(symbol, await provider.getQuote(symbol, "").catch(() => null), now);
+  return curveSpot(symbol, await provider.getQuote(symbol, "").catch(logFailure("futures-curve.client", "Load curve spot quote failed", null)), now);
+}
+
+/** The last day of one-minute bars: the reach of a curve's trades a basis is read for, the far months' older ones aside. */
+const SPOT_BAR_RANGE: TimeRange = "1D";
+
+/**
+ * The spot pair's one-minute bars over the last day, read through the same
+ * history path the charts use, which the basis pairs each trade with by
+ * minute. Bars of any other size pair nothing, and a failed read has none:
+ * the curve stands without its basis, each blank saying why.
+ */
+export async function loadCurveSpotBars(symbol: string,
+  provider: Pick<AssetDataProvider, "getPriceHistoryForResolutionWithMetadata" | "getPriceHistoryForResolution">, force = false): Promise<SpotBar[]> {
+  const context = force ? { cacheMode: "refresh" as const } : undefined;
+  try {
+    if (provider.getPriceHistoryForResolutionWithMetadata) {
+      const history = await provider.getPriceHistoryForResolutionWithMetadata(symbol, "", SPOT_BAR_RANGE, "1m", context);
+      return history.resolution && history.resolution !== "1m" ? [] : spotBarsFromHistory(history.points);
+    }
+    return provider.getPriceHistoryForResolution
+      ? spotBarsFromHistory(await provider.getPriceHistoryForResolution(symbol, "", SPOT_BAR_RANGE, "1m", context)) : [];
+  } catch (error) {
+    return logFailure("futures-curve.client", "Load curve spot bars failed", [] as SpotBar[])(error);
+  }
 }

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

@@ -4,8 +4,8 @@ import type { HeadlessPaneColumn, HeadlessPaneDefinition, HeadlessPaneEntry, Hea
 import { formatPercentRaw } from "../../../utils/format";
 import { DATE_OPTION_EXAMPLES } from "../../../utils/calendar-date";
 import { newestReportTime, oldestReportTime } from "../../../utils/utc-time";
-import { fetchFuturesCurve, loadCurveSpot, loadFuturesCurveAsOf } from "./client";
-import { basisSpotSymbol, BASIS_CONVENTION, blankBasisNote, catalogueCurveUnit, curveAsOfDate, curveBasisPercent, curveBasisRows, curveChangeText, curveContractCode, curvePrice, curveRoundedPrice, curveSpotLabel, curveSpotSource, curveSpreadLabel, curveTimestamp, curveUnitLabel, normalizeCurveRoot, shortDatedBasisNote, thinContractCount, unsupportedCurveRootMessage, type ContractBasis } from "./model";
+import { fetchFuturesCurve, loadCurveSpot, loadCurveSpotBars, loadFuturesCurveAsOf } from "./client";
+import { basisSpotSymbol, BASIS_CONVENTION, blankBasisNote, catalogueCurveUnit, curveAsOfDate, curveBasisPercent, curveBasisRows, curveChangeText, curveContractCode, curvePrice, curveRoundedPrice, curveSpotSource, curveSpreadLabel, curveTimestamp, curveNoTradeSince, curveUnitLabel, noTradeChangeNote, normalizeCurveRoot, shortDatedBasisNote, thinSpreadNotice, unpairedContractCount, unsupportedCurveRootMessage, type ContractBasis } from "./model";
 import { COMMODITIES_VIEW_STATE } from "../commodities-energy/view-state";
 
 /** The root a report shows when none is given. */
@@ -22,6 +22,11 @@ const basisValue = (value: number | null) => value == null ? null : Number(value
  * every root. Prices and changes are at the root's tick precision. `price` is
  * the latest trade and `settlement` the exchange settlement for the curve's
  * settlement session (a past curve's settled rows have no separate trade).
+ * `change` is `price` less `settlement`; `noTradeSince` dates the settlement
+ * a contract has not traded since, whose change is therefore blank. A crypto
+ * root adds the basis: the spot in the minute of `price`'s trade and that
+ * minute (`spot`, `spotTime`), the fractional days from the trade to final
+ * settlement, and the premium and its yearly rate.
  */
 function contractRow(row: FuturesContract, data: FuturesCurvePayload, root: string, past: boolean, basis?: ContractBasis) {
   const price = (value: number | null | undefined) => curveRoundedPrice(value, root);
@@ -30,15 +35,21 @@ function contractRow(row: FuturesContract, data: FuturesCurvePayload, root: stri
     firstNotice: row.firstNotice ?? null, inDelivery: row.inDelivery ?? false,
     settlement: price(row.settlement), settlementDate: row.settlement != null ? data.settlementDate ?? null : null,
     price: past && row.settlement != null ? null : price(row.price), change: price(row.change),
+    noTradeSince: past ? null : curveNoTradeSince(row, data),
     asOf: row.asOf, stale: row.stale, volume: row.volume, openInterest: row.openInterest, percentile: rank(row.percentile),
     samples: row.samples, historyStart: row.historyStart, historyEnd: row.historyEnd,
     currency: row.currency, quoteUnit: curveUnitLabel(data) ?? row.quoteUnit, delayMinutes: row.delayMinutes,
-    ...(basis ? { vsSpotPct: basisValue(basis.vsSpotPct), annualisedBasisPct: basisValue(basis.annualisedBasisPct) } : {}),
+    ...(basis ? { spot: price(basis.spot), spotTime: basis.spotTime, daysToExpiry: basisValue(basis.daysToExpiry),
+      vsSpotPct: basisValue(basis.vsSpotPct), annualisedBasisPct: basisValue(basis.annualisedBasisPct) } : {}),
   };
 }
 
-/** The text table: what a hedge reads, in one order for every root; JSON keeps every field. */
-function contractColumns(root: string, settlementDate: string | null, options: { basis: boolean; last: boolean; notice: boolean }): HeadlessPaneColumn[] {
+/**
+ * The table: what a hedge reads, in one order for every root; JSON keeps every
+ * field. A crypto root's spot is the one each trade is read against; the
+ * export dates it, where the text leaves its minute to As Of UTC, the trade's.
+ */
+function contractColumns(root: string, settlementDate: string | null, options: { basis: boolean; last: boolean; notice: boolean; text?: boolean }): HeadlessPaneColumn[] {
   const price = (value: unknown) => typeof value === "number" ? curvePrice(value, root) : "--";
   const date = (value: unknown) => typeof value === "string" ? value : "--";
   return [
@@ -51,7 +62,10 @@ function contractColumns(root: string, settlementDate: string | null, options: {
     // A Cboe price is the settlement itself, with no separate last trade.
     ...options.last ? [{ key: "price", header: "Last", align: "right" as const, format: price }] : [],
     { key: "change", header: "Change", align: "right", format: (value) => typeof value === "number" ? curveChangeText(value, root) : "--" },
-    ...options.basis ? [{ key: "vsSpotPct", header: "Vs Spot", align: "right" as const, format: (value: unknown) => curveBasisPercent(typeof value === "number" ? value : null, 2) },
+    ...options.basis ? [{ key: "spot", header: "Spot", align: "right" as const, format: price },
+      ...options.text ? [] : [{ key: "spotTime", header: "Spot Time UTC", shrink: false, format: (value: unknown) => typeof value === "string" ? curveTimestamp(value) : "--" }],
+      { key: "vsSpotPct", header: "Vs Spot", align: "right" as const, format: (value: unknown) => curveBasisPercent(typeof value === "number" ? value : null, 2) },
+      { key: "daysToExpiry", header: "Days to Expiry", textHeader: "Days", align: "right" as const, format: (value: unknown) => typeof value === "number" ? value.toFixed(1) : "--" },
       { key: "annualisedBasisPct", header: "Ann Basis", align: "right" as const, format: (value: unknown) => curveBasisPercent(typeof value === "number" ? value : null, 1) }] : [],
     { key: "asOf", header: "As Of UTC", shrink: false, format: (value) => typeof value === "string" ? curveTimestamp(value) : "--" },
     { key: "openInterest", header: "Open Int", align: "right", format: (value) => typeof value === "number" ? value.toLocaleString("en-US") : "--" },
@@ -70,8 +84,9 @@ function fieldColumns(order: readonly string[], fields: object, formats: Record<
     .map((key) => ({ key, header: key, ...formats[key] ? { textFormat: formats[key] } : {} }));
 }
 
+// `basis` says which prices the value subtracts: two last trades made together, or the settlements of the session in `asOf`.
 const FRONT_SPREAD_FIELDS = ["label", "frontSymbol", "nextSymbol", "value", "annualizedRollYield", "percentile", "rollPercentile",
-  "samples", "historyStart", "historyEnd", "asOf", "state"];
+  "samples", "historyStart", "historyEnd", "asOf", "basis", "state", "thinSymbol"];
 const GHOST_FIELDS = ["symbol", "expiration", "price", "asOf"];
 /** The annualized roll yield reads as the percent it is (+32.36%); an export keeps the number. */
 const ROLL_YIELD_FORMAT = { annualizedRollYield: (value: unknown) => typeof value === "number" ? formatPercentRaw(value) : "--" };
@@ -93,7 +108,7 @@ function specEntries(data: FuturesCurvePayload): HeadlessPaneEntry[] {
 export const futuresCurveHeadless: HeadlessPaneDefinition<"bundle"> = {
   discovery: { aliases: ["CTM"], dataRequirements: ["Gloom Cloud futures curve endpoint"],
     limitations: ["Listed-contract catalogues can be incomplete.", "Ghosts and percentiles use the same listed contracts.", "Cboe VIX is daily settlement.",
-    "Ann Basis is simple actual/365 on the latest trade against the spot quote, and noisy under 30 days to expiry."],
+    "Ann Basis is simple actual/365, each last trade against spot in the same minute, and noisy under 7 days to expiry."],
     intents: ["futures basis trade", "cash and carry", "basis against spot"] },
   shape: "bundle", argument: { kind: "free-text", optional: true, placeholder: "root", description: "FUT root such as CL, ES, ZN or VX, or a CME crypto root (BTC, ETH, SOL, XRP). Defaults to ES." },
   // Only the pane reads the tab; the report always carries both.
@@ -106,23 +121,30 @@ export const futuresCurveHeadless: HeadlessPaneDefinition<"bundle"> = {
     const input = args.argument || DEFAULT_ROOT;
     const root = normalizeCurveRoot(input);
     if (!root) throw new Error(unsupportedCurveRootMessage(input));
-    const date = curveAsOfDate(args.options.date);
+    const date = curveAsOfDate(args.options.date, new Date(), "--date");
     // The archive keeps no spot history, so a past curve has no basis.
     const spotSymbol = date ? null : basisSpotSymbol(root);
     const now = Date.now();
-    const [data, spot] = await Promise.all([
+    // The quote names the spot and its feed; the one-minute bars price each trade's own minute.
+    const [data, spot, bars] = await Promise.all([
       date ? loadFuturesCurveAsOf(root, date, ctx.apiClient) : fetchFuturesCurve(root, ctx.apiClient),
       spotSymbol ? loadCurveSpot(spotSymbol, ctx.marketData, now) : null,
+      spotSymbol ? loadCurveSpotBars(spotSymbol, ctx.marketData, ctx.refresh === true) : null,
     ]);
-    const bases = spot ? curveBasisRows(data.contracts, spot) : null;
+    const bases = spot && bars ? curveBasisRows(data.contracts, bars) : null;
     const unit = curveUnitLabel(data);
     const terms = specEntries(data);
     const source = spot ? curveSpotSource(spot) : null;
     const notices = [...args.argument ? [] : [`Showing ${DEFAULT_ROOT}. Try fn CTM ${EXAMPLE_ROOT}.`],
-      ...spot ? [spot.status === "ok" ? `Basis against ${curveSpotLabel(spot, root, now)}${source ? ` (${source})` : ""}; not the CME reference rate.` : `Basis blank: ${spot.reason}.`] : []];
+      ...spot ? [`Basis against ${spot.symbol} spot in each last trade's own minute${source ? ` (${source})` : ""}; not the CME reference rate.`] : []];
     // The footnotes under the table: the convention, why a cell is blank, and where a short-dated rate is not to be trusted.
-    // Against a spot that is not usable every cell is blank for the spot's reason, which the notice above already gives.
-    const notes = spot && bases ? [BASIS_CONVENTION, ...spot.status === "ok" ? [blankBasisNote(data.contracts, bases), shortDatedBasisNote(data.contracts, bases, spot)].filter((note): note is string => !!note) : []] : [];
+    const basisNotes = bases ? [BASIS_CONVENTION, blankBasisNote(data.contracts, bases), shortDatedBasisNote(data.contracts, bases)]
+      .filter((note): note is string => !!note) : [];
+    // A blank Change says why, as a blank basis does; a past curve has no session change to blank.
+    const changeNote = date ? null : noTradeChangeNote(data.contracts, data);
+    const thinSpread = thinSpreadNotice(data);
+    const notes = [...thinSpread ? [`${thinSpread}.`] : [], ...changeNote ? [changeNote] : [], ...basisNotes];
+    const columnOptions = { basis: !!bases, last: data.source !== "cboe", notice: data.contracts.some((row) => row.firstNotice) };
     // Dated by the contracts' own quotes; the same-contract history rows are a year of context, not observations.
     const quoted = data.contracts.map((row) => row.asOf);
     const freshness: HeadlessPaneFreshness = date
@@ -132,8 +154,8 @@ export const futuresCurveHeadless: HeadlessPaneDefinition<"bundle"> = {
     return {
       freshness,
       sections: [
-        { title: "Contracts", columns: contractColumns(root, data.settlementDate ?? null,
-          { basis: !!spot, last: data.source !== "cboe", notice: data.contracts.some((row) => row.firstNotice) }),
+        { title: "Contracts", columns: contractColumns(root, data.settlementDate ?? null, columnOptions),
+          ...bases ? { textColumns: contractColumns(root, data.settlementDate ?? null, { ...columnOptions, text: true }) } : {},
           rows: data.contracts.map((row) => contractRow(row, data, root, !!date, bases?.get(row.symbol))) },
         { title: "Front spread", columns: fieldColumns(FRONT_SPREAD_FIELDS, data.slope, ROLL_YIELD_FORMAT), rows: [{ label: curveSpreadLabel(data.slope), ...data.slope, value: curveRoundedPrice(data.slope.value, root),
           annualizedRollYield: data.slope.annualizedRollYield == null ? null : Number(data.slope.annualizedRollYield.toFixed(2)),
@@ -144,7 +166,7 @@ export const futuresCurveHeadless: HeadlessPaneDefinition<"bundle"> = {
       ],
       errors: data.gaps,
       ...(notes.length ? { notes } : {}),
-      metadata: { ...data, quoteUnit: unit, ...(spot && bases ? { spot, basisBlankedThin: thinContractCount(bases.values()) } : {}), ...(args.argument ? {} : { defaultArgument: DEFAULT_ROOT }),
+      metadata: { ...data, quoteUnit: unit, ...(spot && bases ? { spot, basisBlankedUnpaired: unpairedContractCount(bases.values()) } : {}), ...(args.argument ? {} : { defaultArgument: DEFAULT_ROOT }),
         ...(notices.length ? { notices } : {}),
         complete: data.status === "available", percentileBasis: "Same-contract observations within one year; actual sample start/end retained" },
     };