gloomberb 0.17.2 → 0.17.3

package/src/sync/core-contributors.ts

@@ -1,6 +1,6 @@
 import { scheduleConfigSave } from "../state/config-save-scheduler";
 import { debugLog } from "../utils/debug-log";
-import { stableStringify } from "../utils/hash";
+import { fnv1aHex, stableStringify } from "../utils/hash";
 import type { AppConfig, BrokerInstanceConfig, SavedLayout } from "../types/config";
 import type { PricePoint, TickerFinancials } from "../types/financials";
 import type { Portfolio, TickerMetadata, TickerPosition, TickerRecord, Watchlist } from "../types/ticker";
@@ -40,6 +40,9 @@ import { withoutMissingWatchlists } from "../plugins/builtin/portfolio-list/muta
  */
 const SESSION_SAVED_LAYOUT_KEYS = ["paneState", "focusedPaneId", "activePanel"] as const;
 
+/** Together these are the workspace: the tabs, the one showing, and its arrangement. */
+const LAYOUT_SYNC_KEYS = ["layout", "layouts", "activeLayoutIndex"] as const;
+
 const SENSITIVE_KEY_PATTERN = /(token|secret|password|credential|private|api[_-]?key|access[_-]?key|refresh[_-]?key|session|cookie|dataDir|path|directory|localPath)/i;
 
 const log = debugLog.createLogger("sync");
@@ -351,6 +354,14 @@ function sanitizeTickerMetadata(metadata: TickerMetadata, financials?: TickerFin
   };
 }
 
