gloomberb 0.16.4 → 0.16.6

package/src/plugins/builtin/thirteenf/report-notes.ts

@@ -12,13 +12,115 @@ export const THIRTEENF_MAX_LIMIT = 200;
 
 export const AS_FILED_VALUE = "Value (USD) as reported at period end, not today's price";
 
+/** What a 13F filing leaves out and how late it arrives; the text reports' note and the catalog's limitation. */
+export const THIRTEENF_LIMITS = "Long US-listed equity positions only: shorts, cash and most foreign stocks are absent. Filed up to 45 days after quarter end.";
+
+/** The value basis of option rows, for exports. */
+export const THIRTEENF_OPTIONS_NOTE = "CALL/PUT rows: Value and Shares are the underlying stock's (notional), not the option premium.";
+
+/** The marker the text reports put on an option row's type, explained by `OPTION_ROWS_NOTE`. */
+const OPTION_MARK = "*";
+export const OPTION_ROWS_NOTE = `${OPTION_MARK} ${THIRTEENF_OPTIONS_NOTE}`;
+
+export function isOptionType(type: unknown): boolean {
+  const text = typeof type === "string" ? type.trim().toUpperCase() : "";
+  return text === "CALL" || text === "PUT";
+}
+
+/** A position type as the text report prints it: `CALL*` for an option, which `OPTION_ROWS_NOTE` explains. */
+export function markedPositionType(type: unknown): string {
+  const text = typeof type === "string" && type ? type : "--";
+  return isOptionType(type) ? `${text}${OPTION_MARK}` : text;
+}
+
 const count = (value: number) => value.toLocaleString("en-US");
 
