@gloom-sh/terminal 0.18.5 → 0.19.1

package/src/utils/crypto-pair.ts

@@ -1,4 +1,4 @@
-import { canonicalExchange, parsePublicTickerKey } from "./exchanges";
+import { canonicalExchange, EXCHANGE_TIME_ZONES, isKnownExchangeCode, parsePublicTickerKey } from "./exchanges";
 
 // The fiat codes a pair against USD is read as FX for, never as a coin. The
 // list Cloud reads: it serves these pairs by the same rule, so a copy judged
@@ -9,8 +9,8 @@ const FIAT_CURRENCY_CODES = new Set([
 ]);
 
 const USD_COIN_PAIR = /^([A-Z0-9]+)[-/]USD$/;
-// The other currencies and coins the crypto venue quotes a coin in (BTC-EUR, ETH-BTC).
-const QUOTED_COIN_PAIR = /^([A-Z0-9]+)[-/](?:USDT|USDC|EUR|GBP|BTC|ETH)$/;
+// The other currencies and coins the crypto venue quotes a coin in (BTC-EUR, BTC-JPY, ETH-BTC).
+const QUOTED_COIN_PAIR = /^([A-Z0-9]+)[-/](?:USDT|USDC|EUR|GBP|JPY|KRW|CAD|INR|CNY|AUD|BTC|ETH)$/;
 
 /** A coin quoted in dollars (BTC-USD, ETH/USD). EUR-USD is spot FX, not a coin. */
 function isUsdCoinPair(symbol: string): boolean {
@@ -35,10 +35,18 @@ export function isRoundTheClockCoin(symbol?: string, exchange?: string): boolean
   const parsed = symbol ? parsePublicTickerKey(symbol) : null;
   const venue = canonicalExchange(parsed?.exchange ?? exchange) || canonicalExchange(exchange);
   if (venue === "CCC" || canonicalExchange(exchange) === "CCC") return true;
+  if (parsed && exchangeLineCoinListing(parsed.symbol, venue)) return true;
   return !!parsed && (isUsdCoinPair(parsed.symbol) || (!venue && isQuotedCoinPair(parsed.symbol)));
 }
 
-const SLASH_COIN_PAIR = /^([A-Z0-9]{1,15})\/(USD|EUR|GBP|USDT|USDC|BTC)$/;
+const SLASH_COIN_PAIR = /^([A-Z0-9]{1,15})\/(USD|EUR|GBP|JPY|KRW|CAD|INR|CNY|AUD|USDT|USDC|BTC|ETH)$/;
+
+/**
+ * What the crypto venue (CCC) quotes a coin in: BTC-GBP, BTC-KRW, LINK-ETH.
+ * It has no coin in a stablecoin (BTC-USDT) or in most other currencies
+ * (BTC-TRY, BTC-BRL).
+ */
+const VENUE_QUOTE_LEGS: ReadonlySet<string> = new Set(["USD", "EUR", "GBP", "JPY", "KRW", "CAD", "INR", "CNY", "AUD", "BTC", "ETH"]);
 
 let isoCurrencyCodes: ReadonlySet<string> | null = null;
 
@@ -58,9 +66,114 @@ export function dashedCoinPair(symbol: string): string | null {
   return `${match[1]}-${match[2]}`;
 }
 
