@gloom-sh/terminal 0.19.1 → 0.19.3

package/src/time-series/studies/units.ts

@@ -0,0 +1,243 @@
+import { scalarPointValue } from "../alignment";
+import { resolveCurrencyUnit, US_CENTS } from "../../utils/currency-units";
+import { isCurrencyCode } from "../../utils/currency-pair";
+import { stablePriceFractionDigits } from "../../market-data/market/format";
+import type { ResolvedSeries, TimeSeriesPoint } from "../types";
+import {
+  GALLONS_PER_BARREL,
+  isPerBarrelUnit,
+  isPerGallonUnit,
+  quantityIdentity,
+  unitCurrencyToken,
+} from "../price-units";
+
+export function seriesCurrency(series: ResolvedSeries): string | null {
+  const grouped = series.unitGroup.match(/:([A-Z]{3})$/i)?.[1];
+  if (grouped) return grouped.toUpperCase();
+  if (!/^(?:price|currency-total|per-share)$/.test(series.unitGroup)) return null;
+  return series.unit.match(/^([A-Z]{3})(?:$|\/)/i)?.[1]?.toUpperCase() ?? null;
+}
+
+function unitFactorIdentity(value: string): string {
+  // "US cents", as futures terms word a grain's quote, is the USX the quote names.
+  const token = unitCurrencyToken(value) ?? value.trim();
+  // Three letters are a currency unless they spell a quantity: "bbl" is a barrel.
+  if (/^[A-Za-z]{3}$/.test(token) && quantityIdentity(token) === token.toLowerCase()) {
+    const { currency, divisor } = resolveCurrencyUnit(token);
+    return `${currency}:${divisor}`;
+  }
+  return quantityIdentity(token);
+}
+
+/** Whether a unit's factor is money (USD, GBp, US cents) rather than a quantity it buys. */
+function isCurrencyFactor(value: string): boolean {
+  const currency = /^([A-Z]{3}):\d+$/.exec(unitFactorIdentity(value))?.[1];
+  return !!currency && (currency === US_CENTS || isCurrencyCode(currency));
+}
+
+export function knownUnitSignature(series: Pick<ResolvedSeries, "unit" | "unitGroup">): string | null {
+  const unit = series.unit.trim();
+  if (!unit || /(?:^|\W)(?:currency|unknown|unspecified|n\/a)(?:$|\W)/i.test(unit)
+    || /^(?:units?|[-?]+)$/i.test(unit)) return null;
+  const parts = unit.split("/");
+  if (parts.some((part) => !part.trim() || /^[-?]+$/.test(part.trim()))) return null;
+
+  const monetary = series.unitGroup.match(/^(price|currency-total|per-share)(?::([^:]+))?$/);
+  // A futures contract writes its unit spaced ("USD / gallon"); a catalog series does not ("USD/gallon").
+  const currency = unitCurrencyToken(parts[0]!);
+  if (monetary && (!currency || (monetary[2] && unitFactorIdentity(monetary[2]) !== unitFactorIdentity(currency)))) return null;
+
+  // Currency alone does not establish a price's physical/share basis. A scalar
+  // multiplier cannot establish it either. Explicit USD/share price and EPS
+  // units, however, match despite different groups.
+  if (monetary?.[1] === "price" && !unit.includes("/")) return null;
+  const basis = monetary && !unit.includes("/") ? monetary[1] : "";
+  // Keep currency scale and compound order: GBp/GBX are pence, not pounds;
+  // USD/EUR cannot subtract EUR/USD.
+  return `${basis ?? ""}|${parts.map(unitFactorIdentity).join("/")}`;
+}
+
+/** A leg as an error names it: its ticker (HO=F), else its label. */
+export function legName(series: ResolvedSeries): string {
+  return series.listing?.symbol || series.label;
+}
+
+/** What a leg's unit is, in words: "is USD / gallon", "is in %", "is in USD per an unknown quantity". */
+function unitPhrase(series: ResolvedSeries, unit: string): string {
+  const text = unit.trim();
+  // A rate reads as itself (HO=F is USD / gallon); an amount or a scale is what a leg is in (REVENUE is in USD).
+  if (knownUnitSignature({ unit: text, unitGroup: series.unitGroup }) !== null) return text.includes("/") ? `is ${text}` : `is in ${text}`;
+  if (unitCurrencyToken(text) && /^price(?::|$)/.test(series.unitGroup)) return `is in ${text} per an unknown quantity`;
+  return "has no known unit";
+}
+
+function unitCurrency(series: ResolvedSeries, unit: string): string | null {
+  const token = unitCurrencyToken(unit.split("/")[0] ?? "");
+  return token ? unitFactorIdentity(token) : seriesCurrency(series);
+}
+
+/**
+ * Why two legs cannot be added or subtracted, naming each one's unit and the
+ * fix: a per-gallon leg beside a per-barrel one is 42 gallons short of it.
+ */
+export function unitMismatchMessage(
+  kind: "spread" | "formula",
+  left: { series: ResolvedSeries; unit: string },
+  right: { series: ResolvedSeries; unit: string },
+): string {
+  // Two fields of one listing are told apart by their labels.
+  const [leftName, rightName] = legName(left.series) === legName(right.series)
+    ? [left.series.label, right.series.label]
+    : [legName(left.series), legName(right.series)];
+  const named = `${leftName} ${unitPhrase(left.series, left.unit)} and ${rightName} ${unitPhrase(right.series, right.unit)}`;
+  const leftCurrency = unitCurrency(left.series, left.unit);
+  const rightCurrency = unitCurrency(right.series, right.unit);
+  const gallons = isPerGallonUnit(left.unit) && isPerBarrelUnit(right.unit) ? leftName
+    : isPerBarrelUnit(left.unit) && isPerGallonUnit(right.unit) ? rightName : null;
+  if (gallons && leftCurrency === rightCurrency) {
+    return `${named}: write ${GALLONS_PER_BARREL}*${gallons} to compare per barrel.`;
+  }
+  const subject = kind === "spread" ? "a spread" : "a formula";
+  if (leftCurrency && rightCurrency && leftCurrency !== rightCurrency) return `${named}: ${subject} does not convert currencies.`;
+  const known = knownUnitSignature({ unit: left.unit, unitGroup: left.series.unitGroup }) !== null
+    && knownUnitSignature({ unit: right.unit, unitGroup: right.series.unitGroup }) !== null;
+  return `${named}: ${subject} needs ${kind === "spread" ? "both" : "every leg"} in one${known ? "" : " known"} unit.`;
+}
+
+function unitFactors(unit: string): { numerator: string[]; denominator: string[] } {
+  const [numerator = "", ...denominator] = unit.split("/");
+  const factor = (value: string) => value.split("·").flatMap((part) => {
+    const normalized = part.trim();
+    if (!normalized || normalized === "1") return [];
+    return [normalized.toLowerCase() === "shares" ? "share" : normalized];
+  });
+  return {
+    numerator: factor(numerator),
+    denominator: denominator.flatMap(factor),
+  };
+}
+
+export interface SeriesUnit {
+  unit: string;
+  unitGroup: string;
+}
+
+const UNKNOWN_UNIT: SeriesUnit = { unit: "unknown", unitGroup: "derived-unit:unknown" };
+
+export function isPriceGroup(unitGroup: string): boolean {
+  return /^price(?::|$)/.test(unitGroup);
+}
+
+/**
+ * The unit of `left` times (`power` 1) or over (-1) `right`, the factors they
+ * share cancelling: USD / barrel over an FX rate's USD / EUR is EUR / barrel.
+ * Units are spaced as either side writes them ("USD / gallon"). A price over
+ * or times a price that leaves one currency per one quantity is a price in
+ * that currency; anything else is a derived unit, or a plain ratio.
+ */
+export function combinedUnit(left: SeriesUnit, right: SeriesUnit, power: 1 | -1): SeriesUnit {
+  if (!knownUnitSignature(left) || !knownUnitSignature(right)) return UNKNOWN_UNIT;
+  const leftFactors = unitFactors(left.unit);
+  const rightFactors = unitFactors(right.unit);
+  const numerator = [...leftFactors.numerator, ...(power < 0 ? rightFactors.denominator : rightFactors.numerator)];
+  const denominator = [...leftFactors.denominator, ...(power < 0 ? rightFactors.numerator : rightFactors.denominator)];
+  for (let index = numerator.length - 1; index >= 0; index -= 1) {
+    const match = denominator.findIndex((factor) => (
+      unitFactorIdentity(factor) === unitFactorIdentity(numerator[index]!)
+    ));
+    if (match < 0) continue;
+    numerator.splice(index, 1);
+    denominator.splice(match, 1);
+  }
+  const slash = [left.unit, right.unit].some((unit) => /\s\/\s/.test(unit)) ? " / " : "/";
+  const unit = denominator.length === 0
+    ? numerator.join("·") || "x"
+    : `${numerator.join("·") || "1"}${slash}${denominator.join("·")}`;
+  if (isPriceGroup(left.unitGroup) && isPriceGroup(right.unitGroup) && numerator.length === 1 && isCurrencyFactor(numerator[0]!)
+    && (denominator.length === 0 || (denominator.length === 1 && !isCurrencyFactor(denominator[0]!)))) {
+    return { unit, unitGroup: `price:${unitCurrencyToken(numerator[0]!) ?? numerator[0]!}` };
+  }
+  const groupFactor = (value: string) => {
+    const identity = unitFactorIdentity(value);
+    return (/^[A-Za-z]{3}$/.test(value.trim()) ? identity.replace(/:1$/, "") : identity).toLowerCase();
+  };
+  const groupNumerator = numerator.map(groupFactor).join("·");
+  const groupDenominator = denominator.map(groupFactor).join("·");
+  const group = groupDenominator ? `${groupNumerator || "1"}/${groupDenominator}` : groupNumerator;
+  return {
+    unit,
+    unitGroup: unit === "x" ? "ratio" : `derived-unit:${group}`,
+  };
+}
+
+export function ratioUnit(left: SeriesUnit, right: SeriesUnit): SeriesUnit {
+  return combinedUnit(left, right, -1);
+}
+
+/** An FX rate's unit: one currency per another, as USD / EUR. */
+function isRateUnit(unit: string): boolean {
+  const { numerator, denominator } = unitFactors(unit);
+  return numerator.length === 1 && denominator.length === 1 && isCurrencyFactor(numerator[0]!) && isCurrencyFactor(denominator[0]!);
+}
+
+/**
+ * Why a price times (`power` 1) or over (-1) an FX rate is no price, with how
+ * to convert it instead: a crack in USD / barrel over USDJPY=X (JPY / USD) is
+ * USD·USD / barrel·JPY, and times it JPY / barrel. A ratio, which cannot
+ * multiply, names the formula to write (`priceName` its numerator). Null when
+ * the rate converts the price, or either is not what this asks about.
+ */
+export function fxConversionIssue(price: SeriesUnit, rate: ResolvedSeries, power: 1 | -1, result: SeriesUnit, priceName?: string): string | null {
+  if (!isPriceGroup(price.unitGroup) || !isPriceGroup(rate.unitGroup) || !isRateUnit(rate.unit) || isPriceGroup(result.unitGroup)) {
+    return null;
+  }
+  const name = legName(rate);
+  const done = `${power < 0 ? "Dividing" : "Multiplying"} by ${name} (${rate.unit}) leaves ${result.unit}`;
+  const other = combinedUnit(price, rate, power < 0 ? 1 : -1);
+  if (isPriceGroup(other.unitGroup)) {
+    const fix = priceName ? `write (${priceName})${power < 0 ? "*" : "/"}${name}` : `${power < 0 ? "multiply" : "divide"} by ${name}`;
+    return `${done}; ${fix} instead to get ${other.unit}.`;
+  }
+  const currency = price.unitGroup.slice("price:".length) || "its currency";
+  return `${done}; ${price.unit} converts only with a rate that has ${currency} on one side.`;
+}
+
+/** The distinct currencies a unit still counts, once its factors cancel. */
+export function unitCurrencies(unit: string): Set<string> {
+  const { numerator, denominator } = unitFactors(unit);
+  return new Set([...numerator, ...denominator].filter(isCurrencyFactor).map((factor) => unitFactorIdentity(factor).split(":")[0]!));
+}
+
+/**
+ * The decimals a value worked out from prices prints at: the most its legs
+ * print, from two to four, and no more than a value of its own size needs:
+ * four under 10, two from 10. A crack of 4.9842 USD / gallon heating oil and
+ * 116.72 USD / barrel Brent reads 92.62; a gasoline-heating oil spread reads
+ * 1.7726. Undefined when a leg is not a price or the value has none yet.
+ */
+export function derivedValueDecimals(inputs: readonly ResolvedSeries[], points: readonly TimeSeriesPoint[]): number | undefined {
+  let digits = 0;
+  for (const input of inputs) {
+    if (!isPriceGroup(input.unitGroup) || input.transform !== "raw") return undefined;
+    const reference = latestScalarValue(input.points);
+    if (reference === undefined) return undefined;
+    digits = Math.max(digits, stablePriceFractionDigits({
+      assetCategory: input.priceAssetCategory,
+      currency: unitCurrencyToken(input.unit.split("/")[0] ?? "") ?? undefined,
+      referencePrice: reference,
+      sessionPrices: [reference],
+    }));
+  }
+  const size = latestScalarValue(points);
+  if (size === undefined) return undefined;
+  return Math.min(size < 10 ? 4 : 2, Math.max(2, digits));
+}
+
+/** The size of a series' last nonzero value, which its decimals are read from. */
+function latestScalarValue(points: readonly TimeSeriesPoint[]): number | undefined {
+  for (let index = points.length - 1; index >= 0; index -= 1) {
+    const value = scalarPointValue(points[index]!);
+    if (value !== null && Number.isFinite(value) && value !== 0) return Math.abs(value);
+  }
+  return undefined;
+}

