gloomberb 0.18.4 → 0.18.5

package/src/cli/pane-functions/market-session.ts

@@ -7,6 +7,7 @@ import {
   latestRegularSessionOpen,
   nextRegularSessionOpen,
 } from "../../market-data/market/freshness";
+import { futuresWeekendClosure } from "../../market-data/market/futures-week";
 import { currentFxClosureStart } from "../../utils/fx-market-hours";
 import { zonedDateKey } from "../../utils/zoned-date-time";
 import type { ReportTime } from "../../utils/utc-time";
@@ -21,6 +22,11 @@ export interface ReportMarket {
   reopensAt?: string;
   /** That open's date at its venue, so a Monday open in Sydney reads Monday. */
   reopensOn?: string;
+  /**
+   * The reopen is the week's first trade (a futures venue's Sunday evening),
+   * not a regular session's open: `reopens 22:00 UTC`, never a session's name.
+   */
+  firstTrade?: true;
 }
 
 /** One dated row of a quote report: the venue it trades on and the session its source reports. */
@@ -34,7 +40,7 @@ export interface SessionObservation {
 
 interface VenueSession {
   state: ReportMarketState | "always";
-  next?: { date: string; open: number };
+  next?: { date: string; open: number; firstTrade?: true };
   /** The latest regular session that has closed: its local date and open. */
   last?: { date: string; open: number | null };
   timeZone?: string;
@@ -48,8 +54,9 @@ const US_EXCHANGE_TIME_ZONE = "America/New_York";
 /**
  * A venue's session now, from its calendar (weekends and published holidays),
  * or from the state its source reports when the app has no calendar for it,
- * such as an index publisher or a futures exchange; an index quote that states
- * none is placed on the sessions it carries. Null when none of them says.
+ * such as an index publisher or a futures exchange (whose weekend gap it
+ * knows); an index quote that states none is placed on the sessions it
+ * carries. Null when none of them says.
  */
 function venueSession(exchange: string, marketState: string | undefined, now: number, calendar?: QuoteIndexSession): VenueSession | null {
   if (isAlwaysOpenExchange(exchange)) return { state: "always" };
@@ -67,6 +74,9 @@ function venueSession(exchange: string, marketState: string | undefined, now: nu
     }
     return { state: "closed", next, last, timeZone };
   }
+  // A futures venue's weekend gap closes every contract, so it outranks the state a quote stamped before the Friday close.
+  const weekend = futuresWeekendClosure(exchange, now);
+  if (weekend) return { state: "closed", ...(weekend.reopensAt != null && weekend.reopensOn ? { next: { date: weekend.reopensOn, open: weekend.reopensAt, firstTrade: true as const } } : {}) };
   if (marketState === "REGULAR") return { state: "open" };
   const stated = marketState === "PRE" ? "pre-market" : marketState === "POST" ? "after-hours" : marketState && CLOSED_STATES.has(marketState) ? "closed" : null;
   if (!calendar) return stated ? { state: stated } : null;
@@ -209,7 +219,7 @@ export function reportMarketSession(
   if (states.size !== 1 || states.has("always")) return { market: null, closeDate: null, closeMarket: null };
   const state = [...states][0] as ReportMarketState;
   const reopen = state === "closed" || state === "pre-market"
-    ? [...sessions.values()].reduce<{ date: string; open: number } | null>((first, session) => (
+    ? [...sessions.values()].reduce<NonNullable<VenueSession["next"]> | null>((first, session) => (
       session.next && (!first || session.next.open < first.open) ? session.next : first
     ), null)
     : null;
@@ -217,7 +227,7 @@ export function reportMarketSession(
   return {
     market: {
       state,
-      ...(reopen ? { reopensAt: new Date(reopen.open).toISOString(), reopensOn: reopen.date } : {}),
+      ...(reopen ? { reopensAt: new Date(reopen.open).toISOString(), reopensOn: reopen.date, ...(reopen.firstTrade ? { firstTrade: true as const } : {}) } : {}),
     },
     closeDate,
     closeMarket: closeDate && newest ? closeMarketOf(newest.exchange, newest.session) : null,

package/src/cli/pane-functions/report.ts

@@ -5,6 +5,7 @@ import { buildHeadlessFunctionReport } from "./headless";
 import { appendDomReportFooter, buildDomFunctionReport, domReportNote, domReportView } from "./dom";
 import type { ReportFreshness } from "./freshness";
 import type { CliReportTables } from "../report-tables";
+import { knownGapMessage } from "../known-gaps";
 
 export type PaneFunctionReportSource = "headless" | "dom";
 
@@ -72,7 +73,10 @@ export async function buildFunctionReport(
     // A pane `shot` can draw is still one command away.
     const screenshot = resolved.capability.screenshotReadiness;
     if (screenshot != null && screenshot !== "unsupported") {
-      throw new Error(`${resolved.token} is an interactive pane with no data report; run \`${shotCommand(resolved.token, rawArg)}\` to see it.`);
+      const error = new Error(`${resolved.token} is an interactive pane with no data report; run \`${shotCommand(resolved.token, rawArg)}\` to see it.`);
+      // What the query names that no series is (`fn CAT PMI`): where it is, as `catalog` says it.
+      const gap = rawArg.trim() ? knownGapMessage(rawArg) : null;
+      throw gap ? Object.assign(error, { details: gap }) : error;
     }
     throw new Error(`${resolved.token} is an interactive pane and does not expose a data report.`);
   }

package/src/cli/pane-functions/resolver.ts

@@ -176,12 +176,16 @@ export async function applyListingArgument(
   const exchange = typeof args.options.exchange === "string" ? args.options.exchange : undefined;
   const { exchange: _exchange, ...options } = args.options;
   // A list entry with spaces, or an argument of words, is a company's name search finds, or the symbols it holds.
-  const typed = takesOneTicker ? [args.arg] : await readNameEntries(splitSymbolArgs([args.arg], { phrases: true }), context.dataProvider);
-  if (typed.length === 0) return args;
+  const entered = takesOneTicker ? [args.arg] : await readNameEntries(splitSymbolArgs([args.arg], { phrases: true }), context.dataProvider);
+  if (entered.length === 0) return args;
+  // A symbol the function reads as another (OPX's BTC is the coin, BTC-USD) is named in a note; --exchange keeps it as typed.
+  const aliases = exchange ? [] : entered.map((raw) => headless?.symbolAlias?.(raw) ?? null);
+  const typed = entered.map((raw, index) => aliases[index]?.symbol ?? raw);
   // RY.TO is the listing its quote names, RY:TSX, as `quote` reads it: a function's data is read by venue.
   let listings = await Promise.all(typed.map((raw) => resolveCliListing(raw, exchange, context, { ownExchangeWins: typed.length > 1, venueSuffix: true })));
   // A separator stuck to the end of a pasted list (`UPST;`) is not part of a symbol; it is named.
   const notes: string[] = takesOneTicker ? [] : stripStrayEdges(args.arg).notes;
+  notes.push(...aliases.flatMap((alias) => alias ? [alias.note] : []));
   const token = found.template?.shortcut?.prefix ?? args.target.toUpperCase();
   // Words search finds no company for, and that are not symbols either, name nothing a function can read: tickers do.
   const unnamed = takesList ? listings.filter((listing) => /\s/.test(listing.symbol)) : [];
@@ -213,6 +217,18 @@ export async function applyListingArgument(
       notes.push(...answers.map((answer) => `${answer.message} ${answer.details}`));
     }
   }
+  // A listing the function has nothing for (OPX's SOL-USD) says what exists instead; a list leaves it out.
+  const refusals = headless?.refuseSymbol ? listings.flatMap((listing) => {
+    const refusal = headless.refuseSymbol!(listing.key);
+    return refusal ? [{ listing, refusal }] : [];
+  }) : [];
+  if (refusals.length > 0) {
+    listings = listings.filter((listing) => !refusals.some((entry) => entry.listing === listing));
+    if (listings.length === 0) {
+      throw new ListingArgError(refusals.map(({ refusal }) => refusal.message).join("\n"), refusals.map(({ refusal }) => refusal.details).join("\n"));
+    }
+    notes.push(...refusals.map(({ refusal }) => `${refusal.message} ${refusal.details}`));
+  }
   const usOnly = headless?.usListingsOnly;
   const abroad = usOnly ? listings.filter((listing) => listingAbroadVenue(listing.key) != null) : [];
   if (usOnly && abroad.length > 0) {

package/src/cli/quote-answer.ts

@@ -29,6 +29,7 @@ import {
   type ListingVenue,
 } from "./listing-arg";
 import { withListingSuggestion } from "./not-a-ticker";
+import { isNetworkFailure } from "../utils/network-failure";
 import type { MarketContext } from "./types";
 
 /** The text of an error, or null for none. */
@@ -76,6 +77,8 @@ export async function answerQuote(
   request: ListingDataRequest,
   refresh: boolean,
   venues: Promise<ListingVenue[]> | null,
+  /** The row prints what its move is from: a quote asked for again is dated too. */
+  { datesChangeBasis = false }: { datesChangeBasis?: boolean } = {},
 ): Promise<QuoteAnswer> {
   const root = listing.exchange ? null : indexRootFor(listing.symbol);
   // A bare root that quoted something else, such as MOVE (Corvex), points at the index too.
@@ -89,10 +92,12 @@ export async function answerQuote(
     const board = tradingBoardNote(listing, result.quote);
     return { result, listing, notes: [...choice, venue ?? [], board ?? [], also(result.quote), currencyCodeNote(listing, result.quote) ?? []].flat() };
   }
+  // No answer from the data service: no venue lookup or other listing would get one either.
+  if (isNetworkFailure(result.error)) return { result, listing, notes: [] };
   const notTraded = await notTradedMessage(listing, market);
   if (notTraded) return { result, listing, failure: { message: notTraded, oneLine: notTraded }, notes: [] };
   if (!isNoProviderError(result.error)) return { result, listing, notes: [] };
-  const other = await quoteBareListing(listing, market, request, { refresh });
+  const other = await quoteBareListing(listing, market, request, { refresh, datesChangeBasis });
   if (other?.kind === "quoted") {
     return {
       result: { target: other.listing.request, quote: other.quote },
@@ -110,7 +115,7 @@ export async function answerQuote(
     listing.exchange ? null : knownGapForTicker(listing.symbol),
   ].filter((line): line is string => !!line);
   if (!other && tryLines.length === 0) {
-    return await answerCompanyName(result, listing, market, request, refresh)
+    return await answerCompanyName(result, listing, market, request, refresh, datesChangeBasis)
       ?? { result: await withCurrencyPairHint(result, market), listing, notes: [] };
   }
   const message = other?.message ?? `${listing.symbol} has no ${request.noun}.`;
@@ -136,6 +141,7 @@ async function answerCompanyName(
   market: MarketContext,
   request: ListingDataRequest,
   refresh: boolean,
+  datesChangeBasis: boolean,
 ): Promise<QuoteAnswer | null> {
   if (!listing.typed || listing.exchange || !notATickerSymbol(errorMessage(result.error) ?? "")) return null;
   const named = await oneWordCompanyName(listing.typed, market);
@@ -147,8 +153,8 @@ async function answerCompanyName(
   });
   if (!resolved) return null;
   const found = { ...resolved, readAs: named.readAs, ...named.meant ? { meant: named.meant } : {} };
-  const [quoted] = await market.dataProvider.getQuotesBatch([found.request], { forceRefresh: refresh, revalidate: true });
-  return quoted?.quote ? answerQuote(quoted, found, market, request, refresh, null) : null;
+  const [quoted] = await market.dataProvider.getQuotesBatch([found.request], { forceRefresh: refresh, revalidate: true, datesChangeBasis });
+  return quoted?.quote ? answerQuote(quoted, found, market, request, refresh, null, { datesChangeBasis }) : null;
 }
 
 /** A listing a command found a quote for, with what `quote` says beside it. */

package/src/cli/report-tables.ts

@@ -18,7 +18,9 @@ import {
 import { isEpochMilliseconds, parseReportTime } from "../utils/utc-time";
 import type { ReportFreshness } from "./pane-functions/freshness";
 import {
+  EXPORT_DATING_COLUMNS,
   EXPORT_IDENTITY_COLUMNS,
+  exportDatingCells,
   exportIdentityCells,
   exportSourceLines,
   type ExportIdentity,
@@ -46,6 +48,12 @@ export interface CliReportTables {
   footer: string[];
   /** What the rows are of, for the fixed columns every row ends with (`EXPORT_IDENTITY_COLUMNS`). */
   identity?: ExportIdentity;
+  /**
+   * The rows are statistics dated by a period and a release: every table also
+   * ends with `period`, `released` and `retrieved` (`EXPORT_DATING_COLUMNS`),
+   * less any it has by name, with `as_of` the release.
+   */
+  dated?: boolean;
 }
 
 /** A column as a report declares it: the text view draws `format(value, row)`, or the value itself. */
@@ -623,19 +631,22 @@ function csvLine(row: readonly unknown[]): string {
 function identifiedTable(table: CliReportTable, report: CliReportTables, freshness: ReportFreshness | undefined): CliReportTable {
   if (!freshness || table.columns.length === 0) return table;
   const identity = { ...report.identity, ...table.identity };
-  const cells = exportIdentityCells(freshness, identity);
-  const rowCells = (index: number) => {
+  const identityFor = (index: number) => {
     const own = table.rowIdentities?.[index];
-    return own ? exportIdentityCells(freshness, { ...identity, ...own }) : cells;
+    return own ? { ...identity, ...own } : identity;
   };
   const added = EXPORT_IDENTITY_COLUMNS.flatMap((column, index) => table.columns.includes(column) ? [] : [index]);
-  if (added.length === 0) return table;
+  const dating = report.dated
+    ? EXPORT_DATING_COLUMNS.flatMap((column, index) => table.columns.includes(column) ? [] : [index]) : [];
+  if (added.length === 0 && dating.length === 0) return table;
   return {
     ...table,
-    columns: [...table.columns, ...added.map((index) => EXPORT_IDENTITY_COLUMNS[index]!)],
+    columns: [...table.columns, ...added.map((index) => EXPORT_IDENTITY_COLUMNS[index]!), ...dating.map((index) => EXPORT_DATING_COLUMNS[index]!)],
     rows: table.rows.map((row, index) => {
-      const identityCells = rowCells(index);
-      return [...row, ...added.map((column) => identityCells[column]!)];
+      const rowIdentity = identityFor(index);
+      const identityCells = exportIdentityCells(freshness, rowIdentity);
+      const datingCells = exportDatingCells(freshness, rowIdentity);
+      return [...row, ...added.map((column) => identityCells[column]!), ...dating.map((column) => datingCells[column]!)];
     }),
   };
 }

package/src/cli/restore-plugins.ts

@@ -5,9 +5,18 @@ import { pluginSeedFailure, pluginSeedNotice, samePluginSeedFailure, seedExtract
 import { setPluginSeedNotice } from "../plugins/seed-notice";
 import { debugLog } from "../utils/debug-log";
 import type { AppConfig } from "../types/config";
+import { withDeadline } from "../utils/async-deadline";
 
 const log = debugLog.createLogger("plugin-seed");
 
+/**
+ * How long a launch waits for the plugin registry before it starts without
+ * the plugins left to install. A connection that hangs would otherwise hold
+ * the screen blank: the registry is read first, and git would hang the same
+ * way after it. They are retried at the next launch.
+ */
+const REGISTRY_WAIT_MS = 8_000;
+
 /**
  * Reinstalls plugins that moved out of this repository into their own.
  *
@@ -40,7 +49,10 @@ export async function restoreExtractedPlugins(): Promise<Pick<AppConfig, "seeded
       // Without git every clone fails the same way: no registry read, no attempt.
       gitMissing ??= !gitInstalled();
       if (gitMissing) throw new Error("git is not installed");
-      listings ??= loadRegistryListings();
+      // Only no answer at all stops here: the network hangs, and a clone would
+      // too, so nothing is tried until the next launch. A registry that fails
+      // is not reported as silent: the plugins install from their repositories.
+      listings ??= withDeadline(loadRegistryListings(), REGISTRY_WAIT_MS, "the plugin registry did not answer");
       return installListedPlugin(repo, { quiet: true }, await listings);
     });
     // Recorded, so doctor knows a launch tried, and a failure the next launch

package/src/cli/result.ts

@@ -18,7 +18,10 @@ import { formatFreshnessLine, withSavedCopy, type ReportFreshness } from "./pane
 import { withSearchHints, type FredSeriesCheck } from "./not-a-ticker";
 import { renderReportCsv, renderReportNdjson, withCsvFooter, type CliReportTables } from "./report-tables";
 import {
+  EXPORT_DATING_COLUMNS,
   EXPORT_IDENTITY_COLUMNS,
+  exportDatingCells,
+  exportDatingFields,
   exportIdentityCells,
   exportIdentityFields,
   exportSource,
@@ -120,6 +123,15 @@ export interface CliResultRenderOptions<T = unknown, Row = Record<string, unknow
   exportIdentity?: ExportIdentity | ((row: Row) => ExportIdentity);
   /** What CSV says after the source lines as `# note:` lines: what the rows do not show, such as where a series begins. */
   exportNotes?: readonly string[];
+  /**
+   * The rows are statistics dated by a period and a release (`econ`, `fred`):
+   * CSV and NDJSON rows also end with `period`, `released` and `retrieved`
+   * (`EXPORT_DATING_COLUMNS`) after the five fixed columns, from the `period`
+   * and `released` of each row's `exportIdentity`, and `as_of` is the release.
+   * A column the rows already have by name keeps its own values. Needs a
+   * cited source, as the fixed columns do.
+   */
+  exportDated?: boolean;
   /**
    * Why a row's figures are empty (`Not a ticker: ZZZZQQ.`, `Chg%: no previous
    * close`), for the `status` column CSV writes after the row's own columns and
@@ -348,20 +360,31 @@ function renderCsv<Row extends Record<string, unknown>>(
   columns?: CliResultColumn<Row>[],
   identity?: (row: Row) => string[],
   status?: (row: Row) => string | null | undefined,
+  dating?: (row: Row) => string[],
 ): string {
   const resolvedColumns = columns && columns.length > 0
     ? columns
     : inferColumns(rows as Record<string, unknown>[]) as CliResultColumn<Row>[];
   const headers = resolvedColumns.map((column) => column.header);
+  // A dated export's own `released` column keeps its values; the others close the row.
+  const datingAdded = dating
+    ? EXPORT_DATING_COLUMNS.flatMap((column, index) => headers.includes(column) ? [] : [index]) : [];
   return serializeCsv([
-    [...headers, ...status ? [statusHeader(headers)] : [], ...identity ? EXPORT_IDENTITY_COLUMNS : []],
+    [
+      ...headers,
+      ...status ? [statusHeader(headers)] : [],
+      ...identity ? EXPORT_IDENTITY_COLUMNS : [],
+      ...datingAdded.map((index) => EXPORT_DATING_COLUMNS[index]!),
+    ],
     ...rows.map((row) => {
       const values = resolvedColumns.map((column) => (column.value ? column.value(row) : row[column.key]));
       const blanked = resolvedColumns.flatMap((column, index) => isNonFiniteNumber(values[index]) ? [column.header] : []);
+      const datingCells = dating?.(row) ?? [];
       return [
         ...values.map((value) => isNonFiniteNumber(value) ? "" : value),
         ...status ? [exportStatusText(status(row), blanked)] : [],
         ...identity?.(row) ?? [],
+        ...datingAdded.map((index) => datingCells[index] ?? ""),
       ];
     }),
   ]);
@@ -534,13 +557,26 @@ function serializeCliRows<T, Row extends Record<string, unknown>>(
     return rows.map((row) => {
       if (!isPlainObject(row)) return JSON.stringify(row);
       const fields = ndjsonRow(row as Row, status, statusKey);
-      return JSON.stringify(cited ? { ...fields, ...exportIdentityFields(cited, rowIdentity(row as Row, renderOptions.exportIdentity)) } : fields);
+      if (!cited) return JSON.stringify(fields);
+      const identity = rowIdentity(row as Row, renderOptions.exportIdentity);
+      // A dated export's own fields (a row's `released`) keep their values.
+      const dating = renderOptions.exportDated
+        ? Object.fromEntries(Object.entries(exportDatingFields(cited, identity)).filter(([key]) => !(key in fields))) : {};
+      return JSON.stringify({ ...fields, ...exportIdentityFields(cited, identity), ...dating });
     }).join("\n");
   }
   if (options.format === "csv") {
-    if (!cited) return renderCsv(rows as Row[], renderOptions.columns, undefined, status);
-    const csv = renderCsv(rows as Row[], renderOptions.columns, (row) => exportIdentityCells(cited, rowIdentity(row, renderOptions.exportIdentity)), status);
-    return withCsvFooter(csv, [...exportSourceLines(cited), ...(renderOptions.exportNotes ?? []).map((note) => `note: ${note}`)]);
+    // The rows a window cut say so after them, as text and JSON do: a script has no other way to know.
+    const cutNote = window.note ? [`note: ${window.note}`] : [];
+    if (!cited) return withCsvFooter(renderCsv(rows as Row[], renderOptions.columns, undefined, status), cutNote);
+    const csv = renderCsv(
+      rows as Row[],
+      renderOptions.columns,
+      (row) => exportIdentityCells(cited, rowIdentity(row, renderOptions.exportIdentity)),
+      status,
+      renderOptions.exportDated ? (row) => exportDatingCells(cited, rowIdentity(row, renderOptions.exportIdentity)) : undefined,
+    );
+    return withCsvFooter(csv, [...exportSourceLines(cited), ...cutNote, ...(renderOptions.exportNotes ?? []).map((note) => `note: ${note}`)]);
   }
   if (renderOptions.text) {
     return renderOptions.text(result.data);
@@ -608,6 +644,22 @@ export function printCliResult<T, Row extends Record<string, unknown> = Record<s
       console.error(`${cliStyles.warning("warning:")} ${hinted(warning)}`);
     }
   }
+  // CSV says what its rows do not in closing `# note:` lines; NDJSON has no place for one among its rows,
+  // so the same notes go to stderr, where the warnings are.
+  if (options.format === "ndjson" && !options.quiet) {
+    for (const note of exportNdjsonNotes(result, options, renderOptions)) console.error(`note: ${note}`);
+  }
+}
+
+/** What a `--limit`, or the default a command caps its rows at, left out of a list, then the command's own notes: what CSV closes with as `# note:` lines. */
+function exportNdjsonNotes<T, Row extends Record<string, unknown>>(
+  result: CliResult<T>,
+  options: CliGlobalOptions,
+  renderOptions: CliResultRenderOptions<T, Row>,
+): string[] {
+  if (renderOptions.tables || renderOptions.text) return [];
+  const cut = windowed(asRows(result.data, renderOptions.rows), options, renderOptions).note;
+  return [...cut ? [cut] : [], ...renderOptions.exportNotes ?? []];
 }
 
 export function serializeCliError(error: CliErrorObject, options: CliGlobalOptions): string {

package/src/components/chart/composite/composite-chart.tsx

@@ -7,6 +7,7 @@ import { AXIS_DOUBLE_PRESS_MS, isVerticalWheelDirection } from "./panel-gestures
 import { type ChartToolSpan, CHART_DRAWING_COLORS, isDrawingTool, type ChartDrawing } from "./tools";
 import { ChartDrawingStore, NO_DRAWINGS } from "./drawing-store";
 import { CompositeLegend } from "./legend";
+import { compositeRangeStatisticsLevels } from "./range-statistics";
 import { ChartToolbar, CHART_TOOLBAR_WIDTH } from "./toolbar";
 import { AsciiText, Box, ChartSurface, Text, useUiCapabilities, type BoxRenderable } from "../../../ui";
 import { Button } from "../../ui/button";
@@ -204,6 +205,7 @@ function ThemedCompositeChart({
   timePick,
   pricePick,
   levels,
+  rangeStatisticsSeriesId,
   chartLayout,
   onChartLayoutChange,
 }: CompositeChartProps & { chartLayout: ChartLayoutPrefs; onChartLayoutChange: ChartLayoutUpdate }) {
@@ -337,6 +339,20 @@ function ThemedCompositeChart({
     textDim: colors?.textDim ?? activeThemeColors.textDim,
     negative: colors?.negative ?? activeThemeColors.negative,
   }), [activeThemeColors, colors, paneSurface]);
+  const rangeStatisticsLevels = useMemo(() => {
+    void lastTickKey;
+    return compositeRangeStatisticsLevels(
+      panelSeries.find((entry) => entry.id === rangeStatisticsSeriesId),
+      effectiveViewport,
+      resolvedColors.textDim,
+      formatValue,
+    );
+  }, [effectiveViewport, formatValue, lastTickKey, panelSeries, rangeStatisticsSeriesId, resolvedColors.textDim]);
+  const displayedLevels = useMemo(() => (
+    levels && rangeStatisticsLevels && levels.seriesId === rangeStatisticsLevels.seriesId
+      ? { ...levels, items: [...levels.items, ...rangeStatisticsLevels.items] }
+      : levels ?? rangeStatisticsLevels
+  ), [levels, rangeStatisticsLevels]);
   // A custom x axis means x is not time: a tenor, a fraction, a return. Its
   // last observation belongs at the right edge, under its own label.
   const rightOffsetRatio = xAxis ? 0 : COMPOSITE_RIGHT_OFFSET_RATIO;
@@ -351,6 +367,7 @@ function ThemedCompositeChart({
       timelineSeries: marketTimelineSeries,
       rightOffsetRatio,
       valueScales,
+      referenceLevels: rangeStatisticsLevels,
     });
   }, [
     clipToViewport,
@@ -361,6 +378,7 @@ function ThemedCompositeChart({
     panelSeries,
     panels,
     rightOffsetRatio,
+    rangeStatisticsLevels,
     valueScales,
   ]);
   // Gutters follow the axes the scene actually built. Reading the series list
@@ -426,7 +444,7 @@ function ThemedCompositeChart({
     availableAxisWidth,
     Math.max(
       Math.min(MINIMUM_AXIS_LABEL_WIDTH, maximumAxisWidth),
-      ...(levels?.items ?? []).map((level) => level.axisLabel?.length ?? 0),
+      ...(displayedLevels?.items ?? []).map((level) => level.axisLabel?.length ?? 0),
       ...(layoutPanels ?? []).flatMap((panel) => (["left", "right"] as const).map((side) => {
         const width = compositeAxisLabelWidth(panel.axes[side], formatAxisValue, includeCursorLabels);
         if (!includeSeriesTags || !width) return includeCursorLabels ? width : Math.min(width, maximumAxisWidth);
@@ -437,7 +455,7 @@ function ThemedCompositeChart({
         return (width + 1) * lanes;
       })),
     ),
-  ), [availableAxisWidth, formatAxisValue, includeCursorLabels, includeSeriesTags, layoutPanels, maximumAxisWidth, levels?.items]);
+  ), [availableAxisWidth, displayedLevels?.items, formatAxisValue, includeCursorLabels, includeSeriesTags, layoutPanels, maximumAxisWidth]);
   const leftAxisWidth = hasLeftAxis ? resolvedAxisWidth : 0;
   const rightAxisWidth = hasRightAxis ? resolvedAxisWidth : 0;
   const axisGap = resolvedAxisWidth > 0 ? 1 : 0;
@@ -689,7 +707,7 @@ function ThemedCompositeChart({
     onActivate,
     timePick,
     pricePick,
-    levels,
+    levels: displayedLevels,
     visibleLegendSeries,
     visibleSeriesIds,
     onToggleSeries,
@@ -1136,7 +1154,7 @@ function ThemedCompositeChart({
           showTextFallback={showTextFallback}
           onPickTime={timePick?.onPick}
           onPickPrice={pricePick?.onPick}
-          levels={levelHost?.panel.id === panel.id ? levels ?? null : null}
+          levels={levelHost?.panel.id === panel.id ? displayedLevels ?? null : null}
           selectedLevelId={selectedLevelId}
           onSelectLevel={setSelectedLevelId}
           valueScalable={interactive}

package/src/components/chart/composite/format.ts

@@ -2,6 +2,7 @@ import { formatMarketPrice, formatMarketPriceWithCurrency, stablePriceFractionDi
 import { INDEX_POINTS_UNIT } from "../../../market-data/market/index-level";
 import type { ResolvedSeries, TimeSeriesPoint } from "../../../time-series/types";
 import type { CompositeAxisDomain, CompositePanelScene } from "./types";
+import { formatNumber, formatPercentRaw } from "../../../utils/format";
 import { timeZoneLabel, zonedWallClockMs } from "../../../utils/zoned-date-time";
 
 const CURRENCY_SYMBOLS: Record<string, string> = {
@@ -237,6 +238,28 @@ function compactResolution(value: number): number {
   return absolute > 0 ? 10 ** (Math.floor(Math.log10(absolute)) - 2) : 0;
 }
 
+/** A series of changes over a baseline: returns since the range began, year-on-year or quarter-on-quarter growth. */
+function isChangeSeries(series: ResolvedSeries): boolean {
+  return series.unit.trim() === "%" && (series.transform === "percent" || series.transform === "yoy" || series.transform === "qoq");
+}
+
+/**
+ * A value worked out from prices (a formula, a spread, a price over an FX
+ * rate) at its legs' decimals: bare beside a stated unit (92.6164 USD /
+ * barrel), with its derived unit, or with its currency's sign ($12.34).
+ */
+function formatDerivedValue(value: number, series: ResolvedSeries, decimals: number): string {
+  const number = formatNumber(Math.abs(value), decimals);
+  const sign = value < 0 && /[1-9]/.test(number) ? "-" : "";
+  if (series.statedUnit) return `${sign}${number}`;
+  const unit = series.unit.trim();
+  if (series.unitGroup.toLowerCase().startsWith("derived-unit:")) return `${sign}${number} ${unit}`;
+  const currency = unitCurrencyCode(unit);
+  if (!currency) return `${sign}${number}`;
+  const symbol = CURRENCY_SYMBOLS[currency];
+  return symbol ? `${sign}${symbol}${number}` : `${sign}${number} ${currency}`;
+}
+
 /** `referencePrice` defaults to the series' own; a study on a price axis
  * passes the axis's reference so it shares the price's decimals. */
 export function formatCompositeSeriesValue(
@@ -244,6 +267,10 @@ export function formatCompositeSeriesValue(
   series: ResolvedSeries,
   referencePrice = seriesPriceReference(series),
 ): string {
+  // A return reads as every other return in the app, signed with two decimals, so a legend of them lines up
+  // (+34.02%, +0.76%, +15.80%) instead of one precision per magnitude.
+  if (isChangeSeries(series)) return formatPercentRaw(value);
+  if (series.valueDecimals !== undefined) return formatDerivedValue(value, series, series.valueDecimals);
   if (series.statedUnit) {
     // The number alone: the legend prints the unit beside it, as FUT prints
     // a price beside its unit (4.6242 USD / gallon, not $4.6242).

package/src/components/chart/composite/levels.ts

@@ -23,6 +23,8 @@ export interface CompositeChartLevel {
   label?: string;
   /** Exact instrument price, independent of the grid's compact tick formatter. */
   axisLabel?: string;
+  /** A named reference guide keeps its axis label ahead of ordinary grid ticks. */
+  prioritizeAxisLabel?: boolean;
   dashed?: boolean;
 }
 

package/src/components/chart/composite/panel-series.ts

@@ -30,6 +30,7 @@ function sameSeriesMeta(left: ResolvedSeries, right: ResolvedSeries): boolean {
     && left.unitGroup === right.unitGroup
     && left.statedUnit === right.statedUnit
     && left.priceAssetCategory === right.priceAssetCategory
+    && left.valueDecimals === right.valueDecimals
     && left.nativeFrequency === right.nativeFrequency
     && left.timestampMode === right.timestampMode
     && left.dataShape === right.dataShape

package/src/components/chart/composite/panel-surface.tsx

@@ -542,6 +542,7 @@ export function CompositePanelSurface({
       yRatio,
       label: level.axisLabel ?? (formatAxisValue ? formatAxisValue(level.value, levelDomain) : formatCompositeCursorValue(level.value, levelDomain)),
       color: level.color,
+      prioritizeAxisLabel: level.prioritizeAxisLabel,
     })) : [], [formatAxisValue, levelDomain, projectedLevels, selectedLevelId]);
   const buildAxisMarkers = (side: "left" | "right") => {
     if (!panel.axes[side]) return undefined;
@@ -557,7 +558,8 @@ export function CompositePanelSurface({
     );
     const fixed = [lastPriceMarker, axisMarkers].filter(onSide).map(toAxisMarker);
     // The prior close's label yields to every level's.
-    const levelLabels = [...levelMarkers, priorCloseMarker].filter(onSide).map(toAxisMarker);
+    const referenceLabels = levelMarkers.filter((marker) => marker.prioritizeAxisLabel && onSide(marker)).map(toAxisMarker);
+    const levelLabels = [...levelMarkers.filter((marker) => !marker.prioritizeAxisLabel), priorCloseMarker].filter(onSide).map(toAxisMarker);
     // A label is a row tall, so close levels would stack into an unreadable
     // pile and hide the last price: each keeps its line, and only the labels
     // with a row to themselves show. Desktop badges sit between rows.
@@ -567,8 +569,13 @@ export function CompositePanelSurface({
         pixelY: tick.topPercent / 100 * Math.max(panel.height * cellHeightPx - 1, 1),
       }))
       : [...(side === "left" ? leftAxisLabels : rightAxisLabels)].map(([row, label]) => ({ id: undefined, row, pixelY: row * cellHeightPx, label, color: colors.textDim }));
+    const rowOf = (marker: ReturnType<typeof toAxisMarker>) => fractionalViewport ? marker.pixelY / cellHeightPx : marker.row;
+    // Named guides are part of the chart's readout: ordinary ticks yield to
+    // them, while a live price or cursor still keeps its place.
+    const references = fitAxisLabels(referenceLabels, fixed, rowOf);
     const markers = [
-      ...fitAxisLabels(levelLabels, [...fixed, ...grid], (marker) => fractionalViewport ? marker.pixelY / cellHeightPx : marker.row),
+      ...references,
+      ...fitAxisLabels(levelLabels, [...references, ...fixed, ...grid], rowOf),
       ...fixed,
     ];
     return markers.length > 0 ? markers : undefined;

package/src/components/chart/composite/range-statistics.ts

@@ -0,0 +1,62 @@
+import type { ResolvedSeries, TimeSeriesPoint } from "../../../time-series/types";
+import { formatCompositeSeriesValue } from "./format";
+import type { CompositeViewportRange } from "./interactions";
+import type { CompositeChartLevel, CompositeChartLevels } from "./levels";
+
+/** Population statistics of the finite observations actually in the window. */
+export function compositeRangeStatistics(points: readonly TimeSeriesPoint[], viewport: CompositeViewportRange) {
+  const start = viewport.start.getTime();
+  const end = viewport.end.getTime();
+  if (!Number.isFinite(start) || !Number.isFinite(end) || start > end) return null;
+  let count = 0;
+  let mean = 0;
+  let squaredDeviations = 0;
+  for (const point of points) {
+    const time = point.date.getTime();
+    const value = Number.isFinite(point.value) ? point.value : point.close;
+    if (!Number.isFinite(time) || time < start || time > end
+      || typeof value !== "number" || !Number.isFinite(value)) continue;
+    count += 1;
+    // Welford's update avoids subtracting nearly equal squared sums when
+    // valuations are tightly clustered around a large level.
+    const delta = value - mean;
+    mean += delta / count;
+    squaredDeviations += delta * (value - mean);
+  }
+  if (!count || !Number.isFinite(mean) || !Number.isFinite(squaredDeviations)) return null;
+  return { count, mean, standardDeviation: Math.sqrt(Math.max(0, squaredDeviations / count)) };
+}
+
+/** Read-only levels share the chart's axis labels, vector, Kitty and text paths. */
+export function compositeRangeStatisticsLevels(
+  series: ResolvedSeries | undefined,
+  viewport: CompositeViewportRange | null,
+  color: string,
+  formatValue: (value: number, series: ResolvedSeries) => string = formatCompositeSeriesValue,
+): CompositeChartLevels | null {
+  if (!series || series.hidden || !viewport) return null;
+  const statistics = compositeRangeStatistics(series.points, viewport);
+  if (!statistics || statistics.count < 20) return null;
+  const { mean, standardDeviation } = statistics;
+  const guides = [
+    { id: "mean", label: "Avg", value: mean, dashed: false },
+    { id: "upper", label: "+1σ", value: mean + standardDeviation, dashed: true },
+    { id: "lower", label: "−1σ", value: mean - standardDeviation, dashed: true },
+  ];
+  const items: CompositeChartLevel[] = [];
+  for (const guide of guides) {
+    // A constant window (including one observation) has only its mean.
+    if (!Number.isFinite(guide.value) || items.some((item) => item.value === guide.value)) continue;
+    items.push({
+      id: `range-statistics:${series.id}:${guide.id}`,
+      value: guide.value,
+      color,
+      dashed: guide.dashed,
+      axisLabel: `${guide.label} ${formatValue(guide.value, series)}`,
+      prioritizeAxisLabel: true,
+      editable: false,
+      actionable: false,
+    });
+  }
+  return { seriesId: series.id, items };
+}