gloomberb 0.17.2 → 0.17.4

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

@@ -83,7 +83,7 @@ import { getPricePointTimestamp, isPriceHistoryStaleForCurrentWindow } from "../
 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 { futuresGenericCaption, futuresGenericListing, futuresListingPriceBasis } from "../utils/futures-generic";
 import { isOhlcSeriesStyle } from "./spec";
 import { SERIES_COLORS } from "../theme/series-colors";
 import type {
@@ -1166,8 +1166,10 @@ function baseSecuritySeries(
     : field.unit;
   const generic = field.unitGroup === "price"
     ? futuresGenericListing(spec.source.instrument.symbol, spec.source.instrument.exchange) : null;
-  // A generic future on an index, VIX or Treasuries reads in points or 32nds, not dollars.
-  const genericBasis = generic && isMarketFieldId(field.id) ? futuresGenericPriceBasis(generic) : null;
+  // A generic future on an index, VIX or Treasuries reads in points or 32nds, and an index
+  // future's continuous symbol or contract in points, not dollars, as its quote does.
+  const genericBasis = field.unitGroup === "price" && isMarketFieldId(field.id)
+    ? futuresListingPriceBasis(spec.source.instrument.symbol, spec.source.instrument.exchange) : null;
   const genericUnit = genericBasis === "points" ? "points" : genericBasis === "thirty-seconds" ? "32nds" : null;
   const unit = field.id === "market.volume" ? volumeUnit ?? ""
     : genericUnit ?? (unitTemplate.startsWith("currency") && currency ? unitTemplate.replace("currency", currency) : unitTemplate);
@@ -1235,6 +1237,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 +1260,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);

package/src/ui/resize-settle.ts

@@ -0,0 +1,128 @@
+import { useContext, useEffect, useRef, useState } from "react";
+import { isLiveResizing, onLiveResizeEnd } from "./live-resize";
+import { LivePaneFrameContext, type CellSize } from "./live-stretch";
+
+/**
+ * How long a box's size has to hold still before what is laid out in it
+ * settles at that size. A resize's content catches up every 100 ms
+ * (live-resize.ts), so a pane under the pointer stays resizing between its
+ * catch-ups.
+ */
+export const RESIZE_SETTLE_MS = 120;
+
+/**
+ * How far a box may stretch from the size its layout was made for, on either
+ * axis, before the layout is made again mid-resize: past this, tiles and
+ * blocks drawn in percentages of the old size would look squashed or pulled.
+ */
+const MAX_HELD_STRETCH = 1.5;
+
+export interface ResizeHold {
+  /** The box's size as it last rendered. */
+  size: CellSize;
+  /** While the box is resizing, the size its layout holds to; null at rest. */
+  held: CellSize | null;
+}
+
+function stretch(from: number, to: number): number {
+  return from > 0 && to > 0 ? Math.max(from / to, to / from) : Infinity;
+}
+
+/**
+ * The box rendered at `size`: the first change of a resize holds the layout at
+ * the size it had, later ones keep it there, and a stretch past
+ * MAX_HELD_STRETCH lays it out again at the new size (still resizing).
+ */
+export function nextResizeHold(state: ResizeHold, size: CellSize, maxStretch = MAX_HELD_STRETCH): ResizeHold {
+  if (state.size.width === size.width && state.size.height === size.height) return state;
+  const held = state.held ?? state.size;
+  const far = Math.max(stretch(held.width, size.width), stretch(held.height, size.height)) > maxStretch;
+  return { size, held: far ? size : held };
+}
+
+/** At rest: the layout takes the box's size. */
+export function settleResizeHold(state: ResizeHold): ResizeHold {
+  return state.held ? { size: state.size, held: null } : state;
+}
+
+export interface SettledLayoutSize extends CellSize {
+  /**
+   * The box is being resized: from the first move of a resize that has its
+   * pane's frame, or its first change of size, until it has held still for
+   * RESIZE_SETTLE_MS with the pointer let go. Nothing laid out in it should
+   * animate meanwhile.
+   */
+  resizing: boolean;
+}
+
+/**
+ * Desktop: the size to lay out a surface at whose content is placed in
+ * percentages of its box (a heat map's tiles), and whether that box is being
+ * resized. A pane resize, a divider, a maximise or restore and a window
+ * resize all change the box's size, often once a frame; laying the content
+ * out again at every one of them costs a full restyle and moves every tile
+ * each time. Instead, while the size changes the layout holds to the size it
+ * had and the box stretches it by CSS, and once the size has held still it is
+ * laid out once, at the size the box settled on. A stretch too far from the
+ * held size lays it out again on the way.
+ *
+ * `resizing` is the shared signal for anything that animates when its layout
+ * changes (a glide, a fade, a pulse): none of it while the size is changing.
+ * Off (`enabled: false`, the terminal), the size is the box's at once.
+ */
+export function useSettledLayoutSize(
+  width: number,
+  height: number,
+  { enabled = true }: { enabled?: boolean } = {},
+): SettledLayoutSize {
+  const [state, setState] = useState<ResizeHold>(() => ({ size: { width, height }, held: null }));
+  let current = state;
+  if (state.size.width !== width || state.size.height !== height) {
+    // Stored while rendering, so the render that has the new size already lays out at the held one.
+    current = enabled ? nextResizeHold(state, { width, height }) : { size: { width, height }, held: null };
+    setState(current);
+  }
+
+  // A resize that has this pane's frame: it holds still from the first move, before its content catches up.
+  const frame = useContext(LivePaneFrameContext);
+  const [framed, setFramed] = useState(false);
+  const framedRef = useRef(false);
+  useEffect(() => {
+    // Called on every move: only a resize starting or ending is news.
+    const follow = () => {
+      const next = enabled && frame !== null && frame.live() !== null;
+      if (next === framedRef.current) return;
+      framedRef.current = next;
+      setFramed(next);
+    };
+    follow();
+    return enabled ? frame?.subscribe(follow) : undefined;
+  }, [enabled, frame]);
+
+  useEffect(() => {
+    if (!state.held || framed) return;
+    let timer: ReturnType<typeof setTimeout> | null = null;
+    let stopWaiting: (() => void) | null = null;
+    const settle = () => {
+      timer = null;
+      // A box still under the pointer (a sidebar, a split) settles when it is let go, not when the pointer pauses.
+      if (isLiveResizing()) {
+        stopWaiting = onLiveResizeEnd(() => {
+          stopWaiting?.();
+          stopWaiting = null;
+          timer = setTimeout(settle, RESIZE_SETTLE_MS);
+        });
+        return;
+      }
+      setState(settleResizeHold);
+    };
+    timer = setTimeout(settle, RESIZE_SETTLE_MS);
+    return () => {
+      if (timer !== null) clearTimeout(timer);
+      stopWaiting?.();
+    };
+  }, [framed, state]);
+
+  const layout = current.held ?? current.size;
+  return { width: layout.width, height: layout.height, resizing: enabled && (current.held !== null || framed) };
+}

package/src/utils/calendar-date.ts

@@ -29,3 +29,59 @@ export function isoDateDaysAgo(days: number, now = new Date()): string {
 export function isoDateYearsAgo(years: number, now = new Date()): string {
   return isoDateBefore(now, years, 0);
 }
+
+/** YYYY-MM-DD for a day the calendar has; null for a month or day out of range. */
+function calendarDay(year: number, month: number, day: number): string | null {
+  const date = new Date(Date.UTC(year, month - 1, day));
+  return date.getUTCFullYear() === year && date.getUTCMonth() === month - 1 && date.getUTCDate() === day
+    ? date.toISOString().slice(0, 10)
+    : null;
+}
+
+const ISO_DATE = /^(\d{4})-(\d{2})-(\d{2})$/;
+/** A day and a month in either order, then a four-digit year, with one separator throughout: 14/10/2026, 14.10.2026, 14-10-2026. */
+const YEAR_LAST = /^(\d{1,2})([/.-])(\d{1,2})\2(\d{4})$/;
+/** A four-digit year first, written another way than YYYY-MM-DD: 2026/10/14, 2026.10.14, 2026-10-4. */
+const YEAR_FIRST = /^(\d{4})([/.-])(\d{1,2})\2(\d{1,2})$/;
+
+/**
+ * The YYYY-MM-DD date that a date written another way names: 14/10/2026 and
+ * 10/14/2026 are 2026-10-14, since a part over 12 can only be the day. When
+ * both parts could be the month (03/04/2026), only dots are read, day first,
+ * as dotted dates are written (`assumedDayFirst`); a slash or a dash is
+ * written both ways round, so that is null. Null as well for text that is not
+ * a date of the calendar.
+ */
+function isoDateReading(value: string): { date: string; assumedDayFirst: boolean } | null {
+  const text = value.trim();
+  const yearFirst = YEAR_FIRST.exec(text);
+  if (yearFirst) {
+    const date = calendarDay(Number(yearFirst[1]), Number(yearFirst[3]), Number(yearFirst[4]));
+    return date && date !== text ? { date, assumedDayFirst: false } : null;
+  }
+  const yearLast = YEAR_LAST.exec(text);
+  if (!yearLast) return null;
+  const [first, second, year] = [Number(yearLast[1]), Number(yearLast[3]), Number(yearLast[4])];
+  const monthFirst = first <= 12 && second > 12;
+  const either = first <= 12 && second <= 12 && first !== second;
+  if (either && yearLast[2] !== ".") return null;
+  const date = monthFirst ? calendarDay(year, first, second) : calendarDay(year, second, first);
+  return date ? { date, assumedDayFirst: either } : null;
+}
+
+/**
+ * A date option's value, checked before any request is made: YYYY-MM-DD as
+ * typed, or an error that names the format. A date written another way gets
+ * the option to type instead (`--from 2026-10-14` for 14/10/2026); one whose
+ * day and month could be either way round gets an example of the format. An
+ * empty value is no date.
+ */
+export function isoDateOption(value: string, flag: string, now = new Date()): string {
+  const text = value.trim();
+  const iso = ISO_DATE.exec(text);
+  if (!text || (iso && calendarDay(Number(iso[1]), Number(iso[2]), Number(iso[3])))) return text;
+  const format = `Use a --${flag} date in YYYY-MM-DD format`;
+  const reading = isoDateReading(text);
+  if (reading) throw new Error(`${format}: type --${flag} ${reading.date} for ${text}${reading.assumedDayFirst ? " (day first)" : ""}.`);
+  throw new Error(`${format}, such as --${flag} ${isoDateToday(now)}.`);
+}

package/src/utils/decimal-comma.ts

@@ -92,3 +92,34 @@ export function parsePastedNumber(value: unknown): PastedNumber {
 export function ambiguousNumberMessage(text: string, reading: { thousands: number; decimal: number }): string {
   return `${text.trim()} could be ${reading.thousands} (thousands) or ${reading.decimal} (decimal comma); type ${reading.thousands} or ${reading.decimal}`;
 }
+
+/** What a dot and exactly three digits after one to three (`81.000`, `81.250`) could mean. */
+export interface ThousandsDotReadings {
+  /** The number as written, the dot a decimal point: 81. */
+  decimal: number;
+  /** The dot as many locales write it, between thousands: 81000. */
+  thousands: number;
+}
+
+const THOUSANDS_DOT = /^([+-]?)([1-9]\d{0,2})\.(\d{3})$/;
+
+/** Both readings of `81.000`; null for any other text, which has one. */
+export function thousandsDotReadings(value: unknown): ThousandsDotReadings | null {
+  const match = THOUSANDS_DOT.exec(typeof value === "string" ? value.trim() : "");
+  if (!match) return null;
+  const sign = match[1] === "-" ? -1 : 1;
+  return { decimal: sign * Number(`${match[2]}.${match[3]}`), thousands: sign * Number(`${match[2]}${match[3]}`) };
+}
+
+/**
+ * Whether a dot and three digits was meant as a thousands separator, beside a
+ * price it must be near (the last price): the number as written is more than
+ * 90% away from it, while the thousands reading lands within 10%. A plain
+ * dotted number otherwise keeps its meaning, and without a reference it is
+ * read as written.
+ */
+export function meantThousandsDot(readings: ThousandsDotReadings, reference: number | null | undefined): boolean {
+  if (reference == null || !Number.isFinite(reference) || reference === 0) return false;
+  const scale = Math.abs(reference);
+  return Math.abs(readings.decimal - reference) * 10 > scale * 9 && Math.abs(readings.thousands - reference) * 10 <= scale;
+}

package/src/utils/declared-dividends.ts

@@ -0,0 +1,39 @@
+import type { CorporateActionsData, DeclaredDividendAction } from "../types/financials";
+
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
+/** A paid row this close to a declared one is that distribution, dated a day apart. */
+const SAME_DISTRIBUTION_DAYS = 3;
+const DAY_MS = 86_400_000;
+
+function isoDate(value: unknown): string | undefined {
+  return typeof value === "string" && ISO_DATE.test(value) && Number.isFinite(Date.parse(`${value}T00:00:00Z`)) ? value : undefined;
+}
+
+/**
+ * The declared, unpaid distributions a corporate actions payload carries,
+ * oldest first: rows the source states with a real ex-date and amount, still
+ * owed today (not yet paid, or with no pay date, not yet ex), and not in the
+ * paid history yet. Kept apart from `dividends`, which history, yields and
+ * growth read. A server that does not send them, or a listing it has none
+ * for, gives none.
+ */
+export function declaredDividends(
+  actions: Pick<CorporateActionsData, "dividends" | "declaredDividends"> | null | undefined,
+  now = new Date(),
+): DeclaredDividendAction[] {
+  if (!Array.isArray(actions?.declaredDividends)) return [];
+  const today = now.toISOString().slice(0, 10);
+  const paid = (actions.dividends ?? []).map((payment) => Date.parse(`${payment.exDate}T00:00:00Z`));
+  return actions.declaredDividends.flatMap((row): DeclaredDividendAction[] => {
+    const exDate = isoDate(row?.exDate);
+    if (!exDate || typeof row.amount !== "number" || !Number.isFinite(row.amount) || row.amount <= 0) return [];
+    const payDate = isoDate(row.payDate);
+    const declarationDate = isoDate(row.declarationDate);
+    const recordDate = isoDate(row.recordDate);
+    if ((payDate ?? exDate) < today) return [];
+    const at = Date.parse(`${exDate}T00:00:00Z`);
+    if (paid.some((time) => Math.abs(time - at) <= SAME_DISTRIBUTION_DAYS * DAY_MS)) return [];
+    return [{ exDate, amount: row.amount, ...declarationDate ? { declarationDate } : {},
+      ...recordDate ? { recordDate } : {}, ...payDate ? { payDate } : {} }];
+  }).sort((left, right) => left.exDate.localeCompare(right.exDate));
+}