gloomberb 0.16.0 → 0.16.2

package/src/plugins/builtin/pe-band/headless.ts

@@ -2,7 +2,8 @@ import { MarketDataCoordinator } from "../../../market-data/coordinator";
 import type { HeadlessPaneDefinition } from "../../../types/plugin";
 import { resolveHeadlessInstrument } from "../shared/headless-market-data";
 import { loadPeBandInputs } from "./client";
-import { formatPerShare, projectPeBand } from "./model";
+import { formatPerShare, fxPairQuote, projectPeBand } from "./model";
+import { DAILY_CLOSES } from "../shared/report-freshness";
 
 const multiple = (value: unknown) => typeof value === "number" ? `${value.toFixed(1)}x` : "--";
 const amount = (value: unknown) => typeof value === "number" ? formatPerShare(value) : "--";
@@ -10,18 +11,29 @@ const percent = (value: unknown) => typeof value === "number" ? `${(value * 100)
 
 export const peBandHeadless: HeadlessPaneDefinition<"bundle"> = {
   shape: "bundle", argument: { kind: "ticker", description: "Ticker" },
+  freshness: { ...DAILY_CLOSES, basis: "daily closes and reported EPS" },
   describe: (args) => `PEB ${args.symbols[0] ?? ""}`,
-  discovery: { screenshotReadiness: "live-dom", limitations: ["Trailing EPS in the listing's own currency; weekly closes."] },
+  discovery: { screenshotReadiness: "live-dom", limitations: [
+    "Weekly closes. EPS reported in another currency than a dollar price is converted at daily FX closes; other currency pairs are not computed.",
+  ] },
   options: [
     { key: "lookbackYears", type: "integer", minimum: 0, maximum: 30, defaultValue: 10, description: "Years of history; 0 for all on record" },
   ],
   async load(args, ctx) {
     const instrument = await resolveHeadlessInstrument(ctx, args.symbols[0]!);
-    const inputs = await loadPeBandInputs({ instrument, signal: ctx.signal }, ctx.marketData, new MarketDataCoordinator(ctx.marketData));
+    const inputs = await loadPeBandInputs({ instrument, signal: ctx.signal }, ctx.marketData, new MarketDataCoordinator(ctx.marketData), ctx.apiClient);
     ctx.signal.throwIfAborted();
     const lookbackYears = Number(args.options.lookbackYears ?? 10);
-    const model = projectPeBand(inputs.financials, inputs.history, { symbol: instrument.symbol, lookbackYears });
+    const model = projectPeBand(inputs.financials, inputs.history, { symbol: instrument.symbol, lookbackYears, reports: inputs.reports,
+      fx: inputs.fx, fxError: inputs.fxError });
     const current = model.current;
+    const conversion = model.conversion;
+    const pairQuote = (rate: number) => {
+      const quote = fxPairQuote(conversion!.currency, rate);
+      return `${quote.pair} ${quote.value.toPrecision(5)}`;
+    };
+    const reported = current?.step?.eps != null && conversion && current.step.currency === conversion.currency
+      ? `, from ${conversion.currency} ${amount(current.step.eps)} at ${pairQuote(conversion.latest.rate)} (${conversion.latest.date} close)` : "";
     return {
       sections: [
         { title: "P/E band", columns: [{ key: "label", header: "" }, { key: "value", header: "Value" }], rows: [
@@ -30,20 +42,26 @@ export const peBandHeadless: HeadlessPaneDefinition<"bundle"> = {
           { label: "Ranked over", value: model.sample ? `${model.sample.weeks} weeks since ${model.sample.start.toISOString().slice(0, 10)}` : "--" },
           { label: "P/E low, median, high", value: model.range ? `${multiple(model.range.min)}, ${multiple(model.range.median)}, ${multiple(model.range.max)}` : "--" },
           { label: "Price", value: `${amount(current?.price)} ${model.currency ?? ""}`.trim() },
-          { label: "Trailing EPS", value: current?.step ? `${amount(current.eps)} (${current.step.basis === "annual" ? "FY" : "TTM"} ${current.step.periodEnd})` : "--" },
+          { label: "Trailing EPS", value: current?.step
+            ? `${amount(current.eps)} (${current.step.basis === "annual" ? "FY" : "TTM"} ${current.step.periodEnd})${reported}` : "--" },
         ] },
         { title: "Price at each multiple", columns: [{ key: "multiple", header: "Multiple", format: multiple }, { key: "price", header: "Price", format: amount }],
           rows: model.multiples.map((value) => ({ multiple: value, price: current?.eps != null && current.eps > 0 ? value * current.eps : null })) },
         { title: "Trailing EPS", columns: [{ key: "periodEnd", header: "Period end" }, { key: "basis", header: "Basis" },
-          { key: "knownAt", header: "Known" }, { key: "eps", header: "EPS", format: amount }, { key: "yoy", header: "YoY", format: percent },
-          { key: "price", header: "Price", format: amount }, { key: "pe", header: "P/E", format: multiple }],
+          { key: "knownAt", header: "Known" }, { key: "eps", header: conversion ? "EPS reported" : "EPS", format: amount },
+          ...(conversion ? [{ key: "currency", header: "Currency" }, { key: "fx", header: "FX close" }] : []),
+          { key: "yoy", header: "YoY", format: percent }, { key: "price", header: "Price", format: amount }, { key: "pe", header: "P/E", format: multiple }],
         rows: model.rows.map((row) => ({ periodEnd: row.periodEnd, basis: row.basis === "annual" ? "FY" : "TTM",
-          knownAt: row.dated ? row.knownAt.toISOString().slice(0, 10) : "period end", eps: row.eps, yoy: row.yoy, price: row.price, pe: row.pe })) },
+          knownAt: row.dated ? row.knownAt.toISOString().slice(0, 10) : "period end", eps: row.eps,
+          ...(conversion ? { currency: row.currency, fx: row.fx ? `${pairQuote(row.fx.rate)} (${row.fx.date})` : row.currency === model.currency ? "" : "--" } : {}),
+          yoy: row.yoy, price: row.price, pe: row.pe })) },
       ],
       complete: !inputs.stale && !inputs.error && !inputs.historyError && !model.error,
       unavailableSymbols: current?.pe != null ? [] : [instrument.symbol],
       errors: [inputs.error, inputs.historyError, model.error, model.notice].filter((value): value is string => !!value),
       metadata: { currency: model.currency, lookbackYears,
+        epsConversion: conversion ? { from: conversion.currency, to: model.currency, usdPerUnit: conversion.latest.rate, latestClose: conversion.latest.date,
+          basis: "daily FX close on or before each date: a week's bar date for the band, the publication date for each table row, the latest completed close for the current P/E" } : null,
         sampleStart: model.sample?.start.toISOString().slice(0, 10) ?? null, sampleWeeks: model.sample?.weeks ?? 0, multiples: model.multiples, undatedEpsPeriods: model.undated, unavailableTtmSums: model.unavailable,
         stale: inputs.stale, fetchedAt: inputs.fetchedAt, methodology: "docs/research-data.md#pe-band" },
     };

package/src/plugins/builtin/pe-band/model.ts

@@ -1,8 +1,12 @@
+import { fxLegForCurrency } from "../../../market-data/coordinator/fx-legs";
+import { fxCloseOnOrBefore, type FxCloses } from "../../../market-data/fx-closes";
 import { extractFundamentalSeries } from "../../../time-series/fundamentals";
 import type { SecuritySeriesSource, TimeSeriesPoint } from "../../../time-series/types";
 import { createValuationCurrencyContext } from "../../../time-series/valuation-currency";
 import type { FinancialStatement, PricePoint, TickerFinancials } from "../../../types/financials";
+import { resolveCurrencyUnit } from "../../../utils/currency-units";
 import { areNearbyFinancialPeriodEnds } from "../../../utils/financial-statements";
+import { datedByReport, type ReportDate } from "./report-dates";
 
 const DAY_MS = 86_400_000;
 const YEAR_MS = 365.25 * DAY_MS;
@@ -23,7 +27,7 @@ export interface EpsStep {
   /** Four reported quarters summed, or a reported fiscal year. */
   basis: "ttm" | "annual";
   knownAt: Date;
-  /** False when no publication date is on record and `knownAt` is the period end. */
+  /** False when no publication date or report is on record and `knownAt` is the period end. */
   dated: boolean;
   /** Statement currency units; null when unavailable (a declared gap or an incomplete run of quarters). */
   eps: number | null;
@@ -42,8 +46,24 @@ export interface PeBandRow extends EpsStep {
   /** The close of the week the figure became known, in price units. */
   price: number | null;
   pe: number | null;
-  /** Change from the figure a year earlier, when both are positive. */
+  /** Change from the figure a year earlier in the same currency, when both are positive. */
   yoy: number | null;
+  /** The daily FX close the figure was converted at, when it is in another currency than the price. */
+  fx: FxClose | null;
+}
+
+/** One completed daily FX close: USD per unit of the statement currency. */
+interface FxClose {
+  date: string;
+  rate: number;
+}
+
+/** EPS reported in another currency than a dollar price, converted at daily FX closes. */
+interface EpsConversion {
+  /** The statement currency of today's EPS. */
+  currency: string;
+  /** The latest completed close, which converts today's EPS. */
+  latest: FxClose;
 }
 
 export interface PeBandModel {
@@ -64,10 +84,12 @@ export interface PeBandModel {
    * the line just above today's P/E when that is higher.
    */
   bandCeiling: number | null;
-  /** Figures in the window dated by period end because no publication date is on record. */
+  /** Figures in the window dated by period end because neither a publication date nor a report is on record. */
   undated: number;
   /** Trailing sums in the window that are unavailable (a quarter's EPS is withheld or not reported). */
   unavailable: number;
+  /** Set when today's EPS is in another currency than the dollar price. */
+  conversion: EpsConversion | null;
   /** Blocks the pane: nothing can be priced. */
   error: string | null;
   /** The pane still draws, but without bands. */
@@ -98,10 +120,13 @@ function epsSeries(financials: TickerFinancials, period: "ttm" | "annual"): Time
  * by the shared statement series, which keeps declared gaps and broken runs
  * of quarters unavailable. A reported fiscal year is itself a trailing
  * twelve-month figure; at a fiscal year end it replaces the quarterly sum.
+ * A figure with no publication date of its own is dated by the company's
+ * report of that quarter, when `reports` has it.
  */
-export function trailingEpsSteps(financials: TickerFinancials): EpsStep[] {
-  const adjusted = { ...financials, quarterlyStatements: financials.quarterlyStatements.map(knownWhenFiled),
-    annualStatements: financials.annualStatements.map(knownWhenFiled) };
+export function trailingEpsSteps(financials: TickerFinancials, reports: readonly ReportDate[] = []): EpsStep[] {
+  const known = (row: FinancialStatement) => datedByReport(knownWhenFiled(row), reports);
+  const adjusted = { ...financials, quarterlyStatements: financials.quarterlyStatements.map(known),
+    annualStatements: financials.annualStatements.map(known) };
   const toStep = (basis: EpsStep["basis"]) => (point: TimeSeriesPoint): EpsStep => ({
     periodEnd: point.observedAt.toISOString().slice(0, 10), basis, knownAt: point.date, dated: point.availableAt !== undefined,
     eps: point.value != null && Number.isFinite(point.value) ? point.value : null, currency: point.provenance?.currency ?? null,
@@ -127,6 +152,37 @@ export function perShareDigits(value: number): number {
 
 export const formatPerShare = (value: number) => value.toFixed(perShareDigits(value));
 
+/**
+ * A rate in the pair's market convention: "USD/TWD 31.99" (Taiwan dollars per
+ * dollar) or "EUR/USD 1.17" (dollars per euro), from USD per unit.
+ */
+export function fxPairQuote(currency: string, usdPerUnit: number): { pair: string; value: number } {
+  const perDollar = fxLegForCurrency(currency)?.invert ?? true;
+  return perDollar ? { pair: `USD/${currency}`, value: 1 / usdPerUnit } : { pair: `${currency}/USD`, value: usdPerUnit };
+}
+
+/** The statement unit of an EPS currency when it is a whole currency other than USD with a daily pair, else null. */
+function fxCurrency(code: string | null | undefined): string | null {
+  const unit = resolveCurrencyUnit(code);
+  return unit.divisor === 1 && unit.currency !== "USD" && fxLegForCurrency(unit.currency) ? unit.currency : null;
+}
+
+const isDollarPrice = (currency: string | null | undefined) => {
+  const unit = resolveCurrencyUnit(currency);
+  return unit.currency === "USD" && unit.divisor === 1;
+};
+
+/**
+ * The currencies whose daily FX closes a dollar-priced listing needs: those
+ * its EPS is reported in, other than USD. Rows without a declared currency
+ * are never converted.
+ */
+export function epsFxCurrencies(financials: TickerFinancials): string[] {
+  if (!isDollarPrice(financials.quote?.currency)) return [];
+  const rows = [...financials.annualStatements, ...financials.quarterlyStatements].filter((row) => typeof row.eps === "number");
+  return [...new Set(rows.flatMap((row) => fxCurrency(row.currency?.trim()) ?? []))];
+}
+
 function quantile(sorted: readonly number[], q: number): number {
   const position = (sorted.length - 1) * q;
   const low = Math.floor(position), high = Math.ceil(position);
@@ -193,30 +249,47 @@ export function stepAt(steps: readonly EpsStep[], time: number): EpsStep | null
 export function projectPeBand(
   financials: TickerFinancials | null,
   history: readonly PricePoint[],
-  options: { symbol: string; lookbackYears: number; now?: number },
+  options: {
+    symbol: string; lookbackYears: number; now?: number; reports?: readonly ReportDate[];
+    /** Daily FX closes by statement currency, for a dollar price against EPS in another currency. */
+    fx?: ReadonlyMap<string, FxCloses>;
+    /** Why a needed FX history is missing, said when it leaves today's EPS unconverted. */
+    fxError?: string | null;
+  },
 ): PeBandModel {
   const currency = financials?.quote?.currency ?? null;
   const empty: PeBandModel = { symbol: options.symbol, currency, weeks: [], rows: [], multiples: [], current: null, range: null, sample: null, bandCeiling: null,
-    undated: 0, unavailable: 0, error: null, notice: null };
+    undated: 0, unavailable: 0, conversion: null, error: null, notice: null };
   if (!financials) return { ...empty, error: "Fundamentals unavailable." };
-  const allSteps = trailingEpsSteps(financials);
+  const allSteps = trailingEpsSteps(financials, options.reports);
   const latest = allSteps.findLast((step) => step.eps != null);
   if (!latest) return { ...empty, error: "No trailing EPS on record." };
   const units = createValuationCurrencyContext(financials);
   // Price units per statement unit: 1 for the same currency, 100 for a pence price against pound statements.
-  const scale = (step: EpsStep) => {
+  const unitScale = (step: EpsStep) => {
     const factor = units.priceInStatementUnits({ date: step.periodEnd, currency: step.currency ?? undefined }, 1);
     return factor ? 1 / factor : null;
   };
-  // ADRs and cross-listings report in one currency and trade in another; no FX rate is applied.
-  if (scale(latest) == null) {
-    return { ...empty, error: currency && latest.currency
-      ? `EPS is reported in ${latest.currency} and the price is in ${currency}.` : "The price or EPS currency is unknown." };
+  // ADRs report in one currency and trade in dollars: their EPS converts at a daily FX close.
+  const fxFor = (step: EpsStep) => {
+    const code = isDollarPrice(currency) ? fxCurrency(step.currency) : null;
+    return code ? options.fx?.get(code) ?? null : null;
+  };
+  if (unitScale(latest) == null && !fxFor(latest)) {
+    const fxCode = isDollarPrice(currency) ? fxCurrency(latest.currency) : null;
+    return { ...empty, error: !currency || !latest.currency ? "The price or EPS currency is unknown."
+      : `EPS is reported in ${latest.currency} and the price is in ${currency}${fxCode && options.fxError ? `; ${options.fxError}` : ""}.` };
   }
-  const priced = (step: EpsStep | null) => {
-    const factor = step?.eps != null ? scale(step) : null;
-    return factor == null ? null : step!.eps! * factor;
+  /** The EPS in price units on `date` (YYYY-MM-DD), with the FX close used when it was converted. */
+  const priced = (step: EpsStep | null, date: string): { eps: number; fx: FxClose | null } | null => {
+    if (step?.eps == null) return null;
+    const factor = unitScale(step);
+    if (factor != null) return { eps: step.eps * factor, fx: null };
+    const history = fxFor(step);
+    const close = history ? fxCloseOnOrBefore(history, date) : null;
+    return close ? { eps: step.eps * close.rate, fx: close } : null;
   };
+  const day = (time: Date | number) => new Date(time).toISOString().slice(0, 10);
 
   const now = options.now ?? Date.now();
   const firstKnown = allSteps.find((step) => step.eps != null)!.knownAt.getTime();
@@ -226,7 +299,9 @@ export function projectPeBand(
     .filter((point) => Number.isFinite(point.date.getTime()) && Number.isFinite(point.close) && point.close > 0)
     .sort((a, b) => a.date.getTime() - b.date.getTime());
   const weeks = sorted.filter((point) => point.date.getTime() >= start).map((point): PeBandWeek => {
-    const eps = priced(stepAt(allSteps, point.date.getTime()));
+    // Converted at the FX close of the bar's date, the same date that picks the EPS in force, so each week's multiple
+    // moves with the price and the currency together rather than with the rate of an old publication date.
+    const eps = priced(stepAt(allSteps, point.date.getTime()), day(point.date))?.eps ?? null;
     const positive = eps != null && eps > 0 ? eps : null;
     return { date: point.date, close: point.close, eps: positive, pe: positive ? point.close / positive : null };
   });
@@ -235,10 +310,12 @@ export function projectPeBand(
   const rows = steps.filter((step) => step.eps != null).map((step): PeBandRow => {
     const time = step.knownAt.getTime();
     const price = sorted.findLast((point) => point.date.getTime() <= time)?.close ?? null;
-    const eps = priced(step);
-    const prior = allSteps.find((other) => other.eps != null
+    // Converted at the FX close of the day it became known.
+    const converted = priced(step, day(step.knownAt));
+    const eps = converted?.eps ?? null;
+    const prior = allSteps.find((other) => other.eps != null && other.currency === step.currency
       && Math.abs(Date.parse(step.periodEnd) - Date.parse(other.periodEnd) - 365 * DAY_MS) <= 20 * DAY_MS);
-    return { ...step, price, pe: price != null && eps != null && eps > 0 ? price / eps : null,
+    return { ...step, price, pe: price != null && eps != null && eps > 0 ? price / eps : null, fx: converted?.fx ?? null,
       yoy: step.eps != null && prior?.eps != null && step.eps > 0 && prior.eps > 0 ? step.eps / prior.eps - 1 : null };
   }).reverse();
 
@@ -248,13 +325,16 @@ export function projectPeBand(
   const quotePrice = financials.quote?.price;
   const price = quotePrice != null && Number.isFinite(quotePrice) && quotePrice > 0 ? quotePrice : sorted.at(-1)?.close ?? null;
   const currentStep = stepAt(allSteps, now);
-  const currentEps = priced(currentStep);
+  // Today's EPS at the latest completed FX close.
+  const currentEps = priced(currentStep, day(now))?.eps ?? null;
+  const latestFx = unitScale(latest) == null ? fxFor(latest) : null;
   const currentPe = price != null && currentEps != null && currentEps > 0 ? price / currentEps : null;
   const multiples = chooseMultiples(pes, currentPe);
   const above = currentPe == null ? undefined : multiples.find((multiple) => multiple >= currentPe);
   const highestClose = weeks.reduce((max, week) => Math.max(max, week.close), 0);
   return {
     ...empty, weeks, rows, multiples,
+    conversion: latestFx ? { currency: latestFx.currency, latest: fxCloseOnOrBefore(latestFx, day(now))! } : null,
     sample: ranked.length ? { start: ranked[0]!.date, weeks: ranked.length } : null,
     bandCeiling: highestClose > 0 ? Math.max(highestClose * 1.5, above != null && currentEps != null ? above * currentEps : 0) : null,
     current: price == null ? null : { price, eps: currentEps, pe: currentPe, step: currentStep,

package/src/plugins/builtin/pe-band/pane.tsx

@@ -14,7 +14,7 @@ import { Box } from "../../../ui";
 import { formatCurrency, formatPercentileRank } from "../../../utils/format";
 import { useAssetData } from "../../runtime";
 import { loadPeBandInputs } from "./client";
-import { formatPerShare, perShareDigits, projectPeBand, type PeBandModel, type PeBandRow } from "./model";
+import { formatPerShare, fxPairQuote, perShareDigits, projectPeBand, type PeBandModel, type PeBandRow } from "./model";
 
 export const LOOKBACK_OPTIONS = [{ value: "5", label: "5Y" }, { value: "10", label: "10Y" }, { value: "0", label: "Max" }];
 
@@ -28,14 +28,18 @@ const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "
 const periodLabel = (row: Pick<PeBandRow, "basis" | "periodEnd">) =>
   `${row.basis === "annual" ? "FY" : "TTM"} ${MONTHS[Number(row.periodEnd.slice(5, 7)) - 1]} ${row.periodEnd.slice(0, 4)}`;
 
-const COLUMNS: DataTableColumn[] = [
-  { id: "period", label: "Period", width: 13, align: "left" },
-  { id: "known", label: "Known", width: 11, align: "left" },
-  { id: "eps", label: "EPS", width: 9, align: "right" },
-  { id: "yoy", label: "YoY", width: 8, align: "right" },
-  { id: "price", label: "Price", width: 10, align: "right" },
-  { id: "pe", label: "P/E", width: 7, align: "right" },
-];
+/** With EPS converted from another currency, the table keeps the reported figure and adds the FX close it was converted at. */
+function tableColumns(conversion: PeBandModel["conversion"]): DataTableColumn[] {
+  return [
+    { id: "period", label: "Period", width: 13, align: "left" },
+    { id: "known", label: "Known", width: 11, align: "left" },
+    { id: "eps", label: conversion ? `EPS ${conversion.currency}` : "EPS", width: 9, align: "right" },
+    ...(conversion ? [{ id: "fx", label: fxPairQuote(conversion.currency, conversion.latest.rate).pair, width: 9, align: "right" as const }] : []),
+    { id: "yoy", label: "YoY", width: 8, align: "right" },
+    { id: "price", label: "Price", width: 10, align: "right" },
+    { id: "pe", label: "P/E", width: 7, align: "right" },
+  ];
+}
 
 const rowKey = (row: PeBandRow) => `${row.basis}:${row.periodEnd}`;
 
@@ -49,6 +53,10 @@ function renderCell(row: PeBandRow, column: DataTableColumn, colors: ReturnType<
       color: row.eps != null && row.eps <= 0 ? colors.negative : undefined };
     case "yoy": return { text: pct(row.yoy), value: row.yoy == null ? null : row.yoy * 100,
       color: row.yoy == null || Math.abs(row.yoy) < 0.0005 ? undefined : row.yoy > 0 ? colors.positive : colors.negative };
+    case "fx": {
+      const quote = row.fx && row.currency ? fxPairQuote(row.currency, row.fx.rate).value : null;
+      return { text: quote == null ? "--" : quote.toPrecision(5), value: quote };
+    }
     case "price": return { text: row.price == null ? "--" : formatPerShare(row.price), value: row.price };
     default: return { text: multiple(row.pe), value: row.pe };
   }
@@ -94,9 +102,12 @@ export function PeBandPane({ width, height, focused }: PaneProps) {
 
   const lookbackYears = Number(lookback);
   const model = useMemo(() => inputs.data
-    ? projectPeBand(inputs.data.financials, inputs.data.history, { symbol: symbol ?? "", lookbackYears: Number.isFinite(lookbackYears) ? lookbackYears : 10 })
+    ? projectPeBand(inputs.data.financials, inputs.data.history, { symbol: symbol ?? "", lookbackYears: Number.isFinite(lookbackYears) ? lookbackYears : 10,
+      reports: inputs.data.reports, fx: inputs.data.fx, fxError: inputs.data.fxError })
     : null, [inputs.data, lookbackYears, symbol]);
   const rows = model?.rows ?? [];
+  const conversion = model?.conversion ?? null;
+  const columns = useMemo(() => tableColumns(conversion), [conversion?.currency, conversion?.latest.rate]);
   const series = useMemo(() => model && !model.error ? chartSeries(model, colors) : [], [model, colors]);
   const currency = model?.currency ?? undefined;
   const firstWeek = model?.weeks[0]?.date;
@@ -116,7 +127,8 @@ export function PeBandPane({ width, height, focused }: PaneProps) {
   const unavailableNotice = model?.unavailable
     ? `${model.unavailable} trailing EPS sum${model.unavailable === 1 ? " is" : "s are"} unavailable because a quarter's EPS is not reported; the previous figure stays in force.` : null;
   usePaneNoticeFooter({ registrationId: "pe-band-notices", focused, notices: [...new Set([identityError, inputs.error, inputs.data?.historyError,
-    model?.notice, unavailableNotice, undatedNotice].filter((value): value is string => !!value))] });
+    model?.notice, model && !model.error && inputs.data?.fxError ? `EPS in another currency is not converted: ${inputs.data.fxError}.` : null,
+    unavailableNotice, undatedNotice].filter((value): value is string => !!value))] });
   usePaneFooter("pe-band", () => ({ info: [
     ...(inputs.loading ? [{ id: "loading", parts: [{ text: "loading statements", tone: "muted" as const }] }] : []),
     ...(inputs.data?.stale ? [{ id: "stale", parts: [{ text: "stale", tone: "warning" as const }] }] : []),
@@ -127,15 +139,19 @@ export function PeBandPane({ width, height, focused }: PaneProps) {
     if (!model?.current || model.error) return [];
     const { current, range } = model;
     const step = current.step;
+    // Converted EPS says what it was converted from, and at which close.
+    const pair = conversion ? fxPairQuote(conversion.currency, conversion.latest.rate) : null;
+    const converted = step?.eps != null && conversion && pair && step.currency === conversion.currency
+      ? `, from ${conversion.currency} ${formatPerShare(step.eps)} at ${pair.pair} ${pair.value.toPrecision(5)}` : "";
     return [
       { id: "pe", label: "P/E", value: multiple(current.pe),
         detail: current.pe != null ? formatPercentileRank(current.percentile, windowLabel) : current.eps != null ? "EPS not positive" : "EPS unavailable" },
       { id: "median", label: "Median P/E", value: multiple(range?.median), detail: range ? `${multiple(range.min)} to ${multiple(range.max)}` : undefined },
       { id: "eps", label: "EPS", value: current.eps == null ? "--" : formatCurrency(current.eps, currency, perShareDigits(current.eps)),
-        detail: step ? periodLabel(step) : undefined },
+        detail: step ? `${periodLabel(step)}${converted}` : undefined },
       { id: "price", label: "Price", value: formatCurrency(current.price, currency, perShareDigits(current.price)) },
     ];
-  }, [model, windowLabel, currency]);
+  }, [model, windowLabel, currency, conversion]);
 
   const formatPrice = useCallback((value: number) => formatCurrency(value, currency, perShareDigits(value)), [currency]);
   const formatAxis = useMemo(() => spanAxisFormatter((value, digits) => formatCurrency(value, currency, Math.max(2, digits))), [currency]);
