@gloom-sh/terminal 0.18.5 → 0.19.0

package/src/plugins/builtin/analytics/risk-model.ts

@@ -48,7 +48,16 @@ import {
   type RiskHoldingRequest,
   type RiskMarketSnapshot,
 } from "./risk-client";
-import { accountFxPair, accountFxReason, convertReturnsToAccount, FX_UNAVAILABLE, type AccountFx } from "./risk-fx";
+import {
+  accountFxPair,
+  accountFxReason,
+  bridgedFxClose,
+  convertReturnsToAccount,
+  FX_UNAVAILABLE,
+  fxBridgeNote,
+  riskConversion,
+  type AccountFx,
+} from "./risk-fx";
 
 interface PortfolioRiskHolding {
   id: string;
@@ -77,6 +86,8 @@ interface PortfolioRiskHolding {
   historyAsOf: string | null;
   /** Daily returns in the account currency. */
   returns: DatedReturn[];
+  /** Dates its returns converted at the FX close before them, by pair ("GBP/USD"), its daily closes having none (bridgedFxClose). */
+  fxBridged: ReadonlyMap<string, readonly string[]>;
   error: string | null;
   /** Why the holding is outside the basket; null when it qualifies. */
   leftOut: string | null;
@@ -386,15 +397,43 @@ function cashReason(line: RiskCashLine, accountCurrency: string): string {
     ? "Cash is outside the equity basket"
     : `Cash is outside the equity basket; its ${accountCurrency} value moves with ${own}`;
 }
+/** One note per pair whose missing daily closes the basket's returns were converted across (fxBridgeNote). */
+function fxBridgeNotes(members: readonly Pick<PortfolioRiskHolding, "fxBridged">[]): string[] {
+  const byPair = new Map<string, Set<string>>();
+  for (const member of members)
+    for (const [pair, dates] of member.fxBridged) {
+      const set = byPair.get(pair) ?? new Set<string>();
+      for (const date of dates) set.add(date);
+      byPair.set(pair, set);
+    }
+  return [...byPair].flatMap(([pair, dates]) => fxBridgeNote(pair, dates) ?? []);
+}
 /** USD returns in the account currency, or none with the reason its daily closes cannot convert them. */
-function accountReturns(returns: readonly DatedReturn[], account: AccountFx): { returns: DatedReturn[]; error: string | null } {
-  if (account.error) return { returns: [], error: account.error };
+function accountReturns(
+  returns: readonly DatedReturn[],
+  account: AccountFx,
+): { returns: DatedReturn[]; bridged: string[]; error: string | null } {
+  if (account.error) return { returns: [], bridged: [], error: account.error };
   try {
-    return { returns: convertReturnsToAccount(returns, account), error: null };
+    return { ...convertReturnsToAccount(returns, account), error: null };
   } catch (error) {
-    return { returns: [], error: error instanceof Error ? error.message : accountFxReason(account.currency, FX_UNAVAILABLE) };
+    return { returns: [], bridged: [], error: error instanceof Error ? error.message : accountFxReason(account.currency, FX_UNAVAILABLE) };
   }
 }
+/** The dates a holding's returns converted at the FX close before them, by pair: its listing's into USD, then USD into the account's. */
+function holdingFxBridges(
+  listingCurrency: string | null,
+  listingBridged: readonly string[] | undefined,
+  account: AccountFx | null | undefined,
+  accountBridged: readonly string[] | undefined,
+): Map<string, readonly string[]> {
+  const bridges = new Map<string, readonly string[]>();
+  const listingPair = listingCurrency && listingBridged?.length ? accountFxPair(riskConversion(listingCurrency)?.currency ?? listingCurrency) : null;
+  if (listingPair) bridges.set(listingPair, listingBridged!);
+  const accountPair = account?.pair;
+  if (accountPair && accountBridged?.length) bridges.set(accountPair, [...(bridges.get(accountPair) ?? []), ...accountBridged]);
+  return bridges;
+}
 /**
  * "returns in TRY at daily USD/TRY closes": the currency the basket views of a
  * non-USD account are in and how they got there; null for a USD account, or
@@ -474,6 +513,8 @@ export function riskCoverageNotices(coverage: RiskCoverage | undefined): string[
       `${row.symbol} (${row.share == null ? "value unknown" : `${shareText(row.share)} of the book`}) is excluded from the risk estimate: ${lowerFirst(row.reason.replace(/\.$/, ""))}.`,
   );
 }
+/** What an empty portfolio's pane says after "No holdings in this portfolio.": where holdings come from. */
+export const NO_HOLDINGS_HINT = "Add holdings from the Portfolio pane (PF), or connect a broker in BR to sync them.";
 /** Why the basket views show no estimate, when too little of the holdings qualifies. */
 export function riskCoverageShortfall(
   coverage: RiskCoverage | undefined,
@@ -690,6 +731,7 @@ export function buildPortfolioRisk(
       // Converted returns end with the account currency's last daily close.
       historyAsOf: (inAccount ? inAccount.returns.at(-1)?.dateKey : null) ?? history?.asOf ?? null,
       returns,
+      fxBridged: holdingFxBridges(convertedFrom, history?.converted?.fxBridged, account, inAccount?.bridged),
       error,
       leftOut,
     };
@@ -774,6 +816,8 @@ export function buildPortfolioRisk(
           "Converted holdings are matched to the US close of the same date; where their market closes at another time, correlations and betas to US holdings read lower than they are.",
         ]
       : []),
+    // A pair's daily closes skip Good Friday, Easter Monday, 25 Dec and 1 Jan; returns across them use the close before.
+    ...fxBridgeNotes(members),
   ];
   const warnings = [
     ...market.warnings,
@@ -796,12 +840,14 @@ export function buildPortfolioRisk(
     return (instrument && byId.get(riskInstrumentId(instrument))?.returns) || [];
   };
   // SPY's USD returns are the market factor and the equity stress; the risk
-  // rows compare the basket with SPY in the basket's own currency. A session
-  // without an account close is a gap in that benchmark, never bridged, so it
-  // cannot blank the holdings the closes do cover.
+  // rows compare the basket with SPY in the basket's own currency, bridged
+  // across missing account closes as the holdings are (bridgedFxClose). A
+  // session past a longer gap is a gap in that benchmark, so it cannot blank
+  // the holdings the closes do cover.
   const spy = proxy(RISK_BENCHMARK);
+  const accountClose = (date: string) => account ? bridgedFxClose((day) => account.closes[day], date) : null;
   const benchmark = account
-    ? accountReturns(spy.filter((point) => account.closes[point.startDateKey] && account.closes[point.dateKey]), account).returns
+    ? accountReturns(spy.filter((point) => accountClose(point.startDateKey) && accountClose(point.dateKey)), account).returns
     : spy;
   // Since the filing only for a portfolio that has one; any other keeps the trailing window and says why.
   const filed = window.since === "filed" ? portfolio.importedFrom?.filed ?? null : null;

package/src/plugins/builtin/analytics/risk-pane.tsx

@@ -30,6 +30,7 @@ import {
   useAsyncResource,
   useAutoRefresh,
   usePaneSettingValue,
+  usePluginAppActions,
   usePluginPaneState,
   useShortcut,
 } from "../../../public/react";
@@ -54,6 +55,7 @@ import {
   HOLDINGS_SHARE_UNIT,
   HOLDINGS_SUMMARY_ROW_IDS,
   isShockRow,
+  NO_HOLDINGS_HINT,
   portfolioRiskRequests,
   portfolioRiskTickers,
   riskCoverageLine,
@@ -234,6 +236,7 @@ function RiskDetail({
 export function PortfolioRiskPane({ focused, width, height }: PaneProps) {
   const instance = usePaneInstance(),
     renderer = useRendererHost();
+  const { showPane } = usePluginAppActions();
   const portfolios = useAppSelector((state) => state.config.portfolios),
     tickers = useAppSelector((state) => state.tickers),
     brokerAccounts = useAppSelector((state) => state.brokerAccounts);
@@ -403,14 +406,16 @@ export function PortfolioRiskPane({ focused, width, height }: PaneProps) {
   const model = derived.model;
   const marketLoading = resource.loading && !resource.data;
   // A basket view with nothing to estimate says why in the body, not with a table of dashes.
-  const basketBody = useMemo<{ loading?: boolean; error?: string; title?: string; message?: string } | null>(() => {
+  const basketBody = useMemo<{ loading?: boolean; error?: string; title?: string; message?: string; noHoldings?: boolean } | null>(() => {
     if (!model || !BASKET_VIEWS.has(view)) return null;
     if (!frozen && !resource.data)
       return marketLoading ? { loading: true } : resource.error ? { error: resource.error } : null;
     if (view === "holdings") return null;
     const shortfall = riskCoverageShortfall(model.coverage);
     // The currency and price shocks reprice the book without the basket, so they stay; the footer says why the basket scenarios do not.
-    return shortfall && view === "stress" && model.rows.stress.some(isShockRow) ? null : shortfall;
+    if (shortfall && view === "stress" && model.rows.stress.some(isShockRow)) return null;
+    // A portfolio with no holdings says where they come from, as the other panes' empty states do.
+    return shortfall && !model.coverage?.holdings ? { ...shortfall, message: NO_HOLDINGS_HINT, noHoldings: true } : shortfall;
   }, [frozen, marketLoading, model, resource.data, resource.error, view]);
   // Stress with too little covered for the basket scenarios, its shocks shown alone.
   const stressShortfall = useMemo(
@@ -816,6 +821,7 @@ export function PortfolioRiskPane({ focused, width, height }: PaneProps) {
               loadingLabel="Loading portfolio risk"
               emptyTitle={basketBody.title}
               emptyMessage={basketBody.message || undefined}
+              actions={basketBody.noHoldings ? <Button label="Open Portfolio" compact onPress={() => showPane("portfolio-list")} /> : undefined}
             />
           ) : evidenceMissing ? (
             <PaneStatusBody

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

@@ -5,11 +5,12 @@ import { attentionHeadless } from "./headless";
 import { TrendingPane } from "./trending";
 import { AttentionPane } from "./pane";
 import { ATTENTION_SERIES } from "./series";
+import { ATTENTION_LISTED } from "./listing";
 export const attentionModule: PluginModule = {
   panes: [{ id: "attention", name: "Research Attention", icon: "A", component: AttentionPane, defaultPosition: "right", defaultMode: "floating",
     defaultFloatingSize: { width: 126, height: 32 }, tableExport: true, headless: attentionHeadless },
     { id: "attention-trending", reportFreshness: { status: "not-a-feed", basis: "hourly publication" }, name: "Gloom Trending", icon: "A", component: TrendingPane, defaultPosition: "right", defaultMode: "floating", defaultFloatingSize: { width: 58, height: 12 } }],
-  paneTemplates: [{ id: "attention-pane", paneId: "attention", label: "Research Attention",
+  paneTemplates: [{ id: "attention-pane", paneId: "attention", label: "Research Attention", listed: ATTENTION_LISTED,
     description: "Pro research attention: rankings, abnormal activity, sectors, countries and privacy-qualified hourly history.",
     keywords: ["attention", "trending", "research", "activity"], shortcut: { prefix: "ATTN", argKind: "text", argPlaceholder: "TICKER", argOptional: true },
     headless: attentionHeadless, createInstance: (_ctx, options) => ({ placement: "floating", settings: { window: attentionWindow(options?.values?.window), symbol: (options?.arg ?? options?.symbol)?.trim().toUpperCase() ?? "" } }) },

package/src/plugins/builtin/attention/listing.ts

@@ -0,0 +1,14 @@
+/**
+ * Whether ATTN is listed: in command-bar search, Help, `gloom catalog` and
+ * search, the plugin directory and chat suggestions, and its two screener
+ * fields (ATTN HRS, ATTN Z) in the EQS field and metric pickers.
+ *
+ * Research attention publishes an hour only once enough opted-in users
+ * researched in it, and it has published nothing for weeks, so ATTN stays
+ * unlisted until it does. Typing ATTN still opens it, a screen that already
+ * uses its fields keeps them, and the Attention Counts setting and its
+ * collection are unchanged. Set it to true the day ATTN publishes again,
+ * with the server's own switch, and refresh the docs snapshot
+ * (`bun run docs:snapshot`) once the site lists ATTN.
+ */
+export const ATTENTION_LISTED = false;

package/src/plugins/builtin/broker-manager/index.tsx

@@ -11,7 +11,7 @@ import {
   resetSignedInBrokerCatalog,
   subscribeSignedInBrokers,
 } from "../../../brokers/signed-in/catalog";
-import { DataTableStackView, EmptyState } from "../../../components";
+import { Button, DataTableStackView, EmptyState } from "../../../components";
 import { t } from "../../../i18n";
 import { useAppLanguage } from "../../../i18n/react";
 import {
@@ -340,10 +340,14 @@ export function BrokersPane({ focused, width, height }: PaneProps) {
           sortDirection="asc"
           getItemKey={(row) => row.id}
           renderCell={renderCell}
-          // The footer's a adds one.
+          // The same add the footer's a and the command bar start; as the state's first
+          // action it also answers Enter.
           emptyContent={(
             <Box width="100%" paddingX={1} paddingY={1}>
-              <EmptyState title={t("No broker profiles.")} />
+              <EmptyState
+                title={t("No broker profiles.")}
+                actions={<Button label="Add Broker Account" onPress={startAdd} />}
+              />
             </Box>
           )}
           emptyStateTitle={t("No broker profiles.")}

package/src/plugins/builtin/buildout/cells.tsx

@@ -12,11 +12,19 @@ import {
   activityLabel,
   criticalityColor,
   metricColor,
+  moneyAmount,
+  moneyText,
   text,
   tickerSymbol,
 } from "./format";
 import { favoriteKey } from "./table-model";
 
+/** A dollar figure in the compact form, with its whole number for an export. */
+function moneyCell(value: string | null | undefined, color: string): DataTableCell {
+  const amount = moneyAmount(value);
+  return { text: moneyText(value), ...(amount == null ? {} : { value: amount }), color };
+}
+
 interface BuildoutCellContext {
   favoriteBusyKey: string | null;
   /** The row's last star did not take. */
@@ -40,7 +48,7 @@ export function renderBuildoutCell(
       case "companyCount":
         return { text: list.companyCount == null ? "-" : String(list.companyCount), color: colors.textDim };
       case "totalMarketCap":
-        return { text: text(list.totalMarketCap), color: colors.textDim };
+        return moneyCell(list.totalMarketCap, colors.textDim);
       case "avgSectorGrowth":
         return { text: text(list.avgSectorGrowth), color: metricColor(list.avgSectorGrowth) };
       case "avgReturn1y":
@@ -87,16 +95,16 @@ export function renderBuildoutCell(
       case "criticality":
         return { text: text(company.aiCriticality), color: criticalityColor(company.aiCriticality), attributes: TextAttributes.BOLD };
       case "marketCap":
-        return { text: text(company.marketCap), color: colors.textDim };
+        return moneyCell(company.marketCap, colors.textDim);
       case "revenue":
-        return { text: text(company.revenue), color: colors.textDim };
+        return moneyCell(company.revenue, colors.textDim);
       case "revenueGrowth":
         return {
           text: text(company.revenueGrowthYoy ?? company.lastQuarterGrowth),
           color: metricColor(company.revenueGrowthYoy ?? company.lastQuarterGrowth),
         };
       case "netIncome":
-        return { text: text(company.netIncome), color: metricColor(company.netIncome) };
+        return moneyCell(company.netIncome, metricColor(company.netIncome));
       case "margin":
         return { text: text(company.profitMargins), color: metricColor(company.profitMargins) };
       case "forwardPE":

package/src/plugins/builtin/buildout/format.ts

@@ -44,6 +44,44 @@ export function metricNumber(value: unknown): number | null {
   return (negative ? -parsed : parsed) * multiplier;
 }
 
+/** A dollar figure as the service prints it ("$5094.1B", "$-4.9B"); anything else is not money to reformat. */
+const DOLLAR_STRING = /^-?\$-?[\d,]*\.?\d+\s*[KMBT]?$/i;
+
+/** The dollars in a string the service prints as money, or null for anything else. */
+export function moneyAmount(value: unknown): number | null {
+  return typeof value === "string" && DOLLAR_STRING.test(value.trim()) ? metricNumber(value) : null;
+}
+
+const MONEY_UNITS = [
+  { divisor: 1e12, suffix: "T" },
+  { divisor: 1e9, suffix: "B" },
+  { divisor: 1e6, suffix: "M" },
+  { divisor: 1e3, suffix: "K" },
+] as const;
+
+/**
+ * Dollars in the one compact form every TheBuildout table uses: "$5.1T",
+ * "$356.4B", "-$4.9B". The unit is picked after rounding, so $999.96B is
+ * "$1.0T" and not "$1000.0B".
+ */
+export function formatCompactMoney(amount: number): string {
+  const abs = Math.abs(amount);
+  let index = MONEY_UNITS.findIndex((unit) => abs >= unit.divisor);
+  let digits = index < 0 ? abs.toFixed(0) : (abs / MONEY_UNITS[index]!.divisor).toFixed(1);
+  if (index > 0 && Number(digits) >= 1000) {
+    index -= 1;
+    digits = (abs / MONEY_UNITS[index]!.divisor).toFixed(1);
+  }
+  const sign = amount < 0 && /[1-9]/.test(digits) ? "-" : "";
+  return `${sign}$${digits}${index < 0 ? "" : MONEY_UNITS[index]!.suffix}`;
+}
+
+/** A table cell's text for a dollar figure: compact when it is money, the service's own text otherwise, "-" when absent. */
+export function moneyText(value: string | null | undefined): string {
+  const amount = moneyAmount(value);
+  return amount == null ? text(value) : formatCompactMoney(amount);
+}
+
 export function dateShort(value: string | null | undefined) {
   const date = parseDisplayDate(value);
   if (!date) return "-";

package/src/plugins/builtin/buildout/model/normalizers.ts

@@ -1,4 +1,4 @@
-import { metricNumber, textOrNull, tickerSymbol, uniqueStrings } from "../format";
+import { metricNumber, moneyAmount, textOrNull, tickerSymbol, uniqueStrings } from "../format";
 import type {
   BuildoutCompany,
   BuildoutList,
@@ -124,7 +124,42 @@ export function normalizeList(raw: RawObject): BuildoutList {
   };
 }
 
+/**
+ * The statement figures a depositary receipt can carry in the issuer's
+ * reporting currency under a "$" and the receipt's USD currency: the service
+ * converts a foreign listing's figures and keeps the local ones as "...Original",
+ * but for an ADR it prints the local amounts as they are and names no currency
+ * (SK hynix's receipt shows the won revenue of its Korean listing as dollars).
+ */
+const STATEMENT_FIELDS = ["revenue", "netIncome", "freeCashFlow", "operatingCashFlow", "totalCash", "totalDebt", "dilutedEps"] as const;
+
+/** A yearly figure this many times the company's whole market value is not dollars. */
+const IMPLAUSIBLE_MULTIPLE_OF_MARKET_CAP = 10;
+
+/**
+ * A USD row with nothing converted whose revenue or net income dwarfs its own
+ * market cap has statements in another currency, and the row does not say
+ * which: the figures are left out rather than shown as wrong dollars. The
+ * ordinary range of revenue to market cap is a few times; the rows this
+ * catches sit at 15 to 4,000.
+ */
+function withoutUnconvertedStatements(company: BuildoutCompany): BuildoutCompany {
+  const converted = [company.revenueOriginal, company.netIncomeOriginal].some((value) => textOrNull(value) != null);
+  const usd = (company.currency?.trim().toUpperCase() || "USD") === "USD";
+  const cap = moneyAmount(company.marketCap);
+  if (converted || !usd || cap == null || cap <= 0) return company;
+  const revenue = moneyAmount(company.revenue);
+  const income = moneyAmount(company.netIncome);
+  const limit = cap * IMPLAUSIBLE_MULTIPLE_OF_MARKET_CAP;
+  if ((revenue == null || Math.abs(revenue) <= limit) && (income == null || Math.abs(income) <= limit)) return company;
+  return { ...company, ...Object.fromEntries(STATEMENT_FIELDS.map((field) => [field, null])) };
+}
+
 export function normalizeCompany(raw: RawObject): BuildoutCompany {
+  return withoutUnconvertedStatements(readCompany(raw));
+}
+
+function readCompany(raw: RawObject): BuildoutCompany {
   const ticker = tickerSymbol(stringField(raw, "ticker"));
   const name = stringField(raw, "name") ?? ticker ?? "Company";
   const supplyChain = objectField(raw, "supplyChain", "supply_chain");

package/src/plugins/builtin/buildout/pane/index.tsx

@@ -160,7 +160,10 @@ export function BuildoutPane({ focused, width, height }: PaneProps) {
   const favoriteNotes = useRowNotes<BuildoutRow, string>(rows, { key: favoriteNoteKey });
   const { setNote: setFavoriteNote, noteFor: favoriteNoteFor } = favoriteNotes;
   clearFavoriteNotesRef.current = favoriteNotes.clearNotes;
-  const columns = useMemo(() => columnsForTab(activeTab, selectedList, canFavorite), [activeTab, canFavorite, selectedList]);
+  const columns = useMemo(
+    () => columnsForTab(activeTab, selectedList, canFavorite, width),
+    [activeTab, canFavorite, selectedList, width],
+  );
   const selectedRow = rows[selectedIndex] ?? rows[0] ?? null;
   // The table's cells carry their own badges; this catalog only serves the open
   // detail: its row's tickers, plus the loaded rows' tickers its text mentions.

package/src/plugins/builtin/buildout/table-model.ts

@@ -8,6 +8,7 @@ import type {
   BuildoutTabId,
   SortComparable,
 } from "./model/types";
+import { dropColumnsToFit } from "../../../components/ui/table-layout";
 import type { SortDirection } from "../../../utils/sort-values";
 import { metricNumber, sourceDetailEntries, textOrNull, tickerSymbol } from "./format";
 
@@ -171,9 +172,29 @@ export function activeRows(
   return state.intel.items.map((item) => ({ kind: "intel", item }));
 }
 
-export function columnsForTab(activeTab: BuildoutTabId, selectedList: BuildoutList | null, canFavorite: boolean) {
+/**
+ * What the Companies tab gives up when the pane is too narrow for its figures,
+ * least needed first: the descriptions, then the columns that only add to a
+ * figure already shown, instead of the right edge cutting Market Cap or a
+ * median. The star and the names stay at every width.
+ */
+const LIST_DROP_ORDER: readonly BuildoutColumnId[] = ["listDescription", "avgMargin", "avgReturn1y", "avgSectorGrowth"];
+const COMPANY_DROP_ORDER: readonly BuildoutColumnId[] = [
+  "description", "employees", "dividendYield", "forwardPE", "netIncome", "margin", "sectorTech", "criticality",
+];
+
+/** The columns of a tab for a pane `width` cells wide; the table's scrollbar keeps its cell. */
+export function columnsForTab(
+  activeTab: BuildoutTabId,
+  selectedList: BuildoutList | null,
+  canFavorite: boolean,
+  width: number,
+): BuildoutColumn[] {
   if (activeTab === "companies") {
-    return selectedList && canFavorite ? [favoriteColumn, ...companyColumns] : selectedList ? companyColumns : listColumns;
+    const columns = selectedList
+      ? canFavorite ? [favoriteColumn, ...companyColumns] : companyColumns
+      : listColumns;
+    return dropColumnsToFit(columns, width - 1, selectedList ? COMPANY_DROP_ORDER : LIST_DROP_ORDER);
   }
   if (activeTab === "sites") return canFavorite ? [favoriteColumn, ...siteColumns] : siteColumns;
   return intelColumns;

package/src/plugins/builtin/builtin-plugin-meta.ts

@@ -1,11 +1,14 @@
 // Identity of the built-in composite plugins, shared by the native catalog and
 // the browser catalog (catalog-browser.ts). Keep this file import-free so the
-// browser catalog can read it without pulling in native-only modules.
+// browser catalog can read it without pulling in native-only modules; the
+// one import, ATTN's listing flag, has none of its own.
 //
 // Screeners & Movers and Ownership & Insiders ship fewer panes on
 // the web, so each catalog gives them their own description rather than
 // advertising panes they lack.
 
+import { ATTENTION_LISTED } from "./attention/listing";
+
 export const applicationPluginMeta = {
   id: "application",
   name: "Application",
@@ -116,7 +119,8 @@ export const altDataPluginMeta = {
   stateId: "ticker-research",
   name: "Supply Chain & Alt Data",
   version: "1.0.0",
-  description: "Supply chains and exposure, government awards, hiring, apps and job postings, social mentions, research attention, GPU prices, and power queues.",
+  // Research attention joins once ATTN is listed again (attention/listing.ts).
+  description: `Supply chains and exposure, government awards, hiring, apps and job postings, social mentions, ${ATTENTION_LISTED ? "research attention, " : ""}GPU prices, and power queues.`,
   toggleable: true,
 };
 

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

@@ -11,6 +11,7 @@ import {
 } from "../../../components";
 import { DetailReader } from "../../../components/reader/detail-reader";
 import { loadingErrorFooterInfo, usePaneRefreshKey } from "../../../components/data-table/table-pane";
+import { createTtlCache } from "../../../data/ttl-cache";
 import { fetchChangelogReleases, type ChangelogRelease } from "../../../updater/github-releases";
 import { colors } from "../../../theme/colors";
 import type { PaneProps } from "../../../types/plugin";
@@ -32,7 +33,8 @@ const CHANGELOG_CACHE_TTL_MS = 10 * 60 * 1000;
 
 // Process-lifetime cache. Move it into the updater module if other
 // surfaces start reading releases too.
-let cachedReleases: { releases: ChangelogRelease[]; fetchedAt: number } | null = null;
+const releaseCache = createTtlCache<ChangelogRelease[]>({ ttlMs: CHANGELOG_CACHE_TTL_MS });
+const RELEASES = "releases";
 
 type ChangelogColumn = DataTableColumn & { id: ChangelogColumnId };
 type LoadStatus = "loading" | "loaded" | "error";
@@ -83,10 +85,10 @@ function ChangelogDetail({
 function ChangelogPane({ focused, width, height }: PaneProps) {
   const paneInstance = usePaneInstance();
   const requestedVersion = paneInstance?.params?.version ?? null;
-  const [releases, setReleases] = useState<ChangelogRelease[]>(() => cachedReleases?.releases ?? []);
+  const [releases, setReleases] = useState<ChangelogRelease[]>(() => releaseCache.peek(RELEASES, { stale: true }) ?? []);
   // The mount effect starts the request immediately, so the first paint is a
   // spinner and never "No changelog entries found".
-  const [status, setStatus] = useState<LoadStatus>(() => (cachedReleases ? "loaded" : "loading"));
+  const [status, setStatus] = useState<LoadStatus>(() => (releaseCache.peek(RELEASES, { stale: true }) ? "loaded" : "loading"));
   const [error, setError] = useState<string | null>(null);
   // The selected row and the open release are pane state, so a reload or a
   // shared layout comes back to the same release.
@@ -98,8 +100,9 @@ function ChangelogPane({ focused, width, height }: PaneProps) {
   const requestedVersionOpenedRef = useRef(false);
 
   const loadReleases = useCallback(async (force = false) => {
-    if (!force && cachedReleases && Date.now() - cachedReleases.fetchedAt < CHANGELOG_CACHE_TTL_MS) {
-      setReleases(cachedReleases.releases);
+    const fresh = force ? undefined : releaseCache.peek(RELEASES);
+    if (fresh) {
+      setReleases(fresh);
       setError(null);
       setStatus("loaded");
       return;
@@ -118,7 +121,7 @@ function ChangelogPane({ focused, width, height }: PaneProps) {
 
     try {
       const nextReleases = await fetchChangelogReleases(CHANGELOG_LIMIT, controller.signal);
-      cachedReleases = { releases: nextReleases, fetchedAt: Date.now() };
+      releaseCache.set(RELEASES, nextReleases);
       setReleases(nextReleases);
       setStatus("loaded");
     } catch (loadError) {

package/src/plugins/builtin/chart-composer/catalog-inventory.ts

@@ -31,6 +31,8 @@ export interface CatalogSeriesRow {
   /** The registered expression, `{ticker}` where a symbol goes. */
   template: string;
   url?: string;
+  /** A limit the publisher sets on the series' data, such as how far back its history goes. */
+  limitation?: string;
   /** Asks for a symbol before charting. */
   input?: SeriesInput;
   /** The symbol a row filled in for a typed ticker charts. */
@@ -120,6 +122,7 @@ function rowFromEntry(entry: SeriesCatalogEntry): Omit<CatalogSeriesRow, "order"
     expression,
     template: entry.expression,
     ...(entry.url ? { url: entry.url } : {}),
+    ...(entry.limitation ? { limitation: entry.limitation } : {}),
     ...(entry.input ? { input: entry.input } : {}),
     ...(entry.placement || entry.lines?.length ? {
       seriesName: entry.name,

package/src/plugins/builtin/chart-composer/cli-options.ts

@@ -81,6 +81,10 @@ export function applyChartComposerCapabilityOptions(
     next = { ...next, viewport: { ...next.viewport, extendedHours: true } };
   }
 
+  if (capabilityId === "price-comparison" && options.totalReturn === true) {
+    next = { ...next, viewport: { ...next.viewport, totalReturn: true } };
+  }
+
   if (PRICE_CAPABILITIES.has(capabilityId) && options.axisMode) {
     const transform = options.axisMode === "percent" ? "percent" : "raw";
     next = {

package/src/plugins/builtin/chart-composer/data-catalog-pane.tsx

@@ -4,6 +4,7 @@ import { Box } from "../../../ui";
 import {
   DataTableView,
   QueryBar,
+  usePaneNoticeFooter,
   usePaneTabs,
   useQueryBarSearch,
   type DataTableCell,
@@ -242,6 +243,12 @@ export function DataCatalogPane({ focused, width, height }: PaneProps) {
     }
   }, []);
 
+  usePaneNoticeFooter({
+    registrationId: `${DATA_CATALOG_PANE_ID}:notices`,
+    focused,
+    notices: selectedRow?.limitation ? [`${selectedRow.label}: ${selectedRow.limitation}`] : [],
+  });
+
   usePaneStatusLinkFooter({
     registrationId: DATA_CATALOG_PANE_ID,
     focused,

package/src/plugins/builtin/chart-composer/editor/controller.ts

@@ -10,7 +10,7 @@ import type {
   SeriesTimestampMode,
   SeriesTransform,
 } from "../../../../time-series/types";
-import { hasStudyInputCount, validateChartSpec } from "../../../../time-series/spec";
+import { hasStudyInputCount, isOhlcSeriesStyle, validateChartSpec } from "../../../../time-series/spec";
 import { isPlainKey } from "../../../../utils/keyboard";
 import { getSharedRegistry } from "../../../registry";
 import {
@@ -415,7 +415,7 @@ export function useSeriesEditorController({
         : current.panels,
       series: replaceAt(current.series, selectedIndex, (() => {
         const currentSeries = current.series[selectedIndex]!;
-        const ohlcStyle = currentSeries.style === "candles" || currentSeries.style === "ohlc" || currentSeries.style === "hlc";
+        const ohlcStyle = isOhlcSeriesStyle(currentSeries.style);
         return {
           ...currentSeries,
           style: transform !== "raw" && ohlcStyle

package/src/plugins/builtin/chart-composer/headless-schema.ts

@@ -138,6 +138,12 @@ export const paneSchemas = {
         ],
         defaultValue: "percent",
       },
+      {
+        key: "totalReturn",
+        description: "Reinvest each cash distribution at its ex-date close, so the returns are total returns, not price returns.",
+        type: "boolean",
+        defaultValue: false,
+      },
       {
         key: "chartResolution",
         description: BAR_SIZE_DESCRIPTION,
@@ -151,7 +157,7 @@ export const paneSchemas = {
     discovery: {
       id: "price-comparison",
       aliases: ["stock comparison", "price performance comparison", "returns comparison", "compare stock prices"],
-      limitations: ["Compares closing-price changes in each listing's currency over shared observation dates. Cash distributions and FX conversion are excluded; these are not reinvested total returns."],
+      limitations: ["Compares closing-price changes in each listing's currency over shared observation dates. Cash distributions and FX conversion are excluded unless totalReturn is set, which reinvests each distribution at its ex-date close; FX conversion is never applied."],
       screenshotReadiness: "ready",
     },
   },

package/src/plugins/builtin/chart-composer/headless.ts

@@ -228,6 +228,8 @@ export async function loadChartPaneModel(
         ...reported,
         ...name ? { name } : {},
         ...valueDecimals !== undefined ? { textDecimals: valueDecimals } : {},
+        // A company's reported total (revenue, market cap) reads as 63.33B in the report, as in the legend and the tables.
+        ...series.unitGroup.split(":")[0] === "currency-total" ? { textCompact: true } : {},
         derived: !ids.has(series.id),
         points: series.points.map((point) => ({
           ...point,
@@ -251,7 +253,7 @@ export async function loadChartPaneModel(
       ...(chart.priceHistoryIntegrity?.length ? { priceHistoryIntegrity: chart.priceHistoryIntegrity } : {}),
       ...(valuationPriceIssues.length ? { valuationPriceIssues } : {}),
       ...(periodCoverage.length ? { periodCoverage } : {}),
-      notices: [...chart.warnings.filter((warning) => warning === FINANCIAL_VINTAGE_NOTICE || warning === SEC_EPS_BASIS_NOTICE || warning === chart.priceComparison?.notice
+      notices: [...chart.coverageNotices ?? [], ...chart.returnBasisNotice ? [chart.returnBasisNotice] : [], ...chart.warnings.filter((warning) => warning === FINANCIAL_VINTAGE_NOTICE || warning === SEC_EPS_BASIS_NOTICE || warning === chart.priceComparison?.notice
         || chart.delistings?.some((delisting) => delisting.notice === warning)), ...integrityNotices],
       priceComparison: chart.priceComparison ?? null,
       summaries: chart.series.filter((series) => !series.profile).map((series) => ({ id: series.id, ...summarizeResolvedSeries(series) })),
@@ -723,6 +725,9 @@ export function chartHeadless(template: keyof typeof paneSchemas): HeadlessPaneD
         }, context.marketData) };
       }
       const model = await loadChartPaneModel(spec, context);
+      // A bare coin ticker charted as another listing (ETH, the Grayscale fund) says where the coin is, as `quote` does.
+      const coinNotes = (await Promise.all(listings.values())).flatMap((read) => read?.coinNote ?? []);
+      if (coinNotes.length) model.warnings = [...model.warnings ?? [], ...coinNotes];
       if (template === "graph-intraday-price-pane" && !intradayHistories.length && model.chart.viewport) {
         const { start, end } = model.chart.viewport;
         for (const { target, data } of [

package/src/plugins/builtin/chart-composer/index.tsx

@@ -453,7 +453,7 @@ const chartComposerTemplates: PaneTemplateDef[] = [
     prefix: "CMP",
     aliases: ["COMP", "TRA"],
     label: "Comparison Chart",
-    description: "Compare price returns over shared observation dates for two or more tickers. A leveraged or inverse fund gets its daily objective drawn from its index fund (3× daily QQQ beside TQQQ) and its decay against it.",
+    description: "Compare price returns over shared observation dates for two or more tickers, or total returns with distributions reinvested. A leveraged or inverse fund gets its daily objective drawn from its index fund (3× daily QQQ beside TQQQ) and its decay against it.",
     // Leveraged and inverse funds: the daily line and the decay come with the comparison.
     keywords: ["leveraged", "inverse", "decay", "daily-reset", "daily reset", "volatility decay"],
     argKind: "ticker-list",