gloomberb 0.16.2 → 0.16.4

package/src/types/plugin.ts

@@ -1,6 +1,6 @@
 import type { ReactNode } from "react";
 import type { AppTickerRepositoryPort } from "../core/app-service-ports";
-import type { HeadlessPaneDefinition, HeadlessPaneFreshness } from "./headless";
+import type { HeadlessPaneDefinition, HeadlessPaneFreshness, HeadlessPaneOptionDef } from "./headless";
 
 export type {
   HeadlessBundleResult,
@@ -132,6 +132,18 @@ export interface PaneDef {
    * shows would be wrong: local data, a calculator, filed records.
    */
   reportFreshness?: Pick<HeadlessPaneFreshness, "source" | "status" | "basis">;
+  /**
+   * Options a rendered-view report takes (`fn FXC --currencies USD,ZAR`):
+   * each sets the pane setting of its key, is checked by its `normalize`, and
+   * is listed with its example by `gloomberb catalog`.
+   */
+  reportOptions?: readonly PaneReportOptionDef[];
+  /**
+   * Lines a rendered-view report prints above its table, from the settings it
+   * ran with: what the default view leaves out and how to see more. `--json`
+   * carries them in `data.metadata.notices`.
+   */
+  reportNotices?(settings: Readonly<Record<string, unknown>>): string[];
   /** Add an Excel-compatible CSV action for the pane's single active DataTable. */
   tableExport?: true;
   settings?: PaneSettingsDef | ((context: PaneSettingsContext) => PaneSettingsDef | null);
@@ -144,6 +156,20 @@ export interface PaneDef {
   quickSettings?: readonly PaneQuickSettingDef[];
 }
 
+/**
+ * An option of a rendered-view report, which sets the pane setting of its key,
+ * or of `settingKey` when the flag reads better than the setting's name
+ * (`--columns` for `optionColumnIds`).
+ */
+export interface PaneReportOptionDef extends Omit<HeadlessPaneOptionDef, "pluginState"> {
+  /** The value's name in the catalog's flag, `--currencies <codes>`; the type when absent. */
+  placeholder?: string;
+  /** The option in use as typed after the function, such as `--currencies USD,ZAR,NGN`; the catalog shows it as an example. */
+  example?: string;
+  /** Checks a typed value and returns it as the pane reads it; throws an Error that names what is wrong. */
+  normalize?(value: string): string;
+}
+
 export interface PaneQuickSettingDef {
   type: "toggle";
   key: string;
@@ -389,6 +415,10 @@ export interface CommandResultDef {
   label: string;
   detail?: string;
   category?: string;
+  /** Short tag drawn left of the label, as on a search provider's row. Six characters at most. */
+  badge?: string;
+  /** Drawn muted after the label, e.g. a person's full name after their @username. */
+  name?: string;
   right?: string;
   keywords?: string[];
   current?: boolean;
@@ -414,6 +444,8 @@ export interface CommandBarResultDef {
   category?: string;
   /** Short tag drawn left of the label, e.g. a document type. Six characters at most. */
   badge?: string;
+  /** Drawn muted after the label, e.g. a person's full name after their @username. */
+  name?: string;
   right?: string;
   keywords?: string[];
   disabled?: boolean;
@@ -431,15 +463,29 @@ export interface CommandBarSearchProvider {
   category: string;
   /** Sort position of the section. Higher sinks. Navigation sections are negative; use a positive value to sit below them. */
   priority?: number;
-  /** Skip provide() below this length. Default 3. */
+  /** Skip the provider below this length. Default 3. */
   minQueryLength?: number;
-  /** Default 300. */
+  /** Default 300. Ignored by `match`. */
   debounceMs?: number;
+  /**
+   * Codes (`CHAT`) after which the provider is still asked, typed alone or
+   * with text after them, with the whole query. Every other provider stays
+   * quiet once a code claims the text.
+   */
+  shortcuts?: readonly string[];
   provide(
     query: string,
     context: CommandBarSearchContext,
     signal: AbortSignal,
   ): Promise<CommandBarResultDef[]>;
+  /**
+   * Rows from what the app already holds in memory. When set, the bar calls
+   * this instead of `provide`, as it renders and on every keystroke, so it
+   * must be cheap: no request, no waiting. Its rows are ranked with the bar's
+   * own matches as they are typed and sit under Suggested in the empty bar.
+   * Keep `provide` answering the same rows for older versions of the app.
+   */
+  match?(query: string, context: CommandBarSearchContext): CommandBarResultDef[];
 }
 
 interface CliHelpColumn {

package/src/ui/host.tsx

@@ -108,6 +108,16 @@ export interface SyntaxStyleLike {
   }): number;
 }
 
+/** Where a drag has a box this frame, in cells. */
+export interface LiveBoxFrame {
+  /** Offset from where the box is laid out, carried on the box's own layer. */
+  dx?: number;
+  dy?: number;
+  /** Size in place of the laid-out one: the box and what stretches inside it lay out again, nothing renders. */
+  width?: number;
+  height?: number;
+}
+
 export interface BoxRenderable {
   x?: number;
   y?: number;
@@ -117,6 +127,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; a size lays out the box's own subtree.
+   */
+  setLiveFrame?: (frame: LiveBoxFrame | null) => void;
   [key: string]: unknown;
 }
 

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,
@@ -191,6 +196,8 @@ export const Input = forwardRef<any, ComponentProps<UiHost["Input"]>>((props, re
     },
     metadata: {
       ...remoteMetadataFromProps(rawProps),
+      // Lets a reader that must not see typed passwords (the Cloud relay) recognize one.
+      ...(rawProps.type === "password" ? { inputType: "password" } : {}),
       value: rawProps.value,
       placeholder: rawProps.placeholder,
       focused: rawProps.focused,

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/utils/cli-output.ts

@@ -32,6 +32,7 @@ const MIN_SHRUNK_COLUMN_WIDTH = 8;
 // Text columns first shrink right to left down to this width, then all shrink together.
 const SOFT_MIN_COLUMN_WIDTH = 20;
 let colorEnabledOverride: boolean | null = null;
+let widthOverride: number | null = null;
 
 function colorEnabled(): boolean {
   if (colorEnabledOverride != null) return colorEnabledOverride;
@@ -56,8 +57,14 @@ export function visibleLength(text: string): number {
   return typeof Bun !== "undefined" ? Bun.stringWidth(text) : stripAnsi(text).length;
 }
 
-/** Columns of the terminal stdout writes to, or null when output is piped or redirected. */
+/** `--width n`: tables, help and wrapped text fit n columns, whether or not stdout is a terminal. */
+export function setCliWidthOverride(value: number | null): void {
+  widthOverride = value;
+}
+
+/** Columns the output is fitted to: `--width`, else the terminal's, or null when output is piped or redirected. */
 export function cliTerminalWidth(): number | null {
+  if (widthOverride != null) return widthOverride;
   if (!process.stdout.isTTY) return null;
   const columns = process.stdout.columns;
   return typeof columns === "number" && columns > 0 ? columns : null;
@@ -139,6 +146,12 @@ export function wrapText(text: string, width: number): string[] {
   return lines;
 }
 
+/** One line of text under a table, wrapped to the width the table was fitted to; whole when output is not fitted. */
+export function wrapToTerminal(text: string): string {
+  const width = cliTerminalWidth();
+  return width == null ? text : wrapText(text, width).join("\n");
+}
+
 export const cliStyles = {
   bold: (text: string) => applyAnsi(text, "1"),
   dim: (text: string) => applyAnsi(text, "2"),

package/src/utils/currency-units.ts

@@ -13,11 +13,16 @@ const SUB_UNIT_NAMES: Record<string, string> = {
   ZAc: "cents",
 };
 
-/** A currency code as a reader should see it; a sub-unit says which one: "GBp (pence)". */
-export function currencyUnitLabel(code?: string | null): string {
+/**
+ * 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];
-  return unit ? `${raw} (${unit})` : 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[]> = {

package/src/utils/depositary-receipt.ts

@@ -1,26 +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;
 
-/**
- * Whether a US listing is a depositary receipt, as far as its data says. A
- * quote carries no ADR flag or ratio, so this reads the instrument type, the
- * name, and the security name a profile description opens with. Its share
- * count and market cap are then counted in receipts, not ordinary shares. A
- * listing in another currency is the ordinary line even when its profile
- * mentions the receipts.
- */
-export function isDepositaryReceipt(input: {
+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;
-}): boolean {
+}
+
+/**
+ * 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})`;
+}

package/src/utils/exchanges.ts

@@ -133,6 +133,13 @@ export const CANONICAL_EXCHANGE_ALIASES: Record<string, string> = {
   XJSE: "JSE",
   TLV: "TASE",
   XTAE: "TASE",
+  TADAWUL: "TADAWUL",
+  XSAU: "TADAWUL",
+  QE: "QE",
+  QSE: "QE",
+  DSMD: "QE",
+  DFM: "DFM",
+  XDFM: "DFM",
   CCC: "CCC",
 };
 
@@ -222,6 +229,9 @@ export const EXCHANGE_TIME_ZONES: Record<string, string> = {
   BYMA: "America/Argentina/Buenos_Aires",
   JSE: "Africa/Johannesburg",
   TASE: "Asia/Jerusalem",
+  TADAWUL: "Asia/Riyadh",
+  QE: "Asia/Qatar",
+  DFM: "Asia/Dubai",
   CCC: "UTC",
 };
 
@@ -275,6 +285,9 @@ const EXCHANGE_NAMES: Record<string, string> = {
   BYMA: "Bolsas y Mercados Argentinos",
   JSE: "Johannesburg Stock Exchange",
   TASE: "Tel Aviv Stock Exchange",
+  TADAWUL: "Saudi Exchange",
+  QE: "Qatar Stock Exchange",
+  DFM: "Dubai Financial Market",
 };
 
 const KNOWN_EXCHANGE_CODES: ReadonlySet<string> = new Set([

package/src/utils/format.ts

@@ -8,7 +8,8 @@ function getCurrencyFormatter(currency: string, maximumFractionDigits = 2): Intl
     formatter = new Intl.NumberFormat("en-US", {
       style: "currency",
       currency,
-      minimumFractionDigits: 2,
+      // Whole units (0) drop the cents rather than throw.
+      minimumFractionDigits: Math.min(2, maximumFractionDigits),
       maximumFractionDigits,
     });
     currencyFormatters.set(key, formatter);

package/src/utils/fundamentals.ts

@@ -1,4 +1,4 @@
-import type { Fundamentals } from "../types/financials";
+import type { Fundamentals, TickerFinancials } from "../types/financials";
 
 export const RETRACTABLE_VALUATION_FIELDS = ["enterpriseValue", "enterpriseToRevenue"] as const;
 
@@ -13,3 +13,19 @@ export function redactUnavailableFundamentals(value: Fundamentals | undefined):
   for (const field of unavailableFields) delete result[field];
   return result;
 }
+
+/** A source's enterprise value, or undefined when it has none: banks and insurers come back as 0, which is a gap, not a value. */
+export function reportedEnterpriseValue(fundamentals: Pick<Fundamentals, "enterpriseValue"> | undefined): number | undefined {
+  const value = fundamentals?.enterpriseValue;
+  return typeof value === "number" && Number.isFinite(value) && value !== 0 ? value : undefined;
+}
+
+/**
+ * The currency of the trailing EPS, revenue, income and cash flows: the one the fundamentals declare, else the
+ * one the statements report in. Never the quote's, which a depositary receipt can differ from (USD quote, TWD books).
+ */
+export function fundamentalsCurrency(
+  financials: Pick<TickerFinancials, "fundamentals" | "financialCurrency"> | null | undefined,
+): string | undefined {
+  return financials?.fundamentals?.financialCurrency?.trim() || financials?.financialCurrency?.trim() || undefined;
+}

package/src/utils/fx-market-hours.ts

@@ -1,4 +1,14 @@
+import { canonicalExchange, parsePublicTickerKey } from "./exchanges";
+import { zonedDateTimeParts, zonedWallClockToUtcMs } from "./zoned-date-time";
+
 const HOUR_MS = 60 * 60_000;
+const DAY_MS = 24 * HOUR_MS;
+const NEW_YORK = "America/New_York";
+
+/** A spot currency pair: `=X` listing syntax (EURUSD=X, JPY=X) or the CCY venue. */
+export function isCurrencyPairListing(symbol: string | undefined, exchange: string | undefined): boolean {
+  return canonicalExchange(exchange) === "CCY" || (!!symbol && parsePublicTickerKey(symbol).symbol.endsWith("=X"));
+}
 
 const newYorkClock = new Intl.DateTimeFormat("en-US", {
   timeZone: "America/New_York",
@@ -19,6 +29,30 @@ export function isFxMarketOpen(time: number): boolean {
   return true;
 }
 
+/** The latest close of the FX week, Friday 17:00 New York, at or before `time`. */
+export function latestFxWeekClose(time: number): number | null {
+  if (!Number.isFinite(time)) return null;
+  const { year, month, day } = zonedDateTimeParts(time, NEW_YORK);
+  const today = Date.UTC(year, month - 1, day);
+  for (let offset = 0; offset <= 7; offset += 1) {
+    const date = new Date(today - offset * DAY_MS);
+    if (date.getUTCDay() !== 5) continue;
+    const close = zonedWallClockToUtcMs(NEW_YORK, date.getUTCFullYear(), date.getUTCMonth() + 1, date.getUTCDate(), 17, 0, 0);
+    if (close <= time) return close;
+  }
+  return null;
+}
+
+/**
+ * When the closure the market is in began (Friday 17:00 New York time); null
+ * while it trades. That is `latestFxWeekClose` for every moment the week is
+ * shut, since a closure never lasts to the next Friday, daylight saving weeks
+ * included.
+ */
+export function currentFxClosureStart(time: number): number | null {
+  return isFxMarketOpen(time) ? null : latestFxWeekClose(time);
+}
+
 /**
  * When an FX observation has aged `windowMs`, counting only time the market
  * is open. Friday's last print stays current over the weekend, while a rate

package/src/utils/option-expiry.ts

@@ -0,0 +1,126 @@
+/**
+ * Option expiries as people type and read them. A chain stamps each expiry as
+ * Unix seconds at that calendar date's UTC midnight, so a date and its stamp
+ * convert both ways, and two stamps on the same UTC date are the same expiry.
+ */
+
+// 9999-12-31 in Unix seconds; a longer number is milliseconds or a typo.
+const MAX_UNIX_SECONDS = 253_402_300_799;
+const ISO_DATE = /^(\d{4})-(\d{2})-(\d{2})$/;
+const UNIX_SECONDS = /^\d{1,12}$/;
+const DAY_MS = 86_400_000;
+
+/** How `--expiration` is written, for usage lines and errors. */
+export const OPTION_EXPIRATION_FORMAT = "YYYY-MM-DD (2028-01-21) or Unix seconds (1832025600)";
+/** The value's name in a catalog flag, `--expiration <YYYY-MM-DD|unix>`. */
+export const OPTION_EXPIRATION_PLACEHOLDER = "YYYY-MM-DD|unix";
+
+/** The expiry's calendar date, `2028-01-21`; empty for a stamp that is not a time. */
+export function expiryIsoDate(seconds: number): string {
+  const date = new Date(seconds * 1000);
+  return Number.isNaN(date.getTime()) ? "" : date.toISOString().slice(0, 10);
+}
+
+/**
+ * `--expiration` as the Unix seconds a chain request takes: `2028-01-21` is that
+ * date at 00:00 UTC, a bare integer is already Unix seconds. Anything else,
+ * including a date the calendar does not have, is null.
+ */
+export function parseOptionExpiration(raw: string): number | null {
+  const text = raw.trim();
+  const date = ISO_DATE.exec(text);
+  if (date) {
+    const [year, month, day] = [Number(date[1]), Number(date[2]), Number(date[3])];
+    const at = new Date(Date.UTC(year, month - 1, day));
+    const real = at.getUTCFullYear() === year && at.getUTCMonth() === month - 1 && at.getUTCDate() === day;
+    return real && at.getTime() > 0 ? at.getTime() / 1000 : null;
+  }
+  if (!UNIX_SECONDS.test(text)) return null;
+  const seconds = Number(text);
+  return seconds > 0 && seconds <= MAX_UNIX_SECONDS ? seconds : null;
+}
+
+/**
+ * A pane function's typed expiry flag as the Unix seconds `parseOptionExpiration`
+ * reads; throws an Error naming both accepted forms.
+ */
+export function expirationOptionSeconds(value: string, flag = "expiration"): number {
+  const expiration = parseOptionExpiration(value);
+  if (expiration == null) throw new Error(`Invalid --${flag} "${value}". Use ${OPTION_EXPIRATION_FORMAT}.`);
+  return expiration;
+}
+
+/** A stored or typed expiry setting (seconds, or text `parseOptionExpiration` reads) as Unix seconds; null when it is neither. */
+export function readOptionExpiration(value: unknown): number | null {
+  if (typeof value === "number") return Number.isFinite(value) && value > 0 && value <= MAX_UNIX_SECONDS ? value : null;
+  return typeof value === "string" ? parseOptionExpiration(value) : null;
+}
+
+/** The listed stamp for the requested expiry's date, which may differ from the requested stamp in time of day. */
+export function findListedExpiry(requested: number, expirations: readonly number[]): number | undefined {
+  if (expirations.includes(requested)) return requested;
+  const date = expiryIsoDate(requested);
+  return date ? expirations.find((expiration) => expiryIsoDate(expiration) === date) : undefined;
+}
+
+/** Whole calendar days from the as-of date to the expiry, both read as UTC dates; negative once it has passed. */
+export function daysToExpiry(expiration: number, asOfMs: number): number {
+  const expiry = Date.parse(expiryIsoDate(expiration));
+  const asOf = Date.parse(new Date(asOfMs).toISOString().slice(0, 10));
+  return Math.round((expiry - asOf) / DAY_MS);
+}
+
+/** `469d` to expiry from the as-of date; `expired` once it has passed. */
+export function formatDaysToExpiry(expiration: number, asOfMs: number): string {
+  const days = daysToExpiry(expiration, asOfMs);
+  return days < 0 ? "expired" : `${days}d`;
+}
+
+const NEAREST_EXPIRIES = 4;
+
+/**
+ * The listed expiries nearest a requested date, in date order, so a typo or an
+ * unlisted LEAPS date points at the neighbours to pick. `listed` says the date
+ * itself is listed (its chain came back empty); `more` counts the rest.
+ */
+function expiryChoices(requested: number, expirations: readonly number[]) {
+  const { nearest, more, ...rest } = nearestListedExpiries(requested, expirations);
+  return { ...rest, choices: `${nearest.join(", ")}${more > 0 ? ` (+${more} more)` : ""}` };
+}
+
+/**
+ * Why a requested expiry is not in a catalogue, for a line that already names
+ * the date: `not listed; nearest: 2027-12-17, 2028-01-21, … (+20 more)`.
+ */
+export function unlistedExpiryText(requested: number, expirations: readonly number[]): string {
+  const { total, choices } = expiryChoices(requested, expirations);
+  return total === 0 ? "not listed; the chain lists no expiries" : `not listed; nearest: ${choices}`;
+}
+
+function nearestListedExpiries(
+  requested: number,
+  expirations: readonly number[],
+  count = NEAREST_EXPIRIES,
+): { date: string; listed: boolean; nearest: string[]; more: number; total: number } {
+  const date = expiryIsoDate(requested);
+  const dates = [...new Set(expirations.map(expiryIsoDate).filter(Boolean))].sort();
+  const others = dates.filter((listed) => listed !== date);
+  const distance = (listed: string) => Math.abs(Date.parse(listed) - Date.parse(date));
+  const nearest = [...others].sort((left, right) => distance(left) - distance(right) || left.localeCompare(right))
+    .slice(0, count).sort();
+  return { date, listed: dates.includes(date), nearest, more: others.length - nearest.length, total: dates.length };
+}
+
+/**
+ * Why an expiry has no contracts, naming the nearest listed ones:
+ * `no expiry 2028-01-22; available: 2027-12-17, 2028-01-21, … (+20 more)`.
+ * `subject` names the underlying where nothing else on screen does.
+ */
+export function missingExpiryText(requested: number, expirations: readonly number[], subject?: string): string {
+  const { date, listed, total, choices } = expiryChoices(requested, expirations);
+  const of = subject ? ` for ${subject}` : "";
+  if (total === 0) return `no expiry ${date}${of}; the chain lists no expiries`;
+  return listed
+    ? `no option contracts returned for${subject ? ` ${subject}` : ""} expiry ${date}; nearest others: ${choices}`
+    : `no expiry ${date}${of}; available: ${choices}`;
+}