package/src/time-series/studies/vwap.ts

@@ -0,0 +1,274 @@
+import { latestTradingSessionOpen } from "../../market-data/market/trading-sessions";
+import { CHART_RESOLUTION_STEP_MS, isIntradayResolution, type ManualChartResolution } from "../resolution";
+import { anchoredVwap, sessionVwap, type StudyBar, type VwapValue } from "../trader-studies";
+import { zonedDateTimeParts } from "../../utils/zoned-date-time";
+import type { ChartStudySpec, ResolvedSeries } from "../types";
+import { isFiniteNumber } from "../../utils/guards";
+import { ANCHOR_COLORS, derivedPoint, outputSeries, studyBars, type NumericSample } from "./shared";
+
+const DAY_MS = 86_400_000;
+/** Most anchors one anchored VWAP keeps; each draws its own line. */
+const MAX_VWAP_ANCHORS = 8;
+export const DEFAULT_PROFILE_ROWS = 24;
+
+/** Anchor times of an anchored VWAP, kept as `anchor1`, `anchor2`, ... so the spec stays numeric. */
+export function vwapAnchors(spec: Pick<ChartStudySpec, "parameters">): number[] {
+  return [...new Set(Object.entries(spec.parameters)
+    .filter(([key, value]) => /^anchor\d+$/.test(key) && isFiniteNumber(value))
+    .map(([, value]) => value as number))]
+    .sort((left, right) => left - right)
+    .slice(0, MAX_VWAP_ANCHORS);
+}
+
+export function withVwapAnchors(
+  parameters: ChartStudySpec["parameters"],
+  anchors: readonly number[],
+): ChartStudySpec["parameters"] {
+  const kept = Object.fromEntries(Object.entries(parameters).filter(([key]) => !/^anchor\d+$/.test(key)));
+  const sorted = [...new Set(anchors.filter(Number.isFinite))].sort((left, right) => left - right).slice(-MAX_VWAP_ANCHORS);
+  return { ...kept, ...Object.fromEntries(sorted.map((anchor, index) => [`anchor${index + 1}`, anchor])) };
+}
+
+function isIntradayInput(input: ResolvedSeries, marketResolution?: ManualChartResolution): boolean {
+  const resolution = input.historyResolution === undefined ? marketResolution : input.historyResolution;
+  if (resolution) return isIntradayResolution(resolution);
+  const cadence = input.timeBasis?.cadenceMs;
+  return cadence !== undefined && cadence < DAY_MS;
+}
+
+function localDay(time: number, timeZone: string | undefined): number {
+  if (!timeZone) return Math.floor(time / DAY_MS);
+  const { year, month, day } = zonedDateTimeParts(time, timeZone);
+  return Date.UTC(year, month - 1, day) / DAY_MS;
+}
+
+/**
+ * `step` at each of `times` (ascending) for a step function that never falls
+ * as time moves on, such as a session's open or a local day. It is asked at
+ * both ends of a run and a run whose ends agree takes that value throughout,
+ * so a few calendar lookups per session cover every bar. The live chart
+ * resolves on every quote, and a lookup per 1-minute bar took tens of
+ * milliseconds over a week.
+ */
+function risingSteps<T>(times: readonly number[], step: (time: number) => T): T[] {
+  const values = new Array<T>(times.length);
+  if (times.length === 0) return values;
+  const last = times.length - 1;
+  values[0] = step(times[0]!);
+  values[last] = step(times[last]!);
+  const fill = (from: number, to: number): void => {
+    if (to - from < 2) return;
+    if (values[from] === values[to]) {
+      values.fill(values[from]!, from + 1, to);
+      return;
+    }
+    const middle = (from + to) >> 1;
+    values[middle] = step(times[middle]!);
+    fill(from, middle);
+    fill(middle, to);
+  };
+  fill(0, last);
+  return values;
+}
+
+/** When the session holding `time` opened on the input's listing, or null for a venue without known hours. */
+function sessionOpenOf(input: ResolvedSeries): (time: number) => number | null {
+  const symbol = input.listing?.symbol;
+  const exchange = input.listing?.exchange || input.timeBasis?.exchange;
+  return (time) => latestTradingSessionOpen(symbol, exchange, time);
+}
+
+/** The bar spacing: the requested cadence, else the history's resolution, else a minute. */
+function barStep(input: ResolvedSeries): number {
+  return input.timeBasis?.cadenceMs
+    ?? (input.historyResolution ? CHART_RESOLUTION_STEP_MS[input.historyResolution] : undefined)
+    ?? 60_000;
+}
+
+/**
+ * Each bar's session, named by the open it follows, so the sums restart at
+ * the open and a bar before it continues the previous session: the regular
+ * open for stocks, the venue's published session open for futures (17:00
+ * Central on CME Globex). A venue without known hours starts over with each
+ * local day. The first session is left out when the history begins after its
+ * open, since its sums would be missing the bars before.
+ */
+function regularSessionKeys(bars: readonly StudyBar[], input: ResolvedSeries): Array<number | null> {
+  const step = barStep(input);
+  const times = bars.map((bar) => bar.time);
+  const opens = risingSteps(times, sessionOpenOf(input));
+  const days = opens.includes(null) ? risingSteps(times, (time) => localDay(time, input.timeBasis?.timeZone)) : [];
+  const keys = opens.map((open, index) => open ?? -1 - days[index]!);
+  const first = keys[0];
+  if (first !== undefined && first >= 0 && bars[0]!.time >= first + step) {
+    return keys.map((key) => key === first ? null : key);
+  }
+  return keys;
+}
+
+function vwapOutputs(
+  spec: ChartStudySpec,
+  input: ResolvedSeries,
+  bars: ReadonlyArray<{ sample: NumericSample }>,
+  values: readonly VwapValue[],
+  options: { id: string; label: string; color: string; bands: number; sessionOf?: (index: number) => number | null },
+): ResolvedSeries[] {
+  // A value opening a new session follows a missing one just before it, so
+  // the line restarts there instead of joining the sessions with a diagonal.
+  const at = (pick: (value: VwapValue) => number) => values.flatMap((value, position) => {
+    const bar = bars[value.index];
+    if (!bar) return [];
+    const point = derivedPoint(bar.sample, pick(value));
+    const previous = values[position - 1];
+    if (!previous || !options.sessionOf || options.sessionOf(previous.index) === options.sessionOf(value.index)) return [point];
+    const before = new Date(point.date.getTime() - 1);
+    return [{ ...derivedPoint(bar.sample, null), date: before, observedAt: before }, point];
+  });
+  const outputs = [outputSeries(spec, input, {
+    id: options.id,
+    label: options.label,
+    points: at((value) => value.value),
+    color: options.color,
+  })];
+  if (options.bands > 0) {
+    outputs.push(
+      outputSeries(spec, input, {
+        id: `${options.id}:upper`,
+        label: `${options.label} +${options.bands}σ`,
+        points: at((value) => value.value + value.deviation * options.bands),
+        color: options.color,
+      }),
+      outputSeries(spec, input, {
+        id: `${options.id}:lower`,
+        label: `${options.label} -${options.bands}σ`,
+        points: at((value) => value.value - value.deviation * options.bands),
+        color: options.color,
+      }),
+    );
+  }
+  return outputs;
+}
+
+function hasVolume(bars: readonly StudyBar[]): boolean {
+  return bars.some((bar) => bar.volume > 0);
+}
+
+export function resolveVwap(
+  spec: ChartStudySpec,
+  input: ResolvedSeries,
+  color: string,
+  nameInput: boolean,
+  marketResolution: ManualChartResolution | undefined,
+  warnings: string[],
+): ResolvedSeries[] {
+  const label = nameInput ? `VWAP ${input.label}` : "VWAP";
+  if (!isIntradayInput(input, marketResolution)) {
+    warnings.push(`${label} needs intraday bars: choose 1D or 1W, or a minute timeframe.`);
+    return [];
+  }
+  const bars = studyBars(input);
+  if (!hasVolume(bars)) {
+    warnings.push(`${label} needs traded volume, which ${input.label} does not report.`);
+    return [];
+  }
+  const keys = regularSessionKeys(bars, input);
+  const bands = Math.min(3, Math.max(0, Math.round(isFiniteNumber(spec.parameters.bands) ? spec.parameters.bands : 0)));
+  return vwapOutputs(spec, input, bars, sessionVwap(bars, (_bar, index) => keys[index] ?? null), {
+    id: spec.id,
+    label,
+    color,
+    bands,
+    sessionOf: (index) => keys[index] ?? null,
+  });
+}
+
+const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
+
+/** `Sep 30 09:30` on intraday bars, in the exchange's time; `Sep 30 2025` on daily ones. */
+function formatAnchor(anchor: number, input: ResolvedSeries, intraday: boolean): string {
+  const parts = zonedDateTimeParts(anchor, intraday ? input.timeBasis?.timeZone ?? "UTC" : "UTC");
+  const date = `${MONTHS[parts.month - 1]} ${parts.day}`;
+  return intraday
+    ? `${date} ${String(parts.hour).padStart(2, "0")}:${String(parts.minute).padStart(2, "0")}`
+    : `${date} ${parts.year}`;
+}
+
+/**
+ * Whether the loaded bars reach back to an anchor: a bar at or before it, or
+ * the first bar opening the same local day the anchor names.
+ */
+function historyReaches(bars: readonly StudyBar[], anchor: number, input: ResolvedSeries): boolean {
+  const first = bars[0];
+  if (!first) return false;
+  if (first.time <= anchor) return true;
+  const timeZone = input.timeBasis?.timeZone;
+  if (localDay(first.time, timeZone) !== localDay(anchor, timeZone)) return false;
+  const open = sessionOpenOf(input)(first.time);
+  return open === null || first.time < open + barStep(input);
+}
+
+export function resolveAnchoredVwap(
+  spec: ChartStudySpec,
+  input: ResolvedSeries,
+  color: string,
+  marketResolution: ManualChartResolution | undefined,
+  warnings: string[],
+): ResolvedSeries[] {
+  const anchors = vwapAnchors(spec);
+  if (anchors.length === 0) return [];
+  const bars = studyBars(input);
+  if (!hasVolume(bars)) {
+    warnings.push(`Anchored VWAP needs traded volume, which ${input.label} does not report.`);
+    return [];
+  }
+  const intraday = isIntradayInput(input, marketResolution);
+  const resolution = input.historyResolution ?? marketResolution;
+  const barMs = input.timeBasis?.cadenceMs ?? (resolution ? CHART_RESOLUTION_STEP_MS[resolution] : 0);
+  return anchors.flatMap((anchor, offset) => {
+    const label = `AVWAP ${formatAnchor(anchor, input, intraday)}`;
+    if (!historyReaches(bars, anchor, input)) {
+      warnings.push(`${label} starts before the loaded history; choose a longer range.`);
+      return [];
+    }
+    return vwapOutputs(spec, input, bars, anchoredVwap(bars, anchor, barMs), {
+      id: `${spec.id}:${anchor}`,
+      label,
+      color: offset === 0 ? color : ANCHOR_COLORS[offset % ANCHOR_COLORS.length]!,
+      bands: 0,
+    });
+  });
+}
+
+/** The input's bars, passed through for the chart to profile over what is in view. */
+export function resolveVolumeProfile(
+  spec: ChartStudySpec,
+  input: ResolvedSeries,
+  color: string,
+  warnings: string[],
+): ResolvedSeries[] {
+  if (input.transform !== "raw") {
+    warnings.push("Volume profile needs prices; switch the price series back to its own values.");
+    return [];
+  }
+  const bars = studyBars(input);
+  if (!hasVolume(bars)) {
+    warnings.push(`Volume profile needs traded volume, which ${input.label} does not report.`);
+    return [];
+  }
+  const rows = Math.min(100, Math.max(4, Math.round(isFiniteNumber(spec.parameters.rows) ? spec.parameters.rows : DEFAULT_PROFILE_ROWS)));
+  return [{
+    ...outputSeries(spec, input, {
+      label: "VP POC",
+      points: bars.map(({ sample }) => ({
+        ...derivedPoint(sample, sample.value),
+        open: sample.point.open,
+        high: sample.point.high,
+        low: sample.point.low,
+        close: sample.point.close,
+        volume: sample.point.volume,
+      })),
+      color,
+    }),
+    profile: { rows },
+  }];
+}

