gloomberb 0.16.0 → 0.16.2

package/src/plugins/builtin/earnings-ripple/pane.tsx

@@ -1,20 +1,25 @@
-import { useCallback, useMemo } from "react";
-import { DataTableView, EmptyState, PaneStatusBody, usePaneFooter, usePaneNoticeFooter,
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { DataTableView, EmptyState, PaneStatusBody, usePaneFooter, usePaneNoticeFooter, usePaneTabs,
   type DataTableCell, type DataTableColumn, type PaneHint } from "../../../components";
 import { usePaneRefreshKey } from "../../../components/data-table/table-pane";
+import { getTableWidth } from "../../../components/ui/table-layout";
 import { usePlanAccess } from "../../../api-client/plan-access";
 import { useAsyncResource, useAutoRefresh, usePaneSettingValue, usePluginAppActions, usePluginPaneState, useTickers } from "../../../public/react";
 import type { PaneProps } from "../../../types/plugin";
 import { Box } from "../../../ui";
 import { isUsListingExchange } from "../../../utils/exchanges";
+import { displayWidth } from "../../../utils/format";
 import { CLOUD_PLAN_KEY, useCloudUpgradeAction } from "../shared/cloud-upgrade";
+import { UpgradeLabel } from "../shared/locked-rows";
 import { useResearchCloudSession } from "../shared/research-cloud-session";
-import { cachedRippleSources, loadRipple } from "./client";
-import { revenueOwner, RIPPLE_DAYS, type RippleRow } from "./model";
+import { cachedRippleSources, loadRipple, rippleRouteSettings } from "./client";
+import { hopLabel, revenueOwner, RIPPLE_DAYS, type RippleRow, type SecondHopRow } from "./model";
 
-/** Calls per refresh stay bounded: one disclosure request per holding. */
+/** Calls per refresh stay bounded: one disclosure request per holding, plus one graph request per holding on the second hop. */
 const RIPPLE_HOLDINGS_LIMIT = 60;
 
+const TABS = [{ value: "direct", label: "1 hop" }, { value: "two-hop", label: "2 hops" }];
+
 const COLUMNS: DataTableColumn[] = [
   { id: "date", label: "Date", width: 11, align: "left" },
   { id: "timing", label: "Time", width: 5, align: "left" },
@@ -26,6 +31,67 @@ const COLUMNS: DataTableColumn[] = [
   { id: "holdingDate", label: "Holding reports", width: 16, align: "right" },
 ];
 
+const SECOND_HOP_COLUMNS: DataTableColumn[] = [
+  { id: "date", label: "Date", width: 10, align: "left" },
+  { id: "timing", label: "Time", width: 5, align: "left" },
+  { id: "company", label: "Reports", width: 14, flexGrow: 1, align: "left" },
+  { id: "link", label: "Link", width: 19, align: "left" },
+  { id: "via", label: "Via", width: 9, align: "left" },
+  { id: "holding", label: "Holding", width: 9, align: "left" },
+  { id: "shares", label: "Share per hop", width: 28, align: "left" },
+  { id: "move", label: "Avg move", width: 9, align: "right" },
+  { id: "holdingDate", label: "Holding reports", width: 16, align: "right" },
+];
+const HOP_SEPARATOR = " › ";
+
+/**
+ * Holding to via, then via to the company that reports. The first hop is
+ * padded with no-break spaces, which the desktop does not collapse.
+ */
+function shareText(row: SecondHopRow, firstHopWidth: number) {
+  const first = hopLabel(row.hops[0]);
+  return `${first}${"\u00a0".repeat(Math.max(0, firstHopWidth - displayWidth(first)))}${HOP_SEPARATOR}${hopLabel(row.hops[1])}`;
+}
+
+/**
+ * The 2 hops table at this width. The date, the company and the route (via,
+ * holding, every hop's share) always show, so the route never scrolls out of
+ * view; a pane too narrow for all of it clips the shares. What room is left
+ * goes to the rest, most needed first, each only if it fits: the link, the
+ * report time, a long via name in full, the average move, shares lined up so
+ * every second hop starts at the same place, and the holding's own report.
+ * `firstHopWidth` is what the first hop is padded to, 0 when not lined up.
+ */
+function secondHopLayout(width: number, rows: readonly SecondHopRow[]) {
+  const widest = (texts: readonly string[]) => Math.max(0, ...texts.map(displayWidth));
+  const firstHop = widest(rows.map((row) => hopLabel(row.hops[0])));
+  const shares = Math.min(44, Math.max(28, widest(rows.map((row) => shareText(row, 0)))));
+  const aligned = Math.min(44, Math.max(shares, firstHop + HOP_SEPARATOR.length + widest(rows.map((row) => hopLabel(row.hops[1])))));
+  const widths: Record<string, number> = { via: 9, shares };
+  let firstHopWidth = 0;
+  const shown = new Set(["date", "company", "via", "holding", "shares"]);
+  const columns = () => SECOND_HOP_COLUMNS.filter((column) => shown.has(column.id))
+    .map((column) => widths[column.id] ? { ...column, width: widths[column.id]! } : column);
+  // The vertical scrollbar takes a cell, including when the rows fit.
+  const room = () => width - 1 - getTableWidth(columns());
+  const fitted = widths.shares = Math.max(28, shares + Math.min(0, room()));
+  const extras: [add: () => void, undo: () => void][] = [
+    ...["link", "timing"].map((id): [() => void, () => void] => [() => shown.add(id), () => shown.delete(id)]),
+    [() => { widths.via = Math.min(18, Math.max(9, widest(rows.map((row) => row.via)))); }, () => { widths.via = 9; }],
+    [() => shown.add("move"), () => shown.delete("move")],
+    [() => { widths.shares = aligned; firstHopWidth = firstHop; }, () => { widths.shares = fitted; firstHopWidth = 0; }],
+    [() => shown.add("holdingDate"), () => shown.delete("holdingDate")],
+  ];
+  for (const [add, undo] of extras) {
+    add();
+    if (room() < 0) undo();
+  }
+  return { columns: columns(), firstHopWidth };
+}
+
+const move = (row: RippleRow | SecondHopRow): DataTableCell =>
+  ({ text: row.averageMove == null ? "--" : `±${(row.averageMove * 100).toFixed(1)}%`, value: row.averageMove });
+
 function renderCell(row: RippleRow, column: DataTableColumn): DataTableCell {
   switch (column.id) {
     case "date": return { text: row.date };
@@ -34,16 +100,34 @@ function renderCell(row: RippleRow, column: DataTableColumn): DataTableCell {
     case "link": return { text: row.link === "customer" ? "customer of" : "supplier to" };
     case "holding": return { text: row.holding };
     case "pct": return { text: `${row.pctOfRevenue}%${row.pctScope ? "*" : ""} of ${revenueOwner(row)}`, value: row.pctOfRevenue };
-    case "move": return { text: row.averageMove == null ? "--" : `±${(row.averageMove * 100).toFixed(1)}%`, value: row.averageMove };
+    case "move": return move(row);
+    default: return { text: row.holdingDate ?? "--" };
+  }
+}
+
+function renderSecondHopCell(row: SecondHopRow, column: DataTableColumn, firstHopWidth: number): DataTableCell {
+  switch (column.id) {
+    case "date": return { text: row.date };
+    case "timing": return { text: row.timing?.toUpperCase() ?? "--" };
+    case "company": return { text: `${row.company} ${row.companyName}` };
+    case "link": return { text: row.link === "customer" ? "customer's customer" : "supplier's supplier" };
+    case "via": return { text: row.via };
+    case "holding": return { text: row.holding };
+    case "shares": return { text: shareText(row, firstHopWidth), value: shareText(row, 0) };
+    case "move": return move(row);
     default: return { text: row.holdingDate ?? "--" };
   }
 }
 
 export function EarningsRipplePane({ width, height, focused }: PaneProps) {
   const [symbolsText] = usePaneSettingValue("symbols", "");
+  const [openingTab] = usePaneSettingValue("tab", "direct");
+  const [savedTab, setTab] = usePluginPaneState<string>("tab", openingTab);
+  const tab = savedTab === "two-hop" ? "two-hop" : "direct";
   const tickers = useTickers();
   const { createPaneFromTemplate } = usePluginAppActions();
   const [selectedId, setSelectedId] = usePluginPaneState<string | null>("selectedRow", null);
+  const [selectedSecondId, setSelectedSecondId] = usePluginPaneState<string | null>("selectedSecondHop", null);
   const session = useResearchCloudSession();
   const access = usePlanAccess();
   const accessKey = `${session.requestKey}:${access.hasProAccess ? "full" : "preview"}`;
@@ -58,46 +142,87 @@ export function EarningsRipplePane({ width, height, focused }: PaneProps) {
   }, [symbolsText, tickers]);
   const holdings = scope.holdings;
   const holdingsKey = holdings.join(",");
-  const loader = useCallback((force: boolean) => loadRipple(holdings, cachedRippleSources(accessKey, force)), [holdingsKey, accessKey]);
+  const secondHop = tab === "two-hop";
+  // A free account's graph stops at one hop, so it makes no graph requests and its second tab reuses the first load.
+  // Once a Pro account opens 2 hops the graph stays in the load, so going back and forth between tabs never reloads.
+  // A refresh on 1 hop reads the graphs from the cache instead of asking for them again.
+  const [graphOpened, setGraphOpened] = useState(false);
+  useEffect(() => { if (secondHop && access.hasProAccess) setGraphOpened(true); }, [secondHop, access.hasProAccess]);
+  const graphHop = access.hasProAccess && (secondHop || graphOpened);
+  const secondHopShown = useRef(secondHop);
+  secondHopShown.current = secondHop;
+  const loader = useCallback((force: boolean) => loadRipple(holdings,
+    cachedRippleSources(accessKey, force, !graphHop ? "off" : secondHopShown.current ? "load" : "cached"), undefined, { secondHop: graphHop }),
+  [holdingsKey, accessKey, graphHop]);
   const ripple = useAsyncResource(holdings.length ? loader : null);
   useAutoRefresh(ripple.updatedAt, ripple.load);
   usePaneRefreshKey(() => { void ripple.reload(); }, { focused });
+  const { strip, rows: tabRows } = usePaneTabs(holdings.length ? { tabs: TABS, activeValue: tab, onSelect: setTab, focused, dense: true } : null);
 
   const rows = ripple.data?.rows ?? [];
+  const second = secondHop ? ripple.data?.secondHop ?? null : null;
+  const secondRows = second?.rows ?? [];
   const selected = rows.find((row) => row.id === selectedId) ?? rows[0] ?? null;
+  const selectedSecond = secondRows.find((row) => row.id === selectedSecondId) ?? secondRows[0] ?? null;
+  const current = secondHop ? selectedSecond : selected;
   const failures = ripple.data?.failures ?? [];
   const truncated = ripple.data?.truncated ?? [];
+  const locked = secondHop && (!access.hasProAccess || !!second?.locked);
   const openUpgrade = useCloudUpgradeAction("ripl");
   usePaneNoticeFooter({ registrationId: "earnings-ripple-notices", focused, notices: [
     ...(scope.total > holdings.length ? [`Checking ${holdings.length} of ${scope.total} holdings${scope.named ? "" : ", positions first. Name tickers in pane settings to pick others"}`] : []),
     ...(failures.length ? [`No disclosures for ${failures.map((failure) => failure.symbol).join(", ")}`] : []),
-    ...(truncated.length ? [`Free preview: top three customers and suppliers for ${truncated.join(", ")}`] : []),
+    ...(!secondHop && truncated.length ? [`Free preview: top three customers and suppliers for ${truncated.join(", ")}`] : []),
+    ...(second?.failures.length ? [`No two-hop graph for ${second.failures.map((failure) => failure.symbol).join(", ")}`] : []),
+    // The graph returns at most 50 companies per direction, so a large holding's list can be cut short.
+    ...(second?.truncated.length ? [`Graph search capped for ${second.truncated.map((entry) => entry.symbol).join(", ")}; some companies two hops away may be missing`] : []),
   ] });
   const openSupply = useCallback((row: RippleRow) => createPaneFromTemplate("supply-chain-pane", { symbol: row.holding }), [createPaneFromTemplate]);
+  // SPLC's own table does not reach a company two hops away; its Path view shows the row's route.
+  const openRoute = useCallback((row: SecondHopRow) => createPaneFromTemplate("supply-chain-pane", { symbol: row.holding, values: rippleRouteSettings(row) }),
+    [createPaneFromTemplate]);
   usePaneFooter("earnings-ripple", () => {
     const hints: PaneHint[] = [
-      ...(selected ? [
-        { id: "supply", key: "s", label: "upply chain", onPress: () => openSupply(selected) },
-        { id: "earnings", key: "e", label: "arnings", onPress: () => createPaneFromTemplate("earnings-calendar-pane", { arg: selected.company }) },
-      ] : []),
-      ...(truncated.length ? [{ id: "upgrade", key: CLOUD_PLAN_KEY, label: "upgrade", title: "Upgrade to Pro", onPress: openUpgrade }] : []),
+      ...(secondHop && selectedSecond ? [{ id: "supply", key: "s", label: "upply chain", title: `Supply chain path from ${selectedSecond.holding} to ${selectedSecond.company}`,
+        onPress: () => openRoute(selectedSecond) }]
+        : !secondHop && selected ? [{ id: "supply", key: "s", label: "upply chain", onPress: () => openSupply(selected) }] : []),
+      ...(current ? [{ id: "earnings", key: "e", label: "arnings", onPress: () => createPaneFromTemplate("earnings-calendar-pane", { arg: current.company }) }] : []),
+      ...((secondHop ? locked : truncated.length) ? [{ id: "upgrade", key: CLOUD_PLAN_KEY, label: "upgrade", title: "Upgrade to Pro", onPress: openUpgrade }] : []),
     ];
     return { info: [
-      ...(ripple.loading ? [{ id: "loading", parts: [{ text: "loading disclosures", tone: "muted" as const }] }] : []),
+      ...(ripple.loading ? [{ id: "loading", parts: [{ text: secondHop && graphHop ? "loading supply chain graph" : "loading disclosures", tone: "muted" as const }] }] : []),
       ...(ripple.data?.stale ? [{ id: "stale", parts: [{ text: "stale", tone: "warning" as const }] }] : []),
     ], hints };
-  }, [ripple.loading, ripple.data?.stale, selected, openSupply, createPaneFromTemplate, truncated.length, openUpgrade]);
+  }, [ripple.loading, ripple.data?.stale, current, selected, selectedSecond, secondHop, graphHop, locked, openSupply, openRoute, createPaneFromTemplate, truncated.length, openUpgrade]);
 
+  const secondLayout = useMemo(() => secondHopLayout(width, secondRows), [width, secondRows]);
+  const firstHopWidth = secondLayout.firstHopWidth;
+  const renderSecondCell = useCallback((row: SecondHopRow, column: DataTableColumn) => renderSecondHopCell(row, column, firstHopWidth), [firstHopWidth]);
+  const windowMeta = () => [["window", `${ripple.data?.from} to ${ripple.data?.to}`]];
+  const bodyHeight = Math.max(3, height - tabRows);
   return <Box width={width} height={height} flexDirection="column" overflow="hidden">
+    {strip}
     {!holdings.length ? <EmptyState title="Add tickers to a portfolio or watchlist, or name them in pane settings." />
-      : <PaneStatusBody subject="earnings ripple" loading={ripple.loading && !ripple.data} error={!ripple.data ? ripple.error : null}
-        empty={!!ripple.data && !rows.length} emptyTitle={`No disclosed customer or supplier of these holdings reports in the next ${RIPPLE_DAYS} days.`}>
-        <DataTableView<RippleRow> focused={focused} columns={COLUMNS} items={rows} rootWidth={width} rootHeight={height}
-          getItemKey={(row) => row.id} emptyStateTitle="No reports." sortColumnId={null} sortDirection="asc"
-          selection={{ kind: "id", selectedId: selected?.id ?? null, getId: (row) => row.id, onChange: setSelectedId }}
-          onActivate={openSupply}
-          getExportMetadata={() => [["window", `${ripple.data?.from} to ${ripple.data?.to}`], ["revenue share", "percent of the seller's revenue, as its filing discloses"]]}
-          renderCell={renderCell} />
+      : secondHop && locked ? <Box paddingX={1} paddingTop={1}><EmptyState title="Companies two hops away need Gloom Pro."
+        actions={<UpgradeLabel text="Upgrade for two-hop supply chains" onPress={openUpgrade} role="ripple-upgrade" />} /></Box>
+      : <PaneStatusBody subject={secondHop ? "two-hop supply chains" : "earnings ripple"} loading={ripple.loading && (!ripple.data || (secondHop && !second))}
+        error={!ripple.data ? ripple.error : null}
+        empty={secondHop ? !!second && !secondRows.length : !!ripple.data && !rows.length}
+        emptyTitle={secondHop ? `No company two disclosed hops from these holdings reports in the next ${RIPPLE_DAYS} days.`
+          : `No disclosed customer or supplier of these holdings reports in the next ${RIPPLE_DAYS} days.`}>
+        {secondHop
+          ? <DataTableView<SecondHopRow> focused={focused} columns={secondLayout.columns} items={secondRows} rootWidth={width} rootHeight={bodyHeight}
+            getItemKey={(row) => row.id} emptyStateTitle="No reports." sortColumnId={null} sortDirection="asc"
+            selection={{ kind: "id", selectedId: selectedSecond?.id ?? null, getId: (row) => row.id, onChange: setSelectedSecondId }}
+            onActivate={openRoute}
+            getExportMetadata={() => [...windowMeta(), ["share per hop", "percent of the reporting company's revenue unless another basis is named, holding to via, then via to the company"]]}
+            renderCell={renderSecondCell} />
+          : <DataTableView<RippleRow> focused={focused} columns={COLUMNS} items={rows} rootWidth={width} rootHeight={bodyHeight}
+            getItemKey={(row) => row.id} emptyStateTitle="No reports." sortColumnId={null} sortDirection="asc"
+            selection={{ kind: "id", selectedId: selected?.id ?? null, getId: (row) => row.id, onChange: setSelectedId }}
+            onActivate={openSupply}
+            getExportMetadata={() => [...windowMeta(), ["revenue share", "percent of the seller's revenue, as its filing discloses"]]}
+            renderCell={renderCell} />}
       </PaneStatusBody>}
   </Box>;
 }

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

