gloomberb 0.19.0 → 0.19.1

package/README.md

@@ -50,7 +50,7 @@ The script downloads the prebuilt release from GitHub and checks its SHA-256 aga
 With [Bun](https://bun.sh), on any supported OS:
 
 ```bash
-bun install -g gloomberb
+bun install -g @gloom-sh/terminal
 ```
 
 Then run `gloom`. The command was called `gloomberb` before 0.18.4, and that name still works. For chart graphics, use a Kitty-compatible terminal such as Ghostty, Kitty, or WezTerm. Windows Terminal draws charts as text; the desktop app draws them in full.

package/README.zh-CN.md

@@ -62,7 +62,7 @@ curl -fsSL gloom.sh/install | bash
 也可在 macOS、Linux 或 Windows x64 上通过 [Bun](https://bun.sh) 安装：
 
 ```bash
-bun install -g gloomberb
+bun install -g @gloom-sh/terminal
 ```
 
 运行 `gloom` 即可启动。0.18.4 之前命令名为 `gloomberb`，该名称仍可使用。要显示图形，请使用兼容 Kitty 图形协议的终端，例如 Ghostty、Kitty 或 WezTerm。直接下载、安装位置与更新方式详见[安装指南（英文）](docs/installation.md)。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gloomberb",
-  "version": "0.19.0",
+  "version": "0.19.1",
   "packageManager": "bun@1.3.11",
   "description": "Market research and portfolio tracker for the terminal",
   "module": "src/public/index.ts",

package/patches/electrobun@1.18.1.patch

@@ -1,3 +1,16 @@
+diff --git a/dist/api/browser/index.ts b/dist/api/browser/index.ts
+index 3e309b18fdbcec84a4a56f97df4debe7fb8246f8..03420222c1d9ba897835c5e7376c7153ede294fc 100644
+--- a/dist/api/browser/index.ts
++++ b/dist/api/browser/index.ts
+@@ -50,7 +50,7 @@ class Electroview<T extends RPCWithTransport> {
+ 		// Note: Using ws:// for localhost is intentional - all RPC messages are
+ 		// encrypted with per-webview AES-GCM keys, making TLS redundant
+ 		const socket = new WebSocket(
+-			`ws://localhost:${RPC_SOCKET_PORT}/socket?webviewId=${WEBVIEW_ID}`,
++			`ws://127.0.0.1:${RPC_SOCKET_PORT}/socket?webviewId=${WEBVIEW_ID}`,
+ 		);
+ 
+ 		this.bunSocket = socket;
 diff --git a/dist/api/bun/core/BrowserWindow.ts b/dist/api/bun/core/BrowserWindow.ts
 index c26c2c977ee1fc25a8dc144b85bac8626a45f572..8920a2905380228c23cba66c20d9bfd19ee13e02 100644
 --- a/dist/api/bun/core/BrowserWindow.ts
@@ -54,7 +67,7 @@ index c26c2c977ee1fc25a8dc144b85bac8626a45f572..8920a2905380228c23cba66c20d9bfd1
  				width: this.frame.width,
  				height: this.frame.height,
 diff --git a/dist/api/bun/core/Socket.ts b/dist/api/bun/core/Socket.ts
-index cdaa2bca0fabe577cb667056aa6f8f84211189c2..3839e5232742c2467180c344f51a30f1ff3c797f 100644
+index cdaa2bca0fabe577cb667056aa6f8f84211189c2..e9cdd82c934f6da58055dc8343ee3b953ec1ee81 100644
 --- a/dist/api/bun/core/Socket.ts
 +++ b/dist/api/bun/core/Socket.ts
 @@ -3,13 +3,8 @@ import { BrowserView } from "./BrowserView";
@@ -73,6 +86,15 @@ index cdaa2bca0fabe577cb667056aa6f8f84211189c2..3839e5232742c2467180c344f51a30f1
  }
  
  // Encrypt function
+@@ -65,6 +60,8 @@ const startRPCServer = () => {
+ 	while (port <= endPort) {
+ 		try {
+ 			server = Bun.serve<{ webviewId: number }>({
++				// Only this machine's webviews connect.
++				hostname: "127.0.0.1",
+ 				port,
+ 				fetch(req: Request, server: Server<{ webviewId: number }>) {
+ 					const url = new URL(req.url);
 diff --git a/dist/api/bun/core/Updater.ts b/dist/api/bun/core/Updater.ts
 index 39daf6d341780af8e30c2c50327162863f5977ec..4f3d2bef8e4b41a13a5a522c0af8dd700879a5db 100644
 --- a/dist/api/bun/core/Updater.ts

package/src/api-client/app-attention.ts

@@ -1,3 +1,4 @@
+import type { CompanyFrom } from "../types/company-from"
 type AppStore = "app-store" | "google-play"
 export type AppChart = "free" | "paid" | "grossing" | "unranked"
 
@@ -97,6 +98,8 @@ interface AppSourceState {
 export interface AppAttentionPayload {
   generatedAt: string
   requestedSymbol?: string
+  /** The company's home line the data is read from, when not the listing asked (a receipt, a foreign line). */
+  companyFrom?: CompanyFrom
   page?: { offset: number; limit: number; total: number; nextOffset: number | null }
   symbol: string | null
   access: "pro" | "preview"

package/src/api-client/beneficial-owners.ts

@@ -1,3 +1,4 @@
+import type { CompanyFrom } from "../types/company-from";
 /**
  * Schedule 13D and 13G beneficial ownership reports about one issuer, as
  * `GET /cloud/sec/beneficial-owners` returns them. Percentages are percent
@@ -71,6 +72,8 @@ export interface BeneficialOwnersCoverage {
 
 export interface BeneficialOwnersPayload {
   ticker: string;
+  /** The company's home line the owners are read from, when not the listing asked (a foreign line). */
+  companyFrom?: CompanyFrom;
   cik: string;
   companyName: string;
   /** When the server assembled the list, an ISO time. */

package/src/api-client/company-kpis.ts

@@ -1,3 +1,4 @@
+import type { CompanyFrom } from "../types/company-from"
 import { listingAbroad, type IssuerListingParams } from "./paths";
 
 type QuoteMatchMode = "exact" | "whitespace" | "nfkc_whitespace";
@@ -132,6 +133,8 @@ export interface KpiSeries {
 }
 export interface KpisPayload {
   symbol: string
+  /** The company's home line the data is read from, when not the listing asked (a receipt, a foreign line). */
+  companyFrom?: CompanyFrom
   status: "available" | "unavailable"
   asOf: string | null
   coverage: KpiCoverage

package/src/api-client/data.ts

@@ -1284,8 +1284,9 @@ export class CloudDataApi {
     query: string,
     limit?: number,
     topics?: readonly string[],
+    options: { closest?: boolean; tickers?: readonly string[] } = {},
   ): Promise<CloudNewsListResponse> {
-    return this.request<CloudNewsListResponse>(cloudNewsSearchPath(query, limit, topics));
+    return this.request<CloudNewsListResponse>(cloudNewsSearchPath(query, limit, topics, options));
   }
 
   async getCloudNewsStory(storyId: string): Promise<CloudNewsPayload> {

package/src/api-client/hiring.ts

@@ -1,3 +1,4 @@
+import type { CompanyFrom } from "../types/company-from"
 /** HIRING is an observed requisition series, not headcount or job creation. */
 interface HiringCompany {
   entityId: string
@@ -76,6 +77,8 @@ export interface HiringSummary extends HiringCompany {
 export interface HiringPayload extends HiringSummary {
   generatedAt: string
   requestedSymbol?: string
+  /** The company's home line the data is read from, when not the listing asked (a receipt, a foreign line). */
+  companyFrom?: CompanyFrom
   proRequired: true
   preview: boolean
   locked: { history: number; evidence: number; peers: number; signals: number; mix: number }

package/src/api-client/index.ts

@@ -24,6 +24,7 @@ import { CloudApiRequestTransport, putWithRevision } from "./request";
 import { CloudApiSocket } from "./socket";
 import { CloudCollectionsApi } from "./collections";
 import { CloudFeedbackApi } from "./feedback";
+import { CloudRoadmapApi } from "./roadmap";
 import { CloudNotesApi } from "./notes";
 import { CloudTeamsApi } from "./teams";
 import { CloudTelemetryApi } from "./telemetry";
@@ -154,6 +155,7 @@ class GloomApiClient {
   private readonly data: CloudDataApi = new CloudDataApi((path, options) => this.request(path, options));
   private readonly notes: CloudNotesApi = new CloudNotesApi((path, options) => this.request(path, options));
   private readonly feedback: CloudFeedbackApi = new CloudFeedbackApi((path, options) => this.request(path, options));
+  private readonly roadmap: CloudRoadmapApi = new CloudRoadmapApi((path, options) => this.request(path, options));
   private readonly telemetry: CloudTelemetryApi = new CloudTelemetryApi((path, options) => this.request(path, options));
   private readonly theses: CloudThesesApi = new CloudThesesApi((path, options) => this.request(path, options));
   private readonly collections: CloudCollectionsApi = new CloudCollectionsApi((path, options) => this.request(path, options));
@@ -874,6 +876,8 @@ class GloomApiClient {
   putCloudNote = this.notes.putNote.bind(this.notes);
   submitFeedback = this.feedback.submitFeedback.bind(this.feedback);
   listFeedback = this.feedback.listFeedback.bind(this.feedback);
+  getRoadmap = this.roadmap.getRoadmap.bind(this.roadmap);
+  setRoadmapVote = this.roadmap.setRoadmapVote.bind(this.roadmap);
   reportCrashErrors = this.telemetry.reportCrashErrors.bind(this.telemetry);
   reportUsageCounts = this.telemetry.reportUsageCounts.bind(this.telemetry);
   reportAttentionCounts = this.telemetry.reportAttentionCounts.bind(this.telemetry);

package/src/api-client/ipo.ts

@@ -28,6 +28,24 @@ interface IpoFirstDay {
   returnPct: number | null;
 }
 
+/**
+ * When a US IPO's lock-up is estimated to end: the final prospectus's date
+ * plus the period it states, or the first session plus the usual 180 days
+ * until the prospectus is read. An estimate: underwriters can release
+ * shares early, and some holders agree to other periods.
+ */
+export interface IpoLockup {
+  /** YYYY-MM-DD. */
+  endsOn: string;
+  days: number;
+  /** `prospectus`: the period the final prospectus states; `typical`: 180 days, when it states none of a lock-up's length or was not read. */
+  basis: "prospectus" | "typical";
+  /** The date the final prospectus is dated, when it was read. */
+  prospectusDate: string | null;
+  /** The SEC document the period was read from. */
+  prospectusUrl: string | null;
+}
+
 export interface IpoDeal {
   /** Assigned when the deal is first seen and never changed. */
   id: string;
@@ -66,6 +84,8 @@ export interface IpoDeal {
   listingType: IpoListingType;
   filedDate: string | null;
   firstDay: IpoFirstDay | null;
+  /** A priced or listed US IPO's estimated lock-up end; absent elsewhere, and from a server without the estimate. */
+  lockup?: IpoLockup | null;
   updatedAt: string;
 }
 
@@ -86,11 +106,14 @@ export interface IpoCalendarPayload {
 
 /**
  * Narrows or moves the window. Without any, the server sends its default:
- * 90 days back to 180 ahead, filed and withdrawn deals left out, 500 at most.
+ * a year back (90 days on a server before that) to 180 days ahead, filed
+ * and withdrawn deals left out.
  */
 export interface IpoCalendarParams {
   region?: IpoRegion;
   status?: IpoStatus;
+  /** Company (in either script) or symbol the deals' names contain. */
+  q?: string;
   /** First listing date, YYYY-MM-DD. */
   from?: string;
   /** Last listing date, YYYY-MM-DD. */

package/src/api-client/mna.ts

@@ -1,3 +1,4 @@
+import type { CompanyFrom } from "../types/company-from";
 /**
  * Mergers and acquisitions read from news, press releases and SEC filings.
  * A deal is one target and one buyer; a target with competing bidders has a
@@ -84,6 +85,8 @@ export interface MnaDealsParams {
 
 export interface MnaDealsPayload {
   deals: MnaDeal[];
+  /** The company's home line the data is read from, when not the listing asked (a receipt, a foreign line). */
+  companyFrom?: CompanyFrom;
   hasMore: boolean;
   nextOffset: number;
   /** "delayed" hides deals first reported within `delayDays` from a free account. */

package/src/api-client/paths.ts

@@ -621,10 +621,18 @@ export function cloudNewsPath(params: CloudNewsParams = {}): string {
 
 /** Stories whose headline, summary or publisher matches the text, best match first; the service takes at most 100. */
 /** `topics` are NI codes the stories must carry: `query=gold&topics=metals` is gold's market news. */
-export function cloudNewsSearchPath(query: string, limit?: number, topics?: readonly string[]): string {
+/**
+ * `closest`: when no story has every word, the stories with the most of them, marked `match: "closest"`.
+ * `tickers`: only the stories filed under them (`HAWK:NYSE`).
+ */
+export function cloudNewsSearchPath(
+  query: string, limit?: number, topics?: readonly string[], options: { closest?: boolean; tickers?: readonly string[] } = {},
+): string {
   const search = new URLSearchParams({ query });
   if (limit != null) search.set("limit", String(limit));
   if (topics?.length) search.set("topics", topics.join(","));
+  if (options.tickers?.length) search.set("tickers", options.tickers.join(","));
+  if (options.closest) search.set("closest", "1");
   return appendQuery("/news/search", search);
 }
 

package/src/api-client/roadmap.ts

@@ -0,0 +1,85 @@
+import type { CloudApiRequest } from "./request";
+
+/**
+ * The public roadmap: what is being built, what is planned and what shipped,
+ * with the votes Pro members put on the first two. Anyone reads it; a signed-in
+ * Pro member votes once per item and can take the vote back.
+ */
+const ROADMAP_STATUSES = ["building", "planned", "shipped"] as const;
+export type RoadmapStatus = (typeof ROADMAP_STATUSES)[number];
+
+export interface RoadmapItem {
+  id: string;
+  title: string;
+  /** One line on what it is. */
+  blurb: string;
+  status: RoadmapStatus;
+  /** ISO time it shipped; null until then. */
+  shippedAt: string | null;
+  votes: number;
+  /** Whether this account voted for it; false signed out. */
+  voted: boolean;
+}
+
+export interface RoadmapPayload {
+  items: RoadmapItem[];
+  /** The service's word on whether this session may vote (a verified Pro account). */
+  canVote: boolean;
+}
+
+export interface RoadmapVote {
+  id: string;
+  votes: number;
+  voted: boolean;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function parseItem(value: unknown): RoadmapItem | null {
+  if (!isRecord(value)) return null;
+  const { id, title, blurb, status, shippedAt, votes, voted } = value;
+  if (typeof id !== "string" || !id || typeof title !== "string" || !title.trim()) return null;
+  if (!(ROADMAP_STATUSES as readonly unknown[]).includes(status)) return null;
+  return {
+    id,
+    title: title.trim(),
+    blurb: typeof blurb === "string" ? blurb.trim() : "",
+    status: status as RoadmapStatus,
+    shippedAt: typeof shippedAt === "string" && Number.isFinite(Date.parse(shippedAt)) ? shippedAt : null,
+    votes: typeof votes === "number" && Number.isFinite(votes) ? Math.max(0, Math.round(votes)) : 0,
+    voted: voted === true,
+  };
+}
+
+/** Items it cannot read (an unknown status from a newer service) are left out, not the whole list. */
+function parseRoadmapPayload(value: unknown): RoadmapPayload {
+  if (!isRecord(value) || !Array.isArray(value.items)) throw new Error("The roadmap service returned invalid data.");
+  return {
+    items: value.items.map(parseItem).filter((item): item is RoadmapItem => item !== null),
+    canVote: value.canVote === true,
+  };
+}
+
+function parseVote(value: unknown): RoadmapVote {
+  if (!isRecord(value) || typeof value.id !== "string" || typeof value.votes !== "number" || typeof value.voted !== "boolean") {
+    throw new Error("The roadmap service returned invalid data.");
+  }
+  return { id: value.id, votes: value.votes, voted: value.voted };
+}
+
+export class CloudRoadmapApi {
+  constructor(private readonly request: CloudApiRequest) {}
+
+  async getRoadmap(signal?: AbortSignal): Promise<RoadmapPayload> {
+    return parseRoadmapPayload(await this.request<unknown>("/roadmap", { signal }));
+  }
+
+  /** Votes, or takes the vote back; the answer is the item's count after it. */
+  async setRoadmapVote(id: string, voted: boolean): Promise<RoadmapVote> {
+    return parseVote(await this.request<unknown>(`/roadmap/${encodeURIComponent(id)}/vote`, {
+      method: voted ? "POST" : "DELETE",
+    }));
+  }
+}

package/src/api-client/types.ts

@@ -1,3 +1,4 @@
+import type { CompanyFrom } from "../types/company-from";
 import type {
   AnalystResearchData,
   CorporateActionsData,
@@ -1060,6 +1061,8 @@ export interface CloudEarningsCallListPayload {
   pending?: boolean;
   /** Set when the requested symbol is not one the SEC knows. */
   unknownTicker?: boolean;
+  /** The company's home line the calls are read from, when not the listing asked (a receipt, a foreign line). */
+  companyFrom?: CompanyFrom;
 }
 
 /** One row of a proxy statement's Summary Compensation Table, in dollars. */
@@ -1456,6 +1459,8 @@ export interface CloudSecFilingsResponse {
   filings: CloudSecFilingPayload[];
   hasMore: boolean;
   nextOffset: number;
+  /** The company's home line the filings are read from, when not the listing asked (a foreign line). */
+  companyFrom?: CompanyFrom;
 }
 
 export interface CloudSecDocumentsResponse {
@@ -1558,6 +1563,13 @@ export interface CloudNewsListResponse {
   nextCursor: string | null;
   /** Which news the service answered with, when it says: the live wire, or the one held back for a free account. */
   access?: "realtime" | "delayed";
+  /**
+   * A search asked for its closest stories: `all` when stories have every
+   * word, `closest` when none does and these have the most of them.
+   */
+  match?: "all" | "closest";
+  /** A receipt's or foreign line's feed is its company's: the home line it reads, when not the listing asked. */
+  companyFrom?: CompanyFrom;
 }
 
 interface CloudTweetUserPayload {

package/src/architecture/core-builtin-allowlist.json

@@ -9,7 +9,7 @@
   "src/cli/commands/options-chain.ts": ["options","options-calculator"],
   "src/cli/commands/options-leaps.ts": ["iv-history","options","vol-surface"],
   "src/cli/commands/overview.ts": ["correlation","econ","market-movers","sectors","world-indices"],
-  "src/cli/commands/ticker.ts": ["notes"],
+  "src/cli/commands/ticker.ts": ["ipo-calendar","notes"],
   "src/cli/desktop-pane-shot.ts": ["market-valuation","time-sales"],
   "src/cli/pane-functions/data.ts": ["chart-composer","correlation","seasonality","ticker-detail"],
   "src/cli/pane-functions/financial-ratio-shot.ts": ["ticker-detail"],
@@ -27,7 +27,7 @@
   "src/components/layout/shell/index.tsx": ["cloud"],
   "src/components/onboarding/use-onboarding-upgrade.ts": ["chat"],
   "src/layout/desks.ts": ["chart-composer"],
-  "src/plugins/catalog-browser.ts": ["alerts","analytics","attention","awards","backtest","bond-calculator","catalysts","cds","central-bank-rates","changelog","chart-composer","clinical-trials","cloud","comment-letters","commodities-energy","commodity-balances","company-attention","company-kpis","connections","correlation","cot","cpi","credit-boards","credit-conditions","credit-documents","crypto-board","crypto-etf-flows","debt-maturities","dividend-yield","docs","doe","earnings","earnings-calls","earnings-ripple","econ","econ-statistics","equity-screener","estimate-revisions","executives","exposure","fear-greed","filing-events","fixed-income","futures","futures-curve","fx-matrix","gpu","help","holders","insider","ipo-calendar","iv-history","jobs","jodi","kelly-sizer","layout-manager","macro-day","market-halts","market-heatmap","market-valuation","members","mna","money-markets","news","openfda","options","options-calculator","options-positioning","options-scenario","pe-band","perps","portfolio-list","power","primary-dealers","rate-path","realized-vol","relative-rotation","research","research-search","revenue-breakdown","reverse-dcf","risk-factors","scanner","seasonality","sec","sectors","short-interest","short-volume","social-mentions","supply-chain","thirteenf","ticker-detail","time-sales","trace-bonds","treasury-auctions","treasury-daily","vol-surface","volatility","world-indices","world-venue-map","yield-curve"],
+  "src/plugins/catalog-browser.ts": ["alerts","analytics","attention","awards","backtest","bond-calculator","catalysts","cds","central-bank-rates","changelog","chart-composer","clinical-trials","cloud","comment-letters","commodities-energy","commodity-balances","company-attention","company-kpis","connections","correlation","cot","cpi","credit-boards","credit-conditions","credit-documents","crypto-board","crypto-etf-flows","debt-maturities","dividend-yield","docs","doe","earnings","earnings-calls","earnings-ripple","econ","econ-statistics","equity-screener","estimate-revisions","executives","exposure","fear-greed","filing-events","fixed-income","futures","futures-curve","fx-matrix","gpu","help","holders","insider","ipo-calendar","iv-history","jobs","jodi","kelly-sizer","layout-manager","macro-day","market-halts","market-heatmap","market-valuation","members","mna","money-markets","news","openfda","options","options-calculator","options-positioning","options-scenario","pe-band","perps","portfolio-list","power","primary-dealers","rate-path","realized-vol","relative-rotation","research","research-search","revenue-breakdown","reverse-dcf","risk-factors","roadmap","scanner","seasonality","sec","sectors","short-interest","short-volume","social-mentions","supply-chain","thirteenf","ticker-detail","time-sales","trace-bonds","treasury-auctions","treasury-daily","vol-surface","volatility","world-indices","world-venue-map","yield-curve"],
   "src/plugins/catalog-ui.ts": ["alerts","clinical-trials","cloud","comment-letters","custom-view","fear-greed","ipo-calendar","market-halts","market-heatmap","members","news","notes","openfda","research-search"],
   "src/plugins/catalog.ts": ["debug"],
   "src/remote/controller.ts": ["custom-view"],

package/src/cli/commands/market.ts

@@ -3,6 +3,7 @@ import type { CliCommandDef } from "../../types/plugin";
 import { TIME_RANGES, type TimeRange } from "../../time-series/range";
 import { yearToDateStartIndex } from "../../market-data/market/year-to-date";
 import type { EarningsEvent, QuoteBatchResult, QuoteSubscriptionTarget, SecFilingItem } from "../../types/data-provider";
+import { companyDataNotes, type CompanyFrom } from "../../types/company-from";
 import type { NewsArticle, NewsFeed, NewsQuery } from "../../news/types";
 import type {
   AnalystResearchData,
@@ -165,6 +166,7 @@ import { bareFuturesCode, futuresBoardContract } from "../../market-data/futures
 import { commodityNamedIn, commoditySearchName } from "../../market-data/commodity-names";
 import { newsEmptyMessage } from "./news-hints";
 import {
+  closestStoriesReason,
   commodityNewsRoute,
   commonWordCandidate,
   METALS_NEWS_TOPIC,
@@ -179,6 +181,7 @@ import {
   noMetalStoriesMessage,
   noStoriesMessage,
   quotedSearchCommand,
+  searchClosestNewsStories,
   searchNewsStories,
   wordMeansMore,
 } from "./news-search";
@@ -189,7 +192,7 @@ import { exportedFundamentals } from "../../utils/price-earnings";
 import { fundamentalsFreshness, fxPairFreshness, quotesFreshness, rowsFreshness, valuationFreshness } from "../freshness";
 import { fxRateNotes } from "../../plugins/builtin/shared/fx-rate-freshness";
 import { quoteBarNotes } from "../../market-data/quotes/intraday-bar";
-import { depositaryPairText, isReceiptSide, listingDepositaryPair } from "../../market-data/depositary-pair";
+import { cedearRatioText, depositaryPairText, isReceiptSide, listingCedearRatio, listingDepositaryPair } from "../../market-data/depositary-pair";
 import { isPesoDollarPair, loadPesoDollarRates, pesoDollarRateLines, pesoDollarRatesJson } from "../peso-dollar-rates";
 import { atRegularSessionPrice, regularSessionValuationPrice } from "../../market-data/quotes/regular-session-valuation";
 import { viewMarketCapitalization } from "../../utils/market-capitalization";
@@ -199,6 +202,7 @@ import {
   cloudNewsFreshness,
   cloudRealtimeAccess,
   REPORTED_DATA,
+  SEC_FILING_ROWS,
   SEC_FILINGS,
 } from "../../plugins/builtin/shared/report-freshness";
 import {
@@ -242,7 +246,7 @@ import {
   type ListingIdentity,
 } from "../listing-arg";
 import { bareListingNote, listingFateNotes, noLongerTradingNote, tradingListing } from "../../tickers/listing-fate";
-import { isYieldIndexSymbol } from "../index-roots";
+import { isYieldIndexSymbol } from "../../tickers/index-roots";
 import {
   analyzeTaxEquivalent, distributionBasis, loadTreasuryTenors, parseTaxRates, TAX_RATE_HELP_OPTIONS, taxEquivalentJson, type TaxRates,
 } from "../../market-data/tax-equivalent";
@@ -913,7 +917,7 @@ function corporateActionRows(data: CorporateActionsData) {
     ...declaredDividends(data).map((event) => ({
       type: "dividend",
       date: event.exDate,
-      detail: `declared ${currency ? formatDistributionAmount(event.amount, currency) : cleanDecimal(event.amount)}`
+      detail: `declared ${event.special ? "special " : ""}${currency ? formatDistributionAmount(event.amount, currency) : cleanDecimal(event.amount)}`
         + (event.payDate ? `, payable ${event.payDate}` : ""),
     })),
     ...data.splits.map((event) => ({
@@ -1105,8 +1109,10 @@ async function runQuote(rawArgs: string[], ctx: Parameters<CliCommandDef["execut
         const quiet = ended ? null : noPrintsTodayText(row.quote, now);
         return [ended ?? (quiet ? `${label}: ${quiet}` : []), quoteBarNotes(label, row.quote, now)].flat();
       }),
-      // A receipt and its home line each say the ratio, as `ticker` does.
+      // A receipt and its home line each say the ratio, as `ticker` does; a CEDEAR names itself in its own.
       ...data.flatMap((row) => {
+        const cedear = listingCedearRatio({ quote: row.quote });
+        if (cedear) return [`${cedearRatioText(cedear)}.`];
         const pair = listingDepositaryPair({ quote: row.quote });
         return pair ? [`${row.target.symbol}: ${depositaryPairText(pair, isReceiptSide({ quote: row.quote }))}.`] : [];
       }),
@@ -1932,26 +1938,29 @@ const NEWS_COLUMNS = [
 async function printNewsSearch(
   text: string,
   articles: NewsArticle[],
-  { reason, empty, commodity = true, failure, ticker = null }: {
+  { reason, empty, commodity = true, failure, ticker = null, closest = false }: {
     reason?: string;
     empty?: string;
     commodity?: boolean;
     failure?: string;
     /** The listing a coin pair's search stands in for. */
     ticker?: string | null;
+    /** No story has every word: these are the ones with the most. */
+    closest?: boolean;
   },
   ctx: Parameters<CliCommandDef["execute"]>[1],
 ) {
   const searched = failure === undefined;
   const named = searched && commodity && articles.length === 0 && commodityNamedIn(text) !== null;
   const route = named ? await commodityNewsRoute(text) : null;
+  const closestReason = closest && articles.length > 0 ? closestStoriesReason(text) : null;
   ctx.printResult({
     data: articles,
     ...(searched ? {} : { warnings: [`Searching stories for "${text}" failed: ${failure}`] }),
-    metadata: { ticker, search: text, feed: null, ...(route ? { futuresNews: route.command } : {}) },
+    metadata: { ticker, search: text, feed: null, ...(closestReason ? { match: "closest" } : {}), ...(route ? { futuresNews: route.command } : {}) },
     freshness: rowsFreshness(newsRows(articles), cloudNewsFreshness(await cloudRealtimeAccess())),
   }, {
-    heading: newsSearchHeading(text, reason),
+    heading: newsSearchHeading(text, [reason, closestReason].filter(Boolean).join("  ·  ") || undefined),
     rows: newsRows,
     columns: NEWS_COLUMNS,
     empty: named ? noStoriesMessage(text, route) : empty ?? (searched ? noStoriesMessage(text, null) : "No stories to show."),
@@ -2013,7 +2022,8 @@ async function runNews(rawArgs: string[], ctx: Parameters<CliCommandDef["execute
     if (exchangeOption || feed) ctx.fail(`${exchangeOption ? "--exchange" : "--feed"} goes with a symbol, not with text to search stories for.`, "Usage: gloom news <query>");
     const problem = newsSearchTextProblem(text);
     if (problem) ctx.fail(problem);
-    await printNewsSearch(text, await searchNewsStories(text, limit), {}, ctx);
+    const answer = await searchClosestNewsStories(text, limit);
+    await printNewsSearch(text, answer.found, { closest: answer.closest }, ctx);
     return;
   }
   // A metal's future or name is its market's news, not a company's: GOLD in capitals stays Gold.com's.
@@ -2193,7 +2203,7 @@ async function runFilings(rawArgs: string[], ctx: Parameters<CliCommandDef["exec
           ...listingMetadata(resolved), ...(form ? { form } : {}),
           ...(page ? { announcementsPage: page.url } : {}),
         },
-        freshness: rowsFreshness(filingRows(filings), { ...SEC_FILINGS, observedKey: "filingDate" }),
+        freshness: rowsFreshness(filingRows(filings), SEC_FILING_ROWS),
         ...(choice.length > 0 ? { warnings: choice } : {}),
       }, {
         heading: listingHeading(resolved),
@@ -2205,7 +2215,7 @@ async function runFilings(rawArgs: string[], ctx: Parameters<CliCommandDef["exec
         empty: [form ? `No ${form} filings found for ${listingTitle(resolved)}.`
           : identity ? noSecReportsNotice(resolved)
           : `No SEC filings found for ${listingTitle(resolved)}.`, pageLine].filter(Boolean).join("\n"),
-        ...(pageLine ? { footnote: pageLine, exportNotes: [pageLine] } : {}),
+        ...filingsFootnote(pageLine, filings[0]?.companyFrom),
       });
     } catch (error) {
       if (!(error instanceof SecRegistrantMismatchError)) throw error;
@@ -2223,6 +2233,16 @@ async function runFilings(rawArgs: string[], ctx: Parameters<CliCommandDef["exec
   });
 }
 
+/**
+ * The lines `filings` prints under its rows and CSV writes as notes: an ASX
+ * listing's announcements page, and whose filings a foreign line shows when
+ * they are its company's home line's.
+ */
+function filingsFootnote(pageLine: string | null | undefined, companyFrom: CompanyFrom | undefined): { footnote?: string; exportNotes?: string[] } {
+  const lines = [...(pageLine ? [pageLine] : []), ...companyDataNotes(companyFrom)];
+  return lines.length ? { footnote: lines.join("\n"), exportNotes: lines } : {};
+}
+
 /**
  * `filings` for a company on ASX that files nothing with the SEC: its latest
  * ASX announcements from Gloom Cloud, newest first, under the line saying it
@@ -2393,7 +2413,8 @@ async function printBeneficialOwners(
     heading: `${listingHeading(identity)}${cliStyles.muted(beneficialListFacts(payload, form, rows.length, history).map((fact) => `  ·  ${fact}`).join(""))}`,
     // Text draws each column as the HDS report does; CSV and JSON keep the raw values.
     textColumns: BENEFICIAL_REPORT_COLUMNS.map((column) => ({ ...column, format: column.textFormat ?? column.format })),
-    ...(legend ? { footnote: legend } : {}),
+    // A foreign line's owners read from its company's home line say whose.
+    ...(legend || payload.companyFrom ? { footnote: [legend, ...companyDataNotes(payload.companyFrom)].filter(Boolean).join("\n") } : {}),
     columns: [
       ...BENEFICIAL_REPORT_COLUMNS.map(({ key, header, align }) => ({ key, header, ...(align ? { align } : {}) })),
       { key: "otherPersons", header: "Other persons" },
@@ -2494,7 +2515,7 @@ async function runHolders(
     const columns = holderReportColumns(shownRows, valueCurrency);
     // Dated as HDS dates it: by the list's as-of; an insider report of Form 4 filings alone as INS dates it, by the newest.
     const freshness = form4Only
-      ? rowsFreshness(form4?.newestFiled ? [{ filingDate: form4.newestFiled }] : [], { ...SEC_FILINGS, basis: "Form 4 filings", observedKey: "filingDate" })
+      ? rowsFreshness(form4?.newestFiled ? [{ filingDate: form4.newestFiled }] : [], { ...SEC_FILING_ROWS, basis: "Form 4 filings" })
       : rowsFreshness(shownRows, { ...SEC_FILINGS, basis: "13F filings" }, { asOf: data.asOf ?? null });
     // Named as fn HDS takes it, so the closing notes point to the same listing.
     const requested = exchangeOption && !raw.includes(":") ? `${raw}:${exchangeOption.toUpperCase()}` : raw;
@@ -2564,6 +2585,8 @@ async function runHolders(
         insiderCommand ? insiderSummary(data, listing, identity, form4) : "",
       ].filter(Boolean).join("\n"),
       empty: `No holders reported for ${listingTitle(identity)}.`,
+      // Holders read from the company's home line say whose; the SEC index's are the listing's own.
+      ...(!indexed && data.companyFrom ? { footnote: companyDataNotes(data.companyFrom).join("\n") } : {}),
     });
   });
 }

package/src/cli/commands/news-search.ts

@@ -82,6 +82,28 @@ export async function searchNewsStories(text: string, limit: number, topics?: re
   return response.items.map((item) => mapCloudNewsArticle(item));
 }
 
+/** A search's stories, and whether they are its closest ones because no story has every word. */
+export interface NewsSearchAnswer {
+  found: NewsArticle[];
+  closest: boolean;
+}
+
+/**
+ * The stories matching the text; when no story has every word of a search of
+ * several, the ones with the most of them, most words first. Spellings of
+ * one word are one word to the service: lockup, lock-up and lock up;
+ * spinoff and spin-off; expiry and expiration.
+ */
+export async function searchClosestNewsStories(text: string, limit: number): Promise<NewsSearchAnswer> {
+  const response = await apiClient.searchCloudNews(text, limit, undefined, { closest: true });
+  return { found: response.items.map((item) => mapCloudNewsArticle(item)), closest: response.match === "closest" };
+}
+
+/** What the heading says of a search no story has every word of. */
+export function closestStoriesReason(text: string): string {
+  return `no story has every word of "${text}"; the closest, most words first`;
+}
+
 /** The NI code of the metal markets: prices, futures, bullion and the trusts that hold it, not a miner's releases. */
 export const METALS_NEWS_TOPIC = "metals";