gloomberb 0.16.3 → 0.16.4

package/src/tickers/search/ranking.ts

@@ -216,7 +216,12 @@ export function rankTickerSearchItems<T extends Pick<TickerSearchRankableItem, "
       const aliases = getItemSearchAliases(item);
       const aliasScore = (exactListingSymbol ? [...aliases, exactListingSymbol] : aliases)
         .reduce((best, alias) => Math.max(best, scoreSearchAlias(intent, alias)), 0);
-      const textScore = labelScore + detailScore + aliasScore
+      // Several words match on all of them, in any order, across the name, type,
+      // venue and the themes the row answers to; a theme alone ranks after a name.
+      const keywordScore = scoreAllWords(intent, [...(item.searchKeywords ?? [])]) > 0 ? KEYWORD_MATCH_SCORE : 0;
+      const wordsScore = labelScore + detailScore + aliasScore > 0 ? 0
+        : scoreAllWords(intent, [item.label, item.detail, item.right ?? "", ...(item.searchKeywords ?? [])]);
+      const textScore = labelScore + detailScore + aliasScore + Math.max(keywordScore, wordsScore)
         + (isQualifiedTickerQuery(query) && matchesQualifiedTicker(item, query) ? 100_000 : 0);
       const saved = isSavedSearchItem(item);
       const explicitIntentScore = scoreAssetPreference(intent, item.instrumentClass)
@@ -285,6 +290,13 @@ export function rankTickerSearchItems<T extends Pick<TickerSearchRankableItem, "
     const aSaved = isSavedSearchItem(a.item);
     const bSaved = isSavedSearchItem(b.item);
     if (aSaved !== bSaved) return aSaved ? -1 : 1;
+    // Rows that answer to the same typed name (GOOGL and GOOG for "Google")
+    // keep the order the server gave them rather than the shorter symbol first.
+    if (a.symbolMatchRank === 2) {
+      const aProviderRank = a.item.providerRank ?? Number.POSITIVE_INFINITY;
+      const bProviderRank = b.item.providerRank ?? Number.POSITIVE_INFINITY;
+      if (aProviderRank !== bProviderRank) return aProviderRank - bProviderRank;
+    }
     if (a.item.label.length !== b.item.label.length) return a.item.label.length - b.item.label.length;
     return a.index - b.index;
   };
@@ -487,6 +499,38 @@ function getItemSearchAliases(item: Pick<TickerSearchRankableItem, "label"> & Pa
   return aliases.length > 0 ? aliases : [item.label];
 }
 