-export function periodText(period: string | null | undefined, previousPeriod?: string | null): string {
+function periodText(period: string | null | undefined, previousPeriod?: string | null): string {
   if (!period) return "";
   return previousPeriod ? `Period ${period} vs ${previousPeriod}` : `Period ${period}`;
 }
 
+const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"] as const;
+const DAY_MS = 86_400_000;
+
+function calendarDay(date: string | null | undefined): Date | null {
+  if (!date || !/^\d{4}-\d{2}-\d{2}$/.test(date)) return null;
+  const day = new Date(`${date}T00:00:00Z`);
+  return Number.isFinite(day.getTime()) ? day : null;
+}
+
+/** "30 Jun 2026", or "30 Jun" in `omitYear`. */
+export function filingDayText(date: string, omitYear?: number): string {
+  const day = calendarDay(date);
+  if (!day) return date;
+  const text = `${day.getUTCDate()} ${MONTHS[day.getUTCMonth()]}`;
+  return day.getUTCFullYear() === omitYear ? text : `${text} ${day.getUTCFullYear()}`;
+}
+
+/** Whole days from a quarter end to the filing, or null when either date is unreadable. */
+export function filingLagDays(period: string | null | undefined, filed: string | null | undefined): number | null {
+  const end = calendarDay(period);
+  const day = calendarDay(filed);
+  return end && day ? Math.round((day.getTime() - end.getTime()) / DAY_MS) : null;
+}
+
+/**
+ * "Period 30 Jun · filed 14 Aug 2026 (45 days after quarter end) | QoQ vs 31 Mar":
+ * when the positions date from and when they became public. A date in the
+ * filing's year leaves its year out.
+ */
+export function filedPeriodText(
+  period: string | null | undefined,
+  filed: string | null | undefined,
+  previousPeriod?: string | null,
+): string {
+  if (!period) return "";
+  const filedDay = calendarDay(filed);
+  if (!filed || !filedDay) return periodText(period, previousPeriod);
+  const year = filedDay.getUTCFullYear();
+  const lag = filingLagDays(period, filed);
+  const after = lag != null && lag >= 0 ? ` (${count(lag)} ${lag === 1 ? "day" : "days"} after quarter end)` : "";
+  return [
+    `Period ${filingDayText(period, year)} · filed ${filingDayText(filed)}${after}`,
+    previousPeriod ? `QoQ vs ${filingDayText(previousPeriod, year)}` : "",
+  ].filter(Boolean).join(" | ");
+}
+
+/**
+ * The quarters whose filings Gloom Cloud restated to dollars, in its own words:
+ * "Values restated from thousands: 30 Jun 2026". Empty when none was.
+ */
+export function restatedValuesText(forms: readonly { periodOfReport: string; valueNote?: string }[]): string {
+  const noted = forms.filter((form) => form.valueNote);
+  if (noted.length === 0) return "";
+  const note = noted[0]!.valueNote!;
+  const periods = [...new Set(noted.map((form) => form.periodOfReport))].sort().reverse();
+  return `${note[0]!.toUpperCase()}${note.slice(1)}: ${periods.map((period) => filingDayText(period)).join(", ")}`;
+}
+
+/** A filer this many quarters behind the reporting cycle has missed a filing, not just filed late. */
+export function isStaleFiling(quartersBehind: number | null | undefined): quartersBehind is number {
+  return quartersBehind != null && quartersBehind > 1;
+}
+
+export function quartersOldText(quarters: number): string {
+  return `${count(quarters)} quarters old`;
+}
+
+const NOTHING_LATER = "nothing filed for a later quarter";
+
+export function staleFilingText(quarters: number): string {
+  return `Latest filing is ${quartersOldText(quarters)}; ${NOTHING_LATER}`;
+}
+
+/** The funds in a list whose latest filing is stale, the first few by name. */
+export function staleFundsText(funds: readonly { name: string; quarters: number }[], shown = 3): string {
+  if (funds.length === 0) return "";
+  if (funds.length === 1) return `${funds[0]!.name}: latest filing is ${quartersOldText(funds[0]!.quarters)}; ${NOTHING_LATER}`;
+  const named = funds.slice(0, shown).map((fund) => `${fund.name} (${quartersOldText(fund.quarters)})`).join(", ");
+  return `Latest filing 2+ quarters old: ${named}${funds.length > shown ? ` and ${count(funds.length - shown)} more` : ""}`;
+}
+
 /** "showing 50 of 374" from the start of the list, "showing 51-100 of 374" past it. */
 function shownRangeText(offset: number, end: number, total: number): string {
   return offset > 0

package/src/plugins/builtin/thirteenf/types.ts

@@ -29,6 +29,8 @@ export interface ThirteenFFormSummary {
   tableEntryTotal: number | null;
   isAmendment: boolean;
   amendmentType?: string;
+  /** Set by Gloom Cloud when it restated the filing's values to dollars ("values restated from thousands"). */
+  valueNote?: string;
 }
 
 export interface ThirteenFHoldingRecord {

package/src/plugins/builtin/ticker-detail/data-panes/returns-history.ts

@@ -0,0 +1,114 @@
+import { fetchHistoryResult, InvalidHistoryResultError } from "../../../../sources/history-result";
+import { historyRetentionNotice, isHistoryRetentionError } from "../../../../sources/history-retention";
+import {
+  getChartResolutionLabel,
+  type ChartResolutionSupport,
+  type ManualChartResolution,
+} from "../../../../time-series/resolution";
+import type { DataProvider } from "../../../../types/data-provider";
+import type { PricePoint } from "../../../../types/financials";
+import { isRoundTheClockCoin } from "../../../../utils/crypto-pair";
+import { isCurrencyPairListing } from "../../../../utils/fx-market-hours";
+import {
+  effectiveReturnResolution,
+  endsAtLatestBar,
+  latestBarTime,
+  returnLookbackMs,
+  returnSupportRange,
+  returnVisibleFrom,
+  returnWindowEnd,
+  type ReturnRange,
+} from "./returns-model";
+
+export interface ReturnSeries {
+  points: PricePoint[];
+  visibleFrom: number;
+  visibleTo: number;
+  coverageStart?: string;
+  range: ReturnRange;
+  resolution: ManualChartResolution;
+  /** The market is shut: the local date of its last session, which the window ends at. */
+  lastSession?: string;
+  /** The venue whose sessions the window follows; empty when none is known. */
+  venue: string;
+}
+
+export interface ReturnSeriesRequest {
+  symbol: string;
+  exchange: string;
+  range: ReturnRange;
+  /** The chosen interval; a range it cannot cover loads the nearest coarser one. */
+  resolution: ManualChartResolution;
+  /** What the source serves; empty uses the default intervals. */
+  support: readonly ChartResolutionSupport[];
+  now: number;
+  forceRefresh?: boolean;
+}
+
+function historyErrorMessage(error: unknown, resolution: ManualChartResolution): Error {
+  const label = getChartResolutionLabel(resolution);
+  if (isHistoryRetentionError(error)) return new Error(historyRetentionNotice(error.retention, label, null));
+  // The source answered at another cadence than asked: those bars are not this interval's returns.
+  if (error instanceof InvalidHistoryResultError) return new Error(`${label} bars are unavailable for this ticker`);
+  return error instanceof Error ? error : new Error(String(error));
+}
+
+/**
+ * The venue whose sessions set where the window ends: the one the ticker
+ * names, else the listing its quote names, so a bare VTI ends at the NYSE
+ * Arca close on a weekend. Coins and currency pairs need none.
+ */
+async function sessionVenue(provider: DataProvider, symbol: string, exchange: string): Promise<string> {
+  if (exchange || isRoundTheClockCoin(symbol) || isCurrencyPairListing(symbol, exchange)) return exchange;
+  try {
+    const metadata = provider.getQuoteMetadata
+      ? await provider.getQuoteMetadata(symbol, exchange)
+      : await provider.getQuote(symbol, exchange);
+    return metadata?.listingExchangeName ?? "";
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * The bars of a return window and where it starts and ends, as RETURN, its
+ * report and its capture all load them: the window ends now while the
+ * market trades and at its last session's close while it is shut
+ * (`returnWindowEnd`); the request reaches back far enough for the bar
+ * before the window, which every return is measured from.
+ */
+export async function loadReturnSeries(provider: DataProvider, request: ReturnSeriesRequest): Promise<ReturnSeries> {
+  const { symbol, exchange, range, support, now } = request;
+  const interval = effectiveReturnResolution(range, request.resolution, support);
+  const venue = await sessionVenue(provider, symbol, exchange);
+  const windowEnd = returnWindowEnd({ symbol, exchange: venue }, now);
+  const visibleFrom = returnVisibleFrom(range, interval, windowEnd.end);
+  const start = new Date(visibleFrom - returnLookbackMs(range, interval, support));
+  const end = new Date(now);
+  const context = request.forceRefresh ? { cacheMode: "refresh" as const } : undefined;
+  let result;
+  try {
+    // Exact bounds first, then the interval's range history, as charts do
+    // when a source keeps no bars for the exact window.
+    result = await fetchHistoryResult(provider, symbol, exchange, { kind: "detail", start, end, interval }, context);
+    if (!result?.points.length) {
+      result = await fetchHistoryResult(provider, symbol, exchange, { kind: "resolution", range: returnSupportRange(range), resolution: interval }, context) ?? result;
+    }
+  } catch (error) {
+    throw historyErrorMessage(error, interval);
+  }
+  if (!result) throw new Error("Price history unavailable");
+  const latest = latestBarTime(result.points);
+  return {
+    points: result.points,
+    visibleFrom: endsAtLatestBar(range) && latest !== null && latest < windowEnd.end
+      ? returnVisibleFrom(range, interval, latest)
+      : visibleFrom,
+    visibleTo: now,
+    ...(result.coverageStart ? { coverageStart: result.coverageStart } : {}),
+    range,
+    resolution: interval,
+    ...(windowEnd.lastSession ? { lastSession: windowEnd.lastSession } : {}),
+    venue,
+  };
+}

package/src/plugins/builtin/ticker-detail/data-panes/returns-model.ts

@@ -9,12 +9,29 @@ import {
   type ManualChartResolution,
 } from "../../../../time-series/resolution";
 import type { PricePoint } from "../../../../types/financials";
+import { isAlwaysOpenExchange, isRegularSessionTime, latestRegularSessionClose } from "../../../../market-data/market/freshness";
+import { isRoundTheClockCoin } from "../../../../utils/crypto-pair";
+import { currentFxClosureStart, isCurrencyPairListing } from "../../../../utils/fx-market-hours";
 import { pricePointValues } from "../../../../utils/price-history-integrity";
+import { zonedDateKey } from "../../../../utils/zoned-date-time";
 
 export type ReturnRange = "6H" | "1D" | "5D" | TimeRange;
 
 export const RETURN_RANGES: readonly ReturnRange[] = ["6H", "1D", "5D", "1W", "1M", "3M", "6M", "1Y", "5Y", "ALL"];
 
+/** The bar sizes RETURN takes, as `--interval` reads them. */
+export const RETURN_INTERVAL_VALUES: Array<{ value: ManualChartResolution; aliases?: string[] }> = [
+  { value: "1m", aliases: ["1min"] },
+  { value: "5m", aliases: ["5min"] },
+  { value: "15m", aliases: ["15min"] },
+  { value: "30m", aliases: ["30min"] },
+  { value: "45m", aliases: ["45min"] },
+  { value: "1h", aliases: ["60m", "hour", "hourly"] },
+  { value: "1d", aliases: ["day", "daily"] },
+  { value: "1wk", aliases: ["1w", "week", "weekly"] },
+  { value: "1mo", aliases: ["month", "monthly"] },
+];
+
 const HOUR_MS = 60 * 60_000;
 const DAY_MS = 24 * HOUR_MS;
 
@@ -46,13 +63,51 @@ export function returnVisibleFrom(range: ReturnRange, resolution: ManualChartRes
 }
 
 /**
- * A closed market leaves these windows without a bar when they end now, so
- * they end at the latest bar: on a weekend 1D is the last session.
+ * These windows are shorter than a closed market's gap, so they also end at
+ * the latest bar when it is earlier: a venue whose sessions the app does not
+ * know (an index, a future) still shows its last session on a weekend.
  */
 export function endsAtLatestBar(range: ReturnRange): boolean {
   return range === "6H" || range === "1D";
 }
 
+/** Where a return window ends, and why. */
+export interface ReturnWindowEnd {
+  end: number;
+  /** The market is shut: the local date of its last session, whose close the window ends at. */
+  lastSession?: string;
+}
+
+/**
+ * Where a return window ends: now while the market trades, and always for a
+ * coin, which trades around the clock. A market shut for the weekend, a
+ * holiday or the night ends it at its last session's close, so 5D on a Sunday
+ * is Monday to Friday rather than Wednesday to Friday and a gap. Spot FX
+ * closes for the weekend at 17:00 New York on Friday. A venue whose hours the
+ * app does not know ends now.
+ */
+export function returnWindowEnd(market: { symbol: string; exchange: string }, now: number): ReturnWindowEnd {
+  if (isRoundTheClockCoin(market.symbol, market.exchange) || isAlwaysOpenExchange(market.exchange)) return { end: now };
+  if (isCurrencyPairListing(market.symbol, market.exchange)) {
+    const closure = currentFxClosureStart(now);
+    return closure == null ? { end: now } : { end: closure, lastSession: zonedDateKey(closure - 1, "America/New_York") };
+  }
+  if (isRegularSessionTime(market.exchange, now) !== false) return { end: now };
+  const last = latestRegularSessionClose(market.exchange, now);
+  return last ? { end: last.close, lastSession: last.date } : { end: now };
+}
+
+const WEEKDAYS = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"] as const;
+const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"] as const;
+
+/** `market closed, last session Fri 9 Oct`; the year only when it is not the current one. */
+export function closedMarketNote(lastSession: string, now: number): string {
+  const day = new Date(`${lastSession}T00:00:00Z`);
+  if (!Number.isFinite(day.getTime())) return "market closed";
+  const year = day.getUTCFullYear() === new Date(now).getUTCFullYear() ? "" : ` ${day.getUTCFullYear()}`;
+  return `market closed, last session ${WEEKDAYS[day.getUTCDay()]} ${day.getUTCDate()} ${MONTHS[day.getUTCMonth()]}${year}`;
+}
+
 const WINDOW_DAYS: Record<ReturnRange, number> = {
   "6H": 0.25, "1D": 1, "5D": 5, "1W": 7, "1M": 31, "3M": 92, "6M": 183, "1Y": 366, "5Y": 1827, ALL: Number.POSITIVE_INFINITY,
 };

package/src/plugins/builtin/ticker-detail/data-panes/returns-pane.tsx

@@ -10,6 +10,7 @@ import {
   useQueryBarSearch,
   type DataTableCell,
   type DataTableColumn,
+  type PaneFooterSegment,
   type PaneHint,
 } from "../../../../components";
 import { usePaneRefreshKey } from "../../../../components/data-table/table-pane";
@@ -19,14 +20,11 @@ import {
   type ChartResolutionSupport,
   type ManualChartResolution,
 } from "../../../../time-series/resolution";
-import { fetchHistoryResult, InvalidHistoryResultError } from "../../../../sources/history-result";
 import { historyCoverageNotice } from "../../../../sources/history-coverage";
-import { historyRetentionNotice, isHistoryRetentionError } from "../../../../sources/history-retention";
 import { cleanFloat32Price, historyPriceDecimals } from "../../../../cli/history-rows";
 import { formatPriceObservation, quoteFormatOptions } from "../../../../market-data/market/format";
 import { usePaneTicker } from "../../../../state/app/context";
 import type { PaneProps } from "../../../../types/plugin";
-import type { PricePoint } from "../../../../types/financials";
 import { colors, priceColor } from "../../../../theme/colors";
 import { formatPercent } from "../../../../utils/format";
 import { publicTickerKey } from "../../../../utils/exchanges";
@@ -37,16 +35,13 @@ import { useBoundTicker, useTickerRequest } from "../../shared/ticker-request";
 import {
   availableReturnResolutions,
   buildReturnRows,
+  closedMarketNote,
   effectiveReturnResolution,
-  endsAtLatestBar,
-  latestBarTime,
   RETURN_RANGES,
-  returnLookbackMs,
-  returnSupportRange,
-  returnVisibleFrom,
   type ReturnRange,
   type ReturnRow,
 } from "./returns-model";
+import { loadReturnSeries, type ReturnSeries } from "./returns-history";
 
 type ReturnColumnId = "time" | "price" | "intervalChange" | "intervalPercent" | "cumulativeChange" | "cumulativePercent";
 type ReturnColumn = DataTableColumn & { id: ReturnColumnId };
@@ -64,15 +59,6 @@ const COLUMNS: ReturnColumn[] = [
   { id: "cumulativePercent", label: "TOTAL %", width: 9, align: "right", flexGrow: 1 },
 ];
 
-interface ReturnSeries {
-  points: PricePoint[];
-  visibleFrom: number;
-  visibleTo: number;
-  coverageStart?: string;
-  range: ReturnRange;
-  resolution: ManualChartResolution;
-}
-
 function formatDateTime(date: Date): string {
   const iso = date.toISOString();
   const hasTime = date.getUTCHours() !== 0 || date.getUTCMinutes() !== 0 || date.getUTCSeconds() !== 0;
@@ -121,14 +107,6 @@ function sortValue(row: ReturnRow, id: ReturnColumnId): number | null {
   }
 }
 
-function historyErrorMessage(error: unknown, resolution: ManualChartResolution): Error {
-  const label = getChartResolutionLabel(resolution);
-  if (isHistoryRetentionError(error)) return new Error(historyRetentionNotice(error.retention, label, null));
-  // The source answered at another cadence than asked: those bars are not this interval's returns.
-  if (error instanceof InvalidHistoryResultError) return new Error(`${label} bars are unavailable for this ticker`);
-  return error instanceof Error ? error : new Error(String(error));
-}
-
 export function ReturnsPane({ focused, width, height }: PaneProps) {
   const dataProvider = useAssetData();
   const { symbol, exchange, ticker } = useBoundTicker();
@@ -162,36 +140,15 @@ export function ReturnsPane({ focused, width, height }: PaneProps) {
 
   const loader = useCallback(async (nextSymbol: string, nextExchange: string, forceRefresh: boolean): Promise<ReturnSeries> => {
     if (!dataProvider) throw new Error("Market data unavailable");
-    const sourceSupport = await supportRequest;
-    const interval = effectiveReturnResolution(range, resolution, sourceSupport);
-    const now = Date.now();
-    const visibleFrom = returnVisibleFrom(range, interval, now);
-    const start = new Date(visibleFrom - returnLookbackMs(range, interval, sourceSupport));
-    const end = new Date(now);
-    const context = forceRefresh ? { cacheMode: "refresh" as const } : undefined;
-    let result;
-    try {
-      // Exact bounds first, then the interval's range history, as charts do
-      // when a source keeps no bars for the exact window.
-      result = await fetchHistoryResult(dataProvider, nextSymbol, nextExchange, { kind: "detail", start, end, interval }, context);
-      if (!result?.points.length) {
-        result = await fetchHistoryResult(dataProvider, nextSymbol, nextExchange, { kind: "resolution", range: returnSupportRange(range), resolution: interval }, context) ?? result;
-      }
-    } catch (error) {
-      throw historyErrorMessage(error, interval);
-    }
-    if (!result) throw new Error("Price history unavailable");
-    const latest = latestBarTime(result.points);
-    return {
-      points: result.points,
-      // A closed market leaves a short window ending now without bars, so it
-      // ends at the latest bar instead.
-      visibleFrom: endsAtLatestBar(range) && latest !== null ? returnVisibleFrom(range, interval, latest) : visibleFrom,
-      visibleTo: now,
-      ...(result.coverageStart ? { coverageStart: result.coverageStart } : {}),
+    return loadReturnSeries(dataProvider, {
+      symbol: nextSymbol,
+      exchange: nextExchange,
       range,
-      resolution: interval,
-    };
+      resolution,
+      support: await supportRequest,
+      now: Date.now(),
+      forceRefresh,
+    });
   }, [dataProvider, range, resolution, supportRequest]);
   const { data, loading, error, reload } = useTickerRequest(loader, symbol, exchange);
   usePaneRefreshKey(reload, { focused: focused && !searchActive });
@@ -228,7 +185,13 @@ export function ReturnsPane({ focused, width, height }: PaneProps) {
   const hints = useMemo<PaneHint[]>(() => (
     table.searchable ? [{ id: "search", key: "/", label: "search", onPress: focusSearch }] : []
   ), [focusSearch, table.searchable]);
-  usePaneStatusFooter({ registrationId: "returns", loading, error, hints });
+  // A shut market's window ends at its last session, which the footer names.
+  const marketInfo = useMemo<PaneFooterSegment[]>(() => (
+    data?.lastSession
+      ? [{ id: "market", parts: [{ text: closedMarketNote(data.lastSession, data.visibleTo), tone: "muted" }] }]
+      : []
+  ), [data]);
+  usePaneStatusFooter({ registrationId: "returns", loading, error, hints, info: marketInfo });
 
   const integrityNotice = priceHistoryIntegrityNotice(returnRows.filter((row) => row.inconsistent).length);
   const coverageNotice = data ? historyCoverageNotice(data.coverageStart, data.visibleFrom) : null;
@@ -308,6 +271,7 @@ export function ReturnsPane({ focused, width, height }: PaneProps) {
         ["Range", data?.range ?? range],
         ["Interval", getChartResolutionLabel(data?.resolution ?? shownResolution)],
         ["Window", data ? `after ${new Date(data.visibleFrom).toISOString()} through ${new Date(data.visibleTo).toISOString()}` : ""],
+        ...(data?.lastSession ? [["Market", closedMarketNote(data.lastSession, data.visibleTo)]] : []),
         ["Time zone", "UTC, bar open"],
         ["Basis", "Price returns of bar closes; dividends are not included"],
         ...(coverageNotice ? [["Coverage", coverageNotice]] : []),

package/src/plugins/builtin/ticker-detail/headless-schema.ts

@@ -1,5 +1,6 @@
 import type { HeadlessPaneDefinition } from "../../../types/headless";
 import { FINANCIAL_PERIOD_OPTION, HISTORY_RANGE_VALUES } from "../shared/headless-options";
+import { RETURN_INTERVAL_VALUES, RETURN_RANGES } from "./data-panes/returns-model";
 
 type PaneSchema = Pick<HeadlessPaneDefinition, "argument" | "options" | "discovery">;
 
@@ -64,4 +65,33 @@ export const paneSchemas = {
       screenshotReadiness: "partial",
     },
   },
+  "returns-pane": {
+    argument: { kind: "ticker" },
+    options: [
+      {
+        key: "range",
+        description: "Window the returns cover, ending now, or at the last session's close while the market is shut.",
+        type: "enum",
+        aliases: ["window", "period"],
+        values: RETURN_RANGES.map((value) => ({ value })),
+        defaultValue: "5D",
+        pluginState: { pluginId: "ticker-research" },
+      },
+      {
+        key: "interval",
+        description: "Bar size of each return; a range it does not reach uses the nearest longer bar the source keeps.",
+        type: "enum",
+        aliases: ["bar", "granularity", "resolution"],
+        values: RETURN_INTERVAL_VALUES,
+        defaultValue: "1h",
+        pluginState: { pluginId: "ticker-research" },
+      },
+    ],
+    discovery: {
+      id: "returns",
+      aliases: ["returns", "interval returns", "cumulative return", "performance"],
+      // A capture is read from the rendered table, as before the report existed.
+      screenshotReadiness: "live-dom",
+    },
+  },
 } satisfies Record<string, PaneSchema>;

package/src/plugins/builtin/ticker-detail/headless.ts

@@ -30,6 +30,11 @@ import {
   loadHeadlessFinancials, loadHeadlessPriceHistory, loadHeadlessSymbols, resolveHeadlessInstrument,
 } from "../shared/headless-market-data";
 import { barHistoryFreshness, barResolutionFromDates, quoteFreshnessFields, REPORTED_DATA } from "../shared/report-freshness";
+import { cleanFloat32Price, historyPriceDecimals } from "../../../cli/history-rows";
+import { historyCoverageNotice } from "../../../sources/history-coverage";
+import { getChartResolutionLabel, isIntradayResolution, type ManualChartResolution } from "../../../time-series/resolution";
+import { buildReturnRows, closedMarketNote, type ReturnRange } from "./data-panes/returns-model";
+import { loadReturnSeries } from "./data-panes/returns-history";
 
 export const financialStatementsHeadless: HeadlessPaneDefinition<"rows"> = {
   ...paneSchemas["financial-analysis-pane"],
@@ -286,3 +291,84 @@ export const historicalPricesHeadless: HeadlessPaneDefinition<"rows"> = {
     return { rows, freshness, ...(notice ? { complete: false } : {}), unavailableSymbols: rows.some((row) => row.close !== null) ? [] : [symbol], metadata: { symbol, range, ...(notice ? { notices: [notice] } : {}) } };
   },
 };
+
+/** A percent with its sign, two decimals: `+0.63%`; a dash for a gap. */
+function signedPercentCell(value: unknown): string {
+  if (typeof value !== "number" || !Number.isFinite(value)) return "-";
+  return `${value >= 0 ? "+" : ""}${value.toFixed(2)}%`;
+}
+
+export const returnsHeadless: HeadlessPaneDefinition<"rows"> = {
+  ...paneSchemas["returns-pane"],
+  shape: "rows",
+  description: "Interval and cumulative price returns of one ticker's bars over a range: each bar's close, its move from the bar before, and its move from the bar before the window.",
+  describe: ({ symbols, options }) => `Returns | ${symbols[0]} | ${options.range ?? "5D"} | ${options.interval ?? "1h"}`,
+  async load({ symbols, options }, ctx) {
+    const key = symbols[0]!;
+    const { symbol, exchange } = await resolveHeadlessInstrument(ctx, key);
+    const range = (options.range ?? "5D") as ReturnRange;
+    const requested = (options.interval ?? "1h") as ManualChartResolution;
+    const support = await Promise.resolve(ctx.marketData.getChartResolutionSupport?.(symbol, exchange ?? "") ?? []).catch(() => []);
+    const series = await loadReturnSeries(ctx.marketData, {
+      symbol, exchange: exchange ?? "", range, resolution: requested, support, now: Date.now(), forceRefresh: ctx.refresh,
+    });
+    const returns = buildReturnRows(series.points, series.visibleFrom, series.visibleTo).reverse();
+    const decimals = historyPriceDecimals(returns.flatMap((row) => row.price === null ? [] : [{
+      open: null, high: null, low: null, close: cleanFloat32Price(row.price),
+    }]));
+    const rounded = (value: number | null) => value === null || !Number.isFinite(value) ? null : Number(value.toFixed(Math.min(20, decimals)));
+    const percent = (value: number | null) => value === null ? null : value * 100;
+    const intraday = isIntradayResolution(series.resolution);
+    // A daily or longer bar is a trading date; an intraday one its UTC open.
+    const rows = returns.map((row) => ({
+      time: intraday ? new Date(row.timestamp).toISOString() : new Date(row.timestamp).toISOString().slice(0, 10),
+      close: rounded(row.price),
+      intervalChange: rounded(row.intervalChange),
+      intervalReturnPct: percent(row.intervalPercent),
+      totalChange: rounded(row.cumulativeChange),
+      totalReturnPct: percent(row.cumulativePercent),
+      ...(row.inconsistent ? { inconsistent: true } : {}),
+    }));
+    const price = (value: unknown) => typeof value === "number" && Number.isFinite(value) ? value.toFixed(decimals) : "-";
+    const columns: HeadlessPaneColumn[] = [
+      { key: "time", header: intraday ? "Time (UTC)" : "Date", format: (value) => String(value).slice(0, 16).replace("T", " ") },
+      { key: "close", header: "Price", align: "right", format: price },
+      { key: "intervalChange", header: "Int $", align: "right", format: price },
+      { key: "intervalReturnPct", header: "Int %", align: "right", format: signedPercentCell },
+      { key: "totalChange", header: "Total $", align: "right", format: price },
+      { key: "totalReturnPct", header: "Total %", align: "right", format: signedPercentCell },
+    ];
+    // An interval the range is too long for is served in the nearest longer bar; say so rather than switch silently.
+    const notices = [
+      series.resolution !== requested
+        ? `${getChartResolutionLabel(requested)} bars do not reach back ${range}; these are ${getChartResolutionLabel(series.resolution)} bars.`
+        : null,
+      historyCoverageNotice(series.coverageStart, series.visibleFrom),
+      priceHistoryIntegrityNotice(rows.filter((row) => row.inconsistent).length) ?? null,
+    ].filter((notice): notice is string => !!notice);
+    return {
+      rows,
+      columns,
+      unavailableSymbols: rows.length ? [] : [key],
+      ...(rows.length ? {} : { errors: [`${key}: No bars in this window.`] }),
+      freshness: {
+        ...barHistoryFreshness(intraday ? null : series.resolution),
+        observedKey: "time",
+        oldest: null,
+        ...(series.venue ? { cadenceExchange: series.venue } : {}),
+        // The window ends at the last session while the market is shut, which the status line says.
+        ...(series.lastSession ? { note: closedMarketNote(series.lastSession, series.visibleTo) } : {}),
+      },
+      metadata: {
+        symbol: key,
+        range,
+        interval: series.resolution,
+        requestedInterval: requested,
+        window: { after: new Date(series.visibleFrom).toISOString(), through: new Date(series.visibleTo).toISOString() },
+        ...(series.lastSession ? { marketClosed: true, lastSession: series.lastSession } : {}),
+        basis: "Price returns of bar closes; dividends are not included",
+        ...(notices.length ? { notices } : {}),
+      },
+    };
+  },
+};