@gloom-sh/terminal 0.18.5 → 0.19.0

package/src/time-series/filed-trailing-eps.ts

@@ -0,0 +1,197 @@
+import type { Fundamentals, FinancialStatement, TickerFinancials } from "../types/financials";
+import { resolveCurrencyUnit } from "../utils/currency-units";
+import { areNearbyFinancialPeriodEnds, statementFieldAvailability } from "../utils/financial-statements";
+import { extractFundamentalSeries, knownWhenFiled } from "./fundamentals";
+import type { SecuritySeriesSource, TimeSeriesPoint } from "./types";
+
+const DAY_MS = 86_400_000;
+/**
+ * A figure stops pricing this long after its period end. Sixteen months
+ * covers a fiscal year plus its filing, so a year of unavailable quarterly
+ * sums falls back on the last annual figure but never on one long overdue.
+ */
+export const STALE_TRAILING_EPS_MS = 487 * DAY_MS;
+/**
+ * The latest period's trailing figure reads statements this far back at most:
+ * its four quarters (some 270 days), and for a fiscal fourth quarter read from
+ * its year, the three quarters before it. Older rows change nothing.
+ */
+const LATEST_WINDOW_MS = 760 * DAY_MS;
+
+/** One trailing-twelve-month EPS figure and when it became known. */
+export interface EpsStep {
+  /** ISO period end. */
+  periodEnd: string;
+  /** Four reported quarters summed, or a reported fiscal year. */
+  basis: "ttm" | "annual";
+  knownAt: Date;
+  /** 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;
+  currency: string | null;
+}
+
+function epsSeries(financials: TickerFinancials, period: "ttm" | "annual"): TimeSeriesPoint[] {
+  const source: SecuritySeriesSource = { kind: "security", instrument: { symbol: "" }, fieldId: "fundamental.eps", period, timestampMode: "available-at" };
+  return extractFundamentalSeries(financials, source);
+}
+
+/**
+ * Trailing EPS through time, oldest first. Four reported quarters are summed
+ * by the shared statement series, which keeps declared gaps and broken runs
+ * of quarters unavailable and reads a fiscal fourth quarter with no EPS of its
+ * own from its year. A reported fiscal year is itself a trailing twelve-month
+ * figure; at a fiscal year end it replaces the quarterly sum. `known` dates
+ * each row's figures (PEB dates them by the company's reports as well).
+ */
+export function trailingEpsSteps(
+  financials: TickerFinancials,
+  known: (row: FinancialStatement) => FinancialStatement = knownWhenFiled,
+): EpsStep[] {
+  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,
+  });
+  const steps = epsSeries(adjusted, "annual").map(toStep("annual"));
+  for (const step of epsSeries(adjusted, "ttm").map(toStep("ttm"))) {
+    const index = steps.findIndex((other) => areNearbyFinancialPeriodEnds(other.periodEnd, step.periodEnd));
+    if (index < 0) steps.push(step);
+    else if (steps[index]!.eps == null && step.eps != null) steps[index] = step;
+  }
+  return steps.sort((a, b) => a.knownAt.getTime() - b.knownAt.getTime() || a.periodEnd.localeCompare(b.periodEnd));
+}
+
+/** The trailing EPS of the last period filed, with that period's end and the statements' currency. */
+interface FiledTrailingEps {
+  eps: number;
+  periodEnd: string;
+  currency: string;
+}
+
+/**
+ * How far the filed figure may sit from Gloom Cloud's, either way, before it
+ * is taken for another share basis (a receipt or a class the flags miss, as
+ * BRK.B's statements are per Class A share) rather than newer or restated
+ * quarters: PLTR's 1.17 against 1.13 stands, 4.00 against 0.40 does not.
+ */
+const SERVED_EPS_RATIO_LIMIT = 1.5;
+
+type TrailingEpsInputs = Pick<TickerFinancials, "quote" | "fundamentals" | "annualStatements" | "quarterlyStatements" | "financialCurrency">;
+
+const isReceipt = (financials: TrailingEpsInputs) => !!(
+  financials.quote?.isDepositaryReceipt || financials.fundamentals?.isDepositaryReceipt
+  || financials.fundamentals?.shareBasis === "depositary_receipt" || financials.quote?.adrRatio || financials.fundamentals?.adrRatio
+);
+
+/** `filed` is the day the latest EPS on record was filed (a restated one's restating filing), the period end when none is dated. */
+type LatestStep = { periodEnd: string; eps: number; currency: string; filed: string } | null;
+
+/**
+ * The last period's step by what it is read from: the router answers the same
+ * rows many times, in new arrays. Bounded; the oldest entry leaves first.
+ */
+const latestSteps = new Map<string, LatestStep>();
+const LATEST_STEPS_KEPT = 500;
+
+/** What the trailing EPS series reads of a row. */
+const rowKey = (row: FinancialStatement) => [
+  row.date, row.currency ?? "", row.eps ?? "", statementFieldAvailability(row, "eps") ?? "", row.availableAt ?? "", row.dateSource ?? "",
+  Object.keys(row.fieldAvailability ?? {}).length,
+  row.unavailableFields?.join("+") ?? "", row.unavailableEarnings?.join("+") ?? "", row.epsBasis?.status ?? "", row.shareBasis ?? "",
+].join("|");
+
+/** The trailing EPS step for the last period on record, null when that period gives none. */
+function latestStep(financials: TrailingEpsInputs): LatestStep {
+  const rows = [...financials.quarterlyStatements, ...financials.annualStatements];
+  const latest = rows.map((row) => row.date).filter((date) => Number.isFinite(Date.parse(date))).sort().at(-1);
+  if (!latest) return null;
+  const recent = (row: FinancialStatement) => Date.parse(latest) - Date.parse(row.date) <= LATEST_WINDOW_MS;
+  const quarterlyStatements = financials.quarterlyStatements.filter(recent);
+  const annualStatements = financials.annualStatements.filter(recent);
+  const key = [financials.financialCurrency ?? "", quarterlyStatements.map(rowKey).join(";"), annualStatements.map(rowKey).join(";")].join("#");
+  if (latestSteps.has(key)) return latestSteps.get(key)!;
+  const found = trailingEpsSteps({ financialCurrency: financials.financialCurrency, priceHistory: [], quarterlyStatements, annualStatements })
+    .find((candidate) => areNearbyFinancialPeriodEnds(candidate.periodEnd, latest));
+  const filed = [...quarterlyStatements, ...annualStatements]
+    .flatMap((row) => typeof row.eps === "number" ? [statementFieldAvailability(row, "eps")?.slice(0, 10)] : [])
+    .filter((date): date is string => !!date).sort().at(-1);
+  const step = found?.eps != null && found.currency
+    ? { periodEnd: found.periodEnd, eps: found.eps, currency: found.currency, filed: filed && filed > found.periodEnd ? filed : found.periodEnd }
+    : null;
+  if (latestSteps.size >= LATEST_STEPS_KEPT) latestSteps.delete(latestSteps.keys().next().value!);
+  latestSteps.set(key, step);
+  return step;
+}
+
+/**
+ * The headline trailing EPS, as PEB and GE read the statements: the diluted
+ * EPS of the last four filed quarters, or of the fiscal year when that is the
+ * last period filed. Null when that period gives none (a quarter missing or
+ * withheld, a split basis unresolved, two share bases), when it is overdue,
+ * when its currency is not the price's, for a depositary receipt, whose
+ * statements are per ordinary share, when a split went ex after the last of
+ * its figures was filed (they are on the old share count until a filing
+ * restates them), and when it is more than SERVED_EPS_RATIO_LIMIT times
+ * Gloom Cloud's figure either way.
+ */
+function filedTrailingEps(financials: TrailingEpsInputs, now = Date.now()): FiledTrailingEps | null {
+  const price = resolveCurrencyUnit(financials.quote?.currency);
+  if (!financials.quote || price.divisor !== 1 || !/^[A-Z]{3}$/.test(price.currency) || isReceipt(financials)) return null;
+  const step = latestStep(financials);
+  if (!step || now - Date.parse(step.periodEnd) > STALE_TRAILING_EPS_MS) return null;
+  const currency = resolveCurrencyUnit(step.currency);
+  if (currency.currency !== price.currency || currency.divisor !== 1) return null;
+  // The trailing block's amounts are in another currency: an EPS beside them in this one would be read as theirs.
+  const block = financials.fundamentals?.financialCurrency?.trim();
+  if (block && resolveCurrencyUnit(block).currency !== price.currency) return null;
+  const split = financials.fundamentals?.splitShareBasis?.exDate;
+  if (split && split > step.filed) return null;
+  const served = financials.fundamentals?.eps;
+  if (typeof served === "number" && Number.isFinite(served) && !withinServedRatio(step.eps, served)) return null;
+  return { eps: step.eps, periodEnd: step.periodEnd, currency: price.currency };
+}
+
+/** Same sign and within SERVED_EPS_RATIO_LIMIT of each other; a figure against a zero is not. */
+function withinServedRatio(filed: number, served: number): boolean {
+  const ratio = filed / served;
+  return Number.isFinite(ratio) && ratio > 0 && ratio <= SERVED_EPS_RATIO_LIMIT && ratio >= 1 / SERVED_EPS_RATIO_LIMIT;
+}
+
+const finite = (value: number | null | undefined): value is number => typeof value === "number" && Number.isFinite(value);
+const positive = (value: number | null | undefined): value is number => finite(value) && value > 0;
+
+/**
+ * The financials with their headline trailing EPS and P/E on the filed
+ * quarters (filedTrailingEps): `fundamentals.eps` is that figure and
+ * `trailingPE` the quote's price over it, so every view that moves the P/E to
+ * the regular session price (atRegularSessionPrice, liveTrailingPE) reads the
+ * multiple PEB and GE read. Without one, Gloom Cloud's trailing EPS and P/E
+ * stand, marked `served`, as does a P/E it serves with no EPS (a fund's). A
+ * block with neither is left as it is.
+ */
+export function withFiledTrailingEps<T extends TrailingEpsInputs>(financials: T, now = Date.now()): T {
+  const fundamentals = financials.fundamentals;
+  if (!fundamentals) return financials;
+  const filed = filedTrailingEps(financials, now);
+  if (!filed) {
+    const served = finite(fundamentals.eps) || finite(fundamentals.trailingPE);
+    if (!served || (fundamentals.trailingEpsSource === "served" && fundamentals.trailingEpsPeriodEnd === undefined)) return financials;
+    const { trailingEpsPeriodEnd: _period, ...rest } = fundamentals;
+    return { ...financials, fundamentals: { ...rest, trailingEpsSource: "served" } };
+  }
+  const { trailingPEConversion: _conversion, epsCurrency: _currency, trailingPE: _served, ...rest } = fundamentals;
+  // filedTrailingEps reads a quote's currency, so there is a quote; its price is the one atRegularSessionPrice moves from.
+  const price = financials.quote!.price;
+  const next: Fundamentals = {
+    ...rest,
+    eps: filed.eps,
+    // A loss leaves no multiple: priceEarningsOnEarnings reads the EPS as not meaningful.
+    ...(positive(price) && filed.eps > 0 ? { trailingPE: price / filed.eps } : {}),
+    trailingEpsSource: "filed-quarters",
+    trailingEpsPeriodEnd: filed.periodEnd,
+  };
+  return { ...financials, fundamentals: next };
+}

