gloomberb 0.18.4 → 0.19.0

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

@@ -19,12 +19,15 @@ import { splitSymbolArgs, stripStrayEdges } from "../symbol-args";
 import { readNameEntries } from "../name-entries";
 import { bankFigurePointer } from "../known-gaps";
 import { readTerminalCodeArg } from "../../tickers/company-name-listing";
+import { unknownBloombergMarket } from "../../tickers/terminal-codes";
+import { notATickerWords } from "../company-name-hint";
 import type { MarketContext } from "../types";
 import {
   buildPaneFunctionLookup,
   buildTemplateContext,
   findFunctionCode,
   nearFunctionCodes,
+  paneFunctionCode,
   suggestedFunctionCodes,
   suggestPaneFunctions,
   type NearFunctionCode,
@@ -142,8 +145,9 @@ export function parsePaneFunctionArgsFor(
   const found = parsed.target ? findPaneFunction(registry, parsed.target) : null;
   if (!found?.pane) return parsed;
   const capability = getPaneFunctionCapability(found.template, found.pane);
-  if (!capability.options.some((option) => (option.valueWords ?? 1) > 1)) return parsed;
-  return parsePaneFunctionArgs(args, globalOptions, (key) => findCapabilityOption(capability, key)?.valueWords ?? 1);
+  if (!capability.options.some((option) => (option.valueWords ?? 1) > 1 || option.list)) return parsed;
+  return parsePaneFunctionArgs(args, globalOptions, (key) => findCapabilityOption(capability, key)?.valueWords ?? 1,
+    (key) => findCapabilityOption(capability, key)?.list === true);
 }
 
 /**
@@ -168,20 +172,30 @@ export async function applyListingArgument(
   const takesOneTicker = kind === "ticker";
   const takesList = kind === "tickers" || kind === "symbol-list" || (!headless && kind === "ticker-list");
   // A function with an exchange option of its own (DIST) keeps it.
-  // A ticker with spaces is no listing, unless it is a terminal's code for one ("JPM US Equity").
-  if (!(takesOneTicker || takesList) || (takesOneTicker && /\s/.test(args.arg) && !await readTerminalCodeArg(context.dataProvider, args.arg))
-    || getPaneFunctionCapability(found.template, found.pane).options.some((option) => option.key === "exchange")) {
+  if (!(takesOneTicker || takesList) || getPaneFunctionCapability(found.template, found.pane).options.some((option) => option.key === "exchange")) {
     return args;
   }
+  // A ticker with spaces is no listing, unless it is a terminal's code for one ("JPM US Equity"). A company's name
+  // typed there (`fn RDCF "Palantir Technologies"`) stops before a report of dashes is drawn, as `quote` words a
+  // name that is no ticker, with the company search finds for it.
+  if (takesOneTicker && /\s/.test(args.arg) && !await readTerminalCodeArg(context.dataProvider, args.arg)) {
+    // A line written as a code with a market no venue answers to ("AAPL GP") is refused as the resolver words it.
+    if (unknownBloombergMarket(args.arg)) await resolveCliListing(args.arg, undefined, context);
+    throw new ListingArgError(await notATickerWords(args.arg, context));
+  }
   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 +227,19 @@ 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) {
+      const details = refusals.flatMap(({ refusal }) => refusal.details ? [refusal.details] : []).join("\n");
+      throw new ListingArgError(refusals.map(({ refusal }) => refusal.message).join("\n"), details || undefined);
+    }
+    notes.push(...refusals.map(({ refusal }) => [refusal.message, refusal.details].filter(Boolean).join(" ")));
+  }
   const usOnly = headless?.usListingsOnly;
   const abroad = usOnly ? listings.filter((listing) => listingAbroadVenue(listing.key) != null) : [];
   if (usOnly && abroad.length > 0) {
@@ -332,7 +359,7 @@ export async function resolvePaneFunction(
     tableSection = taken.tableSection;
   }
   // What the user types for the function, which every error about it names.
-  const token = template?.shortcut?.prefix ?? template?.id ?? pane.id;
+  const token = paneFunctionCode(template, pane);
   // A word after a function that takes none is most often one of its option values (`fn JODI gas`).
   // Every function the catalog lists with no argument refuses one, a rendered view (HALT) as a report (CBR).
   // The catalog lists templates and the panes no template opens (HELP); a pane opened by its id stands for its templates.

package/src/cli/pane-functions/screenshot-assessment.ts

@@ -4,6 +4,7 @@ import type { DesktopPaneShotPayload, DesktopPaneShotRenderResult } from "../des
 import type { ResolvedPaneFunction } from "./resolver";
 import type { RemoteUiNodeSnapshot } from "../../remote/types";
 import { accessGateSentence, accessGateStatus } from "./access-gate";
+import { isDataPaneForDomFallback } from "./capabilities";
 import { paneEvidenceMismatches, paneScreenshotEvidenceHook } from "./screenshot-evidence";
 import { collectShotSymbols } from "./data";
 import { renderedReportNotices } from "./report-notices";
@@ -21,10 +22,9 @@ import {
 import { shotExpectedChart, chartEvidenceMismatchesFor, intradayChartEvidenceMismatchesFor } from "./screenshot-chart-evidence";
 
 export function isPaneScreenshotUsable(signals: PaneScreenshotReadinessSignals): boolean {
-  return signals.rowCount > 0
+  return (signals.interactive || (signals.rowCount > 0 && !signals.emptyStateDetected))
     && !signals.loadingStateDetected
     && !signals.errorStateDetected
-    && !signals.emptyStateDetected
     && signals.complete
     && !signals.semanticMismatch
     && (!signals.requiresStructuredDataEvidence || signals.hasStructuredDataEvidence);
@@ -111,12 +111,14 @@ export function assessPaneScreenshot(
   const semanticMismatch = missingExpectedText.length > 0
     || missingExpectedSelections.length > 0
     || chartEvidenceMismatches.length > 0;
+  // Layouts and the other panes that are surfaces to operate have no rows to count: a capture of one is not empty for that.
+  const interactive = !isDataPaneForDomFallback(resolved.pane);
   const empty = render.loadingStateDetected
     || render.errorStateDetected
-    || render.emptyStateDetected
-    || rowCount === 0
+    || (!interactive && (render.emptyStateDetected || rowCount === 0))
     || semanticMismatch;
   const usable = isPaneScreenshotUsable({
+    interactive,
     rowCount,
     loadingStateDetected: render.loadingStateDetected,
     errorStateDetected: render.errorStateDetected,

package/src/cli/pane-functions/screenshot-types.ts

@@ -108,6 +108,11 @@ export type PaneScreenshotDataEvidence =
   | PaneScreenshotEvidence;
 
 export interface PaneScreenshotReadinessSignals {
+  /**
+   * A surface to operate rather than data to read (Layouts, Brokers): its rows
+   * and an empty-state marker inside it say nothing of whether it rendered.
+   */
+  interactive?: boolean;
   rowCount: number;
   loadingStateDetected: boolean;
   errorStateDetected: boolean;

package/src/cli/quote-answer.ts

@@ -14,8 +14,8 @@ import { knownGapForTicker } from "./known-gaps";
 import {
   futuresTryLine,
   isNoProviderError,
+  isUnsettledNoProvider,
   listingChoiceNotes,
-  listingReadNotes,
   ListingArgError,
   loadBareVenues,
   notTradedMessage,
@@ -29,6 +29,8 @@ import {
   type ListingVenue,
 } from "./listing-arg";
 import { withListingSuggestion } from "./not-a-ticker";
+import { notATickerWords } from "./company-name-hint";
+import { isNetworkFailure } from "../utils/network-failure";
 import type { MarketContext } from "./types";
 
 /** The text of an error, or null for none. */
@@ -76,23 +78,27 @@ 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.
   const also = (quote: Quote) => root && quote.instrumentType?.trim().toUpperCase() !== "INDEX"
     ? [indexRootAlsoLine(root, request.command)] : [];
   if (result.quote) {
-    // "CAR = Avis Budget Group, NASDAQ (also XETRA, ASX)" names the venue too, so it replaces "SXR8 -> XETRA".
-    const choice = venues ? await listingChoiceNotes(listing, market, result.quote, venues) : listingReadNotes(listing);
+    // "CAR = Avis Budget Group, NASDAQ (different companies on XETRA, ASX)" names the venue too, so it replaces "SXR8 -> XETRA".
+    const choice = await listingChoiceNotes(listing, market, result.quote, venues);
     const venue = choice.length > 0 ? null : bareListingNote(listing, result.quote);
     // A row saved as 247540:KRX is quoted from KOSDAQ, the board it trades on.
     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 +116,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}.`;
@@ -127,8 +133,12 @@ export async function answerQuote(
  * A company's name typed as one word (`Apple`) that the source says is not a
  * ticker, answered as the listing search names for it with the line saying so
  * ("Read "Apple" as AAPL:NASDAQ (Apple Inc.)."), as a name of several words
- * is. Null when the word names no company, or that listing has no quote
- * either: the word keeps its own "Not a ticker".
+ * is. A source that could not answer for the word (a timeout, a rate limit)
+ * says nothing of it, but when search resolves it to a company, it is read the
+ * same way; when that listing has no quote either, the row says the word is not
+ * a ticker and names the company. Null when the word names no company, or that
+ * listing has no quote though the source did say "not a ticker": the word keeps
+ * its own answer.
  */
 async function answerCompanyName(
   result: QuoteBatchResult,
@@ -136,19 +146,26 @@ 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;
+  if (!listing.typed || listing.exchange) return null;
+  const notATicker = !!notATickerSymbol(errorMessage(result.error) ?? "");
+  const unsettled = !notATicker && isUnsettledNoProvider(result.error);
+  if (!notATicker && !unsettled) return null;
   const named = await oneWordCompanyName(listing.typed, market);
-  if (!named) return null;
+  // A real ticker a source failed to quote is not a company's name, even when the company carries the word.
+  if (!named || (unsettled && named.symbol.toUpperCase() === listing.symbol.toUpperCase())) return null;
   // A listing on a venue the app cannot read is no answer: the word keeps its own "Not a ticker".
   const resolved = await resolveCliListing(named.key, null, market).catch((error: unknown) => {
     if (error instanceof ListingArgError) return null;
     throw error;
   });
-  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 found = resolved ? { ...resolved, readAs: named.readAs, ...named.meant ? { meant: named.meant } : {} } : null;
+  const [quoted] = found ? await market.dataProvider.getQuotesBatch([found.request], { forceRefresh: refresh, revalidate: true, datesChangeBasis }) : [];
+  if (found && quoted?.quote) return answerQuote(quoted, found, market, request, refresh, null, { datesChangeBasis });
+  if (!unsettled) return null;
+  const sentence = await notATickerWords(listing.typed, market);
+  return { result: { ...result, error: new Error(sentence) }, listing, notes: [] };
 }
 
 /** 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/cli/ticker-resolution.ts

@@ -85,7 +85,8 @@ export interface CliTicker {
   /**
    * A bare coin ticker (ETH) read as a listing that is not the coin, such as a
    * fund named for it: "ETH is Grayscale Ethereum Mini Trust ETF, not ethereum.
-   * For ethereum use ETH-USD." It is also the last of `notes`.
+   * For ethereum use ETH-USD." A live company that only shares the letters gets
+   * "Also a coin: LINK-USD" (`notTheCoinNote`). It is also the last of `notes`.
    */
   coinNote: string | null;
   /**
@@ -367,7 +368,7 @@ async function describeResolution(
   const formerIssuer = describeFormerIssuer(listing.symbol, payload, current);
   // One line: a company that left the symbol, else one that merged away from it.
   const line = tickerChangeLine(change) ?? formerIssuer?.note;
-  const coinNote = listing.exchange ? null : savedListingCoinNote(listing.symbol, resolved.ticker);
+  const coinNote = listing.exchange ? null : savedListingCoinNote(listing.symbol, resolved.ticker, { ended: !!resolved.ended });
   return { ...resolved, notes: [...line ? [line] : [], ...resolved.notes, ...coinNote ? [coinNote] : []], change, formerIssuer, coinNote,
     readAs: listing.readAs ?? null, bareSymbol: listing.exchange ? null : listing.symbol, otherVenues: resolved.otherVenues ?? null };
 }

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";
@@ -26,6 +27,7 @@ import { usePaneFocused } from "../../../state/app/activity";
 import { useTabCursorLink } from "../../../state/app/tab-cursor";
 import { useThemeColors, useThemeId } from "../../../theme/theme-context";
 import { themedSeriesColor, themeSeriesColors } from "../../../theme/series-colors";
+import { themeKeysDirection } from "../../../theme/themes";
 import { assignSeriesLineCues } from "./series-cues";
 import { chartSurfaceBackground, usePaneSurface } from "../../layout/pane/surface";
 import { CHART_WATERMARK_ROLE } from "../../../utils/screenshot-watermark";
@@ -204,10 +206,12 @@ function ThemedCompositeChart({
   timePick,
   pricePick,
   levels,
+  rangeStatisticsSeriesId,
   chartLayout,
   onChartLayoutChange,
 }: CompositeChartProps & { chartLayout: ChartLayoutPrefs; onChartLayoutChange: ChartLayoutUpdate }) {
   const activeThemeColors = useThemeColors();
+  const keysDirection = themeKeysDirection(useThemeId());
   const { cellWidthPx = 8, cellHeightPx = 18, pixelRatio = 1, fractionalViewport = false } = useUiCapabilities();
   const isDesktopWeb = useUiCapabilities().nativePaneChrome === true;
   const showTextFallback = useShowChartTextFallback();
@@ -337,6 +341,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 +369,7 @@ function ThemedCompositeChart({
       timelineSeries: marketTimelineSeries,
       rightOffsetRatio,
       valueScales,
+      referenceLevels: rangeStatisticsLevels,
     });
   }, [
     clipToViewport,
@@ -361,6 +380,7 @@ function ThemedCompositeChart({
     panelSeries,
     panels,
     rightOffsetRatio,
+    rangeStatisticsLevels,
     valueScales,
   ]);
   // Gutters follow the axes the scene actually built. Reading the series list
@@ -426,7 +446,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 +457,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 +709,7 @@ function ThemedCompositeChart({
     onActivate,
     timePick,
     pricePick,
-    levels,
+    levels: displayedLevels,
     visibleLegendSeries,
     visibleSeriesIds,
     onToggleSeries,
@@ -1016,6 +1036,8 @@ function ThemedCompositeChart({
           visibleSeriesIds={visibleSeriesIds}
           lineCues={lineCues}
           cellPlot={showTextFallback && !isDesktopWeb}
+          // A color-blind safe theme's blue and vermillion are no convention: a candle series keys them.
+          directionDownColor={keysDirection ? resolvedColors.negative : null}
           width={totalWidth}
           accessory={legendAccessory}
           accessoryWidth={legendAccessoryWidth}
@@ -1136,7 +1158,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/interactions.ts

@@ -17,6 +17,9 @@ export type CompositeChartInteraction =
   | "arm-line"
   | "arm-measure"
   | "arm-pencil"
+  | "arm-ray"
+  | "arm-rect"
+  | "arm-fib"
   | "arm-zoom"
   | "cycle-colour"
   | "clear-cursor"
@@ -366,6 +369,9 @@ export function resolveCompositeChartInteraction(event: {
   if (shifted && key === "z") return "arm-zoom";
   if (shifted && key === "d") return "arm-line";
   if (shifted && key === "p") return "arm-pencil";
+  if (shifted && key === "j") return "arm-ray";
+  if (shifted && key === "b") return "arm-rect";
+  if (shifted && key === "f") return "arm-fib";
   if (shifted && key === "h") return "arm-level";
   // Delete is the same act on a keyboard that has the key, or on a Mac with fn.
   if (key === "backspace" || key === "delete") return "delete-drawing";