+/** A row that answers only to a theme it was sent with (`searchKeywords`), below any name match. */
+const KEYWORD_MATCH_SCORE = 500;
+/** Every query word found somewhere in the row, in any order. */
+const ALL_WORDS_SCORE = 2_200;
+
+/**
+ * ALL_WORDS_SCORE when every word of the query (exchange and asset words
+ * aside) starts a word of some field: "miners copper" finds "Copper Miners
+ * ETF", "lithium" finds a row sent with the lithium theme. Zero otherwise.
+ */
+function scoreAllWords(intent: SearchQueryIntent, fields: readonly string[]): number {
+  const terms = intent.companyQuery.split(" ").filter(Boolean);
+  if (terms.length === 0) return 0;
+  const words = fields.flatMap((field) => normalizeSearchText(field).split(" ").filter(Boolean));
+  return terms.every((term) => words.some((word) => word.startsWith(term))) ? ALL_WORDS_SCORE : 0;
+}
+
+/**
+ * Whether a row is in an answer for a theme it was sent with, not for its
+ * name: the name lacks some of the query's words (Albemarle for "lithium",
+ * Southern Copper for "copper miners").
+ */
+export function answersOnlyByKeyword(
+  item: Pick<TickerSearchRankableItem, "label" | "detail"> & Partial<TickerSearchRankableItem>,
+  query: string,
+): boolean {
+  if (!item.searchKeywords?.length) return false;
+  const terms = analyzeSearchQuery(query).companyQuery.split(" ").filter(Boolean);
+  const words = [item.label, item.detail].flatMap((field) => normalizeSearchText(field).split(" ").filter(Boolean));
+  return terms.length > 0 && !terms.every((term) => words.some((word) => word.startsWith(term)));
+}
+
 function maxScoreForQueries(
   queries: string[],
   value: string,

package/src/tickers/search/types.ts

@@ -2,7 +2,7 @@ import type { BrokerContractRef, InstrumentSearchResult, TickerListingRef } from
 import type { TickerRecord } from "../../types/ticker";
 
 export type TickerSearchInstrumentClass = "equity" | "fund" | "derivative" | "other";
-type TickerSearchCategory = "Saved" | "Primary Listing" | "Other Listings" | "Funds & Derivatives";
+type TickerSearchCategory = "Saved" | "Primary Listing" | "Other Listings" | "Funds & Derivatives" | "Related";
 
 export interface TickerSearchRankableItem {
   id: string;
@@ -21,6 +21,8 @@ export interface TickerSearchRankableItem {
   providerRank?: number;
   popularity?: number;
   searchAliases?: string[];
+  /** Themes the row answers to that its name does not say (`InstrumentSearchResult.searchKeywords`). */
+  searchKeywords?: string[];
 }
 
 export interface TickerSearchCandidate extends TickerSearchRankableItem {

package/src/time-series/resolve.ts

@@ -80,6 +80,7 @@ import { getPricePointTimestamp, isPriceHistoryStaleForCurrentWindow } from "../
 import { latestSessionStart, latestTradingSessionOpen, listingTimeZone, priorSessionClose } from "../market-data/market/trading-sessions";
 import { futuresGenericCaption, futuresGenericListing, futuresGenericPriceBasis } from "../utils/futures-generic";
 import { isOhlcSeriesStyle } from "./spec";
+import { SERIES_COLORS } from "../theme/series-colors";
 import type {
   ChartResolutionResult,
   ChartSeriesSpec,
@@ -88,20 +89,6 @@ import type {
   TimeSeriesPoint,
 } from "./types";
 
-/** Colours for series told apart by name (compared tickers, markets). */
-export const SERIES_COLORS = [
-  "#4dabf7",
-  "#63e6be",
-  "#f6c85f",
-  "#b197fc",
-  "#ff8787",
-  "#ffa94d",
-  "#74c0fc",
-  "#e599f7",
-  "#8ce99a",
-  "#ffd43b",
-] as const;
-
 export interface ChartResolveSources {
   dataProvider: DataProvider | null;
   loadFredSeries: (request: FredSeriesRequest) => Promise<FredSeriesLoadResult>;

package/src/types/config.ts

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

package/src/types/headless.ts

@@ -51,6 +51,15 @@ export interface HeadlessPaneOptionDef {
     pluginId: string;
     key?: string;
   };
+  /** The value's name in the catalog's flag, `--expiration <YYYY-MM-DD|unix>`; the type when absent. */
+  placeholder?: string;
+  /** The option in use as typed after the function, such as `--expiration 2028-01-21`; the catalog shows it as an example. */
+  example?: string;
+  /**
+   * Checks a typed value and returns it as the pane reads it, in place of the
+   * type's own check; throws an Error that names what is wrong.
+   */
+  normalize?(value: string): string | number | boolean;
 }
 
 export interface HeadlessPaneLoadArgs {
@@ -90,6 +99,8 @@ export interface HeadlessPaneColumn {
   header: string;
   align?: "left" | "right" | "center";
   width?: number;
+  /** False keeps the column whole when the text table is fitted to a narrow width, so a time or an id is never cut. */
+  shrink?: boolean;
   description?: string;
   format?: (value: unknown, row: HeadlessPaneRow) => string;
 }

package/src/types/instrument.ts

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

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,10 +108,14 @@ export interface SyntaxStyleLike {
   }): number;
 }
 
-/** Where a drag has a box this frame: an offset in cells from where it is laid out. */
+/** Where a drag has a box this frame, in cells. */
 export interface LiveBoxFrame {
-  dx: number;
-  dy: number;
+  /** 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 {
@@ -126,7 +130,7 @@ export interface BoxRenderable {
   /**
    * 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.
+   * 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

@@ -196,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/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/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/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}`;
+}