@gloom-sh/terminal 0.18.5 → 0.19.0

package/src/time-series/total-return.ts

@@ -0,0 +1,160 @@
+import type { CorporateActionsData } from "../types/financials";
+import { cashInMajorUnits } from "../utils/dividend-cash";
+import { resolveCurrencyUnit } from "../utils/currency-units";
+import { logFailure } from "../utils/log-failure";
+import { dividendReferencePrice } from "../utils/trailing-dividend";
+import { observationDate } from "./price-comparison";
+import { CHART_RESOLUTION_STEP_MS, chartBarSizeStepMs } from "./resolution";
+import type { ResolvedSeries, TimeSeriesPoint } from "./types";
+
+/** One cash distribution per share: its ex-date (`YYYY-MM-DD`) and its amount in the listing's major currency unit. */
+export interface CashDistribution {
+  exDate: string;
+  amount: number;
+}
+
+export interface TotalReturnOptions {
+  /** The session day a bar belongs to, `YYYY-MM-DD`. */
+  dayOf: (point: TimeSeriesPoint) => string;
+  /**
+   * A bar's price in the distributions' currency unit, or null when the two
+   * currencies differ (nothing is converted).
+   */
+  cashPrice: (price: number) => number | null;
+  /**
+   * Bars longer than a session (weekly, monthly) are dated at their start, so a
+   * distribution belongs to the bar that holds its ex-date, not the first one
+   * dated on or after it. This is how many days a bar holds; the last bar holds
+   * that many from its own date, and a distribution after that precedes no bar.
+   */
+  barDays?: number;
+  /** Today, `YYYY-MM-DD`: a distribution dated after it has not gone ex. */
+  asOf?: string;
+}
+
+export interface TotalReturnResult {
+  points: TimeSeriesPoint[];
+  /** Distributions reinvested inside the series; one before its first bar or after its last is not. */
+  applied: number;
+}
+
+/** The day a bar of `barDays` days dated `day` ends on; 30-day multiples are calendar months. */
+function barEnd(day: string, barDays: number): string {
+  const end = new Date(`${day}T00:00:00Z`);
+  if (barDays >= 28 && barDays % 30 === 0) end.setUTCMonth(end.getUTCMonth() + barDays / 30);
+  else end.setUTCDate(end.getUTCDate() + barDays);
+  return end.toISOString().slice(0, 10);
+}
+
+function scaled(value: number | null | undefined, factor: number): number | null | undefined {
+  return typeof value === "number" && Number.isFinite(value) ? value * factor : value;
+}
+
+/**
+ * A price series as its total return: every cash distribution is reinvested at
+ * the close of its ex-date bar, so the series moves by (close + cash) over the
+ * bar before. Each price is multiplied by the shares the cash has bought
+ * since the series began, which leaves its first bar as it was; volume is
+ * left alone. A distribution dated at or before the first bar precedes the
+ * series, so nothing is reinvested for it.
+ */
+export function reinvestDistributions(
+  points: readonly TimeSeriesPoint[],
+  distributions: readonly CashDistribution[],
+  { dayOf, cashPrice, barDays, asOf }: TotalReturnOptions,
+): TotalReturnResult {
+  const ordered = [...points].sort((left, right) => left.date.getTime() - right.date.getTime());
+  const holdingBar = barDays !== undefined && barDays > 1;
+  const cash = distributions
+    .filter((entry) => /^\d{4}-\d{2}-\d{2}$/.test(entry.exDate) && Number.isFinite(entry.amount) && entry.amount > 0
+      && (asOf === undefined || entry.exDate <= asOf))
+    .sort((left, right) => left.exDate.localeCompare(right.exDate));
+  const days = ordered.map(dayOf);
+  let factor = 1;
+  let applied = 0;
+  let next = 0;
+  const adjusted = ordered.map((point, index) => {
+    const barDay = days[index]!;
+    const before = holdingBar ? days[index + 1] ?? barEnd(barDay, barDays!) : null;
+    while (next < cash.length) {
+      const entry = cash[next]!;
+      if (before !== null ? entry.exDate >= before : entry.exDate > barDay) break;
+      if (index === 0) { next += 1; continue; }
+      const close = point.close ?? point.value;
+      // A bar with no price leaves the cash for the next bar that has one.
+      if (typeof close !== "number" || !Number.isFinite(close) || close <= 0) break;
+      // Cash in another currency than the price buys nothing: the series stays a price series.
+      const price = cashPrice(close);
+      if (price !== null && price > 0) {
+        factor *= 1 + entry.amount / price;
+        applied += 1;
+      }
+      next += 1;
+    }
+    if (factor === 1) return point;
+    return {
+      ...point,
+      value: scaled(point.value, factor) ?? null,
+      ...point.rawValue !== undefined ? { rawValue: scaled(point.rawValue, factor) ?? null } : {},
+      ...point.open !== undefined ? { open: scaled(point.open, factor) } : {},
+      ...point.high !== undefined ? { high: scaled(point.high, factor) } : {},
+      ...point.low !== undefined ? { low: scaled(point.low, factor) } : {},
+      ...point.close !== undefined ? { close: scaled(point.close, factor) } : {},
+    };
+  });
+  return { points: adjusted, applied };
+}
+
+export interface TotalReturnOutcome {
+  series: ResolvedSeries;
+  /** Why the series stays a price series, when it does. */
+  notice?: string;
+}
+
+const DAY_MS = 86_400_000;
+
+/** How many days a bar holds when it is longer than a session (a month counts as 30), so a distribution belongs to the bar holding its ex-date. */
+function barDaysLongerThanSession(series: Pick<ResolvedSeries, "barSize" | "historyResolution">): number | undefined {
+  const step = series.barSize ? chartBarSizeStepMs(series.barSize)
+    : series.historyResolution ? CHART_RESOLUTION_STEP_MS[series.historyResolution] : null;
+  return step !== null && step > DAY_MS ? Math.round(step / DAY_MS) : undefined;
+}
+
+/**
+ * A price series as its total return, from the cash history its listing pays.
+ * The series says which basis it ended up on: `total` once its distributions
+ * are reinvested (a listing that pays none is its price), `price` with the
+ * reason when the history cannot be read, covers no distributions, or is in
+ * another currency than the prices. Nothing is converted.
+ */
+export async function totalReturnSeries(
+  series: ResolvedSeries,
+  loadActions: () => Promise<CorporateActionsData | null>,
+  priceCurrency: string | undefined,
+  asOf: Date,
+): Promise<TotalReturnOutcome> {
+  const priceOnly = (notice: string): TotalReturnOutcome => ({ series: { ...series, returnBasis: "price" }, notice });
+  const actions = await loadActions().catch(logFailure("total-return", "Loading distribution history failed", null));
+  if (!actions) return priceOnly("distribution history unavailable; showing the price return.");
+  const cash = cashInMajorUnits(actions);
+  const dividends = Array.isArray(cash.dividends) ? cash.dividends : [];
+  if (cash.coverage?.dividends === "unavailable" || (cash.coverage?.dividends !== "available" && dividends.length === 0)) {
+    return priceOnly("distribution history unavailable; showing the price return.");
+  }
+  const currency = resolveCurrencyUnit(cash.currency).currency;
+  if (dividends.length > 0 && !currency) return priceOnly("distribution currency unknown; showing the price return.");
+  if (dividends.length > 0 && !resolveCurrencyUnit(priceCurrency).currency) {
+    return priceOnly("price currency unknown; showing the price return.");
+  }
+  if (dividends.length > 0 && dividendReferencePrice(1, priceCurrency, currency) === null) {
+    return priceOnly(`distributions are in ${currency}, not the price currency; showing the price return.`);
+  }
+  const { points } = reinvestDistributions(series.points, dividends, {
+    dayOf: (point) => observationDate(point.date.getTime(), series),
+    cashPrice: (price) => dividendReferencePrice(price, priceCurrency, currency),
+    barDays: barDaysLongerThanSession(series),
+    asOf: asOf.toISOString().slice(0, 10),
+  });
+  // "ECC Close" is its price: a label the chart wrote from the field says what the series is now.
+  return { series: { ...series, points, returnBasis: "total", label: series.label.replace(/ (?:Close|Price|Open|High|Low)$/, " Total return") } };
+}

