@gloom-sh/terminal 0.18.5 → 0.19.0

package/src/plugins/builtin/shared/volatility/live-session.ts

@@ -112,6 +112,21 @@ export function useOptionsSessionOpen(enabled = true): boolean {
   return state.nextChangeAt != null && Date.now() >= state.nextChangeAt ? usOptionsSession(Date.now()).open : state.open;
 }
 
+export interface LiveSessionRefresh {
+  /** The refresh cycle is running, which is what "live" means. */
+  live: boolean;
+  /**
+   * Why the last refresh failed, until one succeeds or the cycle stops. The
+   * data it would have replaced stays on screen, so the pane shows this where
+   * it shows its own failed refreshes.
+   */
+  error: string | null;
+}
+
+function isCancellation(error: unknown): boolean {
+  return !!error && typeof error === "object" && (error as { name?: unknown }).name === "AbortError";
+}
+
 /**
  * Calls `refresh` every `intervalMs` while enabled, the pane can be seen (the
  * app is visible and the pane is not covered) and the options market is open.
@@ -119,18 +134,19 @@ export function useOptionsSessionOpen(enabled = true): boolean {
  * after the caller's own load (`loadedAt`); returning after a hidden or
  * covered stretch, or reaching the open, more than an interval after the last
  * data fires straight away. A refresh still in flight is never overlapped by
- * the next. Returns whether the refresh cycle is running, which is what
- * "live" means.
+ * the next. A refresh that throws or rejects is reported as `error` until the
+ * next one succeeds; a cancelled one (an AbortError) is no failure.
  */
 export function useLiveSessionRefresh(
   refresh: () => void | Promise<unknown>,
   intervalMs: number,
   enabled: boolean,
   loadedAt?: number | null,
-): boolean {
+): LiveSessionRefresh {
   const visible = usePaneVisible();
   const open = useOptionsSessionOpen(enabled);
   const active = enabled && visible && open;
+  const [error, setError] = useState<string | null>(null);
   const refreshRef = useRef(refresh);
   refreshRef.current = refresh;
   const lastRef = useRef(Date.now());
@@ -142,21 +158,31 @@ export function useLiveSessionRefresh(
     let cancelled = false;
     // A load the caller finished itself counts as the latest refresh.
     if (loadedAtRef.current != null && loadedAtRef.current > lastRef.current) lastRef.current = loadedAtRef.current;
+    const succeeded = () => { if (!cancelled) setError(null); };
+    const failed = (failure: unknown) => {
+      if (cancelled || isCancellation(failure)) return;
+      const message = (failure instanceof Error ? failure.message : String(failure ?? "")).trim();
+      setError(message || "Live refresh failed");
+    };
     const run = () => {
       if (inFlight || cancelled) return;
       lastRef.current = Date.now();
       let pending: void | Promise<unknown>;
-      try { pending = refreshRef.current(); } catch { return; }
+      try { pending = refreshRef.current(); } catch (failure) {
+        failed(failure);
+        return;
+      }
       if (pending && typeof (pending as Promise<unknown>).then === "function") {
         inFlight = true;
-        void (pending as Promise<unknown>).catch(() => {}).finally(() => { inFlight = false; });
-      }
+        void (pending as Promise<unknown>).then(succeeded, failed).finally(() => { inFlight = false; });
+      } else succeeded();
     };
     if (Date.now() - lastRef.current >= intervalMs) run();
     const timer = setInterval(run, intervalMs);
-    return () => { cancelled = true; clearInterval(timer); };
+    // A stopped cycle's failure is old news: the pane's own loads take over.
+    return () => { cancelled = true; clearInterval(timer); setError(null); };
   }, [active, intervalMs]);
