gloomberb 0.17.6 → 0.18.0

package/src/plugins/builtin/ticker-detail/overview/dividend.ts

@@ -0,0 +1,60 @@
+import { useCallback, useMemo } from "react";
+import { useAsyncResource } from "../../../../react/async-resource";
+import type { CorporateActionsData, TickerFinancials } from "../../../../types/financials";
+import { measuresTrailingYield } from "../../../../market-data/quotes/live-valuation";
+import {
+  distributionHistory,
+  forwardDividendMayHaveLapsed,
+  lapsedDividend,
+  type DividendLapse,
+} from "../../../../utils/forward-dividend";
+import { useAssetData } from "../../../runtime";
+
+/**
+ * What the overview's dividend yield reads beside the fundamentals: whether a
+ * forward yield stands, has stopped, or waits on the history that says, and
+ * the cash history a trailing yield is measured from.
+ */
+export interface OverviewDividendState {
+  /** The history is still being read; the yield is held back rather than shown and then withdrawn. */
+  pending: boolean;
+  lapse: DividendLapse | null;
+  /**
+   * The listing's cash history, for a trailing yield (listingDividendYield).
+   * Null while it is read and when it cannot be, which leaves Gloom Cloud's
+   * yield: a trailing yield is never withdrawn, so it is not held back.
+   */
+  actions?: CorporateActionsData | null;
+}
+
+const CURRENT: OverviewDividendState = { pending: false, lapse: null };
+
+/**
+ * The listing's distribution history as the overview's dividend yield reads
+ * it. A trailing yield is measured from it as DVD measures it. A forward
+ * yield's stopped dividend (lapsedDividend) is read from it only once its
+ * ex-date is far enough past for the dividend to have stopped; without a
+ * history, Gloom Cloud's fifteen months decide on the ex-date alone.
+ */
+export function useOverviewDividend(
+  symbol: string | null,
+  exchange: string,
+  fundamentals: TickerFinancials["fundamentals"] | undefined,
+): OverviewDividendState {
+  const dataProvider = useAssetData();
+  const forward = fundamentals?.dividendYieldBasis === "forward" && fundamentals.dividendYield != null;
+  const trailing = measuresTrailingYield(fundamentals);
+  const asOf = fundamentals?.exDividendDate;
+  const readsHistory = !!symbol && !!dataProvider?.getCorporateActions && (trailing || (forward && forwardDividendMayHaveLapsed(asOf)));
+  const loader = useCallback(() => dataProvider!.getCorporateActions!(symbol!, exchange), [dataProvider, exchange, symbol]);
+  const cached = useMemo(() => readsHistory
+    ? dataProvider?.getCachedQuery?.("getCorporateActions", [symbol!, exchange]).getSnapshot().result?.value ?? null
+    : null, [dataProvider, exchange, readsHistory, symbol]);
+  const resource = useAsyncResource(readsHistory ? loader : null, { initialData: () => cached });
+  const actions = readsHistory ? resource.data ?? cached : null;
+  if (trailing) return { pending: false, lapse: null, actions };
+  if (!forward) return CURRENT;
+  if (!readsHistory) return { pending: false, lapse: lapsedDividend(asOf, null) };
+  if (!actions && resource.loading) return { pending: true, lapse: null };
+  return { pending: false, lapse: lapsedDividend(asOf, distributionHistory(actions)) };
+}

package/src/plugins/builtin/ticker-detail/overview/model.ts

@@ -18,14 +18,19 @@ import {
   formatMarketQuantity,
   withCurrencyMinorDigits,
 } from "../../../../market-data/market/format";
+import { reportedQuoteVolume } from "../../../../market-data/market/index-level";
 import type { OverviewFunctionLink, PositionTableRow, StatField } from "./types";
+import type { OverviewDividendState } from "./dividend";
+import { NO_CURRENT_DIVIDEND } from "../../../../utils/forward-dividend";
 import { getPortfolioPositionMetrics, getPortfolioQuoteDisplay, resolvePortfolioMarketValue, resolvePortfolioPositionPnl, portfolioPnlPercent, signedPositionDirection } from "../../../../portfolio/position-metrics";
-import { liveDividendYield, liveForwardPE, liveMarketCapitalization, liveTrailingPE } from "../../../../market-data/quotes/live-valuation";
+import { listingDividendYield, liveForwardPE, liveMarketCapitalization, liveTrailingPE } from "../../../../market-data/quotes/live-valuation";
 import { atRegularSessionPrice } from "../../../../market-data/quotes/regular-session-valuation";
 import { formatReportedMoney } from "../../../../utils/reported-money";
 import { enterpriseValueCheck, fundamentalsCurrency, fundamentalsEpsCurrency, reportedEnterpriseValue } from "../../../../utils/fundamentals";
 import { formatShortDate } from "../../../../utils/datetime-format";
 import { safeExternalUrl } from "../../../../utils/external-url";
+import type { FundBondFacts } from "../../../../api-client/fund-facts";
+import { bondFigures } from "../../../../market-data/bond-funds";
 
 type CurrencyConverter = (value: number, fromCurrency: string) => number;
 
