@gloom-sh/terminal 0.19.2 → 0.19.3

package/src/plugins/builtin/dividend-yield/ranking-reads.ts

@@ -0,0 +1,73 @@
+import { ApiRequestError } from "../../../api-client/errors";
+import type { FundBondFacts } from "../../../api-client/fund-facts";
+import { createConcurrencyLimiter } from "../../../utils/concurrency";
+import type { DividendData } from "./client";
+import type { DividendRankingEntry } from "./ranking";
+
+/** Tickers one ranking reads at most: `fn DVD`, `shot DVD` and the DVD pane alike. */
+export const MAX_RANKED_SYMBOLS = 25;
+/** Tickers read at once across every ranking in the process, so a ranking never floods Gloom Cloud. */
+const RANKING_CONCURRENCY = 4;
+/** A rate-limited read waits what the server asks, a second when it names nothing, and never longer than this. */
+const RATE_LIMIT_WAIT_MS = 1_000;
+const RATE_LIMIT_WAIT_MAX_MS = 5_000;
+
+/** The one gate every ranking's reads pass through. */
+const rankingReads = createConcurrencyLimiter(RANKING_CONCURRENCY);
+
+/** How a ranking reads one ticker. */
+export interface DividendRankingReads {
+  loadData(symbol: string): Promise<DividendData>;
+  /** A fund's bond facts, null for any other listing. It never rejects: without them the fund ranks as before. */
+  loadBond?(symbol: string): Promise<FundBondFacts | null>;
+}
+
+interface RankingReadOptions {
+  /** How the one retry of a rate-limited read waits; tests pass their own. */
+  sleep?: (ms: number) => Promise<void>;
+}
+
+const wait = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));
+
+/** The 429 a read was refused with, wrapped or not; null for any other failure. */
+function rateLimited(error: unknown): ApiRequestError | null {
+  for (let current: unknown = error, depth = 0; current && typeof current === "object" && depth < 4; depth += 1) {
+    if (current instanceof ApiRequestError) return current.status === 429 ? current : null;
+    current = (current as { cause?: unknown }).cause;
+  }
+  return null;
+}
+
+/** A read Gloom Cloud refused with 429, asked once more after the wait it names; a second refusal is the row's error. */
+async function retryRateLimitedOnce<T>(read: () => Promise<T>, sleep: (ms: number) => Promise<void>): Promise<T> {
+  try {
+    return await read();
+  } catch (error) {
+    const limited = rateLimited(error);
+    if (!limited) throw error;
+    await sleep(Math.min(Math.max(0, limited.retryAfterMs ?? RATE_LIMIT_WAIT_MS), RATE_LIMIT_WAIT_MAX_MS));
+    return read();
+  }
+}
+
+/**
+ * Each ticker of a ranking, read into its entry in the order given: the first
+ * 25, at most four at once through the gate every ranking shares, so `fn`,
+ * `shot` and any open DVD pane together never ask Gloom Cloud for more. A
+ * ticker that fails keeps its row with its error, after one more try when it
+ * was rate limited.
+ */
+export function readDividendRanking(
+  symbols: readonly string[],
+  reads: DividendRankingReads,
+  { sleep = wait }: RankingReadOptions = {},
+): Promise<DividendRankingEntry[]> {
+  return Promise.all(symbols.slice(0, MAX_RANKED_SYMBOLS).map((symbol) => rankingReads(async (): Promise<DividendRankingEntry> => {
+    const bond = reads.loadBond?.(symbol) ?? null;
+    try {
+      return { symbol, data: await retryRateLimitedOnce(() => reads.loadData(symbol), sleep), bond: await bond };
+    } catch (error) {
+      return { symbol, error: error instanceof Error ? error.message : String(error) };
+    }
+  })));
+}

package/src/plugins/builtin/dividend-yield/ranking-view.tsx

