gloomberb 0.17.2 → 0.17.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gloomberb",
-  "version": "0.17.2",
+  "version": "0.17.4",
   "packageManager": "bun@1.3.11",
   "description": "Market research and portfolio tracker for the terminal",
   "module": "src/public/index.ts",
@@ -86,6 +86,7 @@
     "check:pane-screenshot": "bun run scripts/pane-chrome/screenshot.ts",
     "check:pane-rest": "bun run scripts/pane-chrome/rest-diff.ts",
     "check:pane-layout": "bun run scripts/pane-chrome/layout-sweep.ts",
+    "audit:ui": "bun run scripts/pane-chrome/ui-audit.ts",
     "benchmark:pane-drag:compare": "bun run scripts/pane-chrome/frame-budget.ts",
     "test:global-upgrade": "bun run scripts/smoke-global-upgrade.ts",
     "release": "./scripts/release.sh"

package/src/api-client/chat.ts

@@ -154,16 +154,40 @@ export class CloudChatApi {
     );
   }
 
+  /**
+   * `seen`: the app showed them where the reader was looking (the open
+   * channel, a toast in the foreground), which also cancels the phone push
+   * waiting on them. A server that predates it ignores the field.
+   */
   async markNotificationsDelivered(
     notificationIds: string[],
+    options: { seen?: boolean } = {},
   ): Promise<{ delivered: number }> {
     return this.request<{ delivered: number }>(
       "/chat/notifications/delivered",
+      {
+        method: "POST",
+        body: JSON.stringify({ notificationIds, ...(options.seen ? { seen: true } : {}) }),
+      },
+    );
+  }
+
+  /**
+   * The notifications among these the reader has neither read nor been shown
+   * in front of them, on any device. Throws on a server without the route
+   * (404); the caller raises the alert then, as before.
+   */
+  async getUnseenNotificationIds(notificationIds: string[]): Promise<string[]> {
+    const answer = await this.request<{ notificationIds?: unknown }>(
+      "/chat/notifications/unseen",
       {
         method: "POST",
         body: JSON.stringify({ notificationIds }),
       },
     );
+    return Array.isArray(answer?.notificationIds)
+      ? answer.notificationIds.filter((id): id is string => typeof id === "string")
+      : notificationIds;
   }
 
   async openDirectChannel(target: {
@@ -327,6 +351,10 @@ export class CloudChatApi {
     return this.options.socket.subscribeChatNotifications(listener);
   }
 
+  subscribeChannelState(listener: (state: ChatChannelState) => void): () => void {
+    return this.options.socket.subscribeChatChannelState(listener);
+  }
+
   subscribePresence(listener: ChatPresenceListener): () => void {
     return this.options.socket.subscribeChatPresence(listener);
   }

package/src/api-client/errors.ts

@@ -75,12 +75,22 @@ export function parseApiErrorMessage(body: string): string {
       (value): value is string =>
         typeof value === "string" && value.trim().length > 0,
     );
-    return parts.join(" ") || body;
+    return parts.join(" ") || validationErrorText(parsed) || body;
   } catch {
     return htmlErrorTitle(body) ?? body;
   }
 }
 