+/**
+ * The crypto exchanges whose own lines of a coin pair search lists in a currency the crypto venue quotes coins in,
+ * and the venue itself. A slash pair saved on any other venue, or on none, is not read as a coin: on the commodity
+ * or currency venue it is spot crude, gold by the gram or a currency (WTI/USD, GAU/USD, RUB/USD).
+ */
+const COIN_EXCHANGES: ReadonlySet<string> = new Set([
+  "CCC", "BIGONE", "BINANCE", "BITBANK", "BITBNS", "BITFINEX", "BITFLYER", "BITHUMB", "BITMART", "BITRUE", "BITSTAMP",
+  "BTC MARKETS", "BYBIT", "CEX.IO", "COINBASE PRO", "COINONE", "CRYPTO.COM EXCHANGE", "FREIEXCHANGE", "GATE.IO", "HITBTC",
+  "HUOBI", "INDEPENDENT RESERVE", "KRAKEN", "KUCOIN", "LATOKEN", "MEXC", "MXC", "OKEX", "OKX", "POLONIEX", "SYNTHETIC",
+  "UNISWAP", "UPBIT", "WAZIRX", "XT.COM", "YOBIT", "ZAIF",
+]);
+
+/** Venues whose slash pairs are commodities or currencies, never coins, whatever a row's type says. */
+const NOT_COIN_VENUES: ReadonlySet<string> = new Set(["COMMODITY", "CCY", "FX", "FOREX", "CURRENCY", "PHYSICAL CURRENCY"]);
+
+/**
+ * Spot commodities written as a pair: gold, silver, platinum and palladium, gold and silver by the gram (GAU,
+ * XAGG), WTI, Brent (XBR) and Urals crude, and copper (HG1). Never a coin, though tokens share the letters
+ * (GAU-USD is Gamer Arena).
+ */
+const SPOT_COMMODITY_BASES: ReadonlySet<string> = new Set(["XAU", "GAU", "XAG", "XAGG", "XPT", "XPD", "WTI", "XBR", "URALS", "HG1"]);
+
+/** A spot commodity's pair (WTI/USD, GAU/USD) or a pair on the commodity or currency venue, which no coin is. */
+export function isSpotCommodityOrCurrencyPair(symbol: string, exchange?: string): boolean {
+  const parsed = parsePublicTickerKey(symbol.trim().toUpperCase());
+  const named = (parsed.exchange ?? exchange ?? "").trim().toUpperCase();
+  const base = /^([A-Z0-9]{1,15})\//.exec(parsed.symbol)?.[1];
+  return !!base && (SPOT_COMMODITY_BASES.has(base) || NOT_COIN_VENUES.has(named) || NOT_COIN_VENUES.has(canonicalExchange(named)));
+}
+
+/** The crypto venue's listing of a coin pair written with a slash (BTC/GBP); null for a currency, a spot commodity or another leg. */
+function slashCoinPairListing(symbol: string): { symbol: string; exchange: "CCC"; currency: string } | null {
+  const match = SLASH_COIN_PAIR.exec(symbol.trim().toUpperCase());
+  if (!match) return null;
+  const [, base, quote] = match as unknown as [string, string, string];
+  if (isIsoCurrencyCode(base) || SPOT_COMMODITY_BASES.has(base) || !VENUE_QUOTE_LEGS.has(quote)) return null;
+  return { symbol: `${base}-${quote}`, exchange: "CCC", currency: quote };
+}
+
+/**
+ * A crypto exchange's own line of a coin pair (BTC/GBP on COINBASE PRO, LINK/EUR on KRAKEN, DOGE/BTC on BINANCE)
+ * as the crypto venue's listing of it, in the currency it is quoted in: BTC-GBP on CCC, in pounds. Search offers
+ * those lines, and no source quotes them.
+ *
+ * Only a pair on a crypto exchange (COIN_EXCHANGES) is one, or a search row whose type says it is a coin
+ * (`coinRow`) on a venue that is no stock, commodity or currency venue. Null for a currency pair (EUR/USD,
+ * RUB/USD), a spot commodity (XAU/USD, WTI/USD), a pair the venue quotes in no such currency (BTC/USDT), a pair
+ * with no venue, and a slash on a stock exchange, which is a share class (BRK/B).
+ */
+export function exchangeLineCoinListing(
+  symbol: string,
+  exchange?: string,
+  { coinRow = false }: { coinRow?: boolean } = {},
+): { symbol: string; exchange: "CCC"; currency: string } | null {
+  const parsed = parsePublicTickerKey(symbol);
+  const listing = slashCoinPairListing(parsed.symbol);
+  if (!listing) return null;
+  const named = (parsed.exchange ?? exchange ?? "").trim().toUpperCase();
+  const venue = canonicalExchange(named);
+  if (COIN_EXCHANGES.has(named) || COIN_EXCHANGES.has(venue)) return listing;
+  if (!coinRow || !venue || NOT_COIN_VENUES.has(named) || NOT_COIN_VENUES.has(venue)) return null;
+  // The crypto venues trade around the clock; a venue the app knows that does not is a stock exchange.
+  return isKnownExchangeCode(venue) && EXCHANGE_TIME_ZONES[venue] !== "UTC" ? null : listing;
+}
+
+/**
+ * A coin pair typed with a slash (btc/gbp) as the crypto venue's listing of it, BTC-GBP on CCC; with a venue
+ * (BTC/GBP:KRAKEN), as that exchange's line reads (exchangeLineCoinListing). Null for a currency pair, a spot
+ * commodity (wti/usd) and a pair the venue quotes in no such currency.
+ */
+export function typedCoinPairListing(query: string): { symbol: string; exchange: "CCC"; currency: string } | null {
+  const parsed = parsePublicTickerKey(query.trim().toUpperCase());
+  return parsed.exchange ? exchangeLineCoinListing(parsed.symbol, parsed.exchange) : slashCoinPairListing(parsed.symbol);
+}
+
+/**
+ * Search rows with each crypto exchange's line of a coin pair (ETH/EUR on KRAKEN, COINBASE PRO, BITSTAMP and
+ * BINANCE) as the crypto venue's one listing of it, ETH-EUR on CCC in euros, where the first line stood. A pair
+ * already offered on the venue is not offered twice. Newer servers send the listing themselves.
+ */
+export function withExchangeLinesAsCoinListings<T extends { symbol: string; exchange: string; type: string; currency?: string; brokerContract?: unknown }>(rows: T[]): T[] {
+  const offered = new Set(rows.filter((row) => canonicalExchange(row.exchange) === "CCC").map((row) => row.symbol.trim().toUpperCase()));
+  let changed = false;
+  const mapped = rows.flatMap((row) => {
+    const coin = !row.brokerContract && isCoinRowType(row.type) ? exchangeLineCoinListing(row.symbol, row.exchange, { coinRow: true }) : null;
+    if (!coin) return [row];
+    changed = true;
+    if (offered.has(coin.symbol)) return [];
+    offered.add(coin.symbol);
+    return [{ ...row, symbol: coin.symbol, exchange: coin.exchange, currency: row.currency || coin.currency }];
+  });
+  return changed ? mapped : rows;
+}
+
+/** Whether a search row's type says it is a coin (CRYPTOCURRENCY, Digital Currency). */
+export function isCoinRowType(type: string | undefined): boolean {
+  return /CRYPTO|DIGITAL|COIN/i.test(type ?? "");
+}
+
+/** The currency or coin a pair on the crypto venue is quoted in: GBP for BTC-GBP; null for anything else. */
+export function coinPairQuoteCurrency(symbol: string): string | null {
+  const match = /^([A-Z0-9]{1,15})-([A-Z]{3})$/.exec(parsePublicTickerKey(symbol).symbol);
+  return match && !isIsoCurrencyCode(match[1]!) && VENUE_QUOTE_LEGS.has(match[2]!) ? match[2]! : null;
+}
+
 // A base-quote pair such as BTC-USD or SOL-EUR. Equities with a share-class dash (BRK-B) and
 // currency pairs (EURUSD=X) do not match.
