gloomberb 0.18.2 → 0.18.4

package/src/plugins/builtin/ticker-detail/adr-pair/model.ts

@@ -0,0 +1,132 @@
+import type { DepositaryPair, Quote, TickerFinancials } from "../../../../types/financials";
+import type { TickerRecord } from "../../../../types/ticker";
+import { canonicalExchange, parsePublicTickerKey, publicTickerKey } from "../../../../utils/exchanges";
+import { listingSuffixCandidate, listingSuffixVenue } from "../../../../sources/listing-symbols";
+import { formatMarketPriceWithCurrency } from "../../../../market-data/market/format";
+import { adrRatioText } from "../../../../utils/depositary-receipt";
+import {
+  compareDepositaryPair, dollarPairLabel, formatPairRate, isReceiptSide, listingDepositaryPair, pairPriceInput, pairTimeText,
+  premiumText, ratioCount, spotRateKind, type DepositaryPairComparison, type PairPriceInput, type PairSpotInput,
+} from "../../../../market-data/depositary-pair";
+
+/** The DES tab a listing with a known receipt pair gets, and the function that opens DES on it. */
+export const ADR_PAIR_TAB_ID = "adr-vs-home";
+export const ADR_PAIR_TEMPLATE_ID = "adr-pair-pane";
+
+/** The two listings a pair compares, from one side's records: the listing itself and the other line. */
+export interface AdrPairLegs {
+  pair: DepositaryPair;
+  /** The listing is the receipt (else one of the home lines). */
+  receiptSide: boolean;
+  receiptKey: string;
+  homeKey: string;
+  /** The line to quote besides the listing's own. */
+  otherKey: string;
+}
+
+/** Whether a home line of the pair is the listing (GGAL.BA for GGAL on BYMA). */
+function sameListing(line: string, symbol: string, exchange: string | undefined): boolean {
+  const own = parsePublicTickerKey(symbol);
+  const ownSuffix = listingSuffixVenue(own.symbol, exchange);
+  const ownSymbol = ownSuffix?.symbol ?? own.symbol;
+  const ownVenue = canonicalExchange(ownSuffix?.exchange ?? own.exchange ?? exchange);
+  if (line.toUpperCase() === symbol.toUpperCase()) return true;
+  // A served line's suffix names its venue, a one-letter one too (GSK.L is GSK on LSE).
+  const venue = listingSuffixCandidate(line);
+  return !!venue && venue.symbol === ownSymbol && canonicalExchange(venue.exchange) === ownVenue;
+}
+
+export function adrPairLegs(
+  financials: Pick<TickerFinancials, "quote" | "fundamentals"> | null | undefined,
+  ticker: Pick<TickerRecord, "metadata"> | null | undefined,
+  symbol: string | null | undefined,
+): AdrPairLegs | null {
+  const pair = listingDepositaryPair(financials);
+  if (!pair) return null;
+  const receiptSide = isReceiptSide(financials);
+  const ownSymbol = ticker?.metadata.ticker ?? symbol ?? "";
+  const ownExchange = ticker?.metadata.exchange || financials?.quote?.listingExchangeName || undefined;
+  if (receiptSide) return { pair, receiptSide, receiptKey: pair.receipt, homeKey: pair.ordinary[0]!, otherKey: pair.ordinary[0]! };
+  const home = pair.ordinary.find((line) => sameListing(line, ownSymbol, ownExchange))
+    ?? (ownExchange && !parsePublicTickerKey(ownSymbol).exchange ? publicTickerKey(ownSymbol, ownExchange) : ownSymbol);
+  return { pair, receiptSide, receiptKey: pair.receipt, homeKey: home, otherKey: pair.receipt };
+}
+
+/** The comparison from the two quotes and the home currency's USD value (as exchange rates are served). */
+export function adrPairComparison(
+  legs: AdrPairLegs,
+  quotes: { receipt: Quote | null | undefined; home: Quote | null | undefined },
+  spot: PairSpotInput | null,
+  now = Date.now(),
+): DepositaryPairComparison | null {
+  return compareDepositaryPair(legs.pair.ratio, pairPriceInput(legs.receiptKey, quotes.receipt), pairPriceInput(legs.homeKey, quotes.home), spot, now);
+}
+
+export interface AdrPairFigure {
+  id: string;
+  label: string;
+  value: string;
+  detail?: string;
+}
+
+/** The figures the tab heads with: the implied rate, spot, the premium and the ratio. */
+export function adrPairFigures(comparison: DepositaryPairComparison): AdrPairFigure[] {
+  const currency = comparison.home.currency;
+  const pairLabel = dollarPairLabel(currency);
+  const kind = spotRateKind(currency);
+  return [
+    {
+      id: "implied", label: `Implied ${pairLabel}`, value: formatPairRate(comparison.impliedFx),
+      // Through a receipt the peso rate is the CCL rate traders quote.
+      detail: currency === "ARS" ? "CCL" : `home × ${ratioCount(comparison.ratio)} / ADR`,
+    },
+    {
+      id: "spot", label: `Spot ${pairLabel}`, value: comparison.spot ? formatPairRate(comparison.spot.rate) : "—",
+      ...(kind ? { detail: kind } : {}),
+    },
+    {
+      id: "premium", label: "ADR vs home",
+      value: comparison.premiumPercent == null ? "—" : premiumText(comparison.premiumPercent),
+      ...(comparison.premiumPercent == null ? {} : { detail: "at spot" }),
+    },
+    { id: "ratio", label: "Ratio", value: adrRatioText(comparison.ratio) ?? `1:${ratioCount(comparison.ratio)}` },
+  ];
+}
+
+export interface AdrPairInputRow {
+  id: "home" | "receipt" | "spot";
+  listing: string;
+  role: string;
+  price: string;
+  asOf: string;
+  session: string;
+  /** The listing a row opens, none for the spot rate. */
+  opens: string | null;
+}
+
+function sessionText(input: PairPriceInput): string {
+  return input.open ? "Open" : "Closed";
+}
+
+/** The inputs the figures come from, each with when it was set. */
+export function adrPairInputRows(comparison: DepositaryPairComparison, now = Date.now()): AdrPairInputRow[] {
+  const { home, receipt, spot, ratio } = comparison;
+  const time = (value: number | null) => value == null ? "—" : pairTimeText(value, now).replace(/ UTC$/, "");
+  const kind = spotRateKind(home.currency);
+  return [
+    {
+      id: "home", listing: home.symbol, role: `Home, ${ratioCount(ratio)} per ADR`,
+      price: formatMarketPriceWithCurrency(home.price, home.currency, { currencyCode: true }),
+      asOf: time(home.observedAt), session: sessionText(home), opens: home.symbol,
+    },
+    {
+      id: "receipt", listing: receipt.symbol, role: "ADR",
+      price: formatMarketPriceWithCurrency(receipt.price, receipt.currency), asOf: time(receipt.observedAt),
+      session: sessionText(receipt), opens: receipt.symbol,
+    },
+    ...spot ? [{
+      id: "spot" as const, listing: dollarPairLabel(home.currency), role: kind ? `Spot, ${kind}` : "Spot",
+      price: formatPairRate(spot.rate), asOf: time(spot.observedAt), session: "", opens: null,
+    }] : [],
+  ];
+}