@@ -34,6 +39,10 @@ const HOLDERS: OverviewFunctionLink = { name: "Holders", tabId: "holders", templ
 const SHORT_INTEREST: OverviewFunctionLink = { name: "Short Interest", tabId: "short-interest", templateId: "short-interest-pane" };
 const EARNINGS: OverviewFunctionLink = { name: "Earnings", templateId: "earnings-calendar-pane" };
 const DIVIDENDS: OverviewFunctionLink = { name: "Dividends", tabId: "dividend-yield", templateId: "dividend-yield-pane" };
+const FUND_FACTS: OverviewFunctionLink = { name: "Fund Facts", templateId: "sec-etf-pane" };
+
+/** A bond fund's sponsor figures in a narrow grid: `SEC Yield 4.04% 2026-10-15`. */
+const BOND_STAT_LABELS = { secYield: "SEC Yield", yieldToWorst: "Yld to Worst" } as const;
 
 const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"] as const;
 const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
@@ -77,6 +86,8 @@ export function buildOverviewStats({
   nextEarnings,
   depositaryReceipt = false,
   today,
+  dividend,
+  bond = null,
 }: {
   quote: Quote | undefined;
   fundamentals: TickerFinancials["fundamentals"] | undefined;
@@ -91,13 +102,22 @@ export function buildOverviewStats({
   depositaryReceipt?: boolean;
   /** The listing's calendar day, YYYY-MM-DD; dates before it are left out. */
   today?: string;
+  /** The history the dividend yield reads (useOverviewDividend): a trailing one is measured from its cash, a forward one stops with it; without it the yield stands. */
+  dividend?: OverviewDividendState;
+  /**
+   * A bond fund's SEC yield, yield to worst and duration: its yield is then a
+   * distribution yield, not its SEC yield, which follows it with its date.
+   */
+  bond?: FundBondFacts | null;
 }): StatField[] {
   const stats: StatField[] = [];
   const money = (value: number, perShare = false) => formatReportedMoney(value, fundamentalsCurrency({ fundamentals, financialCurrency }), perShare);
 
-  if (quote?.volume != null) {
+  // An index's 0 is volume nobody counts, not a quiet session: no Volume row.
+  const volume = reportedQuoteVolume(quote);
+  if (volume != null) {
     // Live figures keep their decimals (12.30M, not 12.3M) so the digits hold still.
-    stats.push({ label: "Volume", value: formatCompact(quote.volume, { fixedDecimals: true }) });
+    stats.push({ label: "Volume", value: formatCompact(volume, { fixedDecimals: true }) });
   }
   // Price-derived statistics follow the quote; see live-valuation for when a stored figure is kept.
   const capitalization = liveMarketCapitalization(quote, fundamentals);
@@ -146,16 +166,33 @@ export function buildOverviewStats({
       link: EARNINGS,
     });
   }
-  const dividendYield = liveDividendYield(quote, fundamentals);
-  if (fundamentals && dividendYield != null) {
-    const label = fundamentals.dividendYieldBasis === "forward" ? "Fwd Div Yld" : fundamentals.dividendYieldBasis === "trailing" ? "TTM Div Yld" : "Div Yield";
-    stats.push({ label, value: formatLevelPercent(dividendYield) });
+  // A trailing yield as DVD measures it from the cash history, once that is read.
+  const dividendYield = listingDividendYield(quote, fundamentals, dividend?.actions);
+  // A dividend that stopped has no forward yield, and its last ex-date is when it was last paid.
+  const lapse = dividend?.lapse ?? null;
+  // A bond fund pays distributions, and its yield on them is not the SEC yield after it.
+  const kind = bond ? "Dist" : "Div";
+  const notSec = bond ? { detail: ["not SEC yield", "not SEC"] } : {};
+  if (fundamentals && lapse) {
+    stats.push({ label: `Fwd ${kind} Yld`, value: NO_CURRENT_DIVIDEND });
+  } else if (fundamentals && dividendYield != null && !dividend?.pending) {
+    const basis = fundamentals.dividendYieldBasis;
+    const label = basis === "forward" ? `Fwd ${kind} Yld` : basis === "trailing" ? `TTM ${kind} Yld` : `${kind} Yield`;
+    stats.push({ label, value: formatLevelPercent(dividendYield), ...notSec });
+  }
+  if (bond) {
+    // Each dated, as the sponsor publishes it; the narrowest column drops the year.
+    for (const figure of bondFigures(bond)) {
+      const label = figure.key === "duration" ? (bond.duration?.measure === "average" ? "Avg Duration" : "Eff Duration") : BOND_STAT_LABELS[figure.key];
+      const forms = figure.date ? [...new Set([figure.date, figure.date.replace(/\b\d{4}-(\d{2}-\d{2})\b/, "$1")])] : undefined;
+      stats.push({ label, value: figure.text, ...(forms ? { detail: forms } : {}), link: FUND_FACTS });
+    }
   }
-  const exDividendDate = fundamentals?.exDividendDate;
+  const exDividendDate = lapse?.lastPaid ?? fundamentals?.exDividendDate;
   if (exDividendDate && ISO_DATE.test(exDividendDate)) {
     const days = today ? daysUntil(exDividendDate, today) : -1;
     stats.push({
-      label: "Ex-Dividend",
+      label: lapse ? "Last Paid" : "Ex-Dividend",
       value: calendarDate(exDividendDate, today ?? exDividendDate),
       detail: days >= 0 ? daysAhead(days) : undefined,
       link: DIVIDENDS,

package/src/plugins/builtin/ticker-detail/overview/pane.tsx

@@ -12,6 +12,7 @@ import { getTickerResearchPaneSettings } from "../settings";
 import { OverviewTab } from "../overview-tab";
 import { useOpenResearchTab } from "../research-tab-navigation";
 import type { OverviewFunctionLink } from "./types";
+import { useOverviewDividend } from "./dividend";
 
 /** Registered by the chart composer, in the same plugin as this tab. */
 const CHART_TAB_ID = "chart";
@@ -23,6 +24,7 @@ export function OverviewResearchTab({ width, height, focused }: TickerResearchTa
   const paneInstance = usePaneInstance();
   const openResearchTab = useOpenResearchTab();
   const { createPaneFromTemplate } = usePluginAppActions();
+  const dividend = useOverviewDividend(ticker?.metadata.ticker ?? null, ticker?.metadata.exchange ?? "", financials?.fundamentals);
   // A pane locked to one tab has nowhere to go.
   const lockedToOneTab = getTickerResearchPaneSettings(paneInstance?.settings).hideTabs;
   const openChart = useCallback(() => {
@@ -43,6 +45,7 @@ export function OverviewResearchTab({ width, height, focused }: TickerResearchTa
       financials={financials}
       onOpenChart={paneId && !lockedToOneTab ? openChart : undefined}
       onOpenFunction={openFunction}
+      dividend={dividend}
       perpetuals={ticker ? <PerpEquityRow symbol={ticker.metadata.ticker} exchange={ticker.metadata.exchange} instrumentType={financials?.quote?.instrumentType ?? ticker.metadata.assetCategory} /> : undefined}
     />
   );

package/src/plugins/builtin/ticker-detail/overview-tab.tsx

@@ -1,4 +1,8 @@
 import { TrendingSummary } from "../attention/trending";
+import { fundFactOverviewFields } from "../sec/fund-facts";
+import { useFundFacts } from "../sec/fund-facts-view";
+import { resolveTickerInstrumentKind } from "../../../tickers/instrument-kind";
+import { mayBeUsEquityOrFundTicker } from "../../../utils/sec";
 import type { ReactNode } from "react";
 import { EmptyState, PaneLinkMenu, SectionHeading, usePaneNoticeFooter } from "../../../components";
 import { CompositeChart, pricePointsToResolvedSeries } from "../../../components/chart/composite";
@@ -8,6 +12,7 @@ import { PriceReturnStrip } from "../../../components/price-performance";
 import { t } from "../../../i18n";
 import { useFxRatesMap } from "../../../market-data/hooks";
 import { formatMarketPriceWithCurrency, formatSignedMarketPrice, liveQuoteFormatOptions } from "../../../market-data/market/format";
+import { priceSeriesUnit } from "../../../market-data/market/index-level";
 import {
   exchangeShortName,
   extendedSessionLineLabel,
@@ -41,6 +46,7 @@ import {
   textGridColumns,
 } from "./overview/components";
 import { useFuturesContractTerms } from "./overview/futures-contract";
+import type { OverviewDividendState } from "./overview/dividend";
 import { buildOverviewStats, buildPositionRows, buildProfileFields } from "./overview/model";
 import type { OverviewFunctionLink, StatField } from "./overview/types";
 import { describeFundamentalMarketCap } from "../../../utils/market-capitalization";
@@ -80,6 +86,8 @@ interface OverviewTabProps {
   onOpenChart?: () => void;
   /** A click on a figure opens its research function (beta to GR, holders to HDS). */
   onOpenFunction?: (link: OverviewFunctionLink) => void;
+  /** The history the dividend yield reads (useOverviewDividend): a trailing one's cash, a forward one's lapse; without it the yield stands. */
+  dividend?: OverviewDividendState;
 }
 
 export function OverviewTab(props: OverviewTabProps) {
@@ -87,7 +95,10 @@ export function OverviewTab(props: OverviewTabProps) {
   return <ResolvedOverviewTab {...props} ticker={props.ticker} />;
 }
 
-function ResolvedOverviewTab({ width, height, focused = false, ticker, financials, onOpenChart, onOpenFunction, perpetuals }: OverviewTabProps & { ticker: TickerRecord }) {
+/** Where a fund's facts open: the ETF function, its facts over its filings. */
+const FUND_FACTS_LINK: OverviewFunctionLink = { name: "Fund Facts", templateId: "sec-etf-pane" };
+
+function ResolvedOverviewTab({ width, height, focused = false, ticker, financials, onOpenChart, onOpenFunction, perpetuals, dividend }: OverviewTabProps & { ticker: TickerRecord }) {
   const baseCurrency = useAppSelector((state) => state.config.baseCurrency);
   const { width: termWidth } = useViewport();
   const { fractionalViewport = false, nativePaneChrome, cellWidthPx = 8, cellHeightPx = 18, pixelRatio = 1 } = useUiCapabilities();
@@ -125,6 +136,14 @@ function ResolvedOverviewTab({ width, height, focused = false, ticker, financial
     routingVenue && routingVenue !== listingVenue ? `route ${routingVenue}` : "",
   ].filter((part) => part.length > 0);
 
+  // A US-listed fund's facts (fee, NAV, premium, net assets) stand where a company's fundamentals would; each opens ETF.
+  const fundFactsSymbol = resolveTickerInstrumentKind(ticker, financials) === "fund" && mayBeUsEquityOrFundTicker(ticker) ? ticker.metadata.ticker : null;
+  const fundFacts = useFundFacts(fundFactsSymbol).data?.payload;
+  // Each figure dated; one older than it looks takes the warning colour, as in ETF.
+  const fundFactFields: StatField[] = fundFacts?.covered
+    ? fundFactOverviewFields(fundFacts).map(({ warn, ...field }) => ({ ...field, ...(warn ? { valueColor: colors.warning } : {}), link: FUND_FACTS_LINK }))
+    : [];
+
   const contentWidth = Math.max((width || Math.floor(termWidth * 0.5)) - (fractionalViewport ? 2 : 4), 20);
   const chartWidth = contentWidth;
   const hasHistory = (financials?.priceHistory?.length ?? 0) > 2;
@@ -139,7 +158,8 @@ function ResolvedOverviewTab({ width, height, focused = false, ticker, financial
     id: `${ticker.metadata.ticker}:price`,
     label: `${ticker.metadata.ticker} Price`,
     color: priceColor(chartDelta),
-    unit: unknownHistoryBasis ? "unknown" : quoteCurrency,
+    // An index's axis reads in points: ^VIX at 20, never $20.
+    unit: unknownHistoryBasis ? "unknown" : priceSeriesUnit(quoteCurrency, instrumentType),
     style: "area",
     axis: "right",
     panelId: "price",
@@ -236,6 +256,8 @@ function ResolvedOverviewTab({ width, height, focused = false, ticker, financial
     depositaryReceipt: sharesOutstandingInReceipts(quote, fundamentals, description),
     // Report and ex-dividend dates are the listing's calendar days.
     today: zonedDateKey(Date.now(), chartTimeZone ?? "America/New_York"),
+    dividend,
+    bond: fundFacts?.bond ?? null,
   });
   const profileFields = buildProfileFields({
     instrumentType: instrumentTypeLabel(instrumentType, quote?.name || ticker.metadata.name),
@@ -355,7 +377,7 @@ function ResolvedOverviewTab({ width, height, focused = false, ticker, financial
         {perpetuals && <PaneLinkMenu>{perpetuals}</PaneLinkMenu>}
 
         {(hasDayRange || yearRange) && quote && (
-          <Box flexDirection={rangeInline ? "row" : "column"} gap={rangeInline ? RANGE_PAIR_GAP : 0} width={contentWidth}>
+          <Box flexDirection={rangeInline ? "row" : "column"} gap={rangeInline ? RANGE_PAIR_GAP : 0} width={nativePaneChrome ? undefined : contentWidth}>
             {hasDayRange && (
               <CompactRangeBar
                 current={sessionQuote?.price ?? quote.price}
@@ -366,6 +388,7 @@ function ResolvedOverviewTab({ width, height, focused = false, ticker, financial
                 labelWidth={rangeLabelWidth}
                 endpointWidth={rangeEndpointCells}
                 width={rangeWidth}
+                grow={rangeInline}
                 currency={quoteCurrency}
                 priceOptions={moneyOptions}
               />
@@ -380,6 +403,7 @@ function ResolvedOverviewTab({ width, height, focused = false, ticker, financial
                 labelWidth={rangeLabelWidth}
                 endpointWidth={rangeEndpointCells}
                 width={rangeWidth}
+                grow={rangeInline}
                 currency={quoteCurrency}
                 priceOptions={moneyOptions}
               />
@@ -426,6 +450,15 @@ function ResolvedOverviewTab({ width, height, focused = false, ticker, financial
           </Box>
         )}
 
+        {fundFactFields.length > 0 && (
+          <Box flexDirection="column">
+            <SectionHeading title={t("Fund Facts")} />
+            <PaneLinkMenu>
+              <FundamentalsGrid fields={fundFactFields} width={contentWidth} onOpenLink={onOpenFunction} />
+            </PaneLinkMenu>
+          </Box>
+        )}
+
         {stats.length > 0 && (
           <Box flexDirection="column">
             <SectionHeading title={t("Fundamentals")} />

package/src/plugins/builtin/ticker-detail/quote-monitor/card.tsx

@@ -59,7 +59,7 @@ function extendedLineParts(
   return candidates.find(({ label, figures }) => fits(`${label} ${figures}`)) ?? null;
 }
 
-const DESKTOP_DETAIL_TEXT_STYLE = { fontSize: "12px", lineHeight: "14px", whiteSpace: "nowrap" };
+const DESKTOP_DETAIL_TEXT_STYLE = { fontSize: "var(--gloom-type-ui)", lineHeight: "14px", whiteSpace: "nowrap" };
 
 function ExtendedSessionLine({
   parts,
@@ -203,9 +203,10 @@ export function QuoteMonitorCard({
     || height >= (stacked ? 3 : 2) + statusRows + terminalSparklineHeight;
   // Figures sit over the sparkline, so the desktop rings them in the card colour.
   const figureHalo = { textShadow: `0 1px 2px ${colors.bg}` };
+  // The card's title: a heading over the app's 12px name, under the 20px price.
   const desktopSymbolStyle = nativePaneChrome
     ? {
-        fontSize: "15px",
+        fontSize: "var(--gloom-type-heading)",
         lineHeight: "18px",
       }
     : undefined;
@@ -237,12 +238,10 @@ export function QuoteMonitorCard({
         position: "relative",
         width: "100%",
         height: "100%",
-        paddingLeft: 10,
-        paddingRight: 10,
-        paddingTop: 6,
-        paddingBottom: 4,
-        borderRight: showRightDivider ? `1px solid ${colors.border}` : undefined,
-        borderBottom: showBottomDivider ? `1px solid ${colors.border}` : undefined,
+        padding: "var(--gloom-space-xs) var(--gloom-inset)",
+        // The rules between the board's cards are the app's hairline.
+        borderRight: showRightDivider ? "1px solid var(--gloom-hairline)" : undefined,
+        borderBottom: showBottomDivider ? "1px solid var(--gloom-hairline)" : undefined,
         outline: selected ? `1px solid ${colors.borderFocused}` : undefined,
         outlineOffset: selected ? -1 : undefined,
       } : undefined}
@@ -267,7 +266,7 @@ export function QuoteMonitorCard({
             // The name gives way first; the price keeps its natural width.
             gridTemplateColumns: "minmax(0, 1fr) auto",
             gridTemplateRows: "auto 1fr auto auto",
-            columnGap: 12,
+            columnGap: "var(--gloom-space-md)",
             width: "100%",
             height: "100%",
           }}
@@ -286,7 +285,7 @@ export function QuoteMonitorCard({
               {symbol}
             </Text>
             {quoteFailed && (
-              <Text fg={colors.negative} style={{ fontSize: "12px", lineHeight: "14px" }}>
+              <Text fg={colors.negative} style={{ fontSize: "var(--gloom-type-ui)", lineHeight: "14px" }}>
                 {quoteStatus.text}
               </Text>
             )}
@@ -294,7 +293,7 @@ export function QuoteMonitorCard({
               <Text
                 fg={colors.textDim}
                 style={{
-                  fontSize: "12px",
+                  fontSize: "var(--gloom-type-ui)",
                   lineHeight: "14px",
                   maxWidth: "100%",
                   overflow: "hidden",
@@ -306,7 +305,7 @@ export function QuoteMonitorCard({
               </Text>
             )}
             {navAsOf && (
-              <Text fg={colors.textDim} style={{ fontSize: "12px", lineHeight: "14px" }}>
+              <Text fg={colors.textDim} style={{ fontSize: "var(--gloom-type-ui)", lineHeight: "14px" }}>
                 {navAsOf}
               </Text>
             )}
@@ -320,9 +319,9 @@ export function QuoteMonitorCard({
               gridRow: "1",
               justifySelf: "end",
               backgroundColor: colors.bg,
-              borderRadius: 4,
+              borderRadius: "var(--gloom-radius-sm)",
               boxShadow: `0 0 0 2px ${colors.bg}`,
-              paddingLeft: 6,
+              paddingLeft: "var(--gloom-space-xs)",
               paddingBottom: 1,
             }}
           >
@@ -361,10 +360,10 @@ export function QuoteMonitorCard({
                 gridRow: "3",
                 justifySelf: "end",
                 alignSelf: "end",
-                fontSize: "11px",
-                lineHeight: "13px",
+                fontSize: "var(--gloom-type-ui)",
+                lineHeight: "14px",
                 backgroundColor: colors.bg,
-                paddingLeft: 6,
+                paddingLeft: "var(--gloom-space-xs)",
                 paddingRight: 2,
                 boxShadow: `0 0 0 2px ${colors.bg}`,
               }}
@@ -410,7 +409,7 @@ export function QuoteMonitorCard({
                   <Text
                     fg={colors.textDim}
                     style={{
-                      fontSize: "12px",
+                      fontSize: "var(--gloom-type-ui)",
                       lineHeight: "16px",
                       overflow: "hidden",
                       textOverflow: "ellipsis",
@@ -449,7 +448,7 @@ export function QuoteMonitorCard({
               area={!nativePaneChrome}
             />
             {nativePaneChrome && rangeLabel && (
-              <Text fg={colors.textDim} style={{ fontSize: "11px", lineHeight: "14px" }}>
+              <Text fg={colors.textDim} style={{ fontSize: "var(--gloom-type-ui)", lineHeight: "14px" }}>
                 {rangeLabel}
               </Text>
             )}

package/src/plugins/builtin/time-sales/client.ts

@@ -1,6 +1,6 @@
 import { apiClient } from "../../../api-client";
 import { ApiRequestError } from "../../../api-client/errors";
-import type { TapeSnapshot } from "../../../api-client/tape";
+import type { TapeRange, TapeSnapshot } from "../../../api-client/tape";
 import { canonicalExchange, normalizeSymbol } from "../../../utils/exchanges";
 import { tapeTimeKey, tradeKey } from "./model";
 
@@ -25,7 +25,9 @@ export function validateTape(data: TapeSnapshot, symbol: string, exchange: strin
     || data.feed !== (data.access === "realtime" ? "sip" : "delayed_sip") || data.delaySeconds !== (data.access === "realtime" ? 0 : 900)
     || !data.capacity || !count(data.capacity.trades) || data.capacity.trades > 1000 || !count(data.capacity.quotes) || data.capacity.quotes > 500
     || !Array.isArray(data.trades) || data.trades.length > data.capacity.trades || !Array.isArray(data.quotes) || data.quotes.length > data.capacity.quotes
-    || !data.dropped || !count(data.dropped.trades) || !count(data.dropped.quotes) || !count(data.corrections) || !count(data.cancels)) {
+    || !data.dropped || !count(data.dropped.trades) || !count(data.dropped.quotes) || !count(data.corrections) || !count(data.cancels)
+    || data.window !== undefined && (!data.window || !timestamp(data.window.from) || !timestamp(data.window.to) || !data.window.truncated
+      || typeof data.window.truncated.trades !== "boolean" || typeof data.window.truncated.quotes !== "boolean")) {
     throw new Error("The server returned an invalid tape snapshot");
   }
   const cutoffDate = new Date(Date.parse(data.generatedAt) - data.delaySeconds * 1000).toISOString();
@@ -56,9 +58,10 @@ export function validateTape(data: TapeSnapshot, symbol: string, exchange: strin
   return { ...data, source: "Gloom Cloud", trades: [...data.trades].sort((a, b) => tapeTimeKey(a.timestamp).localeCompare(tapeTimeKey(b.timestamp))),
     quotes: [...data.quotes].sort((a, b) => tapeTimeKey(a.timestamp).localeCompare(tapeTimeKey(b.timestamp))) };
 }
+/** The latest tape, or with a `range` that window of the session. */
 export async function fetchTape(symbol: string, exchange: string, signal?: AbortSignal,
-  client: Pick<typeof apiClient, "getCloudTape"> = apiClient): Promise<TapeSnapshot> {
-  try { return validateTape(await client.getCloudTape(symbol, exchange, signal), symbol, exchange); }
+  client: Pick<typeof apiClient, "getCloudTape"> = apiClient, range?: TapeRange): Promise<TapeSnapshot> {
+  try { return validateTape(await (range ? client.getCloudTape(symbol, exchange, signal, range) : client.getCloudTape(symbol, exchange, signal)), symbol, exchange); }
   catch (error) {
     if (error instanceof ApiRequestError && [404, 503].includes(error.status ?? 0)) throw new Error("Time and sales is not available yet.");
     // A rejected request answers with an unavailable snapshot; show its reason, not the JSON body.

package/src/plugins/builtin/time-sales/headless.ts

@@ -1,13 +1,14 @@
-import type { HeadlessPaneColumn, HeadlessPaneDefinition, HeadlessPaneRow } from "../../../types/plugin";
-import { subMinuteDataMessage } from "../../../cli/known-gaps";
-import { listingSuffixExchange } from "../../../sources/listing-symbols";
-import { parsePublicTickerKey } from "../../../utils/exchanges";
-import { listingAbroadVenue } from "../../../utils/sec";
+import type { HeadlessPaneColumn, HeadlessPaneContext, HeadlessPaneDefinition, HeadlessPaneRow } from "../../../types/plugin";
+import { listedAbroad, subMinuteDataMessage } from "../../../cli/known-gaps";
+import type { TapeRange, TapeSnapshot } from "../../../api-client/tape";
 import { fetchTape } from "./client";
-import { newestFirst, quoteSpread, tapePrice, tapePriceDigits, tapeStatistics } from "./model";
+import { newestFirst, quoteSpread, tapePrice, tapePriceDigits, tapeStatistics, tapeTimeKey } from "./model";
+import { REPORT_ROWS } from "../shared/headless-options";
+import { inTapeRange, normalizeTapeClock, parseTapeClock, servedWindow, sessionDay, tapeMoment, tapeWindowRange } from "./window";
 
 type Format = NonNullable<HeadlessPaneColumn["format"]>;
 const fixedPrice = (digits: number): Format => (value) => tapePrice(typeof value === "number" ? value : null, digits);
+const whole: Format = (value) => typeof value === "number" && Number.isFinite(value) ? value.toFixed(0) : "--";
 const bps: Format = (value) => typeof value === "number" && Number.isFinite(value) ? value.toFixed(2) : "--";
 
 /** Every row key in order, with the pane's rounding where the report would otherwise print raw floats. */
@@ -16,22 +17,62 @@ function formattedColumns(rows: readonly HeadlessPaneRow[], formats: Record<stri
     .map((key) => ({ key, header: key, ...(formats[key] ? { format: formats[key] } : {}) }));
 }
 
+function oldestFirst<T extends { timestamp: string }>(rows: readonly T[]): T[] {
+  return [...rows].sort((a, b) => tapeTimeKey(a.timestamp).localeCompare(tapeTimeKey(b.timestamp)));
+}
+
+/** When `--limit` cuts a window's trades: how many of them are listed. */
+function listedNote(range: TapeRange, served: number, listed: number): string[] {
+  return listed < served ? [`Listing the first ${listed} of the ${served} trades from ${tapeMoment(Date.parse(range.from))}; --limit takes up to 1000.`] : [];
+}
+
+
+const WINDOW_OPTION = { reportOnly: "lists a window of the session in the text report" };
+
 /**
- * Whether a listing trades abroad, by its key, its saved exchange or its
- * listing suffix (RMS.AX is the ASX): the SIP tape carries US listings only,
- * so it has nothing for one, and its bare symbol can be another company there.
+ * The window `--from`/`--to` ask for, read against the session the latest tape
+ * serves, then fetched as that window. A server that predates windows answers
+ * with its latest tape: its prints that fall in the window stand, and a note
+ * says from when that tape runs.
  */
-function listedAbroad(key: string, exchange: string | undefined): boolean {
-  const parsed = parsePublicTickerKey(key);
-  const venue = parsed.exchange || exchange || listingSuffixExchange(parsed.symbol);
-  return !!venue && listingAbroadVenue(`${parsed.symbol}:${venue}`) != null;
+async function loadWindow(symbol: string, exchange: string, from: string, to: string, ctx: HeadlessPaneContext) {
+  const latest = await fetchTape(symbol, exchange, ctx.signal, ctx.apiClient);
+  const served = servedWindow(latest);
+  if (!served) throw new Error(`TAS has no session for ${symbol} to read a window of; run it without --from and --to for the latest prints.`);
+  const range = tapeWindowRange(served, from ? parseTapeClock(from) : null, to ? parseTapeClock(to) : null);
+  const data = await fetchTape(symbol, exchange, ctx.signal, ctx.apiClient, range);
+  const notes = [`Window: ${sessionDay(served.date)}, ${tapeMoment(Date.parse(range.from))} to ${tapeMoment(Date.parse(range.to))}.`];
+  if (data.window) {
+    if (data.window.truncated.trades) {
+      const last = data.trades.at(-1)?.timestamp;
+      notes.push(`The window holds more than ${data.capacity.trades} trades: these are the first${last ? `, through ${tapeMoment(Date.parse(last))}` : ""}; start --from there to read on.`);
+    }
+    return { data, range, notes };
+  }
+  const trades = data.trades.filter((row) => inTapeRange(row.timestamp, range)), quotes = data.quotes.filter((row) => inTapeRange(row.timestamp, range));
+  // Dated by what it lists, as a served window is.
+  const times = oldestFirst([...trades, ...quotes]).map((row) => row.timestamp);
+  const kept = { ...data, trades, quotes, asOf: times.at(-1) ?? null, observedFrom: times[0] ?? null };
+  if (data.observedFrom && tapeTimeKey(data.observedFrom) > tapeTimeKey(range.from)) {
+    notes.push(`This server serves only its latest tape, from ${tapeMoment(Date.parse(data.observedFrom))}: prints before it are not listed.`);
+  }
+  return { data: kept, range, notes };
 }
 
 export const timeSalesHeadless: HeadlessPaneDefinition<"bundle"> = {
   shape: "bundle", argument: { kind: "ticker", placeholder: "ticker", description: "US equity ticker." },
   usListingsOnly: "Time and sales",
-  usListingsOnlyHint: subMinuteDataMessage,
-  options: [{ key: "limit", type: "integer", minimum: 1, maximum: 1000, defaultValue: 100, description: "Maximum recent prints in the report." }],
+  usListingsOnlyHint: (symbol) => subMinuteDataMessage(symbol, "abroad"),
+  options: [
+    { key: "limit", shot: REPORT_ROWS, type: "integer", minimum: 1, maximum: 1000, defaultValue: 100, description: "Maximum recent prints in the report." },
+    { key: "from", shot: WINDOW_OPTION, type: "string", defaultValue: "", placeholder: "time", example: "--from 10:30 --to 10:35",
+      description: "Start of a window of the served session, as a time of day: 10:30 or 10:30:15 on New York's clock, 14:30Z on UTC's."
+        + " The report then lists that window's prints oldest first; without --to it runs to the end of what is served.",
+      normalize: normalizeTapeClock },
+    { key: "to", shot: WINDOW_OPTION, type: "string", defaultValue: "", placeholder: "time",
+      description: "End of the window, as --from takes it; without --from the window starts at 04:00 New York time.",
+      normalize: normalizeTapeClock },
+  ],
   discovery: { aliases: ["TAS", "QR"], dataRequirements: ["Gloom Cloud SIP trade and quote feed"],
     limitations: ["Bounded observed window, not a complete session.", "SIP is delayed fifteen minutes without realtime entitlement.", "Quote sizes are round lots.", "No Level 2 or inferred aggressor side."] },
   describe: (args) => `Time and sales ${args.argument ?? ""}`,
@@ -41,28 +82,36 @@ export const timeSalesHeadless: HeadlessPaneDefinition<"bundle"> = {
     if (listedAbroad(symbol, instrument?.exchange)) {
       // Say why the table is empty and where the finest bars for it are, rather than the tape's bare "unavailable".
       return { complete: false, sections: [
-        { title: ctx.settings?.tab === "quotes" ? "NBBO" : "Trades", rows: [], empty: subMinuteDataMessage(symbol) },
+        { title: ctx.settings?.tab === "quotes" ? "NBBO" : "Trades", rows: [], empty: subMinuteDataMessage(symbol, "abroad") },
       ] };
     }
-    const data = await fetchTape(symbol, instrument?.exchange ?? "", ctx.signal, ctx.apiClient);
+    const exchange = instrument?.exchange ?? "";
+    const from = String(args.options.from ?? "").trim(), to = String(args.options.to ?? "").trim();
+    const windowed = from || to ? await loadWindow(symbol, exchange, from, to, ctx) : null;
+    const data: TapeSnapshot = windowed?.data ?? await fetchTape(symbol, exchange, ctx.signal, ctx.apiClient);
+    const limit = Number(args.options.limit ?? 100);
     const statistics = tapeStatistics(data);
     const window = [{ from: statistics.from, asOf: statistics.asOf, prints: statistics.count, shares: statistics.volume,
       vwap: statistics.vwap, low: statistics.low, high: statistics.high, pricePercentile: statistics.pricePercentile }];
-    const quotes = newestFirst(data.quotes).slice(0, Number(args.options.limit ?? 100)).map((row) => ({ ...row, ...quoteSpread(row), conditions: row.conditions.join(" ") }));
+    // A window reads forward from its start; the latest tape newest first, as the pane lists it.
+    const ordered = <T extends { timestamp: string }>(rows: readonly T[]) => windowed ? oldestFirst(rows) : newestFirst(rows);
+    const quotes = ordered(data.quotes).slice(0, limit).map((row) => ({ ...row, ...quoteSpread(row), conditions: row.conditions.join(" ") }));
     // One decimal count per column, as the pane shows it, so sub-penny prints align.
     const price = fixedPrice(tapePriceDigits(data.trades.map((row) => row.price)));
-    const trades = newestFirst(data.trades).slice(0, Number(args.options.limit ?? 100)).map((row) => ({ ...row, conditions: row.conditions.join(" ") }));
+    const trades = ordered(data.trades).slice(0, limit).map((row) => ({ ...row, conditions: row.conditions.join(" ") }));
+    const notes = windowed ? [...windowed.notes, ...listedNote(windowed.range, data.trades.length, trades.length)] : [];
     // SIP prints, real-time or fifteen minutes delayed by entitlement, dated by the newest print.
     const freshness = data.feed === "sip"
       ? { status: "live" as const, cadence: "daily" as const }
       : { status: "delayed" as const, delayMinutes: Math.round(data.delaySeconds / 60), cadence: "daily" as const };
-    return { freshness, sections: [
-      { title: "Observed window", columns: formattedColumns(window, { vwap: price, low: price, high: price }), rows: window },
+    return { freshness, ...(notes.length ? { notes } : {}), sections: [
+      // The last price's rank among the window's prints, whole, as the pane shows it.
+      { title: windowed ? "Window" : "Observed window", columns: formattedColumns(window, { vwap: price, low: price, high: price, pricePercentile: whole }), rows: window },
       { title: "Regular session", columns: formattedColumns([data.session], { high: price, low: price }), rows: [data.session] },
       { title: "Trades", columns: formattedColumns(trades, { price }), rows: trades },
       { title: "NBBO", columns: formattedColumns(quotes, { bps }), rows: quotes },
     ], errors: data.gaps, metadata: { source: data.source, feed: data.feed, delaySeconds: data.delaySeconds,
-      asOf: data.asOf, observedFrom: data.observedFrom, generatedAt: data.generatedAt, status: data.status,
+      asOf: data.asOf, observedFrom: data.observedFrom, generatedAt: data.generatedAt, status: data.status, ...(windowed ? { window: windowed.range } : {}),
       complete: data.status === "available", capacity: data.capacity, dropped: data.dropped, corrections: data.corrections, cancels: data.cancels, connected: data.connected } };
   },
 };

package/src/plugins/builtin/time-sales/model.ts

@@ -36,6 +36,18 @@ export const quoteKey = (row: TapeQuote) => JSON.stringify([tapeTimeKey(row.time
 export function newestFirst<T extends { timestamp: string }>(rows: readonly T[]): T[] {
   return [...rows].sort((a, b) => tapeTimeKey(b.timestamp).localeCompare(tapeTimeKey(a.timestamp)));
 }
+/**
+ * A moment in milliseconds as a tape key, the one comparison both picking the
+ * row at a pinned moment and muting the rows after it use, so a print at
+ * 14:30:00.000000002 is after a moment of 14:30:00.000 for both.
+ */
+export const tapeMomentKey = (at: number) => tapeTimeKey(new Date(at).toISOString());
+/** Whether a SIP stamp is after a moment's key (`tapeMomentKey`). */
+export const tapeAfter = (timestamp: string, momentKey: string) => tapeTimeKey(timestamp) > momentKey;
+/** Of rows newest first, the first printed at or before a moment's key: null when every row is later. */
+export function tapeRowAtOrBefore<T>(rows: readonly T[], timestamp: (row: T) => string, momentKey: string): T | null {
+  return rows.find((row) => !tapeAfter(timestamp(row), momentKey)) ?? null;
+}
 export function tapeStatistics(data: Pick<TapeSnapshot, "trades">) {
   const trades = newestFirst(data.trades);
   const prices = trades.map((row) => row.price);