@@ -0,0 +1,163 @@
+import { useCallback, useMemo, useRef } from "react";
+import { apiClient } from "../../../api-client";
+import {
+  DataTableView,
+  PaneStatusBody,
+  usePaneFooter,
+  type DataTableCell,
+  type DataTableColumn,
+} from "../../../components";
+import { loadingErrorFooterInfo, usePaneRefreshKey } from "../../../components/data-table/table-pane";
+import { useAsyncResource } from "../../../react/async-resource";
+import { useAssetData, usePluginAppActions, usePluginPaneState } from "../../../public/react";
+import { useAppSelector } from "../../../state/app/context";
+import { resolveSavedInstrument } from "../../../tickers/saved-instrument";
+import { colors } from "../../../theme/colors";
+import type { HeadlessPaneColumn } from "../../../types/headless";
+import { TextAttributes } from "../../../ui";
+import { compareSortValues, nextHeaderSort, type SortComparableValue, type SortPreference } from "../../../utils/sort-values";
+import { SignInWall } from "../cloud/auth-actions";
+import { isCloudSessionRequired, useResearchCloudSession } from "../shared/research-cloud-session";
+import { fetchDividendData } from "./client";
+import { dividendRankingReads, type DividendReadContext } from "./headless";
+import { projectDividendRanking, type DividendRankingEntry } from "./ranking";
+import { readDividendRanking, type DividendRankingReads } from "./ranking-reads";
+
+/** The pane setting a ranking of several tickers is opened with (`shot DVD KO JNJ`). */
+export const RANK_SYMBOLS_SETTING = "rankSymbols";
+
+/** The tickers a pane ranks, from its settings: two or more, or none for a pane of one ticker. */
+export function rankSymbolsOf(settings: Readonly<Record<string, unknown>> | undefined): string[] {
+  const value = settings?.[RANK_SYMBOLS_SETTING];
+  const symbols = Array.isArray(value) ? value.filter((entry): entry is string => typeof entry === "string" && entry.trim() !== "") : [];
+  return symbols.length > 1 ? symbols : [];
+}
+
+/** How wide each of the ranking's columns starts, in characters; a column not named fits its header. */
+const COLUMN_WIDTHS: Record<string, number> = { symbol: 10, lastExDate: 10, payDate: 10, note: 24, yieldBasis: 24 };
+/** Growth figures read by their sign, as the single-ticker pane colors them. */
+const SIGNED_COLUMNS = new Set(["growth1Y", "growth3Y"]);
+const DATE_COLUMNS = new Set(["lastExDate", "payDate", "secYieldAsOf"]);
+
+type RankingRow = Record<string, unknown> & { symbol: string };
+type RankingColumn = DataTableColumn & { source: HeadlessPaneColumn };
+/**
+ * The order `fn DVD` ranks in: trailing yield, highest first. A stable sort
+ * of the ranked rows keeps a ticker not read last among those with no yield.
+ */
+const RANKED_ORDER: SortPreference<string> = { columnId: "trailingYield", direction: "desc" };
+
+function sortRankingRows(rows: RankingRow[], sort: SortPreference<string>): RankingRow[] {
+  const { columnId, direction } = sort;
+  if (!columnId) return rows;
+  return [...rows].sort((left, right) => compareSortValues(left[columnId] as SortComparableValue, right[columnId] as SortComparableValue, direction));
+}
+
+/** Signed out, every read is refused for the account: the pane shows the wall the single-ticker DVD shows. */
+function needsSignIn(entries: readonly DividendRankingEntry[] | null): boolean {
+  return !!entries?.length && entries.every((entry) => !("data" in entry))
+    && entries.some((entry) => "error" in entry && isCloudSessionRequired(entry.error));
+}
+
+function cellText(column: HeadlessPaneColumn, row: RankingRow): string {
+  const value = row[column.key];
+  const format = column.textFormat ?? column.format;
+  return format ? format(value, row) : value == null ? "" : String(value);
+}
+
+/**
+ * Several tickers ranked by trailing yield in one table, with the columns and
+ * figures `fn DVD A B C` prints; Enter opens a ticker's own dividend pane.
+ */
+export function DividendRankingView({ symbols, focused, width, height, loadData }: {
+  symbols: readonly string[];
+  focused: boolean;
+  width: number;
+  height: number;
+  /** One listing's history alone, without the quote `fn DVD` prices it at; for tests. */
+  loadData?: typeof fetchDividendData;
+}) {
+  const key = symbols.join(",");
+  const marketData = useAssetData();
+  const cloudSession = useResearchCloudSession();
+  // A key reads the listing `fn DVD` reads for it: its own venue, else the one its saved ticker is on.
+  // Through a ref, so a quote that updates a saved ticker does not read the ranking again.
+  const tickers = useAppSelector((state) => state.tickers);
+  const tickersRef = useRef(tickers);
+  tickersRef.current = tickers;
+  const reads = useMemo<DividendRankingReads>(() => {
+    const resolveInstrument = (typed: string) => resolveSavedInstrument(typed, (saved) => tickersRef.current.get(saved));
+    // `fn DVD`'s own reads: the listing's quote for the price, the stated forward rate, a fund's bond facts.
+    if (marketData && !loadData) return dividendRankingReads({ marketData, apiClient, resolveInstrument } satisfies DividendReadContext);
+    const history = loadData ?? fetchDividendData;
+    return { loadData: async (typed) => {
+      const listing = await resolveInstrument(typed);
+      return history(listing.symbol, null, listing.exchange ?? "");
+    } };
+  }, [loadData, marketData]);
+  // A sign-in or a verified email reads the ranking again.
+  const request = useCallback(() => readDividendRanking(key.split(","), reads), [key, reads, cloudSession.requestKey]);
+  const resource = useAsyncResource(request, { keepPreviousData: true });
+  const authWall = needsSignIn(resource.data);
+  const { createPaneFromTemplate } = usePluginAppActions();
+  const section = useMemo(() => resource.data ? projectDividendRanking(resource.data).sections[0] ?? null : null, [resource.data]);
+  const [sort, setSort] = usePluginPaneState<SortPreference<string>>("dividend-ranking:sort", RANKED_ORDER);
+  const rows = useMemo(() => sortRankingRows((section?.rows ?? []) as RankingRow[], sort), [section, sort]);
+  const columns = useMemo<RankingColumn[]>(() => (section?.columns ?? []).map((column) => ({
+    id: column.key,
+    label: column.header,
+    width: Math.max(column.header.length, COLUMN_WIDTHS[column.key] ?? 0),
+    align: column.align === "right" ? "right" : "left",
+    source: column,
+  })), [section]);
+  const [selected, setSelected] = usePluginPaneState<string | null>("dividend-ranking:selected", null);
+
+  usePaneFooter("dividend-ranking", () => ({
+    info: loadingErrorFooterInfo(resource.loading && !!resource.data, resource.data ? null : resource.error),
+  }), [resource.loading, resource.data, resource.error]);
+  usePaneRefreshKey(resource.reload, { focused, enabled: !authWall });
+
+  const renderCell = useCallback((row: RankingRow, column: RankingColumn): DataTableCell => {
+    const text = cellText(column.source, row);
+    const value = row[column.id];
+    if (column.id === "symbol") return { text, color: colors.textBright, attributes: TextAttributes.BOLD };
+    if (column.id === "note") return { text, color: colors.warning };
+    if (DATE_COLUMNS.has(column.id) || column.id === "yieldBasis") return { text, color: colors.textDim };
+    if (SIGNED_COLUMNS.has(column.id) && typeof value === "number") {
+      return { text, color: value > 0 ? colors.positive : value < 0 ? colors.negative : colors.text };
+    }
+    return { text };
+  }, []);
+
+  if (authWall) return <SignInWall placement="dividend-yield-signin" action="view dividend history" needsVerification={cloudSession.needsVerification} />;
+
+  return (
+    <PaneStatusBody
+      subject="dividends"
+      loading={!resource.data && resource.loading}
+      error={!resource.data ? resource.error : null}
+      empty={false}
+    >
+      <DataTableView<RankingRow, RankingColumn>
+        focused={focused}
+        columns={columns}
+        items={rows}
+        rootWidth={width}
+        rootHeight={height}
+        freezeFirstColumn
+        sortColumnId={sort.columnId}
+        sortDirection={sort.direction}
+        // A third click on a column returns to the ranking.
+        onHeaderClick={(id) => setSort((current) => nextHeaderSort(current, id, {
+          firstDirection: id === "symbol" || id === "note" || id === "yieldBasis" ? "asc" : "desc", resetTo: RANKED_ORDER }))}
+        getItemKey={(row) => row.symbol}
+        selection={{ kind: "id", selectedId: rows.some((row) => row.symbol === selected) ? selected! : rows[0]?.symbol ?? "",
+          getId: (row) => row.symbol, onChange: (id) => setSelected(id) }}
+        onActivate={(row) => createPaneFromTemplate("dividend-yield-pane", { symbol: row.symbol })}
+        renderCell={renderCell}
+        selectedTextOverridesCellColor
+        emptyStateTitle="No tickers"
+      />
+    </PaneStatusBody>
+  );
+}

