gloomberb 0.18.2 → 0.18.4

package/src/utils/fundamentals.ts

@@ -1,6 +1,9 @@
-import type { EnterpriseValueCheck, Fundamentals, TickerFinancials } from "../types/financials";
+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 { formatCompact } from "./format";
+import { formatUtcTime } from "./utc-time";
 
 export const RETRACTABLE_VALUATION_FIELDS = ["enterpriseValue", "enterpriseToRevenue"] as const;
 
@@ -26,44 +29,72 @@ const finiteNumber = (value: unknown): value is number => typeof value === "numb
 
 /**
  * The served check of the enterprise value beside it, when it describes that value: a provider EV the check labels or
- * matches is the one shown, and a withdrawn one is no longer shown. A check merged beside another source's EV is none.
+ * matches is the one shown, a computed one is the check's own figure, and a withdrawn or not meaningful one is no
+ * longer shown. A check merged beside another source's EV is none.
  */
 export function enterpriseValueCheck(
   fundamentals: Pick<Fundamentals, "enterpriseValue" | "enterpriseValueCheck" | "unavailableFields"> | undefined,
 ): EnterpriseValueCheck | undefined {
   const check = fundamentals?.enterpriseValueCheck;
-  if (!check || !finiteNumber(check.source) || !check.currency) return undefined;
-  if (check.status === "withdrawn") {
-    return fundamentals?.enterpriseValue === undefined && fundamentals.unavailableFields?.includes("enterpriseValue")
-      && finiteNumber(check.computed) ? check : undefined;
+  if (!check) return undefined;
+  const withdrawn = fundamentals?.enterpriseValue === undefined && !!fundamentals?.unavailableFields?.includes("enterpriseValue");
+  // Not meaningful needs no figure of its own: a source EV below zero may come with no cap or currency.
+  if (check.status === "not-meaningful") return withdrawn ? check : undefined;
+  if (!check.currency) return undefined;
+  if (check.status === "withdrawn") return withdrawn && finiteNumber(check.computed) && finiteNumber(check.source) ? check : undefined;
+  if (check.status === "computed") {
+    return finiteNumber(check.computed) && fundamentals?.enterpriseValue === check.computed ? check : undefined;
   }
-  return fundamentals?.enterpriseValue === check.source ? check : undefined;
+  return finiteNumber(check.source) && fundamentals?.enterpriseValue === check.source ? check : undefined;
+}
+
+/** Why a source EV below zero that nothing checked is not meaningful: its cash and investments exceed the rest. */
+const SOURCE_ENTERPRISE_VALUE_NOT_POSITIVE = "Cash and investments exceed market cap + debt in the source's EV";
+
+/**
+ * Why the enterprise value is not meaningful, if it is: Gloom Cloud's reason for an EV that comes out at or below
+ * zero, or for an EV below zero from any source that served no check. A bank's 0 is a gap, not N/M. EV/S, EV/EBITDA
+ * and a reverse DCF over it are N/M too.
+ */
+export function enterpriseValueNotMeaningful(fundamentals: Parameters<typeof enterpriseValueCheck>[0]): string | undefined {
+  const check = enterpriseValueCheck(fundamentals);
+  if (check?.status === "not-meaningful") return check.reason?.trim() || SOURCE_ENTERPRISE_VALUE_NOT_POSITIVE;
+  const value = fundamentals?.enterpriseValue;
+  return finiteNumber(value) && value < 0 ? SOURCE_ENTERPRISE_VALUE_NOT_POSITIVE : undefined;
 }
 
 /**
  * Whether the provider's EV was withdrawn: retracted (`unavailableFields`) and none served in its place, by the
- * served check or by Gloom Cloud's own validation of the source observation, which leaves no check.
+ * served check or by Gloom Cloud's own validation of the source observation, which leaves no check. Not one that is
+ * not meaningful (enterpriseValueNotMeaningful), which says N/M instead.
  */
 export function enterpriseValueWithdrawn(fundamentals: Parameters<typeof enterpriseValueCheck>[0]): boolean {
-  return fundamentals?.enterpriseValue === undefined && !!fundamentals?.unavailableFields?.includes("enterpriseValue");
+  return fundamentals?.enterpriseValue === undefined && !!fundamentals?.unavailableFields?.includes("enterpriseValue")
+    && enterpriseValueNotMeaningful(fundamentals) === undefined;
 }
 
-/** "(provider)" beside an EV more than 5% from market cap + debt - cash, or "unavailable" for a withdrawn one. */
-export function enterpriseValueLabel(fundamentals: Parameters<typeof enterpriseValueCheck>[0]): "provider" | "unavailable" | undefined {
+/** "(provider)" beside an EV more than 5% from market cap + debt - cash, "unavailable" for a withdrawn one, N/M for one at or below zero. */
+export function enterpriseValueLabel(fundamentals: Parameters<typeof enterpriseValueCheck>[0]): "provider" | "unavailable" | "not-meaningful" | undefined {
+  if (enterpriseValueNotMeaningful(fundamentals)) return "not-meaningful";
   const status = enterpriseValueCheck(fundamentals)?.status;
   return status === "differs" ? "provider" : status === "withdrawn" || enterpriseValueWithdrawn(fundamentals) ? "unavailable" : undefined;
 }
 
 /**
- * The reconciliation line under a labelled or withdrawn EV: "EV 61.75B USD (provider) vs 63.75B computed from market
- * cap + total debt - cash (balance sheet 2026-06-30)." For an EV withdrawn without a check, that the source failed
- * validation. Undefined when the EV matches, is unchecked, or has no check. Read it from the fundamentals the rows
- * show (atRegularSessionPrice moves the check with the EV and the market cap), so its figures are theirs.
+ * The reconciliation line under a labelled, withdrawn or not meaningful EV: "EV 61.75B USD (provider) vs 63.75B
+ * computed from market cap + total debt - cash (balance sheet 2026-06-30).", "EV N/M: cash and short-term investments
+ * exceed market cap + total debt (balance sheet 2026-06-30)." For an EV withdrawn without a check, that the source
+ * failed validation. Undefined when the EV matches, is unchecked or computed, or has no check. Read it from the
+ * fundamentals the rows show (atRegularSessionPrice moves the check with the EV and the market cap), so its figures
+ * are theirs.
  */
 export function enterpriseValueReconciliationNote(fundamentals: Parameters<typeof enterpriseValueCheck>[0]): string | undefined {
+  const notMeaningful = enterpriseValueNotMeaningful(fundamentals);
+  if (notMeaningful) return `EV N/M: ${notMeaningful.charAt(0).toLowerCase()}${notMeaningful.slice(1)}.`;
   const check = enterpriseValueCheck(fundamentals);
   if (!check && enterpriseValueWithdrawn(fundamentals)) return "EV unavailable: the provider's figure failed validation.";
-  if (!check || !finiteNumber(check.computed) || (check.status !== "differs" && check.status !== "withdrawn")) return undefined;
+  if (!check || !finiteNumber(check.computed) || !finiteNumber(check.source)
+    || (check.status !== "differs" && check.status !== "withdrawn")) return undefined;
   const source = `${formatCompact(check.source)} ${check.currency}`;
   const computed = formatCompact(check.computed);
   const basis = `market cap + total debt - cash${check.balanceSheetDate ? ` (balance sheet ${check.balanceSheetDate})` : ""}`;
@@ -72,19 +103,39 @@ export function enterpriseValueReconciliationNote(fundamentals: Parameters<typeo
   return `EV unavailable: the provider's ${source}${ratio} the ${computed} computed from ${basis}.`;
 }
 
-/** What names the currency of the trailing figures: the fundamentals' own labels, else the statements'. */
+/**
+ * What `valuation` says of an insurer's or a holding company's EV, which Gloom Cloud computes rather than takes from
+ * the provider: "EV 1.23T USD is market cap + total debt - 40.61B of cash and equivalents (balance sheet 2026-06-30);
+ * investments stay in." Undefined for any other EV. The overview stat says it in two words ("investments in").
+ */
+export function computedEnterpriseValueNote(fundamentals: Parameters<typeof enterpriseValueCheck>[0]): string | undefined {
+  const check = enterpriseValueCheck(fundamentals);
+  if (check?.status !== "computed" || !finiteNumber(check.computed) || !finiteNumber(check.cash)) return undefined;
+  const sheet = check.balanceSheetDate ? ` (balance sheet ${check.balanceSheetDate})` : "";
+  return `EV ${formatCompact(check.computed)} ${check.currency} is market cap + total debt - ${formatCompact(check.cash)} of cash and equivalents${sheet}; investments stay in.`;
+}
+
+/** 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"> & {
-  fundamentals?: Pick<Fundamentals, "financialCurrency" | "epsCurrency"> | null;
+  fundamentals?: Pick<Fundamentals, "financialCurrency" | "epsCurrency" | "marketCapCurrency"> | null;
+  quote?: Pick<Quote, "currency"> | null;
 };
 
 /**
- * The currency of the trailing EPS, revenue, income and cash flows: the one the fundamentals declare, else the
- * one the statements report in. Never the quote's, which a depositary receipt can differ from (USD quote, TWD books).
+ * 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.
  */
 export function fundamentalsCurrency(
   financials: FundamentalsCurrencies | null | undefined,
 ): string | undefined {
-  return financials?.fundamentals?.financialCurrency?.trim() || financials?.financialCurrency?.trim() || undefined;
+  const declared = financials?.fundamentals?.financialCurrency?.trim();
+  if (declared) return declared;
+  const statements = financials?.financialCurrency?.trim();
+  if (!statements) return undefined;
+  const listed = financials?.fundamentals?.marketCapCurrency?.trim() || financials?.quote?.currency?.trim();
+  return !listed || resolveCurrencyUnit(listed).currency === resolveCurrencyUnit(statements).currency ? statements : undefined;
 }
 
 /**
@@ -99,22 +150,87 @@ export function fundamentalsEpsCurrency(
 
 const ISO_DAY = /^\d{4}-\d{2}-\d{2}$/;
 
+const usableRate = (rate: number | null | undefined): rate is number => typeof rate === "number" && Number.isFinite(rate) && rate > 0;
+
+/** The currency a trailing block was converted from into another it is labelled with; undefined for a block in the reporting currency. */
+function ttmConvertedFrom(fundamentals: Pick<Fundamentals, "financialCurrency" | "ttmConversion"> | undefined): string | undefined {
+  const from = fundamentals?.ttmConversion?.from?.trim();
+  const to = fundamentals?.financialCurrency?.trim();
+  return from && to && from !== to ? from : undefined;
+}
+
+/** A rate the app converts at, the one `fx` reports: units of the target currency per unit of the source one, and when it was observed. */
+export interface AppFxRate {
+  rate: number;
+  /** Epoch ms of the older leg's observation; null when the source did not date it. */
+  asOf: number | null;
+}
+
+/** One currency's US dollar rate as the app holds it, a minor unit's by its major currency. */
+type UsdLeg = (currency: string) => AppFxRate | null | undefined;
+
 /**
- * "TTM converted from EUR (1 EUR = 1.1257 USD, 2026-10-09); EPS at report-date rates.": what a converted trailing
- * block was converted from, at which rate and when. Undefined for a block in the currency the company reports in.
+ * The app's rate for a converted trailing block: units of its currency per unit of the one it was converted from,
+ * through the two US dollar legs `fx` reads, dated by the older. Null for an unconverted block or a missing leg.
+ */
+export function appTtmRate(fundamentals: Pick<Fundamentals, "financialCurrency" | "ttmConversion"> | undefined, usd: UsdLeg): AppFxRate | null {
+  const from = ttmConvertedFrom(fundamentals);
+  if (!from || !usableRate(fundamentals?.ttmConversion?.rate)) return null;
+  const leg = (currency: string) => {
+    const major = resolveCurrencyUnit(currency).currency;
+    return major === "USD" ? { rate: 1, asOf: null } : usd(major);
+  };
+  const source = leg(from), target = leg(fundamentals!.financialCurrency!.trim());
+  if (!usableRate(source?.rate) || !usableRate(target?.rate)) return null;
+  const dates = [source!.asOf, target!.asOf].filter((time): time is number => time != null && Number.isFinite(time));
+  return { rate: source!.rate / target!.rate, asOf: dates.length > 0 ? Math.min(...dates) : null };
+}
+
+const TTM_AMOUNTS = ["revenue", "netIncome", "operatingCashFlow", "freeCashFlow"] as const;
+
+/**
+ * A converted trailing block at the app's own rate, so a screen converts at one rate, the one `fx` reports: revenue,
+ * income and cash flows the source converted at `ttmConversion.rate` go back to the reporting currency and are
+ * converted again at `rate`, which the conversion then names with its time. EPS stays at report-date rates. The block
+ * as served when it is not converted, states no rate, or the app has none.
+ */
+export function ttmAtAppRate<T extends Fundamentals>(fundamentals: T, rate: AppFxRate | null | undefined): T {
+  const conversion = fundamentals.ttmConversion;
+  if (!rate || !usableRate(rate.rate) || !conversion || !ttmConvertedFrom(fundamentals) || !usableRate(conversion.rate)) return fundamentals;
+  const factor = rate.rate / conversion.rate;
+  const shown: T = { ...fundamentals };
+  for (const key of TTM_AMOUNTS) {
+    const value = fundamentals[key];
+    if (finiteNumber(value)) (shown as Fundamentals)[key] = Math.round(value * factor);
+  }
+  const { asOf: _served, ...kept } = conversion;
+  shown.ttmConversion = { ...kept, rate: rate.rate, ...(rate.asOf != null ? { asOf: new Date(rate.asOf).toISOString() } : {}) };
+  return shown;
+}
+
+/** `2026-10-09`, or `2026-10-23 21:29 UTC` for the time of a rate. */
+function conversionTime(asOf: string | undefined): string | undefined {
+  if (!asOf) return undefined;
+  if (ISO_DAY.test(asOf)) return asOf;
+  const time = Date.parse(asOf);
+  return Number.isFinite(time) ? formatUtcTime(new Date(time)) || undefined : undefined;
+}
+
+/**
+ * "TTM converted from ARS at USD/ARS 1529, as of 2026-10-23 21:29 UTC; EPS at report-date rates.": what a converted
+ * trailing block was converted from, at which rate, as markets quote the pair and `fx` reads it, and when. Undefined
+ * for a block in the currency the company reports in.
  */
 export function ttmConversionNote(fundamentals: Pick<Fundamentals, "financialCurrency" | "ttmConversion"> | undefined): string | undefined {
-  const conversion = fundamentals?.ttmConversion;
-  const from = conversion?.from?.trim();
-  const to = fundamentals?.financialCurrency?.trim();
-  if (!conversion || !from || !to || from === to) return undefined;
-  const rate = typeof conversion.rate === "number" && Number.isFinite(conversion.rate) && conversion.rate > 0
-    ? `1 ${from} = ${Number(conversion.rate.toPrecision(5))} ${to}`
-    : undefined;
-  const asOf = conversion.asOf && ISO_DAY.test(conversion.asOf) ? conversion.asOf : undefined;
-  const basis = [rate, asOf].filter(Boolean).join(", ");
+  const from = ttmConvertedFrom(fundamentals);
+  if (!from) return undefined;
+  const conversion = fundamentals!.ttmConversion!;
+  const quoted = usableRate(conversion.rate) ? quotedFxPair(from, fundamentals!.financialCurrency!, conversion.rate) : undefined;
+  const rate = quoted ? ` at ${quoted.pair} ${formatFxRate(quoted.rate)}` : "";
+  const time = conversionTime(conversion.asOf);
+  const when = time ? `${rate ? "," : ""} as of ${time}` : "";
   const eps = conversion.eps === "report_date" ? "; EPS at report-date rates" : "";
-  return `TTM converted from ${from}${basis ? ` (${basis})` : ""}${eps}.`;
+  return `TTM converted from ${from}${rate}${when}${eps}.`;
 }
 
 /**
@@ -147,7 +263,7 @@ export function convertedPriceEarningsNote(fundamentals: PriceEarningsBasis | un
   if (from && to && from !== to && typeof conversion?.rate === "number" && Number.isFinite(conversion.rate) && conversion.rate > 0) {
     return `P/E (TTM): price over EPS converted at 1 ${from} = ${Number(conversion.rate.toPrecision(5))} ${to}.`;
   }
-  return (ttmConversionNote(fundamentals) && fundamentals?.ttmConversion?.eps === "report_date") || epsConversionNote(fundamentals)
+  return (ttmConvertedFrom(fundamentals) && fundamentals?.ttmConversion?.eps === "report_date") || epsConversionNote(fundamentals)
     ? "P/E (TTM): spot price over EPS at report-date rates."
     : undefined;
 }

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

@@ -1,5 +1,5 @@
 import { canonicalExchange, parsePublicTickerKey } from "./exchanges";
-import { zonedDateTimeParts, zonedWallClockToUtcMs } from "./zoned-date-time";
+import { zonedDateKey, zonedDateTimeParts, zonedWallClockToUtcMs } from "./zoned-date-time";
 
 const HOUR_MS = 60 * 60_000;
 const DAY_MS = 24 * HOUR_MS;
@@ -29,6 +29,15 @@ export function isFxMarketOpen(time: number): boolean {
   return true;
 }
 
+/**
+ * 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.
+ */
+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);
+}
+
 /** The latest 17:00 New York on `weekday` (0 is Sunday) at or before `time`. */
 function latestNewYorkFivePm(time: number, weekday: number): number | null {
   if (!Number.isFinite(time)) return null;

package/src/utils/latest-financial-period.ts

@@ -24,3 +24,11 @@ export function latestFinancialPeriod<T>(
   }
   return latest;
 }
+
+/** The newest reported period end across the annual and quarterly statements: the period the trailing figures run through. */
+export function latestReportedPeriod(financials: {
+  annualStatements?: readonly { date: string }[];
+  quarterlyStatements?: readonly { date: string }[];
+}): string | null {
+  return latestFinancialPeriod([...financials.annualStatements ?? [], ...financials.quarterlyStatements ?? []], (row) => row.date)?.date ?? null;
+}

package/src/utils/linux-libc.ts

@@ -0,0 +1,54 @@
+/**
+ * Which C library a Linux process runs on. The terminal's native render
+ * library and the release binary each have a glibc and a musl build, and the
+ * wrong one fails to load: the glibc library on Alpine stops at startup with
+ * "getcontext: symbol not found".
+ */
+export type LinuxLibc = "glibc" | "musl";
+
+/**
+ * Reads the libraries mapped into the process (`/proc/self/maps`). musl is
+ * checked first because a glibc program started through gcompat still runs on
+ * musl underneath, and the musl library is the one it can load.
+ */
+export function libcFromProcessMaps(maps: string): LinuxLibc | null {
+  if (maps.includes("/ld-musl-") || maps.includes("/libc.musl-")) return "musl";
+  if (maps.includes("/libc.so.6") || maps.includes("/ld-linux-")) return "glibc";
+  return null;
+}
+
+/** Reads the system's `ldd`, a script that names its C library, for when `/proc` is not mounted. */
+export function libcFromLdd(script: string): LinuxLibc | null {
+  if (script.includes("musl")) return "musl";
+  if (/GNU C Library|glibc/i.test(script)) return "glibc";
+  return null;
+}
+
+function readText(path: string): string | null {
+  try {
+    return process.getBuiltinModule("fs").readFileSync(path, "utf8");
+  } catch {
+    // Intentional ignore: a missing or unreadable file only means this source cannot tell.
+    return null;
+  }
+}
+
+let detected: LinuxLibc | null | undefined;
+
+/** The C library this process runs on, or null off Linux or when nothing says. */
+export function detectLinuxLibc(): LinuxLibc | null {
+  if (globalThis.process?.platform !== "linux") return null;
+  if (detected !== undefined) return detected;
+  detected = libcFromProcessMaps(readText("/proc/self/maps") ?? "")
+    ?? libcFromLdd(readText("/usr/bin/ldd") ?? "");
+  return detected;
+}
+
+/**
+ * @opentui/core loads its glibc library on Linux unless `OPENTUI_LIBC` says
+ * musl; it never looks at the system. Has to run before it is first imported.
+ * An `OPENTUI_LIBC` the user set is kept.
+ */
+export function selectOpenTuiLibc(env: Record<string, string | undefined>, libc: LinuxLibc | null): void {
+  if (!env.OPENTUI_LIBC && libc === "musl") env.OPENTUI_LIBC = "musl";
+}

package/src/utils/market-capitalization.ts

@@ -1,4 +1,4 @@
-import type { Fundamentals, Quote } from "../types/financials";
+import type { Fundamentals, Quote, SplitShareBasis } from "../types/financials";
 import { formatCompact, formatNumber } from "./format";
 
 export interface MarketCapitalization {
@@ -66,23 +66,119 @@ export function listedMarketCapitalization(value: number | null): number | null
   return value != null && Number.isFinite(value) && value > 0 ? value : null;
 }
 
-/** How far a market cap may sit from the share count times the price and still rest on that count. */
+/** Within this a provider's cap is the share count times the price at another moment, and is not worth a note. */
 const SHARE_COUNT_TOLERANCE = 0.02;
+/**
+ * How far a provider's cap may sit from the share count times the price and
+ * still be on that count, off by price timing or a recent issuance (EVN:ASX,
+ * 3% in October 2026). Past it the count is not the cap's: one class's count
+ * beside an all-class cap (NRDY).
+ */
+const SHARE_BASIS_LIMIT = 0.1;
+
+/** A market cap a view shows, and how it stands against the share count shown beside it. */
+export interface ViewMarketCapitalization extends MarketCapitalization {
+  /** Set when the cap shown is `shares` x `price` and the provider's sat more than 2% (and at most 10%) from it. */
+  computed?: { shares: number; price: number; providerValue: number };
+  /** Set when the provider's cap, shown, sits more than 10% from `shares` x `price`: the count is not the cap's. */
+  otherBasis?: { shares: number; price: number; product: number };
+  /** Set when a recent split put the share count and cap on the basis the listing trades on, with the count shown. */
+  split?: SplitShareBasis & { shares?: number };
+}
+
+const positiveFinite = (value: number | null | undefined): value is number => value != null && Number.isFinite(value) && value > 0;
 
 /**
- * Where a market cap does not rest on the share count shown beside it (one class's count beside an all-class cap):
- * "Market cap 137.20B USD is the provider's and does not rest on the 799.93M shares shown (x 110.11 USD = 88.08B)."
- * Undefined when they tie, or without a count and a price in the cap's currency to test.
+ * The one market cap a view shows, so RV, `valuation` and EQS agree:
+ * the share count shown times the price, the provider's figure only as a
+ * noted fallback. The product stands while the provider's sits within 10% of
+ * it, named in the note when more than 2% off (price timing, a recent
+ * issuance); past 10% the count shown is not the cap's (one class's beside
+ * an all-class cap), and the provider's is shown with a note saying the two
+ * do not tie. `price` is the price the view measures at (the regular
+ * session's); without a count or a price in the cap's currency the
+ * provider's stands. Gloom Cloud's screener and earnings board apply the
+ * same rule (sharesTimesLast in the server's market-cap-basis.ts).
  */
-export function marketCapShareBasisNote(
-  capitalization: Pick<MarketCapitalization, "value" | "currency"> | null,
-  shares: number | undefined,
+export function viewMarketCapitalization(
+  quote: Quote | undefined,
+  fundamentals: Fundamentals | undefined,
+  price: number | null | undefined = quote?.price,
+): ViewMarketCapitalization | null {
+  const capitalization = viewCapitalization(quote, fundamentals, price);
+  const split = fundamentals?.splitShareBasis;
+  return capitalization && split
+    ? { ...capitalization, split: { ...split, shares: fundamentals?.sharesOutstanding } }
+    : capitalization;
+}
+
+function viewCapitalization(
+  quote: Quote | undefined,
+  fundamentals: Fundamentals | undefined,
   price: number | null | undefined,
-  priceCurrency: string | undefined,
-): string | undefined {
-  if (!capitalization || !(capitalization.value > 0) || capitalization.currency !== priceCurrency) return undefined;
-  if (shares == null || !Number.isFinite(shares) || !(shares > 0) || price == null || !Number.isFinite(price) || !(price > 0)) return undefined;
-  const product = shares * price;
-  if (Math.abs(capitalization.value / product - 1) <= SHARE_COUNT_TOLERANCE) return undefined;
-  return `Market cap ${formatCompact(capitalization.value)} ${capitalization.currency} is the provider's and does not rest on the ${formatCompact(shares)} shares shown (x ${formatNumber(price, price < 1 ? 4 : 2)} ${priceCurrency} = ${formatCompact(product)}).`;
+): ViewMarketCapitalization | null {
+  const selected = selectMarketCapitalization(quote, fundamentals);
+  const shares = fundamentals?.sharesOutstanding;
+  if (!selected || !(selected.value > 0) || selected.currency !== quote?.currency) return selected;
+  if (!positiveFinite(shares) || !positiveFinite(price)) return selected;
+  // In whole units, as caps are served.
+  const product = Math.round(shares * price);
+  const gap = Math.abs(selected.value - product);
+  if (gap > SHARE_BASIS_LIMIT * product) return { ...selected, otherBasis: { shares, price, product } };
+  return {
+    value: product,
+    currency: selected.currency,
+    // Priced at the quote, whichever block the provider's figure came from.
+    provenance: { kind: "quote", source: quote.providerId },
+    ...(gap > SHARE_COUNT_TOLERANCE * product ? { computed: { shares, price, providerValue: selected.value } } : {}),
+  };
+}
+
+/** "1-for-15 reverse split" for a price factor of 15, "10-for-1 split" for 0.1. */
+function splitRatio(priceFactor: number): string {
+  const ratio = (value: number) => String(Number(value.toPrecision(4)));
+  return priceFactor >= 1 ? `1-for-${ratio(priceFactor)} reverse split` : `${ratio(1 / priceFactor)}-for-1 split`;
+}
+
+/**
+ * What a view says when a recent split moved the share count shown:
+ * - a filed count: "12.77M shares: 191.61M filed 2026-07-31, adjusted for the 1-for-15 reverse split on 2026-08-19."
+ * - the provider's cap: "Provider's market cap; its 2.46B share count predates the 10-for-1 split on 2024-06-10."
+ */
+function splitShareCountNote(split: SplitShareBasis & { shares?: number }): string {
+  const ratio = splitRatio(split.priceFactor);
+  if (split.method === "provider_cap") {
+    return `Provider's market cap; its ${formatCompact(split.reportedShares)} share count predates the ${ratio} on ${split.exDate}.`;
+  }
+  const shown = positiveFinite(split.shares) ? `${formatCompact(split.shares)} shares: ` : "";
+  const filed = split.reportedAsOf ? ` filed ${split.reportedAsOf}` : " filed";
+  return `${shown}${formatCompact(split.reportedShares)}${filed}, adjusted for the ${ratio} on ${split.exDate}.`;
+}
+
+/**
+ * What a view says when its market cap and the share count shown beside it are not the provider's cap alone:
+ * - the product shown: "Market cap 23.69B AUD is the 1.99B shares shown x 11.93 AUD; the provider's is 24.40B AUD."
+ * - the provider's shown, on another count: "Market cap 79.11M USD is the provider's and does not rest on the
+ *   72.23M shares shown (x 0.7133 USD = 51.52M)."
+ * A recent split that moved the count is said first (splitShareCountNote).
+ * Undefined when the provider's cap ties with the count and no split moved it.
+ */
+export function marketCapBasisNote(capitalization: ViewMarketCapitalization | null): string | undefined {
+  if (!capitalization) return undefined;
+  const { split } = capitalization;
+  const splitNote = split ? splitShareCountNote(split) : undefined;
+  const basisNote = shareBasisNote(capitalization);
+  return splitNote && basisNote ? `${splitNote} ${basisNote}` : splitNote ?? basisNote;
+}
+
+function shareBasisNote(capitalization: ViewMarketCapitalization): string | undefined {
+  const { currency, computed, otherBasis } = capitalization;
+  const priced = (price: number) => `${formatNumber(price, price < 1 ? 4 : 2)} ${currency}`;
+  if (computed) {
+    return `Market cap ${formatCompact(capitalization.value)} ${currency} is the ${formatCompact(computed.shares)} shares shown x ${priced(computed.price)}; the provider's is ${formatCompact(computed.providerValue)} ${currency}.`;
+  }
+  if (otherBasis) {
+    return `Market cap ${formatCompact(capitalization.value)} ${currency} is the provider's and does not rest on the ${formatCompact(otherBasis.shares)} shares shown (x ${priced(otherBasis.price)} = ${formatCompact(otherBasis.product)}).`;
+  }
+  return undefined;
 }

package/src/utils/max-drawdown.ts

@@ -0,0 +1,64 @@
+/**
+ * The largest fall from a close to a later close (docs/usage.md, under `history`):
+ * the peak it fell from and the trough it reached, each with its date, the
+ * fall as a fraction of the peak, and the first later close back at the peak,
+ * if any. Read off closes, as returns are; a missing or non-positive close is
+ * passed over. The earliest of equal falls is the one named.
+ */
+export interface MaxDrawdown {
+  peak: { date: string; close: number };
+  trough: { date: string; close: number };
+  /** trough / peak - 1: 0 when no close fell below an earlier one, else negative. */
+  drawdown: number;
+  /** The first date after the trough whose close is back at the peak; null when none is in the series. */
+  recovered: string | null;
+  /** The last date in the series, which a fall not yet recovered is measured to. */
+  through: string;
+}
+
+interface ClosePoint {
+  /** An ISO date or instant; points sort by it. */
+  date: string;
+  close: number | null | undefined;
+}
+
+/** The series' max drawdown, or null with fewer than two closes. */
+export function maxDrawdown(points: readonly ClosePoint[]): MaxDrawdown | null {
+  const closes = points
+    .filter((point): point is { date: string; close: number } => typeof point.close === "number" && Number.isFinite(point.close) && point.close > 0)
+    .toSorted((left, right) => left.date.localeCompare(right.date));
+  if (closes.length < 2) return null;
+  let peak = closes[0]!;
+  let worst = { peak, trough: peak, drawdown: 0 };
+  for (const point of closes) {
+    if (point.close > peak.close) peak = point;
+    const fall = point.close / peak.close - 1;
+    if (fall < worst.drawdown) worst = { peak, trough: point, drawdown: fall };
+  }
+  const recovered = worst.drawdown < 0
+    ? closes.find((point) => point.date > worst.trough.date && point.close >= worst.peak.close)?.date ?? null
+    : null;
+  return {
+    peak: { date: worst.peak.date, close: worst.peak.close },
+    trough: { date: worst.trough.date, close: worst.trough.close },
+    drawdown: worst.drawdown,
+    recovered,
+    through: closes.at(-1)!.date,
+  };
+}
+
+/**
+ * The report line: `Max drawdown -69.6% (daily closes): peak 53.25 on 2007-05-30, trough 16.19 on 2009-03-09,
+ * not back to the peak by 2009-12-31`. `price` and `date` draw a close and a date as the table does.
+ */
+export function maxDrawdownText(
+  value: MaxDrawdown,
+  { basis, price, date = (text) => text.slice(0, 10) }: { basis: string; price: (value: number) => string; date?: (text: string) => string },
+): string {
+  const percent = (value.drawdown * 100).toFixed(1);
+  // A fall that rounds to nothing is still a fall, which -0.0% would hide.
+  const head = `Max drawdown ${percent === "-0.0" ? "under 0.1%" : `${percent}%`} (${basis})`;
+  if (value.drawdown === 0) return `${head}: no close fell below an earlier one`;
+  const back = value.recovered ? `back to the peak on ${date(value.recovered)}` : `not back to the peak by ${date(value.through)}`;
+  return `${head}: peak ${price(value.peak.close)} on ${date(value.peak.date)}, trough ${price(value.trough.close)} on ${date(value.trough.date)}, ${back}`;
+}

package/src/utils/network-failure.ts

@@ -0,0 +1,83 @@
+/** What every surface says when a request to Gloom's data service never got an answer. */
+export const DATA_SERVICE_UNREACHABLE_MESSAGE = "Gloom couldn't reach its data service";
+
+/**
+ * A request that never reached the data service: no connection, a proxy that
+ * refused it, a name that did not resolve. The fetch's own error is the
+ * `cause`, and its `code` (Bun's `ConnectionRefused`, Node's `ENOTFOUND`) is
+ * kept for code that classifies failures by it.
+ */
+export class DataServiceUnreachableError extends Error {
+  readonly code?: string;
+
+  constructor(cause: unknown) {
+    super(DATA_SERVICE_UNREACHABLE_MESSAGE, { cause });
+    this.name = "DataServiceUnreachableError";
+    const code = (cause as { code?: unknown } | null)?.code;
+    if (typeof code === "string") this.code = code;
+  }
+}
+
+/**
+ * Codes a fetch fails with when it never connected: Bun's, then Node's and
+ * the system's. A reset or a closed socket is not one: the request may have
+ * reached the server.
+ */
+const NO_CONNECTION_CODES = new Set([
+  "ConnectionRefused",
+  "FailedToOpenSocket",
+  "ECONNREFUSED",
+  "ENOTFOUND",
+  "EAI_AGAIN",
+  "ENETUNREACH",
+  "EHOSTUNREACH",
+  "ENETDOWN",
+]);
+
+/**
+ * The same failure in each fetch's exact words, so a server's or a broker's
+ * sentence that merely starts the same way ("Failed to fetch quote from
+ * upstream", "Unable to connect to IB Gateway") is not one: Bun's, which the
+ * desktop relays from its Bun process as a plain message, then a browser's
+ * (Chrome, Safari, Firefox).
+ */
+const NO_CONNECTION_MESSAGES = new Set([
+  "Unable to connect. Is the computer able to access the url?",
+  "Failed to fetch",
+  "Load failed",
+  "NetworkError when attempting to fetch resource.",
+]);
+
+/** An answer came back: an HTTP status, or an error the server wrote. Its code is the server's, not a socket's. */
+function cameFromServer(error: object): boolean {
+  const { name, status, statusCode } = error as { name?: unknown; status?: unknown; statusCode?: unknown };
+  return typeof status === "number" || typeof statusCode === "number" || name === "ApiRequestError";
+}
+
+/**
+ * Whether a request failed before any answer came back. A caller's abort and
+ * a timeout are not: the first is on purpose, and the second reached a server
+ * that did not answer in time. Nor is anything the server answered, whatever
+ * its text or code says.
+ */
+export function isNetworkFailure(error: unknown): boolean {
+  if (typeof error === "string") return NO_CONNECTION_MESSAGES.has(error.trim());
+  for (let current = error, depth = 0; current && typeof current === "object" && depth < 4; depth += 1) {
+    if (current instanceof DataServiceUnreachableError) return true;
+    if (cameFromServer(current)) return false;
+    const { name, code, message } = current as { name?: unknown; code?: unknown; message?: unknown };
+    if (name === "AbortError" || name === "TimeoutError") return false;
+    if (typeof code === "string" && NO_CONNECTION_CODES.has(code)) return true;
+    if (typeof message === "string" && NO_CONNECTION_MESSAGES.has(message.trim())) return true;
+    // Node's fetch says only "fetch failed" and puts the socket's error in `cause`.
+    current = (current as { cause?: unknown }).cause;
+  }
+  return false;
+}
+
+/** A network failure as `DataServiceUnreachableError`; anything else as it was. */
+export function asDataServiceFailure(error: unknown): unknown {
+  return isNetworkFailure(error) && !(error instanceof DataServiceUnreachableError)
+    ? new DataServiceUnreachableError(error)
+    : error;
+}