package/src/time-series/types.ts

@@ -265,6 +265,8 @@ export interface ResolvedSeries {
   /** Rejected valuation price inputs, retained independently of usable observations. */
   valuationPriceIssues?: import("./valuation-price").ValuationPriceIssue[];
   warning?: string;
+  /** When the copy the points came from was saved (ms), when its refresh failed and that copy answered. */
+  savedAt?: number;
   /** Listed in the legend so it can be restored, but not drawn. */
   hidden?: boolean;
   /**
@@ -324,6 +326,11 @@ export interface ChartResolutionResult {
   loading: boolean;
   errors: string[];
   warnings: string[];
+  /**
+   * The oldest saved copy a shown series answered from after its refresh
+   * failed (ms), which the chart's footer dates: "saved copy from …".
+   */
+  savedAt?: number;
   /**
    * Where a series' source starts after the range asked for, and why (a
    * publisher's cap on history), as `warnings` also carries it, so a report

package/src/types/config.ts

@@ -193,8 +193,13 @@ export interface OnboardingProgress {
   positionsImported?: number;
   accountStatus?: "signed-in" | "skipped";
   checkoutOpenedAt?: string;
-  /** Desks picked at "What do you trade?", in the order picked; empty when skipped. */
+  /** Desks picked at "What do you trade most?", in the order picked; empty when skipped. */
   desks?: string[];
+  /**
+   * Opened again from Settings (Run Setup Again) after setup was done: every
+   * step can be left, and the layouts are rebuilt in place.
+   */
+  rerun?: boolean;
 }
 
 /**
@@ -231,8 +236,19 @@ export interface TelemetryConfig {
    * both off; absent means on.
    */
   usage?: boolean;
