gloomberb 0.19.1 → 0.19.3

package/src/plugins/builtin/executives/data.ts

@@ -3,7 +3,7 @@ import {
   type CloudProxyStatementListPayload,
   type CloudProxyStatementPayload,
 } from "../../../api-client";
-import { ApiRequestError, isPermanentClientError } from "../../../api-client/errors";
+import { ApiRequestError, isPermanentClientError, isTransientFailure } from "../../../api-client/errors";
 import type { IssuerListingParams } from "../../../api-client/paths";
 import type { PluginPersistence } from "../../../types/plugin";
 import { secListingKey } from "../../../utils/sec";
@@ -46,6 +46,8 @@ interface ProxyResult<T> {
   /** Null is an explicit 404, not a transient failure or access denial. */
   data: T | null;
   fetchedAt: number | null;
+  /** Its refresh failed and the copy saved at this time (ms) answered instead. */
+  savedAt?: number;
   refreshError?: string;
 }
 type ActiveRequest<T> = { store: PluginPersistence | null; promise: Promise<ProxyResult<T>> };
@@ -105,11 +107,14 @@ function loadCached<T>(
       }
       throw error;
     }
+    // A saved copy answers only for a failure asking again may get past, not for a reply that fails validation.
+    if (!isTransientFailure(error)) throw error;
     const fallback = store?.getResource<T>(kind, key, { ...options, allowExpired: true });
     if (!fallback || tierOf(fallback.value) !== tier) throw error;
     return {
       data: fallback.value,
       fetchedAt: fallback.fetchedAt,
+      savedAt: fallback.fetchedAt,
       refreshError: (error instanceof Error ? error.message : String(error)).trim() || "Request failed",
     };
   }).finally(() => { if (active.get(activeKey) === request) active.delete(activeKey); });

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

@@ -8,12 +8,12 @@ import {
   DataTableView,
   EmptyState, FigureList, PaneStatusBody, Prose, QueryBar, READING_WIDTH, SectionHeading,
   usePaneFooter,
-  usePaneNoticeFooter,
   type DataTableCell,
   type DataTableColumn,
   type PaneFooterSegment,
   type PaneHint,
 } from "../../../components";
+import { savedCopyFooterInfo } from "../../../components/layout/pane/footer";
 import { useAsyncResource } from "../../../react/async-resource";
 import { usePaneStateValue } from "../../../state/app/context";
 import { colors, getChartIndicatorColor } from "../../../theme/colors";