@@ -361,6 +361,7 @@ function EconCalendarPane({ focused, width, height }: PaneProps) {
 export const economicCalendarModule: PluginModule = {
   panes: [{
     id: "econ-calendar",
+    reportFreshness: { status: "not-a-feed", basis: "calendar" },
     name: "Economic Calendar",
     icon: "E",
     component: EconCalendarPane,

package/src/plugins/builtin/econ-statistics/headless.ts

@@ -123,6 +123,8 @@ export function projectStatsHeadlessBundle(
 
 export const econStatisticsHeadless: HeadlessPaneDefinition<"bundle"> = {
   shape: "bundle",
+  // Each row checks its own release schedule and says when it is stale.
+  freshness: { source: "FRED", status: "not-a-feed", basis: "published statistics" },
   argument: {
     kind: "free-text",
     placeholder: "statistic",

package/src/plugins/builtin/equity-screener/headless.ts

@@ -14,6 +14,7 @@ import {
 
 export const equityScreenerHeadless: HeadlessPaneDefinition<"bundle"> = {
   shape: "bundle",
+  freshness: { status: "not-a-feed", basis: "screener snapshot" },
   argument: { kind: "none" },
   options: [
     {
@@ -49,6 +50,7 @@ export const equityScreenerHeadless: HeadlessPaneDefinition<"bundle"> = {
     // Payload status also counts ordinary per-field sparsity; only generation
     // warnings are failures, and more pages are not an error.
     return {
+      freshness: { asOf: data.snapshot?.sourceNewestAt ?? null },
       complete: !data.nextCursor && data.warnings.length === 0,
       errors: data.warnings,
       sections: [

package/src/plugins/builtin/estimate-revisions/headless.ts

@@ -3,6 +3,7 @@ import { fetchEstimates } from "./client";
 import { estimateCurrent, periodLabel, pinnedEstimatePeriods } from "./model";
 export const estimateRevisionsHeadless: HeadlessPaneDefinition<"bundle"> = {
   shape: "bundle",
+  freshness: { status: "not-a-feed", basis: "analyst estimates" },
   argument: {
     kind: "ticker",
     placeholder: "ticker",

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

@@ -30,6 +30,7 @@ export const executivesModule: PluginModule = {
   panes: [
     {
       id: EXECUTIVES_PANE_ID,
+      reportFreshness: { source: "SEC EDGAR", status: "not-a-feed", basis: "proxy statements" },
       name: "Executives",
       icon: "X",
       component: ExecutivesPane,

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

@@ -5,7 +5,9 @@ import { DEFAULT_SCENARIO, parseCustomScenario, parseHoldings, TABS } from "./mo
 import { portfolioHoldings, watchlistHoldings } from "./holdings";
 
 export const exposureHeadless: HeadlessPaneDefinition<"bundle"> = {
-  shape: "bundle", argument: { kind: "free-text", optional: true, placeholder: "AAPL=60% NVDA=40%", description: "Tickers, signed NAV weights, PORT:<id>, or WATCH:<id>. Unweighted lists and watchlists use equal weights." },
+  shape: "bundle",
+  freshness: { status: "not-a-feed", basis: "company disclosures" },
+  argument: { kind: "free-text", optional: true, placeholder: "AAPL=60% NVDA=40%", description: "Tickers, signed NAV weights, PORT:<id>, or WATCH:<id>. Unweighted lists and watchlists use equal weights." },
   discovery: { aliases: ["EXPO"], dataRequirements: ["Gloom Cloud geographic revenue, disclosed supply chains, KPIs, guidance and credit disclosures", "Portfolio NAV for local PORT weights"],
     limitations: ["Pro: full holdings and up to four-hop paths; free: one holding, one hop", "Operating exposure estimates, never predicted stock returns", "Missing relationships and sensitivities remain unknown", "Basis and reporting period are kept separate"] },
   options: [

package/src/plugins/builtin/fear-greed/headless.ts

@@ -76,6 +76,8 @@ export function createFearGreedHeadless(
       return {
         ...projected,
         ...(result.refreshError ? { errors: [result.refreshError] } : {}),
+        // A cached index the refresh could not replace is stale; otherwise CNN's published reading.
+        freshness: { source: "CNN", status: result.stale ? "stale" : "not-a-feed", basis: "published index" },
         metadata: { fetchedAt: result.fetchedAt, stale: result.stale },
       };
     },

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

@@ -21,6 +21,7 @@ export const filingEventsModule: PluginModule = {
   panes: [
     {
       id: FILING_EVENTS_PANE_ID,
+      reportFreshness: { source: "SEC EDGAR", status: "not-a-feed", basis: "filed data" },
       name: "8-K Filings",
       icon: "K",
       component: FilingEventsPane,

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

@@ -2,7 +2,8 @@ import { apiClient } from "../../../api-client";
 import type { FuturesCurvePayload } from "../../../api-client/futures-curve";
 import { createPluginCache } from "../../../data/plugin-cache";
 import { loadCloudResource, unavailableOnServer } from "../shared/cloud-resource";
-import { archivedFuturesCurve, curveLookbackDate, normalizeCurveRoot } from "./model";
+import type { DataProvider } from "../../../types/data-provider";
+import { archivedFuturesCurve, curveLookbackDate, curveSpot, normalizeCurveRoot, unsupportedCurveRootMessage, type CurveSpot } from "./model";
 
 export const futuresCurveCache = createPluginCache<FuturesCurvePayload>({
   kind: "futures-curve", source: "gloom-cloud", schemaVersion: 1,
@@ -51,7 +52,7 @@ export function validateFuturesCurve(data: FuturesCurvePayload, root: string): F
 
 export async function fetchFuturesCurve(root: string, client: Pick<typeof apiClient, "getCloudFuturesCurve"> = apiClient): Promise<FuturesCurvePayload> {
   const normalized = normalizeCurveRoot(root);
-  if (!normalized) throw new Error(`Unsupported futures root: ${root}`);
+  if (!normalized) throw new Error(unsupportedCurveRootMessage(root));
   try { return validateFuturesCurve(await client.getCloudFuturesCurve(normalized), normalized); }
   catch (error) { throw unavailableOnServer(error, "Futures curves are not available yet."); }
 }
@@ -71,7 +72,7 @@ export async function loadFuturesCurve(root: string, force = false): Promise<Fut
 export async function loadFuturesCurveAsOf(root: string, date: string,
   client: Pick<typeof apiClient, "getCloudFuturesCurveAsOf"> = apiClient): Promise<FuturesCurvePayload> {
   const normalized = normalizeCurveRoot(root);
-  if (!normalized) throw new Error(`Unsupported futures root: ${root}`);
+  if (!normalized) throw new Error(unsupportedCurveRootMessage(root));
   try {
     const [curve, week, month] = await Promise.all([
       client.getCloudFuturesCurveAsOf(normalized, date),
@@ -85,3 +86,11 @@ export async function loadFuturesCurveAsOf(root: string, date: string,
     return archivedFuturesCurve(normalized, curve, { "1W": week, "1M": month }, new Date().toISOString());
   } catch (error) { throw unavailableOnServer(error, "Past futures curves are not available yet."); }
 }
+
+/**
+ * The spot behind a crypto curve's basis, read through the same quote path every pane uses.
+ * 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);
+}

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

@@ -1,35 +1,64 @@
-import type { HeadlessPaneDefinition } from "../../../types/plugin";
-import { fetchFuturesCurve, loadFuturesCurveAsOf } from "./client";
-import { curveAsOfDate, normalizeCurveRoot } from "./model";
+import type { HeadlessPaneDefinition, HeadlessPaneFreshness } from "../../../types/plugin";
+import { newestReportTime, oldestReportTime } from "../../../utils/utc-time";
+import { fetchFuturesCurve, loadCurveSpot, loadFuturesCurveAsOf } from "./client";
+import { basisSpotSymbol, contractBasis, curveAsOfDate, curveSpotLabel, normalizeCurveRoot, thinContractCount, unsupportedCurveRootMessage } from "./model";
+
+/** The root a report shows when none is given. */
+const DEFAULT_ROOT = "ES";
+const EXAMPLE_ROOT = "CL";
 
 /** Percentiles read as the pane shows them, a whole rank. */
 const rank = (value: number | null) => value == null ? null : Math.round(value);
+/** The basis fields are read to four decimals, finer than any cell shows. */
+const basisValue = (value: number | null) => value == null ? null : Number(value.toFixed(4));
 
 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"] },
-  shape: "bundle", argument: { kind: "free-text", optional: true, placeholder: "root", description: "FUT root such as CL, ES, ZN or VX. Defaults to ES." },
+  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.
   options: [{ key: "tab", description: "Curve or the full contract table.", type: "enum",
     values: [{ value: "curve" }, { value: "contracts", aliases: ["contract", "table"] }], defaultValue: "curve",
     pluginState: { pluginId: "market-overview", key: "tab" } },
   { key: "date", type: "string", settingKey: "asOfDate", description: "Past date (YYYY-MM-DD): the curve as the daily settlement archive held it, with the curves a week and a month before." }],
-  describe: (args) => `Futures curve ${args.argument || "ES"}`,
+  describe: (args) => `Futures curve ${args.argument || DEFAULT_ROOT}`,
   async load(args, ctx) {
-    const input = args.argument || "ES";
+    const input = args.argument || DEFAULT_ROOT;
     const root = normalizeCurveRoot(input);
-    if (!root) throw new Error(`Unsupported futures root: ${input}`);
+    if (!root) throw new Error(unsupportedCurveRootMessage(input));
     const date = curveAsOfDate(args.options.date);
-    const data = date ? await loadFuturesCurveAsOf(root, date, ctx.apiClient) : await fetchFuturesCurve(root, ctx.apiClient);
+    // 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([
+      date ? loadFuturesCurveAsOf(root, date, ctx.apiClient) : fetchFuturesCurve(root, ctx.apiClient),
+      spotSymbol ? loadCurveSpot(spotSymbol, ctx.marketData, now) : null,
+    ]);
+    const bases = spot ? data.contracts.map((row) => contractBasis(row, spot)) : [];
+    const notices = [...args.argument ? [] : [`Showing ${DEFAULT_ROOT}. Try fn CTM ${EXAMPLE_ROOT}.`],
+      ...spot ? [spot.status === "ok" ? `Basis against ${curveSpotLabel(spot, root, now)}.` : `Basis blank: ${spot.reason}.`] : []];
+    // 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
+      ? { status: "not-a-feed", basis: "settlement archive", asOf: date }
+      : { ...(data.source === "cboe" ? { source: "Cboe", status: "not-a-feed", basis: "daily settlement", cadence: "daily" } as const : {}),
+        asOf: newestReportTime(quoted), oldest: oldestReportTime(quoted) };
     return {
+      freshness,
       sections: [
-        { title: "Contracts", rows: data.contracts.map((row) => ({ ...row, percentile: rank(row.percentile) })) },
+        { title: "Contracts", rows: data.contracts.map((row, index) => {
+          const basis = bases[index];
+          return { ...row, percentile: rank(row.percentile),
+            ...(basis ? { vsSpotPct: basisValue(basis.vsSpotPct), annualisedBasisPct: basisValue(basis.annualisedBasisPct) } : {}) };
+        }) },
         { title: "Front spread", rows: [{ ...data.slope, annualizedRollYield: data.slope.annualizedRollYield == null ? null : Number(data.slope.annualizedRollYield.toFixed(2)),
           percentile: rank(data.slope.percentile), rollPercentile: rank(data.slope.rollPercentile) }] },
         ...data.ghosts.map((ghost) => ({ title: `${ghost.label} same-contract history`, rows: ghost.points.map((point) => ({ ...point })) })),
       ],
       errors: data.gaps,
-      metadata: { ...data, complete: data.status === "available", percentileBasis: "Same-contract observations within one year; actual sample start/end retained" },
+      metadata: { ...data, ...(spot ? { spot, basisBlankedThin: thinContractCount(bases) } : {}), ...(args.argument ? {} : { defaultArgument: DEFAULT_ROOT }),
+        ...(notices.length ? { notices } : {}),
+        complete: data.status === "available", percentileBasis: "Same-contract observations within one year; actual sample start/end retained" },
     };
   },
 };

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

@@ -1,7 +1,7 @@
 import type { PluginModule } from "../plugin-module";
 import { futuresCurveCache } from "./client";
 import { futuresCurveHeadless } from "./headless";
-import { CURVE_HORIZONS, CURVE_ROOTS, DEFAULT_CURVE_HORIZON, normalizeCurveRoot } from "./model";
+import { CURVE_HORIZONS, CURVE_ROOTS, curveRootForTicker, DEFAULT_CURVE_HORIZON, normalizeCurveRoot } from "./model";
 import { FuturesCurvePane } from "./pane";
 
 export const futuresCurveModule: PluginModule = {
@@ -17,14 +17,14 @@ export const futuresCurveModule: PluginModule = {
     }),
   }],
   paneTemplates: [{ id: "futures-curve-pane", paneId: "futures-curve", label: "Futures Curve",
-    description: "Listed futures contracts, historical curves, roll yield and open interest including VIX futures.",
+    description: "Listed futures contracts, historical curves, roll yield and open interest including VIX and CME crypto futures.",
     keywords: ["ctm", "futures", "curve", "contango", "backwardation", "roll", "vix"],
     shortcut: { prefix: "CTM", aliases: ["CT"], argKind: "text", argPlaceholder: "root", argOptional: true,
       argOptions: () => CURVE_ROOTS },
     headless: futuresCurveHeadless,
     createInstance: (context, options) => {
       const input = options?.arg?.trim();
-      const root = input ? normalizeCurveRoot(input) : normalizeCurveRoot(context.activeTicker) ?? "ES";
+      const root = input ? normalizeCurveRoot(input) : curveRootForTicker(context.activeTicker) ?? "ES";
       return { title: `CTM ${root ?? input}`, params: { root: root ?? input ?? "ES" }, placement: "floating" };
     },
   }],