-  /** Ticker-level research counts. Only an explicit true opts in; absent is OFF. */
+  /**
+   * Ticker-level research counts (Attention Counts). On by default: `false`
+   * turns them off and `true` is an explicit on. While unset, an account is
+   * counted only once this installation has shown it the one-time notice.
+   * Cloud sync carries only whether it is off, so an off reaches the
+   * account's other devices.
+   */
   attention?: boolean;
+  /**
+   * The accounts this installation has shown the Attention Counts notice to,
+   * oldest first. Kept on this device; never synced or sent.
+   */
+  attentionNoticeShownTo?: string[];
 }
 
 /**

package/src/types/data-provider.ts

@@ -68,6 +68,11 @@ export interface SecFilingItem {
    * Frankfurt reads SK hynix's). Absent on the listing's own filings.
    */
   companyFrom?: CompanyFrom;
+  /**
+   * A current report's press release (its EX-99.1), when its index names one:
+   * the page the results or the news are on, not the cover page.
+   */
+  pressReleaseUrl?: string;
 }
 
 export interface SecFilingDocument {
@@ -137,6 +142,9 @@ export interface EarningsEvent {
   timing: "BMO" | "AMC" | "TNS" | "";
 }
 
+/** The reads a provider may send in batches (`DataProvider.batchesReads`). */
+export type BatchedReadMethod = "getPriceHistory" | "getOptionsChain";
+
 export interface MarketDataRequestContext {
   brokerId?: string;
   brokerInstanceId?: string;
@@ -155,6 +163,12 @@ export interface MarketDataRequestContext {
   historySession?: "extended";
   /** The listing's company, from its own quote: an SEC lookup for a non-US listing checks the registrant against it. */
   listingName?: string;
+  /**
+   * The caller asks many reads like this one in the same moment (a board's
+   * rows), having checked `batchesReads`: a provider that batches them may
+   * hold this one a moment to send it with the others.
+   */
+  batch?: boolean;
   /**
    * The caller prints what the quote's move is from: a short-lived process
    * (the CLI) waits briefly for the daily closes that date a previous close
@@ -259,6 +273,15 @@ export interface AssetDataProvider {
   primaryMarketSourceName?(): string | null | Promise<string | null>;
   getCachedFinancialsForTargets?(targets: CachedFinancialsTarget[], options?: { allowExpired?: boolean; includeStaleQuotes?: boolean }): Map<string, TickerFinancials> | Promise<Map<string, TickerFinancials>>;
   getQuotesBatch?(targets: QuoteSubscriptionTarget[], options?: QuoteBatchOptions): Promise<QuoteBatchResult[]>;
+  /**
+   * Whether reads of `method` asked with others in one moment (context
+   * `batch`) go out as batch requests (trailing history, dated option
+   * expiries), so a caller that otherwise keeps a few in flight may ask them
+   * all at once. A router answers true only when every source it could ask
+   * for them does; a remote transport asks the process that owns the router.
+   * Absent or false: ask a few at a time, without `batch`.
+   */
+  batchesReads?(method: BatchedReadMethod): boolean | Promise<boolean>;
   getTickerFinancialsBatch?(targets: CachedFinancialsTarget[], options?: { forceRefresh?: boolean; datesChangeBasis?: boolean }): Promise<TickerFinancialsBatchResult[]>;
   getTickerFinancials(ticker: string, exchange?: string, context?: MarketDataRequestContext): Promise<TickerFinancials>;
   getQuote(ticker: string, exchange?: string, context?: MarketDataRequestContext): Promise<Quote>;