@@ -45,13 +45,6 @@ import {
 
 export const EXECUTIVES_PANE_ID = "executives";
 
-function retainedDataNotice(subject: string, error: string, fetchedAt: number | null): string {
-  const retrieved = new Date(fetchedAt ?? Number.NaN);
-  const age = Number.isFinite(retrieved.getTime())
-    ? `retrieved ${retrieved.toISOString()}` : "with unavailable retrieval time";
-  return `${subject} refresh failed: ${error}. Retained data ${age}.`;
-}
-
 const PAY_PARTS: Array<{ key: keyof CloudExecutiveRowPayload; label: string }> =
   [
     { key: "salary", label: "Salary" },
@@ -301,18 +294,10 @@ function ExecutiveResearch({ ticker, listing, tier, focused, width, nested, guar
   // The free preview: each executive's total pay; the breakdown and earlier years are Pro.
   const preview = statement?.access === "preview" || list.data?.data?.access === "preview";
   const loading = list.loading || detail.loading;
-  const listError = list.error ?? list.data?.refreshError;
-  const statementError = detail.error ?? detail.data?.refreshError;
-  usePaneNoticeFooter({
-    registrationId: `${EXECUTIVES_PANE_ID}:data-notices`,
-    notices: [
-      list.data?.data && listError
-        ? retainedDataNotice("Proxy list", listError, list.data.fetchedAt) : null,
-      detail.data?.data && statementError
-        ? retainedDataNotice(`${year} proxy`, statementError, detail.data.fetchedAt) : null,
-    ].filter((notice): notice is string => notice !== null),
-    focused,
-  });
+  // A copy saved earlier answering a failed refresh says when it was saved, in the footer every pane uses;
+  // a failed refresh with only what is on screen says why. Without anything shown, the body says it.
+  const listError = list.data?.data ? list.error ?? (list.data.savedAt == null ? list.data.refreshError : null) ?? null : null;
+  const statementError = detail.data?.data ? detail.error ?? (detail.data.savedAt == null ? detail.data.refreshError : null) ?? null : null;
   const refresh = useCallback(() => {
     void list.reload();
     if (year !== null) void detail.reload();
@@ -338,6 +323,9 @@ function ExecutiveResearch({ ticker, listing, tier, focused, width, nested, guar
     const info: PaneFooterSegment[] = [];
     if (loading)
       info.push({ id: "loading", parts: [{ text: "loading", tone: "muted" }] });
+    if (listError) info.push({ id: "list-error", parts: [{ text: `Proxy list: ${listError}`, tone: "warning" }] });
+    if (statementError) info.push({ id: "statement-error", parts: [{ text: `${year} proxy: ${statementError}`, tone: "warning" }] });
+    info.push(...savedCopyFooterInfo([list.data?.data ? list.data.savedAt : null, statement ? detail.data?.savedAt : null]));
     if (statement) {
       info.push({
         id: "filed",
@@ -351,7 +339,7 @@ function ExecutiveResearch({ ticker, listing, tier, focused, width, nested, guar
     if (yearHint) hints.push(yearHint);
     if (preview) hints.push({ id: "upgrade", key: CLOUD_PLAN_KEY, label: "upgrade", title: "Upgrade to Pro", onPress: openUpgrade });
     return { info, hints };
-  }, [loading, statement, openFiling, yearHint, preview, openUpgrade]);
+  }, [loading, listError, statementError, year, list.data, detail.data, statement, openFiling, yearHint, preview, openUpgrade]);
 
   const figures = useMemo(
     () => (statement ? figuresOf(statement) : []),

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

@@ -1,5 +1,6 @@
 import type { ExposureHolding } from "../../../api-client/exposure";
 import type { DataProvider } from "../../../types/data-provider";
+import type { Quote } from "../../../types/financials";
 import type { Portfolio, TickerRecord } from "../../../types/ticker";
 import { publicTickerKey } from "../../../utils/exchanges";
 import { resolveCurrencyUnit } from "../../../utils/currency-units";
@@ -7,8 +8,25 @@ import { convertCurrency } from "../../../utils/format";
 import { logFailure } from "../../../utils/log-failure";
 import { getPortfolioPositionMetrics, getPortfolioQuoteDisplay, resolvePortfolioMarketValue } from "../../../portfolio/position-metrics";
 
+/**
+ * Every position's quote: one batch where the provider has one, else one
+ * request per position, all at once. A position without a quote is null.
+ */
+async function positionQuotes(positions: TickerRecord[], market: Pick<DataProvider, "getQuote" | "getQuotesBatch">): Promise<Array<Quote | null>> {
+  const failed = logFailure("exposure.holdings", "Load portfolio holding quote failed", null);
+  if (market.getQuotesBatch) {
+    const targets = positions.map((ticker) => ({ symbol: ticker.metadata.ticker, exchange: ticker.metadata.exchange, surface: "portfolio" as const }));
+    const results = await market.getQuotesBatch(targets).catch((error: unknown) => {
+      failed(error);
+      return [];
+    });
+    return positions.map((_, index) => results[index]?.quote ?? null);
+  }
+  return Promise.all(positions.map((ticker) => market.getQuote(ticker.metadata.ticker, ticker.metadata.exchange).catch(failed)));
+}
+
 /** Explicit NAV preserves cash, shorts and leverage; net holdings are never used as NAV. */
-export async function portfolioHoldings(portfolio: Portfolio, tickers: TickerRecord[], nav: number, market: Pick<DataProvider, "getQuote" | "getExchangeRate">): Promise<ExposureHolding[]> {
+export async function portfolioHoldings(portfolio: Portfolio, tickers: TickerRecord[], nav: number, market: Pick<DataProvider, "getQuote" | "getQuotesBatch" | "getExchangeRate">): Promise<ExposureHolding[]> {
   if (!Number.isFinite(nav) || nav <= 0) throw new Error(`Enter positive NAV in ${portfolio.currency} for ${portfolio.name}.`);
   const positions = tickers.filter(t => t.metadata.positions.some(p => p.portfolio === portfolio.id && p.shares !== 0));
   if (!positions.length) throw new Error("The selected portfolio has no positions.");
@@ -21,25 +39,29 @@ export async function portfolioHoldings(portfolio: Portfolio, tickers: TickerRec
     t.metadata.positions.filter(p => p.portfolio === portfolio.id).forEach(p => { if (p.currency) currencies.add(p.currency); });
   }
   const rates = new Map<string, number>([["USD", 1]]);
-  const majorRates = new Map<string, number>([["USD", 1]]);
+  // One request per major currency, however many of its units (GBP, GBp) ask at once.
+  const majorRates = new Map<string, Promise<number>>([["USD", Promise.resolve(1)]]);
   const ensureRate = async (rawCurrency: string) => {
     const unit = resolveCurrencyUnit(rawCurrency);
     if (!unit.currency) throw new Error("Portfolio currency is missing.");
-    let rate = majorRates.get(unit.currency);
-    if (rate === undefined) {
-      rate = await market.getExchangeRate(unit.currency);
-      if (!Number.isFinite(rate) || rate <= 0) throw new Error(`FX unavailable for ${unit.currency}; weights were not estimated.`);
-      majorRates.set(unit.currency, rate);
+    const major = unit.currency;
+    let pending = majorRates.get(major);
+    if (!pending) {
+      pending = market.getExchangeRate(major).then((rate) => {
+        if (!Number.isFinite(rate) || rate <= 0) throw new Error(`FX unavailable for ${major}; weights were not estimated.`);
+        return rate;
+      });
+      majorRates.set(major, pending);
     }
-    rates.set(rawCurrency, rate / unit.divisor);
+    rates.set(rawCurrency, (await pending) / unit.divisor);
   };
-  for (const currency of currencies) await ensureRate(currency);
+  const [quotes] = await Promise.all([positionQuotes(positions, market), Promise.all([...currencies].map(ensureRate))]);
+  // A quote in a currency the positions did not name.
+  await Promise.all([...new Set(quotes.flatMap((quote) => quote?.currency && !rates.has(quote.currency) ? [quote.currency] : []))].map(ensureRate));
   const holdings: ExposureHolding[] = [];
-  for (const ticker of positions) {
-    const quote = await market.getQuote(ticker.metadata.ticker, ticker.metadata.exchange)
-      .catch(logFailure("exposure.holdings", "Load portfolio holding quote failed", null));
+  for (const [index, ticker] of positions.entries()) {
+    const quote = quotes[index] ?? null;
     const currency = quote?.currency || ticker.metadata.currency;
-    if (!rates.has(currency)) await ensureRate(currency);
     const metrics = getPortfolioPositionMetrics(ticker, portfolio.id, currency, {
       currency: portfolio.currency, convert: (value, from) => convertCurrency(value, from, portfolio.currency, rates),
     }, quote);

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

@@ -2,7 +2,6 @@ import type { PaneTemplateContext, ShortcutArgError } from "../../../types/plugi
 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;
 
@@ -29,7 +28,7 @@ function unknownSourceArg(arg: string, context: PaneTemplateContext): ShortcutAr
 }
 
 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,
+  panes: [{ id: "exposure", name: "Exposure", icon: "E", get component(): typeof import("./pane").ExposurePane { const { ExposurePane } = require("./pane"); return 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.",

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

@@ -35,6 +35,10 @@ export type FearGreedCacheEntry = {
 export interface FearGreedLoadResult extends FearGreedCacheEntry {
   /** Set when the network failed and cached data was served instead. */
   refreshError?: string;
+  /** `stale-fallback` when a saved copy answered a failed refresh. */
+  source?: "cache" | "network" | "stale-fallback";
+  /** The failure a `stale-fallback` copy answered. */
+  error?: unknown;
 }
 
 const cache = createPluginCache<FearGreedData, PersistedFearGreedData>({

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

@@ -0,0 +1,44 @@
+import { CLI_COMMAND_GROUPS } from "../../../cli/help";
+import { rowsFreshness } from "../../../cli/freshness";
+import { humanizeCliKey } from "../../../cli/result";
+import type { CliCommandDef } from "../../../types/plugin";
+import { loadFearGreed } from "./cache";
+
+const SCORE_KEYS = new Set(["score", "previousClose", "previousWeek", "previousMonth", "previousYear"]);
+/** A score to a tenth of a point (17.9); a missing one leaves its cell empty, as before. */
+const scoreTenths = (value: unknown) => typeof value === "number" && Number.isFinite(value) ? value.toFixed(1) : "";
+
+// Without the pane cache attached, this fetches a fresh reading for the command.
+export const fearGreedCliCommand: CliCommandDef = {
+  name: "fear-greed",
+  description: "Fetch CNN Fear & Greed gauge data",
+  help: { group: CLI_COMMAND_GROUPS.markets },
+  async execute(_args, ctx) {
+    const { data, stale } = await loadFearGreed(ctx.cliOptions.refresh);
+    const rows = [{
+      score: data.overall.score,
+      rating: data.overall.rating,
+      updatedAt: data.overall.updatedAt?.toISOString() ?? "",
+      previousClose: data.overall.previousClose,
+      previousWeek: data.overall.previousWeek,
+      previousMonth: data.overall.previousMonth,
+      previousYear: data.overall.previousYear,
+    }];
+    ctx.printResult({
+      data: rows,
+      // Exports cite CNN's reading as `fn FNG` does; the text stays the row alone.
+      exportFreshness: rowsFreshness(rows, { source: "CNN", status: stale ? "stale" : "not-a-feed", basis: "published index" }),
+      metadata: {
+        indicators: data.indicators.map((indicator) => ({
+          id: indicator.definition.id,
+          score: indicator.score,
+          rating: indicator.rating,
+        })),
+      },
+    }, {
+      // Scores read to a tenth of a point on the text table; exports keep every digit.
+      textColumns: Object.keys(rows[0]!).map((key) => ({ key, header: humanizeCliKey(key),
+        ...(SCORE_KEYS.has(key) ? { align: "right" as const, format: scoreTenths } : {}) })),
+    });
+  },
+};

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

@@ -1,26 +1,15 @@
-import { CLI_COMMAND_GROUPS } from "../../../cli/help";
-import { rowsFreshness } from "../../../cli/freshness";
-import { humanizeCliKey } from "../../../cli/result";
+import { fearGreedPluginMeta } from "../builtin-plugin-meta";
+import { fearGreedCliCommand } from "./cli";
 import type { GloomPlugin } from "../../../types/plugin";
 import {
   attachFearGreedPersistence,
-  loadFearGreed,
   resetFearGreedPersistence,
 } from "./cache";
-import { FearGreedPane } from "./pane";
 import { fearGreedHeadless } from "./headless";
 import { FEAR_GREED_SERIES } from "./series";
 
-const SCORE_KEYS = new Set(["score", "previousClose", "previousWeek", "previousMonth", "previousYear"]);
-/** A score to a tenth of a point (17.9); a missing one leaves its cell empty, as before. */
-const scoreTenths = (value: unknown) => typeof value === "number" && Number.isFinite(value) ? value.toFixed(1) : "";
-
 export const fearGreedPlugin: GloomPlugin = {
-  id: "fear-greed",
-  name: "Fear & Greed",
-  version: "1.0.0",
-  description: "CNN Fear & Greed index with the seven indicator charts",
-  toggleable: true,
+  ...fearGreedPluginMeta,
 
   // One JSON endpoint over HTTPS, so every renderer. CNN sends no CORS
   // headers and wants a Referer, which is why the host is declared: the web
@@ -44,7 +33,7 @@ export const fearGreedPlugin: GloomPlugin = {
       id: "fear-greed",
       name: "Fear & Greed",
       icon: "G",
-      component: FearGreedPane,
+      get component(): typeof import("./pane").FearGreedPane { const { FearGreedPane } = require("./pane"); return FearGreedPane; },
       defaultPosition: "right",
       defaultMode: "floating",
       defaultFloatingSize: { width: 110, height: 36 },
@@ -63,42 +52,5 @@ export const fearGreedPlugin: GloomPlugin = {
     },
   ],
 
-  // `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: [
-    {
-      name: "fear-greed",
-      description: "Fetch CNN Fear & Greed gauge data",
-      help: { group: CLI_COMMAND_GROUPS.markets },
-      async execute(_args, ctx) {
-        const { data, stale } = await loadFearGreed(ctx.cliOptions.refresh);
-        const rows = [{
-          score: data.overall.score,
-          rating: data.overall.rating,
-          updatedAt: data.overall.updatedAt?.toISOString() ?? "",
-          previousClose: data.overall.previousClose,
-          previousWeek: data.overall.previousWeek,
-          previousMonth: data.overall.previousMonth,
-          previousYear: data.overall.previousYear,
-        }];
-        ctx.printResult({
-          data: rows,
-          // Exports cite CNN's reading as `fn FNG` does; the text stays the row alone.
-          exportFreshness: rowsFreshness(rows, { source: "CNN", status: stale ? "stale" : "not-a-feed", basis: "published index" }),
-          metadata: {
-            indicators: data.indicators.map((indicator) => ({
-              id: indicator.definition.id,
-              score: indicator.score,
-              rating: indicator.rating,
-            })),
-          },
-        }, {
-          // Scores read to a tenth of a point on the text table; exports keep every digit.
-          textColumns: Object.keys(rows[0]!).map((key) => ({ key, header: humanizeCliKey(key),
-            ...(SCORE_KEYS.has(key) ? { align: "right" as const, format: scoreTenths } : {}) })),
-        });
-      },
-    },
-  ],
+  cliCommands: [fearGreedCliCommand],
 };

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

@@ -8,6 +8,7 @@ import {
   usePaneStatusFooter,
   type StatItem,
 } from "../../../components";
+import { ageFooterSegment } from "../../../components/layout/pane/footer";
 import { usePaneRefreshKey } from "../../../components/data-table/table-pane";
 import { useAsyncResource } from "../../../react/async-resource";
 import type { PaneProps } from "../../../types/plugin";
@@ -61,7 +62,7 @@ export function FearGreedPane({ paneId, focused, width, height }: PaneProps) {
       ],
     }] : []),
     ...(stale ? [{ id: "stale", parts: [{ text: "stale", tone: "warning" as const }] }] : []),
-    ...(updatedAgo ? [{ id: "age", parts: [{ text: `updated ${updatedAgo}`, tone: "value" as const }] }] : []),
+    ...(updatedAgo ? [ageFooterSegment(updatedAgo, { id: "age", verb: "updated", tone: "value" })] : []),
   ], [data, stale, updatedAgo]);
   usePaneStatusFooter({ registrationId: paneId, loading, error, info: footerInfo });
 

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

@@ -1,5 +1,6 @@
 import type { SeriesDefinition, SeriesLoadResult, SeriesPoint } from "../../../series/types";
-import { cachedSeriesWarning } from "../shared/series-warning";
+import { savedCopyForTransientFailure } from "../../../data/plugin-cache";
+import { cachedSeriesNote } from "../shared/series-warning";
 import { loadFearGreed } from "./cache";
 import type { FearGreedData } from "./data";
 
@@ -30,9 +31,10 @@ function series(id: string, name: string, unit: string, read: Reading, tags: rea
     tags: ["fear and greed", ...tags],
     refreshMs: REFRESH_MS,
     load: async (): Promise<SeriesLoadResult> => {
-      const result = await loadFearGreed();
-      const warning = cachedSeriesWarning(result);
-      return { points: read(result.data), ...(warning ? { warning } : {}) };
+      // A saved copy answers only a failure asking again may get past; a refusal is the chart's error.
+      const result = savedCopyForTransientFailure(await loadFearGreed());
+      return { points: read(result.data),
+        ...cachedSeriesNote({ ...result, ...(result.source === "stale-fallback" ? { savedAt: result.fetchedAt } : {}) }) };
     },
   };
 }

package/src/plugins/builtin/fixed-income/index.tsx

@@ -1,14 +1,13 @@
 import type { PluginModule } from "../plugin-module";
 import { treasuryAuctionsSettings } from "../treasury-auctions";
 import { FIXED_INCOME_PANE_ID } from "./model";
-import { FixedIncomePane } from "./pane";
 
 export const fixedIncomeModule: PluginModule = {
   panes: [{
     id: FIXED_INCOME_PANE_ID,
     name: "Fixed Income",
     icon: "B",
-    component: FixedIncomePane,
+    get component(): typeof import("./pane").FixedIncomePane { const { FixedIncomePane } = require("./pane"); return FixedIncomePane; },
     defaultPosition: "right",
     defaultMode: "floating",
     defaultFloatingSize: { width: 116, height: 32 },

package/src/plugins/builtin/futures/board-reads.ts

@@ -0,0 +1,25 @@
+import { createConcurrencyLimiter } from "../../../utils/concurrency";
+
+/**
+ * The board's contract histories (use-front-returns) and contract terms
+ * (use-board-terms) share one limit of twelve reads at a time, across both and
+ * every board open: seventy-odd rows load in about a second without the two
+ * crowding out each other or the quotes.
+ */
+const BOARD_READ_LIMIT = 12;
+
+export const boardRead = createConcurrencyLimiter(BOARD_READ_LIMIT);
+
+/**
+ * Reads that reach a source sending reads asked together as batch requests
+ * skip that limit: asked all at once, the API client sends a board's rows
+ * sixteen a request. This bound only keeps a runaway caller in check.
+ */
+const BOARD_BATCHED_READ_LIMIT = 200;
+
+const boardBatchedRead = createConcurrencyLimiter(BOARD_BATCHED_READ_LIMIT);
+
+/** The gate for the board's reads: twelve at a time, unless they go out in batch requests. */
+export function boardReadGate(batched: boolean): typeof boardRead {
+  return batched ? boardBatchedRead : boardRead;
+}

package/src/plugins/builtin/futures/coalesced-bump.ts

@@ -0,0 +1,44 @@
+/** How long reads landing one after another are gathered into one redraw. */
+const LANDING_GATHER_MS = 100;
+
+/**
+ * A redraw for reads that land one by one (a board's seventy contract
+ * histories): the first landing redraws at once, and those in the next
+ * `LANDING_GATHER_MS` are drawn together when it ends, so the board redraws a
+ * few times rather than once per read. `flush` draws what is waiting at once
+ * (the last read landed) and `cancel` drops it (the board moved on).
+ */
+export function coalescedBump(redraw: () => void, gatherMs = LANDING_GATHER_MS) {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let waiting = false;
+  const gather = () => {
+    timer = setTimeout(() => {
+      timer = undefined;
+      if (!waiting) return;
+      waiting = false;
+      redraw();
+      gather();
+    }, gatherMs);
+  };
+  const cancel = () => {
+    clearTimeout(timer);
+    timer = undefined;
+    waiting = false;
+  };
+  return {
+    bump() {
+      if (timer !== undefined) {
+        waiting = true;
+        return;
+      }
+      redraw();
+      gather();
+    },
+    flush() {
+      const draw = waiting;
+      cancel();
+      if (draw) redraw();
+    },
+    cancel,
+  };
+}

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

@@ -25,9 +25,11 @@ import type { PluginModule } from "../plugin-module";
 import { FUTURES_SERIES } from "./series";
 import { useLiveStreamingSetting } from "../../../state/hooks/live-streaming";
 import { quoteObservation } from "../shared/report-freshness";
+import { useQuoteDelayFooter } from "../shared/cloud-upgrade";
 import {
   boardErrorMessage,
   boardHeadlineQuote,
+  boardQuotes,
   quoteBoardFooterInfo,
   quoteBoardStatus,
   useQuoteBoard,
@@ -46,6 +48,7 @@ import {
   DEFAULT_FUTURES_SORT,
   effectiveCollapsedSectors,
   FUTURES_RETURN_COLUMNS,
+  futuresNoMatchFailure,
   futuresRowId,
   type FuturesColumnId,
   type FuturesSortPreference,
@@ -255,15 +258,26 @@ export function FuturesPane({ focused, width, height }: PaneProps) {
     },
   } : null);
 
+  // `fn FUT natgas` with no contract to list fails with what to type instead, not the board's empty labels.
+  const noMatch = !!dataProvider && !!searchQuery.trim() && !rows.some((row) => row.type === "row");
+  useRemoteUiNode(noMatch ? {
+    role: "report-failure",
+    label: "No matching contracts",
+    getMetadata: () => futuresNoMatchFailure(searchQuery),
+  } : null);
+
   const status = quoteBoardStatus(listedQuotes);
   const errorMessage = boardErrorMessage(listedQuotes);
   // Every load came back empty: a board of dashes reads as broken, so the
   // body says so once and offers a retry. One quote is enough to keep rows.
   const noQuotes = !!dataProvider && listedQuotes.size > 0 && status.unavailable === listedQuotes.size;
+  // Signed out or free, the contracts' quotes are delayed ones.
+  const quoteDelay = useQuoteDelayFooter(boardQuotes(listedQuotes), "futures-delay");
   usePaneFooter(FUTURES_PANE_ID, () => {
     if (noQuotes) return { info: [], hints: [] };
     const info: PaneFooterSegment[] = quoteBoardFooterInfo(status);
     if (errorMessage) info.push({ id: "reason", parts: [{ text: errorMessage, tone: "warning" }] });
+    if (quoteDelay) info.push(quoteDelay);
     return {
       info,
       hints: [{ id: "search", key: "/", label: "search", onPress: focusSearch }],
@@ -272,6 +286,7 @@ export function FuturesPane({ focused, width, height }: PaneProps) {
     errorMessage,
     focusSearch,
     noQuotes,
+    quoteDelay,
     status.latestTs,
     status.loading,
     status.savedAt,

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

@@ -149,9 +149,23 @@ function matchesFuturesSearch(contract: FuturesContract, query: string, quote?:
     || contract.name.toLowerCase().includes(normalized)
     || futuresContractName(contract, quote).toLowerCase().includes(normalized)
     || contract.symbol.toLowerCase().includes(normalized)
+    // Everyday names the board's own does not hold: natgas is Natural Gas.
+    || (contract.aliases ?? []).some((alias) => alias.includes(normalized))
   );
 }
 
+/**
+ * Why `fn FUT urea` lists nothing, for a search no contract matches: what
+ * to type instead, never the board's own buttons ("Clear search.").
+ */
+export function futuresNoMatchFailure(query: string): { message: string; details: string } {
+  return {
+    message: `No futures contract matches "${query.trim()}".`,
+    details: "Try a code such as NG, CL or GC, or a name such as natural gas or gold: gloom fn FUT NG."
+      + " Other boards: gloom fn FUT --tab inventories, positioning or crops.",
+  };
+}
+
 export const FUTURES_RETURN_COLUMNS: Readonly<Partial<Record<FuturesColumnId, FuturesReturnHorizon>>> = {
   return1w: "1W",
   return1m: "1M",

package/src/plugins/builtin/futures/use-board-terms.ts

@@ -5,6 +5,9 @@ import type { FuturesContract } from "../../../market-data/futures-board";
 import { createTtlCache } from "../../../data/ttl-cache";
 import { loadFuturesContractTerms } from "../../../market-data/futures-contract";
 import { logFailure } from "../../../utils/log-failure";
+import { coalescedBump } from "./coalesced-bump";
+import { apiClient } from "../../../api-client";
+import { boardReadGate } from "./board-reads";
 
 interface FuturesTermsState {
   /** The row's terms are still being asked for. */
@@ -23,8 +26,6 @@ const TERMS_TTL_MS = 30 * 60_000;
  * once a minute, not once a tick.
  */
 const TERMS_RETRY_MS = 60_000;
-/** Forty-odd rows open at once; a few requests at a time keep the board's quotes first. */
-const TERMS_CONCURRENCY = 4;
 
 /**
  * Null when the server has no terms for the symbol, which is an answer and is
@@ -33,18 +34,18 @@ const TERMS_CONCURRENCY = 4;
  */
 const termsCache = createTtlCache<FuturesContractTermsPayload | null>({ ttlMs: TERMS_TTL_MS, rejectionMs: TERMS_RETRY_MS });
 
-async function readTerms(symbol: string): Promise<FuturesContractTermsPayload | null> {
+async function readTerms(symbol: string, batch: boolean): Promise<FuturesContractTermsPayload | null> {
   try {
-    return await loadFuturesContractTerms(symbol);
+    return await loadFuturesContractTerms(symbol, apiClient, { batch });
   } catch (error) {
     if (error instanceof ApiRequestError && error.status === 404) return null;
     throw error;
   }
 }
 
-/** Whether the row has an answer; false when the read failed. */
-function loadTerms(symbol: string): Promise<boolean> {
-  return termsCache.load(symbol, () => readTerms(symbol))
+/** Whether the row has an answer; false when the read failed. `batch`: asked with every other row's, in batch requests. */
+function loadTerms(symbol: string, batch: boolean): Promise<boolean> {
+  return termsCache.load(symbol, () => readTerms(symbol, batch))
     .then(() => true, logFailure("futures", "Read a futures row's contract terms failed", false));
 }
 
@@ -67,18 +68,24 @@ export function useFuturesBoardTerms(contracts: readonly FuturesContract[], enab
     let cancelled = false;
     let failed = false;
     let retryTimer: ReturnType<typeof setTimeout> | undefined;
-    const worker = async () => {
-      for (let symbol = queue.shift(); symbol; symbol = queue.shift()) {
-        if (!await loadTerms(symbol)) failed = true;
-        if (!cancelled) setVersion((current) => current + 1);
-      }
-    };
-    void Promise.all(Array.from({ length: Math.min(TERMS_CONCURRENCY, queue.length) }, worker)).then(() => {
+    const landed = coalescedBump(() => {
+      if (!cancelled) setVersion((current) => current + 1);
+    });
+    // Twelve reads at a time, shared with the rows' histories (`boardRead`), or all at once while the client
+    // sends terms in batch requests; a board that moved on skips its turn.
+    const batch = apiClient.batchesReads("futures-terms");
+    const read = boardReadGate(batch);
+    void Promise.all(queue.map((symbol) => read(async () => {
+      if (cancelled) return;
+      if (!await loadTerms(symbol, batch)) failed = true;
+      landed.bump();
+    }))).then(() => {
+      landed.flush();
       if (failed && !cancelled) retryTimer = setTimeout(() => setRetry((current) => current + 1), TERMS_RETRY_MS);
     });
     return () => {
       cancelled = true;
-      queue.length = 0;
+      landed.cancel();
       clearTimeout(retryTimer);
     };
   }, [enabled, symbolKey, retry]);