-const CRYPTO_PAIR = /^[A-Z0-9]{1,15}-(?:USD|EUR|GBP|USDT|USDC|BTC)$/;
+const CRYPTO_PAIR = /^[A-Z0-9]{1,15}-(?:USD|EUR|GBP|JPY|KRW|CAD|INR|CNY|AUD|USDT|USDC|BTC|ETH)$/;
 
 /**
  * Wider than isUsdCoinPair, for the hint under a pair that will not load: it
@@ -91,9 +204,54 @@ export const MAJOR_COIN_NAMES: ReadonlyMap<string, string> = new Map([
   ["BNB", "BNB"],
 ]);
 
-const COIN_PAIR = /^([A-Z0-9]{1,15})[-/](?:USD|EUR|GBP|USDT|USDC|BTC)$/;
+/**
+ * The largest coins by market value, stablecoins and gold tokens left out, with
+ * how a note names each: the coins whose bare ticker a listed company or fund
+ * may hold instead (SOL is a stale Emeren Group, LINK is Interlink Electronics).
+ * A hint reads this list; `MAJOR_COIN_NAMES` stays the shorter one stories and
+ * company-name lookups use, so a word such as "stellar" is still a company's.
+ */
+export const TOP_COIN_NAMES: ReadonlyMap<string, string> = new Map([
+  ...MAJOR_COIN_NAMES,
+  ["TRX", "tron"],
+  ["ZEC", "zcash"],
+  ["HYPE", "hyperliquid"],
+  ["XMR", "monero"],
+  ["XLM", "stellar"],
+  ["NEAR", "near protocol"],
+  ["TON", "toncoin"],
+  ["UNI", "uniswap"],
+  ["SUI", "sui"],
+  ["HBAR", "hedera"],
+  ["TAO", "bittensor"],
+  ["SHIB", "shiba inu"],
+  ["ENA", "ethena"],
+  ["CRO", "cronos"],
+  ["AAVE", "aave"],
+  ["ONDO", "ondo"],
+  ["PEPE", "pepe"],
+  ["ICP", "internet computer"],
+  ["ETC", "ethereum classic"],
+  ["ARB", "arbitrum"],
+  ["ALGO", "algorand"],
+  ["ATOM", "cosmos"],
+  ["APT", "aptos"],
+  ["FIL", "filecoin"],
+  ["POL", "polygon"],
+  ["OP", "optimism"],
+  ["WLD", "worldcoin"],
+  ["MNT", "mantle"],
+  ["KAS", "kaspa"],
+  ["QNT", "quant"],
+  ["VET", "vechain"],
+  ["INJ", "injective"],
+  ["RENDER", "render"],
+]);
+
+const COIN_PAIR = /^([A-Z0-9]{1,15})[-/](?:USD|EUR|GBP|JPY|KRW|CAD|INR|CNY|AUD|USDT|USDC|BTC|ETH)$/;
 // What a pair's listing name adds after the coin's: its quote currency, an id in brackets.
