@gloom-sh/terminal 0.19.1 → 0.19.3

package/src/plugins/builtin/debt-maturities/series.ts

@@ -1,6 +1,6 @@
 import type { DebtHistoryPoint } from "../../../api-client/debt-maturities";
 import type { SeriesDefinition } from "../../../series/types";
-import { cachedSeriesWarning } from "../shared/series-warning";
+import { cachedSeriesNote } from "../shared/series-warning";
 import { loadDebtMaturities } from "./client";
 
 type HistoryField = "totalPrincipal" | "next12MonthsShare" | "next3YearsShare";
@@ -36,10 +36,10 @@ export const DEBT_MATURITY_SERIES: readonly SeriesDefinition[] = FIELDS.map(({ i
     // An amount stays in the unit it is listed in: a filing in another currency is a gap, not a converted figure.
     const listed = (point: DebtHistoryPoint) => unit !== "USD" || point.currency === "USD";
     const other = resource.payload.history.find((point) => !listed(point))?.currency;
-    const warning = other ? `Filings reported in ${other} are left out.` : cachedSeriesWarning(resource);
     return {
       points: resource.payload.history.map((point) => ({ date: point.asOf, value: listed(point) ? point[field] : null })),
-      ...(warning ? { warning } : {}),
+      ...cachedSeriesNote(resource),
+      ...(other ? { warning: `Filings reported in ${other} are left out.` } : {}),
     };
   },
 }));

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

@@ -288,7 +288,7 @@ export const debugPlugin: GloomPlugin = {
       name: "Debug Log",
       icon: "D",
       component: DebugPane,
-      reportFreshness: { status: "not-a-feed", basis: "debug log" },
+      reportFreshness: { status: "not-a-feed", basis: "debug log", local: true },
       defaultPosition: "right",
       defaultMode: "floating",
       defaultFloatingSize: { width: 120, height: 30 },

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

@@ -75,6 +75,19 @@ function statedRateSummary(stated: StatedForwardRate): QuoteSummaryDividendField
 interface DividendReadOptions {
   /** The forward rate fundamentals state (statedForwardRate), asked only when the summary is missing. */
   loadStatedForwardRate?: () => Promise<StatedForwardRate | null> | StatedForwardRate | null;
+  /** The history already asked for (requestDividendHistory), so it need not wait for the quote the price comes from. */
+  history?: Promise<DividendHistoryResponse>;
+}
+
+type DividendHistoryResponse = Awaited<ReturnType<typeof apiClient.getMarketDividends>>;
+
+/** Asks Gloom Cloud for a listing's dividend history, for fetchDividendData to read once the price is known. */
+export function requestDividendHistory(symbol: string, exchange = ""): Promise<DividendHistoryResponse> {
+  const pending = trackRequest("dividends", () => apiClient.getMarketDividends(symbol, exchange));
+  pending.catch(() => {
+    // Intentional ignore: fetchDividendData awaits this same promise and reports its failure.
+  });
+  return pending;
 }
 
 let connectionHealth: ConnectionHealthRegistry | null = null;
@@ -125,8 +138,22 @@ function declaredCashByExDate(declared: DeclaredCash | undefined, cashCurrency:
     ? [[row.exDate, { amount: row.amount / unit.divisor, currency: unit.currency }] as const] : []));
 }
 