@@ -144,14 +160,16 @@ export function PeBandPane({ width, height, focused }: PaneProps) {
   if (!symbol) return <EmptyState title="Choose a ticker." />;
   return <Box width={width} height={height} flexDirection="column" overflow="hidden">
     <PaneStatusBody subject="P/E band" loading={inputs.loading && !model} error={!model ? inputs.error ?? identityError ?? null : model.error} empty={false}>
-      {model && !model.error ? <DataTableView<PeBandRow> focused={focused} columns={COLUMNS} items={rows} rootWidth={width} rootHeight={height}
+      {model && !model.error ? <DataTableView<PeBandRow> focused={focused} columns={columns} items={rows} rootWidth={width} rootHeight={height}
         getItemKey={rowKey} emptyStateTitle="No trailing EPS in this window." sortColumnId={null} sortDirection="desc" resetScrollKey={symbol}
         selection={{ kind: "id", selectedId: selected, getId: rowKey, onChange: (id) => setSelectedId(id) }}
         selectedTextOverridesCellColor
         getExportMetadata={() => [["symbol", model.symbol], ["currency", model.currency ?? ""],
-          ["units", "EPS and price in the listing currency; P/E at the close of the week the EPS became known"]]}
+          ["units", conversion
+            ? `EPS as reported in ${conversion.currency}; FX close of the day it became known; price in ${model.currency ?? ""}; P/E at that close and that week's close`
+            : "EPS and price in the listing currency; P/E at the close of the week the EPS became known"]]}
         renderCell={(row, column) => renderCell(row, column, colors)}
-        rootBefore={<ChartTableHeader width={width} height={height} tableRows={rows.length} tableColumns={COLUMNS} query={query} figures={figures}
+        rootBefore={<ChartTableHeader width={width} height={height} tableRows={rows.length} tableColumns={columns} query={query} figures={figures}
           chart={model.weeks.length >= 2 ? { series, formatValue: formatPrice, formatAxisValue: formatAxis, remoteKind: "pe-band", ...link } : null} />} />
         : null}
     </PaneStatusBody>

package/src/plugins/builtin/pe-band/report-dates.ts

@@ -0,0 +1,78 @@
+import type { EarningsHistoryPayload } from "../../../api-client/earnings";
+import type { FinancialStatement } from "../../../types/financials";
+import { statementFieldAvailability } from "../../../utils/financial-statements";
+import { newYorkToday } from "../earnings/board-model";
+
+const DAY_MS = 86_400_000;
+/** A 52/53-week fiscal quarter ends within days of its month end, never a month away. */
+const MONTH_END_TOLERANCE_MS = 10 * DAY_MS;
+/** A company reports after its period ends; later than this the report is another quarter's. */
+const MAX_REPORT_LAG_MS = 180 * DAY_MS;
+
+/** One reported quarter, reduced to what dates its EPS. */
+export interface ReportDate {
+  /** New York report date, YYYY-MM-DD. */
+  date: string;
+  /** Fiscal quarter end month, YYYY-MM. */
+  fiscalPeriod: string;
+  /** Filing time, when on record. */
+  reportedAt: string | null;
+}
+
+/**
+ * The reports that happened, with the quarter they cover. An upcoming report,
+ * one whose date is only expected, and one with no fiscal quarter date nothing.
+ */
+export function reportDatesFrom(payload: EarningsHistoryPayload): ReportDate[] {
+  const asOf = Date.parse(payload.asOf);
+  if (!Number.isFinite(asOf)) return [];
+  const today = newYorkToday(new Date(asOf));
+  return payload.reports.flatMap((report) => (
+    report.fiscalPeriod && /^\d{4}-(0[1-9]|1[0-2])$/.test(report.fiscalPeriod) && report.date <= today
+      && (report.epsActual != null || report.reportedAt != null)
+      ? [{ date: report.date, fiscalPeriod: report.fiscalPeriod, reportedAt: report.reportedAt }] : []
+  ));
+}
+
+function coversPeriod(periodEnd: number, fiscalPeriod: string): boolean {
+  if (new Date(periodEnd).toISOString().slice(0, 7) === fiscalPeriod) return true;
+  const monthEnd = Date.UTC(Number(fiscalPeriod.slice(0, 4)), Number(fiscalPeriod.slice(5, 7)), 0);
+  return Math.abs(periodEnd - monthEnd) <= MONTH_END_TOLERANCE_MS;
+}
+
+/** The filing time when it falls on the report date in both New York and UTC, else the date. */
+function publishedAt(report: ReportDate): string {
+  const filed = report.reportedAt ? new Date(report.reportedAt) : null;
+  return filed && Number.isFinite(filed.getTime()) && filed.toISOString().slice(0, 10) === report.date
+    && newYorkToday(filed) === report.date ? report.reportedAt! : report.date;
+}
+
+/**
+ * When the quarter ended on `periodEnd` was reported. It is the one report
+ * whose fiscal quarter month is the period's own month or sits within days of
+ * it, and which comes after the period. No report, or two on different dates,
+ * leaves the period undated rather than guessed.
+ */
+function reportedWhen(periodEnd: string, reports: readonly ReportDate[]): string | null {
+  const end = Date.parse(`${periodEnd}T00:00:00Z`);
+  if (!Number.isFinite(end)) return null;
+  const matches = reports.filter((report) => {
+    const lag = Date.parse(`${report.date}T00:00:00Z`) - end;
+    return lag > 0 && lag <= MAX_REPORT_LAG_MS && coversPeriod(end, report.fiscalPeriod);
+  });
+  if (new Set(matches.map((report) => report.date)).size !== 1) return null;
+  return publishedAt(matches.find((report) => report.reportedAt) ?? matches[0]!);
+}
+
+/**
+ * The statement with its EPS dated by the company's report, only when it has no
+ * publication date of its own: a date on record always wins. A fiscal year is
+ * dated by the report of its last quarter, which shares its period end. A
+ * trailing sum takes the latest of its four quarters from the shared series,
+ * so it cannot be known before all four are.
+ */
+export function datedByReport(row: FinancialStatement, reports: readonly ReportDate[]): FinancialStatement {
+  if (!reports.length || typeof row.eps !== "number" || !Number.isFinite(row.eps) || statementFieldAvailability(row, "eps") !== undefined) return row;
+  const known = reportedWhen(row.date, reports);
+  return known ? { ...row, fieldAvailability: { ...row.fieldAvailability, eps: known } } : row;
+}

package/src/plugins/builtin/perps/client.ts

@@ -1,5 +1,6 @@
 import { apiClient } from "../../../api-client";
-import type { PerpBoardPayload, PerpBoardRow, PerpHistoryPayload, PerpHistoryQuery, PerpMarketPayload } from "../../../api-client/perps";
+import type { PerpBoardPayload, PerpBoardQuery, PerpBoardRow, PerpEquityListing, PerpHistoryPayload, PerpHistoryQuery, PerpLongShortPoint, PerpLongShortRatio, PerpMarketPayload,
+  PerpRankingsPayload } from "../../../api-client/perps";
 import { createPluginCache } from "../../../data/plugin-cache";
 import { cachedCloudResource, loadCloudResource } from "../shared/cloud-resource";
 
@@ -9,6 +10,12 @@ export const perpsHistoryCache = createPluginCache<PerpHistoryPayload>({ kind: "
   policy: { staleMs: 60_000, expireMs: 86_400_000 } });
 const finiteOrNull = (n: unknown) => n === null || typeof n === "number" && Number.isFinite(n);
 const date = (s: unknown) => typeof s === "string" && Number.isFinite(Date.parse(s));
+const share = (n: unknown) => typeof n === "number" && n >= 0 && n <= 1;
+/** A long/short reading: shares within 0..1, a finite ratio or none. Older servers send no reading at all. */
+const validShares = (value: Pick<PerpLongShortPoint, "longShare" | "shortShare" | "ratio" | "derived" | "definition" | "observedAt">) =>
+  share(value.longShare) && share(value.shortShare) && finiteOrNull(value.ratio) && typeof value.derived === "boolean" && typeof value.definition === "string" && date(value.observedAt);
+const validLongShort = (value: PerpLongShortRatio | null | undefined) => value == null
+  || typeof value === "object" && validShares(value) && typeof value.venue === "string" && typeof value.definitionText === "string" && date(value.bucketAt) && typeof value.stale === "boolean";
 function validRow(row: PerpBoardRow) {
   return !!row && typeof row.marketId === "string" && typeof row.symbol === "string" && typeof row.displayName === "string"
     && typeof row.baseAsset === "string" && typeof row.quoteCurrency === "string" && typeof row.marginCurrency === "string"
@@ -16,7 +23,8 @@ function validRow(row: PerpBoardRow) {
     && [row.markPrice, row.oraclePrice, row.fundingRate, row.fundingIntervalHours, row.fundingRate8h, row.fundingApr,
       row.predictedFundingRate, row.predictedFundingIntervalHours, row.openInterestBase, row.openInterestUsd, row.volume24hUsd,
       row.premium, row.oiChange24h, row.closedMarketPremium].every(finiteOrNull)
-    && (row.fundingIntervalHours === null || row.fundingIntervalHours > 0);
+    && (row.fundingIntervalHours === null || row.fundingIntervalHours > 0)
+    && validLongShort(row.longShortRatio) && (row.longShortRatioReason == null || typeof row.longShortRatioReason === "string");
 }
 function envelope(data: { access: string; locked: number | boolean; asOf: string | null }) {
   return !!data && ["pro", "preview"].includes(data.access) && (typeof data.locked === "boolean" || Number.isInteger(data.locked) && data.locked >= 0) && (data.asOf === null || date(data.asOf));
@@ -30,12 +38,65 @@ export function validatePerpsHistory(data: PerpHistoryPayload, expectedMarketId?
   if (!envelope(data) || typeof data.marketId !== "string" || expectedMarketId !== undefined && data.marketId !== expectedMarketId || !Array.isArray(data.rows) || !Array.isArray(data.funding) || !Array.isArray(data.candles)
     || !data.rows.every((row) => date(row.time) && [row.markPrice, row.oraclePrice, row.premium, row.fundingRate, row.fundingIntervalHours, row.openInterestBase, row.openInterestUsd].every(finiteOrNull) && (row.fundingIntervalHours === null || row.fundingIntervalHours > 0))
     || !data.funding.every((row) => date(row.time) && typeof row.rate === "number" && Number.isFinite(row.rate) && Number.isFinite(row.intervalHours) && row.intervalHours > 0 && row.marketId === data.marketId && date(row.observedAt) && typeof row.sourceUrl === "string")
-    || !data.candles.every((row) => date(row.time) && [row.open, row.high, row.low, row.close].every((n) => typeof n === "number" && Number.isFinite(n)) && row.marketId === data.marketId && date(row.observedAt) && typeof row.sourceUrl === "string")) throw new Error("The server returned unreadable perpetual history");
+    || !data.candles.every((row) => date(row.time) && [row.open, row.high, row.low, row.close].every((n) => typeof n === "number" && Number.isFinite(n)) && row.marketId === data.marketId && date(row.observedAt) && typeof row.sourceUrl === "string")
+    || data.longShortRatio != null && !(Array.isArray(data.longShortRatio) && data.longShortRatio.every((point) => !!point && date(point.time) && validShares(point)))) throw new Error("The server returned unreadable perpetual history");
   return data;
 }
 export const fetchPerpsHistory = async (query: PerpHistoryQuery, client: Pick<typeof apiClient, "getCloudPerpsHistory"> = apiClient) => validatePerpsHistory(await client.getCloudPerpsHistory(query), query.marketId);
-const fetchPerpsEquity = async (symbol: string, client: Pick<typeof apiClient, "getCloudPerpsEquity"> = apiClient) => validatePerpsBoard(await client.getCloudPerpsEquity(symbol));
-export const loadPerpsEquity = (symbol: string, access: string, force = false) => loadCloudResource(perpsCache, `equity:${symbol}:${access}`, () => fetchPerpsEquity(symbol), { force, validate: validatePerpsBoard });
+
+const RANKING_KEYS = ["fundingPositive", "fundingNegative", "oiSurges", "premiumDislocations", "closedMarketDislocations"] as const;
+export function validatePerpsRankings(data: PerpRankingsPayload): PerpRankingsPayload {
+  // A market can rank in several lists, but only once in each.
+  if (!envelope(data) || !RANKING_KEYS.every((key) => Array.isArray(data[key]) && data[key].every(validRow)
+    && new Set(data[key].map((row) => row.marketId)).size === data[key].length)) throw new Error("The server returned unreadable perpetual rankings");
+  return data;
+}
+/**
+ * The server ranks by its own figures and has no long-share order. A full board (Pro) and the fixed preview
+ * both arrive whole, so ordering them here is the order the server would give: highest first, none last.
+ */
+const LONG_SHORT_SORT = "long-short";
+const byLongShare = (rows: readonly PerpBoardRow[]) => [...rows].sort((a, b) =>
+  (b.longShortRatio?.longShare ?? -Infinity) - (a.longShortRatio?.longShare ?? -Infinity) || a.marketId.localeCompare(b.marketId));
+export async function fetchPerpsBoard(query: PerpBoardQuery, client: Pick<typeof apiClient, "getCloudPerpsBoard"> = apiClient) {
+  if (query.sort !== LONG_SHORT_SORT) return validatePerpsBoard(await client.getCloudPerpsBoard(query));
+  const data = validatePerpsBoard(await client.getCloudPerpsBoard({ ...query, sort: "oi" }));
+  return { ...data, rows: byLongShare(data.rows) };
+}
+export const fetchPerpsRankings = async (client: Pick<typeof apiClient, "getCloudPerpsRankings"> = apiClient) => validatePerpsRankings(await client.getCloudPerpsRankings());
+function validatePerpsCompare(data: PerpBoardPayload, baseAsset: string): PerpBoardPayload {
+  validatePerpsBoard(data);
+  if (!data.rows.every((row) => row.baseAsset.toUpperCase() === baseAsset.toUpperCase())) throw new Error("The server returned contracts for another asset");
+  return data;
+}
+export const fetchPerpsCompare = async (baseAsset: string, client: Pick<typeof apiClient, "getCloudPerpsCompare"> = apiClient) => validatePerpsCompare(await client.getCloudPerpsCompare(baseAsset), baseAsset);
+export const perpsRankingsCache = createPluginCache<PerpRankingsPayload>({ kind: "perps-rankings", source: "gloom-cloud", schemaVersion: 1,
+  policy: { staleMs: 60_000, expireMs: 86_400_000 } });
+// Board and comparison payloads share the board cache, keyed by the query and the account's plan.
+const boardKey = (query: PerpBoardQuery, access: string) => `board:v1:${query.assetClass ?? "all"}:${query.sort ?? "oi"}:${query.search?.trim().toUpperCase() ?? ""}:${access}`;
+export const cachedPerpsBoard = (query: PerpBoardQuery, access: string) => cachedCloudResource(perpsCache, boardKey(query, access), validatePerpsBoard);
+export const loadPerpsBoard = (query: PerpBoardQuery, access: string, force = false) => loadCloudResource(perpsCache, boardKey(query, access), () => fetchPerpsBoard(query), { force, validate: validatePerpsBoard });
+export const cachedPerpsRankings = (access: string) => cachedCloudResource(perpsRankingsCache, `rankings:v1:${access}`, validatePerpsRankings);
+export const loadPerpsRankings = (access: string, force = false) => loadCloudResource(perpsRankingsCache, `rankings:v1:${access}`, () => fetchPerpsRankings(), { force, validate: validatePerpsRankings });
+const compareKey = (baseAsset: string, access: string) => `compare:v1:${baseAsset.toUpperCase()}:${access}`;
+export const cachedPerpsCompare = (baseAsset: string, access: string) => cachedCloudResource(perpsCache, compareKey(baseAsset, access), (data) => validatePerpsCompare(data, baseAsset));
+export const loadPerpsCompare = (baseAsset: string, access: string, force = false) => loadCloudResource(perpsCache, compareKey(baseAsset, access), () => fetchPerpsCompare(baseAsset), { force, validate: (data) => validatePerpsCompare(data, baseAsset) });
+function validatePerpsEquity(data: PerpBoardPayload, listing: PerpEquityListing): PerpBoardPayload {
+  validatePerpsBoard(data);
+  const same = (value: PerpEquityListing | null | undefined) => value?.symbol === listing.symbol && value.exchange === listing.exchange;
+  if (!same(data.listing) || !data.rows.every((row) => {
+    const match = row.equityMatch;
+    return same(match?.listing) && row.assetClass === "stocks" && !!match?.underlying.exchange
+      && match.underlying.symbol === row.underlyingSymbol
+      && (match.basis === "issuer" || match.basis === "listing" && same(match.underlying));
+  })) throw new Error("The server returned perpetuals for another listing");
+  return data;
+}
+export const loadPerpsEquity = (listing: PerpEquityListing, access: string, force = false) => {
+  const validate = (data: PerpBoardPayload) => validatePerpsEquity(data, listing);
+  return loadCloudResource(perpsCache, `equity:v2:${listing.symbol}:${listing.exchange}:${access}`,
+    async () => validate(await apiClient.getCloudPerpsEquity(listing.symbol, listing.exchange)), { force, validate });
+};
 
 function validatePerpsMarket(data: PerpMarketPayload): PerpMarketPayload {
   validatePerpsBoard(data);

package/src/plugins/builtin/perps/equity-identity.ts

@@ -0,0 +1,16 @@
+import type { PerpEquityListing } from "../../../api-client/perps";
+import { listingSuffixExchange } from "../../../sources/listing-symbols";
+import { canonicalExchange } from "../../../utils/exchanges";
+import { listingIdentity } from "../shared/ticker-request";
+
+/** A qualifier owns the listing. Conflicting metadata cannot authorize a comparison. */
+export function perpEquityIdentity(key: string, savedExchange = ""): PerpEquityListing | null {
+  const identity = listingIdentity(key, savedExchange);
+  if (!identity) return null;
+  const suffixExchange = listingSuffixExchange(identity.symbol);
+  const exchange = suffixExchange ?? canonicalExchange(identity.exchange);
+  if (!exchange || (identity.exchange && canonicalExchange(identity.exchange) !== exchange)
+    || (savedExchange && canonicalExchange(savedExchange) !== exchange)) return null;
+  const symbol = suffixExchange ? identity.symbol.slice(0, identity.symbol.lastIndexOf(".")) : identity.symbol;
+  return /^[A-Z0-9.-]{1,32}$/.test(symbol) ? { symbol, exchange } : null;
+}