gloomberb 0.16.1 → 0.16.3

package/src/types/headless.ts

@@ -71,7 +71,12 @@ export interface HeadlessPaneContext {
   settings?: Record<string, unknown>;
   capabilities?: CapabilityInvoker;
   /** Read one local portfolio without passing holdings through a remote endpoint. */
-  resolvePortfolio?: (id: string) => Promise<{ portfolio: import("./ticker").Portfolio; tickers: import("./ticker").TickerRecord[] } | null>;
+  resolvePortfolio?: (id: string) => Promise<{
+    portfolio: import("./ticker").Portfolio;
+    tickers: import("./ticker").TickerRecord[];
+    /** The broker account the portfolio was last synced with, as saved on this device. */
+    account?: import("./trading").BrokerAccount | null;
+  } | null>;
   /** Read locally remembered watchlist membership. */
   resolveWatchlist?: (id: string) => Promise<import("./ticker").TickerRecord[] | null>;
   /** Resolve locally remembered exchange identities without coupling plugins to storage. */
@@ -97,6 +102,63 @@ export interface HeadlessPaneEntry {
   formatted?: string;
 }
 
+/**
+ * How current a report's data is (docs/usage.md#how-current-a-report-is):
+ * - `live`: a real-time feed, such as a streaming venue or a real-time quote.
+ * - `delayed`: a feed held back on purpose, by `delayMinutes` when known.
+ * - `stale`: a feed or scheduled release whose newest observation is older
+ *   than that kind of data allows.
+ * - `not-a-feed`: data that is not a feed at all (filings, fundamentals,
+ *   calendars, statistics releases, calculators, local portfolio data). It
+ *   never reads stale just because it is old.
+ */
+export type HeadlessFreshnessStatus = "live" | "delayed" | "stale" | "not-a-feed";
+
+/**
+ * What a report can cite about its data. Every field is optional: the report
+ * fills what is missing from the result itself (quote `dataSource`,
+ * `delayMinutes`, `stale`, `asOf`/`observedAt`/`lastUpdated` fields, the last
+ * point of each series), so a pane declares only what that would get wrong.
+ */
+export interface HeadlessPaneFreshness {
+  /**
+   * Who a reader would cite: the venue, exchange or agency for primary data
+   * ("SEC EDGAR", "Hyperliquid"), "Gloom Cloud" for aggregated market data,
+   * "Local data" or "Your inputs". Never a data vendor or an internal provider id.
+   */
+  source?: string;
+  /** Newest observation in the data. A `YYYY-MM-DD` string reads as a date without a time. */
+  asOf?: string | number | Date | null;
+  /** Oldest observation, mentioned when it is far older than `asOf`; `null` when the rows are a history. */
+  oldest?: string | number | Date | null;
+  /**
+   * The row field that says when each row was observed, when it is not one of
+   * the standard names (`asOf`, `observedAt`, `lastUpdated`...). The report is
+   * then dated by that field alone, not by metadata stamps.
+   */
+  observedKey?: string;
+  status?: HeadlessFreshnessStatus;
+  /** How far a delayed feed is held back, in minutes. */
+  delayMinutes?: number;
+  /** What not-a-feed data is, in a few words: "filed data", "monthly release", "your inputs". */
+  basis?: string;
+  /** The newest observation is stale once it is older than this many minutes. */
+  maxAgeMinutes?: number;
+  /**
+   * The rows' and metadata's own `stale` flags mean something other than "this
+   * value is out of date" (a historical marker, a cache state), so the report
+   * judges staleness from the schedule alone.
+   */
+  ignoreStaleFlags?: boolean;
+  /**
+   * `daily`: one observation per US trading day, stale once more than one
+   * completed session has passed after the newest (a day's lag is allowed).
+   */
+  cadence?: "daily";
+  /** The newest observation is stale once this time (the next scheduled release) has passed by a day. */
+  nextExpectedAt?: string | number | Date | null;
+}
+
 interface HeadlessPaneResultBase {
   /** False when usable output does not fully cover the requested inputs/depth. */
   complete?: boolean;
@@ -104,8 +166,17 @@ interface HeadlessPaneResultBase {
   symbols?: string[];
   /** Missing inputs must remain visible even when other inputs returned rows. */
   unavailableSymbols?: string[];
+  /** Failures: a source that did not answer, or a value that could not be computed. */
   errors?: string[];
+  /**
+   * Caveats about a report that did load: what it leaves out, what it assumes,
+   * how a value was marked. One sentence each. They never make a report fail;
+   * `complete: false` says when the report does not cover what was asked.
+   */
+  notes?: string[];
   metadata?: Record<string, unknown>;
+  /** What this load knows about its data's source and age; overrides the definition's `freshness`. */
+  freshness?: HeadlessPaneFreshness;
 }
 
 export interface HeadlessRowsResult extends HeadlessPaneResultBase {
@@ -185,8 +256,14 @@ export interface HeadlessPaneDefinition<Shape extends HeadlessPaneShape = Headle
   description?: string;
   argument: HeadlessPaneArgumentDef;
   options: HeadlessPaneOptionDef[];
+  /** What is true of every load: its source, and whether it is a feed. */
+  freshness?: HeadlessPaneFreshness;
   columns?: HeadlessPaneColumn[];
-  describe?: string | ((args: HeadlessPaneLoadArgs) => string);
+  /**
+   * The report title. A report passes the loaded result, so a title can name
+   * what the load resolved (the view an `auto` query became, a fund's name).
+   */
+  describe?: string | ((args: HeadlessPaneLoadArgs, result?: HeadlessPaneResult) => string);
   load(
     args: HeadlessPaneLoadArgs,
     ctx: HeadlessPaneContext,

package/src/types/plugin.ts

@@ -1,10 +1,11 @@
 import type { ReactNode } from "react";
 import type { AppTickerRepositoryPort } from "../core/app-service-ports";
-import type { HeadlessPaneDefinition } from "./headless";
+import type { HeadlessPaneDefinition, HeadlessPaneFreshness } from "./headless";
 
 export type {
   HeadlessBundleResult,
   HeadlessBundleSection,
+  HeadlessFreshnessStatus,
   HeadlessPaneApiClient,
   HeadlessPaneArgumentDef,
   HeadlessPaneArgumentKind,
@@ -12,6 +13,7 @@ export type {
   HeadlessPaneContext,
   HeadlessPaneDefinition,
   HeadlessPaneEntry,
+  HeadlessPaneFreshness,
   HeadlessPaneLoadArgs,
   HeadlessPaneOptionDef,
   HeadlessPaneOptionType,
@@ -124,6 +126,12 @@ export interface PaneDef {
   tickerFollower?: boolean | ((pane: PaneInstanceConfig) => boolean);
   /** Renderer-neutral data model used by CLI functions, automation, and hosted tools. */
   headless?: HeadlessPaneDefinition;
+  /**
+   * Source and status a rendered-view report (`fn` on a pane without a
+   * `headless` model) cites, when "Gloom Cloud" with the state the footer
+   * shows would be wrong: local data, a calculator, filed records.
+   */
+  reportFreshness?: Pick<HeadlessPaneFreshness, "source" | "status" | "basis">;
   /** Add an Excel-compatible CSV action for the pane's single active DataTable. */
   tableExport?: true;
   settings?: PaneSettingsDef | ((context: PaneSettingsContext) => PaneSettingsDef | null);
@@ -146,6 +154,12 @@ export interface PaneQuickSettingDef {
    * it off picks the field's other option.
    */
   onValue?: string;
+  /**
+   * Shows the control only where it changes something, for a setting that
+   * applies to some of what the pane can show. The field stays in the
+   * settings dialog either way.
+   */
+  visible?: (context: PaneSettingsContext) => boolean;
 }
 
 export interface PaneSettingsContext {
@@ -264,6 +278,11 @@ interface PaneTemplateShortcut {
   aliases?: readonly string[];
   argPlaceholder?: string;
   argKind?: "text" | "ticker" | "ticker-list";
+  /**
+   * For a ticker list, entries kept as typed instead of resolved as tickers:
+   * CORR keeps map series (`GEO:HORMUZ`) beside its tickers.
+   */
+  keepArgToken?: (token: string) => boolean;
   argOptional?: boolean;
   /**
    * With no argument typed and none to infer from the active ticker, open

package/src/types/ticker.ts

@@ -56,6 +56,21 @@ export interface Portfolio {
   lastSyncedAt?: number;
   /** Set on paper portfolios shared with a team; the server holds the items. */
   teamId?: string;
+  /**
+   * Cash held beside the positions, entered by hand. A broker account that
+   * reports its own cash is shown instead of this.
+   */
+  cash?: PortfolioCash;
+  /**
+   * Target weights in percent of the total value, cash included, keyed by
+   * ticker symbol; `CASH` is the cash line.
+   */
+  targetWeights?: Record<string, number>;
+}
+
+export interface PortfolioCash {
+  amount: number;
+  currency: string;
 }
 
 export interface Watchlist {

package/src/ui/host.tsx

@@ -108,6 +108,12 @@ export interface SyntaxStyleLike {
   }): number;
 }
 
+/** Where a drag has a box this frame: an offset in cells from where it is laid out. */
+export interface LiveBoxFrame {
+  dx: number;
+  dy: number;
+}
+
 export interface BoxRenderable {
   x?: number;
   y?: number;
@@ -117,6 +123,12 @@ export interface BoxRenderable {
   absoluteY?: number;
   absoluteBounds?: { x: number; y: number; width: number; height: number };
   getBoundingClientRect?: () => { x: number; y: number; width: number; height: number };
+  /**
+   * Desktop only: draws the box at `frame` by restyling its own element, with
+   * no render, until it is called with null. The offset rides the compositor,
+   * so it costs no layout or repaint.
+   */
+  setLiveFrame?: (frame: LiveBoxFrame | null) => void;
   [key: string]: unknown;
 }
 
@@ -461,6 +473,20 @@ export interface HostPopoverProps {
   trigger: ReactNode;
   children: ReactNode;
   anchorPoint?: { x: number; y: number } | null;
+  /**
+   * Opens beside this element instead of the trigger, such as a name the
+   * pointer is on: below it with the left edges aligned, above it when there
+   * is no room below, and kept inside the boundary. A Box ref is one. Read
+   * each time the popover places itself, so it follows the element when the
+   * page scrolls.
+   */
+  anchor?: BoxRenderable | null;
+  /** `pane` also keeps the popover inside the pane it opens from. Default `viewport`. */
+  boundary?: "viewport" | "pane";
+  /** The pointer came onto the popover, e.g. to keep a hover card open while it is used. */
+  onPointerEnter?: () => void;
+  /** The pointer left the popover. */
+  onPointerLeave?: () => void;
   placement?: "bottom-start" | "bottom-end";
   minWidth?: number | string;
   maxWidth?: number | string;

package/src/ui/index.tsx

@@ -1,6 +1,7 @@
 import { createElement, forwardRef, useCallback, useRef, type ComponentProps } from "react";
 import { useForwardedScrollBoxRef, useRegisterPaneScrollBox } from "../state/pane-scroll-registry";
 import { useUiHost, type UiHost } from "./host";
+import { scrollBoxScrollsVertically } from "./scroll-box-axis";
 import { useRemoteUiNode } from "../remote/semantic-tree";
 import { assignRef } from "../react/assign-ref";
 import {
@@ -48,6 +49,7 @@ export type {
   MediaSurfaceHandle,
   MediaSurfaceProps,
   InputRenderable,
+  LiveBoxFrame,
   NativeCursorState,
   NativeRendererHost,
   NativePostProcessFn,
@@ -128,8 +130,11 @@ export const ScrollBox = forwardRef<any, ComponentProps<UiHost["ScrollBox"]>>((p
   const { ScrollBox: HostScrollBox } = useUiHost();
   const localRef = useForwardedScrollBoxRef<any>(ref);
   const rawProps = props as Record<string, unknown>;
+  // The same rule the hosts scroll by: a ScrollBox that omits scrollY scrolls,
+  // so it is a scrollbox to the remote tree and to the pane scroll keys.
+  const scrollsVertically = scrollBoxScrollsVertically(props);
   const remoteNodeId = useRemoteUiNode(
-    props.scrollY === true
+    scrollsVertically
       ? {
         role: remotePropRole(rawProps, "scrollbox"),
         label: remotePropLabel(rawProps),
@@ -150,7 +155,7 @@ export const ScrollBox = forwardRef<any, ComponentProps<UiHost["ScrollBox"]>>((p
           ...remoteMetadataFromProps(rawProps),
           width: rawProps.width,
           height: rawProps.height,
-          scrollY: props.scrollY === true,
+          scrollY: true,
           scrollTop: localRef.current?.scrollTop,
           viewportHeight: localRef.current?.viewport?.height,
         },
@@ -158,7 +163,7 @@ export const ScrollBox = forwardRef<any, ComponentProps<UiHost["ScrollBox"]>>((p
       : null,
   );
   useRegisterPaneScrollBox(localRef, {
-    enabled: props.scrollY === true,
+    enabled: scrollsVertically,
     onScrollActivity: typeof props.onMouseScroll === "function"
       ? props.onMouseScroll as (event: { scroll: { direction: "up" | "down"; delta: number } }) => void
       : undefined,

package/src/ui/scroll-box-axis.ts

@@ -0,0 +1,26 @@
+/**
+ * Which axes a ScrollBox scrolls on, decided from its props. The terminal and
+ * DOM hosts and the pane keyboard scroll registration all read it here, so a
+ * ScrollBox that omits `scrollY` behaves the same everywhere: it scrolls
+ * vertically, with the wheel and with the arrows, PageUp, PageDown, Home and
+ * End. Pass `scrollY={false}` to turn that off.
+ */
+interface ScrollBoxAxisProps {
+  scrollX?: unknown;
+  scrollY?: unknown;
+  height?: unknown;
+}
+
+/**
+ * A one-row strip that only scrolls sideways: tab bars, table headers and
+ * chart legends. It is not a vertical scroller even though `scrollY` is
+ * omitted.
+ */
+export function isHeaderStripScrollBox(props: ScrollBoxAxisProps): boolean {
+  return props.scrollX === true && props.scrollY !== true && props.height === 1;
+}
+
+/** Whether the ScrollBox scrolls vertically: unless `scrollY` is false, and never a header strip. */
+export function scrollBoxScrollsVertically(props: ScrollBoxAxisProps): boolean {
+  return props.scrollY !== false && !isHeaderStripScrollBox(props);
+}

package/src/updater/index.ts

@@ -1,7 +1,7 @@
 import { compareSemver } from "../utils/semver";
 import { GITHUB_LATEST_RELEASE_API_URL } from "./github-releases";
 
-function getRuntimeProcess(): Pick<NodeJS.Process, "platform" | "arch" | "argv" | "execPath"> | null {
+function getRuntimeProcess(): Pick<NodeJS.Process, "platform" | "arch" | "argv" | "execPath" | "getBuiltinModule"> | null {
   return (globalThis as { process?: NodeJS.Process }).process ?? null;
 }
 
@@ -414,17 +414,15 @@ export async function performUpdate(
   let unlinkUpdatePath: ((path: string) => void) | null = null;
 
   try {
-    const fsModulePath = "fs";
-    const zlibModulePath = "zlib";
-    const cryptoModulePath = "crypto";
-    const {
-      renameSync,
-      unlinkSync,
-      chmodSync,
-    } = await import(fsModulePath) as typeof import("fs");
+    // Not import(): Bun folds even a specifier held in a variable and bundles
+    // browser polyfills for all three into the web and desktop view builds,
+    // which never reach this path. Self-update only runs in the compiled
+    // terminal binary, where the process is always there.
+    const runtime = getRuntimeProcess()!;
+    const { renameSync, unlinkSync, chmodSync } = runtime.getBuiltinModule("fs");
     unlinkUpdatePath = unlinkSync;
-    const { gunzipSync } = await import(zlibModulePath) as typeof import("zlib");
-    const { createHash } = await import(cryptoModulePath) as typeof import("crypto");
+    const { gunzipSync } = runtime.getBuiltinModule("zlib");
+    const { createHash } = runtime.getBuiltinModule("crypto");
 
     onProgress({ phase: "downloading", percent: 0 });
 

package/src/utils/async-deadline.ts

@@ -58,3 +58,24 @@ export function abortable<T>(promise: Promise<T>, signal: AbortSignal | undefine
     promise.then(resolve, reject).finally(() => signal.removeEventListener("abort", abort));
   });
 }
+
+/**
+ * Aborts when the caller's signal does or after `timeoutMs`, whichever comes
+ * first, with that signal's reason. Wired by hand because AbortSignal.any is
+ * missing from the older system WebViews the desktop app runs in.
+ */
+export function signalWithTimeout(signal: AbortSignal | undefined, timeoutMs: number): AbortSignal {
+  const timeout = AbortSignal.timeout(timeoutMs);
+  if (!signal) return timeout;
+  if (signal.aborted) return signal;
+  const controller = new AbortController();
+  const fromCaller = () => controller.abort(signal.reason);
+  const fromTimeout = () => controller.abort(timeout.reason);
+  signal.addEventListener("abort", fromCaller, { once: true });
+  timeout.addEventListener("abort", fromTimeout, { once: true });
+  controller.signal.addEventListener("abort", () => {
+    signal.removeEventListener("abort", fromCaller);
+    timeout.removeEventListener("abort", fromTimeout);
+  }, { once: true });
+  return controller.signal;
+}

package/src/utils/cli-output.ts

@@ -8,6 +8,8 @@ export interface CliTableColumn {
   maxWidth?: number;
   /** Dropped, rightmost first, before other columns are shortened to fit a terminal. */
   optional?: boolean;
+  /** Among optional columns, a higher priority is dropped sooner; equal ones go rightmost first. */
+  dropPriority?: number;
   /** False keeps the column whole when fitting, for identifiers a user types into the next command. */
   shrink?: boolean;
 }
@@ -301,7 +303,9 @@ export function renderTable(columns: CliTableColumn[], rows: string[][], options
   let truncate = false;
   if (available != null && tableWidth(shown.map((entry) => entry.width)) > available) {
     while (tableWidth(shown.map((entry) => entry.width)) > available) {
-      const dropped = shown.findLast((entry) => entry.column.optional);
+      const dropped = shown.reduce<(typeof shown)[number] | undefined>((pick, entry) => (
+        entry.column.optional && (!pick || (entry.column.dropPriority ?? 0) >= (pick.column.dropPriority ?? 0)) ? entry : pick
+      ), undefined);
       if (!dropped) break;
       shown = shown.filter((entry) => entry !== dropped);
     }

package/src/utils/crypto-pair.ts

@@ -0,0 +1,41 @@
+import { canonicalExchange, parsePublicTickerKey } from "./exchanges";
+
+// The fiat codes a pair against USD is read as FX for, never as a coin. The
+// list Cloud reads: it serves these pairs by the same rule, so a copy judged
+// here as current or stale agrees with the answer it was fetched from.
+const FIAT_CURRENCY_CODES = new Set([
+  "USD", "EUR", "JPY", "GBP", "CHF", "CAD", "AUD", "NZD", "CNY", "CNH", "HKD", "SGD", "SEK", "NOK", "DKK",
+  "ZAR", "INR", "BRL", "MXN", "KRW", "TWD", "ILS", "PLN", "TRY", "CZK", "HUF",
+]);
+
+const USD_COIN_PAIR = /^([A-Z0-9]+)[-/]USD$/;
+
+/** A coin quoted in dollars (BTC-USD, ETH/USD). EUR-USD is spot FX, not a coin. */
+function isUsdCoinPair(symbol: string): boolean {
+  const base = USD_COIN_PAIR.exec(symbol.trim().toUpperCase())?.[1];
+  return base !== undefined && !FIAT_CURRENCY_CODES.has(base);
+}
+
+/**
+ * A series that trades around the clock: anything on the crypto venue (CCC), or
+ * a coin quoted in dollars whether or not the caller named that venue. A bare
+ * BTC-USD is the coin, not a US listing; a bare BTC (no quote) is a US fund.
+ */
+export function isRoundTheClockCoin(symbol?: string, exchange?: string): boolean {
+  const parsed = symbol ? parsePublicTickerKey(symbol) : null;
+  if (canonicalExchange(parsed?.exchange ?? exchange) === "CCC" || canonicalExchange(exchange) === "CCC") return true;
+  return !!parsed && isUsdCoinPair(parsed.symbol);
+}
+
+// A base-quote pair such as BTC-USD or SOL-EUR. Equities with a share-class dash (BRK-B) and
+// currency pairs (EURUSD=X) do not match.
+const CRYPTO_PAIR = /^[A-Z0-9]{1,15}-(?:USD|EUR|GBP|USDT|USDC|BTC)$/;
+
+/**
+ * Wider than isUsdCoinPair, for the hint under a pair that will not load: it
+ * also takes pairs quoted in other currencies and in coins, and does not tell
+ * a fiat base from a coin.
+ */
+export function isCryptoPairSymbol(symbol: string): boolean {
+  return CRYPTO_PAIR.test(symbol);
+}

package/src/utils/currency-units.ts

@@ -6,6 +6,25 @@ const SUB_UNIT_CURRENCIES: Record<string, { currency: string; divisor: number }>
   ZAc: { currency: "ZAR", divisor: 100 },
 };
 
+const SUB_UNIT_NAMES: Record<string, string> = {
+  GBp: "pence",
+  GBX: "pence",
+  ILA: "agorot",
+  ZAc: "cents",
+};
+
+/**
+ * A currency code as a reader should see it; a sub-unit says which one,
+ * "GBp (pence)", and with `ofMajor` what it divides: "ILA (agorot, 1/100 ILS)".
+ */
+export function currencyUnitLabel(code?: string | null, { ofMajor = false }: { ofMajor?: boolean } = {}): string {
+  const raw = (code ?? "").trim();
+  const unit = SUB_UNIT_NAMES[raw];
+  const major = SUB_UNIT_CURRENCIES[raw];
+  if (!unit) return raw;
+  return ofMajor && major ? `${raw} (${unit}, 1/${major.divisor} ${major.currency})` : `${raw} (${unit})`;
+}
+
 const LIKELY_UNIT_MISMATCH_RATIOS: Record<string, number[]> = {
   BHD: [1000],
   GBP: [100],

package/src/utils/depositary-receipt.ts

@@ -0,0 +1,70 @@
+import type { Fundamentals, Quote, ShareBasis } from "../types/financials";
+
+// A word of its own, so a company called "ADS-TEC" is not one.
+const DEPOSITARY_NAME = /(?:^|\s)(?:ADRs?|ADSs?|American depositary (?:receipts?|shares?))(?=$|[\s,)])/i;
+const DEPOSITARY_TYPES = new Set(["ADR", "ADS", "DEPOSITARYRECEIPT"]);
+/** A profile that opens by naming the security: "Toyota Motor Corporation Sponsored ADR is ...". */
+const DEPOSITARY_SUBJECT = /^.{0,160}?\s(?:ADRs?|ADSs?|American depositary (?:receipts?|shares?)) is\s/i;
+
+interface ListingEvidence {
+  /** Gloom Cloud's verdict; absent when it has no evidence either way. */
+  isDepositaryReceipt?: boolean | null;
+  instrumentType?: string | null;
+  name?: string | null;
+  currency?: string | null;
+  description?: string | null;
+}
+
+/**
+ * Whether a listing is a depositary receipt. Gloom Cloud's flag decides when
+ * it is set. Without it (an older service, or a listing it has no evidence
+ * for) this reads the instrument type, the name, and the security name a
+ * profile description opens with. A listing in another currency is the
+ * ordinary line even when its profile mentions the receipts.
+ */
+export function isDepositaryReceipt(input: ListingEvidence): boolean {
+  if (typeof input.isDepositaryReceipt === "boolean") return input.isDepositaryReceipt;
+  const currency = input.currency?.trim().toUpperCase();
+  if (currency && currency !== "USD") return false;
+  if (DEPOSITARY_TYPES.has((input.instrumentType ?? "").replace(/[\s_-]/g, "").toUpperCase())) return true;
+  if (input.name && DEPOSITARY_NAME.test(input.name)) return true;
+  return DEPOSITARY_SUBJECT.test(input.description?.trim() ?? "");
+}
+
+/**
+ * Whether a record's share counts are in receipts. Gloom Cloud says so with
+ * `shareBasis`; without it, a receipt's counts are read as receipts, as its
+ * market cap is.
+ */
+function sharesInReceipts(input: ListingEvidence & { shareBasis?: ShareBasis | null }): boolean {
+  if (input.shareBasis === "depositary_receipt") return true;
+  if (input.shareBasis === "ordinary") return false;
+  return isDepositaryReceipt(input);
+}
+
+/**
+ * Whether a listing's shares outstanding are counted in receipts: the
+ * fundamentals' basis, else the listing's flag (the fundamentals' or the
+ * quote's), else what the quote and profile say.
+ */
+export function sharesOutstandingInReceipts(
+  quote: Pick<Quote, "isDepositaryReceipt" | "instrumentType" | "name" | "currency"> | null | undefined,
+  fundamentals: Pick<Fundamentals, "isDepositaryReceipt" | "shareBasis"> | null | undefined,
+  description?: string | null,
+): boolean {
+  return sharesInReceipts({
+    instrumentType: quote?.instrumentType,
+    name: quote?.name,
+    currency: quote?.currency,
+    description,
+    isDepositaryReceipt: fundamentals?.isDepositaryReceipt ?? quote?.isDepositaryReceipt,
+    shareBasis: fundamentals?.shareBasis,
+  });
+}
+
+/** "1 ADR = 2 ordinary shares", or null without a usable ratio. */
+export function adrRatioText(ratio: number | null | undefined): string | null {
+  if (typeof ratio !== "number" || !Number.isFinite(ratio) || ratio <= 0) return null;
+  const count = Number.isInteger(ratio) ? String(ratio) : String(Number(ratio.toPrecision(6)));
+  return `1 ADR = ${count} ordinary share${ratio === 1 ? "" : "s"}`;
+}

package/src/utils/display-number.ts

@@ -0,0 +1,63 @@
+/**
+ * Reading back a number a table or report drew ("+1.25%", "1.20B", "$1,234.50"),
+ * so a CSV export can write the number a spreadsheet uses and name the unit
+ * in its header instead of in every cell.
+ */
+
+/** What a cell draws for a missing value: a dash, a run of dashes, or the loading ellipsis. */
+export const DISPLAY_PLACEHOLDER = /^(?:[-\u2013\u2014]{1,3}|\u2026|\.\.\.)$/;
+
+/**
+ * A number as a table draws it: sign, currency symbol, thousands commas,
+ * decimals, a compact scale (12.3k, 1.20B) and a unit (%, x, bp, USD, or c
+ * for the cents grain futures quote in).
+ */
+const DISPLAY_NUMBER = /^([+-]?)([A-Z]{0,3}[$\u20ac\u00a3\u00a5\u20b9\u20a9\u20bd\u20ba\u20aa\u20ab\u0e3f])?(?=\.?\d)(\d{1,3}(?:,\d{3})+|\d*)(?:\.(\d+))?([kKMBT])?(%|x|c|\u00a2| ?bps?| [A-Z]{3})?$/;
+
+const SCALE_DIGITS: Record<string, number> = { k: 3, K: 3, M: 6, B: 9, T: 12 };
+
+export interface DisplayNumber {
+  /** Plain decimal text: no sign for positives, no commas, no scale letter. */
+  number: string;
+  /** What the column header has to name once the cells are bare numbers. */
+  unit: string;
+  /** The place value of the last digit drawn: 0.01 for "1.25%", 10,000,000 for "1.20B". */
+  step: number;
+}
+
+export const BLANK_DISPLAY = "blank";
+
+/** Moves the decimal point right without going through a float, so 1.23B is exactly 1230000000. */
+function scaleDecimal(integer: string, fraction: string, digits: number): string {
+  const whole = `${integer}${fraction.padEnd(digits, "0").slice(0, digits)}`.replace(/^0+(?=\d)/, "") || "0";
+  const rest = fraction.slice(digits);
+  return rest ? `${whole}.${rest}` : whole;
+}
+
+export function parseDisplayNumber(text: string): DisplayNumber | typeof BLANK_DISPLAY | null {
+  // A direction arrow beside a signed move repeats the sign.
+  const trimmed = text.trim().replace(/\u2212/g, "-").replace(/\s*[\u2191\u2193]$/, "");
+  if (!trimmed || DISPLAY_PLACEHOLDER.test(trimmed)) return BLANK_DISPLAY;
+  const match = DISPLAY_NUMBER.exec(trimmed);
+  if (!match) return null;
+  const [, sign, currency = "", grouped, fraction = "", scale, unitText = ""] = match;
+  const integer = grouped!.replace(/,/g, "") || "0";
+  const digits = scale ? SCALE_DIGITS[scale]! : 0;
+  const magnitude = digits ? scaleDecimal(integer, fraction, digits) : fraction ? `${integer}.${fraction}` : integer;
+  const unit = unitText.trim().replace(/^bps$/, "bp").replace(/^\u00a2$/, "c");
+  return {
+    number: `${sign === "-" ? "-" : ""}${magnitude}`,
+    unit: [currency, unit].filter(Boolean).join(" "),
+    step: 10 ** (digits - fraction.length),
+  };
+}
+
+/** Adds the unit the cells dropped, unless the label already names it. */
+export function labelWithUnit(label: string, unit: string): string {
+  if (!unit) return label;
+  // A word unit has to stand alone: "Max" does not name x.
+  const named = unit === "bp" ? /\bbps?\b/i.test(label)
+    : /^[A-Za-z]+$/.test(unit) ? new RegExp(`\\b${unit}\\b`, "i").test(label)
+      : label.includes(unit);
+  return named ? label : `${label} (${unit})`;
+}