+/**
+ * A request the API's schema refused comes back as the values it was sent
+ * (`{"type":"validation","on":"query","found":{...}}`), which is no message to
+ * show; it is said in words instead.
+ */
+function validationErrorText(parsed: Record<string, unknown>): string | null {
+  if (parsed.type !== "validation") return null;
+  return parsed.on === "query" ? "Gloom Cloud did not accept an option or filter value." : "Gloom Cloud did not accept the request.";
+}
+
 /** A JSON error body as an object, or undefined for any other body. */
 export function parseApiErrorDetails(body: string): Readonly<Record<string, unknown>> | undefined {
   try {

package/src/api-client/futures-curve.ts

@@ -30,6 +30,22 @@ export interface FuturesContractTermsPayload {
   inDelivery: boolean
   /** The newest exchange settlement confirmed for the contract, with its session. */
   settlement: { price: number; date: string } | null
+  /**
+   * For a continuous symbol (CL=F) or a front generic: the nearest contract
+   * still trading when the symbol has rolled past it to the most active one,
+   * with its last trade; null when it prices the nearest itself. Absent from
+   * servers that do not send it.
+   */
+  nearest?: FuturesNearestContract | null
+}
+
+/** The nearest contract still trading, which a continuous symbol has rolled past (CLX26 under CL=F on Dec). */
+interface FuturesNearestContract {
+  contract: string
+  contractSymbol: string
+  /** YYYY-MM */
+  deliveryMonth: string
+  lastTrade: string | null
 }
 
 /** Gloom Cloud futures prices retain provider denomination and explicit quote units. */

package/src/api-client/index.ts

@@ -12,7 +12,7 @@ import {
   parseCloudLayoutEntry,
   parseCloudLayoutList,
 } from "../layout-marketplace/cloud";
-import type { SyncSnapshot } from "../sync/types";
+import { SyncRevisionConflictError, type SyncSnapshot } from "../sync/types";
 import { withDeadline } from "../utils/async-deadline";
 import { CloudASKGApi } from "./askg";
 import { CloudAuthApi } from "./auth";
@@ -60,7 +60,8 @@ export type {
 /** Server-side caps for `/assist/command`; enforced here so a 422 is never sent. */
 const ASSIST_QUERY_MAX_LENGTH = 200;
 const ASSIST_COMMAND_LIMIT = 150;
-const ASSIST_ARG_OPTION_LIMIT = 64;
+/** The futures curve's root list is the longest a command sends: 76 since GLO-783. */
+export const ASSIST_ARG_OPTION_LIMIT = 128;
 const ASSIST_ARG_OPTION_VALUE_MAX_LENGTH = 40;
 const ASSIST_ARG_OPTION_LABEL_MAX_LENGTH = 60;
 const ASSIST_REQUEST_TIMEOUT_MS = 6_000;
@@ -450,14 +451,24 @@ class GloomApiClient {
     return this.request<CloudSyncSnapshotResponse>("/sync/snapshot", { method: "GET" });
   }
 
+  /**
+   * `baseRevision` goes out as If-Match: the server ignores the body field and
+   * would replace a snapshot another device wrote since this one pulled. With
+   * the header it refuses that write (409), raised as SyncRevisionConflictError
+   * so the controller pulls again instead.
+   */
   async putSyncSnapshot(snapshot: SyncSnapshot, options?: { baseRevision?: number | null }): Promise<CloudSyncPushResponse> {
-    return this.request<CloudSyncPushResponse>("/sync/snapshot", {
-      method: "PUT",
-      body: JSON.stringify({
-        snapshot,
-        baseRevision: options?.baseRevision ?? null,
-      }),
-    });
+    const baseRevision = options?.baseRevision ?? null;
+    try {
+      return await this.request<CloudSyncPushResponse>("/sync/snapshot", {
+        method: "PUT",
+        ...(baseRevision !== null ? { headers: { "If-Match": String(baseRevision) } } : {}),
+        body: JSON.stringify({ snapshot, baseRevision }),
+      });
+    } catch (error) {
+      if (error instanceof ApiRequestError && error.status === 409) throw new SyncRevisionConflictError(error.message);
+      throw error;
+    }
   }
 
   async getMarketplaceLayout(
@@ -636,6 +647,7 @@ class GloomApiClient {
   getChatState = this.chat.getState.bind(this.chat);
   updateChatChannelState = this.chat.updateChannelState.bind(this.chat);
   markChatNotificationsDelivered = this.chat.markNotificationsDelivered.bind(this.chat);
+  getUnseenChatNotificationIds = this.chat.getUnseenNotificationIds.bind(this.chat);
   openDirectChannel = this.chat.openDirectChannel.bind(this.chat);
   openGroupChannel = this.chat.openGroupChannel.bind(this.chat);
   getMessages = this.chat.getMessages.bind(this.chat);
@@ -648,6 +660,7 @@ class GloomApiClient {
   subscribeChatReactions = this.chat.subscribeReactions.bind(this.chat);
   connectChannel = this.chat.connectChannel.bind(this.chat);
   subscribeChatNotifications = this.chat.subscribeNotifications.bind(this.chat);
+  subscribeChatChannelState = this.chat.subscribeChannelState.bind(this.chat);
   subscribeChatPresence = this.chat.subscribePresence.bind(this.chat);
   getChatDiscordLink = this.chat.getDiscordLink.bind(this.chat);
   unlinkChatDiscord = this.chat.unlinkDiscord.bind(this.chat);

package/src/api-client/normalizers.ts

@@ -2,6 +2,7 @@ import type {
   ChatAccountType,
   ChatAttachment,
   ChatChannel,
+  ChatChannelState,
   ChatDiscordLink,
   ChatMessage,
   ChatMessageOrigin,
@@ -191,6 +192,26 @@ export function normalizeChatNotification(
   };
 }
 
+/** A `chat.channel_state` frame, or null when it is not one. */
+export function normalizeChatChannelStateFrame(data: unknown): ChatChannelState | null {
+  if (!data || typeof data !== "object") return null;
+  const state = data as Partial<ChatChannelState>;
+  if (
+    typeof state.channelId !== "string"
+    || typeof state.notificationsEnabled !== "boolean"
+    || typeof state.unreadCount !== "number"
+    || (state.lastReadMessageId !== null && typeof state.lastReadMessageId !== "string")
+  ) {
+    return null;
+  }
+  return {
+    channelId: state.channelId,
+    notificationsEnabled: state.notificationsEnabled,
+    lastReadMessageId: state.lastReadMessageId,
+    unreadCount: state.unreadCount,
+  };
+}
+
 export function normalizeChatChannel(
   channel: ChatChannel,
   fallbackKind: ChatChannel["kind"] = "public",

package/src/api-client/socket.ts

@@ -1,6 +1,7 @@
 import type { TapeFeedEvent } from "./tape";
 import type {
   AuthUser,
+  ChatChannelState,
   ChatMessage,
   ChatNotification,
   ChatReactionsUpdate,
@@ -11,6 +12,7 @@ import type {
   TeamNotification,
 } from "./types";
 import {
+  normalizeChatChannelStateFrame,
   normalizeChatMessage,
   normalizeChatNotification,
   normalizeChatReactions,
@@ -42,6 +44,7 @@ const cloudApiLog = debugLog.createLogger("cloud-api");
 
 type ChannelListener = (message: ChatMessage) => void;
 type ChatNotificationListener = (notification: ChatNotification) => void;
+type ChatChannelStateListener = (state: ChatChannelState) => void;
 type ChatPresenceListener = (onlineCount: number) => void;
 type ChatReactionsListener = (update: ChatReactionsUpdate) => void;
 type TeamNotificationListener = (notification: TeamNotification) => void;
@@ -108,6 +111,8 @@ export class CloudApiSocket {
   private readonly channelListeners = new Map<string, Set<ChannelListener>>();
   private readonly chatNotificationListeners =
     new Set<ChatNotificationListener>();
+  private readonly chatChannelStateListeners =
+    new Set<ChatChannelStateListener>();
   private readonly chatPresenceListeners = new Set<ChatPresenceListener>();
   private readonly chatReactionsListeners = new Set<ChatReactionsListener>();
   private readonly teamNotificationListeners =
@@ -249,6 +254,17 @@ export class CloudApiSocket {
     };
   }
 
+  /**
+   * The reader's read state or mute changed on another device or window. Like
+   * notifications, it never opens the socket by itself.
+   */
+  subscribeChatChannelState(listener: ChatChannelStateListener): () => void {
+    this.chatChannelStateListeners.add(listener);
+    return () => {
+      this.chatChannelStateListeners.delete(listener);
+    };
+  }
+
   /** A message's reactions changed in a channel this socket reads. */
   subscribeChatReactions(listener: ChatReactionsListener): () => void {
     this.chatReactionsListeners.add(listener);
@@ -511,6 +527,7 @@ export class CloudApiSocket {
     this.offeredFeatureListeners.clear();
     this.connectionListeners.clear();
     this.chatNotificationListeners.clear();
+    this.chatChannelStateListeners.clear();
     this.chatPresenceListeners.clear();
     this.chatReactionsListeners.clear();
     this.teamNotificationListeners.clear();
@@ -614,6 +631,16 @@ export class CloudApiSocket {
       return;
     }
 
+    if (parsed?.type === "chat.channel_state") {
+      const state = normalizeChatChannelStateFrame(parsed.data);
+      if (state) {
+        for (const listener of this.chatChannelStateListeners) {
+          listener(state);
+        }
+      }
+      return;
+    }
+
     if (parsed?.type === "team.notification" && parsed.data) {
       const notification = normalizeTeamNotification(
         parsed.data as TeamNotification,

package/src/api-client/types.ts

@@ -459,10 +459,12 @@ export interface CloudPricePointPayload {
   low?: number;
   close: number;
   volume?: number;
-  /** A coin's daily bar for the UTC day still forming when served; it has no volume yet. */
+  /** A daily bar still forming when served: a coin's UTC day, or the trade date a future is trading. */
   partial?: boolean;
   /** A coin's daily bar whose prices were rebuilt from hourly bars; a day the source left empty has no volume. */
   filled?: boolean;
+  /** A future's closed session whose settlement is not confirmed yet: it closes on the last trade. */
+  unsettled?: boolean;
 }
 
 type CloudEconImpact = "high" | "medium" | "low";

package/src/app/runtime/startup.ts

@@ -107,6 +107,10 @@ export function useAppStartupRuntime({
     appLog.info("app activity propagated", { active: appActive });
   }, [appActive]);
 
+  useEffect(() => {
+    chatController.setRaisesBackgroundAlerts(!isDetachedWindow);
+  }, [isDetachedWindow]);
+
   // Runs for the life of the app: a freeze is only reportable if something
   // was watching the clock while it happened.
   useEffect(() => startMainThreadStallMonitor(), []);

package/src/cli/commands/market.ts

@@ -24,6 +24,7 @@ import { withCliServices, withMarketData } from "../context";
 import { isoDate, parsePositiveInt, requireOneArg, takeFlag, takeOption } from "./command-utils";
 import type { BuiltinCliCommandDef } from "../command-options";
 import { CLI_COMMAND_GROUPS, TABLE_SECTION_OPTION } from "../help";
+import { CLI_EXIT_CODES } from "../exit-codes";
 import {
   formatChangePercentCell,
   formatCountCell,
@@ -44,7 +45,9 @@ import {
 import { getPublishedUsEquityCalendarYears, getPublishedUsEquitySession } from "../../market-data/published-us-sessions";
 import { isQuoteStaleForCurrentSession } from "../../market-data/quotes/freshness";
 import { isOptionsUnavailableError, listedOptionsAlternative, optionsUnavailableTitle } from "../../market-data/options-alternatives";
-import { cliFuturesContract, futuresContractMetrics, fundamentalsReportTables, renderFundamentalsReport } from "./ticker";
+import {
+  cliFuturesContract, futuresContractMetrics, fundamentalsReportTables, loadForwardYieldDeclarations, renderFundamentalsReport,
+} from "./ticker";
 import type { FuturesContractTermsPayload } from "../../api-client/futures-curve";
 import { futuresSettleText, isFuturesInstrument } from "../../market-data/futures-contract";
 import {
@@ -65,6 +68,7 @@ import {
   type OptionsChainBasis,
 } from "./options-chain";
 import { missingExpiryMessage } from "../../utils/option-expiry";
+import { declaredDividends } from "../../utils/declared-dividends";
 import {
   DEFAULT_LEAPS_CRITERIA, LEAPS_EXTRA_COLUMNS, LEAPS_USAGE, parseLeapsCriteria, runLeapsScreen, takeLeapsOptions,
 } from "./options-leaps";
@@ -143,14 +147,14 @@ import { earningsCalendarFailure, earningsChoiceNote, earningsDateLabel, isListi
 import { formatBasisPoints, toBasisPoints } from "../../utils/basis-points";
 import { notATickerSymbol, providerMissReason } from "../../sources/provider-errors";
 import { isNotATickerMessage, withListingSuggestion } from "../not-a-ticker";
-import { describeSuggestion, suggestListing } from "../listing-suggestion";
+import { describeSuggestion, suggestListing, suggestUsTicker, type ListingSuggestion } from "../listing-suggestion";
 import { splitSymbolArgs, uniqueSecuritySymbols } from "../symbol-args";
 import { cliPerpetualContract, perpetualContractStats, type PerpetualContractPayload } from "../perpetual-contract";
 import { subMinuteDataMessage } from "../known-gaps";
 import { secRegistrantMismatchMessage, SecRegistrantMismatchError, areDifferentCompanies } from "../../sources/sec-registrant";
 import { isCryptoPairSymbol } from "../../utils/crypto-pair";
 import { looksLikeCurrencyPair } from "../../utils/currency-pair";
-import { isUsListingExchange } from "../../utils/exchanges";
+import { canonicalExchange, isUsListingExchange } from "../../utils/exchanges";
 import { describeTickerChange, startTickerChangeLookup, tickerChangeLine, type TickerChange } from "../../tickers/ticker-changes";
 import { noSecReportsNotice, nonUsSecListingVenue } from "../../utils/sec";
 import type { MarketContext } from "../types";
@@ -208,6 +212,8 @@ type QuoteCliRecord = Omit<QuoteBatchResult, "error"> & {
   perpetualContract?: PerpetualContractPayload;
   /** The symbol changed: its issuer moved to another symbol, or its holder had another before. */
   tickerChange?: TickerChange;
+  /** A bare symbol read on a listing abroad that is one slip from a US ticker: the US ticker it was most likely typed for. */
+  usSuggestion?: ListingSuggestion;
 };
 type FinancialsCliData = TickerFinancials & {
   symbol: string;
@@ -504,6 +510,13 @@ function corporateActionRows(data: CorporateActionsData) {
       date: event.exDate,
       detail: currency ? formatDistributionAmount(event.amount, currency) : cleanDecimal(event.amount),
     })),
+    // Declared and unpaid, at its ex-date beside the paid rows, never one of them.
+    ...declaredDividends(data).map((event) => ({
+      type: "dividend",
+      date: event.exDate,
+      detail: `declared ${currency ? formatDistributionAmount(event.amount, currency) : cleanDecimal(event.amount)}`
+        + (event.payDate ? `, payable ${event.payDate}` : ""),
+    })),
     ...data.splits.map((event) => ({
       type: "split",
       date: event.date,
@@ -568,7 +581,9 @@ async function runQuote(rawArgs: string[], ctx: Parameters<CliCommandDef["execut
     // So is whether a symbol changed (FB is now META), for the same lists.
     const changes = new Map(listings.length > MAX_CHOICE_LOOKUPS ? []
       : listings.map((listing) => [listing, startTickerChangeLookup(market.dataProvider, listing.symbol, listing.exchange)] as const));
-    const results = await market.dataProvider.getQuotesBatch(targets, { forceRefresh: ctx.cliOptions.refresh });
+    // The service's quote of the moment, not each form's local copy from whenever it was last asked for:
+    // BRK.B saved on NYSE, BRK-B and BRK.B:NYSE print one quote (GLO-735). A local copy answers only offline.
+    const results = await market.dataProvider.getQuotesBatch(targets, { forceRefresh: ctx.cliOptions.refresh, revalidate: true });
     const listingOf = (result: QuoteBatchResult, index: number) => listings[targets.indexOf(result.target)] ?? listings[index]!;
     const asked = results.map(listingOf);
     const request = { command: commandName, noun: "quote" };
@@ -595,6 +610,11 @@ async function runQuote(rawArgs: string[], ctx: Parameters<CliCommandDef["execut
     const perpetualContracts = await Promise.all(answers.map(({ result }) => commandName === "quote" && result.quote
       ? cliPerpetualContract(result.quote)
       : null));
+    // A bare symbol quoted on a listing abroad (APPL, Aptus Pharma on BSE) that is one slip from a US ticker (AAPL) says so.
+    const usSuggestions = await Promise.all(answers.map(({ result, listing, notes }) => {
+      const venue = result.quote && !listing.saved ? bareListingNote(listing, result.quote) : null;
+      return venue && notes.includes(venue) ? suggestUsTicker(listing.symbol, market) : null;
+    }));
     // Each row names its listing by key (SAN:EPA) and company, so the table needs no line above it.
     const data = answers.map(({ result, listing, failure }, index) => ({
       target: result.target,
@@ -604,6 +624,7 @@ async function runQuote(rawArgs: string[], ctx: Parameters<CliCommandDef["execut
       quote: result.quote,
       ...contracts[index] ? { futuresContract: contracts[index] } : {},
       ...perpetualContracts[index] ? { perpetualContract: perpetualContracts[index] } : {},
+      ...usSuggestions[index] ? { usSuggestion: usSuggestions[index] } : {},
       error: failure?.oneLine ?? errorMessage(result.error),
       ...yieldIndexFields(result),
       ...tickerChanges[index] ? { tickerChange: tickerChanges[index] } : {},
@@ -630,15 +651,38 @@ async function runQuote(rawArgs: string[], ctx: Parameters<CliCommandDef["execut
       freshness: quotesFreshness(data.map((row) => row.quote)),
     }, {
       rows: quoteRows,
-      details: quoteFuturesContractText,
+      details: quoteDetailsText,
       columns,
       ...(yieldsOnly ? { textColumns: columns.map((column) => column.key === "changePercent" ? { ...column, header: "Chg" } : column) } : {}),
     });
+    // The table names each symbol it found nothing for; with none found, the exit status says so too.
+    if (data.every((row) => !row.quote)) process.exitCode = CLI_EXIT_CODES.error;
   });
 }
 
 /**
- * Under the table, each futures row's Settle line and Contract block, worded
+ * Under the table: each futures row's Settle line and Contract block, then the
+ * line for a symbol that is not a US ticker though it is one slip from one.
+ */
+function quoteDetailsText(data: QuoteCliRecord[]): string {
+  return [quoteFuturesContractText(data), ...data.flatMap((row) => notUsTickerLine(row) ?? [])].filter(Boolean).join("\n\n");
+}
+
+/**
+ * "APPL is not a US ticker: it is Aptus Pharma Limited on BSE (INR). Did you
+ * mean AAPL (Apple Inc.)?", for a symbol read on a listing abroad that is one
+ * slip from a US ticker, worded as the not-a-ticker answers word it.
+ */
+function notUsTickerLine({ target, quote, listing, usSuggestion }: QuoteCliRecord): string | null {
+  if (!quote || !usSuggestion) return null;
+  const venue = canonicalExchange(quote.listingExchangeName || quote.exchangeName);
+  const name = quote.name || listing?.name;
+  const what = `${name ? `${name} on ` : ""}${venue}${quote.currency ? ` (${quote.currency})` : ""}`;
+  return cliStyles.warning(`${target.symbol} is not a US ticker: it is ${what}. Did you mean ${describeSuggestion(usSuggestion)}?`);
+}
+
+/**
+ * Each futures row's Settle line and Contract block, worded
  * as `ticker` words them. Several symbols name theirs in the block's title.
  */
 function quoteFuturesContractText(data: QuoteCliRecord[]): string {
@@ -842,16 +886,18 @@ async function runHistory(rawArgs: string[], ctx: Parameters<CliCommandDef["exec
     const flagColumn: CliResultColumn = {
       key: "flag", header: "Flag", format: (value) => typeof value === "string" ? cliStyles.warning(value) : "",
     };
-    // Text also marks a bar still forming or rebuilt from hourly bars there; exports keep them as their own fields.
+    // Text also marks a bar still forming, rebuilt from hourly bars or closing before its settlement; exports keep them as fields.
     const flagTextColumn: CliResultColumn = {
       ...flagColumn,
       format: (value, row) => [
         typeof value === "string" ? cliStyles.warning(value) : "",
         row.partial ? cliStyles.muted("partial") : "",
         row.filled ? cliStyles.muted("filled") : "",
+        row.unsettled ? cliStyles.muted("unsettled") : "",
       ].filter(Boolean).join(" "),
     };
     const marked = data.some((row) => row.partial || row.filled);
+    const unsettled = data.some((row) => row.unsettled);
     ctx.printResult({
       data,
       metadata: {
@@ -880,6 +926,7 @@ async function runHistory(rawArgs: string[], ctx: Parameters<CliCommandDef["exec
         ...priceColumns,
         flagColumn,
         ...marked ? [{ key: "partial", header: "Partial" }, { key: "filled", header: "Filled" }] : [],
+        ...unsettled ? [{ key: "unsettled", header: "Unsettled" }] : [],
         ...volume ? [{ key: "volumeUnit", header: "Volume unit" }, { key: "volumeNote", header: "Volume note" }] : [],
       ],
       // Every exported row says what it is a bar of, the currency a price is in and its bar size, so it survives head and concatenation.
@@ -937,6 +984,10 @@ async function runFinancials(rawArgs: string[], ctx: Parameters<CliCommandDef["e
       // Market cap, the multiples and the yield at the regular session price, as the text gives them; the quote stays as sent.
       const priced = atRegularSessionPrice(financials);
       const capitalization = selectMarketCapitalization(priced.quote, priced.fundamentals);
+      // A forward yield dated ahead names the declared distribution it annualizes, in the text and tables.
+      const report = ctx.cliOptions.format === "json" ? data : {
+        ...data, declaredDividends: await loadForwardYieldDeclarations(market.dataProvider, listing.request, financials.fundamentals),
+      };
       ctx.printResult({
         // JSON reads a multiple over a loss as null with its reason, never as a number.
         data: {
@@ -951,8 +1002,8 @@ async function runFinancials(rawArgs: string[], ctx: Parameters<CliCommandDef["e
         freshness,
         ...(choice.length > 0 ? { warnings: choice } : {}),
       }, {
-        text: () => renderFundamentalsReport(data, view),
-        ...(tabular ? { tables: selectTables(fundamentalsReportTables(data, view, freshness)) } : {}),
+        text: () => renderFundamentalsReport(report, view),
+        ...(tabular ? { tables: selectTables(fundamentalsReportTables(report, view, freshness)) } : {}),
         exportIdentity: { symbolOrSeries: listing.key },
       });
       return;

package/src/cli/commands/search.ts

@@ -26,7 +26,7 @@ import { indexRootFor, indexRootTryLine } from "../index-roots";
 import { knownGapMessage, settingsPointer } from "../known-gaps";
 import { instrumentTypeLabel } from "../../tickers/instrument-kind";
 import { canonicalExchange, isUsListingExchange } from "../../utils/exchanges";
-import { groupByCompany } from "../../tickers/company-name";
+import { groupByCompany, sameCompany } from "../../tickers/company-name";
 import { findCatalogSeries, renderSeriesMatches, type SeriesMatch } from "../series-search";
 import { centralBankCiting, centralBankNamed, type CentralBank } from "../../utils/central-banks";
 import { createPaneCatalog } from "../pane-functions/discovery";
@@ -120,7 +120,7 @@ export async function searchCandidatesForCli({
     const quote = BARE_SYMBOL.test(symbol) && candidates.some((candidate) => candidate.symbol.toUpperCase() === symbol)
       ? await (quoted ?? loadSearchedQuote(symbol, savedExchange, dataProvider))
       : null;
-    return withQuotedNames(symbol, withPrimaryListingFirst(symbol, candidates, quote), quote).slice(0, totalLimit);
+    return withQuotedNames(symbol, withHomeListingPrimary(symbol, withPrimaryListingFirst(symbol, candidates, quote)), quote).slice(0, totalLimit);
   } catch {
     return [];
   }
@@ -217,6 +217,47 @@ function withPrimaryListingFirst(
   ));
 }
 
+/** Venues that only quote shares listed elsewhere: the OTC tiers, Frankfurt's open market and Germany's regional exchanges. */
+const SECONDARY_VENUES = new Set(["OTC", "PNK", "OTCQX", "OTCQB", "FWB2", "MUNICH", "XSTU", "XDUS", "XBER", "XHAM", "HANOVER"]);
+
+/**
+ * How far a listing is from being its company's own line: 0 a plain one, 1 a
+ * line that only quotes shares listed elsewhere (a regional venue, OTC, a
+ * Milan 4MSFT or London 0XXX code), 2 a depositary receipt.
+ */
+function listingDistance(candidate: TickerSearchCandidate): 0 | 1 | 2 {
+  if (/depositary|^(?:ADR|ADS|GDR|CDR|BDR)$/i.test(candidate.instrumentType ?? "")) return 2;
+  return SECONDARY_VENUES.has(candidateExchange(candidate)) || /\d/.test(candidate.symbol) && /[A-Za-z]/.test(candidate.symbol) ? 1 : 0;
+}
+
+/**
+ * A company searched by name lists its home line as the primary listing. A
+ * search row names no home exchange or volume, so a company's lines go by
+ * how far each is from being its own line (`listingDistance`), then by the
+ * search score the service gives the listings people look up most. The
+ * listing search put first, often the one-off cross-listing whose short name
+ * matched the query (LUFTHANSA on Budapest), gives way only to a closer line,
+ * or to one searched at least twice as often, or any scored line when it has
+ * no score. A listing searched by its own symbol is not moved.
+ */
+function withHomeListingPrimary(symbol: string, candidates: TickerSearchCandidate[]): TickerSearchCandidate[] {
+  const primary = candidates.find((candidate) => candidate.category === "Primary Listing");
+  if (!primary || primary.kind !== "search" || primary.symbol.toUpperCase() === symbol) return candidates;
+  const company = resolveSearchName(primary);
+  const lines = candidates.filter((candidate) => candidate.kind === "search" && candidate.category !== "Funds & Derivatives"
+    && (candidate.instrumentClass === "equity" || candidate.instrumentClass === "other") && sameCompany(resolveSearchName(candidate), company));
+  const score = (candidate: TickerSearchCandidate) => candidate.result?.popularity ?? candidate.popularity ?? null;
+  const [home] = [...lines].sort((a, b) => listingDistance(a) - listingDistance(b) || (score(b) ?? -1) - (score(a) ?? -1) || candidates.indexOf(a) - candidates.indexOf(b));
+  if (!home || home === primary) return candidates;
+  const closer = listingDistance(home) < listingDistance(primary);
+  const [homeScore, primaryScore] = [score(home), score(primary)];
+  const moreSearched = listingDistance(home) === listingDistance(primary) && homeScore != null && (primaryScore == null || homeScore >= primaryScore * 2);
+  if (!closer && !moreSearched) return candidates;
+  const rest = candidates.filter((candidate) => candidate !== home);
+  const at = rest.indexOf(primary);
+  return [...rest.slice(0, at), { ...home, category: "Primary Listing" as const }, { ...primary, category: "Other Listings" as const }, ...rest.slice(at + 1)];
+}
+
 /** The candidate on the venue the quote prices; the US exchanges share one symbol, so a quote on any of them is its one US line. */
 function quotedCandidate(candidates: readonly TickerSearchCandidate[], quote: Quote | null): TickerSearchCandidate | undefined {
   const quoted = canonicalExchange(quote?.listingExchangeName || quote?.exchangeName);