+function collectLayoutPayload(config: Pick<AppConfig, typeof LAYOUT_SYNC_KEYS[number]>) {
+  return sanitizeUnknown({
+    layout: config.layout,
+    layouts: config.layouts.map(withoutSessionLayoutState),
+    activeLayoutIndex: config.activeLayoutIndex,
+  }) as Record<string, unknown>;
+}
+
 function collectCoreConfigPayload(config: AppConfig) {
   return sanitizeUnknown({
     configVersion: config.configVersion,
@@ -358,9 +369,7 @@ function collectCoreConfigPayload(config: AppConfig) {
     refreshIntervalMinutes: config.refreshIntervalMinutes,
     portfolios: config.portfolios.map(sanitizePortfolio),
     watchlists: config.watchlists.map(sanitizeWatchlist),
-    layout: config.layout,
-    layouts: config.layouts.map(withoutSessionLayoutState),
-    activeLayoutIndex: config.activeLayoutIndex,
+    ...collectLayoutPayload(config),
     brokerInstances: config.brokerInstances.map(sanitizeBrokerInstance),
     // This build merges profiles one by one before it pushes, so a profile
     // missing from its list was removed, not one it never pulled.
@@ -622,11 +631,204 @@ function withLocalSessionLayoutState(
   });
 }
 
+/**
+ * A layout as the user arranged it. Stacking order follows whichever floating
+ * pane was focused last, and a pane in its own desktop window is one a
+ * terminal draws inline as a floating pane, so neither tells two copies apart.
+ */
+function arrangedLayout(layout: unknown): unknown {
+  if (!isRecord(layout)) return layout;
+  const windows = [
+    ...(Array.isArray(layout.floating) ? layout.floating : []),
+    ...(Array.isArray(layout.detached) ? layout.detached : []),
+  ].map((entry) => {
+    if (!isRecord(entry)) return entry;
+    const { zIndex: _zIndex, ...rest } = entry;
+    return rest;
+  });
+  const instanceId = (entry: unknown) => (isRecord(entry) ? String(entry.instanceId) : "");
+  windows.sort((left, right) => instanceId(left).localeCompare(instanceId(right)));
+  return { ...layout, floating: windows, detached: [] };
+}
+
+// Pulled and last synced payloads are compared on every sync and never change.
+const layoutIntents = new WeakMap<object, string | null>();
+
+/**
+ * A key for the workspace a payload describes, equal for two copies that only
+ * differ in what reflects one device, so a real edit can be told from them.
+ * Null when the payload holds no complete workspace.
+ */
+function layoutIntent(payload: unknown): string | null {
+  if (!isRecord(payload) || !Array.isArray(payload.layouts)) return null;
+  if (!LAYOUT_SYNC_KEYS.every((key) => key in payload)) return null;
+  const cached = layoutIntents.get(payload);
+  if (cached !== undefined) return cached;
+  const intent = stableStringify(sanitizeUnknown({
+    layout: arrangedLayout(payload.layout),
+    layouts: payload.layouts.map((entry) => (
+      isRecord(entry)
+        ? { ...withoutSessionLayoutState(entry as unknown as SavedLayout), layout: arrangedLayout(entry.layout) }
+        : entry
+    )),
+    activeLayoutIndex: payload.activeLayoutIndex,
+  }));
+  const key = `${fnv1aHex(intent)}:${intent.length}`;
+  layoutIntents.set(payload, key);
+  return key;
+}
+
+/** The workspace keys of a payload, with the time its layout was last edited when it says. */
+function pickLayoutPayload(payload: Record<string, unknown>): Record<string, unknown> {
+  const picked = Object.fromEntries([...LAYOUT_SYNC_KEYS, "layoutEditedAt"].flatMap((key) => (
+    key in payload ? [[key, payload[key]]] : []
+  )));
+  // An older build still sent the view it was looking at with each layout.
+  if (Array.isArray(picked.layouts)) {
+    picked.layouts = picked.layouts.map((entry) => (isRecord(entry) ? withoutSessionLayoutState(entry as unknown as SavedLayout) : entry));
+  }
+  return picked;
+}
+
+/**
+ * What this device remembers about its workspace between syncs: when it last
+ * edited it (null when that happened while the app was closed, so the time is
+ * unknown), or, when it took the workspace from the cloud, that copy as synced.
+ */
+interface LayoutMemo {
+  intent: string;
+  editedAt: number | null;
+  synced?: Record<string, unknown>;
+}
+
+function readLayoutMemo(value: unknown): LayoutMemo | null {
+  if (!isRecord(value) || typeof value.intent !== "string") return null;
+  return {
+    intent: value.intent,
+    editedAt: typeof value.editedAt === "number" && Number.isFinite(value.editedAt) ? value.editedAt : null,
+    ...(isRecord(value.synced) ? { synced: value.synced } : {}),
+  };
+}
+
+/**
+ * When a pulled workspace was last edited. A copy from a build that did not
+ * date edits counts as edited when it was pushed, which is never earlier.
+ */
+function pulledLayoutEditedAt(payload: Record<string, unknown>, pushedAt: string | undefined): number {
+  if (typeof payload.layoutEditedAt === "number" && Number.isFinite(payload.layoutEditedAt)) return payload.layoutEditedAt;
+  const pushed = pushedAt ? Date.parse(pushedAt) : Number.NaN;
+  return Number.isFinite(pushed) ? pushed : Number.POSITIVE_INFINITY;
+}
+
+/**
+ * Whether a pulled workspace replaces this device's, three ways: against the
+ * copy this device last synced, the one it had when the pull started, and the
+ * pulled one. Only a real edit here keeps the local copy; the pane state,
+ * focus and window stacking that change on every launch never do.
+ */
+function shouldAdoptPulledLayout({
+  local,
+  atPullStart,
+  lastSynced,
+  pulled,
+  memo,
+  pulledEditedAt,
+}: {
+  local: string | null;
+  atPullStart: string | null;
+  lastSynced: string | null;
+  pulled: string | null;
+  memo: LayoutMemo | null;
+  pulledEditedAt: number;
+}): boolean {
+  if (pulled === null || pulled === local) return false;
+  // Edited while the pull was in flight: newer than anything it carries.
+  if (local !== atPullStart) return false;
+  const takenFromCloud = !!memo?.synced && memo.intent === local;
+  const editedHere = lastSynced !== null && local !== lastSynced && !takenFromCloud;
+  if (!editedHere) return true;
+  // The cloud still holds what this device last synced: only this side changed.
+  if (pulled === lastSynced) return false;
+  // Both sides changed since: the later edit wins, and an undated local one loses.
+  const localEditedAt = memo?.intent === local ? memo.editedAt : null;
+  return localEditedAt === null || localEditedAt <= pulledEditedAt;
+}
+
+/**
+ * The workspace as the cloud already has it unless this device really edited
+ * it, so what only reflects this device never replaces another device's copy,
+ * and a real edit goes out dated.
+ */
+function withLayoutProvenance(
+  payload: Record<string, unknown>,
+  lastSyncedPayload: unknown,
+  memoValue: unknown,
+): Record<string, unknown> {
+  const local = layoutIntent(payload);
+  if (local === null) return payload;
+  const memo = readLayoutMemo(memoValue);
+  if (memo?.synced && memo.intent === local) return { ...payload, ...memo.synced };
+  if (isRecord(lastSyncedPayload) && layoutIntent(lastSyncedPayload) === local) {
+    return { ...payload, ...pickLayoutPayload(lastSyncedPayload) };
+  }
+  return {
+    ...payload,
+    layoutEditedAt: memo?.intent === local && memo.editedAt !== null ? memo.editedAt : Date.now(),
+  };
+}
+
+/**
+ * Dates a workspace edit when it happens, online or not, so a later conflict
+ * with another device's edit goes to the newer one.
+ */
+function noteLayoutEdit(config: AppConfig, lastSyncedPayload: unknown, memoValue: unknown, launch: boolean): LayoutMemo | null {
+  const lastSynced = layoutIntent(lastSyncedPayload);
+  if (lastSynced === null) return null;
+  const local = layoutIntent(collectLayoutPayload(config));
+  if (local === null || local === lastSynced) return null;
+  if (readLayoutMemo(memoValue)?.intent === local) return null;
+  // Seen at launch, it was made while the app was closed or just before it
+  // quit; when is unknown, so it gives way to a dated edit elsewhere.
+  return { intent: local, editedAt: launch ? null : Date.now() };
+}
+
+/**
+ * Once this device holds the cloud's workspace, by taking it or because the
+ * two already matched, it remembers that copy as synced, keyed by how it
+ * looks here once applied. The next push then sends the cloud's own copy back
+ * rather than this device's rendering of it.
+ */
+function rememberCloudLayout(
+  payload: Record<string, unknown>,
+  pushedAt: string | undefined,
+  applied: AppConfig,
+  memo: { get(): unknown; set(value: unknown): void },
+  adopted: boolean,
+): void {
+  const local = layoutIntent(collectLayoutPayload(applied));
+  if (local === null || (!adopted && local !== layoutIntent(payload))) return;
+  const current = readLayoutMemo(memo.get());
+  if (!adopted && current?.synced && current.intent === local) return;
+  const editedAt = pulledLayoutEditedAt(payload, pushedAt);
+  memo.set({
+    intent: local,
+    editedAt: Number.isFinite(editedAt) ? editedAt : null,
+    synced: pickLayoutPayload(payload),
+  } satisfies LayoutMemo);
+}
+
+interface LayoutMergeContext {
+  memo?: unknown;
+  /** When the pulled copy was pushed, for one from a build that did not date layout edits. */
+  pushedAt?: string;
+}
+
 function mergeConfigPayload(
   config: AppConfig,
   payload: unknown,
   baselineConfig: AppConfig = config,
   lastSyncedPayload?: unknown,
+  layoutContext: LayoutMergeContext = {},
 ): AppConfig | null {
   if (!isRecord(payload)) return null;
   const next: AppConfig = { ...config };
@@ -634,11 +836,9 @@ function mergeConfigPayload(
   // was in flight; lastSyncedPayload catches edits made while the app was not
   // running at all (CLI writes, offline edits), which otherwise look pristine.
   const lastSynced = isRecord(lastSyncedPayload) ? lastSyncedPayload : null;
-  const localPayload = lastSynced
-    ? collectCoreConfigPayload(config) as Record<string, unknown>
-    : null;
+  const localPayload = collectCoreConfigPayload(config) as Record<string, unknown>;
   const matchesLastSynced = (key: string) => (
-    !lastSynced || valuesEqual(localPayload?.[key], lastSynced[key])
+    !lastSynced || valuesEqual(localPayload[key], lastSynced[key])
   );
   const canApply = <K extends keyof AppConfig>(key: K) => (
     valuesEqual(config[key], baselineConfig[key]) && matchesLastSynced(key as string)
@@ -689,15 +889,20 @@ function mergeConfigPayload(
     );
   }
 
-  const layoutStateUntouched = config.layout === baselineConfig.layout
-    && config.layouts === baselineConfig.layouts
-    && config.activeLayoutIndex === baselineConfig.activeLayoutIndex
-    && ["layout", "layouts", "activeLayoutIndex"].every(matchesLastSynced);
-  if (
-    layoutStateUntouched
-    && ["layout", "layouts", "activeLayoutIndex"].every((key) => key in payload)
-    && Array.isArray(payload.layouts)
-  ) {
+  // Compared by content, not identity: the active layout mirrors pane state,
+  // so a cursor settling at launch replaced it mid-pull, the pulled workspace
+  // was refused, and the push that followed wrote this device's older one
+  // over it on every other device.
+  const localIntent = layoutIntent(localPayload);
+  const adoptLayout = shouldAdoptPulledLayout({
+    local: localIntent,
+    atPullStart: baselineConfig === config ? localIntent : layoutIntent(collectLayoutPayload(baselineConfig)),
+    lastSynced: layoutIntent(lastSynced),
+    pulled: layoutIntent(payload),
+    memo: readLayoutMemo(layoutContext.memo),
+    pulledEditedAt: pulledLayoutEditedAt(payload, layoutContext.pushedAt),
+  });
+  if (adoptLayout) {
     next.layout = payload.layout as unknown as AppConfig["layout"];
     next.layouts = withLocalSessionLayoutState(payload.layouts as AppConfig["layouts"], config.layouts);
     next.activeLayoutIndex = payload.activeLayoutIndex as number;
@@ -872,24 +1077,43 @@ function tickerChangedSinceLastSync(
   return !valuesEqual(withoutQuote(local), withoutQuote(baseline));
 }
 
+const CORE_CONFIG_CONTRIBUTOR_ID = "core.config";
+
 export const coreConfigSyncContributor: SyncContributor = {
-  id: "core.config",
+  id: CORE_CONFIG_CONTRIBUTOR_ID,
   schemaVersion: 1,
-  collect: ({ state }) => collectCoreConfigPayload(state.config),
-  apply: async (payload, { baselinePayload, baselineState, state, getState, isCurrent, dispatch, tickerRepository }) => {
-    const nextConfig = mergeConfigPayload(state.config, payload, baselineState.config, baselinePayload);
-    if (!nextConfig || valuesEqual(nextConfig, state.config)) return;
-    // Adopting another device's workspace rearranges the screen under the
-    // user, so it is worth a line in the log when a report says "my panes
-    // moved on their own".
-    if (nextConfig.layout !== state.config.layout) {
-      log.info("config.layout.adopted", {
-        panes: nextConfig.layout.instances.length,
-        activeLayoutIndex: nextConfig.activeLayoutIndex,
-      });
+  collect: ({ state, baselinePayload, memo }) => withLayoutProvenance(
+    collectCoreConfigPayload(state.config) as Record<string, unknown>,
+    baselinePayload,
+    memo?.get(),
+  ),
+  observe: ({ state, baselinePayload, memo, launch }) => {
+    const edit = noteLayoutEdit(state.config, baselinePayload, memo.get(), launch);
+    if (edit) memo.set(edit);
+  },
+  apply: async (payload, { snapshot, baselinePayload, baselineState, state, getState, isCurrent, dispatch, tickerRepository, memo }) => {
+    const pushedAt = snapshot?.contributors[CORE_CONFIG_CONTRIBUTOR_ID]?.updatedAt;
+    const nextConfig = mergeConfigPayload(state.config, payload, baselineState.config, baselinePayload, {
+      memo: memo?.get(),
+      pushedAt,
+    });
+    if (!nextConfig) return;
+    const configChanged = !valuesEqual(nextConfig, state.config);
+    if (configChanged) {
+      // Adopting another device's workspace rearranges the screen under the
+      // user, so it is worth a line in the log when a report says "my panes
+      // moved on their own".
+      if (nextConfig.layout !== state.config.layout) {
+        log.info("config.layout.adopted", {
+          panes: nextConfig.layout.instances.length,
+          activeLayoutIndex: nextConfig.activeLayoutIndex,
+        });
+      }
+      dispatch({ type: "SET_CONFIG", config: nextConfig });
+      scheduleConfigSave(nextConfig);
     }
-    dispatch({ type: "SET_CONFIG", config: nextConfig });
-    scheduleConfigSave(nextConfig);
+    if (memo && isRecord(payload)) rememberCloudLayout(payload, pushedAt, getState().config, memo, nextConfig.layouts !== state.config.layouts);
+    if (!configChanged) return;
 
     // A profile removed on another device takes its positions with it here
     // too; kept, this device would push them back and recreate the tickers

package/src/sync/types.ts

@@ -19,8 +19,29 @@ export interface SyncSnapshot {
   contributors: Record<string, SyncContributorPayload>;
 }
 
+/**
+ * What this device remembers about its own copy of one contributor's data
+ * between syncs, kept across launches: when it last edited it, or which cloud
+ * copy it took. Never sent anywhere.
+ */
+interface SyncContributorMemo {
+  get(): unknown;
+  set(value: unknown): void;
+}
+
 interface SyncCollectContext {
   state: AppState;
+  /** The payload this device last pushed for this contributor, or null when it never synced. */
+  baselinePayload?: unknown;
+  memo?: SyncContributorMemo;
+}
+
+interface SyncObserveContext {
+  state: AppState;
+  baselinePayload: unknown;
+  memo: SyncContributorMemo;
+  /** True for the first look after the app started: a change seen then was made while it was closed. */
+  launch: boolean;
 }
 
 interface SyncApplyContext {
@@ -37,6 +58,7 @@ interface SyncApplyContext {
   isCurrent: () => boolean;
   dispatch: Dispatch<AppAction>;
   tickerRepository: AppTickerRepositoryPort;
+  memo?: SyncContributorMemo;
 }
 
 export interface SyncContributor {
@@ -44,6 +66,12 @@ export interface SyncContributor {
   schemaVersion: number;
   collect(context: SyncCollectContext): unknown | Promise<unknown>;
   apply?(payload: unknown, context: SyncApplyContext): void | Promise<void>;
+  /**
+   * Called before every sync attempt and shortly after local changes, online
+   * or not, so an edit can be dated when it happens rather than when the
+   * network is next reachable.
+   */
+  observe?(context: SyncObserveContext): void;
 }
 
 export interface SyncSnapshotResponse {
@@ -63,9 +91,22 @@ export interface SyncTransport {
   id: string;
   isAvailable(): boolean;
   pullSnapshot(): Promise<SyncSnapshotResponse>;
+  /**
+   * `baseRevision` is the stored revision the snapshot was merged with (0 when
+   * there was none). A transport that can refuse a write made against an older
+   * revision throws `SyncRevisionConflictError`, and the controller pulls again.
+   */
   pushSnapshot(snapshot: SyncSnapshot, options?: { baseRevision?: number | null }): Promise<SyncPushResult>;
 }
 
+/** Another device wrote since this one pulled; its push would have replaced that write. */
+export class SyncRevisionConflictError extends Error {
+  constructor(message = "The synced copy changed since it was pulled.") {
+    super(message);
+    this.name = "SyncRevisionConflictError";
+  }
+}
+
 export interface SyncSettings {
   syncEnabled: boolean;
   weeklyRoundupEnabled: boolean;
@@ -79,6 +120,9 @@ export interface SyncSettings {
 export interface SyncBaselineStore {
   load(): Record<string, unknown> | null;
   save(payloads: Record<string, unknown>): void;
+  /** Contributor memos by contributor id; see `SyncContributorMemo`. */
+  loadMemos?(): Record<string, unknown> | null;
+  saveMemos?(memos: Record<string, unknown>): void;
 }
 
 export interface RegisteredSyncContributor {

package/src/time-series/resolve.ts

@@ -1235,6 +1235,21 @@ function baseSecuritySeries(
   };
 }
 
+const FRED_CATALOG_UNITS: Readonly<Record<string, string>> = {
+  "percent": "%",
+  "millions of u.s. dollars": "million USD",
+  "millions of dollars": "million USD",
+  "billions of dollars": "billion USD",
+  "billions of u.s. dollars": "billion USD",
+  "billions of us dollars": "billion USD",
+  "dollars per barrel": "USD/barrel",
+  "thousands of persons": "thousand people",
+};
+
+function fredCatalogUnit(units: string): string {
+  return FRED_CATALOG_UNITS[units.toLowerCase()] ?? units;
+}
+
 function baseEconomicSeries(
   spec: ChartSeriesSpec,
   loaded: FredSeriesLoadResult,
@@ -1243,13 +1258,15 @@ function baseEconomicSeries(
   if (spec.source.kind !== "economic") return null;
   const { data } = loaded;
   const units = data.info?.units?.trim() || "value";
+  const catalogUnit = fredCatalogUnit(units);
+  // "Percent Change from Year Ago" and "Percent per Annum" are percent too.
   const isPercent = units.toLowerCase().includes("percent");
   return {
     id: spec.id,
     label: spec.label?.trim() || data.info?.title?.trim() || spec.source.seriesId,
     color: spec.color ?? SERIES_COLORS[index % SERIES_COLORS.length]!,
-    unit: isPercent ? "%" : units,
-    unitGroup: isPercent ? "percent" : `economic:${units.toLowerCase()}`,
+    unit: isPercent ? "%" : catalogUnit,
+    unitGroup: isPercent ? "percent" : `economic:${catalogUnit.toLowerCase()}`,
     nativeFrequency: "auto",
     timestampMode: "period-end",
     dataShape: "scalar",

package/src/types/data-provider.ts

@@ -180,6 +180,14 @@ export interface QuoteBatchOptions {
    * provider with no cache answers every target with no quote.
    */
   cacheOnly?: boolean;
+  /**
+   * Ask the sources even for a target whose cached quote is still fresh; that
+   * copy answers only when they cannot. A command that prints quotes once
+   * shows the service's quote of the moment, so every form of one listing
+   * (BRK.B saved on NYSE, BRK-B, BRK.B:NYSE) prints the same quote, never
+   * each form's own copy from whenever it was last asked for.
+   */
+  revalidate?: boolean;
   /** The caller stopped waiting; a transport that can abandon the request does. */
   signal?: AbortSignal;
 }

package/src/types/financials.ts

@@ -5,6 +5,20 @@ export type SessionConfidence = "explicit" | "derived" | "unknown";
 export type QuoteDataSource = "live" | "delayed" | "snapshot";
 export type QuoteDelivery = "stream" | "poll";
 
+/**
+ * The regular sessions an index quote carries, dated by its source: the
+ * calendar its publisher's name does not give (SNP, DJI, NASDAQ GIDS). Times
+ * are ms.
+ */
+export interface QuoteIndexSession {
+  /** The zone the sessions' dates are read in. */
+  timeZone: string;
+  /** The regular session the quote's day follows: today's, or the next one while it has not opened. */
+  current: { start: number; end: number };
+  /** The latest regular sessions, oldest first. */
+  regular: Array<{ start: number; end: number }>;
+}
+
 export interface QuoteFieldProvenance {
   providerId: string;
   dataSource?: QuoteDataSource;
@@ -100,6 +114,8 @@ export interface Quote extends DepositaryReceiptFacts {
   routingExchangeFullName?: string;
   marketState?: MarketState;
   sessionConfidence?: SessionConfidence;
+  /** An index's own regular sessions, for the open its pre-market waits for and the close its last print was. */
+  indexSession?: QuoteIndexSession;
   preMarketPrice?: number;
   preMarketChange?: number;
   preMarketChangePercent?: number;
@@ -245,15 +261,17 @@ export interface Fundamentals extends DepositaryReceiptFacts {
   return3Y?: number;
   lastQuarterGrowth?: number;
   sharesOutstanding?: number;
-  /** Free float: shares outstanding less insider and strategic holdings. */
+  /** Free float: shares outstanding less insider and strategic holdings, never above `sharesOutstanding`. */
   floatShares?: number;
   beta?: number;
-  /** Shares sold short at the source's latest settlement. */
+  /** Shares short at the latest FINRA settlement, the one `SI` and `SIW` show; dated by `shortInterestDate`. */
   sharesShort?: number;
-  /** Shares short over float from the same observation, as a fraction (0.0127 for 1.27%). */
+  /** `sharesShort` over `floatShares`, as a fraction (0.0127 for 1.27%). */
   shortPercentOfFloat?: number;
-  /** Days to cover: shares short over average daily volume. */
+  /** Days to cover as FINRA states it for the settlement: shares short over the period's average daily volume. */
   shortRatio?: number;
+  /** The settlement date (YYYY-MM-DD) of `sharesShort`, `shortPercentOfFloat` and `shortRatio`. */
+  shortInterestDate?: string;
   /** Fractions of shares outstanding. */
   insiderPercentHeld?: number;
   institutionPercentHeld?: number;
@@ -366,6 +384,20 @@ export interface DividendAction {
   amount: number;
 }
 
+/**
+ * A distribution the issuer has declared and not yet paid, as the source
+ * states it. Kept apart from the paid `dividends`: no history, yield or growth
+ * figure takes it.
+ */
+export interface DeclaredDividendAction {
+  exDate: string;
+  /** Per share, in the listing's dividend currency (`currency`). */
+  amount: number;
+  declarationDate?: string;
+  recordDate?: string;
+  payDate?: string;
+}
+
 export interface SplitAction {
   date: string;
   description?: string;
@@ -417,6 +449,8 @@ export interface CorporateActionsData {
   micCode?: string;
   exchangeTimezone?: string;
   dividends: DividendAction[];
+  /** Declared and unpaid, for the listings Gloom Cloud has them for; absent elsewhere and from older servers. */
+  declaredDividends?: DeclaredDividendAction[];
   splits: SplitAction[];
   earnings: EarningsAction[];
 }
@@ -757,6 +791,8 @@ export interface PricePoint {
   partial?: boolean;
   /** The bar's prices were rebuilt from shorter bars where the source left it empty or too coarse. */
   filled?: boolean;
+  /** A future's session that has closed but whose settlement is not confirmed yet: its close is the last trade. */
+  unsettled?: boolean;
 }
 
 export interface StatementHistoryAttempt {

package/src/types/headless.ts

@@ -257,6 +257,12 @@ export interface HeadlessPaneFreshness {
   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;
+  /**
+   * Rows quoted on several markets (a US line beside Xetra and Paris ones)
+   * date each market's session in the status line, `US, XETRA and EPA Tue 13
+   * Oct 2026 close`, instead of only the newest row's.
+   */
+  datesEachVenue?: boolean;
   /**
    * Exports also cite the oldest observation whenever the rows are dated
    * apart, not only when it is a day older: a portfolio valued at one
@@ -265,6 +271,12 @@ export interface HeadlessPaneFreshness {
   citeOldest?: boolean;
   /** What the figures are, said after the status: `funding = current estimate, pays 08:00 UTC`. */
   note?: string;
+  /**
+   * When the figures reach readers and when the next ones are due, said right
+   * after the as-of date: `published Fri 9 Oct, next settlement Thu 15 Oct,
+   * published Mon 26 Oct` for a settlement a regulator publishes days later.
+   */
+  schedule?: string;
 }
 
 interface HeadlessPaneResultBase {
@@ -295,6 +307,12 @@ interface HeadlessPaneResultBase {
 
 export interface HeadlessRowsResult extends HeadlessPaneResultBase {
   columns?: HeadlessPaneColumn[];
+  /**
+   * The columns the text report prints in place of `columns`, when the
+   * exports carry more than a terminal table should (each cell's source and
+   * as-of beside it). CSV, NDJSON and JSON keep `columns`.
+   */
+  textColumns?: HeadlessPaneColumn[];
   rows: HeadlessPaneRow[];
   /** What the report says when `rows` is empty, in place of "No data.": why there are none. */
   empty?: string;
@@ -401,7 +419,22 @@ export interface HeadlessPaneDefinition<Shape extends HeadlessPaneShape = Headle
    * points at GIP's 1-minute bars). `key` is the listing as read, RMS:ASX.
    */
   usListingsOnlyHint?(key: string): string;
+  /**
+   * `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
+   * exits 0 and names the others in its errors.
+   */
+  failsWithoutData?: boolean;
   options: HeadlessPaneOptionDef[];
+  /**
+   * Widens the argument before the function runs, so its report, its capture
+   * and its pane all read the same symbols: RV's `--peers` adds a symbol's
+   * competitors. Null runs the argument as typed.
+   */
+  expandArgument?(
+    args: HeadlessPaneLoadArgs,
+    ctx: HeadlessPaneContext,
+  ): Promise<HeadlessArgumentExpansion | null>;
   /** What is true of every load: its source, and whether it is a feed. */
   freshness?: HeadlessPaneFreshness;
   columns?: HeadlessPaneColumn[];
@@ -426,3 +459,13 @@ export interface HeadlessPaneDefinition<Shape extends HeadlessPaneShape = Headle
 }
 
 export type HeadlessPaneResult = HeadlessPaneResultByShape[HeadlessPaneShape];
+
+/** What a function runs with once it has widened its argument (`expandArgument`). */
+export interface HeadlessArgumentExpansion {
+  /** The argument as it would be typed: `DUOL, COUR, CHGG`. */
+  argument: string;
+  /** Merged into the pane's settings, which the load reads as `ctx.settings` and the pane as its own. */
+  settings?: Record<string, unknown>;
+  /** The pane's title when the widened argument needs saying (`RV DUOL + auto peers by industry: Airlines`). */
+  title?: string;
+}

package/src/types/plugin.ts

@@ -3,6 +3,7 @@ import type { AppTickerRepositoryPort } from "../core/app-service-ports";
 import type { HeadlessPaneDefinition, HeadlessPaneFreshness, HeadlessPaneOptionDef } from "./headless";
 
 export type {
+  HeadlessArgumentExpansion,
   HeadlessBundleResult,
   HeadlessBundleSection,
   HeadlessFreshnessStatus,
@@ -189,6 +190,12 @@ export interface PaneDef {
    * the last ones. Leave it off for long or paged lists.
    */
   shotFitsRows?: true;
+  /**
+   * A report of the pane grows to the whole text of the page its reader has
+   * open (a docs page), so it is not cut at the first screen. A list the reader
+   * opens from keeps its height.
+   */
+  shotFitsReader?: true;
   /** Add an Excel-compatible CSV action for the pane's single active DataTable. */
   tableExport?: true;
   settings?: PaneSettingsDef | ((context: PaneSettingsContext) => PaneSettingsDef | null);