package/src/plugins/builtin/dividend-yield/ranking.ts

@@ -146,7 +146,7 @@ const RANKING_COLUMNS: HeadlessPaneColumn[] = [
   { key: "growth3Y", header: "3Y CAGR", align: "right", format: growth("growth3Y"),
     description: "Compound annual growth of trailing twelve-month cash per share over three years; n/a when either year holds fewer payments than the cadence pays." },
   { key: "lastExDate", header: "Last ex", format: day, shrink: false },
-  { key: "payDate", header: "Pay date", format: day, shrink: false, stackPriority: 2,
+  { key: "payDate", header: "Next pay", format: day, shrink: false, stackPriority: 2,
     description: "Pay date of the next declared distribution; past distributions carry ex-dates only." },
 ];
 

package/src/plugins/builtin/dividend-yield/view.ts

@@ -1,4 +1,7 @@
 import type { DividendPayment, GrowthPayments } from "./types";
+import { formatCurrency } from "../../../utils/format";
+import { currencyMinorDigits } from "../../../market-data/market/format";
+import { resolveCurrencyUnit } from "../../../utils/currency-units";
 import type { ProjectedChartPoint } from "../../../components/chart/core/data";
 import { calendarMonthsBefore } from "../../../utils/calendar-date";
 import { NOT_MEANINGFUL, formatPriceEarnings } from "../../../utils/price-earnings";
@@ -6,6 +9,24 @@ import { LATE_GRACE_DAYS, trailingCashAt, type TrailingPayments } from "../../..
 
 const DAY = 24 * 60 * 60 * 1000;
 
+/**
+ * A cash amount the listing pays as a conversion of the currency its company
+ * declares in (`DividendData.convertedFrom`), to two decimals of the unit its
+ * source states it in: pence stay pence (BP's 6.4059p is `6.41p`, never
+ * `£0.06`), and a major unit keeps its currency's decimals (`ZAR 0.87`, not
+ * `ZAR 0.866087`), as the conversion gives it no more.
+ */
+export function formatConvertedAmount(value: number | null | undefined, currency: string, subUnit?: string): string {
+  if (value == null || !Number.isFinite(value)) return "—";
+  const unit = subUnit ? resolveCurrencyUnit(subUnit) : null;
+  return unit && unit.divisor !== 1 && unit.currency === currency
+    ? formatCurrency(value * unit.divisor, subUnit!, 2)
+    : formatCurrency(value, currency, currencyMinorDigits(currency));
+}
+
+/** What a converted amount says beside it: `converted from USD`. */
+export const convertedFromText = (currency: string) => `converted from ${currency}`;
+
 export function formatDividendYield(value: number | null): string {
   return value != null && Number.isFinite(value) ? `${(value * 100).toFixed(2)}%` : "—";
 }

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

@@ -6,7 +6,6 @@ import type { PaneTemplateContext, PaneTemplateCreateOptions } from "../../../ty
 import { getSharedRegistry } from "../../registry";
 import { buildRegistryHelpIndex } from "../help/function-index";
 import type { PluginModule } from "../plugin-module";
-import { DocsPane } from "./pane";
 import { docsTopicForArgument, docsTopicForPane } from "./targets";
 
 /** One reader: every request lands in the same pane, on top of its history. */
@@ -38,8 +37,8 @@ export const docsModule: PluginModule = {
       id: "docs",
       name: "Docs",
       icon: "?",
-      component: DocsPane,
-      reportFreshness: { status: "not-a-feed", basis: "documentation" },
+      get component(): typeof import("./pane").DocsPane { const { DocsPane } = require("./pane"); return DocsPane; },
+      reportFreshness: { status: "not-a-feed", basis: "documentation", local: true },
       // A page reads whole in a report, not cut at the first screen.
       shotFitsReader: true,
       defaultPosition: "right",

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

@@ -49,6 +49,14 @@ function seasonalRows(row: DoeSeriesRow) {
     fiveYearLow: level(min), fiveYearAverage: level(average), fiveYearHigh: level(max) }));
 }
 