-const PAIR_NAME_SUFFIX = /(?:\s*\([^)]*\))+$|\s+(?:USD|EUR|GBP|USDT|USDC|BTC|US Dollars?)$/i;
+// Not ETH, which ends coins' own names (Lido Staked ETH).
+const PAIR_NAME_SUFFIX = /(?:\s*\([^)]*\))+$|\s+(?:USD|EUR|GBP|JPY|KRW|CAD|INR|CNY|AUD|USDT|USDC|BTC|US Dollars?)$/i;
 
 /**
  * The coin a crypto pair trades, as stories name it: "bitcoin" for BTC-USD

package/src/utils/declared-dividends.ts

@@ -34,6 +34,6 @@ export function declaredDividends(
     const at = Date.parse(`${exDate}T00:00:00Z`);
     if (paid.some((time) => Math.abs(time - at) <= SAME_DISTRIBUTION_DAYS * DAY_MS)) return [];
     return [{ exDate, amount: row.amount, ...declarationDate ? { declarationDate } : {},
-      ...recordDate ? { recordDate } : {}, ...payDate ? { payDate } : {} }];
+      ...recordDate ? { recordDate } : {}, ...payDate ? { payDate } : {}, ...row.special === true ? { special: true as const } : {} }];
   }).sort((left, right) => left.exDate.localeCompare(right.exDate));
 }

package/src/utils/forward-dividend.ts

@@ -14,6 +14,8 @@ import { formatDistributionAmount } from "./format";
  * the rate divided back.
  */
 export const LATEST_DISTRIBUTION = "latest distribution annualized";
+/** The basis of a forward rate that is the year's regular payments, which differ too widely for one to be annualized (unevenRegularPayments). */
+export const UNEVEN_REGULAR_PAYMENTS = "trailing regular payments: uneven interims";
 
 /**
  * What a trailing dividend yield is everywhere it shows (DVD, a fund's in

package/src/utils/fundamentals.ts

@@ -2,20 +2,24 @@ import { formatFxRate } from "../cli/fx-pair";
 import type { EnterpriseValueCheck, Fundamentals, Quote, TickerFinancials } from "../types/financials";
 import { quotedFxPair } from "./currency-pair";
 import { resolveCurrencyUnit } from "./currency-units";
+import { isUsListingExchange } from "./exchanges";
 import { formatCompact } from "./format";
 import { formatUtcTime } from "./utc-time";
 
 export const RETRACTABLE_VALUATION_FIELDS = ["enterpriseValue", "enterpriseToRevenue"] as const;
+/** Every field a source can retract: the valuation fields, and a receipt's market cap (`marketCapUnavailable`). */
+export const RETRACTED_FUNDAMENTALS_FIELDS = [...RETRACTABLE_VALUATION_FIELDS, "marketCap"] as const;
 
-/** A retraction survives serialization and overrides a contradictory cached number. */
+/** A retraction survives serialization and overrides a contradictory cached number; its reason goes with it. */
 export function redactUnavailableFundamentals(value: Fundamentals | undefined): Fundamentals | undefined {
-  if (!value || value.unavailableFields === undefined) return value;
+  if (!value || (value.unavailableFields === undefined && value.marketCapUnavailable === undefined)) return value;
   const unavailableFields = Array.isArray(value.unavailableFields)
-    ? RETRACTABLE_VALUATION_FIELDS.filter((field) => value.unavailableFields!.includes(field)) : [];
+    ? RETRACTED_FUNDAMENTALS_FIELDS.filter((field) => value.unavailableFields!.includes(field)) : [];
   const result = { ...value };
   if (unavailableFields.length) result.unavailableFields = unavailableFields;
   else delete result.unavailableFields;
   for (const field of unavailableFields) delete result[field];
+  if (!unavailableFields.includes("marketCap")) delete result.marketCapUnavailable;
   return result;
 }
 
@@ -116,24 +120,53 @@ export function computedEnterpriseValueNote(fundamentals: Parameters<typeof ente
 }
 
 /** What names the currency of the trailing figures: the fundamentals' own labels, else the statements' on a listing that trades in theirs. */
