@gloom-sh/terminal 0.18.5 → 0.19.1

package/src/time-series/studies.ts

@@ -400,15 +400,21 @@ function resolveVolume(spec: ChartStudySpec, input: ResolvedSeries, color: strin
   // No bar has volume to plot (spot FX quotes 0 for every bar; a coin's window
   // can miss every bar's), so the study adds no panel rather than an empty one.
   if (input.points.length > 0 && !input.points.some((point) => isFiniteNumber(point.volume) && point.volume !== 0)) return [];
+  // Left to its own colour, volume follows the candles: the price's colour for
+  // a bar that rose, the falling colour for one that fell. A colour picked for it stays flat.
+  const directional = !spec.color;
   const points = [...input.points]
     .sort((left, right) => left.date.getTime() - right.date.getTime())
     .flatMap((point) => isFiniteNumber(point.volume)
-      ? [derivedPoint({ point, value: point.volume }, point.volume)]
+      ? [{
+        ...derivedPoint({ point, value: point.volume }, point.volume),
+        ...(directional && isFiniteNumber(point.open) && isFiniteNumber(point.close) && point.close < point.open ? { fell: true } : {}),
+      }]
       : []);
   return [outputSeries(spec, input, {
     label: nameInput ? `Volume ${input.label}` : "Volume",
     points,
-    color,
+    color: directional ? input.color : color,
     unit: input.volumeUnit ?? "",
     unitGroup: "volume",
     style: "columns",

package/src/time-series/total-return.ts

@@ -0,0 +1,160 @@
+import type { CorporateActionsData } from "../types/financials";
+import { cashInMajorUnits } from "../utils/dividend-cash";
+import { resolveCurrencyUnit } from "../utils/currency-units";
+import { logFailure } from "../utils/log-failure";
+import { dividendReferencePrice } from "../utils/trailing-dividend";
+import { observationDate } from "./price-comparison";
+import { CHART_RESOLUTION_STEP_MS, chartBarSizeStepMs } from "./resolution";
+import type { ResolvedSeries, TimeSeriesPoint } from "./types";
+
+/** One cash distribution per share: its ex-date (`YYYY-MM-DD`) and its amount in the listing's major currency unit. */
+export interface CashDistribution {
+  exDate: string;
+  amount: number;
+}
+
+export interface TotalReturnOptions {
+  /** The session day a bar belongs to, `YYYY-MM-DD`. */
+  dayOf: (point: TimeSeriesPoint) => string;
+  /**
+   * A bar's price in the distributions' currency unit, or null when the two
+   * currencies differ (nothing is converted).
+   */
+  cashPrice: (price: number) => number | null;
+  /**
+   * Bars longer than a session (weekly, monthly) are dated at their start, so a
+   * distribution belongs to the bar that holds its ex-date, not the first one
+   * dated on or after it. This is how many days a bar holds; the last bar holds
+   * that many from its own date, and a distribution after that precedes no bar.
+   */
+  barDays?: number;
+  /** Today, `YYYY-MM-DD`: a distribution dated after it has not gone ex. */
+  asOf?: string;
+}
+
+export interface TotalReturnResult {
+  points: TimeSeriesPoint[];
+  /** Distributions reinvested inside the series; one before its first bar or after its last is not. */
+  applied: number;
+}
+
+/** The day a bar of `barDays` days dated `day` ends on; 30-day multiples are calendar months. */
+function barEnd(day: string, barDays: number): string {
+  const end = new Date(`${day}T00:00:00Z`);
+  if (barDays >= 28 && barDays % 30 === 0) end.setUTCMonth(end.getUTCMonth() + barDays / 30);
+  else end.setUTCDate(end.getUTCDate() + barDays);
+  return end.toISOString().slice(0, 10);
+}
+
+function scaled(value: number | null | undefined, factor: number): number | null | undefined {
+  return typeof value === "number" && Number.isFinite(value) ? value * factor : value;
+}
+
+/**
+ * A price series as its total return: every cash distribution is reinvested at
+ * the close of its ex-date bar, so the series moves by (close + cash) over the
+ * bar before. Each price is multiplied by the shares the cash has bought
+ * since the series began, which leaves its first bar as it was; volume is
+ * left alone. A distribution dated at or before the first bar precedes the
+ * series, so nothing is reinvested for it.
+ */
+export function reinvestDistributions(
+  points: readonly TimeSeriesPoint[],
+  distributions: readonly CashDistribution[],
+  { dayOf, cashPrice, barDays, asOf }: TotalReturnOptions,
+): TotalReturnResult {
+  const ordered = [...points].sort((left, right) => left.date.getTime() - right.date.getTime());
+  const holdingBar = barDays !== undefined && barDays > 1;
+  const cash = distributions
+    .filter((entry) => /^\d{4}-\d{2}-\d{2}$/.test(entry.exDate) && Number.isFinite(entry.amount) && entry.amount > 0
+      && (asOf === undefined || entry.exDate <= asOf))
+    .sort((left, right) => left.exDate.localeCompare(right.exDate));
+  const days = ordered.map(dayOf);
+  let factor = 1;
+  let applied = 0;
+  let next = 0;
+  const adjusted = ordered.map((point, index) => {
+    const barDay = days[index]!;
+    const before = holdingBar ? days[index + 1] ?? barEnd(barDay, barDays!) : null;
+    while (next < cash.length) {
+      const entry = cash[next]!;
+      if (before !== null ? entry.exDate >= before : entry.exDate > barDay) break;
+      if (index === 0) { next += 1; continue; }
+      const close = point.close ?? point.value;
+      // A bar with no price leaves the cash for the next bar that has one.
+      if (typeof close !== "number" || !Number.isFinite(close) || close <= 0) break;
+      // Cash in another currency than the price buys nothing: the series stays a price series.
+      const price = cashPrice(close);
+      if (price !== null && price > 0) {
+        factor *= 1 + entry.amount / price;
+        applied += 1;
+      }
+      next += 1;
+    }
+    if (factor === 1) return point;
+    return {
+      ...point,
+      value: scaled(point.value, factor) ?? null,
+      ...point.rawValue !== undefined ? { rawValue: scaled(point.rawValue, factor) ?? null } : {},
+      ...point.open !== undefined ? { open: scaled(point.open, factor) } : {},
+      ...point.high !== undefined ? { high: scaled(point.high, factor) } : {},
+      ...point.low !== undefined ? { low: scaled(point.low, factor) } : {},
+      ...point.close !== undefined ? { close: scaled(point.close, factor) } : {},
+    };
+  });
+  return { points: adjusted, applied };
+}
+
+export interface TotalReturnOutcome {
+  series: ResolvedSeries;
+  /** Why the series stays a price series, when it does. */
+  notice?: string;
+}
+
+const DAY_MS = 86_400_000;
+
+/** How many days a bar holds when it is longer than a session (a month counts as 30), so a distribution belongs to the bar holding its ex-date. */
+function barDaysLongerThanSession(series: Pick<ResolvedSeries, "barSize" | "historyResolution">): number | undefined {
+  const step = series.barSize ? chartBarSizeStepMs(series.barSize)
+    : series.historyResolution ? CHART_RESOLUTION_STEP_MS[series.historyResolution] : null;
+  return step !== null && step > DAY_MS ? Math.round(step / DAY_MS) : undefined;
+}
+
+/**
+ * A price series as its total return, from the cash history its listing pays.
+ * The series says which basis it ended up on: `total` once its distributions
+ * are reinvested (a listing that pays none is its price), `price` with the
+ * reason when the history cannot be read, covers no distributions, or is in
+ * another currency than the prices. Nothing is converted.
+ */
+export async function totalReturnSeries(
+  series: ResolvedSeries,
+  loadActions: () => Promise<CorporateActionsData | null>,
+  priceCurrency: string | undefined,
+  asOf: Date,
+): Promise<TotalReturnOutcome> {
+  const priceOnly = (notice: string): TotalReturnOutcome => ({ series: { ...series, returnBasis: "price" }, notice });
+  const actions = await loadActions().catch(logFailure("total-return", "Loading distribution history failed", null));
+  if (!actions) return priceOnly("distribution history unavailable; showing the price return.");
+  const cash = cashInMajorUnits(actions);
+  const dividends = Array.isArray(cash.dividends) ? cash.dividends : [];
+  if (cash.coverage?.dividends === "unavailable" || (cash.coverage?.dividends !== "available" && dividends.length === 0)) {
+    return priceOnly("distribution history unavailable; showing the price return.");
+  }
+  const currency = resolveCurrencyUnit(cash.currency).currency;
+  if (dividends.length > 0 && !currency) return priceOnly("distribution currency unknown; showing the price return.");
+  if (dividends.length > 0 && !resolveCurrencyUnit(priceCurrency).currency) {
+    return priceOnly("price currency unknown; showing the price return.");
+  }
+  if (dividends.length > 0 && dividendReferencePrice(1, priceCurrency, currency) === null) {
+    return priceOnly(`distributions are in ${currency}, not the price currency; showing the price return.`);
+  }
+  const { points } = reinvestDistributions(series.points, dividends, {
+    dayOf: (point) => observationDate(point.date.getTime(), series),
+    cashPrice: (price) => dividendReferencePrice(price, priceCurrency, currency),
+    barDays: barDaysLongerThanSession(series),
+    asOf: asOf.toISOString().slice(0, 10),
+  });
+  // "ECC Close" is its price: a label the chart wrote from the field says what the series is now.
+  return { series: { ...series, points, returnBasis: "total", label: series.label.replace(/ (?:Close|Price|Open|High|Low)$/, " Total return") } };
+}

package/src/time-series/transforms.ts

@@ -1,6 +1,7 @@
 import type { ResolvedSeries, SeriesTransform, TimeSeriesPoint } from "./types";
 import { calendarMonthsBefore } from "../utils/calendar-date";
 import { isFiniteNumber } from "../utils/guards";
+import { isOhlcSeriesStyle } from "./spec";
 
 const DAY_MS = 24 * 60 * 60 * 1_000;
 // Volume is separate supporting data, not another price. A volume series has
@@ -166,9 +167,7 @@ export function applyResolvedSeriesTransform(
     unit: percent ? "%" : transform === "index100" ? "index" : "log",
     unitGroup: percent ? "percent" : transform === "index100" ? "index" : "log",
     dataShape: "scalar",
-    style: series.style === "candles" || series.style === "ohlc" || series.style === "hlc"
-      ? "line"
-      : series.style,
+    style: isOhlcSeriesStyle(series.style) ? "line" : series.style,
     points: applySeriesTransform(series.points, transform, options),
   };
 }

package/src/time-series/types.ts

@@ -10,7 +10,7 @@ export type SeriesPeriod = "auto" | "daily" | "weekly" | "monthly" | "quarterly"
  * "band" draws a line through each point's value inside a shaded range from
  * its `low` to its `high`: an average within its historical range.
  */
-export type SeriesStyle = "line" | "area" | "step" | "columns" | "points" | "candles" | "ohlc" | "hlc" | "band";
+export type SeriesStyle = "line" | "area" | "step" | "columns" | "points" | "candles" | "hollow" | "heikin-ashi" | "ohlc" | "hlc" | "band";
 export type SeriesTransform = "raw" | "percent" | "index100" | "yoy" | "qoq" | "log";
 export type SeriesAxis = "auto" | "left" | "right";
 export type SeriesInterpolation = "none" | "step-after";
@@ -110,6 +110,11 @@ export interface ChartViewportSpec {
   maxPoints?: number;
   /** Intraday market history includes pre-market and after-hours bars where the venue has them. */
   extendedHours?: boolean;
+  /**
+   * Security price series are drawn as total returns: each cash distribution
+   * is reinvested at the close of its ex-date bar. Price returns otherwise.
+   */
+  totalReturn?: boolean;
 }
 
 export interface ChartSpec {
@@ -141,6 +146,8 @@ export interface TimeSeriesPoint {
   low?: number | null;
   close?: number | null;
   volume?: number | null;
+  /** The bar this figure traded in closed below its open: volume draws it in the falling colour. */
+  fell?: boolean;
   periodLabel?: string;
   /**
    * A financial statement period as the FA columns name it: `FY2025`, `Q3 FY26`,
@@ -183,6 +190,12 @@ export interface ResolvedSeries {
   unit: string;
   /** Unit of rawValue, retained when presentation transforms change unit. */
   rawUnit?: string;
+  /**
+   * What a price series' returns are, set when the chart asked for total
+   * returns: `total` once its distributions are reinvested, `price` when the
+   * source gave none to reinvest (`warning` says why).
+   */
+  returnBasis?: "total" | "price";
   unitGroup: string;
   /**
    * The unit the legend states beside each value, read bare as FUT prints its
@@ -311,6 +324,14 @@ export interface ChartResolutionResult {
   loading: boolean;
   errors: string[];
   warnings: string[];
+  /**
+   * 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
+   * says it where it would otherwise print a range that quietly starts later.
+   */
+  coverageNotices?: string[];
+  /** What the price levels of a total-return chart without a comparison are (`warnings` also carries it). */
+  returnBasisNotice?: string;
   /**
    * Each charted listing that no longer trades: its symbol and label
    * ("Delisted Oct 27, 2022"), which `warnings` carries as "TWTR: Delisted Oct 27, 2022".

package/src/types/company-from.ts

@@ -0,0 +1,40 @@
+/**
+ * The listing a pane's company data comes from when it is not the listing on
+ * screen: a receipt or a foreign line (SKHY, HY9H in Frankfurt) reads its
+ * company's home line (000660 on KRX) for news, filings, holders, hiring and
+ * the other company panes. Gloom Cloud names it on those answers.
+ */
+export interface CompanyFrom {
+  symbol: string;
+  /** The venue's code (KRX, FWB2, NASDAQ). */
+  exchange: string;
+  /** The company's name. */
+  name?: string;
+}
+
+const US_VENUES = new Set(["NASDAQ", "NYSE", "AMEX", "ARCA", "BATS", "CBOE", "IEX"]);
+
+/** The listing as the note names it: `000660 KRX`, or `SKHY` on a US venue. */
+export function companyFromLabel(from: CompanyFrom): string {
+  const exchange = from.exchange.trim().toUpperCase();
+  return exchange && !US_VENUES.has(exchange) ? `${from.symbol} ${exchange}` : from.symbol;
+}
+
+/** The note's listing from an answer's field, or null when the answer names none or something malformed. */
+export function readCompanyFrom(value: unknown): CompanyFrom | null {
+  if (!value || typeof value !== "object") return null;
+  const { symbol, exchange, name } = value as Record<string, unknown>;
+  if (typeof symbol !== "string" || !symbol.trim() || typeof exchange !== "string") return null;
+  return { symbol: symbol.trim(), exchange: exchange.trim(), ...(typeof name === "string" && name.trim() ? { name: name.trim() } : {}) };
+}
+
+/**
+ * What a report says under company data read from another listing, as the
+ * pane's footer does: "Company data from 000660 KRX (SK hynix)." Empty when
+ * the data is the listing's own, so a report's notes spread it as they are.
+ */
+export function companyDataNotes(from: CompanyFrom | null | undefined): string[] {
+  if (!from) return [];
+  const listing = companyFromLabel(from);
+  return [`Company data from ${listing}${from.name && from.name !== from.symbol ? ` (${from.name})` : ""}.`];
+}

package/src/types/data-provider.ts

@@ -1,3 +1,4 @@
+import type { CompanyFrom } from "./company-from";
 import type { ExchangeRateSnapshot } from "./exchange-rate";
 import type {
   AnalystResearchData,
@@ -61,6 +62,12 @@ export interface SecFilingItem {
    * series list reaches).
    */
   fundSeries?: boolean;
+  /**
+   * The company's home line the filing was read from, when the listing asked
+   * is a receipt or a foreign line with no filer of its own (HY9H in
+   * Frankfurt reads SK hynix's). Absent on the listing's own filings.
+   */
+  companyFrom?: CompanyFrom;
 }
 
 export interface SecFilingDocument {

package/src/types/financials.ts

@@ -1,3 +1,4 @@
+import type { CompanyFrom } from "./company-from";
 import type { PerpBoardRow } from "../api-client/perps";
 import type { PriceBasis } from "./instrument";
 
@@ -87,6 +88,26 @@ export interface DepositaryPair {
   ordinary: string[];
 }
 
+/**
+ * A Buenos Aires CEDEAR's ratio from BYMA's published list, as Gloom Cloud
+ * serves it: 20 AAPL:BYMA are 1 Apple share. Its market cap is the company's,
+ * in the currency of the listing it stands for.
+ */
+export interface CedearRatio {
+  /** The CEDEAR's listing: AAPL:BYMA. */
+  listing: string;
+  /** CEDEARs that make `shares` of the company's shares: 20 for Apple. */
+  receipts: number;
+  /** The company's shares `receipts` CEDEARs stand for: 1 for Apple, 8 for BABA's 9 (one receipt of 8 shares). */
+  shares: number;
+  /** The company as the list names it: "Apple Inc.". */
+  company: string;
+  /** The listing it stands for, as a ticker: AAPL, VALE3.SA. */
+  underlying: string;
+  /** The date of BYMA's list. */
+  listedAt: string;
+}
+
 /** How a depositary receipt relates to the ordinary shares, as Gloom Cloud states it. */
 interface DepositaryReceiptFacts {
   /** Whether the listing is a depositary receipt; absent when unknown. */
@@ -95,6 +116,8 @@ interface DepositaryReceiptFacts {
   adrRatio?: number;
   /** The receipt and its home lines, on the receipt's records and each home line's. */
   depositaryPair?: DepositaryPair;
+  /** A Buenos Aires CEDEAR's ratio, on its records. */
+  cedearRatio?: CedearRatio;
 }
 
 export interface Quote extends DepositaryReceiptFacts {
@@ -330,7 +353,12 @@ export interface Fundamentals extends DepositaryReceiptFacts {
   /** Set where Gloom Cloud checked `enterpriseValue` against market cap + total debt - cash; pairs with that value only. */
   enterpriseValueCheck?: EnterpriseValueCheck;
   /** Explicit provider retractions; omitted fields alone remain eligible for fallback. */
-  unavailableFields?: Array<"enterpriseValue" | "enterpriseToRevenue">;
+  unavailableFields?: Array<"enterpriseValue" | "enterpriseToRevenue" | "marketCap">;
+  /**
+   * Why `marketCap` is retracted, with "marketCap" in `unavailableFields`: a depositary receipt its source priced as
+   * an ordinary share (the receipt's price times the company's ordinary shares), with no ratio to convert them.
+   */
+  marketCapUnavailable?: "receipt-priced-as-ordinary";
   operatingCashFlow?: number;
   freeCashFlow?: number;
   dividendYield?: number;
@@ -345,6 +373,18 @@ export interface Fundamentals extends DepositaryReceiptFacts {
   revenue?: number;
   netIncome?: number;
   eps?: number;
+  /**
+   * Where `eps` and `trailingPE` come from: `filed-quarters` when `eps` is the
+   * diluted EPS of the last four filed quarters (or the fiscal year they end
+   * with), as PEB and GE read the statements, its last period ending
+   * `trailingEpsPeriodEnd`, and `trailingPE` the price over it; `served` when
+   * those quarters give none (or one that cannot be priced: see
+   * time-series/filed-trailing-eps) and both are Gloom Cloud's trailing
+   * figures, including a P/E it serves with no EPS (a fund's). Absent when
+   * there is neither an EPS nor a P/E.
+   */
+  trailingEpsSource?: "filed-quarters" | "served";
+  trailingEpsPeriodEnd?: string;
   operatingMargin?: number;
   profitMargin?: number;
   revenueGrowth?: number;
@@ -419,6 +459,8 @@ export interface HolderData extends DepositaryReceiptFacts {
   asOf?: string;
   summary?: HolderSummary;
   holders: HolderRecord[];
+  /** The company's home line the data is read from, when not the listing asked (a receipt, a foreign line). */
+  companyFrom?: CompanyFrom;
 }
 
 interface AnalystPriceTarget {
@@ -497,6 +539,8 @@ export interface DeclaredDividendAction {
   declarationDate?: string;
   recordDate?: string;
   payDate?: string;
+  /** A one-off beside the regular payments (AIOK's $3.50), as the server marks it. */
+  special?: true;
 }
 
 export interface SplitAction {
@@ -556,10 +600,24 @@ export interface CorporateActionsData {
   dividends: DividendAction[];
   /** Declared and unpaid, for the listings Gloom Cloud has them for; absent elsewhere and from older servers. */
   declaredDividends?: DeclaredDividendAction[];
+  /**
+   * What each paid row was declared as when the company declares in another
+   * currency than the listing pays (BP's dollars beside its London pence), per
+   * ordinary share, keyed by the paid row's ex-date. Absent elsewhere and from older servers.
+   */
+  declaredCash?: DeclaredCash;
+  /** Set when `dividends` is the last good history standing in for a refresh that could not read it: when that history was read. */
+  dividendsAsOf?: string;
   splits: SplitAction[];
   earnings: EarningsAction[];
 }
 
+/** Paid rows as their company declared them, in `currency` (its major unit). */
+export interface DeclaredCash {
+  currency: string;
+  rows: DividendAction[];
+}
+
 export interface CompanyProfile {
   description?: string;
   /**

package/src/types/headless.ts

@@ -34,6 +34,12 @@ export interface HeadlessPaneArgumentDef {
   examples?: readonly string[];
 }
 
+/** A list the catalog prints under a function's options, such as the sector names a screen's criteria match. */
+export interface HeadlessPaneReference {
+  title: string;
+  items: readonly string[];
+}
+
 export interface HeadlessPaneOptionValue {
   value: string;
   aliases?: string[];
@@ -83,6 +89,8 @@ export interface HeadlessPaneOptionDef {
    * absent.
    */
   valueWords?: number;
+  /** The value is a comma list (`--metric trailingPE,dividendYieldPercent`), and the flag typed again adds to it. */
+  list?: boolean;
   /** The option in use as typed after the function, such as `--expiration 2028-01-21`; the catalog shows it as an example. */
   example?: string;
   /** The example runs without the function's optional argument, as an option that works only then does (`fn INS --side sell`). */
@@ -138,8 +146,10 @@ export interface HeadlessPaneContext {
    * known. A code several companies list (BDI) throws asking which, with
    * `quote`'s message; `argumentWith(key)` is the function's argument naming
    * that listing instead (`BDI:TSX`), for the retry each listing offers.
+   * `coinNote` is what `quote` says of a bare coin ticker read as a listing
+   * that is not the coin (ETH, the Grayscale fund), for the report's warnings.
    */
-  resolveListing?: (symbol: string, argumentWith: (key: string) => string) => Promise<{ symbol: string; exchange?: string; name?: string } | null>;
+  resolveListing?: (symbol: string, argumentWith: (key: string) => string) => Promise<{ symbol: string; exchange?: string; name?: string; coinNote?: string } | null>;
   /**
    * What a plugin keeps on this device only (its `ctx.resume` state, never
    * synced), such as ALRT's log of the alerts the app fired; null when none.
@@ -393,6 +403,12 @@ export interface HeadlessPaneFreshness {
    * `newest story` dates a news list `newest story Tue 29 Sep 2026 20:17 UTC`.
    */
   asOfLabel?: string;
+  /**
+   * Say when the rows were retrieved too, after the newest one's date: a list
+   * dated by its newest filing was not read then (`newest filing Tue 27 Oct
+   * 2026 · retrieved Wed 28 Oct 2026 19:07 UTC`).
+   */
+  retrievedToo?: boolean;
   /** What the figures are, said after the status: `funding = current estimate, pays 08:00 UTC`. */
   note?: string;
   /**
@@ -602,6 +618,8 @@ export interface HeadlessSeries {
   interval?: string;
   /** Decimal places the text report prints the latest value to (a correlation to 3); JSON and CSV keep every digit. */
   textDecimals?: number;
+  /** The text report prints the latest value as the tables print an amount (63.33B), for a company's reported total; JSON and CSV keep every digit. */
+  textCompact?: boolean;
   /** Each point's `value` is its bar's close: `--csv` and `--ndjson` write Close alone, JSON keeps both. */
   valueIsClose?: boolean;
   points: HeadlessSeriesPoint[];
@@ -615,6 +633,8 @@ export interface HeadlessSeriesResult extends HeadlessPaneResultBase {
 export interface HeadlessSnapshotResult extends HeadlessPaneResultBase {
   asOf: string | number | Date;
   items: HeadlessPaneRow[];
+  /** What the report says when `items` is empty, in place of "No data.": why there are none. */
+  empty?: string;
 }
 
 export interface HeadlessPaneResultByShape {
@@ -640,6 +660,8 @@ export interface HeadlessPaneDefinition<Shape extends HeadlessPaneShape = Headle
     intents?: string[];
     dataRequirements?: string[];
     limitations?: string[];
+    /** Names an option's values match, listed by the catalog under each title: EQS's sectors and industries. */
+    reference?: HeadlessPaneReference[];
     screenshotReadiness?: "ready" | "partial" | "live-dom" | "unsupported";
   };
   /**
@@ -672,9 +694,11 @@ export interface HeadlessPaneDefinition<Shape extends HeadlessPaneShape = Headle
   /**
    * A listing the function has no data for, answered before any request with
    * what exists instead: OPX and OVDV answer a coin nothing lists options on
-   * (SOL-USD) with BTC and ETH options. `key` is the listing as read.
+   * (SOL-USD) with BTC and ETH options, and OVDV, VCA and HIVG an FX pair with
+   * the currency funds' options. `key` is the listing as read; `details` is
+   * the line after `message`, left out when the message says it all.
    */
-  refuseSymbol?(key: string): { message: string; details: string } | null;
+  refuseSymbol?(key: string): { message: string; details?: string } | null;
   /**
    * `fn` exits 1 when the report has no name with data: no rows, or every row
    * is one of `unavailableSymbols`. A list that gives data for some names

package/src/types/news-source.ts

@@ -1,4 +1,5 @@
 export type {
+  NewsAccess,
   NewsArticle,
   NewsQuery,
   NewsQueryState,

package/src/types/plugin.ts

@@ -20,6 +20,7 @@ export type {
   HeadlessPaneOptionType,
   HeadlessPaneOptionValue,
   HeadlessPaneOptionValues,
+  HeadlessPaneReference,
   HeadlessPaneResult,
   HeadlessPaneResultByShape,
   HeadlessPaneRow,
@@ -529,6 +530,14 @@ export interface PaneTemplateDef {
   description: string;
   keywords?: string[];
   shortcut?: PaneTemplateShortcut;
+  /**
+   * False leaves the function out of every list and search of functions
+   * (command-bar browse, search and assistant, Help, `gloom catalog` and
+   * search, the plugin directory, chat suggestions) while typing its code
+   * still opens it, `fn` and `shot` still run it and its help still answers.
+   * ATTN until it publishes (attention/listing.ts).
+   */
+  listed?: boolean;
   /** Template-specific headless model. Takes precedence over the pane-level model. */
   headless?: HeadlessPaneDefinition;
   /**

package/src/ui/host.tsx

@@ -82,6 +82,8 @@ export interface ChartVectorShape {
   gradient?: readonly string[];
   /** Opacity of the whole shape, so others can recede behind a highlighted one. */
   opacity?: number;
+  /** Text set just above the shape's first point, such as a retracement level's ratio and price. */
+  label?: string;
 }
 
 interface TextEditBuffer {
@@ -508,6 +510,7 @@ export interface HostCheckboxProps {
 interface HostQueryBarOption {
   value: string;
   label: string;
+  group?: string;
   description?: string;
   disabled?: boolean;
   selected: boolean;

package/src/updater/failure.ts

@@ -24,7 +24,7 @@ const UPDATE_FAILURE_CODES = [
   "no_build",
   /** The download stopped before the whole file arrived. */
   "interrupted",
-  /** The file arrived whole but does not match its checksum, or does not unpack. */
+  /** The download does not match its checksum, or does not unpack (part of it is missing or damaged). */
   "corrupt",
   "permission_denied",
   /** The macOS app runs from where it cannot be replaced: a disk image, App Translocation, another volume. */
@@ -112,6 +112,9 @@ export function classifyUpdateError(error: unknown): UpdateFailureCode {
   if (status) return httpStatusFailureCode(Number(status));
   if (/checksum mismatch|hash mismatch/i.test(message)) return "corrupt";
   if (/zstd|decompress|gunzip|incorrect header|unexpected end of (?:file|data)/i.test(message)) return "corrupt";
+  // Bun.Archive on a tar that does not read: cut off, damaged, or none at all.
+  // Unpacking says only "ReadError", whatever stopped it.
+  if (/\bReadError\b|truncated tar|damaged tar|unrecognized archive format/i.test(message)) return "corrupt";
   if (/timed? ?out/i.test(message)) return "timeout";
   if (/rate limit/i.test(message)) return "rate_limited";
   if (/read-only file system/i.test(message)) return "read_only";

package/src/utils/cli-output.ts

@@ -74,6 +74,47 @@ const PLAIN_EMPTY_CELL = "—";
 let colorEnabledOverride: boolean | null = null;
 let widthOverride: number | null = null;
 let plainOverride: boolean | null = null;
+/** Output is being rendered for a file (`renderForFile`), which has no terminal width. */
+let renderingForFile = false;
+
+/** Renders for a file from here on; the function returned puts the terminal's rendering back. */
+function enterFileRendering(): () => void {
+  const saved = { color: colorEnabledOverride, plain: plainOverride, file: renderingForFile };
+  colorEnabledOverride = false;
+  plainOverride = true;
+  renderingForFile = true;
+  return () => {
+    colorEnabledOverride = saved.color;
+    plainOverride = saved.plain;
+    renderingForFile = saved.file;
+  };
+}
+
+/**
+ * Output rendered for a file (`fn --output`) as a redirect gets it: plain,
+ * without colour, and fitted to no width but `--width`'s.
+ */
+export function renderForFile<T>(render: () => T): T {
+  const restore = enterFileRendering();
+  try {
+    return render();
+  } finally {
+    restore();
+  }
+}
+
+/**
+ * `renderForFile` around work that renders as it loads: a report whose text is
+ * drawn while it is built is drawn for the file, though stdout is a terminal.
+ */
+export async function buildForFile<T>(build: () => Promise<T>): Promise<T> {
+  const restore = enterFileRendering();
+  try {
+    return await build();
+  } finally {
+    restore();
+  }
+}
 
 function colorEnabled(): boolean {
   if (colorEnabledOverride != null) return colorEnabledOverride;
@@ -176,7 +217,7 @@ export function setCliWidthOverride(value: number | null): void {
 /** Columns the output is fitted to: `--width`, else the terminal's, or null when output is piped or redirected. */
 export function cliTerminalWidth(): number | null {
   if (widthOverride != null) return widthOverride;
-  if (!process.stdout.isTTY) return null;
+  if (renderingForFile || !process.stdout.isTTY) return null;
   const columns = process.stdout.columns;
   return typeof columns === "number" && columns > 0 ? columns : null;
 }