+/** Words for natural gas storage, which `NGS` reads, rather than a series of the petroleum tables. */
+const GAS_WORDS = new Set(["ngs", "ng", "gas", "natgas", "naturalgas", "natgasstorage", "naturalgasstorage", "gasstorage", "storage", "workinggas"]);
+
+/** Whether `DOE` was given a word for gas storage (`NGS`, `natural gas`) rather than a series. */
+export function doeGasWord(argument: string): boolean {
+  return GAS_WORDS.has(argument.toLowerCase().replace(/[^a-z]/g, ""));
+}
+
 /** `DOE` reads every tab unless one is named; `NGS` starts on gas storage; a series argument adds its year. */
 export function doeHeadless(defaultTab: DoeTab | "all"): HeadlessPaneDefinition<"bundle"> {
   return {
@@ -77,10 +85,13 @@ export function doeHeadless(defaultTab: DoeTab | "all"): HeadlessPaneDefinition<
           nextExpectedAt: oldestReportTime(reports.map((report) => report.nextReleaseAt)) };
       };
       const argument = Array.isArray(args.argument) ? args.argument.join(" ") : args.argument;
-      if (argument) {
+      // `DOE NGS` or `DOE natural gas` is the gas storage tables `NGS` opens on, and says so; `NGS gas` is them already.
+      const gasWord = argument ? doeGasWord(argument) : false;
+      const ngs = defaultTab === "gas";
+      if (argument && !gasWord) {
         const option = doeSeriesOption(argument);
         const row = option ? data.series.find((entry) => entry.id === option.value) : null;
-        if (!row) throw new Error("Use a series such as cushing, gasoline, distillate or east");
+        if (!row) throw new Error(`Use a series such as cushing, gasoline, distillate or east${ngs ? "" : "; for gas storage, gloom fn NGS"}`);
         return {
           sections: [
             { title: doeHeaderLine(doeReport(data, row.tab)) ?? row.label, columns: SUMMARY_COLUMNS, rows: [reportRow(row)] },
@@ -95,8 +106,10 @@ export function doeHeadless(defaultTab: DoeTab | "all"): HeadlessPaneDefinition<
           metadata: { ...data, series: [row], complete: data.status === "available" },
         };
       }
-      const tabs = args.options.tab === "all" || args.options.tab == null ? DOE_TABS.map(({ value }) => value) : [doeTab(args.options.tab)];
+      const tabs = gasWord ? ["gas" as const]
+        : args.options.tab === "all" || args.options.tab == null ? DOE_TABS.map(({ value }) => value) : [doeTab(args.options.tab)];
       return {
+        ...(gasWord && !ngs ? { warnings: [`Gas storage is its own function: gloom fn NGS (one region: gloom fn NGS east)`] } : {}),
         sections: tabs.map((tab) => ({
           title: `${DOE_TABS.find((entry) => entry.value === tab)!.label}${doeHeaderLine(doeReport(data, tab)) ? `: ${doeHeaderLine(doeReport(data, tab))}` : ""}`,
           columns: SUMMARY_COLUMNS,

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

@@ -4,15 +4,16 @@ import type { PluginModule } from "../plugin-module";
 import { DOE_CATALOG_SERIES } from "./series";
 import { doeBoardCache } from "./client";
 import { doePriceCache } from "./prices";
-import { doeHeadless } from "./headless";
+import { doeGasWord, doeHeadless } from "./headless";
 import { DOE_SERIES_OPTIONS, doeSeriesOption } from "./model";
-import { DoePane } from "./pane";
 
 /** Opens on a tab, or on the series typed after the mnemonic and its tab. */
 function doeInstance(tab: DoeTab, options?: PaneTemplateCreateOptions): PaneTemplateInstanceConfig {
   const input = options?.arg?.trim();
+  // `DOE NGS` or `DOE natural gas` opens on gas storage, as `NGS` does.
+  if (input && doeGasWord(input)) return { placement: "floating", settings: { tab: "gas" } };
   const series = doeSeriesOption(input);
-  if (input && !series) throw new Error("Use a series such as cushing, gasoline, distillate or east");
+  if (input && !series) throw new Error(`Use a series such as cushing, gasoline, distillate or east${tab === "gas" ? "" : "; for gas storage, gloom fn NGS"}`);
   return { placement: "floating", settings: { tab: series?.tab ?? tab }, ...(series ? { params: { series: series.value } } : {}) };
 }
 
@@ -23,7 +24,7 @@ const shortcut = (prefix: string, tab: DoeTab | null) => ({
 
 export const doeModule: PluginModule = {
   series: DOE_CATALOG_SERIES,
-  panes: [{ id: "doe", name: "Oil and Gas Inventories", icon: "D", component: DoePane,
+  panes: [{ id: "doe", name: "Oil and Gas Inventories", icon: "D", get component(): typeof import("./pane").DoePane { const { DoePane } = require("./pane"); return DoePane; },
     defaultPosition: "right", defaultMode: "floating", defaultFloatingSize: { width: 96, height: 34 },
     tableExport: true, headless: doeHeadless("all") }],
   paneTemplates: [{

package/src/plugins/builtin/earnings/board.tsx

@@ -10,6 +10,7 @@ import {
   type QueryBarFilter,
   type QueryBarView,
 } from "../../../components";
+import { ageFooterSegment } from "../../../components/layout/pane/footer";
 import { handleRefreshKey, usePaneRefreshKey } from "../../../components/data-table/table-pane";
 import { openFormModal } from "../../../components/form-modal";
 import { FILL_REST } from "../../../components/ui/fill";
@@ -305,7 +306,7 @@ export function EarningsBoard({ focused, width, height, scopedSymbols, highlight
     loading: resource.loading,
     error: resource.error ?? data?.refreshError ?? null,
     stale: !!data?.stale,
-    info: data && updatedAgo ? [{ id: "updated", parts: [{ text: updatedAgo, tone: "muted" as const }] }] : [],
+    info: data && updatedAgo ? [ageFooterSegment(updatedAgo)] : [],
   });
   const symbol = open?.symbol ?? selectedReport?.symbol ?? null;
   // The desktop and the web only: the terminal's footer stays as it was.

package/src/plugins/builtin/earnings/history.tsx

@@ -8,6 +8,7 @@ import {
   usePaneStatusFooter,
   type ChartTableChart,
 } from "../../../components";
+import { ageFooterSegment } from "../../../components/layout/pane/footer";
 import { staticSeries } from "../../../components/chart/static/series";
 import { usePaneRefreshKey } from "../../../components/data-table/table-pane";
 import { useAsyncResource, useAutoRefresh, usePluginPaneState, useUpdatedAgo } from "../../../public/react";
@@ -107,7 +108,7 @@ export function EarningsHistoryView({ symbol, width, height, focused, registrati
     error: historyError,
     stale: !!resource.data?.stale,
     info: abroad ? [{ id: "us-listings", parts: [{ text: "past reports: US listings only", tone: "muted" as const }] }]
-      : payload && updatedAgo ? [{ id: "updated", parts: [{ text: updatedAgo, tone: "muted" as const }] }] : [],
+      : payload && updatedAgo ? [ageFooterSegment(updatedAgo)] : [],
   });
 
   return (

package/src/plugins/builtin/earnings-ripple/client.ts

@@ -4,8 +4,8 @@ import { DEFAULT_GRAPH_OPTIONS, type GraphOptions, type GraphPayload } from "../
 import { errorMessage } from "../../../utils/errors";
 import { addDays, newYorkToday } from "../earnings/board-model";
 import { loadEarningsBoard } from "../earnings/client";
-import { loadSupplyChain } from "../supply-chain/client";
-import { cachedGraph, loadGraph } from "../supply-chain/graph-client";
+import { loadSupplyChain, loadSupplyChainsAhead } from "../supply-chain/client";
+import { cachedGraph, loadGraph, loadGraphsAhead } from "../supply-chain/graph-client";
 import { projectRipple, projectSecondHop, rippleCompanyTickers, RIPPLE_DAYS, secondHopLinks, type RippleRow, type SecondHopRow } from "./model";
 
 export interface RippleSources {
@@ -13,6 +13,10 @@ export interface RippleSources {
   calendar(query: EarningsCalendarQuery): Promise<EarningsCalendarPayload>;
   /** SPLC's graph, which returns both hops around a holding in one call. Absent when the account sees one hop only. */
   graph?(symbol: string, options: GraphOptions): Promise<GraphPayload>;
+  /** Reads every holding's disclosures ahead in batch requests, for `supplyChain` to find. */
+  supplyChainsAhead?(symbols: readonly string[]): Promise<void>;
+  /** Reads these holdings' graphs ahead in batch requests, for `graph` to find. */
+  graphsAhead?(symbols: readonly string[], options: GraphOptions): Promise<void>;
 }
 
 /**
@@ -60,14 +64,29 @@ export interface RippleSnapshot {
  */
 export function cachedRippleSources(accessKey: string, force = false, graph: "off" | "load" | "cached" = "off"): RippleSources & { staleFlags: boolean[] } {
   const staleFlags: boolean[] = [];
+  // A forced read takes what this refresh read ahead as fresh.
+  const chainsAhead = new Set<string>();
+  const graphsAhead = new Set<string>();
   return {
     staleFlags,
-    supplyChain: async (symbol) => { const result = await loadSupplyChain(symbol, accessKey, force); staleFlags.push(result.stale); return result.payload; },
+    supplyChainsAhead: async (symbols) => {
+      for (const symbol of await loadSupplyChainsAhead(symbols, accessKey, force)) chainsAhead.add(symbol);
+    },
+    supplyChain: async (symbol) => {
+      const result = await loadSupplyChain(symbol, accessKey, force && !chainsAhead.has(symbol.toUpperCase()));
+      staleFlags.push(result.stale);
+      return result.payload;
+    },
     calendar: async (query) => { const result = await loadEarningsBoard(query, force); staleFlags.push(result.stale); return result.payload; },
     // Cached by the full query, apart from SPLC Graph's default one.
     ...(graph !== "off" ? { graph: async (symbol: string, options: GraphOptions) => {
       const cached = graph === "cached" ? cachedGraph(symbol, "", options, accessKey) : null;
-      const result = cached ?? await loadGraph(symbol, "", options, accessKey, force); staleFlags.push(result.stale); return result.payload;
+      const result = cached ?? await loadGraph(symbol, "", options, accessKey, force && !graphsAhead.has(symbol.toUpperCase()));
+      staleFlags.push(result.stale);
+      return result.payload;
+    } } : {}),
+    ...(graph === "load" ? { graphsAhead: async (symbols: readonly string[], options: GraphOptions) => {
+      for (const symbol of await loadGraphsAhead(symbols, options, accessKey, force)) graphsAhead.add(symbol);
     } } : {}),
   };
 }
@@ -84,8 +103,12 @@ async function eachLimited(symbols: readonly string[], load: (symbol: string) =>
 const locked = () => ({ graphs: new Map<string, GraphPayload>(), failures: [] as Failure[], locked: true });
 const isPreview = (graphs: ReadonlyMap<string, GraphPayload>) => [...graphs.values()].some((graph) => graph.access === "preview");
 
-/** One graph call per holding. The first answer says whether the account sees two hops; a one-hop preview skips the rest. */
-async function loadGraphs(holdings: readonly string[], graph: NonNullable<RippleSources["graph"]>) {
+/**
+ * One graph per holding. The first answer says whether the account sees two
+ * hops; a one-hop preview skips the rest, which are otherwise read ahead in
+ * batch requests.
+ */
+async function loadGraphs(holdings: readonly string[], graph: NonNullable<RippleSources["graph"]>, ahead?: RippleSources["graphsAhead"]) {
   const graphs = new Map<string, GraphPayload>();
   const failures: Failure[] = [];
   const load = async (symbol: string) => {
@@ -95,6 +118,7 @@ async function loadGraphs(holdings: readonly string[], graph: NonNullable<Ripple
   const [first, ...rest] = holdings;
   if (first) await load(first);
   if (isPreview(graphs)) return locked();
+  await ahead?.(rest, RIPPLE_GRAPH_OPTIONS);
   await eachLimited(rest, load);
   // Only when the first holding failed can a preview get this far.
   if (isPreview(graphs)) return locked();
@@ -107,11 +131,12 @@ export async function loadRipple(holdings: readonly string[], sources: RippleSou
   const symbols = [...new Set(holdings.map((symbol) => symbol.toUpperCase()))];
   const chains = new Map<string, SupplyChainPayload>();
   const failures: Failure[] = [];
+  await sources.supplyChainsAhead?.(symbols);
   await eachLimited(symbols, async (symbol) => {
     try { chains.set(symbol, await sources.supplyChain(symbol)); }
     catch (error) { failures.push({ symbol, error: errorMessage(error) }); }
   });
-  const second = !secondHop ? null : sources.graph ? await loadGraphs(symbols, sources.graph) : locked();
+  const second = !secondHop ? null : sources.graph ? await loadGraphs(symbols, sources.graph, sources.graphsAhead) : locked();
   const graphs = second?.graphs ?? new Map<string, GraphPayload>();
   const companies = [...rippleCompanyTickers(chains), ...secondHopLinks(chains, graphs).map((link) => link.company.ticker!.toUpperCase())];
   const reports: EarningsCalendarPayload["reports"] = [];

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

@@ -1,7 +1,6 @@
 import type { PluginModule } from "../plugin-module";
 import { formatTickerListInput, parseTickerListInput } from "../../../tickers/list";
 import { earningsRippleHeadless } from "./headless";
-import { EarningsRipplePane } from "./pane";
 
 function namedSymbols(arg: string | undefined): string[] {
   try { return arg?.trim() ? parseTickerListInput(arg) : []; } catch { return []; }
@@ -9,7 +8,7 @@ function namedSymbols(arg: string | undefined): string[] {
 
 export const earningsRippleModule: PluginModule = {
   panes: [{
-    id: "earnings-ripple", name: "Earnings Ripple", icon: "E", component: EarningsRipplePane,
+    id: "earnings-ripple", name: "Earnings Ripple", icon: "E", get component(): typeof import("./pane").EarningsRipplePane { const { EarningsRipplePane } = require("./pane"); return EarningsRipplePane; },
     defaultPosition: "right", defaultMode: "floating", defaultFloatingSize: { width: 96, height: 20 },
     tableExport: true,
     // Without named tickers it lists what is in the person's portfolios.

package/src/plugins/builtin/econ/calendar-model.ts

@@ -256,17 +256,40 @@ export function econEventName(event: Pick<EconEvent, "country" | "event" | "actu
 /** Letters and digits only, lower case: "Non-Farm" and "nonfarm" read alike. */
 const compactName = (text: string) => text.toLowerCase().replace(/[^a-z0-9]+/g, "");
 
+/** Words an initialism leaves out: the U.S. Department of Agriculture is USDA. */
+const INITIALISM_SKIPS = new Set(["of", "the", "and", "for", "on", "in"]);
+
+/**
+ * The ways a row's publisher is written, compacted: its name, its initials
+ * ("usda" for the U.S. Department of Agriculture, "bls" for the Bureau of
+ * Labor Statistics) and the name of its site (usda.gov).
+ */
+function publisherNames(source: EconEvent["source"]): string[] {
+  if (!source?.name?.trim()) return [];
+  const initials = source.name.split(/[\s.,&/()-]+/).filter((word) => word && !INITIALISM_SKIPS.has(word.toLowerCase()))
+    .map((word) => word[0]!).join("");
+  let site = "";
+  try {
+    site = source.url ? new URL(source.url).hostname.replace(/^www\./i, "").split(".")[0] ?? "" : "";
+  } catch {
+    // Intentional ignore: a publisher's address that does not parse leaves its name and initials.
+  }
+  return [source.name, initials, site].map(compactName).filter(Boolean);
+}
+
 /**
- * Whether a row's name carries every word of `query`, case, spaces and
- * punctuation aside: `nonfarm` finds Non Farm Payrolls and Non-Farm
- * Employment Change, `fed funds` the Federal Funds Rate. The name shown and the
- * feed's own are both read.
+ * Whether a row carries every word of `query` in its name or its publisher's,
+ * case, spaces and punctuation aside: `nonfarm` finds Non Farm Payrolls and
+ * Non-Farm Employment Change, `fed funds` the Federal Funds Rate, and `usda`
+ * every row the U.S. Department of Agriculture publishes. The name shown and
+ * the feed's own are both read.
  */
-export function matchesEventSearch(event: Pick<EconEvent, "country" | "event" | "actual" | "forecast" | "prior">, query: string): boolean {
+export function matchesEventSearch(event: Pick<EconEvent, "country" | "event" | "actual" | "forecast" | "prior" | "source">, query: string): boolean {
   const words = query.split(/\s+/).map(compactName).filter(Boolean);
   if (words.length === 0) return true;
   const names = [event.event, econEventName(event)].map(compactName);
-  return names.some((name) => words.every((word) => name.includes(word)));
+  const publisher = publisherNames(event.source);
+  return names.some((name) => words.every((word) => name.includes(word) || publisher.some((text) => text.includes(word))));
 }
 
 /**

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

@@ -2,7 +2,6 @@ import type { PluginModule } from "../plugin-module";
 import { statsCache } from "./cache";
 import { STAT_CATEGORIES } from "./defs";
 import { econStatisticsHeadless } from "./headless";
-import { EconStatisticsPane } from "./pane";
 import { resolveStatArg, STATS, DEFAULT_STAT_ID } from "./stats";
 
 
@@ -13,7 +12,7 @@ export const econStatisticsModule: PluginModule = {
     id: ECON_STATISTICS_PANE_ID,
     name: "Economic Statistics",
     icon: "E",
-    component: EconStatisticsPane,
+    get component(): typeof import("./pane").EconStatisticsPane { const { EconStatisticsPane } = require("./pane"); return EconStatisticsPane; },
     defaultPosition: "right",
     defaultMode: "floating",
     defaultFloatingSize: { width: 120, height: 36 },

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

@@ -21,7 +21,7 @@ const savedPath = (id: string) => `saved/${encodeURIComponent(id)}`;
 export const screenerApi = {
   query: (query: ScreenQuery, signal?: AbortSignal, client: ScreenerClient = apiClient) =>
     client.equityScreener<ScreenPayload>("query", json("POST", query, { signal })),
-  fields: (signal?: AbortSignal) => apiClient.equityScreener<ScreenFieldsResponse>("fields?include=social,research,attention,hiring-apps,kpis,volatility,dividends,technical,option-volatility,ownership", { signal }),
+  fields: (signal?: AbortSignal) => apiClient.equityScreener<ScreenFieldsResponse>("fields?include=social,research,attention,hiring-apps,kpis,volatility,dividends,technical,option-volatility,ownership,quality", { signal }),
   export: (definition: ScreenDefinition, snapshotId: string) =>
     apiClient.equityScreener<ScreenExportResponse>("export", json("POST", { ...definition, snapshotId }, { headers: { Accept: "application/json" } })),
   saved: async (signal?: AbortSignal, client: ScreenerClient = apiClient) =>

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

@@ -251,6 +251,7 @@ export const equityScreenerHeadless: HeadlessPaneDefinition<"bundle"> = {
       "IV percentile is the share of the past 52 weeks' options closes with IV30 below the latest; IV30 changes are in volatility points (25% to 27% is +2). IV fields with no close in five days are unavailable. HV20 is 20-session realized volatility, annualized, and HV rank places it between its 52-week low and high.",
       "Technical fields (RSI, moving averages, MACD and golden crosses, new highs and lows, Bollinger width) read US listings' completed daily sessions: they describe the last close, not the session in progress. A days-since field counts trading days, 0 at the last session.",
       "Shares outstanding, float, short % of float and institutional ownership cover US filers: the 10-K or 10-Q cover count, the stored statistics float, the FINRA settlement, the 13F quarter. The source does not say when it measured the float, so float and short % of float are partial, dated by when the statistics were retrieved (within 30 days) and never above the dated shares outstanding. A stale or inconsistent input leaves a field unavailable with its reason. Institutional ownership is over the balance-sheet count at the 13F quarter end; over 100% is partial with its reason.",
+      "ROIC, FCF yield, net debt / EBITDA and debt / equity read FA's latest annual column: the trailing four quarters, or the fiscal year when those quarters are it. Revenue and EPS CAGRs run from the latest fiscal year back 3 or 5 years, both years from the stored statements or both from the SEC filings (US filers), never one of each. Forward growth is the consensus EE shows for the fiscal year in progress. N/M where FA prints it: EBITDA, equity, invested capital or a base year at or below zero.",
     ],
   },
   async load(args, ctx) {