package/src/plugins/builtin/ticker-detail/adr-pair/tab.tsx

@@ -0,0 +1,87 @@
+import { useState } from "react";
+import {
+  DataTableView, EmptyState, Notice, PaneStatusBody, StatGrid, statGridRows, usePaneTicker,
+  type DataTableCell, type DataTableColumn, type StatItem,
+} from "../../../../components";
+import { useFxRateObservations, useQuoteEntry } from "../../../../market-data/hooks";
+import { resolveEntryData } from "../../../../market-data/selectors";
+import { spotFromUsdValue } from "../../../../market-data/depositary-pair";
+import { heldCurrencyUnit } from "../../../../utils/currency-units";
+import type { TickerResearchTabProps } from "../../../../types/plugin";
+import { Box } from "../../../../ui";
+import { useOpenDescription } from "../../shared/open-description";
+import { adrPairComparison, adrPairFigures, adrPairInputRows, adrPairLegs, type AdrPairInputRow } from "./model";
+
+// The price and its time first: a narrow pane keeps them and drops the role.
+const COLUMNS: DataTableColumn[] = [
+  { id: "listing", label: "Listing", width: 9, align: "left" },
+  { id: "price", label: "Price", width: 13, align: "right" },
+  { id: "asOf", label: "As of (UTC)", width: 16, align: "left" },
+  { id: "session", label: "Session", width: 7, align: "left" },
+  { id: "role", label: "Role", width: 24, align: "left" },
+];
+
+function renderCell(row: AdrPairInputRow, column: DataTableColumn): DataTableCell {
+  return { text: String(row[column.id as keyof AdrPairInputRow] ?? "") };
+}
+
+/**
+ * DES "ADR vs home": a receipt beside its home line, for a listing Gloom
+ * Cloud pairs with one. The ratio, both prices, the dollar rate they imply
+ * (home × ratio / ADR), spot, and the receipt's premium or discount at spot,
+ * each price dated, and a note when the two were not set together.
+ */
+export function AdrPairResearchTab({ width, height, focused }: TickerResearchTabProps) {
+  const { symbol, ticker, financials } = usePaneTicker();
+  const legs = adrPairLegs(financials, ticker, symbol);
+  // Both legs through the quote path, so each is read alike whichever side the pane is on.
+  const ownEntry = useQuoteEntry(legs ? ticker?.metadata.ticker ?? symbol : null, ticker);
+  const otherEntry = useQuoteEntry(legs?.otherKey ?? null, null);
+  const [receiptEntry, homeEntry] = legs?.receiptSide ? [ownEntry, otherEntry] : [otherEntry, ownEntry];
+  const receiptQuote = resolveEntryData(receiptEntry);
+  const homeQuote = resolveEntryData(homeEntry);
+  // The home price's currency, a minor unit read as its own (GBp as GBP), as the comparison reads it.
+  const homeCurrency = homeQuote?.currency ? heldCurrencyUnit(homeQuote.currency).currency : "";
+  const observed = useFxRateObservations([homeCurrency]).get(homeCurrency);
+  const spot = spotFromUsdValue(observed?.rate, observed?.asOf);
+  const comparison = legs ? adrPairComparison(legs, { receipt: receiptQuote, home: homeQuote }, spot) : null;
+  const openDescription = useOpenDescription();
+  const [selectedIndex, setSelectedIndex] = useState(0);
+
+  const stats: StatItem[] = comparison ? adrPairFigures(comparison) : [];
+  const rows = comparison ? adrPairInputRows(comparison) : [];
+
+  if (!legs) return <EmptyState title="No ADR pair for this listing." />;
+  const pending = (entry: typeof receiptEntry) => !entry || entry.phase === "loading" || entry.phase === "idle";
+  const loading = !comparison && (pending(receiptEntry) || pending(homeEntry));
+  const error = !comparison && !loading
+    ? `Prices unavailable for ${!receiptQuote ? legs.receiptKey : legs.homeKey}.`
+    : null;
+  // The note wraps to the pane's width, less its inset.
+  const noteRows = comparison?.timingNote ? Math.ceil(comparison.timingNote.length / Math.max(1, width - 2)) : 0;
+  const tableHeight = Math.max(3, height - statGridRows(stats, width) - noteRows);
+
+  return <Box width={width} height={height} flexDirection="column" overflow="hidden">
+    <PaneStatusBody subject="ADR pair" loading={loading} error={error} width={width} height={height}>
+      {comparison ? <>
+        <StatGrid items={stats} width={width} />
+        {comparison.timingNote ? <Box paddingX={1} flexShrink={0}><Notice>{comparison.timingNote}</Notice></Box> : null}
+        <DataTableView<AdrPairInputRow>
+          focused={focused}
+          columns={COLUMNS}
+          items={rows}
+          rootWidth={width}
+          rootHeight={tableHeight}
+          getItemKey={(row) => row.id}
+          emptyStateTitle="No prices."
+          sortColumnId={null}
+          sortDirection="asc"
+          selection={{ kind: "index", selectedIndex, onChange: setSelectedIndex }}
+          isNavigable={(row) => row.opens != null}
+          onActivate={(row) => { if (row.opens) openDescription(row.opens); }}
+          renderCell={renderCell}
+        />
+      </> : null}
+    </PaneStatusBody>
+  </Box>;
+}

