gloomberb 0.16.3 → 0.16.5

package/src/time-series/resolve.ts

@@ -77,9 +77,12 @@ import {
   resolveExchangeTimeZone,
 } from "../utils/exchanges";
 import { getPricePointTimestamp, isPriceHistoryStaleForCurrentWindow } from "../utils/price-history";
+import { timeZoneLabel, zonedDateKey, zonedWallClockMs } from "../utils/zoned-date-time";
+import { formatShortDate } from "../utils/datetime-format";
 import { latestSessionStart, latestTradingSessionOpen, listingTimeZone, priorSessionClose } from "../market-data/market/trading-sessions";
 import { futuresGenericCaption, futuresGenericListing, futuresGenericPriceBasis } from "../utils/futures-generic";
 import { isOhlcSeriesStyle } from "./spec";
+import { SERIES_COLORS } from "../theme/series-colors";
 import type {
   ChartResolutionResult,
   ChartSeriesSpec,
@@ -88,20 +91,6 @@ import type {
   TimeSeriesPoint,
 } from "./types";
 
-/** Colours for series told apart by name (compared tickers, markets). */
-export const SERIES_COLORS = [
-  "#4dabf7",
-  "#63e6be",
-  "#f6c85f",
-  "#b197fc",
-  "#ff8787",
-  "#ffa94d",
-  "#74c0fc",
-  "#e599f7",
-  "#8ce99a",
-  "#ffd43b",
-] as const;
-
 export interface ChartResolveSources {
   dataProvider: DataProvider | null;
   loadFredSeries: (request: FredSeriesRequest) => Promise<FredSeriesLoadResult>;
@@ -115,6 +104,11 @@ export interface ChartResolveSources {
   liveSince?: number;
   /** Capture the resolved inputs, including the calculation buffer, for an export. */
   onSecurityData?: (series: ChartSeriesSpec, data: TickerFinancials, includesHistory: boolean) => void;
+  /**
+   * How often, in milliseconds, a plugin-owned series is loaded again while
+   * it is charted; nothing for a series that keeps what it loaded.
+   */
+  capabilityRefreshMs?: (source: Extract<ChartSeriesSpec["source"], { kind: "capability" }>) => number | undefined;
   /** Provider-neutral boundary for plugin-owned chart series. */
   resolveCapabilitySeries?: (
     source: Extract<ChartSeriesSpec["source"], { kind: "capability" }>,
@@ -277,6 +271,24 @@ function instrumentLabel(spec: Extract<ChartSeriesSpec["source"], { kind: "secur
   return publicTickerKey(spec.instrument.symbol, spec.instrument.exchange);
 }
 
+/**
+ * Shown while a current chart draws a saved copy that no refetch brought up
+ * to date: the last saved bar on the venue's clock, as the axis reads it.
+ */
+function behindHistoryNotice(
+  source: Extract<ChartSeriesSpec["source"], { kind: "security" }>,
+  points: TickerFinancials["priceHistory"],
+  now: number,
+): string | null {
+  const latest = points.findLast((point) => Number.isFinite(point.close) && Number.isFinite(getPricePointTimestamp(point)));
+  if (!latest) return null;
+  const zone = listingTimeZone(source.instrument.symbol, source.instrument.exchange) ?? "UTC";
+  const wall = new Date(zonedWallClockMs(getPricePointTimestamp(latest), zone)).toISOString();
+  const sameYear = wall.slice(0, 4) === zonedDateKey(now, zone).slice(0, 4);
+  const day = formatShortDate(wall.slice(0, 10), { utc: true, year: sameYear ? false : "numeric" });
+  return `${instrumentLabel(source)}: newer bars are unavailable; showing saved bars as of ${day} ${wall.slice(11, 16)} ${timeZoneLabel(zone)}.`;
+}
+
 // A series that fails to load keeps its place with no observations. Dropping it
 // made a series the user had added disappear from the legend while it still sat
 // in the series editor, with nothing on screen to explain the difference.
@@ -555,6 +567,25 @@ function followLatestMarketObservation(
   };
 }
 
+/**
+ * A chart of capability series alone (CHOKE's vessel transits) ends at its
+ * newest observation, not today: such data is published days late, and an
+ * axis running on to today would read as days with nothing in them. The
+ * start stays where the range put it, so no empty span opens on the left.
+ */
+function endAtNewestObservation(bounds: DateBounds, series: readonly ResolvedSeries[]): DateBounds {
+  if (bounds.end === null) return bounds;
+  let newest = Number.NEGATIVE_INFINITY;
+  for (const entry of series) {
+    for (const point of entry.points) {
+      const timestamp = point.date.getTime();
+      if (point.value !== null && Number.isFinite(timestamp) && timestamp > newest) newest = timestamp;
+    }
+  }
+  if (!Number.isFinite(newest) || newest >= bounds.end || (bounds.start !== null && newest <= bounds.start)) return bounds;
+  return { start: bounds.start, end: newest };
+}
+
 /**
  * 1D shows the latest trading session of the chart's first market listing,
  * from its open to the newest bar, with the close before it as a reference.
@@ -1138,6 +1169,7 @@ function baseCapabilitySeries(
     axis: spec.axis === "right" ? "right" : spec.axis === "left" ? "left" : loaded.axis,
     panelId: spec.panelId,
     interpolation: spec.interpolation,
+    observationKind: loaded.observationKind ?? "dataset",
     points,
   };
 }
@@ -1641,33 +1673,63 @@ async function resolveChartSpecPass(
       return next;
     };
     pending ??= acquire();
-    let loaded = await pending;
+    let loaded: LoadedPriceHistory;
+    try {
+      loaded = await pending;
+    } catch (error) {
+      // Another series' refetch failed and put the saved copy back below.
+      const restored = cache.priceHistoryByRequest.get(key);
+      if (!restored || restored === pending) throw error;
+      pending = restored;
+      loaded = await pending;
+    }
     const now = () => referenceNow.getTime() + Math.max(0, Date.now() - resolutionStartedAt);
     const currentWindow = () => !request.explicitWindow
       || (request.bounds.end !== null && now() - (request.bounds.end + 1) < 60 * 60_000);
-    const staleCurrent = (value: LoadedPriceHistory) => currentWindow() && !!value.session
-      && isPriceHistoryStaleForCurrentWindow(value.points, now(), {
+    // A copy with a session record is judged here; any other says so itself,
+    // when the router answered it from a saved copy short of the latest session.
+    const staleCurrent = (value: LoadedPriceHistory) => currentWindow() && (value.savedCopyBehind === true
+      || (!!value.session && isPriceHistoryStaleForCurrentWindow(value.points, now(), {
         symbol: source.instrument.symbol, exchange: source.instrument.exchange, session: value.session,
         ...(value.resolution ? { intervalMs: CHART_RESOLUTION_STEP_MS[value.resolution] } : {}),
-      });
+      })));
+    // A copy behind the current session is fetched again at most every 30 s.
+    // Until a fetch answers a current one, the saved copy is drawn with a
+    // notice, as every other history path does, rather than an error.
+    let behind = false;
     if (staleCurrent(loaded)) {
+      const saved = pending;
+      const savedValue = loaded;
+      const latest = cache.priceHistoryByRequest.get(key);
+      let refresh: Promise<LoadedPriceHistory> | undefined;
       if (reused && (cache.priceHistoryRefreshAfter.get(key) ?? 0) <= Date.now()) {
         // Claim the refresh before awaiting it so price/volume/studies share one attempt.
         cache.priceHistoryRefreshAfter.set(key, Date.now() + 30_000);
-        if (cache.priceHistoryByRequest.get(key) === pending) pending = acquire();
-        else pending = cache.priceHistoryByRequest.get(key)!;
-        loaded = await pending;
-      } else if (cache.priceHistoryByRequest.get(key) !== pending) {
-        loaded = await cache.priceHistoryByRequest.get(key)!;
+        refresh = latest && latest !== pending ? latest : acquire();
+      } else if (latest && latest !== pending) {
+        refresh = latest;
+      }
+      if (refresh) {
+        const attempt = refresh;
+        loaded = await attempt.catch(() => {
+          // A failed refetch leaves the saved copy in place until the next one is due.
+          if (cache.priceHistoryByRequest.get(key) === attempt) {
+            cache.priceHistoryByRequest.set(key, saved);
+            if (savedValue.expiresAt !== undefined) cache.priceHistoryExpiryByRequest.set(key, savedValue.expiresAt);
+            else cache.priceHistoryExpiryByRequest.delete(key);
+          }
+          return savedValue;
+        });
       }
-      if (staleCurrent(loaded)) {
+      behind = staleCurrent(loaded);
+      if (behind) {
         const previousDeadline = cache.priceHistoryRefreshAfter.get(key) ?? 0;
-        const retryAt = previousDeadline > Date.now() ? previousDeadline : Date.now() + 30_000;
-        cache.priceHistoryRefreshAfter.set(key, retryAt);
-        throw new PriceHistoryAcquisitionError(`Current price history is unavailable for ${instrumentLabel(source)}.`, retryAt);
+        cache.priceHistoryRefreshAfter.set(key, previousDeadline > Date.now() ? previousDeadline : Date.now() + 30_000);
+        const notice = behindHistoryNotice(source, loaded.points, now());
+        if (notice) priorityWarnings.push(notice);
       }
     }
-    cache.priceHistoryRefreshAfter.delete(key);
+    if (!behind) cache.priceHistoryRefreshAfter.delete(key);
     const history = loaded.points;
     const coverageNotice = historyCoverageNotice(loaded.coverageStart, request.visibleBounds.start);
     if (coverageNotice) priorityWarnings.push(coverageNotice);
@@ -1926,9 +1988,12 @@ async function resolveChartSpecPass(
     ? latestSessionView(primaryRaw, rawSeries.filter((entry) => entry.observationKind === "market"),
       extendedHistories.has(primaryRaw?.id ?? ""), quoteReferences.get(primaryRaw?.id ?? ""))
     : null;
+  const capabilityOnly = spec.series.length > 0 && spec.series.every(({ source }) => source.kind === "capability");
   const bounds = hasExplicitWindow
     ? requestVisibleBounds
-    : sessionView?.bounds ?? followLatestMarketObservation(initialVisibleBounds, rawSeries);
+    : sessionView?.bounds ?? (capabilityOnly
+      ? endAtNewestObservation(initialVisibleBounds, rawSeries)
+      : followLatestMarketObservation(initialVisibleBounds, rawSeries));
   if (sessionView?.priorClose != null && primaryRaw?.transform === "raw"
     && primaryRaw.unitGroup.startsWith("price") && primaryRaw.unitGroup !== "price:unknown") {
     const index = rawSeries.indexOf(primaryRaw);
@@ -2146,8 +2211,9 @@ export function reconcileChartTail(
     const refreshed = mergePriceHistoryWindows(loaded.points, points, tail.resolution);
     if (samePricePoints(refreshed, loaded.points)) return false;
     const acquisition = priceHistoryTailAcquisition(loaded, result);
+    // The merged bars are as current as the newer acquisition says.
     cache.priceHistoryByRequest.set(key, Promise.resolve({ ...loaded, points: refreshed,
-      session: acquisition.session, sourceKey: acquisition.sourceKey }));
+      session: acquisition.session, sourceKey: acquisition.sourceKey, savedCopyBehind: acquisition.savedCopyBehind }));
     if (accumulated) {
       const accumulatedAcquisition = priceHistoryTailAcquisition(accumulated, result);
       cache.accumulatedPriceHistory.set(tail.accumulationKey, { ...accumulated,

package/src/time-series/types.ts

@@ -178,8 +178,10 @@ export interface ResolvedSeries {
    */
   listing?: { symbol: string; exchange: string };
   /** Price/volume observations and their derived studies, including 24/7
-   * markets. Independent of whether the chart compresses exchange sessions. */
-  observationKind?: "market";
+   * markets. Independent of whether the chart compresses exchange sessions.
+   * `dataset`: a capability's published observations (vessel transits),
+   * whose values the legend dates because they arrive days late. */
+  observationKind?: "market" | "dataset";
   /** Regular-session move supplied with the latest market quote. */
   latestChangePercent?: number;
   /** The previous session's close, set on a one-day chart's price series and drawn as its reference line. */

package/src/time-series/use-chart-resolution.ts

@@ -457,6 +457,38 @@ export function useChartResolution(
     };
   }, [coordinator, liveFrameMs, liveKey, sources]);
 
+  // A plugin series that changes through the day asks to be loaded again on
+  // its own cadence; only its entries leave the cache, so nothing else refetches.
+  const capabilityRefreshMs = sources.capabilityRefreshMs;
+  const seriesRefreshMs = useMemo(() => {
+    if (snapshot || !capabilityRefreshMs) return 0;
+    let shortest = 0;
+    for (const series of spec.series) {
+      if (series.source.kind !== "capability" || series.visible === false) continue;
+      const refreshMs = capabilityRefreshMs(series.source) ?? 0;
+      if (refreshMs > 0 && (shortest === 0 || refreshMs < shortest)) shortest = refreshMs;
+    }
+    return shortest;
+    // The spec key is the series' identity; a new spec object alone must not restart the timer.
+  }, [capabilityRefreshMs, snapshot, specKey]);
+  useEffect(() => {
+    if (!seriesRefreshMs || !paneVisible || !capabilityRefreshMs) return;
+    const timer = setInterval(() => {
+      const cache = resolveCacheRef.current;
+      let dropped = false;
+      for (const key of [...cache.capabilitySeriesByRequest.keys()]) {
+        const [, capabilityId, seriesId] = JSON.parse(key) as [string, string, string];
+        if (!capabilityRefreshMs({ kind: "capability", capabilityId, seriesId })) continue;
+        cache.capabilitySeriesByRequest.delete(key);
+        dropped = true;
+      }
+      if (!dropped) return;
+      cache.revision += 1;
+      setSupportRevision((current) => current + 1);
+    }, seriesRefreshMs);
+    return () => clearInterval(timer);
+  }, [capabilityRefreshMs, paneVisible, seriesRefreshMs]);
+
   useEffect(() => {
     if (snapshot) return;
     generationRef.current += 1;

package/src/types/config.ts

@@ -2,7 +2,7 @@ import type { Portfolio, Watchlist } from "./ticker";
 import type { BrokerContractRef, TickerListingRef } from "./instrument";
 import type { LanguagePreference } from "../i18n/languages";
 
-export const CURRENT_CONFIG_VERSION = 24;
+export const CURRENT_CONFIG_VERSION = 25;
 
 type ChartRendererPreference = "auto" | "kitty" | "braille";
 
@@ -59,6 +59,30 @@ export interface PanePlacementMemory {
   detached?: DetachedPlacementMemory;
 }
 
+/**
+ * A ticker link Move to New Layout had to cut: the pane followed another one
+ * that stayed behind (or left with the moved pane) and was pinned on `symbol`.
+ * Move Back links it again while it is still pinned there.
+ */
+export interface PaneMovedLink {
+  instanceId: string;
+  sourceInstanceId: string;
+  symbol: string;
+  /** The title before the pin renamed it ("OPX" for "OPX NVDA"), when it did. */
+  title?: string;
+}
+
+/** Where Move to New Layout took a pane from, so Move Back can return it. */
+export interface PaneMovedFrom {
+  /** `SavedLayout.id` of the layout it left. */
+  layoutId: string;
+  /** Set when it was docked there: its place in the tree and its share of the split. */
+  docked?: DockedPlacementMemory & { ratio?: number };
+  /** Set when it was floating there. */
+  floating?: FloatingPlacementMemory;
+  links?: PaneMovedLink[];
+}
+
 export interface PaneInstanceConfig {
   instanceId: string;
   paneId: string;
@@ -69,6 +93,8 @@ export interface PaneInstanceConfig {
   placementMemory?: PanePlacementMemory;
   /** Pinned by the user: the keyboard close shortcuts leave this pane alone. */
   locked?: boolean;
+  /** Set by Move to New Layout and cleared by Move Back; never published. */
+  movedFrom?: PaneMovedFrom;
 }
 
 interface DockPaneNode {
@@ -203,6 +229,21 @@ export interface TelemetryConfig {
   attention?: boolean;
 }
 
+/**
+ * The one-time line in the terminal's status bar asking to star Gloomberb on
+ * GitHub. Absent means on and not shown yet. Kept on this machine only.
+ */
+export interface StarPromptConfig {
+  /** `false` turns the line off; absent means on. */
+  enabled?: boolean;
+  /** Local days (`YYYY-MM-DD`) the terminal app was opened on, oldest first, until the line shows. */
+  days?: string[];
+  /** When the line showed. Once set it never shows again. */
+  shownAt?: string;
+  /** How it ended: the repository was opened, the line was dismissed, or it timed out. */
+  outcome?: "opened" | "dismissed" | "expired";
+}
+
 /**
  * One recent command-bar run: `id` is `pane-template:<templateId>`, `label`
  * its name when it ran, and `arg` a ticker it ran with (never free text).
@@ -255,6 +296,18 @@ export interface AppConfig {
   /** Key overrides for this machine. Absent means every default applies. */
   keybindings?: KeybindingsConfig;
   telemetry?: TelemetryConfig;
+  starPrompt?: StarPromptConfig;
+  /**
+   * The IANA zone (`Asia/Tokyo`) the CLI and function reports show a local
+   * time in, beside every UTC time. Absent prints UTC alone. Trading-day dates
+   * are never shifted by it.
+   */
+  timezone?: string;
+  /**
+   * Presentation mode: the panes fill the window, without the header or the
+   * status bar, for a screen that is shown rather than worked at. Absent is off.
+   */
+  presentationMode?: boolean;
 }
 
 export const TICKER_RESEARCH_PANE_ID = "ticker-research";
@@ -582,6 +635,17 @@ export function clonePlacementMemory(memory: PanePlacementMemory | undefined): P
   };
 }
 
+function clonePaneMovedFrom(movedFrom: PaneMovedFrom): PaneMovedFrom {
+  return {
+    layoutId: movedFrom.layoutId,
+    ...(movedFrom.docked ? {
+      docked: { ...movedFrom.docked, ...(movedFrom.docked.path ? { path: [...movedFrom.docked.path] } : {}) },
+    } : {}),
+    ...(movedFrom.floating ? { floating: { ...movedFrom.floating } } : {}),
+    ...(movedFrom.links ? { links: movedFrom.links.map((link) => ({ ...link })) } : {}),
+  };
+}
+
 function cloneUnknownValue<T>(value: T): T {
   if (Array.isArray(value)) {
     return value.map((entry) => cloneUnknownValue(entry)) as T;
@@ -816,6 +880,7 @@ export function normalizePaneLayout(
       params: instance.params ? { ...instance.params } : undefined,
       settings: clonePaneSettings(instance.settings),
       placementMemory: clonePlacementMemory(instance.placementMemory),
+      ...(instance.movedFrom ? { movedFrom: clonePaneMovedFrom(instance.movedFrom) } : {}),
     })),
     floating: nextLayout.floating
       .filter((entry) => (
@@ -838,6 +903,7 @@ export function cloneLayout(layout: LayoutConfig): LayoutConfig {
       params: instance.params ? { ...instance.params } : undefined,
       settings: clonePaneSettings(instance.settings),
       placementMemory: clonePlacementMemory(instance.placementMemory),
+      ...(instance.movedFrom ? { movedFrom: clonePaneMovedFrom(instance.movedFrom) } : {}),
     })),
     floating: layout.floating.map((entry) => ({ ...entry })),
     detached: detached.map((entry) => ({ ...entry })),

package/src/types/data-provider.ts

@@ -138,6 +138,11 @@ export interface SearchRequestContext {
    * well under a second rather than given the batch budget.
    */
   interactive?: boolean;
+  /**
+   * Rows to ask a catalogue for. Every listing of a symbol several companies
+   * use (CAR: Avis, Carrefour, CAR Group) takes more than a keystroke's ten.
+   */
+  limit?: number;
   /**
    * Called when a later source improves the result the search already returned,
    * typically a broker adding contract detail to a symbol the cloud found

package/src/types/financials.ts

@@ -100,6 +100,14 @@ export interface Quote extends DepositaryReceiptFacts {
   postMarketPrice?: number;
   postMarketChange?: number;
   postMarketChangePercent?: number;
+  /**
+   * Whether the quote holds a trade from the pre-market or after-hours
+   * session in progress (marketState PRE or POST). False when nothing has
+   * traded in it yet: the extended fields, or the price, are then the regular
+   * price carried forward, and their flat move is no move. Absent in the other
+   * sessions and when the source does not say.
+   */
+  extendedSessionPrint?: boolean;
   bid?: number;
   ask?: number;
   bidSize?: number;
@@ -123,6 +131,26 @@ export interface QuoteContribution extends Quote {
 
 export type QuoteContributionMap = Record<string, QuoteContribution>;
 
+/** How a fundamentals block's trailing figures were converted from the currency the company reports in. */
+export interface TtmConversion {
+  /** The reporting currency the figures were converted from. */
+  from: string;
+  /** Units of `financialCurrency` per unit of `from` for revenue, income and cash flow; absent when not measured. */
+  rate?: number;
+  /** YYYY-MM-DD the converted figures were fetched. */
+  asOf?: string;
+  /** EPS is converted at the rate of each report date, so a P/E on it divides a spot price by EPS at older rates. */
+  eps?: "report_date";
+}
+
+/** How a trailing P/E converts the EPS it divides by, when that EPS is in another currency than the price. */
+export interface TrailingPEConversion {
+  /** The currency of the trailing EPS. */
+  from: string;
+  /** Units of the quote's (major) currency per unit of `from`. */
+  rate: number;
+}
+
 export interface Fundamentals extends DepositaryReceiptFacts {
   /** Every share count here is on this basis, the basis of the listing's price and market cap; absent when unproven. */
   shareBasis?: ShareBasis;
@@ -131,8 +159,14 @@ export interface Fundamentals extends DepositaryReceiptFacts {
   source?: "gloom";
   fetchedAt?: string;
   stale?: boolean;
-  /** Currency of reported revenue, income, and cash flows; may differ from the listing. */
+  /** Currency of the trailing revenue, income, cash flows and EPS (EPS unless `epsCurrency` says otherwise); may differ from the listing and the statements. */
   financialCurrency?: string;
+  /** Set when the trailing figures were converted from the reporting currency into `financialCurrency`. */
+  ttmConversion?: TtmConversion;
+  /** Set when the trailing EPS is in another currency than `financialCurrency`: the listing's, converted from the reporting currency at each report date's rate. */
+  epsCurrency?: string;
+  /** Set when `trailingPE` divides the price by the trailing EPS converted from another currency. */
+  trailingPEConversion?: TrailingPEConversion;
   /** Provider-reported issuer market cap; marketCapCurrency identifies its units when known. */
   marketCap?: number;
   marketCapCurrency?: string;
@@ -302,6 +336,16 @@ export interface SplitAction {
   toFactor?: number;
 }
 
+/**
+ * How a reported EPS relates to the company's statements: `gaap` is the
+ * quarter's diluted EPS as the statements report it; `adjusted` is the
+ * consensus-basis figure, which leaves out items the statements include.
+ */
+export type EarningsEpsBasis = "gaap" | "adjusted";
+
+/** A report that is out, a date the company announced, or a date projected from its past reports. */
+export type EarningsDateStatus = "reported" | "confirmed" | "projected";
+
 export interface EarningsAction {
   date: string;
   dateType?: "announcement" | "fiscal-period-end";
@@ -311,6 +355,13 @@ export interface EarningsAction {
   epsActual?: number;
   difference?: number;
   surprisePercent?: number;
+  /** Fiscal quarter end month, YYYY-MM, when the report's quarter is known. */
+  fiscalPeriod?: string;
+  /** Analysts behind `epsEstimate`, when known. */
+  epsAnalysts?: number;
+  /** Null when the basis cannot be determined; absent from sources that do not say. */
+  epsBasis?: EarningsEpsBasis | null;
+  dateStatus?: EarningsDateStatus;
 }
 
 export interface CorporateActionsData {

package/src/types/headless.ts

@@ -51,6 +51,15 @@ export interface HeadlessPaneOptionDef {
     pluginId: string;
     key?: string;
   };
+  /** The value's name in the catalog's flag, `--expiration <YYYY-MM-DD|unix>`; the type when absent. */
+  placeholder?: string;
+  /** The option in use as typed after the function, such as `--expiration 2028-01-21`; the catalog shows it as an example. */
+  example?: string;
+  /**
+   * Checks a typed value and returns it as the pane reads it, in place of the
+   * type's own check; throws an Error that names what is wrong.
+   */
+  normalize?(value: string): string | number | boolean;
 }
 
 export interface HeadlessPaneLoadArgs {
@@ -90,8 +99,18 @@ export interface HeadlessPaneColumn {
   header: string;
   align?: "left" | "right" | "center";
   width?: number;
+  /** False keeps the column whole when the text table is fitted to a narrow width, so a time or an id is never cut. */
+  shrink?: boolean;
   description?: string;
   format?: (value: unknown, row: HeadlessPaneRow) => string;
+  /** What the text report prints when it can say more than an export should (a unit word beside a number); CSV and NDJSON keep `format`. */
+  textFormat?: (value: unknown, row: HeadlessPaneRow) => string;
+  /**
+   * The text report prints the value on its own lines under the row instead
+   * of in a column, for a footnote that belongs to that row; an empty value
+   * prints nothing. Exports keep it as a column.
+   */
+  underRow?: boolean;
 }
 
 export interface HeadlessPaneEntry {
@@ -142,6 +161,12 @@ export interface HeadlessPaneFreshness {
   delayMinutes?: number;
   /** What not-a-feed data is, in a few words: "filed data", "monthly release", "your inputs". */
   basis?: string;
+  /**
+   * How often the data is published, when its dates mark the start of a period
+   * (a monthly statistic is dated the 1st). The report then names the month,
+   * quarter or year, not a day it was never observed on.
+   */
+  periodicity?: "monthly" | "quarterly" | "annual";
   /** The newest observation is stale once it is older than this many minutes. */
   maxAgeMinutes?: number;
   /**
@@ -155,8 +180,44 @@ export interface HeadlessPaneFreshness {
    * completed session has passed after the newest (a day's lag is allowed).
    */
   cadence?: "daily";
+  /** The venue whose trading days a `daily` cadence counts instead, when the app knows its sessions. */
+  cadenceExchange?: string;
+  /**
+   * Whose trading day a dated (`YYYY-MM-DD`) as-of is, as a reader names the
+   * market: `US` for a US trading or business day. The report then reads
+   * `US trading day Fri 9 Oct 2026`, so a reader whose day is already Saturday
+   * does not take the US Friday for theirs. Leave it out when the dates are not
+   * one market's.
+   */
+  tradingDayMarket?: string;
   /** The newest observation is stale once this time (the next scheduled release) has passed by a day. */
   nextExpectedAt?: string | number | Date | null;
+  /**
+   * Observations of the world collected and published some days after they
+   * happen (vessel transits, job postings, rental prices, grid queues), not
+   * quotes. A screenshot then cites the source, the newest observation's date
+   * and its lag in days (`Source: Gloom Cloud · observed Sun 4 Oct · lag 6d`),
+   * never a market's session. Rows that are quotes keep the market line.
+   */
+  dataset?: boolean;
+  /**
+   * What a dataset's newest observation is, when its every line names it:
+   * `last trade` makes the `fn` footer, the pane footer and a screenshot read
+   * the same, `Source: DTCC · last trade 2026-10-09 · lag 2 days`, dated as
+   * the report's rows are, by ISO date.
+   */
+  observation?: string;
+  /**
+   * Each source's own newest observation, for data drawn from several venues
+   * polled apart (a perpetuals board). The line then dates every source and
+   * says how old the oldest of them is (`Binance 02:15 · Bybit 02:24 UTC ·
+   * oldest 9 min`), and `asOf` is the newest of them unless declared.
+   */
+  sources?: Array<{ source: string; asOf: string | number | Date }>;
+  /** Say how old the oldest observation is (`oldest 4 min`): rows polled apart from one source. */
+  oldestAge?: boolean;
+  /** What the figures are, said after the status: `funding = current estimate, pays 08:00 UTC`. */
+  note?: string;
 }
 
 interface HeadlessPaneResultBase {
@@ -182,6 +243,8 @@ interface HeadlessPaneResultBase {
 export interface HeadlessRowsResult extends HeadlessPaneResultBase {
   columns?: HeadlessPaneColumn[];
   rows: HeadlessPaneRow[];
+  /** What the report says when `rows` is empty, in place of "No data.": why there are none. */
+  empty?: string;
 }
 
 export type HeadlessBundleSection =
@@ -189,6 +252,8 @@ export type HeadlessBundleSection =
     title: string;
     columns?: HeadlessPaneColumn[];
     rows: HeadlessPaneRow[];
+    /** What the report says when `rows` is empty, in place of "No data.": why there are none, and what to run instead. */
+    empty?: string;
     entries?: never;
   }
   | {
@@ -255,6 +320,13 @@ export interface HeadlessPaneDefinition<Shape extends HeadlessPaneShape = Headle
    */
   description?: string;
   argument: HeadlessPaneArgumentDef;
+  /**
+   * The data covers US listings only, named as a sentence starts ("Time and
+   * sales"). `fn` and `shot` answer a listing abroad with that and the
+   * company's US listing instead of loading, so a symbol another company uses
+   * in the US never shows that company's numbers.
+   */
+  usListingsOnly?: string;
   options: HeadlessPaneOptionDef[];
   /** What is true of every load: its source, and whether it is a feed. */
   freshness?: HeadlessPaneFreshness;

package/src/types/instrument.ts

@@ -59,4 +59,12 @@ export interface InstrumentSearchResult {
   /** How often the listing is searched, higher is more (the search service score,
    * sent by newer cloud servers). Only comparable within one response. */
   popularity?: number;
+  /** Trade names the row answers to ("Aramco" for Saudi Arabian Oil Co.), sent by
+   * newer cloud servers on a row a trade-name query added. The legal name does not
+   * contain them, so search matches the query against them too. */
+  searchAliases?: string[];
+  /** A theme the row answers to without its name saying so ("lithium" on
+   * Albemarle, which the lithium funds hold), sent by newer cloud servers on a
+   * row a theme query added. Matched like the name, ranked after name matches. */
+  searchKeywords?: string[];
 }