@gloom-sh/terminal 0.18.5 → 0.19.0

package/src/plugins/builtin/realized-vol/pane.tsx

@@ -109,7 +109,7 @@ export function RealizedVolPane({ width, height, focused }: PaneProps) {
   const refreshedCurrent = refreshedIv?.owner === ivLoader && refreshedIv.at > (loadedIv.updatedAt ?? 0) ? refreshedIv.data : null;
   const iv = { ...loadedIv, data: refreshedCurrent ?? loadedIv.data };
   ivDataRef.current = iv.data;
-  useLiveSessionRefresh(refreshIv, ATM_IV_REFRESH_MS, showIv && spotAvailable && !!iv.data?.reference && !loadedIv.loading,
+  const ivRefresh = useLiveSessionRefresh(refreshIv, ATM_IV_REFRESH_MS, showIv && spotAvailable && !!iv.data?.reference && !loadedIv.loading,
     loadedIv.updatedAt);
   const model = useMemo(() => history.data ? projectRealizedVolatility(history.data.history, {
     symbol: history.data.symbol, estimator, windows, lookbackYears: Number(lookback) === 2 ? 2 : 1,
@@ -117,7 +117,7 @@ export function RealizedVolPane({ width, height, focused }: PaneProps) {
   const chartInput = useMemo(() => model ? { history: model.history, rolling: model.series, windows: model.windows,
     priceUnit: priceSeriesUnit(quote?.currency ?? "", quote?.instrumentType), iv: showIv ? iv.data?.reference ?? null : null } : null,
   [model, quote?.currency, quote?.instrumentType, showIv, iv.data]);
-  const notices = [identityError, history.error, history.data?.error, iv.error, iv.data?.error,
+  const notices = [identityError, history.error, history.data?.error, iv.error, ivRefresh.error, iv.data?.error,
     ...(model?.warnings ?? []), ...(showIv ? iv.data?.warnings ?? [] : []),
     ...(showIv && symbol && !spotAvailable ? ["Current ATM IV unavailable: underlying quote is missing or stale"] : []),
   ].filter((value): value is string => !!value);
@@ -161,7 +161,7 @@ export function RealizedVolPane({ width, height, focused }: PaneProps) {
     stale: history.data?.stale ?? false, source: history.data?.source ?? null,
     asOf: model?.asOf?.toISOString() ?? null,
     errors: [...new Set([history.error, history.data?.error, ...(model?.warnings ?? []),
-      ...(showIv ? [iv.error, iv.data?.error, !iv.data?.reference ? "Current ATM IV unavailable" : null] : []),
+      ...(showIv ? [iv.error, ivRefresh.error, iv.data?.error, !iv.data?.reference ? "Current ATM IV unavailable" : null] : []),
     ].filter((value): value is string => !!value))],
     currentIv: showIv && iv.data?.reference ? { value: iv.data.reference.value * 100,
       date: iv.data.reference.date.toISOString(), label: iv.data.reference.label,

package/src/plugins/builtin/relative-rotation/client.ts

@@ -7,6 +7,7 @@ import type {
 } from "../../../api-client/types";
 import { createPluginCache } from "../../../data/plugin-cache";
 import { isAccessDenied } from "../../../api-client/errors";
+import { quoteTradingExchange } from "../../../market-data/quotes/metadata";
 import { cachedCloudResource, loadCloudResource } from "../shared/cloud-resource";
 import {
   buildRotation,
@@ -75,6 +76,10 @@ export function validateRotationHistory(
     throw new Error("Invalid daily history.");
   return response.data;
 }
+/** The venue a quote is for, as `quote` names it; empty when it names none. */
+function listingVenue(quote: CloudQuotePayload | undefined): string {
+  return quote ? quoteTradingExchange(quote) : "";
+}
 export async function fetchRotation(
   benchmark: RotationInstrument,
   instruments: RotationInstrument[],
@@ -106,6 +111,16 @@ export async function fetchRotation(
     if (isAccessDenied(error)) throw error;
     quoteError = "Listing currencies unavailable.";
   }
+  // A benchmark typed without its exchange (ACWI) is the listing its quote is for (ACWI:NASDAQ), as `quote`
+  // reads it: that venue's calendar picks the weekly closes.
+  const venue = benchmark.exchange
+    ? ""
+    : listingVenue(quotes.get(rotationId(benchmark)));
+  const reference = venue ? { ...benchmark, exchange: venue } : benchmark;
+  const requested = unique.map((row) => ({
+    id: rotationId(row),
+    instrument: rotationId(row) === rotationId(benchmark) ? reference : row,
+  }));
   const start = new Date(now);
   start.setUTCFullYear(start.getUTCFullYear() - 3);
   start.setUTCDate(1);
@@ -115,10 +130,9 @@ export async function fetchRotation(
   let next = 0;
   // Bound Cloud history requests; shared server caches batch upstream demand.
   await Promise.all(
-    Array.from({ length: Math.min(4, unique.length) }, async () => {
-      while (next < unique.length) {
-        const instrument = unique[next++]!,
-          id = rotationId(instrument),
+    Array.from({ length: Math.min(4, requested.length) }, async () => {
+      while (next < requested.length) {
+        const { id, instrument } = requested[next++]!,
           currency = quotes.get(id)?.currency ?? null;
         try {
           const response = await client.getCloudHistory(

package/src/plugins/builtin/relative-rotation/headless.ts

@@ -1,6 +1,6 @@
 import type { HeadlessPaneDefinition } from "../../../types/plugin";
 import { fetchRotation } from "./client";
-import { rotationInstruments, sectorRotationInstruments } from "./model";
+import { DEFAULT_ROTATION_BENCHMARK, rotationInstruments, sectorRotationInstruments } from "./model";
 
 /** Same rounding as the pane: ratios to 2 decimals, percentiles whole. */
 const fixed = (value: unknown, digits: number) =>
@@ -21,7 +21,7 @@ export const rotationHeadless: HeadlessPaneDefinition<"bundle"> = {
       key: "benchmark",
       type: "string",
       description: "Benchmark listing.",
-      defaultValue: "SPY:NYSEARCA",
+      defaultValue: DEFAULT_ROTATION_BENCHMARK,
     },
     {
       key: "trail",
@@ -44,7 +44,7 @@ export const rotationHeadless: HeadlessPaneDefinition<"bundle"> = {
   },
   async load(args, ctx) {
     const references = rotationInstruments(
-      String(args.options.benchmark ?? "SPY:NYSEARCA"),
+      String(args.options.benchmark ?? DEFAULT_ROTATION_BENCHMARK),
     );
     if (references.length !== 1) throw new Error("Choose one benchmark.");
     const instruments = args.symbols.length

package/src/plugins/builtin/relative-rotation/index.tsx

@@ -3,6 +3,7 @@ import type { PluginModule } from "../plugin-module";
 import { rotationCache } from "./client";
 import { rotationHeadless } from "./headless";
 import { RelativeRotationPane } from "./pane";
+import { DEFAULT_ROTATION_BENCHMARK } from "./model";
 
 export const relativeRotationModule: PluginModule = {
   panes: [
@@ -41,7 +42,7 @@ export const relativeRotationModule: PluginModule = {
             key: "benchmark",
             label: "Benchmark",
             type: "text",
-            placeholder: "SPY:NYSEARCA",
+            placeholder: DEFAULT_ROTATION_BENCHMARK,
           },
           {
             key: "trail",

package/src/plugins/builtin/relative-rotation/model.ts

@@ -2,6 +2,7 @@ import { publishedWeekClose } from "../analytics/sharpe-cadence";
 import { historyStatistics } from "../../../components/chart/curve/model";
 import type { CloudPricePointPayload } from "../../../api-client/types";
 import { getSectorCollection } from "../sectors/sector-data";
+import { rotationQuadrant, rotationSeries, type RotationQuadrantName } from "../alerts/metric-model";
 import {
   canonicalExchange,
   normalizeSymbol,
@@ -11,6 +12,8 @@ import {
 const DAY = 86_400_000;
 const WEEK = 7 * DAY;
 export const ROTATION_LIMIT = 24;
+/** RRG's benchmark when none is chosen; RRG alerts default to it too. */
+export const DEFAULT_ROTATION_BENCHMARK = "SPY:NYSEARCA";
 export interface RotationInstrument {
   symbol: string;
   exchange: string;
@@ -46,8 +49,7 @@ export interface RotationRow {
   asOf: string | null;
   strength: number | null;
   momentum: number | null;
-  quadrant:
-    "Leading" | "Weakening" | "Lagging" | "Improving" | "Neutral" | null;
+  quadrant: RotationQuadrantName | null;
   strengthRank: RotationRank;
   momentumRank: RotationRank;
   relativeReturn13w: number | null;
@@ -149,21 +151,8 @@ function rotationRank(
     lastDate: stats.endDate,
   };
 }
-export function rotationQuadrant(
-  strength: number | null,
-  momentum: number | null,
-): RotationRow["quadrant"] {
-  if (strength == null || momentum == null) return null;
-  if (Math.abs(strength - 100) < 1e-9 || Math.abs(momentum - 100) < 1e-9)
-    return "Neutral";
-  return strength > 100
-    ? momentum > 100
-      ? "Leading"
-      : "Weakening"
-    : momentum > 100
-      ? "Improving"
-      : "Lagging";
-}
+/** The weekly strength, momentum and quadrant math is the RRG alert's, shared with Gloom Cloud's delivery. */
+export { rotationQuadrant };
 export function buildRotation(
   benchmark: RotationHistory,
   instruments: RotationHistory[],
@@ -219,10 +208,12 @@ export function buildRotation(
   const benchmarkUsable = !!benchmark.currency && !!asOf;
   const rows = instruments.map((source): RotationRow => {
     const closes = rotationCloses(source.points, through);
+    // A benchmark with no usable weeks says so once in `gaps`; its rows are not to blame for it.
     const gaps = [
       source.error,
       source.stale ? "History is stale." : null,
-      source.currency !== benchmark.currency || !source.currency
+      benchmarkUsable &&
+      (source.currency !== benchmark.currency || !source.currency)
         ? "Price currency does not match the benchmark."
         : null,
     ].filter((x): x is string => !!x);
@@ -240,34 +231,16 @@ export function buildRotation(
         ? ratio
         : null;
     });
-    const strengths = ratios.map((ratio, index) => {
-      const window = ratios.slice(Math.max(0, index - 12), index + 1);
-      if (
-        ratio == null ||
-        window.length !== 13 ||
-        window.some((value) => value == null)
-      )
-        return null;
-      const mean =
-        (window as number[]).reduce((sum, value) => sum + value, 0) / 13;
-      return (100 * ratio) / mean;
-    });
+    const series = rotationSeries(ratios);
     const history = weeks.map((week, index): RotationPoint => {
-      const strength = strengths[index] ?? null,
-        previous = index >= 4 ? (strengths[index - 4] ?? null) : null;
-      const contiguous =
-        index >= 4 &&
-        strengths.slice(index - 4, index + 1).every((value) => value != null);
+      const { strength, momentum } = series[index]!;
       const priorRatio = index >= 13 ? (ratios[index - 13] ?? null) : null,
         ratio = ratios[index] ?? null;
       return {
         date: weekly.get(week)?.date ?? week,
         week,
         strength,
-        momentum:
-          strength != null && previous != null && contiguous
-            ? (100 * strength) / previous
-            : null,
+        momentum,
         relativeReturn13w:
           ratio != null &&
           priorRatio != null &&
@@ -284,7 +257,10 @@ export function buildRotation(
       Number.isFinite(latest.strength) &&
       latest.momentum != null &&
       Number.isFinite(latest.momentum);
-    if (!latest || latest.strength == null || latest.momentum == null)
+    if (
+      benchmarkUsable &&
+      (!latest || latest.strength == null || latest.momentum == null)
+    )
       gaps.push(
         "At least 17 contiguous matched weekly closes are required; a missing week breaks the trail.",
       );

package/src/plugins/builtin/relative-rotation/pane.tsx

@@ -36,6 +36,7 @@ import {
 import { useResearchCloudSession } from "../shared/research-cloud-session";
 import { cachedRotation, loadRotation } from "./client";
 import {
+  DEFAULT_ROTATION_BENCHMARK,
   ROTATION_LIMIT,
   rotationId,
   rotationTrailWeeks,
@@ -140,13 +141,13 @@ function RotationDetail({
 export function RelativeRotationPane(props: PaneProps) {
   const [scope] = usePaneSettingValue("scope", "sectors");
   const [symbols] = usePaneSettingValue("symbols", "");
-  const [benchmarkText] = usePaneSettingValue("benchmark", "SPY:NYSEARCA");
+  const [benchmarkText] = usePaneSettingValue("benchmark", DEFAULT_ROTATION_BENCHMARK);
   const [trailText] = usePaneSettingValue("trail", "6");
   const { collectionId } = usePaneCollection();
   const tickers = useTickers();
   const context = useMemo(() => {
     try {
-      const references = rotationInstruments(benchmarkText || "SPY:NYSEARCA");
+      const references = rotationInstruments(benchmarkText || DEFAULT_ROTATION_BENCHMARK);
       if (references.length !== 1)
         throw new Error("Choose one benchmark in pane settings.");
       const instruments =

package/src/plugins/builtin/research/corporate-actions-pane.tsx

@@ -446,6 +446,7 @@ export function CorporateActionsView({
   const financialCurrency = tickerFinancials?.financialCurrency;
   const trailingEps = tickerFinancials?.fundamentals?.eps;
   const trailingEpsCurrency = tickerFinancials?.fundamentals?.epsCurrency;
+  const trailingEpsSource = tickerFinancials?.fundamentals?.trailingEpsSource;
   const fundamentalsCurrency = tickerFinancials?.fundamentals?.financialCurrency;
   const marketCapCurrency = tickerFinancials?.fundamentals?.marketCapCurrency;
   const quoteCurrency = tickerFinancials?.quote?.currency;
@@ -453,10 +454,10 @@ export function CorporateActionsView({
     () => (quarterlyStatements || financialCurrency || trailingEps != null ? {
       quarterlyStatements: quarterlyStatements ?? [],
       financialCurrency,
-      fundamentals: { eps: trailingEps, epsCurrency: trailingEpsCurrency, financialCurrency: fundamentalsCurrency, marketCapCurrency },
+      fundamentals: { eps: trailingEps, epsCurrency: trailingEpsCurrency, financialCurrency: fundamentalsCurrency, marketCapCurrency, trailingEpsSource },
       quote: quoteCurrency ? { currency: quoteCurrency } : null,
     } : null),
-    [financialCurrency, fundamentalsCurrency, marketCapCurrency, quarterlyStatements, quoteCurrency, trailingEps, trailingEpsCurrency],
+    [financialCurrency, fundamentalsCurrency, marketCapCurrency, quarterlyStatements, quoteCurrency, trailingEps, trailingEpsCurrency, trailingEpsSource],
   );
   const actionsLoader = useCallback((nextSymbol: string, nextExchange: string, forceRefresh: boolean) => {
     if (!dataProvider?.getCorporateActions) throw new Error("Corporate actions source unavailable");

package/src/plugins/builtin/research/event-model.ts

@@ -15,7 +15,7 @@ import {
 } from "../../../utils/format";
 import { computeTTM } from "../ticker-detail/financials/aggregation";
 import { declaredDividends } from "../../../utils/declared-dividends";
-import { fundamentalsEpsCurrency } from "../../../utils/fundamentals";
+import { fundamentalsEpsCurrency, SERVED_TRAILING_EPS } from "../../../utils/fundamentals";
 import {
   earningsDateStatus,
   earningsDetail,
@@ -175,11 +175,11 @@ function estimateValue(pair: EstimatePair): string {
 }
 
 /**
- * What the TTM row reads: the statements for its four quarters and revenue, and the trailing EPS Gloom Cloud serves
- * with the fundamentals, the figure `ticker` prints as EPS (TTM).
+ * What the TTM row reads: the statements for its four quarters and revenue, and the trailing EPS of the fundamentals,
+ * the figure `ticker` prints as EPS (TTM) (the filed quarters' when they give one, see time-series/filed-trailing-eps).
  */
 export type EventFinancials = Pick<TickerFinancials, "quarterlyStatements" | "financialCurrency"> & {
-  fundamentals?: Pick<NonNullable<TickerFinancials["fundamentals"]>, "eps" | "epsCurrency" | "financialCurrency" | "marketCapCurrency"> | null;
+  fundamentals?: Pick<NonNullable<TickerFinancials["fundamentals"]>, "eps" | "epsCurrency" | "financialCurrency" | "marketCapCurrency" | "trailingEpsSource"> | null;
   /** The listing's currency, which says whether an unlabelled EPS can be in the statements' (fundamentalsCurrency). */
   quote?: Pick<NonNullable<TickerFinancials["quote"]>, "currency"> | null;
 };
@@ -204,9 +204,10 @@ function adjustedQuarterSum(
 }
 
 /**
- * The TTM row's EPS is the GAAP diluted trailing figure, the one `ticker` prints as EPS (TTM). Without it, the four
- * statement quarters' diluted EPS summed. The reported rows above it are often adjusted, so they are never added to
- * it: only when all four are adjusted does the detail also give their sum.
+ * The TTM row's EPS is the GAAP diluted trailing figure `ticker` prints as EPS (TTM): the last four filed quarters',
+ * or Gloom Cloud's trailing figure, named so, when they give none. Without either, the four statement quarters'
+ * diluted EPS summed. The reported rows above it are often adjusted, so they are never added to it: only when all
+ * four are adjusted does the detail also give their sum.
  */
 function ttmRow(
   quarterlyStatements: readonly FinancialStatement[],
@@ -226,7 +227,8 @@ function ttmRow(
     date: latest?.date ?? "",
     status: "TTM",
     period: "4 qtrs",
-    detail: [eps == null ? "statement sum" : served ? "GAAP diluted" : "GAAP diluted (statements)",
+    detail: [eps == null ? "statement sum" : !served ? "GAAP diluted (statements)"
+      : financials?.fundamentals?.trailingEpsSource === "served" ? `GAAP diluted (${SERVED_TRAILING_EPS})` : "GAAP diluted",
       adjusted == null ? null : `adj sum ${formatNumber(adjusted, 2)}`].filter(Boolean).join(", "),
     epsCurrency: served ? fundamentalsEpsCurrency(financials) : ttm.currency ?? financials?.financialCurrency,
     revenueCurrency: ttm.currency ?? financials?.financialCurrency,

package/src/plugins/builtin/research/headless.ts

@@ -83,7 +83,7 @@ function projectEarningsEstimatesHeadless(
       returned: rows.length,
       truncated: rows.length < matching.length,
       coverageNote: notice?.text,
-      epsBasis: `${EPS_BASIS_NOTE} The TTM row's EPS is the GAAP diluted trailing figure ticker shows as EPS (TTM), or the four statement quarters' diluted EPS when none is served; reported quarters of different bases are never summed, and the row adds an adjusted sum only when all four quarters are adjusted.`,
+      epsBasis: `${EPS_BASIS_NOTE} The TTM row's EPS is the GAAP diluted trailing figure ticker shows as EPS (TTM): the last four filed quarters', or Gloom Cloud's TTM (named so) when they give none, or the four statement quarters' diluted EPS when neither is there; reported quarters of different bases are never summed, and the row adds an adjusted sum only when all four quarters are adjusted.`,
       dateNote: "Fiscal period dates are not announcement dates. Revenue is attached only to an identified statement period.",
       unmatchedReportedPeriods,
     },

package/src/plugins/builtin/research/relative-valuation-headless.ts

@@ -96,7 +96,10 @@ const VALUATION_COLUMNS: HeadlessPaneColumn[] = [
   ...([["fcfYield", "FCF Yield"], ["revenueGrowth", REVENUE_GROWTH_HEADER], ["operatingMargin", "TTM Op Margin"]] as const).map(([key, header]) => ({
     key, header, align: "right" as const,
     format: (value: unknown, row: Record<string, unknown>) => value == null ? gapText(row, key)
-      : key === "revenueGrowth" ? formatPercent(Number(value)) : formatLevelPercent(Number(value)),
+      : key === "revenueGrowth" ? formatPercent(Number(value))
+        // A margin of the latest fiscal year, where no trailing quarters were served, says which year.
+        : key === "operatingMargin" && typeof row.operatingMarginPeriod === "string"
+          ? `${formatLevelPercent(Number(value))} ${row.operatingMarginPeriod}` : formatLevelPercent(Number(value)),
   })),
 ];
 
@@ -226,6 +229,7 @@ export const relativeValuationHeadless: HeadlessPaneDefinition<"rows"> = {
           ...rows.flatMap((row) => row.evSalesUnavailable ? [`${row.symbol}: ${row.evSalesUnavailable}`] : []),
           ...rows.flatMap((row) => row.evSalesNote ? [`${row.symbol}: ${row.evSalesNote}`] : []),
           ...rows.flatMap((row) => row.marketCapNote ? [`${row.symbol}: ${row.marketCapNote}`] : []),
+          ...rows.flatMap((row) => row.marketCapWithheld ? [`${row.symbol}: ${row.marketCapWithheld}`] : []),
         ],
         multipleBasis: "Comparable P/E fields require a positive finite multiple over positive EPS, and evSales an enterprise value above zero; notMeaningful says why one is null, and reportedMultiples preserves the finite provider P/E values.",
         marketCapBasis: "Market caps retain their own currency and source. Fundamentals retrieval time is not a valuation date; quote timestamps do not date fallback caps.",

package/src/plugins/builtin/research/relative-valuation-model.ts

@@ -1,9 +1,10 @@
 import { formatCurrency } from "../../../utils/format";
 import { comparablePriceEarnings, notMeaningfulMultiples } from "../../../utils/price-earnings";
-import { marketCapBasisNote, viewMarketCapitalization } from "../../../utils/market-capitalization";
+import { marketCapBasisNote, viewMarketCapitalization, withheldMarketCap } from "../../../utils/market-capitalization";
 import { enterpriseValueNotMeaningful, enterpriseValueReconciliationNote, enterpriseValueWithdrawn, reportedEnterpriseValue } from "../../../utils/fundamentals";
 import { getExtendedSessionDisplay, getQuoteSessionFields } from "../../../market-data/market/status";
 import { atRegularSessionPrice, movePriceDerivedFigures, regularSessionValuationPrice } from "../../../market-data/quotes/regular-session-valuation";
+import { fiscalPeriodLabel, fiscalYearEndMonth } from "../../../utils/fiscal-period";
 import { latestFinancialPeriod, latestReportedPeriod } from "../../../utils/latest-financial-period";
 import type { Quote, TickerFinancials } from "../../../types/financials";
 
@@ -50,6 +51,25 @@ function fcfYieldGap(fundamentals: TickerFinancials["fundamentals"], capCurrency
 }
 export const RELATIVE_VALUATION_STALE_FUNDAMENTALS_NOTICE = "Fundamentals stale: retained values may be out of date";
 
+/**
+ * The operating margin of the latest fiscal year, for a row whose trailing
+ * twelve months are not whole (a quarter the source has not carried yet):
+ * that year's operating income over its revenue, named for the year ("FY25")
+ * so a cell never passes it off as trailing. Null when the latest year lacks
+ * either figure; an older year is never stood in for it.
+ */
+function fiscalYearOperatingMargin(annualStatements: TickerFinancials["annualStatements"] | undefined) {
+  const latest = latestFinancialPeriod(annualStatements, (row) => row.date);
+  if (!latest || !finiteNumber(latest.operatingIncome) || !finiteNumber(latest.totalRevenue) || latest.totalRevenue <= 0) return null;
+  const year = /^FY\d{2}(\d{2})$/.exec(fiscalPeriodLabel(latest.date, "annual", fiscalYearEndMonth(annualStatements ?? [])))?.[1];
+  return {
+    value: latest.operatingIncome / latest.totalRevenue,
+    // The fiscal year's own name; the calendar year of its end where the year cannot be named.
+    label: `FY${year ?? latest.date.slice(2, 4)}`,
+    periodEnd: latest.date.slice(0, 10),
+  };
+}
+
 /**
  * A peer's row. Last, its change and the extended print are the quote's
  * sessions as `quote` reads them (getQuoteSessionFields): after the close,
@@ -97,14 +117,17 @@ export function relativeValuationValues(snapshot: TickerFinancials | null) {
     && fundamentals.freeCashFlow != null && Number.isFinite(fundamentals.freeCashFlow) && capitalization.value > 0
     ? fundamentals.freeCashFlow / capitalization.value : null;
   const revenueGrowth = fundamentals?.revenueGrowth ?? fundamentals?.lastQuarterGrowth ?? null;
-  const operatingMargin = fundamentals?.operatingMargin ?? null;
+  const trailingOperatingMargin = fundamentals?.operatingMargin ?? null;
+  const fiscalYearMargin = trailingOperatingMargin == null ? fiscalYearOperatingMargin(financials?.annualStatements) : null;
+  const operatingMargin = trailingOperatingMargin ?? fiscalYearMargin?.value ?? null;
   const trailingPE = trailingNotMeaningful ? null : comparablePriceEarnings(reportedMultiples.trailingPE);
   const forwardPE = forwardNotMeaningful ? null : comparablePriceEarnings(reportedMultiples.forwardPE);
   // Every figure a row lacks says why, so an export's blank cell is never silent: N/M multiples say so themselves.
   const gaps: Partial<Record<RelativeValuationGapKey, string>> = {};
   if (session.price == null) gaps.price = quoteStale ? QUOTE_STALE : NOT_REPORTED;
   if (session.changePercent == null) gaps.changePercent = quoteStale ? QUOTE_STALE : NOT_REPORTED;
-  if (capitalization == null) gaps.marketCap = quoteStale && !fundamentals?.marketCap ? QUOTE_STALE : NOT_REPORTED;
+  const withheld = withheldMarketCap(fundamentals);
+  if (capitalization == null) gaps.marketCap = withheld?.gap ?? (quoteStale && !fundamentals?.marketCap ? QUOTE_STALE : NOT_REPORTED);
   if (trailingPE == null && !trailingNotMeaningful && reportedMultiples.trailingPE == null) gaps.trailingPE = NOT_REPORTED;
   if (forwardPE == null && !forwardNotMeaningful && reportedMultiples.forwardPE == null) gaps.forwardPE = NOT_REPORTED;
   if (evSales == null && !evSalesNotMeaningful) gaps.evSales = evSalesGap(fundamentals, quote?.currency, evSalesWithdrawn, enterpriseValueGap);
@@ -136,6 +159,8 @@ export function relativeValuationValues(snapshot: TickerFinancials | null) {
     marketCapProvenance: capitalization?.provenance ?? null,
     /** valuation's note when the cap is the share count times the price: the provider's figure it replaced. */
     marketCapNote: marketCapBasisNote(capitalization) ?? null,
+    /** Why Gloom Cloud withheld the cap (a receipt priced as ordinary shares), as `valuation` and EQS say it; null otherwise. */
+    marketCapWithheld: withheld?.note ?? null,
     trailingPE,
     forwardPE,
     reportedMultiples,
@@ -151,6 +176,9 @@ export function relativeValuationValues(snapshot: TickerFinancials | null) {
     fcfYield,
     revenueGrowth,
     operatingMargin,
+    /** The fiscal year the operating margin is of ("FY25") when no trailing figure was served; null when it is trailing twelve months. */
+    operatingMarginPeriod: fiscalYearMargin?.label ?? null,
+    operatingMarginPeriodEnd: fiscalYearMargin?.periodEnd ?? null,
     /** Why each missing figure is missing, in a few words the row draws in its place. */
     gaps,
   };

package/src/plugins/builtin/research/relative-valuation-pane.tsx

@@ -97,7 +97,7 @@ function extendedMove(row: RelativeRow, columnId: ExtendedColumnId): number | nu
  * AFTER-HRS or OVERNIGHT column, named as BI and MOST name it, follows CHG%
  * for each session in `extendedSessions`.
  */
-function buildRelativeColumns(baseCurrency: string, extendedSessions: readonly ExtendedSession[]): RelativeColumn[] {
+function buildRelativeColumns(baseCurrency: string, extendedSessions: readonly ExtendedSession[], marginNamesYear: boolean): RelativeColumn[] {
   const symbolWidth = 8;
   const priceWidth = 10;
   const pctWidth = 8;
@@ -117,7 +117,8 @@ function buildRelativeColumns(baseCurrency: string, extendedSessions: readonly E
     { id: "fcfYield", label: "FCF%", width: metricWidth, align: "right" },
     // Latest quarter against the year before, and a trailing-twelve-month margin.
     { id: "revenueGrowth", label: REVENUE_GROWTH_LABEL, width: metricWidth, align: "right" },
-    { id: "operatingMargin", label: "TTM OP%", width: metricWidth, align: "right" },
+    // Wider while a peer's margin is of its latest fiscal year and names it ("16.83% FY25").
+    { id: "operatingMargin", label: "TTM OP%", width: marginNamesYear ? 12 : metricWidth, align: "right" },
   ];
 }
 
@@ -217,9 +218,10 @@ export function RelativeValuationPane({ focused, width, height }: PaneProps) {
   const fxRates = useFxRatesMap([baseCurrency, ...rows.map((row) => row.marketCapCurrency)]);
   // A pre-market or after-hours print gets its own column when a peer has one.
   const extendedSessionsKey = extendedSessionsOf(rows).join(",");
+  const marginNamesYear = rows.some((row) => row.operatingMarginPeriod != null);
   const columns = useMemo(
-    () => buildRelativeColumns(baseCurrency, extendedSessionsKey ? extendedSessionsKey.split(",") as ExtendedSession[] : []),
-    [baseCurrency, extendedSessionsKey],
+    () => buildRelativeColumns(baseCurrency, extendedSessionsKey ? extendedSessionsKey.split(",") as ExtendedSession[] : [], marginNamesYear),
+    [baseCurrency, extendedSessionsKey, marginNamesYear],
   );
 
   const comparableRows = useMemo(() => rows.map((row) => ({
@@ -319,7 +321,7 @@ export function RelativeValuationPane({ focused, width, height }: PaneProps) {
       case "revenueGrowth":
         return { text: formatPercent(row.revenueGrowth ?? undefined), color: shownPriceColor((row.revenueGrowth ?? 0) * 100, 2) };
       case "operatingMargin":
-        return { text: formatLevelPercent(row.operatingMargin ?? undefined), color: colors.text };
+        return { text: `${formatLevelPercent(row.operatingMargin ?? undefined)}${row.operatingMargin != null && row.operatingMarginPeriod ? ` ${row.operatingMarginPeriod}` : ""}`, color: colors.text };
     }
   }, []);
 

package/src/plugins/builtin/reverse-dcf/headless.ts

@@ -4,7 +4,8 @@ import type { HeadlessPaneDefinition } from "../../../types/plugin";
 import { formatCompactCurrency } from "../../../utils/format";
 import { resolveHeadlessInstrument } from "../shared/headless-market-data";
 import { loadReverseDcfInputs } from "./client";
-import { describeFcfMargin, DISCOUNT_RATES, projectReverseDcf, TERMINAL_GROWTH, TERMINAL_GROWTHS, type ImpliedGrowth } from "./model";
+import { describeFcfMargin, DISCOUNT_RATES, pastGrowthBasis, projectReverseDcf, TERMINAL_GROWTH, TERMINAL_GROWTHS, ttmBaseNote,
+  type ImpliedGrowth } from "./model";
 
 const percent = (value: unknown) => typeof value === "number" ? `${(value * 100).toFixed(1)}%` : "--";
 /** An assumption as it is set: 9%, 2.5%. */
@@ -35,6 +36,7 @@ export const reverseDcfHeadless: HeadlessPaneDefinition<"bundle"> = {
     const quote = inputs.financials?.quote;
     // The enterprise value is measured at the regular session price, so the report is dated by it: after the close, the close.
     const valuedAt = regularSessionValuationTime(quote);
+    const notes = [model.enterpriseValueNote, ttmBaseNote(model)].filter((note): note is string => !!note);
     return {
       sections: [
         { title: "Reverse DCF", columns: [{ key: "label", header: "" }, { key: "value", header: "Value" }], rows: [
@@ -42,7 +44,7 @@ export const reverseDcfHeadless: HeadlessPaneDefinition<"bundle"> = {
             : `${typeof growth === "number" ? percent(growth) : growth} at ${rate(discountRate)} discount, ${rate(TERMINAL_GROWTH)} terminal` },
           { label: "Implied revenue, year 10", value: model.impliedRevenue == null ? "--"
             : `${formatCompactCurrency(model.impliedRevenue, currency)} at ${describeFcfMargin(fcfMargin, fcfMarginBasis)}` },
-          { label: "Past FCF growth", value: model.pastGrowth ? `${percent(model.pastGrowth.rate)} over ${model.pastGrowth.years}y` : "--" },
+          { label: "Past FCF growth", value: model.pastGrowth ? `${percent(model.pastGrowth.rate)} ${pastGrowthBasis(model.pastGrowth)}` : "--" },
           { label: "FCF yield", value: percent(model.fcfYield) },
           { label: "Enterprise value", value: `${formatCompactCurrency(model.enterpriseValue ?? undefined, currency)}${model.enterpriseValueNote ? " (provider)" : ""}` },
           { label: "Free cash flow, TTM", value: formatCompactCurrency(model.freeCashFlow ?? undefined, currency) },
@@ -60,7 +62,7 @@ export const reverseDcfHeadless: HeadlessPaneDefinition<"bundle"> = {
       },
       unavailableSymbols: model.implied ? [] : [instrument.symbol],
       errors: [inputs.error, model.error].filter((value): value is string => !!value),
-      ...(model.enterpriseValueNote ? { notes: [model.enterpriseValueNote] } : {}),
+      ...notes.length > 0 ? { notes } : {},
       metadata: { currency: model.currency, discountRate, terminalGrowth: TERMINAL_GROWTH, discountRates: DISCOUNT_RATES, fcfMargin,
         fcfMarginSource: fcfMarginBasis.source, companyFcfMargin: fcfMarginBasis.company, fcfMarginGap: fcfMarginBasis.gap,
         impliedRevenue: model.impliedRevenue, stale: inputs.stale, fetchedAt: inputs.fetchedAt, methodology: "docs/research-data.md#reverse-dcf" },

package/src/plugins/builtin/reverse-dcf/model.ts

@@ -1,6 +1,8 @@
 import { unavailableText } from "../../../components/ui/status";
 import { atRegularSessionPrice } from "../../../market-data/quotes/regular-session-valuation";
 import type { Fundamentals, TickerFinancials } from "../../../types/financials";
+import { fiscalPeriodLabel, fiscalYearEndMonth } from "../../../utils/fiscal-period";
+import { formatCompactCurrency } from "../../../utils/format";
 import { enterpriseValueCheck, enterpriseValueLabel, enterpriseValueNotMeaningful, enterpriseValueReconciliationNote,
   enterpriseValueWithdrawn, reportedEnterpriseValue } from "../../../utils/fundamentals";
 
@@ -50,8 +52,10 @@ export interface ReverseDcfModel {
   fcfMarginBasis: FcfMarginBasis;
   /** Year-ten revenue at `fcfMargin`: trailing free cash flow grown at the implied rate for ten years, over the margin. */
   impliedRevenue: number | null;
-  /** Annual FCF growth between the latest annual statement and one up to five years earlier, when both are positive. */
-  pastGrowth: { rate: number; years: number } | null;
+  /** Annual FCF growth between the latest annual statement and one up to five years earlier, when both are positive. `period` names the two years: FY2021–FY2025. */
+  pastGrowth: { rate: number; years: number; period: string } | null;
+  /** The latest annual statement's free cash flow, which the past growth ends at, and the year it is of (FY2025). */
+  fiscalYearFcf: { value: number; label: string } | null;
   /** Implied growth for each discount rate (rows) at each terminal growth (columns). */
   sensitivity: { discountRate: number; implied: (ImpliedGrowth | null)[] }[];
   error: string | null;
@@ -82,15 +86,65 @@ export function solveImpliedGrowth(enterpriseValue: number, fcf: number, discoun
   return { kind: "rate", value: (low + high) / 2 };
 }
 
-function pastFcfGrowth(financials: TickerFinancials): ReverseDcfModel["pastGrowth"] {
-  const annual = financials.annualStatements
+/** The latest annual statements with a free cash flow, oldest first, as many as the past growth looks back over. */
+function annualFreeCashFlows(financials: TickerFinancials) {
+  return financials.annualStatements
     .filter((row) => typeof row.freeCashFlow === "number" && Number.isFinite(row.freeCashFlow))
     .sort((a, b) => a.date.localeCompare(b.date))
     .slice(-6);
+}
+
+/** The two years a past growth spans, as issuers name them: `FY2021–FY2025`; period end dates where a year is off the fiscal calendar. */
+function fiscalSpan(financials: TickerFinancials, from: string, to: string): string {
+  const month = fiscalYearEndMonth(financials.annualStatements);
+  const [start, end] = [from, to].map((date) => fiscalPeriodLabel(date, "annual", month)) as [string, string];
+  return start.startsWith("FY") && end.startsWith("FY") ? `${start}–${end}` : `${from.slice(0, 10)} to ${to.slice(0, 10)}`;
+}
+
+function pastFcfGrowth(financials: TickerFinancials): ReverseDcfModel["pastGrowth"] {
+  const annual = annualFreeCashFlows(financials);
   const first = annual[0], last = annual.at(-1);
   if (!first || !last || first === last || !(first.freeCashFlow! > 0) || !(last.freeCashFlow! > 0)) return null;
   const years = Math.round((Date.parse(last.date) - Date.parse(first.date)) / (365.25 * 86_400_000));
-  return years > 0 ? { rate: (last.freeCashFlow! / first.freeCashFlow!) ** (1 / years) - 1, years } : null;
+  return years > 0
+    ? { rate: (last.freeCashFlow! / first.freeCashFlow!) ** (1 / years) - 1, years, period: fiscalSpan(financials, first.date, last.date) }
+    : null;
+}
+
+function latestFiscalYearFcf(financials: TickerFinancials): ReverseDcfModel["fiscalYearFcf"] {
+  const last = annualFreeCashFlows(financials).at(-1);
+  return last ? { value: last.freeCashFlow!, label: fiscalPeriodLabel(last.date, "annual", fiscalYearEndMonth(financials.annualStatements)) } : null;
+}
+
+/** How far above the latest fiscal year's free cash flow the trailing twelve months' must be to say the two bases differ. */
+const TTM_BASE_RATIO = 1.5;
+
+/**
+ * How a trailing free cash flow more than 1.5 times the latest fiscal year's
+ * differs from it (`2.7x` FY2025's `5.3B USD`): the growth priced in starts
+ * from the trailing figure, the past growth ends at the year's. Null when they
+ * are near each other, the year's is not positive, or the model has no growth
+ * to say.
+ */
+export function ttmBaseGap(model: Pick<ReverseDcfModel, "freeCashFlow" | "fiscalYearFcf" | "currency" | "error">): { multiple: string; year: string; fcf: string } | null {
+  const { freeCashFlow, fiscalYearFcf } = model;
+  if (model.error || freeCashFlow == null || !fiscalYearFcf || !(fiscalYearFcf.value > 0) || !(freeCashFlow > fiscalYearFcf.value * TTM_BASE_RATIO)) return null;
+  return {
+    multiple: `${(freeCashFlow / fiscalYearFcf.value).toFixed(1)}x`,
+    year: fiscalYearFcf.label,
+    fcf: formatCompactCurrency(fiscalYearFcf.value, model.currency ?? undefined),
+  };
+}
+
+/** "The TTM base differs from FY2025: TTM FCF is 2.7x that year's 5.3B USD.", the one line a report adds when `ttmBaseGap` finds a gap. */
+export function ttmBaseNote(model: Parameters<typeof ttmBaseGap>[0]): string | null {
+  const gap = ttmBaseGap(model);
+  return gap ? `The TTM base differs from ${gap.year}: TTM FCF is ${gap.multiple} that year's ${gap.fcf}.` : null;
+}
+
+/** What the past growth rate is over, after the rate: `a year, FY2021–FY2025`. */
+export function pastGrowthBasis(growth: NonNullable<ReverseDcfModel["pastGrowth"]>): string {
+  return `a year, ${growth.period}`;
 }
 
 /**
@@ -145,7 +199,8 @@ export function projectReverseDcf(
   const empty: ReverseDcfModel = { symbol: options.symbol, currency, discountRate: options.discountRate, terminalGrowth: TERMINAL_GROWTH,
     enterpriseValue, computedEnterpriseValue: check?.computed ?? null, enterpriseValueNote: check ? enterpriseValueReconciliationNote(fundamentals) ?? null : null,
     freeCashFlow, fcfYield: null, implied: null, fcfMargin, fcfMarginBasis, impliedRevenue: null,
-    pastGrowth: financials ? pastFcfGrowth(financials) : null, sensitivity: [], error: null };
+    pastGrowth: financials ? pastFcfGrowth(financials) : null, fiscalYearFcf: financials ? latestFiscalYearFcf(financials) : null,
+    sensitivity: [], error: null };
   const valueCurrency = fundamentals?.marketCapCurrency;
   // ADRs and cross-listings can report cash flows in one currency and trade in another.
   if (currency && valueCurrency && currency !== valueCurrency) {