package/src/plugins/builtin/ticker-detail/data-panes/historical-prices.tsx

@@ -19,8 +19,10 @@ import { colors, priceColor } from "../../../../theme/colors";
 import { formatCompact, formatPercent } from "../../../../utils/format";
 import { isPlainKeyboardEvent } from "../../../../utils/keyboard";
 import { publicTickerKey } from "../../../../utils/exchanges";
-import { formatPriceObservation, quoteFormatOptions } from "../../../../market-data/market/format";
-import { cleanFloat32Price, historyPriceDecimals } from "../../../../cli/history-rows";
+import { quoteFormatOptions } from "../../../../market-data/market/format";
+import {
+  barPriceDecimals, formatBarPrice, historyAllStart, historyBarsAfterHole, historyChangeBaseNote, historyMissingPeriodsNote,
+} from "../../../../cli/history-rows";
 import {
   MISSING_VOLUME_TEXT, missingVolumeCount, missingVolumeNotice, pricePointValues, priceHistoryIntegrityNotice,
 } from "../../../../utils/price-history-integrity";
@@ -65,6 +67,8 @@ export type HistoricalPriceRow = {
   filled: boolean;
   change: number | null;
   changePercent: number | null;
+  /** Periods without a bar lie between this bar and the one before, so its change spans them (marked `*`). */
+  changeSpansGap: boolean;
 };
 
 function pricePointDate(point: PricePoint): Date | null {
@@ -81,26 +85,12 @@ function formatDateTime(date: Date): string {
 
 /** Every price in the table at one decimal count, so the columns line up. */
 function formatMaybePrice(value: number | null | undefined, decimals: number, width: number): string {
-  if (value == null || !Number.isFinite(value)) return "-";
-  const rounded = Number(value.toFixed(Math.min(20, decimals)));
-  return formatPriceObservation(rounded, { minimumFractionDigits: decimals, maxWidth: width });
+  return value == null || !Number.isFinite(value) ? "-" : formatBarPrice(value, decimals, width);
 }
 
-/**
- * The decimals the table's prices need, by the same rule the CLI history
- * uses: capped by the asset's display rules (cents for a US equity) and read
- * from the float32-cleaned values so feed noise does not widen every row.
- */
+/** The decimals the table's prices need: the one rule `history` and `fn HP` print by (barPriceDecimals). */
 function historicalPriceDecimals(rows: readonly HistoricalPriceRow[], assetCategory?: string): number {
-  const clean = (value: number | null) => value == null ? null : cleanFloat32Price(value);
-  return historyPriceDecimals(rows.flatMap(({ point }) => point.close == null ? [] : [{
-    date: "",
-    open: clean(point.open),
-    high: clean(point.high),
-    low: clean(point.low),
-    close: clean(point.close)!,
-    volume: point.volume,
-  }]), assetCategory);
+  return barPriceDecimals(rows.map(({ point }) => point), assetCategory);
 }
 
 /** The exported price: the digits the table shows, without the width limit. */
@@ -112,6 +102,11 @@ function formatMaybePercent(value: number | null): string {
   return value == null ? "-" : formatPercent(value);
 }
 
+/** A change across periods without a bar, marked `*`: its base is the bar before them, which the gap notice names. */
+function spanMark(text: string, row: Pick<HistoricalPriceRow, "changeSpansGap">, value: number | null): string {
+  return row.changeSpansGap && value != null ? `${text}*` : text;
+}
+
 /** Volume as the table shows it; missing reads as missing (`volumeMissing`) in a history that reports volume, never 0. */
 function formatVolume(value: number | null | undefined, volumeMissing: boolean): string {
   return value == null ? volumeMissing ? MISSING_VOLUME_TEXT : "-" : formatCompact(value);
@@ -127,6 +122,8 @@ interface HistoricalPriceTable {
   dayToDate: boolean;
   /** The newest bar's day, `YYYY-MM-DD`. */
   newestDate: string | undefined;
+  /** The months or weeks without a bar, named (historyMissingPeriodsNote), and what each change after them is from. */
+  gapNotices: string[];
 }
 
 function buildHistoricalPriceRows(points: PricePoint[], venue: string | undefined, now: number): HistoricalPriceTable {
@@ -140,6 +137,12 @@ function buildHistoricalPriceRows(points: PricePoint[], venue: string | undefine
   const newestDate = sorted.at(-1)?.date.toISOString().slice(0, 10);
   const forming = formingHistoryBar(size, newestDate, venue, now);
   const dayToDate = size === "1d" && sorted.at(-1)?.partial === true;
+  // A month or week without a bar, or a break in daily bars, is named; the change after it is from the bar before it.
+  const times = sorted.map((entry) => entry.date.getTime());
+  const interval = size === "intraday" ? null : size;
+  const afterGap = historyBarsAfterHole(times, interval);
+  const gapNotices = [historyMissingPeriodsNote(times, interval), historyChangeBaseNote(times, interval)]
+    .filter((notice): notice is string => notice != null);
   const rows = sorted.map((entry, index) => {
     const previous = sorted[index - 1]?.point;
     const { point, date, sourceIndex, filled } = entry;
@@ -159,9 +162,10 @@ function buildHistoricalPriceRows(points: PricePoint[], venue: string | undefine
       filled,
       change,
       changePercent: previous?.close && change !== null ? change / previous.close : null,
+      changeSpansGap: afterGap[index] === true,
     };
   }).reverse();
-  return { rows, size, forming, dayToDate, newestDate };
+  return { rows, size, forming, dayToDate, newestDate, gapNotices };
 }
 
 const HISTORY_PRICE_WIDTH = 10;
@@ -240,7 +244,7 @@ export function HistoricalPricesPane({ focused, width, height }: PaneProps) {
     () => withSessionBar(data ?? [], quote, { now: Date.now(), venue }),
     [data, quote, venue],
   );
-  const { rows, size, forming, dayToDate, newestDate } = useMemo(
+  const { rows, size, forming, dayToDate, newestDate, gapNotices } = useMemo(
     () => buildHistoricalPriceRows(points, venue, Date.now()),
     [points, venue],
   );
@@ -299,27 +303,35 @@ export function HistoricalPricesPane({ focused, width, height }: PaneProps) {
           ...(column.id === "close" ? { color: colors.textBright, attributes: TextAttributes.BOLD } : { color: colors.text }),
         };
       case "change":
-        return { text: formatMaybePrice(row.change, priceDecimals, column.width), value: exportPrice(row.change, priceDecimals), color: priceColor(row.change ?? 0) };
+        return { text: spanMark(formatMaybePrice(row.change, priceDecimals, column.width - (row.changeSpansGap ? 1 : 0)), row, row.change),
+          value: exportPrice(row.change, priceDecimals), color: priceColor(row.change ?? 0) };
       case "changePercent":
-        return { text: formatMaybePercent(row.changePercent), value: row.changePercent == null ? null : row.changePercent * 100, color: priceColor(row.changePercent ?? 0) };
+        return { text: spanMark(formatMaybePercent(row.changePercent), row, row.changePercent),
+          value: row.changePercent == null ? null : row.changePercent * 100, color: priceColor(row.changePercent ?? 0) };
       case "volume":
         return { text: formatVolume(row.point.volume, volumeMissing > 0), value: row.point.volume ?? null, color: colors.textDim };
     }
   }, [priceDecimals, volumeMissing]);
 
+  // ALL starts where the source's bars do, when that is well inside the window (BTC-USD's in 2014-09).
+  const oldestDate = rows.at(-1)?.exportDate;
+  const allStart = historyAllStart(range, size === "intraday" ? null : size, oldestDate);
+
   // The range is picked in the query bar; t still steps through it. The range
   // sets the bar size, which the footer says, and a week or month still
   // running says how far the newest bar goes.
   const barInfo = useMemo<PaneFooterSegment[]>(() => [
-    ...rows.length > 0 ? [{ id: "bars", parts: [{ text: historyBarSizeText(size), tone: "muted" as const }] }] : [],
+    ...rows.length > 0 ? [{ id: "bars", parts: [{
+      text: allStart ? `${historyBarSizeText(size)} from ${allStart}` : historyBarSizeText(size), tone: "muted" as const,
+    }] }] : [],
     ...forming && newestDate ? [{ id: "forming", parts: [{ text: formingHistoryBarText(forming, newestDate), tone: "muted" as const }] }] : [],
     ...dayToDate ? [{ id: "forming", parts: [{ text: DAY_SO_FAR_TEXT, tone: "muted" as const }] }] : [],
-  ], [dayToDate, forming, newestDate, rows.length, size]);
+  ], [allStart, dayToDate, forming, newestDate, rows.length, size]);
   usePaneStatusFooter({ registrationId: "historical-prices", loading, error, info: barInfo });
 
   usePaneNoticeFooter({
     registrationId: "historical-prices:integrity",
-    notices: [integrityNotice, volumeNotice].filter((notice): notice is string => !!notice),
+    notices: [integrityNotice, volumeNotice, ...gapNotices].filter((notice): notice is string => !!notice),
     focused,
     title: "Price history data",
   });