package/src/time-series/transforms.ts

@@ -1,6 +1,7 @@
 import type { ResolvedSeries, SeriesTransform, TimeSeriesPoint } from "./types";
 import { calendarMonthsBefore } from "../utils/calendar-date";
 import { isFiniteNumber } from "../utils/guards";
+import { isOhlcSeriesStyle } from "./spec";
 
 const DAY_MS = 24 * 60 * 60 * 1_000;
 // Volume is separate supporting data, not another price. A volume series has
@@ -166,9 +167,7 @@ export function applyResolvedSeriesTransform(
     unit: percent ? "%" : transform === "index100" ? "index" : "log",
     unitGroup: percent ? "percent" : transform === "index100" ? "index" : "log",
     dataShape: "scalar",
-    style: series.style === "candles" || series.style === "ohlc" || series.style === "hlc"
-      ? "line"
-      : series.style,
+    style: isOhlcSeriesStyle(series.style) ? "line" : series.style,
     points: applySeriesTransform(series.points, transform, options),
   };
 }

package/src/time-series/types.ts

@@ -10,7 +10,7 @@ export type SeriesPeriod = "auto" | "daily" | "weekly" | "monthly" | "quarterly"
  * "band" draws a line through each point's value inside a shaded range from
  * its `low` to its `high`: an average within its historical range.
  */