-type FundamentalsCurrencies = Pick<TickerFinancials, "financialCurrency"> & {
+type FundamentalsCurrencies = Pick<TickerFinancials, "financialCurrency" | "statementHistory"> & {
   fundamentals?: Pick<Fundamentals, "financialCurrency" | "epsCurrency" | "marketCapCurrency"> | null;
-  quote?: Pick<Quote, "currency"> | null;
+  quote?: Pick<Quote, "currency" | "exchangeName" | "listingExchangeName" | "isDepositaryReceipt"> | null;
 };
 
+/** What a caller knows of the listing beyond its quote: the day it listed (its IPO's), when known. */
+interface ListingAge {
+  listedSince?: string | null;
+  now?: Date;
+}
+
+/** A listing that started within about a year: its statements may not be served yet. */
+const RECENT_LISTING_DAYS = 372;
+
+/**
+ * The listing's own currency, standing in for figures with no statements to tell their currency by: only for a
+ * listing of the last year or so (a recent IPO such as HAWK) or a US listing in dollars that is no receipt, and
+ * never after a statements read that failed. A minor unit (GBp) does not say whether figures are pence or pounds.
+ */
+function listingCurrencyFallback(financials: FundamentalsCurrencies | null | undefined, listing: ListingAge): string | undefined {
+  const listed = financials?.fundamentals?.marketCapCurrency?.trim() || financials?.quote?.currency?.trim();
+  if (!listed || resolveCurrencyUnit(listed).divisor !== 1) return undefined;
+  if (financials?.statementHistory?.status === "retryable-failure") return undefined;
+  const currency = resolveCurrencyUnit(listed).currency;
+  const since = listing.listedSince ? Date.parse(`${listing.listedSince.slice(0, 10)}T00:00:00Z`) : NaN;
+  const recent = Number.isFinite(since) && (listing.now ?? new Date()).getTime() - since <= RECENT_LISTING_DAYS * 86_400_000;
+  const quote = financials?.quote;
+  const home = currency === "USD" && quote?.isDepositaryReceipt !== true
+    && isUsListingExchange(quote?.listingExchangeName || quote?.exchangeName);
+  return recent || home ? currency : undefined;
+}
+
 /**
  * The currency of the trailing EPS, revenue, income and cash flows: the one the fundamentals declare for themselves.
  * A block that declares none is in the statements' currency only when the listing trades in it; on a listing quoted
  * in another (a receipt in USD beside TWD books, YPFD in ARS beside USD statements) its currency is unknown, since
- * Gloom Cloud labels every block whose currency it can tell. Never the quote's.
+ * Gloom Cloud labels every block whose currency it can tell. With no statements to tell by, the listing's own
+ * currency where that is safe (listingCurrencyFallback).
  */
 export function fundamentalsCurrency(
   financials: FundamentalsCurrencies | null | undefined,
+  listing: ListingAge = {},
 ): string | undefined {
   const declared = financials?.fundamentals?.financialCurrency?.trim();
   if (declared) return declared;
   const statements = financials?.financialCurrency?.trim();
-  if (!statements) return undefined;
+  if (!statements) return listingCurrencyFallback(financials, listing);
   const listed = financials?.fundamentals?.marketCapCurrency?.trim() || financials?.quote?.currency?.trim();
   return !listed || resolveCurrencyUnit(listed).currency === resolveCurrencyUnit(statements).currency ? statements : undefined;
 }
@@ -144,8 +177,9 @@ export function fundamentalsCurrency(
  */
 export function fundamentalsEpsCurrency(
   financials: FundamentalsCurrencies | null | undefined,
+  listing: ListingAge = {},
 ): string | undefined {
-  return financials?.fundamentals?.epsCurrency?.trim() || fundamentalsCurrency(financials);
+  return financials?.fundamentals?.epsCurrency?.trim() || fundamentalsCurrency(financials, listing);
 }
 
 const ISO_DAY = /^\d{4}-\d{2}-\d{2}$/;
@@ -243,6 +277,24 @@ export function epsConversionNote(fundamentals: Pick<Fundamentals, "financialCur
   return eps && amounts && eps !== amounts ? `EPS (TTM) in ${eps}, converted from ${amounts} at report-date rates.` : undefined;
 }
 
+/** What a trailing EPS that is not the filed quarters' is called where it is shown (EE's TTM row). */
+export const SERVED_TRAILING_EPS = "Gloom Cloud's TTM";
+
+/**
+ * "EPS (TTM) and P/E (TTM) are Gloom Cloud's trailing figures, not the last four filed quarters'.": the headline EPS
+ * and P/E are the filed quarters' (time-series/filed-trailing-eps), so served ones say so, naming those `shown`
+ * ("P/E (TTM) is Gloom Cloud's trailing figure, ..." for a fund's P/E with no EPS). Undefined otherwise.
+ */
+export function trailingEpsSourceNote(
+  fundamentals: Pick<Fundamentals, "trailingEpsSource"> | undefined,
+  shown: { eps: boolean; pe: boolean },
+): string | undefined {
+  if (fundamentals?.trailingEpsSource !== "served" || (!shown.eps && !shown.pe)) return undefined;
+  const figures = shown.eps && shown.pe ? "EPS (TTM) and P/E (TTM) are Gloom Cloud's trailing figures"
+    : `${shown.eps ? "EPS (TTM)" : "P/E (TTM)"} is Gloom Cloud's trailing figure`;
+  return `${figures}, not the last four filed quarters'.`;
+}
+
 type PriceEarningsBasis = Pick<Fundamentals, "financialCurrency" | "ttmConversion" | "epsCurrency" | "trailingPEConversion">;
 
 /** The trailing EPS in the price's currency: converted at the rate the served P/E used when it says so. */

package/src/utils/fx-market-hours.ts

@@ -30,12 +30,35 @@ export function isFxMarketOpen(time: number): boolean {
 }
 
 /**
- * The FX trading day an instant belongs to, as "YYYY-MM-DD": the day rolls
- * at 17:00 New York time, so Wednesday 18:00 New York is Thursday's.
+ * The FX trading day a print made at `time` belongs to, as "YYYY-MM-DD": the
+ * day rolls at 17:00 New York time, so Wednesday 18:00 New York is
+ * Thursday's. A print stamped exactly 17:00:00 is that day's close, so it is
+ * still that day's.
  */
 export function fxTradingDay(time: number): string {
   // The roll is 17:00, seven hours before New York's midnight, daylight saving or not.
-  return zonedDateKey(time + 7 * HOUR_MS, NEW_YORK);
+  return zonedDateKey(time - 1 + 7 * HOUR_MS, NEW_YORK);
+}
+
+/**
+ * The FX trading day of a print made at `time` (fxTradingDay), or null for a
+ * print made while the market is shut: from just after Friday's 17:00 New
+ * York close, whose own print still counts, through Sunday's 17:00 open. A
+ * tick over the weekend belongs to no trading day.
+ */
+export function fxPrintTradingDay(time: number): string | null {
+  return Number.isFinite(time) && isFxMarketOpen(time - 1) ? fxTradingDay(time) : null;
+}
+
+/**
+ * The FX trading day the market is on at `time`: the day in progress while it
+ * trades, or the Friday that closed it while it is shut.
+ */
+export function fxTradingDayAt(time: number): string | null {
+  const day = fxPrintTradingDay(time);
+  if (day != null || !Number.isFinite(time)) return day;
+  const shut = currentFxClosureStart(time - 1);
+  return shut != null ? fxTradingDay(shut) : null;
 }
 
 /** The latest 17:00 New York on `weekday` (0 is Sunday) at or before `time`. */

package/src/utils/main-thread-stall.ts

@@ -9,13 +9,43 @@ const SAMPLE_INTERVAL_MS = 250;
  */
 const STALL_THRESHOLD_MS = 400;
 
+export interface StallEvent {
+  blockedMs: number;
+  /** The last measured section before the stall (perf-marks), if any. */
+  lastMeasured?: string;
+  /** How long before the stall was noticed that section ended. */
+  lastMeasuredEndedMsAgo?: number;
+}
+
+let stallSink: ((event: StallEvent) => void) | null = null;
+
+/**
+ * Where this process's stalls go besides the Debug Log: the stall log and its
+ * report (telemetry/stall-reports.ts), or, in the desktop window, the Bun
+ * process that keeps them.
+ */
+export function setStallSink(next: ((event: StallEvent) => void) | null): () => void {
+  stallSink = next;
+  return () => {
+    if (stallSink === next) stallSink = null;
+  };
+}
+
+function noteStall(event: StallEvent): void {
+  try {
+    stallSink?.(event);
+  } catch {
+    // Intentional ignore: reporting a freeze must never become one.
+  }
+}
+
 export interface MainThreadStallMonitorOptions {
   intervalMs?: number;
   thresholdMs?: number;
   now?: () => number;
   schedule?: (callback: () => void, delayMs: number) => unknown;
   cancel?: (handle: unknown) => void;
-  report?: (blockedMs: number, context: Record<string, unknown>) => void;
+  report?: (blockedMs: number, context: Omit<StallEvent, "blockedMs">) => void;
 }
 
 function defaultNow(): number {
@@ -41,7 +71,10 @@ export function startMainThreadStallMonitor(
   const schedule = options.schedule ?? ((callback, delayMs) => setInterval(callback, delayMs));
   const cancel = options.cancel ?? ((handle) => clearInterval(handle as ReturnType<typeof setInterval>));
   const report = options.report
-    ?? ((blockedMs, context) => recordPerfSample("runtime.stall", blockedMs, context));
+    ?? ((blockedMs, context) => {
+      recordPerfSample("runtime.stall", blockedMs, context);
+      noteStall({ blockedMs, ...context });
+    });
 
   let previous = now();
   const handle = schedule(() => {

package/src/utils/market-capitalization.ts

@@ -20,11 +20,34 @@ function explicitCurrency(currency: string | undefined): currency is string {
   return currency != null && /^[A-Z]{3}$/.test(currency);
 }
 
-/** A lightweight quote can omit capitalization without invalidating the snapshot. */
+/** What every view says for a cap Gloom Cloud withheld, in the words its screener uses. */
+const WITHHELD_MARKET_CAP: Record<NonNullable<Fundamentals["marketCapUnavailable"]>, { gap: string; note: string }> = {
+  "receipt-priced-as-ordinary": {
+    gap: "receipt, no ratio",
+    note: "No market cap: a depositary receipt with no known ratio, whose source's cap is the receipt price x the company's ordinary shares.",
+  },
+};
+
+/**
+ * Why a listing has no market cap when Gloom Cloud withheld it: `gap` for a cell, `note` for a line under a
+ * report. Null when the cap was not withheld.
+ */
+export function withheldMarketCap(fundamentals: Pick<Fundamentals, "unavailableFields" | "marketCapUnavailable"> | undefined):
+  { gap: string; note: string } | null {
+  if (!fundamentals?.unavailableFields?.includes("marketCap")) return null;
+  const reason = fundamentals.marketCapUnavailable ? WITHHELD_MARKET_CAP[fundamentals.marketCapUnavailable] : undefined;
+  return reason ?? { gap: "withheld", note: "No market cap: Gloom Cloud withheld it." };
+}
+
+/**
+ * A lightweight quote can omit capitalization without invalidating the snapshot. A cap Gloom Cloud withheld
+ * (withheldMarketCap) is none, the quote's included.
+ */
 export function selectMarketCapitalization(
   quote: Quote | undefined,
   fundamentals: Fundamentals | undefined,
 ): MarketCapitalization | null {
+  if (withheldMarketCap(fundamentals)) return null;
   if (usableValue(quote?.marketCap) && explicitCurrency(quote?.currency)) {
     return { value: quote.marketCap, currency: quote.currency,
       provenance: { kind: "quote", source: quote.providerId } };

package/src/utils/price-history.ts

@@ -2,7 +2,7 @@ import type { PricePoint, TickerFinancials } from "../types/financials";
 import { canonicalExchange } from "./exchanges";
 import { isRoundTheClockCoin } from "./crypto-pair";
 import { isCurrencyPairListing, isFxMarketOpen, latestFxWeekClose, latestFxWeekOpen } from "./fx-market-hours";
-import { hasPublishedSessionCalendar, historySourceWeekendDays, latestRegularSessionClose, latestRegularSessionOpen, sessionCalendarTimeZone } from "../market-data/market/freshness";
+import { hasPublishedSessionCalendar, historySourceWeekendDays, isMiddayBreakPrint, latestRegularSessionClose, latestRegularSessionOpen, sessionCalendarTimeZone } from "../market-data/market/freshness";
 import { zonedDateTimeParts } from "./zoned-date-time";
 import { regularHistorySessionStaleness } from "../market-data/history-session";
 import type { HistorySession } from "../types/price-history";
@@ -234,6 +234,12 @@ export function isPriceHistoryStaleForCurrentWindow(
   const age = now - latestTime;
   const allowedLag = allowedBarLagMs(intervalMs);
   if (age <= allowedLag) return false;
+  // A venue paused at midday (SSE/SZSE/BSE, TKO, ...) holds the morning's last
+  // bar current through the break, as the quote freshness rule does. A bar is
+  // labelled by its start, so an hourly bar ending at the break is judged by
+  // when it ends.
+  const latestBarEnd = intervalMs != null ? Math.min(latestTime + intervalMs, now) : latestTime;
+  if (isMiddayBreakPrint(latestBarEnd, options.exchange, now, 0)) return false;
   const sessions = listingSessionsAt(now, options);
   if (!sessions) return age > UNSCHEDULED_HISTORY_MAX_AGE_MS;
   const fetchedAt = options.fetchedAt ?? Number.NEGATIVE_INFINITY;

package/src/utils/shell-word.ts

@@ -0,0 +1,8 @@
+/**
+ * One word of a command line as a shell reads it back: as written when it
+ * holds nothing a shell treats specially (`NVDA`, `SAN:EPA`, `BRK.B`), else
+ * in single quotes (`'Altria Group'`, `'$nvda'`, `'AT&T'`).
+ */
+export function shellWord(word: string): string {
+  return /^[\p{L}\p{N}._:@%+,/][\p{L}\p{N}._:@%+,/=-]*$/u.test(word) ? word : `'${word.replaceAll("'", "'\\''")}'`;
+}

package/src/utils/trailing-dividend.ts

@@ -51,7 +51,9 @@ export function inferCadence(payments: readonly Pick<CashDistribution, "exDate">
 }
 
 /**
- * Trailing twelve-month cash as known at `asOf`, one payment per regular period.
+ * The payments trailing twelve-month cash is made of as known at `asOf`, one
+ * per regular period, and how many a year the issuer's cadence pays (null
+ * without a regular cadence).
  *
  * A fixed one-year ex-date window counts a fifth quarterly (or thirteenth
  * monthly) payment when this year's ex-date is a few days earlier than last
@@ -61,13 +63,13 @@ export function inferCadence(payments: readonly Pick<CashDistribution, "exDate">
  * the window holds fewer than one year of payments. Irregular cash uses the
  * plain window, so special distributions are neither dropped nor extended.
  */
-export function trailingCashAt<Payment extends CashDistribution>(payments: readonly Payment[], asOf: Date): number {
+function trailingPayments<Payment extends CashDistribution>(payments: readonly Payment[], asOf: Date): { counted: Payment[]; perYear: number | null; cadence: DistributionCadence | null } {
   const known = payments.filter((payment) => payment.exDate <= asOf && Number.isFinite(payment.amount) && payment.amount > 0)
     .sort((a, b) => a.exDate.getTime() - b.exDate.getTime());
   const cutoff = calendarMonthsBefore(asOf, 12);
   const cadence = inferCadence(known, asOf);
   const regular = cadence ? REGULAR_CADENCE[cadence] : undefined;
-  if (!regular) return known.filter((payment) => payment.exDate > cutoff).reduce((sum, payment) => sum + payment.amount, 0);
+  if (!regular) return { counted: known.filter((payment) => payment.exDate > cutoff), perYear: null, cadence };
 
   const halfPeriod = regular.halfPeriodDays * DAY;
   const graceCutoff = new Date(cutoff.getTime() - Math.min(regular.halfPeriodDays, MAX_LATE_GRACE_DAYS) * DAY);
@@ -94,7 +96,54 @@ export function trailingCashAt<Payment extends CashDistribution>(payments: reado
   const late = candidates.filter((payment) => payment.exDate <= cutoff && payment.exDate > graceCutoff && !superseded.has(payment))
     .reverse()
     .slice(0, Math.max(0, regular.perYear - counted.length));
-  return [...counted, ...late].reduce((sum, payment) => sum + payment.amount, 0);
+  return { counted: [...counted, ...late], perYear: regular.perYear, cadence };
+}
+
+/** Trailing twelve-month cash as known at `asOf` (trailingPayments). */
+export function trailingCashAt<Payment extends CashDistribution>(payments: readonly Payment[], asOf: Date): number {
+  return trailingPayments(payments, asOf).counted.reduce((sum, payment) => sum + payment.amount, 0);
+}
+
+/** How many payments trailing cash counts against how many a year the issuer's cadence pays. */
+export interface TrailingPayments {
+  counted: number;
+  expected: number;
+  cadence: DistributionCadence;
+}
+
+/**
+ * The payments a regular payer's trailing cash counts when it is fewer than
+ * its cadence pays in a year: a hole in the history (ECC's monthly July to
+ * September 2026 distributions), a missed or late payment, or a fund under a
+ * year old. Null for a full year, an irregular payer and an issuer with no
+ * cadence, whose trailing cash is the plain window.
+ */
+export function trailingPaymentShortfall(payments: readonly CashDistribution[], asOf: Date): TrailingPayments | null {
+  const { counted, perYear, cadence } = trailingPayments(payments, asOf);
+  return perYear != null && cadence && counted.length < perYear ? { counted: counted.length, expected: perYear, cadence } : null;
+}
+
+/** Over this ratio between a regular payer's largest and smallest payment of a year, no one payment stands for the year. */
+const UNEVEN_PAYMENT_RATIO = 1.5;
+
+/**
+ * A regular payer's payments of the trailing year when they differ widely:
+ * exactly as many as its cadence pays, the largest more than 1.5 times the
+ * smallest (HSBC's final beside its interims, AstraZeneca's interim beside its
+ * final). Their total is the year's cash, where the latest one annualized is
+ * not (HSBA's interim read as 2.17% a year beside the 4.08% it paid). Null for
+ * an even year, one with a hole or an extra payment, an annual payer and an
+ * irregular one. `latest` is the newest payment's ex-date.
+ */
+export function unevenRegularPayments(payments: readonly CashDistribution[], asOf: Date): { total: number; latest: Date } | null {
+  const { counted, perYear } = trailingPayments(payments, asOf);
+  if (perYear == null || perYear < 2 || counted.length !== perYear) return null;
+  const amounts = counted.map((payment) => payment.amount);
+  if (Math.max(...amounts) <= UNEVEN_PAYMENT_RATIO * Math.min(...amounts)) return null;
+  return {
+    total: atSourcePrecision(amounts.reduce((sum, amount) => sum + amount, 0)),
+    latest: new Date(Math.max(...counted.map((payment) => payment.exDate.getTime()))),
+  };
 }
 
 /** A history row as a paid distribution; null when its date is not a calendar day or its amount is no cash. */

package/src/version.ts

@@ -3,7 +3,7 @@ import packageJson from "../package.json" with { type: "json" };
 export const VERSION = packageJson.version;
 
 /**
- * The npm package this copy came from: `gloomberb`, or `@gloom-sh/terminal`
- * once releases are also published under that name.
+ * The npm package this copy came from: `@gloom-sh/terminal` or `gloomberb`,
+ * which every release publishes with the same build.
  */
 export const PACKAGE_NAME = packageJson.name;

package/src/plugins/builtin/clinical-trials/ticker-sponsor.ts

@@ -1,17 +0,0 @@
-import type { DataProvider } from "../../../types/data-provider";
-import { shortCompanyName } from "../../../tickers/company-name";
-import { classifyInstrumentKind } from "../../../tickers/search/ranking";
-
-/**
- * The company a ticker is, by the name a registry files its studies under:
- * VKTX is "Viking Therapeutics". Read from the listing's quote, which names
- * it; a fund or a contract is no sponsor. Null when no share trades under it.
- */
-export async function tickerSponsorName(dataProvider: Pick<DataProvider, "getQuote"> | null, ticker: string): Promise<string | null> {
-  const symbol = ticker.trim().toUpperCase();
-  if (!dataProvider || !symbol) return null;
-  const quote = await dataProvider.getQuote(symbol).catch(() => null);
-  const name = quote?.name?.trim();
-  const kind = classifyInstrumentKind(quote?.instrumentType);
-  return name && kind !== "fund" && kind !== "derivative" ? shortCompanyName(name) : null;
-}