@@ -365,7 +377,9 @@ export function HistoricalPricesPane({ focused, width, height }: PaneProps) {
         ["Price units", "As served in the history; currency and price-basis metadata are unavailable"],
         ["Status", error ? (rows.length ? "Retained after refresh failure" : "Unavailable")
           : loading ? (rows.length ? "Refreshing" : "Loading") : rows.length ? "Available" : "Empty"],
+        ...(allStart ? [["Source starts", allStart]] : []),
         ...(integrityNotice ? [["Warning", integrityNotice]] : []),
+        ...gapNotices.map((notice) => ["Gap note", notice]),
         ...(volumeNotice ? [["Volume note", volumeNotice]] : []),
         ...(error ? [["Error", error]] : []),
       ]}

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

@@ -1,6 +1,7 @@
 import { BAR_INTERVAL_LABELS } from "../../../../cli/history-rows";
 import { periodToDateText } from "../../../../cli/pane-functions/freshness";
 import { barLastSession, barPeriodToDate, type BarPeriod, type BarPeriodToDate } from "../../../../market-data/market/bar-period";
+import { isIntradayDailyBar } from "../../../../market-data/market/period-return";
 import { barSizeFromGap, medianBarGap } from "../../../../time-series/bar-spacing";
 import type { TimeRange } from "../../../../time-series/range";
 import { CHART_RESOLUTION_STEP_MS, type ManualChartResolution } from "../../../../time-series/resolution";