-  return active;
+  return { live: active, error: active ? error : null };
 }
 
 /**

package/src/plugins/builtin/shared/volatility/pricing.ts

@@ -134,6 +134,25 @@ export function valueOption(input: OptionPricingInput): OptionValuation {
   };
 }
 
+/**
+ * The chance the underlying closes above `strike` at expiry under the same
+ * Black-Scholes-Merton model: N(d2), the risk-neutral probability a call there
+ * finishes in the money. 1 or 0 when nothing is left uncertain (expiry, zero
+ * volatility), by where the discounted forward sits.
+ */
+export function probabilityAbove(input: Omit<OptionPricingInput, "side">): number {
+  const spot = Math.max(0, finite(input.spot));
+  const strike = Math.max(0, finite(input.strike));
+  const years = Math.max(0, finite(input.daysToExpiry)) / DAYS_PER_YEAR;
+  const rate = finite(input.rate);
+  const dividendYield = finite(input.dividendYield);
+  const volatility = Math.max(0, finite(input.volatility));
+  if (strike <= 0) return 1;
+  if (years <= 0 || volatility <= 0 || spot <= 0) return spot * Math.exp((rate - dividendYield) * years) > strike ? 1 : 0;
+  const d2 = (Math.log(spot / strike) + (rate - dividendYield - volatility * volatility / 2) * years) / (volatility * Math.sqrt(years));
+  return normalCdf(d2);
+}
+
 export interface ImpliedVolatilityResult {
   volatility: number | null;
   /** Why no volatility could be solved, phrased for the pane body. */

package/src/plugins/builtin/shared/wall-view-lifecycle.ts

@@ -1,3 +1,5 @@
+import { logFailure } from "../../../utils/log-failure";
+
 type Arm = "control" | "teaser" | null;
 type TeaserKind = "summary" | "sample" | "none";
 const active = new Map<string, Set<object>>();
@@ -17,7 +19,7 @@ export function trackWallView({ identity, placement, exposure, currentIdentity,
   active.set(key, copies);
   let released = false;
   let reported = false;
-  const answer = exposure.catch(() => null);
+  const answer = exposure.catch(logFailure("shared.wall-view-lifecycle", "Resolve wall experiment arm failed", null));
 
   return {
     exposure: answer,

package/src/plugins/builtin/themes/model.ts

@@ -17,14 +17,16 @@ export function boardYtdBase(payload: { asOf?: unknown; regularSessionDate?: unk
 }
 
 /**
- * A period's header. YTD names its base close, as long as `room` allows:
- * `YTD vs 31 Dec close`, `YTD vs 31 Dec`, then `YTD 31 Dec`.
+ * A period's header. YTD says what it is, a return against the close it is
+ * measured from, as long as `room` allows: `YTD vs 31 Dec close`, `YTD vs 31
+ * Dec`, then `YTD`.
  */
 export function periodLabel(period: ThemePeriod, ytdBase: string | null, room = Infinity): string {
   if (period !== "returnYtdPercent" || !ytdBase) return PERIOD_LABELS[period];
-  const labels = [`YTD vs ${ytdBase} close`, `YTD vs ${ytdBase}`, `YTD ${ytdBase}`];
+  const labels = [`YTD vs ${ytdBase} close`, `YTD vs ${ytdBase}`, "YTD"];
   return labels.find((label) => label.length <= room) ?? labels.at(-1)!;
 }
+
 export interface ThemeSort { columnId: string; direction: SortDirection }
 export const DEFAULT_SORT: ThemeSort = { columnId: "changePercent", direction: "desc" };
 export function percent(value: number | null): string {
@@ -32,12 +34,17 @@ export function percent(value: number | null): string {
   const rounded = Number(value.toFixed(2));
   return `${rounded > 0 ? "+" : ""}${rounded.toFixed(2)}%`;
 }
+/** How many of a theme's names a figure is drawn from, when not all of them: `7 of 8`. Empty when every name is in it. */
+export function coverageText(metric: ThemeAggregate): string {
+  return metric.covered < metric.total ? `${metric.covered} of ${metric.total}` : "";
+}
 export function aggregateText(metric: ThemeAggregate, breadth = false): string {
   const value = breadth && metric.value !== null ? `${Math.round(metric.value)}%` : percent(metric.value);
-  return `${value}${metric.covered < metric.total ? ` ${metric.covered}/${metric.total}` : ""}`;
+  const coverage = coverageText(metric);
+  return `${value}${coverage ? ` ${coverage}` : ""}`;
 }
 export const memberPrice = (value: number | null) => value === null ? "--" : value.toLocaleString("en-US", { minimumFractionDigits: 2, maximumFractionDigits: 2 });
-export const coverageWidth = (metrics: readonly ThemeAggregate[]) => Math.max(0, ...metrics.map((metric) => metric.covered < metric.total ? `${metric.covered}/${metric.total}`.length + 1 : 0));
+export const coverageWidth = (metrics: readonly ThemeAggregate[]) => Math.max(0, ...metrics.map((metric) => coverageText(metric) ? coverageText(metric).length + 1 : 0));
 export function sortThemes(rows: readonly ThemeSummary[], sort: ThemeSort): ThemeSummary[] {
   const value = (row: ThemeSummary) => {
     if (sort.columnId === "name") return row.name;
@@ -152,9 +159,11 @@ export function themeColumns(width: number, rows: readonly ThemeSummary[], ytdBa
   const metricWidth = (period: ThemePeriod) => Math.max(8, ...rows.map((row) => percent(row.returns[period].value).length)) + suffixWidth(period);
   // The same trailing space is reserved in every cell and its header. A note
   // occupies that space without moving the number away from its label.
-  const label = (period: ThemePeriod, room?: number) => periodLabel(period, ytdBase, room) + " ".repeat(suffixWidth(period));
+  const label = (period: ThemePeriod, room: number) => periodLabel(period, ytdBase, room) + " ".repeat(suffixWidth(period));
+  // The board always keeps room for `YTD vs 31 Dec`, so even a narrow one says what its YTD is measured against.
+  const leastRoom = ytdBase ? `YTD vs ${ytdBase}`.length : 0;
   const columns = [column("name", "Theme", 26, "left"), column("memberCount", "N", 3),
-    ...THEME_PERIODS.map((period) => column(period, label(period, 0), Math.max(metricWidth(period), label(period, 0).length + HEADER_ROOM))),
+    ...THEME_PERIODS.map((period) => column(period, label(period, leastRoom), Math.max(metricWidth(period), label(period, leastRoom).length + HEADER_ROOM))),
     column("breadth", "Breadth" + " ".repeat(coverageWidth(rows.map((row) => row.breadth))), 7 + coverageWidth(rows.map((row) => row.breadth))),
     column("best", "Best 1D", 15), column("worst", "Worst 1D", 15)];
   const fitted = fitColumns(columns, width, ["worst", "best", "return3MPercent", "returnYtdPercent", "return1MPercent", "return1WPercent", "memberCount"]);

package/src/plugins/builtin/themes/pane.tsx

@@ -5,14 +5,14 @@ import { usePaneRefreshKey } from "../../../components/data-table/table-pane";
 import type { ExtendedSession } from "../../../market-data/market/status";
 import { useAsyncResource, useAutoRefresh, usePluginPaneState, usePluginTickerActions, useUpdatedAgo } from "../../../public/react";
 import { usePaneInstance } from "../../../state/app/context";
-import { priceColor, shownPriceColor } from "../../../theme/colors";
+import { shownPriceColor } from "../../../theme/colors";
 import { useThemeColors } from "../../../theme/theme-context";
 import { Box, Text } from "../../../ui";
 import { nextHeaderSort } from "../../../utils/sort-values";
 import { useMembersMenu } from "../shared/members-menu";
 import { cachedMembers, cachedThemes, loadMembers, loadThemes } from "./client";
 import {
-  aggregateText, boardYtdBase, coverageWidth, DEFAULT_SORT, extendedMove, matchTheme, memberColumns, memberExtendedSessions, memberPrice, percent,
+  aggregateText, boardYtdBase, coverageText, coverageWidth, DEFAULT_SORT, extendedMove, matchTheme, memberColumns, memberExtendedSessions, memberPrice, percent,
   isLiveBoard, LIVE_BOARD_REFRESH_MS, SNAPSHOT_STALE_MS, snapshotFooterText, sortMembers, sortThemes, themeColumns, type ThemeSort,
 } from "./model";
 
@@ -135,14 +135,14 @@ export function ThemesBoard({ width, height, focused, tabStrip, tabRows = 0 }: T
     if (column.id === "best" || column.id === "worst") {
       const member = row[column.id];
       return { text: member ? `${member.symbol} ${percent(member.changePercent)}` : "--", value: member?.changePercent ?? null,
-        color: member ? priceColor(member.changePercent, colors) : colors.textMuted };
+        color: member ? shownPriceColor(member.changePercent, 2, colors) : colors.textMuted };
     }
     const breadth = column.id === "breadth";
     const metric = breadth ? row.breadth : row.returns[column.id as ThemePeriod];
     const suffixWidth = coverageWidth((data?.themes ?? []).map((theme) => breadth ? theme.breadth : theme.returns[column.id as ThemePeriod]));
-    const color = metric.value === null || breadth ? colors.textMuted : priceColor(metric.value, colors);
+    const color = metric.value === null || breadth ? colors.textMuted : shownPriceColor(metric.value, 2, colors);
     const valueText = breadth && metric.value !== null ? `${Math.round(metric.value)}%` : percent(metric.value);
-    const suffix = metric.covered < metric.total ? `${metric.covered}/${metric.total}` : "";
+    const suffix = coverageText(metric);
     return { text: aggregateText(metric, breadth), value: metric.value,
       color, content: suffixWidth ? <Box flexDirection="row" width={column.width} justifyContent="flex-end">
         <Text fg={color}>{valueText}</Text><Text fg={colors.textMuted}>{suffix.padStart(suffixWidth)}</Text>

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

@@ -16,12 +16,12 @@ import { TIME_RANGES, type TimeRange } from "../../../../time-series/range";
 import type { PaneProps } from "../../../../types/plugin";
 import type { PricePoint } from "../../../../types/financials";
 import { colors, priceColor } from "../../../../theme/colors";
-import { formatCompact, formatPercent } from "../../../../utils/format";
+import { displayWidth, formatCompact, formatPercent } from "../../../../utils/format";
 import { isPlainKeyboardEvent } from "../../../../utils/keyboard";
 import { publicTickerKey } from "../../../../utils/exchanges";
-import { quoteFormatOptions } from "../../../../market-data/market/format";
+import { isPenceQuotedLine, penceFigure, quoteFormatOptions } from "../../../../market-data/market/format";
 import {
-  barPriceDecimals, formatBarPrice, historyAllStart, historyBarsAfterHole, historyChangeBaseNote, historyMissingPeriodsNote,
+  barPriceDecimals, formatBarPrice, historyAllStart, historyBarsAfterHole, historyChangeBaseNote, historyMissingPeriodsNote, quotedPriceDivisor,
 } from "../../../../cli/history-rows";
 import {
   MISSING_VOLUME_TEXT, missingVolumeCount, missingVolumeNotice, pricePointValues, priceHistoryIntegrityNotice,
@@ -89,8 +89,8 @@ function formatMaybePrice(value: number | null | undefined, decimals: number, wi
 }
 
 /** 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 {
-  return barPriceDecimals(rows.map(({ point }) => point), assetCategory);
+function historicalPriceDecimals(rows: readonly HistoricalPriceRow[], assetCategory?: string, priceDivisor = 1): number {
+  return barPriceDecimals(rows.map(({ point }) => point), assetCategory, priceDivisor);
 }
 
 /** The exported price: the digits the table shows, without the width limit. */
@@ -178,19 +178,27 @@ const HISTORY_NUMERIC_IDS = ["open", "high", "low", "close", "change", "changePe
 /**
  * Fixed date and volume columns; the price columns take the rest of the pane
  * evenly, and give up cells down to a floor when it is narrow, so the volume
- * stays on screen.
+ * stays on screen. A close with a note beside it (a London line's pence) asks
+ * for `closeWidth`, the widest close and note: the other columns give way to
+ * it first, down to their minimum, before it gives up its note.
  */
-function buildHistoryColumns(width: number, intraday: boolean, size: HistoryBarSize, newestDate: string): HistoryColumn[] {
+function buildHistoryColumns(width: number, intraday: boolean, size: HistoryBarSize, newestDate: string, closeWidth = 0): HistoryColumn[] {
   // A month reads as `2026-10`; the newest bar, when its week or month runs on, adds `MTD` or `WTD`.
   const dateWidth = Math.max(intraday ? 16 : size === "1mo" ? 7 : 10, newestDate.length);
-  const numeric: number[] = HISTORY_NUMERIC_IDS.map((id) => id === "changePercent" ? HISTORY_PERCENT_WIDTH : HISTORY_PRICE_WIDTH);
+  const numeric: number[] = HISTORY_NUMERIC_IDS.map((id) => id === "changePercent" ? HISTORY_PERCENT_WIDTH
+    : id === "close" ? Math.max(HISTORY_PRICE_WIDTH, closeWidth) : HISTORY_PRICE_WIDTH);
   // One gap per column plus the table's inset on both sides.
   const available = width - dateWidth - HISTORY_VOLUME_WIDTH - 8 - 2;
   let spare = available - numeric.reduce((sum, value) => sum + value, 0);
-  for (let index = 0; spare < 0 && numeric.some((value) => value > HISTORY_NUMERIC_MIN_WIDTH); index = (index + 1) % numeric.length) {
-    if (numeric[index]! > HISTORY_NUMERIC_MIN_WIDTH) {
-      numeric[index]! -= 1;
-      spare += 1;
+  // The close keeps the width its note asks for while another column can give way, then gives it up too.
+  const closeAt = HISTORY_NUMERIC_IDS.indexOf("close");
+  for (const closeFloor of [Math.max(HISTORY_NUMERIC_MIN_WIDTH, closeWidth), HISTORY_NUMERIC_MIN_WIDTH]) {
+    const floor = (index: number) => index === closeAt ? closeFloor : HISTORY_NUMERIC_MIN_WIDTH;
+    for (let index = 0; spare < 0 && numeric.some((value, at) => value > floor(at)); index = (index + 1) % numeric.length) {
+      if (numeric[index]! > floor(index)) {
+        numeric[index]! -= 1;
+        spare += 1;
+      }
     }
   }
   if (spare > 0) {
@@ -256,13 +264,25 @@ export function HistoricalPricesPane({ focused, width, height }: PaneProps) {
   // Daily and longer bars are dates; only intraday bars carry a time.
   const intraday = rows.length > 0 ? rows.some((row) => row.timed) : range === "1D" || range === "1W";
   const newestRowDate = rows[0]?.date ?? "";
-  const columns = useMemo(() => buildHistoryColumns(width, intraday, size, newestRowDate), [intraday, newestRowDate, size, width]);
   const assetCategory = quoteFormatOptions(
     financials?.quote,
     ticker?.metadata.assetCategory,
     financials?.quoteMetadata?.instrumentType,
   ).assetCategory;
-  const priceDecimals = useMemo(() => historicalPriceDecimals(rows, assetCategory), [assetCategory, rows]);
+  const priceDivisor = quotedPriceDivisor(quote);
+  const priceDecimals = useMemo(() => historicalPriceDecimals(rows, assetCategory, priceDivisor), [assetCategory, priceDivisor, rows]);
+  // A London line's close reads in pence too (6.385 638.5p): the close column asks for room for the widest.
+  const pence = isPenceQuotedLine(quote);
+  const closeWidth = useMemo(() => !pence ? 0 : rows.reduce((widest, row) => {
+    const close = row.point.close;
+    const pence = penceFigure(exportPrice(close, priceDecimals), quote, priceDecimals);
+    // A cell more than the text, so the close never runs into the low before it.
+    return pence ? Math.max(widest, displayWidth(` ${formatMaybePrice(close, priceDecimals, Infinity)} ${pence}`)) : widest;
+  }, 0), [pence, priceDecimals, quote, rows]);
+  const columns = useMemo(
+    () => buildHistoryColumns(width, intraday, size, newestRowDate, closeWidth),
+    [closeWidth, intraday, newestRowDate, size, width],
+  );
   const boundedSelectedIdx = rows.length > 0 ? Math.min(selectedIdx, rows.length - 1) : -1;
   const cycleRange = useCallback(() => setRange((current) => nextHistoryRange(current)), [setRange]);
 
@@ -296,12 +316,17 @@ export function HistoricalPricesPane({ focused, width, height }: PaneProps) {
       case "open":
       case "high":
       case "low":
-      case "close":
+      case "close": {
+        const value = row.point[column.id];
+        // A London line's close also reads in the pence it trades in, where the column has room: 6.385 638.5p.
+        const pence = column.id === "close" ? penceFigure(exportPrice(value, priceDecimals), quote, priceDecimals) : null;
         return {
-          text: formatMaybePrice(row.point[column.id], priceDecimals, column.width),
-          value: exportPrice(row.point[column.id], priceDecimals),
+          text: formatMaybePrice(value, priceDecimals, column.width),
+          value: exportPrice(value, priceDecimals),
+          ...(pence ? { note: pence } : {}),
           ...(column.id === "close" ? { color: colors.textBright, attributes: TextAttributes.BOLD } : { color: colors.text }),
         };
+      }
       case "change":
         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) };
@@ -311,7 +336,7 @@ export function HistoricalPricesPane({ focused, width, height }: PaneProps) {
       case "volume":
         return { text: formatVolume(row.point.volume, volumeMissing > 0), value: row.point.volume ?? null, color: colors.textDim };
     }
-  }, [priceDecimals, volumeMissing]);
+  }, [priceDecimals, quote, 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;

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

@@ -1,3 +1,4 @@
+import { logFailure } from "../../../../utils/log-failure";
 import { fetchHistoryResult, InvalidHistoryResultError } from "../../../../sources/history-result";
 import { historyRetentionNotice, isHistoryRetentionError } from "../../../../sources/history-retention";
 import {
@@ -74,8 +75,8 @@ async function sessionVenue(provider: DataProvider, symbol: string, exchange: st
       ? await provider.getQuoteMetadata(symbol, exchange)
       : await provider.getQuote(symbol, exchange);
     return metadata?.listingExchangeName ?? "";
-  } catch {
-    return "";
+  } catch (error) {
+    return logFailure("ticker-detail.data-panes.returns-history", "Read return session venue failed", "")(error);
   }
 }
 

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

@@ -17,7 +17,9 @@ import {
 import { isRoundTheClockCoin } from "../../../../utils/crypto-pair";
 import { currentFxClosureStart, isCurrencyPairListing } from "../../../../utils/fx-market-hours";
 import { pricePointValues } from "../../../../utils/price-history-integrity";
+import { timeZoneCity, zonedClock } from "../../../../utils/utc-time";
 import { zonedDateKey } from "../../../../utils/zoned-date-time";
+import { historyDateHeader } from "./history-bars";
 
 export type ReturnRange = "6H" | "1D" | "5D" | TimeRange;
 
@@ -347,6 +349,66 @@ export function returnBaseCloseDay(
   return period ? barLastSession(day, period, venue, now) ?? barCloseDay(day, resolution, venue) : day;
 }
 
+/**
+ * The clock an intraday bar's time is shown on: its venue's own, where the app
+ * knows its sessions, so the open reads 09:30 and not 13:30; null for UTC, which
+ * is where a coin, a currency pair or a venue with no known zone keeps its bars.
+ */
+function returnClockZone(venue: string | undefined): string | null {
+  if (!venue || isAlwaysOpenExchange(venue)) return null;
+  return sessionCalendarTimeZone(venue);
+}
+
+/**
+ * A bar as the table dates it: an intraday bar's open on its venue's clock
+ * (`2026-10-23 09:30`), a daily or longer bar its session day.
+ */
+export function returnTimeText(timestamp: number, resolution: ManualChartResolution, venue: string | undefined): string {
+  if (!isIntradayResolution(resolution)) return barSessionDay(timestamp, venue);
+  const zone = returnClockZone(venue);
+  if (!zone) return new Date(timestamp).toISOString().slice(0, 16).replace("T", " ");
+  const clock = zonedClock(timestamp, zone);
+  return `${clock.date} ${clock.time}`;
+}
+
+/**
+ * What the time column is headed: the clock its times are on (`ET` for New York,
+ * as TAS heads it, the venue's city for another zone, else `UTC`), or what a
+ * daily or longer bar is dated by.
+ */
+export function returnTimeHeader(resolution: ManualChartResolution, venue: string | undefined): string {
+  if (!isIntradayResolution(resolution)) return historyDateHeader(resolution)?.toUpperCase() ?? "DATE";
+  const zone = returnClockZone(venue);
+  return `TIME ${!zone ? "UTC" : zone === "America/New_York" ? "ET" : timeZoneCity(zone).toUpperCase()}`;
+}
+
+/** The figures a window's rows add up to: its total, and the bars that moved most each way. */
+export interface ReturnSummary {
+  /** The newest row's total return, a fraction. Null when no bar has one. */
+  total: number | null;
+  best: ReturnRow | null;
+  worst: ReturnRow | null;
+}
+
+/**
+ * The window's total return (the newest priced row's, measured from the base
+ * close) with its best and worst interval. A single bar has no interval worth
+ * ranking, and a window whose every interval is the same move has no best or
+ * worst, so neither is named then.
+ */
+export function summarizeReturns(rows: readonly ReturnRow[]): ReturnSummary {
+  // Rows are newest first.
+  const total = rows.find((row) => row.cumulativePercent !== null)?.cumulativePercent ?? null;
+  const moves = rows.filter((row) => row.intervalPercent !== null);
+  let best: ReturnRow | null = null;
+  let worst: ReturnRow | null = null;
+  for (const row of moves) {
+    if (!best || row.intervalPercent! > best.intervalPercent!) best = row;
+    if (!worst || row.intervalPercent! < worst.intervalPercent!) worst = row;
+  }
+  return best && worst && best.intervalPercent !== worst.intervalPercent ? { total, best, worst } : { total, best: null, worst: null };
+}
+
 /** Whether the newest daily row is the session still trading at its venue, which its table marks. */
 export function isTodayReturnRow(row: Pick<ReturnRow, "timestamp"> | undefined, resolution: ManualChartResolution, venue: string | undefined, now: number): boolean {
   return !!row && resolution === "1d" && isIntradayDailyBar(barSessionDay(row.timestamp, venue), venue, now);