+/**
+ * The currency the company declares in when it pays the listing another
+ * (South32's dollars, which its rand line converts): the listing's amounts are
+ * conversions of it. Undefined for a listing paid in what was declared.
+ */
+function declaredCurrencyOf(declared: DeclaredCash | undefined, cashCurrency: string): string | undefined {
+  const currency = resolveCurrencyUnit(declared?.currency).currency;
+  return currency && currency !== cashCurrency ? currency : undefined;
+}
+
 export interface DividendData {
   payments: DividendPayment[];
+  /** The currency the company declares in, when its amounts here are converted from it (declaredCurrencyOf). */
+  convertedFrom?: string;
+  /** Beside convertedFrom, the sub-unit the source states the cash in (GBp, ZAc): converted amounts are written in it. */
+  convertedSubUnit?: string;
   /** Declared and unpaid, in `currency`; never in `payments` or any figure. Absent from older servers. */
   declared?: DeclaredDividendAction[];
   metrics: DividendMetrics;
@@ -155,7 +182,7 @@ export async function fetchDividendData(
   currentPriceCurrency?: string,
   options: DividendReadOptions = {},
 ): Promise<DividendData> {
-  const response = await trackRequest("dividends", () => apiClient.getMarketDividends(symbol, exchange));
+  const response = await (options.history ?? requestDividendHistory(symbol, exchange));
   if (!response.data) throw new Error(`No dividend data found for ${symbol}`);
   const { actions: sourceActions, quote: rawQuote, summary, triedAt } = response.data;
   // In the major unit as the history arrives, as every other reader of it gets it.
@@ -180,6 +207,9 @@ export async function fetchDividendData(
     historyError = MISSING_DIVIDEND_CURRENCY;
   }
   const declaredCash = cashCurrency ? declaredCashByExDate(actions?.declaredCash, cashCurrency) : new Map();
+  const convertedFrom = cashCurrency ? declaredCurrencyOf(actions?.declaredCash, cashCurrency) : undefined;
+  const sourceUnit = sourceActions?.currency;
+  const convertedSubUnit = convertedFrom && sourceUnit && resolveCurrencyUnit(sourceUnit).divisor !== 1 ? sourceUnit : undefined;
   const payments = actions && cashCurrency ? actions.dividends.flatMap(action => {
     const payment = toDividendPayment(action.exDate, action.amount, cashCurrency);
     const declared = declaredCash.get(action.exDate);
@@ -203,7 +233,7 @@ export async function fetchDividendData(
     throw new Error(`No dividend data found for ${symbol}`);
   }
   return {
-    payments, ...(declared.length > 0 ? { declared } : {}), metrics, price, currency: currency || undefined, historyAvailable,
+    payments, ...(declared.length > 0 ? { declared } : {}), ...(convertedFrom ? { convertedFrom } : {}), ...(convertedSubUnit ? { convertedSubUnit } : {}), metrics, price, currency: currency || undefined, historyAvailable,
     ...(suppliedPrice == null && price != null && quote ? dividendQuotePriceMetadata(quote) : {}),
     ...(historyError ? { historyError } : {}), ...(summaryError ? { summaryError } : {}),
     ...(statedFields && metrics.forwardRate != null ? { forwardFromFundamentals: true } : {}),

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

@@ -4,19 +4,21 @@ import type {
   HeadlessPaneDefinition,
   HeadlessPaneLoadArgs,
 } from "../../../types/plugin";
-import { fetchDividendData, statedForwardRate, type DividendData } from "./client";
+import { fetchDividendData, requestDividendHistory, statedForwardRate, type DividendData } from "./client";
 import { dividendReferencePrice } from "../../../utils/trailing-dividend";
 import type { DividendPayment, GrowthPayments } from "./types";
-import { formatDividendYield, growthPaymentsText, PAYOUT_NOT_MEANINGFUL, staleHistoryText, toDividendRows, trailingPaymentsText } from "./view";
+import {
+  convertedFromText, formatConvertedAmount, formatDividendYield, growthPaymentsText, PAYOUT_NOT_MEANINGFUL, staleHistoryText, toDividendRows, trailingPaymentsText,
+} from "./view";
 import { formatDistributionAmount, formatPercent } from "../../../utils/format";
 import { forwardDividendBasis, noCurrentDividend, TRAILING_DIVIDEND_BASIS, UNEVEN_REGULAR_PAYMENTS } from "../../../utils/forward-dividend";
 import { currencyPriceMinDigits, formatMarketPriceWithCurrency } from "../../../market-data/market/format";
 import type { Quote } from "../../../types/financials";
 import { regularSessionValuationPrice } from "../../../market-data/quotes/regular-session-valuation";
 import { dividendPriceStatus, dividendQuotePriceMetadata } from "./reference-price";
-import { mapWithConcurrency } from "../../../utils/concurrency";
 import { logFailure } from "../../../utils/log-failure";
-import { projectDividendRanking, roundedRatio, type DividendRankingEntry } from "./ranking";
+import { projectDividendRanking, roundedRatio } from "./ranking";
+import { MAX_RANKED_SYMBOLS, readDividendRanking, type DividendRankingReads } from "./ranking-reads";
 import { REPORT_FILTER, REPORT_ROWS } from "../shared/headless-options";
 import type { FundBondFacts } from "../../../api-client/fund-facts";
 import { resolveTickerInstrumentKind } from "../../../tickers/instrument-kind";
@@ -27,31 +29,35 @@ import {
   type TaxEquivalentAnalysis, type TreasuryTenor,
 } from "../../../market-data/tax-equivalent";
 
-/** Symbols one `fn DVD` ranks at most, and how many it reads at once. */
-const MAX_RANKED_SYMBOLS = 25;
-const RANKING_CONCURRENCY = 4;
 /** The history options' defaults: a ranking lists no history, so only these leave it unchanged. */
 const DEFAULT_TYPE = "all";
 const DEFAULT_LIMIT = 40;
 
-const PAYMENT_COLUMNS = [
-  { key: "exDate", header: "Ex-date" },
-  { key: "amount", header: "Amount", align: "right" as const,
-    format: (value: unknown, row: Record<string, unknown>) => typeof value === "number" && typeof row.currency === "string" && row.currency
-      ? formatDistributionAmount(value, row.currency) : value == null ? "-" : String(value) },
-  { key: "currency", header: "CCY" },
-  { key: "type", header: "Type" },
-];
+/** The history's columns; amounts converted from the currency the company declares in go to two decimals of their source's unit. */
+function paymentColumns(converted: boolean, subUnit?: string) {
+  const amount = converted ? (value: number, currency: string) => formatConvertedAmount(value, currency, subUnit) : formatDistributionAmount;
+  return [
+    { key: "exDate", header: "Ex-date" },
+    { key: "amount", header: "Amount", align: "right" as const,
+      format: (value: unknown, row: Record<string, unknown>) => typeof value === "number" && typeof row.currency === "string" && row.currency
+        ? amount(value, row.currency) : value == null ? "-" : String(value) },
+    { key: "currency", header: "CCY" },
+    { key: "type", header: "Type" },
+  ];
+}
 
 /** After the amount, for a company declaring in another currency than the listing pays: what it declared. */
 const DECLARED_COLUMN = { key: "declared", header: "Declared", align: "right" as const,
   format: (value: unknown, row: Record<string, unknown>) => typeof value === "number" && typeof row.declaredCurrency === "string"
     ? formatDistributionAmount(value, row.declaredCurrency) : "-" };
 
+/** What a ticker's read needs: the market data, Gloom Cloud, and the listing a typed key stands for. */
+export type DividendReadContext = Pick<HeadlessPaneContext, "marketData" | "apiClient" | "resolveInstrument">;
+
 export interface DividendYieldHeadlessDependencies {
-  loadData(symbol: string, context: HeadlessPaneContext): Promise<DividendData>;
+  loadData(symbol: string, context: DividendReadContext): Promise<DividendData>;
   /** A US-listed fund's bond facts (SEC yield, yield to worst, duration); null for any other listing. */
-  loadBond?(symbol: string, context: HeadlessPaneContext): Promise<FundBondFacts | null>;
+  loadBond?(symbol: string, context: DividendReadContext): Promise<FundBondFacts | null>;
   /** The Treasury par curve GC shows, for the muni/Treasury ratio; null when it cannot be read. */
   loadTreasury?(context: HeadlessPaneContext): Promise<TreasuryTenor[] | null>;
 }
@@ -68,6 +74,8 @@ const defaultDependencies: DividendYieldHeadlessDependencies = {
     const instrument = await context.resolveInstrument?.(symbol);
     const listingSymbol = instrument?.symbol ?? symbol;
     const exchange = instrument?.exchange ?? "";
+    // The history is asked for beside the quote, not after it: only its yields need the price.
+    const history = requestDividendHistory(listingSymbol, exchange);
     try {
       const quote = await context.marketData.getQuote(listingSymbol, exchange);
       // The regular session's price: after the close, the close rather than an after-hours print.
@@ -79,6 +87,7 @@ const defaultDependencies: DividendYieldHeadlessDependencies = {
       currentPrice = null;
     }
     const data = await fetchDividendData(listingSymbol, currentPrice, exchange, currentPriceCurrency, {
+      history,
       // Read only when the summary is missing: the forward rate fundamentals state, as `fundamentals` shows it.
       loadStatedForwardRate: async () => statedForwardRate(await context.marketData.getTickerFinancials(listingSymbol, exchange)),
     });
@@ -102,6 +111,25 @@ const defaultDependencies: DividendYieldHeadlessDependencies = {
   loadTreasury: (context) => loadTreasuryTenors(context.apiClient),
 };
 
+/**
+ * How a ranking reads each ticker: `fn DVD`'s, and the DVD pane's with the
+ * app's market data, so both read the same listing at the same price. A
+ * fund's bond facts never fail its row: without them it ranks as before.
+ */
+export function dividendRankingReads(
+  context: DividendReadContext,
+  dependencies: Pick<DividendYieldHeadlessDependencies, "loadData" | "loadBond"> = defaultDependencies,
+): DividendRankingReads {
+  const { loadBond } = dependencies;
+  return {
+    loadData: (symbol) => dependencies.loadData(symbol, context),
+    ...loadBond ? {
+      loadBond: (symbol: string) => loadBond(symbol, context).catch((error) => error instanceof BondClassificationError ? null
+        : logFailure("dividend-yield.headless", "Read bond fund facts for ranking failed", null)(error)),
+    } : {},
+  };
+}
+
 /** A growth figure, or what its short year holds: "n/a: 1 of 2 payments". */
 function growthText(growth: number | null, payments: GrowthPayments | null | undefined): string {
   return growth == null && payments ? growthPaymentsText(payments) : formatPercent(growth ?? undefined);
@@ -147,10 +175,16 @@ export function projectDividendYieldHeadless(
       ...(row.declared ? { declared: row.declared.amount, declaredCurrency: row.declared.currency } : {}),
     };
   });
+  // A listing paid in another currency than its company declares (South32's rand) has its amounts converted from that one.
+  const convertedFrom = data.convertedFrom;
+  const subUnit = data.convertedSubUnit;
+  const paymentColumnList = paymentColumns(!!convertedFrom, subUnit);
   const declaredColumns = rows.some((row) => row.declared)
-    ? [...PAYMENT_COLUMNS.slice(0, 2), DECLARED_COLUMN, ...PAYMENT_COLUMNS.slice(2)] : PAYMENT_COLUMNS;
+    ? [...paymentColumnList.slice(0, 2), DECLARED_COLUMN, ...paymentColumnList.slice(2)] : paymentColumnList;
   const metrics = data.metrics;
   const currency = data.currency ?? data.payments[0]?.currency ?? "";
+  const cashRate = (value: number | null) => !currency ? "—" : !convertedFrom ? formatDistributionAmount(value ?? undefined, currency)
+    : value == null ? formatConvertedAmount(value, currency) : `${formatConvertedAmount(value, currency, subUnit)} (${convertedFromText(convertedFrom)})`;
   const priceStatus = dividendPriceStatus(data.price, data.priceAsOf, data.priceStale);
   // A regular payer's year with fewer payments than its cadence pays: the yield says how many it counts.
   const shortfall = trailingPaymentsText(metrics.trailingPayments, { cadence: true });
@@ -180,8 +214,8 @@ export function projectDividendYieldHeadless(
             value: figure.value,
             formatted: `${figure.text}${figure.date ? ` (as of ${figure.date})` : ""}`,
           })) : []),
-          { label: "Trailing rate", value: metrics.trailingRate, formatted: currency ? formatDistributionAmount(metrics.trailingRate ?? undefined, currency) : "—" },
-          { label: "Forward rate", value: metrics.forwardRate, formatted: currency ? formatDistributionAmount(metrics.forwardRate ?? undefined, currency) : "—" },
+          { label: "Trailing rate", value: metrics.trailingRate, formatted: cashRate(metrics.trailingRate) },
+          { label: "Forward rate", value: metrics.forwardRate, formatted: cashRate(metrics.forwardRate) },
           { label: "Earnings Payout", value: roundedRatio(metrics.payoutRatio), formatted: metrics.payoutNotMeaningful ? PAYOUT_NOT_MEANINGFUL : formatDividendYield(metrics.payoutRatio) },
           { label: "1Y Cash Growth", value: roundedRatio(metrics.growth1Y), formatted: growthText(metrics.growth1Y, metrics.growth1YPayments) },
           { label: "3Y Cash CAGR", value: roundedRatio(metrics.growth3Y), formatted: growthText(metrics.growth3Y, metrics.growth3YPayments) },
@@ -198,7 +232,7 @@ export function projectDividendYieldHeadless(
         entries: taxEquivalentLines(tax).map((line) => ({ label: line.label, value: line.value, formatted: line.text })),
       }] : []),
       {
-        title: "Dividend history",
+        title: convertedFrom ? `Dividend history (amounts ${convertedFromText(convertedFrom)})` : "Dividend history",
         columns: declaredColumns,
         rows,
         // Each amount is in its own row's currency.
@@ -211,6 +245,8 @@ export function projectDividendYieldHeadless(
       truncated: rows.length < matching.length,
       type,
       currency: data.currency ?? data.payments[0]?.currency ?? null,
+      // The currency the company declares in, when the amounts are converted from it; null for one paid as declared.
+      convertedFrom: convertedFrom ?? null,
       historyAvailable: data.historyAvailable ?? true,
       historyError: data.historyError ?? null,
       summaryError: data.summaryError ?? null,
@@ -321,18 +357,7 @@ export function createDividendYieldHeadless(
       if (historyOptions.length > 0) {
         throw new Error(`${historyOptions.join(" and ")} ${historyOptions.length === 1 ? "filters" : "filter"} one ticker's payment history, and a ranking of several lists none. Drop ${historyOptions.length === 1 ? "it" : "them"}, or run DVD on one ticker.`);
       }
-      const entries = await mapWithConcurrency(args.symbols, RANKING_CONCURRENCY, async (symbol): Promise<DividendRankingEntry> => {
-        // A fund's bond facts never fail its row: without them it ranks as before.
-        const bond = dependencies.loadBond?.(symbol, context)
-          .catch((error) => error instanceof BondClassificationError ? null
-            : logFailure("dividend-yield.headless", "Read bond fund facts for ranking failed", null)(error)) ?? null;
-        try {
-          return { symbol, data: await dependencies.loadData(symbol, context), bond: await bond };
-        } catch (error) {
-          return { symbol, error: error instanceof Error ? error.message : String(error) };
-        }
-      });
-      return projectDividendRanking(entries);
+      return projectDividendRanking(await readDividendRanking(args.symbols, dividendRankingReads(context, dependencies)));
     },
   };
 }

package/src/plugins/builtin/dividend-yield/index.tsx

@@ -8,6 +8,9 @@ import {
 } from "./client";
 import { DividendYieldPane } from "./pane";
 import { dividendYieldHeadless } from "./headless";
+import { RANK_SYMBOLS_SETTING } from "./ranking-view";
+import { MAX_RANKED_SYMBOLS } from "./ranking-reads";
+import type { PaneTemplateCreateOptions, PaneTemplateDef } from "../../../types/plugin";
 
 function createDividendYieldModule({
   component = DividendYieldPane,
@@ -65,7 +68,7 @@ function createDividendYieldModule({
 
     paneTemplates: [
       {
-        ...createTickerSurfacePaneTemplate({
+        ...withRanking(createTickerSurfacePaneTemplate({
           id: "dividend-yield-pane",
           paneId: "dividend-yield",
           label: "Dividend Yield",
@@ -75,11 +78,43 @@ function createDividendYieldModule({
             "dividend growth", "payout ratio", "drip", "reinvest", "reinvestment", "dividend reinvestment", "rank dividend payers",
             "sec yield", "distribution yield", "muni", "munis", "municipal", "municipal bonds", "tax-exempt", "tax-equivalent yield", "muni treasury ratio"],
           shortcut: "DVD",
-        }),
+        })),
         headless,
       },
     ],
   };
 }
 
+/**
+ * The tickers a DVD is opened with when there are several: the list a command
+ * passes (`shot DVD KO JNJ`), or a comma list typed as its argument.
+ */
+function rankedSymbols(options: PaneTemplateCreateOptions | undefined): string[] {
+  const list = options?.symbols?.length ? options.symbols : (options?.arg ?? options?.symbol ?? "").split(",");
+  // The first 25, as `fn DVD` ranks at most.
+  const symbols = [...new Set(list.map((symbol) => symbol.trim().toUpperCase()).filter(Boolean))].slice(0, MAX_RANKED_SYMBOLS);
+  return symbols.length > 1 ? symbols : [];
+}
+
+/** DVD with several tickers opens one pane that ranks them by yield, as `fn DVD A B C` does; with one, its own pane. */
+function withRanking(template: PaneTemplateDef): PaneTemplateDef {
+  return {
+    ...template,
+    // `fn` and `shot` pass a typed list as `symbols`, so `shot DVD KO JNJ` draws the ranking `fn DVD KO JNJ` prints.
+    opensTickerList: true,
+    canCreate: (context, options) => rankedSymbols(options).length > 1 || (template.canCreate?.(context, options) ?? true),
+    createInstance: (context, options) => {
+      const symbols = rankedSymbols(options);
+      if (symbols.length < 2) return template.createInstance?.(context, options) ?? null;
+      return {
+        instanceId: `dividend-yield:rank:${symbols.map((symbol) => encodeURIComponent(symbol)).join(",")}`,
+        title: `DVD ${symbols.join(", ")}`,
+        binding: { kind: "none" },
+        placement: "floating",
+        settings: { [RANK_SYMBOLS_SETTING]: symbols },
+      };
+    },
+  };
+}
+
 export const dividendYieldModule = createDividendYieldModule();

package/src/plugins/builtin/dividend-yield/pane.tsx

@@ -31,7 +31,7 @@ import { isCloudSessionRequired, useResearchCloudSession } from "../shared/resea
 import { fetchDividendData, repriceDividendMetrics, statedForwardRate, type DividendData } from "./client";
 import { dividendReferencePrice } from "../../../utils/trailing-dividend";
 import { useTickerQuoteStream } from "../../../state/hooks/live-ticker-financials";
-import { buildTrailingCashChartPoints, formatDividendYield, growthPaymentsDetail, PAYOUT_NOT_MEANINGFUL, staleHistoryText, toDividendRows, trailingPaymentsText, type DividendRow } from "./view";
+import { buildTrailingCashChartPoints, convertedFromText, formatConvertedAmount, formatDividendYield, growthPaymentsDetail, PAYOUT_NOT_MEANINGFUL, staleHistoryText, toDividendRows, trailingPaymentsText, type DividendRow } from "./view";
 import {
   DEFAULT_SORT_PREFERENCE,
   buildDividendColumns,
@@ -46,11 +46,14 @@ import type { FundBondFacts } from "../../../api-client/fund-facts";
 import { resolveTickerInstrumentKind } from "../../../tickers/instrument-kind";
 import { mayBeUsEquityOrFundTicker } from "../../../utils/sec";
 import { useFundFacts } from "../sec/fund-facts-view";
+import { usePaneInstance } from "../../../state/app/context";
+import { DividendRankingView, rankSymbolsOf } from "./ranking-view";
 import { bondFigures } from "../../../market-data/bond-funds";
 
-function formatRate(value: number | null, currency: string): string {
+/** A per-share rate; one converted from the currency the company declares in goes to two decimals of its source's unit. */
+function formatRate(value: number | null, currency: string, converted = false, subUnit?: string): string {
   if (value == null) return "—";
-  return formatDistributionAmount(value, currency);
+  return converted ? formatConvertedAmount(value, currency, subUnit) : formatDistributionAmount(value, currency);
 }
 
 function formatGrowth(value: number | null): string {
@@ -90,7 +93,9 @@ function formatFrequency(freq: DividendMetrics["paymentFrequency"]): string {
  * say they are not its SEC yield, and the SEC yield follows them with its date.
  */
 function buildMetricItems(metrics: DividendMetrics, currency: string, hasHistory: boolean, short: boolean,
-  declared: DividendData["declared"], bond: FundBondFacts | null = null): StatItem[] {
+  declared: DividendData["declared"], bond: FundBondFacts | null = null, convertedFrom?: string, convertedSubUnit?: string): StatItem[] {
+  // The rates of a listing paid in a conversion of what its company declares say what they were converted from.
+  const converted = convertedFrom ? { detail: convertedFromText(convertedFrom) } : {};
   const exDate: StatItem[] = metrics.nextExDividendDate
     ? [{ id: "next-ex", label: "Next ex", value: formatDate(metrics.nextExDividendDate) }]
     : hasHistory ? [] : [{ id: "last-ex", label: "Last ex", value: formatDate(metrics.lastExDividendDate) }];
@@ -116,8 +121,10 @@ function buildMetricItems(metrics: DividendMetrics, currency: string, hasHistory
         ...(forwardNote ? { detail: forwardNote } : {}) },
     // The 30-day SEC yield as the fund's sponsor publishes it, dated.
     ...(sec ? [{ id: "sec-yield", label: short ? "SEC yld" : "SEC yield", value: sec.text, ...(sec.date ? { detail: `as of ${sec.date}` } : {}) }] : []),
-    { id: "ttm-rate", label: short ? "TTM/sh" : "TTM/share", value: formatRate(metrics.trailingRate, currency) },
-    { id: "forward-rate", label: short ? "Fwd/sh" : "Fwd/share", value: formatRate(metrics.forwardRate, currency) },
+    { id: "ttm-rate", label: short ? "TTM/sh" : "TTM/share", value: formatRate(metrics.trailingRate, currency, !!convertedFrom, convertedSubUnit),
+      ...metrics.trailingRate != null ? converted : {} },
+    { id: "forward-rate", label: short ? "Fwd/sh" : "Fwd/share", value: formatRate(metrics.forwardRate, currency, !!convertedFrom, convertedSubUnit),
+      ...metrics.forwardRate != null ? converted : {} },
     growthItem("growth-1y", short ? "1Y chg" : "1Y growth", metrics.growth1Y, metrics.growth1YPayments),
     growthItem("cagr-3y", "3Y CAGR", metrics.growth3Y, metrics.growth3YPayments),
     { id: "payout", label: "Payout", value: metrics.payoutNotMeaningful ? PAYOUT_NOT_MEANINGFUL : metrics.payoutRatio != null ? `${(metrics.payoutRatio * 100).toFixed(1)}%` : "—" },
@@ -144,13 +151,15 @@ const rowKey = (row: DividendRow) => row.key;
 function renderCell(
   row: DividendRow,
   column: DividendColumn,
+  converted = false,
+  subUnit?: string,
 ): DataTableCell {
   switch (column.id) {
     case "exDate":
       return { text: row.exDate, color: colors.textDim };
     case "amount":
       return {
-        text: formatDistributionAmount(row.amount, row.currency),
+        text: converted ? formatConvertedAmount(row.amount, row.currency, subUnit) : formatDistributionAmount(row.amount, row.currency),
         color: colors.textBright,
         attributes: TextAttributes.BOLD,
       };
@@ -161,9 +170,15 @@ function renderCell(
   }
 }
 
-export function DividendYieldPane({ focused, width, height, loadData = fetchDividendData }: {
-  focused: boolean; width: number; height: number; loadData?: typeof fetchDividendData;
-}) {
+type DividendPaneProps = { focused: boolean; width: number; height: number; loadData?: typeof fetchDividendData };
+
+/** One ticker's dividends, or several ranked by yield when the pane was opened with a list (`shot DVD KO JNJ`). */
+export function DividendYieldPane(props: DividendPaneProps) {
+  const ranked = rankSymbolsOf(usePaneInstance()?.settings);
+  return ranked.length > 1 ? <DividendRankingView symbols={ranked} {...props} /> : <DividendTickerPane {...props} />;
+}
+
+function DividendTickerPane({ focused, width, height, loadData = fetchDividendData }: DividendPaneProps) {
   const { symbol, ticker, financials } = usePaneTicker();
   const { nativePaneChrome } = useUiCapabilities();
   // Yields are repriced from the quote on every render, so streaming it is all
@@ -275,13 +290,17 @@ export function DividendYieldPane({ focused, width, height, loadData = fetchDivi
   });
   // The header row, plus the scrollbar row once the columns overflow the pane.
   const tableChromeRows = chartTableChromeRows(columns, width);
-  const fullFigures = metrics ? buildMetricItems(metrics, currency, sortedRows.length > 0, false, data?.declared, bond) : [];
+  const convertedFrom = historyData?.convertedFrom;
+  const convertedSubUnit = historyData?.convertedSubUnit;
+  const renderRowCell = useCallback((row: DividendRow, column: DividendColumn) => renderCell(row, column, !!convertedFrom, convertedSubUnit),
+    [convertedFrom, convertedSubUnit]);
+  const fullFigures = metrics ? buildMetricItems(metrics, currency, sortedRows.length > 0, false, data?.declared, bond, convertedFrom, convertedSubUnit) : [];
   const keptFigures = chartTableLayout({
     width, height, figures: fullFigures, tableRows: sortedRows.length, tableChromeRows, chart: chartPoints.length >= 2 ? {} : null,
   }).figures;
   // The desktop grid never clips a label; the terminal shortens them rather than clip.
   const figures = metrics && !nativePaneChrome && labelsClip(keptFigures, width)
-    ? buildMetricItems(metrics, currency, sortedRows.length > 0, true, data?.declared, bond) : fullFigures;
+    ? buildMetricItems(metrics, currency, sortedRows.length > 0, true, data?.declared, bond, convertedFrom, convertedSubUnit) : fullFigures;
 
   const handleHeaderClick = useCallback((columnId: string) => {
     setSortPreference((current) => nextHeaderSort(current, columnId as DividendColumnId, {
@@ -324,7 +343,7 @@ export function DividendYieldPane({ focused, width, height, loadData = fetchDivi
       sortDirection={sortPreference.direction}
       onHeaderClick={handleHeaderClick}
       getItemKey={rowKey}
-      renderCell={renderCell}
+      renderCell={renderRowCell}
       selectedTextOverridesCellColor
       emptyStateTitle={emptyTitle}
     />

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) };
+    }
+  })));
+}