@@ -76,10 +77,12 @@ export function formingHistoryBar(
 }
 
 /**
- * The day the newest weekly or monthly bar, dated `date` by the start of its
- * period, closed on once that period has ended (barLastSession): the week of
- * Mon 12 Oct 2026 is Fri 16 Oct, the day its close is from. Null while it
- * forms (formingHistoryBar dates it then), and for any other bar.
+ * The day the newest daily, weekly or monthly bar, dated `date` by the start
+ * of its period, closed on once that period has ended (barLastSession): the
+ * week of Mon 12 Oct 2026 is Fri 16 Oct, the day its close is from, and a
+ * daily bar its own day once its session has closed, as `history` dates it,
+ * never its midnight. Null while it forms (formingHistoryBar dates it then,
+ * and a daily bar by its latest quote), and for an intraday bar.
  */
 export function closedHistoryBarDay(
   size: HistoryBarSize,
@@ -87,6 +90,7 @@ export function closedHistoryBarDay(
   venue: string | undefined,
   now: number,
 ): string | null {
+  if (size === "1d") return date && !isIntradayDailyBar(date.slice(0, 10), venue, now) ? date.slice(0, 10) : null;
   const period = historyBarPeriod(size);
   return period && date && !barPeriodToDate(date, period, venue, now) ? barLastSession(date, period, venue, now) : null;
 }

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

@@ -1,10 +1,15 @@
 import { fetchHistoryResult, InvalidHistoryResultError } from "../../../../sources/history-result";
 import { historyRetentionNotice, isHistoryRetentionError } from "../../../../sources/history-retention";
 import {
+  CHART_RESOLUTION_STEP_MS,
+  DEFAULT_CHART_RESOLUTION_SUPPORT,
   getChartResolutionLabel,
+  getSupportedChartResolutionsForViewport,
+  isIntradayResolution,
   type ChartResolutionSupport,
   type ManualChartResolution,
 } from "../../../../time-series/resolution";
+import { priceWindowBarStart, type PriceWindow } from "../../../../utils/price-window";
 import type { DataProvider } from "../../../../types/data-provider";
 import type { PricePoint } from "../../../../types/financials";
 import { isRoundTheClockCoin } from "../../../../utils/crypto-pair";
@@ -14,9 +19,11 @@ import {
   endsAtLatestBar,
   latestBarTime,
   returnLookbackMs,
+  returnRowsFrom,
   returnSupportRange,
   returnVisibleFrom,
   returnWindowEnd,
+  returnWindowLookbackMs,
   type ReturnRange,
 } from "./returns-model";
 
@@ -43,6 +50,8 @@ export interface ReturnSeriesRequest {
   support: readonly ChartResolutionSupport[];
   now: number;
   forceRefresh?: boolean;
+  /** Dates in place of the range (`--from 2007 --to 2009`): every bar dated inside them. */
+  window?: PriceWindow | null;
 }
 
 function historyErrorMessage(error: unknown, resolution: ManualChartResolution): Error {
@@ -78,11 +87,12 @@ async function sessionVenue(provider: DataProvider, symbol: string, exchange: st
  * before the window, which every return is measured from.
  */
 export async function loadReturnSeries(provider: DataProvider, request: ReturnSeriesRequest): Promise<ReturnSeries> {
+  if (request.window) return loadReturnWindow(provider, request, request.window);
   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 visibleFrom = returnVisibleFrom(range, interval, windowEnd.end, venue || undefined);
   const start = new Date(visibleFrom - returnLookbackMs(range, interval, support));
   const end = new Date(now);
   const context = request.forceRefresh ? { cacheMode: "refresh" as const } : undefined;
@@ -101,9 +111,10 @@ export async function loadReturnSeries(provider: DataProvider, request: ReturnSe
   const latest = latestBarTime(result.points);
   return {
     points: result.points,
+    // A 1W to 5Y window's rows start after its base close, found among the bars by their session days.
     visibleFrom: endsAtLatestBar(range) && latest !== null && latest < windowEnd.end
-      ? returnVisibleFrom(range, interval, latest)
-      : visibleFrom,
+      ? returnVisibleFrom(range, interval, latest, venue || undefined)
+      : returnRowsFrom(result.points, range, interval, windowEnd.end, venue || undefined),
     visibleTo: now,
     ...(result.coverageStart ? { coverageStart: result.coverageStart } : {}),
     range,
@@ -112,3 +123,56 @@ export async function loadReturnSeries(provider: DataProvider, request: ReturnSe
     venue,
   };
 }
+
+/**
+ * The bars of a dated window and the one before it, in the chosen interval
+ * when the window is short enough for it and else the nearest coarser one, as
+ * a chart of those dates picks. A source that keeps no intraday bars that far
+ * back (it serves none, or says how far back it keeps them) answers in daily
+ * bars. A weekly or monthly window starts with the week or month its first
+ * date falls in, as `history` does.
+ */
+async function loadReturnWindow(provider: DataProvider, request: ReturnSeriesRequest, window: PriceWindow): Promise<ReturnSeries> {
+  const { symbol, exchange, support, now } = request;
+  const first = Date.parse(`${window.from}T00:00:00Z`);
+  const last = Date.parse(`${window.to}T23:59:59.999Z`);
+  const available = getSupportedChartResolutionsForViewport("ALL", support.length > 0 ? support : DEFAULT_CHART_RESOLUTION_SUPPORT,
+    { start: new Date(first), end: new Date(last) });
+  const step = CHART_RESOLUTION_STEP_MS[request.resolution];
+  let interval = available.includes(request.resolution) ? request.resolution
+    : available.find((candidate) => CHART_RESOLUTION_STEP_MS[candidate] >= step) ?? available.at(-1) ?? "1d";
+  const venue = await sessionVenue(provider, symbol, exchange);
+  const context = request.forceRefresh ? { cacheMode: "refresh" as const } : undefined;
+  const load = async (resolution: ManualChartResolution) => {
+    // A daily or longer bar is stamped at midnight UTC, so the window takes every bar from its first date's day, week or month on.
+    const visibleFrom = isIntradayResolution(resolution) ? first : priceWindowBarStart(window.from, resolution) - 1;
+    const result = await fetchHistoryResult(provider, symbol, exchange,
+      { kind: "detail", start: new Date(visibleFrom - returnWindowLookbackMs(resolution)), end: new Date(Math.min(last, now)), interval: resolution }, context);
+    return { result, visibleFrom };
+  };
+  let loaded: Awaited<ReturnType<typeof load>> | null = null;
+  try {
+    loaded = await load(interval);
+  } catch (error) {
+    // `1H history starts Oct 23, 2024`: a window before that is read in daily bars, which the report says it got.
+    if (!isIntradayResolution(interval) || !isHistoryRetentionError(error)) throw historyErrorMessage(error, interval);
+  }
+  if (!loaded?.result?.points.length && isIntradayResolution(interval)) {
+    interval = "1d";
+    try {
+      loaded = await load(interval);
+    } catch (error) {
+      throw historyErrorMessage(error, interval);
+    }
+  }
+  if (!loaded?.result) throw new Error("Price history unavailable");
+  return {
+    points: loaded.result.points,
+    visibleFrom: loaded.visibleFrom,
+    visibleTo: Math.min(last, now),
+    ...(loaded.result.coverageStart ? { coverageStart: loaded.result.coverageStart } : {}),
+    range: request.range,
+    resolution: interval,
+    venue,
+  };
+}