-export type SeriesStyle = "line" | "area" | "step" | "columns" | "points" | "candles" | "ohlc" | "hlc" | "band";
+export type SeriesStyle = "line" | "area" | "step" | "columns" | "points" | "candles" | "hollow" | "heikin-ashi" | "ohlc" | "hlc" | "band";
 export type SeriesTransform = "raw" | "percent" | "index100" | "yoy" | "qoq" | "log";
 export type SeriesAxis = "auto" | "left" | "right";
 export type SeriesInterpolation = "none" | "step-after";
@@ -110,6 +110,11 @@ export interface ChartViewportSpec {
   maxPoints?: number;
   /** Intraday market history includes pre-market and after-hours bars where the venue has them. */
   extendedHours?: boolean;
+  /**
+   * Security price series are drawn as total returns: each cash distribution
+   * is reinvested at the close of its ex-date bar. Price returns otherwise.
+   */
+  totalReturn?: boolean;
 }
 
 export interface ChartSpec {
@@ -141,6 +146,8 @@ export interface TimeSeriesPoint {
   low?: number | null;
   close?: number | null;
   volume?: number | null;
+  /** The bar this figure traded in closed below its open: volume draws it in the falling colour. */
+  fell?: boolean;
   periodLabel?: string;
   /**
    * A financial statement period as the FA columns name it: `FY2025`, `Q3 FY26`,
@@ -183,6 +190,12 @@ export interface ResolvedSeries {
   unit: string;
   /** Unit of rawValue, retained when presentation transforms change unit. */
   rawUnit?: string;
+  /**
+   * What a price series' returns are, set when the chart asked for total
+   * returns: `total` once its distributions are reinvested, `price` when the
+   * source gave none to reinvest (`warning` says why).
+   */
+  returnBasis?: "total" | "price";
   unitGroup: string;
   /**
    * The unit the legend states beside each value, read bare as FUT prints its
@@ -311,6 +324,14 @@ export interface ChartResolutionResult {
   loading: boolean;
   errors: string[];
   warnings: string[];
+  /**
+   * Where a series' source starts after the range asked for, and why (a
+   * publisher's cap on history), as `warnings` also carries it, so a report
+   * says it where it would otherwise print a range that quietly starts later.
+   */
+  coverageNotices?: string[];
+  /** What the price levels of a total-return chart without a comparison are (`warnings` also carries it). */
+  returnBasisNotice?: string;
   /**
    * Each charted listing that no longer trades: its symbol and label
    * ("Delisted Oct 27, 2022"), which `warnings` carries as "TWTR: Delisted Oct 27, 2022".

package/src/types/financials.ts

@@ -330,7 +330,12 @@ export interface Fundamentals extends DepositaryReceiptFacts {
   /** Set where Gloom Cloud checked `enterpriseValue` against market cap + total debt - cash; pairs with that value only. */
   enterpriseValueCheck?: EnterpriseValueCheck;
   /** Explicit provider retractions; omitted fields alone remain eligible for fallback. */
-  unavailableFields?: Array<"enterpriseValue" | "enterpriseToRevenue">;
+  unavailableFields?: Array<"enterpriseValue" | "enterpriseToRevenue" | "marketCap">;
+  /**
+   * Why `marketCap` is retracted, with "marketCap" in `unavailableFields`: a depositary receipt its source priced as
+   * an ordinary share (the receipt's price times the company's ordinary shares), with no ratio to convert them.
+   */
+  marketCapUnavailable?: "receipt-priced-as-ordinary";
   operatingCashFlow?: number;
   freeCashFlow?: number;
   dividendYield?: number;
@@ -345,6 +350,18 @@ export interface Fundamentals extends DepositaryReceiptFacts {
   revenue?: number;
   netIncome?: number;
   eps?: number;
+  /**
+   * Where `eps` and `trailingPE` come from: `filed-quarters` when `eps` is the
+   * diluted EPS of the last four filed quarters (or the fiscal year they end
+   * with), as PEB and GE read the statements, its last period ending
+   * `trailingEpsPeriodEnd`, and `trailingPE` the price over it; `served` when
+   * those quarters give none (or one that cannot be priced: see
+   * time-series/filed-trailing-eps) and both are Gloom Cloud's trailing
+   * figures, including a P/E it serves with no EPS (a fund's). Absent when
+   * there is neither an EPS nor a P/E.
+   */
+  trailingEpsSource?: "filed-quarters" | "served";
+  trailingEpsPeriodEnd?: string;
   operatingMargin?: number;
   profitMargin?: number;
   revenueGrowth?: number;
@@ -556,10 +573,24 @@ export interface CorporateActionsData {
   dividends: DividendAction[];
   /** Declared and unpaid, for the listings Gloom Cloud has them for; absent elsewhere and from older servers. */
   declaredDividends?: DeclaredDividendAction[];
+  /**
+   * What each paid row was declared as when the company declares in another
+   * currency than the listing pays (BP's dollars beside its London pence), per
+   * ordinary share, keyed by the paid row's ex-date. Absent elsewhere and from older servers.
+   */
+  declaredCash?: DeclaredCash;
+  /** Set when `dividends` is the last good history standing in for a refresh that could not read it: when that history was read. */
+  dividendsAsOf?: string;
   splits: SplitAction[];
   earnings: EarningsAction[];
 }
 
+/** Paid rows as their company declared them, in `currency` (its major unit). */
+export interface DeclaredCash {
+  currency: string;
+  rows: DividendAction[];
+}
+
 export interface CompanyProfile {
   description?: string;
   /**

package/src/types/headless.ts

@@ -34,6 +34,12 @@ export interface HeadlessPaneArgumentDef {
   examples?: readonly string[];
 }
 
+/** A list the catalog prints under a function's options, such as the sector names a screen's criteria match. */
+export interface HeadlessPaneReference {
+  title: string;
+  items: readonly string[];
+}
+
 export interface HeadlessPaneOptionValue {
   value: string;
   aliases?: string[];
@@ -83,6 +89,8 @@ export interface HeadlessPaneOptionDef {
    * absent.
    */
   valueWords?: number;
+  /** The value is a comma list (`--metric trailingPE,dividendYieldPercent`), and the flag typed again adds to it. */
+  list?: boolean;
   /** The option in use as typed after the function, such as `--expiration 2028-01-21`; the catalog shows it as an example. */
   example?: string;
   /** The example runs without the function's optional argument, as an option that works only then does (`fn INS --side sell`). */
@@ -138,8 +146,10 @@ export interface HeadlessPaneContext {
    * known. A code several companies list (BDI) throws asking which, with
    * `quote`'s message; `argumentWith(key)` is the function's argument naming
    * that listing instead (`BDI:TSX`), for the retry each listing offers.
+   * `coinNote` is what `quote` says of a bare coin ticker read as a listing
+   * that is not the coin (ETH, the Grayscale fund), for the report's warnings.
    */
-  resolveListing?: (symbol: string, argumentWith: (key: string) => string) => Promise<{ symbol: string; exchange?: string; name?: string } | null>;
+  resolveListing?: (symbol: string, argumentWith: (key: string) => string) => Promise<{ symbol: string; exchange?: string; name?: string; coinNote?: string } | null>;
   /**
    * What a plugin keeps on this device only (its `ctx.resume` state, never
    * synced), such as ALRT's log of the alerts the app fired; null when none.
@@ -602,6 +612,8 @@ export interface HeadlessSeries {
   interval?: string;
   /** Decimal places the text report prints the latest value to (a correlation to 3); JSON and CSV keep every digit. */
   textDecimals?: number;
+  /** The text report prints the latest value as the tables print an amount (63.33B), for a company's reported total; JSON and CSV keep every digit. */
+  textCompact?: boolean;
   /** Each point's `value` is its bar's close: `--csv` and `--ndjson` write Close alone, JSON keeps both. */
   valueIsClose?: boolean;
   points: HeadlessSeriesPoint[];
@@ -615,6 +627,8 @@ export interface HeadlessSeriesResult extends HeadlessPaneResultBase {
 export interface HeadlessSnapshotResult extends HeadlessPaneResultBase {
   asOf: string | number | Date;
   items: HeadlessPaneRow[];
+  /** What the report says when `items` is empty, in place of "No data.": why there are none. */
+  empty?: string;
 }
 
 export interface HeadlessPaneResultByShape {
@@ -640,6 +654,8 @@ export interface HeadlessPaneDefinition<Shape extends HeadlessPaneShape = Headle
     intents?: string[];
     dataRequirements?: string[];
     limitations?: string[];
+    /** Names an option's values match, listed by the catalog under each title: EQS's sectors and industries. */
+    reference?: HeadlessPaneReference[];
     screenshotReadiness?: "ready" | "partial" | "live-dom" | "unsupported";
   };
   /**
@@ -672,9 +688,11 @@ export interface HeadlessPaneDefinition<Shape extends HeadlessPaneShape = Headle
   /**
    * A listing the function has no data for, answered before any request with
    * what exists instead: OPX and OVDV answer a coin nothing lists options on
-   * (SOL-USD) with BTC and ETH options. `key` is the listing as read.
+   * (SOL-USD) with BTC and ETH options, and OVDV, VCA and HIVG an FX pair with
+   * the currency funds' options. `key` is the listing as read; `details` is
+   * the line after `message`, left out when the message says it all.
    */
-  refuseSymbol?(key: string): { message: string; details: string } | null;
+  refuseSymbol?(key: string): { message: string; details?: string } | null;
   /**
    * `fn` exits 1 when the report has no name with data: no rows, or every row
    * is one of `unavailableSymbols`. A list that gives data for some names

package/src/types/news-source.ts

@@ -1,4 +1,5 @@
 export type {
+  NewsAccess,
   NewsArticle,
   NewsQuery,
   NewsQueryState,

package/src/types/plugin.ts

@@ -20,6 +20,7 @@ export type {
   HeadlessPaneOptionType,
   HeadlessPaneOptionValue,
   HeadlessPaneOptionValues,
+  HeadlessPaneReference,
   HeadlessPaneResult,
   HeadlessPaneResultByShape,
   HeadlessPaneRow,
@@ -529,6 +530,14 @@ export interface PaneTemplateDef {
   description: string;
   keywords?: string[];
   shortcut?: PaneTemplateShortcut;
+  /**
+   * False leaves the function out of every list and search of functions
+   * (command-bar browse, search and assistant, Help, `gloom catalog` and
+   * search, the plugin directory, chat suggestions) while typing its code
+   * still opens it, `fn` and `shot` still run it and its help still answers.
+   * ATTN until it publishes (attention/listing.ts).
+   */
+  listed?: boolean;
   /** Template-specific headless model. Takes precedence over the pane-level model. */
   headless?: HeadlessPaneDefinition;
   /**

package/src/ui/host.tsx

@@ -82,6 +82,8 @@ export interface ChartVectorShape {
   gradient?: readonly string[];
   /** Opacity of the whole shape, so others can recede behind a highlighted one. */
   opacity?: number;
+  /** Text set just above the shape's first point, such as a retracement level's ratio and price. */
+  label?: string;
 }
 
 interface TextEditBuffer {
@@ -508,6 +510,7 @@ export interface HostCheckboxProps {
 interface HostQueryBarOption {
   value: string;
   label: string;
+  group?: string;
   description?: string;
   disabled?: boolean;
   selected: boolean;

package/src/updater/failure.ts

@@ -24,7 +24,7 @@ const UPDATE_FAILURE_CODES = [
   "no_build",
   /** The download stopped before the whole file arrived. */
   "interrupted",
-  /** The file arrived whole but does not match its checksum, or does not unpack. */
+  /** The download does not match its checksum, or does not unpack (part of it is missing or damaged). */
   "corrupt",
   "permission_denied",
   /** The macOS app runs from where it cannot be replaced: a disk image, App Translocation, another volume. */
@@ -112,6 +112,9 @@ export function classifyUpdateError(error: unknown): UpdateFailureCode {
   if (status) return httpStatusFailureCode(Number(status));
   if (/checksum mismatch|hash mismatch/i.test(message)) return "corrupt";
   if (/zstd|decompress|gunzip|incorrect header|unexpected end of (?:file|data)/i.test(message)) return "corrupt";
+  // Bun.Archive on a tar that does not read: cut off, damaged, or none at all.
+  // Unpacking says only "ReadError", whatever stopped it.
+  if (/\bReadError\b|truncated tar|damaged tar|unrecognized archive format/i.test(message)) return "corrupt";
   if (/timed? ?out/i.test(message)) return "timeout";
   if (/rate limit/i.test(message)) return "rate_limited";
   if (/read-only file system/i.test(message)) return "read_only";

package/src/utils/cli-output.ts

@@ -74,6 +74,47 @@ const PLAIN_EMPTY_CELL = "—";
 let colorEnabledOverride: boolean | null = null;
 let widthOverride: number | null = null;
 let plainOverride: boolean | null = null;
+/** Output is being rendered for a file (`renderForFile`), which has no terminal width. */
+let renderingForFile = false;
+
+/** Renders for a file from here on; the function returned puts the terminal's rendering back. */
+function enterFileRendering(): () => void {
+  const saved = { color: colorEnabledOverride, plain: plainOverride, file: renderingForFile };
+  colorEnabledOverride = false;
+  plainOverride = true;
+  renderingForFile = true;
+  return () => {
+    colorEnabledOverride = saved.color;
+    plainOverride = saved.plain;
+    renderingForFile = saved.file;
+  };
+}
+
+/**
+ * Output rendered for a file (`fn --output`) as a redirect gets it: plain,
+ * without colour, and fitted to no width but `--width`'s.
+ */
+export function renderForFile<T>(render: () => T): T {
+  const restore = enterFileRendering();
+  try {
+    return render();
+  } finally {
+    restore();
+  }
+}
+
+/**
+ * `renderForFile` around work that renders as it loads: a report whose text is
+ * drawn while it is built is drawn for the file, though stdout is a terminal.
+ */
+export async function buildForFile<T>(build: () => Promise<T>): Promise<T> {
+  const restore = enterFileRendering();
+  try {
+    return await build();
+  } finally {
+    restore();
+  }
+}
 
 function colorEnabled(): boolean {
   if (colorEnabledOverride != null) return colorEnabledOverride;
@@ -176,7 +217,7 @@ export function setCliWidthOverride(value: number | null): void {
 /** Columns the output is fitted to: `--width`, else the terminal's, or null when output is piped or redirected. */
 export function cliTerminalWidth(): number | null {
   if (widthOverride != null) return widthOverride;
-  if (!process.stdout.isTTY) return null;
+  if (renderingForFile || !process.stdout.isTTY) return null;
   const columns = process.stdout.columns;
   return typeof columns === "number" && columns > 0 ? columns : null;
 }

package/src/utils/crypto-pair.ts

@@ -91,6 +91,50 @@ export const MAJOR_COIN_NAMES: ReadonlyMap<string, string> = new Map([
   ["BNB", "BNB"],
 ]);
 
+/**
+ * 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|USDT|USDC|BTC)$/;
 // 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;

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

@@ -6,16 +6,19 @@ 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;
 }
 
@@ -243,6 +246,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`. */