package/src/time-series/fundamentals.ts

@@ -502,6 +502,47 @@ function valuationStatements(financials: TickerFinancials): { quarterly: Financi
   return { quarterly: financials.quarterlyStatements.map(knownWhenFiled), annual: financials.annualStatements.map(knownWhenFiled) };
 }
 
+/**
+ * A fiscal fourth quarter's EPS stated without a filing date of its own (a
+ * 10-K states the year, the results release the quarter) was public once its
+ * year's filing was, so it is dated by that filing. The daily P/E of the
+ * quarters after it then sums the same four quarters PEB and the headline EPS
+ * (TTM) sum (time-series/filed-trailing-eps), rather than reading the quarter
+ * from the year and landing a cent of rounding away from them. The window that
+ * ends with the year takes the year's own EPS (fiscalYearEpsAtYearEnd).
+ */
+function fourthQuarterEpsAtYearFiling(row: FinancialStatement, annual: readonly FinancialStatement[]): FinancialStatement {
+  if (!isFiniteNumber(row.eps) || hasStatementGap(row, "eps") || statementFieldAvailability(row, "eps")) return row;
+  const year = annual.find((candidate) => candidate.currency === row.currency && areNearbyFinancialPeriodEnds(candidate.date, row.date));
+  const filed = year && isFiniteNumber(year.eps) ? statementFieldAvailability(year, "eps") : undefined;
+  return filed ? { ...row, fieldAvailability: { ...row.fieldAvailability, eps: filed } } : row;
+}
+
+/**
+ * At a fiscal year end the filed year's diluted EPS is the daily trailing
+ * figure, as PEB and the headline EPS (TTM) read it (filed-trailing-eps): four
+ * quarters need not add up to their year (3.90 for the year beside four
+ * quarters of 1.00), so their sum stands only where the year gives no dated EPS.
+ */
+function fiscalYearEpsAtYearEnd(statements: readonly InternalStatement[], annual: readonly FinancialStatement[]): InternalStatement[] {
+  return statements.map((statement) => {
+    const year = annual.find((row) => row.currency === statement.currency && areNearbyFinancialPeriodEnds(row.date, statement.date));
+    const eps = year && !hasStatementGap(year, "eps") ? statementNumber(year, "eps") : null;
+    if (!year || eps === null) return statement;
+    const { epsBasis: _sum, ...rest } = statement;
+    const fieldAvailability = { ...statement.fieldAvailability };
+    const filed = statementFieldAvailability(year, "eps");
+    if (filed) fieldAvailability.eps = filed;
+    else delete fieldAvailability.eps;
+    const next: InternalStatement = {
+      ...rest, eps, fieldAvailability, ...(year.epsBasis ? { epsBasis: year.epsBasis } : {}),
+      __timeSeriesDerivedFields: [...new Set([...(statement.__timeSeriesDerivedFields ?? []), "eps" as const])],
+    };
+    next.availableAt = completeStatementAvailability(next) ?? statement.availableAt;
+    return next;
+  });
+}
+
 /** An undated vendor value cannot block a derivation from dated filings. */
 function datedValuationStatement(statement: FinancialStatement): FinancialStatement {
   const dated = { ...statement };
@@ -530,6 +571,8 @@ function sourceStatements(
     const venue = financials.quote?.listingExchangeName || financials.quote?.exchangeName || exchange;
     known = { quarterly: known.quarterly.map(row => statementAtRelease(row, releases, venue)),
       annual: known.annual.map(row => statementAtRelease(row, releases, venue)) };
+    const annualRows = known.annual;
+    known = { ...known, quarterly: known.quarterly.map((row) => fourthQuarterEpsAtYearFiling(row, annualRows)) };
     known = { quarterly: known.quarterly.map(datedValuationStatement), annual: known.annual.map(datedValuationStatement) };
     // A later comparative quarter may repeat a year-end balance sheet that
     // the annual filing already published. Only identical, same-currency
@@ -559,7 +602,7 @@ function sourceStatements(
     // Sparse or loss-making quarters are gaps, not permission to substitute
     // an older annual denominator. Annual-only issuers retain their years.
     if (!known.quarterly.length) return { statements: mergeStatementsByPeriod(known.annual), period: "annual" };
-    const statements = buildTtmStatements(quarterly, known.annual);
+    const statements = fiscalYearEpsAtYearEnd(buildTtmStatements(quarterly, known.annual), known.annual);
     // Capitalization uses the latest reported share count, not an average
     // of four quarters. Keep TTM average shares for the income/EPS fallback.
     if (valuationMetric !== "trailingPE") for (const statement of statements) {

package/src/time-series/ice-credit.ts

@@ -17,6 +17,9 @@ export interface IceCreditSeries {
   tags: readonly string[];
 }
 
+/** What every surface that shows an ICE series says about how far back FRED carries it. */
+export const ICE_HISTORY_LIMIT_NOTICE = "History limited to 3 years by the publisher.";
+
 const HIGH_YIELD = ["high yield", "junk"];
 
 export const ICE_CREDIT_SERIES: readonly IceCreditSeries[] = [

package/src/time-series/price-comparison.ts

@@ -10,6 +10,19 @@ import {
 } from "../market-data/market/period-return";
 
 const PRICE_COMPARISON_BASIS = "Price returns in each listing's currency; cash distributions and FX conversion excluded.";
+const TOTAL_COMPARISON_BASIS = "Total returns in each listing's currency; cash distributions reinvested at the ex-date close, FX conversion excluded.";
+
+/**
+ * What a comparison's returns are: price returns, or total returns when the
+ * chart asked for them, naming any leg whose distributions could not be read
+ * (it stays a price return, and the others do not wait for it).
+ */
+function comparisonBasis(spec: ChartSpec, legs: ReadonlyArray<{ label: string; entry: ResolvedSeries | undefined }>): string {
+  if (spec.viewport.totalReturn !== true) return PRICE_COMPARISON_BASIS;
+  const priceOnly = legs.filter(({ entry }) => entry?.returnBasis === "price").map(({ label }) => label);
+  if (priceOnly.length === legs.length && legs.length > 0) return PRICE_COMPARISON_BASIS;
+  return priceOnly.length ? `${TOTAL_COMPARISON_BASIS} Price return for ${priceOnly.join(", ")}: distribution history unavailable.` : TOTAL_COMPARISON_BASIS;
+}
 
 export interface PriceComparison {
   seriesIds: string[];
@@ -111,6 +124,20 @@ export function priceComparisonSeriesIds(spec: ChartSpec): string[] | null {
   return visible.map((entry) => entry.id);
 }
 
+/**
+ * What a total-return chart's price levels are when it is not a comparison (the
+ * raw price axis): prices with cash distributions reinvested, not what the
+ * listing quotes. Null for a price chart, and when no leg is a total return.
+ */
+export function totalReturnLevelsNotice(spec: ChartSpec, series: readonly ResolvedSeries[]): string | null {
+  if (spec.viewport.totalReturn !== true) return null;
+  const legs = series.filter((entry) => entry.returnBasis !== undefined);
+  if (!legs.some((entry) => entry.returnBasis === "total")) return null;
+  const priceOnly = legs.filter((entry) => entry.returnBasis === "price").map((entry) => entry.label);
+  return `Total return levels in each listing's currency: prices include cash distributions reinvested at the ex-date close, so they are not quoted prices; FX conversion excluded.${
+    priceOnly.length ? ` Price only for ${priceOnly.join(", ")}: distribution history unavailable.` : ""}`;
+}
+
 interface ComparedLeg {
   id: string;
   label: string;
@@ -152,7 +179,8 @@ export function resolvePriceComparison(
     return source?.kind === "security" ? source.instrument.symbol : id;
   };
   // A leg not loaded yet (a seed from cached history) has not failed: nothing compares until it is.
-  const unavailable = `${PRICE_COMPARISON_BASIS} Comparison unavailable: need two shared dates and a nonzero baseline.`;
+  const basis = comparisonBasis(spec, seriesIds.map((id) => ({ label: symbolOf(id), entry: byId.get(id) })));
+  const unavailable = `${basis} Comparison unavailable: need two shared dates and a nonzero baseline.`;
   if (seriesIds.some((id) => !byId.has(id))) return { seriesIds, start: null, end: null, notice: unavailable };
   const dropped: NonNullable<PriceComparison["dropped"]> = [];
   const reported = new Set<string>();
@@ -259,7 +287,7 @@ export function resolvePriceComparison(
     sourceBounds,
     legs: legDays,
     ...(dropped.length ? { dropped } : {}),
-    notice: `${PRICE_COMPARISON_BASIS} ${span}${droppedText}`,
+    notice: `${basis} ${span}${droppedText}`,
   };
 }
 

package/src/time-series/resolve-context.ts

@@ -3,7 +3,7 @@ import type { PriceHistoryResult } from "../types/price-history";
 import { LiveBarAccumulator } from "./live-bars";
 import type { ChartResolutionSupport, ManualChartResolution } from "./resolution";
 import type { DataProvider, MarketDataRequestContext } from "../types/data-provider";
-import type { EarningsAction, Quote, QuoteMetadata, TickerFinancials } from "../types/financials";
+import type { CorporateActionsData, EarningsAction, Quote, QuoteMetadata, TickerFinancials } from "../types/financials";
 import type { EarningsHistoryPayload } from "../api-client/earnings";
 import type { FredSeriesLoadResult, FredSeriesRequest } from "../sources/gloomberb-cloud/fred-series";
 import { chartQuoteOverrideKeyForSource } from "./live-quotes";
@@ -78,6 +78,8 @@ export interface LiveTailRequest {
 export class ChartResolveCache {
   readonly financialsByInstrument = new Map<string, Promise<TickerFinancials | null>>();
   readonly earningsReleasesByInstrument = new Map<string, Promise<EarningsAction[]>>();
+  /** Each listing's cash distribution history, for the charts that draw total returns. */
+  readonly distributionsByInstrument = new Map<string, Promise<CorporateActionsData | null>>();
   readonly quoteMetadataByInstrument = new Map<string, Promise<QuoteMetadata | null>>();
   /** Each futures symbol's contract price unit, asked once per chart once known. */
   readonly futuresPriceUnits = new Map<string, Promise<string | null>>();

package/src/time-series/resolve.ts

@@ -23,7 +23,7 @@ import {
 import { aggregatePriceBars, futuresOpenMinuteOf, withBuiltBarSize } from "./bar-aggregation";
 import { TIME_RANGES, type TimeRange } from "./range";
 import type { DataProvider } from "../types/data-provider";
-import type { EarningsAction, Quote, TickerFinancials } from "../types/financials";
+import type { CorporateActionsData, EarningsAction, Quote, TickerFinancials } from "../types/financials";
 import { mergeQuoteMetadata, quoteMetadataFromQuote, quoteMetadataMatchesTarget } from "../market-data/quotes/metadata";
 import type { FredSeriesRequest } from "../sources/gloomberb-cloud/fred-series";
 import { fredCreditCoverageNotice } from "./economic";
@@ -44,12 +44,14 @@ import { VALUATION_CURRENCY_WARNING_PREFIX } from "./valuation-currency";
 import { chartPriceHistoryIntegrityNotices } from "./market";
 import { maxStudyWarmupPoints, resolveStudies } from "./studies";
 import { clipSeriesToWindow } from "./alignment";
+import { totalReturnSeries } from "./total-return";
 import {
   bufferPriceComparison,
   clipPriceComparison,
   priceComparisonBoundsForSeries,
   priceComparisonSeriesIds,
   resolvePriceComparison,
+  totalReturnLevelsNotice,
 } from "./price-comparison";
 import { chartQuoteOverrideKeyForSource } from "./live-quotes";
 import { chartSeriesSourceKey } from "../capabilities/chart-series";
@@ -266,6 +268,13 @@ export async function resolveChartSpecData(
   return result;
 }
 
+/** The price fields whose returns a distribution adds to. */
+function totalReturnFieldId(fieldId: string): boolean {
+  const canonical = getTimeSeriesField(fieldId)?.id ?? fieldId;
+  return canonical === "market.ohlcv" || canonical === "market.close" || canonical === "market.open"
+    || canonical === "market.high" || canonical === "market.low";
+}
+
 async function resolveChartSpecPass(
   spec: ChartSpec,
   sources: ChartResolveSources,
@@ -277,6 +286,7 @@ async function resolveChartSpecPass(
     && entry.source.kind === "security" && isFundamentalFieldId(entry.source.fieldId))
     ? [FINANCIAL_VINTAGE_NOTICE] : [];
   const priorityWarnings: string[] = [];
+  const coverageNotices: string[] = [];
   const delistings = new Map<string, { symbol: string; label: string; notice: string }>();
   const baseSeriesIds = new Set(spec.series.map((entry) => entry.id));
   const visibleSeriesIds = new Set(spec.series
@@ -357,6 +367,26 @@ async function resolveChartSpecPass(
     }
     return pending;
   };
+  // Total returns reinvest the cash a listing paid; each listing's history is read once per chart.
+  const loadDistributions = (source: Extract<ChartSeriesSpec["source"], { kind: "security" }>) => {
+    const key = instrumentKey(source);
+    let pending = cache.distributionsByInstrument.get(key);
+    if (!pending) {
+      pending = (async (): Promise<CorporateActionsData | null> => {
+        const read = sources.dataProvider?.getCorporateActions;
+        if (!read) return null;
+        try {
+          return await read.call(sources.dataProvider, source.instrument.symbol, source.instrument.exchange, requestContext(source));
+        } catch (error) {
+          cache.distributionsByInstrument.delete(key);
+          throw error;
+        }
+      })();
+      cache.distributionsByInstrument.set(key, pending);
+      cache.revision += 1;
+    }
+    return pending;
+  };
   const loadQuoteMetadata = (source: Extract<ChartSeriesSpec["source"], { kind: "security" }>) => {
     const key = instrumentKey(source);
     let pending = cache.quoteMetadataByInstrument.get(key);
@@ -527,6 +557,12 @@ async function resolveChartSpecPass(
     const sourceResolution = dailyValuation ? "1d" : initialResolution;
     const maxRange = getSupportMaxRange(support, sourceResolution);
     const ahead = movedWindow ? barsAhead(requestVisibleBounds, maxRange, referenceNow.getTime()) : 0;
+    // Bars ahead that reach the present end wherever the clock is on this pass.
+    // Such a window is named by its start and the present, so every pass shares
+    // one acquisition and the stale-copy refresh below keeps it current. Named
+    // by the clock, each live pass fetched and kept another copy of the history.
+    const toPresent = ahead > 0 && requestVisibleBounds.end !== null
+      && requestVisibleBounds.end + ahead >= referenceNow.getTime();
     const durationEnd = rangeDurationBounds(spec, initialCalculationBounds).end;
     const historyBounds = clampHistoryBoundsToSupport(
       ahead > 0 && initialCalculationBounds.end !== null
@@ -560,7 +596,9 @@ async function resolveChartSpecPass(
       request.allowProviderDefaultFallback ? "auto" : "manual",
       isMarketFieldId(source.fieldId) ? source.period ?? "auto" : "auto",
       ...(request.explicitWindow
-        ? [request.bounds.start ?? "open", request.bounds.end ?? "open"]
+        ? toPresent
+          ? [initialCalculationBounds.start ?? "open", "present"]
+          : [request.bounds.start ?? "open", request.bounds.end ?? "open"]
         : []),
       // A moved view can chart retained bars that the same authored dates cannot.
       ...(request.explicitWindow && !request.authoredWindow && !request.allowProviderDefaultFallback ? ["moved"] : []),
@@ -803,7 +841,10 @@ async function resolveChartSpecPass(
         const result = baseEconomicSeries(seriesSpec, fred, index);
         const coverageNotice = fredCreditCoverageNotice(seriesSpec.source.seriesId, fred.data.info,
           requestVisibleBounds.start, fred.data.observations);
-        if (result && coverageNotice) priorityWarnings.push(`${result.label}: ${coverageNotice}`);
+        if (result && coverageNotice) {
+          priorityWarnings.push(`${result.label}: ${coverageNotice}`);
+          coverageNotices.push(`${result.label}: ${coverageNotice}`);
+        }
         const freshnessWarning = staleFredWarning(fred);
         if (result && freshnessWarning) priorityWarnings.push(`${result.label}: ${freshnessWarning}`);
         return result;
@@ -927,7 +968,13 @@ async function resolveChartSpecPass(
         contractUnit,
       );
       if (!base) throw new Error(`Unknown field ${source.fieldId}.`);
-      const result = builtBars ? withBuiltBarSize(base, builtBars) : base;
+      let result = builtBars ? withBuiltBarSize(base, builtBars) : base;
+      if (spec.viewport.totalReturn === true && totalReturnFieldId(source.fieldId)) {
+        const outcome = await totalReturnSeries(result, () => loadDistributions(resolvedSource),
+          merged.quote?.currency || quoteMetadata?.currency, referenceNow);
+        result = outcome.series;
+        if (outcome.notice) warnings.push(`${instrumentLabel(resolvedSource)}: ${outcome.notice}`);
+      }
       if (marketField && history?.historyStart !== undefined && Number.isFinite(history.historyStart)) {
         result.historyStart = new Date(history.historyStart);
       }
@@ -1073,6 +1120,9 @@ async function resolveChartSpecPass(
     bounds, comparisonResolution, requestBounds ? null : spec.viewport.dateWindow ?? null,
   );
   if (priceComparison) warnings.push(priceComparison.notice);
+  // A raw-price chart of total returns is no comparison, and its levels say what they are instead.
+  const returnBasisNotice = priceComparison ? null : totalReturnLevelsNotice(spec, rawSeries);
+  if (returnBasisNotice) warnings.push(returnBasisNotice);
   warnings.push(...chartPriceHistoryIntegrityNotices(priceHistoryIntegrity));
   warnings.push(...financialPeriodCoverageWarnings(financialPeriodCoverage(spec, resolved)));
   const resolvedById = new Map(resolved.map((entry) => [entry.id, entry] as const));
@@ -1130,6 +1180,8 @@ async function resolveChartSpecPass(
     loading: false,
     errors,
     warnings: [...new Set([...priorityWarnings, ...warnings])],
+    ...(coverageNotices.length ? { coverageNotices: [...new Set(coverageNotices)] } : {}),
+    ...(returnBasisNotice ? { returnBasisNotice } : {}),
     ...(delistings.size ? { delistings: [...delistings.values()] } : {}),
     viewport,
     resolution,

package/src/time-series/session-bar.ts

@@ -136,3 +136,14 @@ export function withSessionBar(
   }
   return points;
 }
+
+/**
+ * The daily bars `history` shows as final, which alerts on a daily close read
+ * too: the bars as served, less the bar of a session still trading
+ * (withSessionBar, which `history` rebuilds from the quote and marks partial)
+ * and any bar the source marks partial. A close `history` prints without
+ * `partial` is final here, and one it prints with it is not.
+ */
+export function finalDailyBars(points: PricePoint[], options: SessionBarOptions): PricePoint[] {
+  return withSessionBar(points, null, options).filter((point) => !point.partial);
+}

package/src/time-series/spec.ts

@@ -37,7 +37,7 @@ import { isLeverageFactor } from "./leverage";
 const RANGE_SET = new Set<TimeRange>(TIME_RANGES);
 const PERIODS = new Set<SeriesPeriod>(["auto", "daily", "weekly", "monthly", "quarterly", "annual", "ttm"]);
 // `band` only stays on a capability series: a field's styles and an economic series' leave it out.
-const STYLES = new Set<SeriesStyle>(["line", "area", "step", "columns", "points", "candles", "ohlc", "hlc", "band"]);
+const STYLES = new Set<SeriesStyle>(["line", "area", "step", "columns", "points", "candles", "hollow", "heikin-ashi", "ohlc", "hlc", "band"]);
 const ECONOMIC_STYLES = new Set<SeriesStyle>(["line", "area", "step", "columns", "points"]);
 const TRANSFORMS = new Set<SeriesTransform>(["raw", "percent", "index100", "yoy", "qoq", "log"]);
 const AXES = new Set<SeriesAxis>(["auto", "left", "right"]);
@@ -71,7 +71,7 @@ export function isDatasetChart(spec: Pick<ChartSpec, "series">): boolean {
 }
 
 export function isOhlcSeriesStyle(style: SeriesStyle): boolean {
-  return style === "candles" || style === "ohlc" || style === "hlc";
+  return style === "candles" || style === "hollow" || style === "heikin-ashi" || style === "ohlc" || style === "hlc";
 }
 
 export function coerceSeriesTransformForStyle(
@@ -333,6 +333,7 @@ export function normalizeChartSpec(value: unknown, fallback: ChartSpec = DEFAULT
         ? Math.min(10_000, Math.floor(viewport.maxPoints))
         : undefined,
       ...(viewport?.extendedHours === true ? { extendedHours: true } : {}),
+      ...(viewport?.totalReturn === true ? { totalReturn: true } : {}),
     },
     panels,
     series,

package/src/time-series/studies.ts

@@ -400,15 +400,21 @@ function resolveVolume(spec: ChartStudySpec, input: ResolvedSeries, color: strin
   // No bar has volume to plot (spot FX quotes 0 for every bar; a coin's window
   // can miss every bar's), so the study adds no panel rather than an empty one.
   if (input.points.length > 0 && !input.points.some((point) => isFiniteNumber(point.volume) && point.volume !== 0)) return [];
+  // Left to its own colour, volume follows the candles: the price's colour for
+  // a bar that rose, the falling colour for one that fell. A colour picked for it stays flat.
+  const directional = !spec.color;
   const points = [...input.points]
     .sort((left, right) => left.date.getTime() - right.date.getTime())
     .flatMap((point) => isFiniteNumber(point.volume)
-      ? [derivedPoint({ point, value: point.volume }, point.volume)]
+      ? [{
+        ...derivedPoint({ point, value: point.volume }, point.volume),
+        ...(directional && isFiniteNumber(point.open) && isFiniteNumber(point.close) && point.close < point.open ? { fell: true } : {}),
+      }]
       : []);
   return [outputSeries(spec, input, {
     label: nameInput ? `Volume ${input.label}` : "Volume",
     points,
-    color,
+    color: directional ? input.color : color,
     unit: input.volumeUnit ?? "",
     unitGroup: "volume",
     style: "columns",