gloomberb 0.16.1 → 0.16.2

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

@@ -1,5 +1,7 @@
 import { apiClient } from "../../../api-client";
 import { getSharedMarketDataCoordinator, MarketDataCoordinator, resolveEntryValue } from "../../../market-data/coordinator";
+import { fxLegForCurrency } from "../../../market-data/coordinator/fx-legs";
+import { dailyFxCloses, FxHistoryError, type FxCloses } from "../../../market-data/fx-closes";
 import type { InstrumentRef } from "../../../market-data/request-types";
 import type { ManualChartResolution } from "../../../time-series/resolution";
 import type { DataProvider } from "../../../types/data-provider";
@@ -8,6 +10,7 @@ import { abortable, abortError, settleWithin } from "../../../utils/async-deadli
 import { errorMessage } from "../../../utils/errors";
 import { isUsListingExchange } from "../../../utils/exchanges";
 import { fetchEarningsHistory } from "../earnings/client";
+import { epsFxCurrencies } from "./model";
 import { reportDatesFrom, type ReportDate } from "./report-dates";
 
 export interface PeBandInputs {
@@ -20,6 +23,10 @@ export interface PeBandInputs {
   historyError: string | null;
   /** Report dates for US listings; empty for the rest and when the earnings history is unavailable. */
   reports: ReportDate[];
+  /** Daily FX closes for each currency a dollar-priced listing reports its EPS in. */
+  fx: Map<string, FxCloses>;
+  /** Why a currency's FX closes are missing; its EPS then stays unconverted. */
+  fxError: string | null;
   fetchedAt: number;
 }
 
@@ -31,7 +38,40 @@ const REPORT_LIMIT = 40;
 /** Report dates only refine the figures' dates, so the pane does not wait longer than this for them. */
 const REPORT_DEADLINE_MS = 8_000;
 
-type ReportClient = Pick<typeof apiClient, "getCloudEarningsHistory">;
+/** Daily FX closes back this far before the oldest statement, so its weeks find a close. */
+const FX_LEAD_DAYS = 14;
+/** About thirty years of daily closes; a longer reply is not a daily FX history. */
+const FX_MAX_ROWS = 8_000;
+
+type ReportClient = Pick<typeof apiClient, "getCloudEarningsHistory" | "getCloudHistory">;
+
+/**
+ * Completed daily closes of each currency's dollar pair, from just before the
+ * oldest statement in that currency. Never rejects but on cancel: a missing
+ * or stale history is said in `error`, and that currency's EPS stays unconverted.
+ */
+async function loadFxCloses(financials: TickerFinancials, client: ReportClient, signal: AbortSignal | undefined, now: Date):
+  Promise<{ fx: Map<string, FxCloses>; error: string | null }> {
+  const fx = new Map<string, FxCloses>();
+  const errors: string[] = [];
+  const rows = [...financials.annualStatements, ...financials.quarterlyStatements];
+  await Promise.all(epsFxCurrencies(financials).map(async (currency) => {
+    const leg = fxLegForCurrency(currency)!;
+    const oldest = rows.filter((row) => row.currency?.trim().toUpperCase() === currency && Number.isFinite(Date.parse(row.date)))
+      .reduce((min, row) => Math.min(min, Date.parse(row.date)), now.getTime());
+    try {
+      const response = await client.getCloudHistory(leg.instrument.symbol, leg.instrument.exchange ?? "", {
+        interval: "1day", startDate: new Date(oldest - FX_LEAD_DAYS * 86_400_000).toISOString().slice(0, 10),
+        endDate: now.toISOString().slice(0, 10), outputsize: FX_MAX_ROWS,
+      }, signal ? { signal } : undefined);
+      fx.set(currency, dailyFxCloses(response, leg, now, FX_MAX_ROWS));
+    } catch (error) {
+      if (signal?.aborted) throw abortError(CANCELLED);
+      errors.push(`daily ${currency} FX closes are ${error instanceof FxHistoryError && error.problem === "stale" ? "stale" : "unavailable"}`);
+    }
+  }));
+  return { fx, error: errors.length ? errors.join("; ") : null };
+}
 
 /** Never rejects: a listing without reports, an outage or a refused session leaves the figures as they are. */
 function loadReportDates(symbol: string, client: ReportClient): Promise<ReportDate[]> {
@@ -73,12 +113,17 @@ export async function loadPeBandInputs(
   const entry = chart.status === "fulfilled" ? chart.value : null;
   const history = entry ? resolveEntryValue(entry) ?? [] : [];
   const quote = value?.quote;
-  const reports = await abortable(early ?? (isUsListingExchange(quote?.listingExchangeName ?? quote?.exchangeName ?? quote?.fullExchangeName)
-    ? loadReportDates(instrument.symbol, cloud) : Promise.resolve([])), request.signal, CANCELLED);
+  const [reports, fx] = await abortable(Promise.all([
+    early ?? (isUsListingExchange(quote?.listingExchangeName ?? quote?.exchangeName ?? quote?.fullExchangeName)
+      ? loadReportDates(instrument.symbol, cloud) : Promise.resolve([])),
+    value ? loadFxCloses(value, cloud, request.signal, new Date(now)) : Promise.resolve({ fx: new Map<string, FxCloses>(), error: null }),
+  ]), request.signal, CANCELLED);
   return {
     financials: value,
     history,
     reports,
+    fx: fx.fx,
+    fxError: fx.error,
     stale: !!value?.fundamentals?.stale || !!entry?.error || (entry?.staleAt != null && entry.staleAt <= now),
     error: financials.status === "rejected" ? errorMessage(financials.reason) : null,
     historyError: chart.status === "rejected" ? errorMessage(chart.reason)

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,8 +11,11 @@ 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" },
   ],
@@ -20,8 +24,16 @@ export const peBandHeadless: HeadlessPaneDefinition<"bundle"> = {
     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, reports: inputs.reports });
+    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,7 +1,10 @@
+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";
 
@@ -43,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 {
@@ -69,6 +88,8 @@ export interface PeBandModel {
   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. */
@@ -131,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);
@@ -197,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; reports?: readonly ReportDate[] },
+  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, 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();
@@ -230,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 };
   });
@@ -239,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();
 
@@ -252,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 };
   }
@@ -95,9 +103,11 @@ 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,
-      reports: inputs.data.reports })
+      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;
@@ -117,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 }] }] : []),
@@ -128,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]);
@@ -145,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/perps/client.ts

@@ -1,5 +1,6 @@
 import { apiClient } from "../../../api-client";
-import type { PerpBoardPayload, PerpBoardRow, PerpEquityListing, 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,10 +38,49 @@ 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 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;