gloomberb 0.18.3 → 0.18.4

package/src/theme/ui-tokens.ts

@@ -53,11 +53,16 @@ function surfaceSunkenColour(palette: Palette): string {
   return palette.bg;
 }
 
+/** A row or control under the pointer: halfway from the background to the selection. */
+export function hoverColour(palette: Palette): string {
+  return blendHex(palette.bg, palette.selected, 0.5);
+}
+
 /**
  * The colour roles the palette names indirectly, as `--gloom-*` variables:
  * styles.css and inline styles read these, never a blend of their own.
  */
-export function roleColours(palette: Palette): Array<[string, string]> {
+function roleColours(palette: Palette): Array<[string, string]> {
   return [
     ["--gloom-surface-raised", surfaceRaisedColour(palette)],
     ["--gloom-surface-sunken", surfaceSunkenColour(palette)],
@@ -69,3 +74,34 @@ export function roleColours(palette: Palette): Array<[string, string]> {
     ["--gloom-locked", palette.textDim],
   ];
 }
+
+/** The palette entries styles.css reads as they are. */
+const PALETTE_VARIABLES: Array<[keyof Palette, string]> = [
+  ["bg", "--gloom-bg"],
+  ["panel", "--gloom-panel"],
+  ["border", "--gloom-border"],
+  ["borderFocused", "--gloom-border-focused"],
+  ["text", "--gloom-text"],
+  ["textDim", "--gloom-text-dim"],
+  ["textBright", "--gloom-text-bright"],
+  ["textMuted", "--gloom-text-muted"],
+  ["positive", "--gloom-positive"],
+  ["negative", "--gloom-negative"],
+  ["neutral", "--gloom-neutral"],
+  ["warning", "--gloom-warning"],
+  ["header", "--gloom-header"],
+  ["headerText", "--gloom-header-text"],
+  ["selected", "--gloom-selected"],
+  ["selectedText", "--gloom-selected-text"],
+  ["commandBg", "--gloom-command-bg"],
+  ["commandBorder", "--gloom-command-border"],
+];
+
+/** Every custom property a theme sets on the document root, which the desktop and web stylesheet draws with. */
+export function themeCssVariables(palette: Palette): Array<[string, string]> {
+  return [
+    ...PALETTE_VARIABLES.map(([key, name]): [string, string] => [name, palette[key]]),
+    ["--gloom-hover-bg", hoverColour(palette)],
+    ...roleColours(palette),
+  ];
+}

package/src/tickers/company-name-listing.ts

@@ -2,11 +2,13 @@ import { logFailure } from "../utils/log-failure";
 import type { DataProvider } from "../types/data-provider";
 import type { InstrumentSearchResult } from "../types/instrument";
 import { canonicalExchange, isUsListingExchange, parsePublicTickerKey } from "../utils/exchanges";
-import { companyNameMatch, shortCompanyName } from "./company-name";
+import { companyNameMatch, sameCompany, shortCompanyName } from "./company-name";
 import { LISTING_SEARCH_LIMIT } from "./search";
-import { classifyInstrumentKind } from "./search/ranking";
+import { lineDistance } from "./search/home-listing";
+import { classifyInstrumentKind, isCryptoInstrumentType } from "./search/ranking";
 import { isProviderBusy, type ProviderBusyError } from "../sources/provider-errors";
-import { readTerminalListingCode, type TerminalListingCode } from "./terminal-codes";
+import { readTerminalListingCode, type TerminalListing, type TerminalListingCode } from "./terminal-codes";
+import { hasNonLatinLetters } from "../utils/typed-text";
 
 export interface CompanyNameListing {
   symbol: string;
@@ -14,6 +16,12 @@ export interface CompanyNameListing {
   exchange: string;
   /** The listing's name as search gives it. */
   name: string;
+  /**
+   * When the listing is a fund or an index carrying the name ("JP Morgan" read
+   * as ^JTEK, JP MORGAN ETF TRUS), the company's common stock the name says
+   * run together (JPM, JPMorgan Chase & Co.), which the reader is asked about.
+   */
+  meant?: Omit<CompanyNameListing, "meant">;
 }
 
 /** Share lines that are not the company's common stock, though search may type them as such. */
@@ -33,65 +41,234 @@ export function isCompanyNameInput(input: string): boolean {
  * is also searched without its legal form, which can find more), the company
  * whose name says no more than the one typed goes first, so a subsidiary that
  * shares the word (Whirlpool of India) does not, and of those a name matched
- * word for word before one a short form matched; then its line on a US
- * exchange, then a plain line before a depositary receipt, the shortest
- * symbol (WHR before WHR-A) and search's order. Contracts, preferred shares
- * and notes are never the listing. Null when none matches; when none does
- * because search was too busy to answer, `ProviderBusyError`.
+ * word for word before one a short form matched; then a company's shares
+ * (its stock or a receipt) before a fund or an index named alike; then its
+ * primary listing, the line the service marks as its home (SIE on XETRA for
+ * "SIEMENS AG"), before
+ * its other plain lines, those before a line that only quotes shares listed
+ * elsewhere (4SIE in Milan, OTC, a regional German venue) and those before a
+ * depositary receipt (SAP's NYSE line for "SAP SE"), so a receipt is the
+ * listing only of a company listed by receipts alone (PDD); then the row the
+ * service marks with the name, a US line, the shortest symbol (WHR before
+ * WHR-A) and search's order. The row the service marks with the name as typed
+ * (`searchAliases`: JPM for "JP Morgan", SIE for "SIEMENS AG", though its name
+ * is Siemens Aktiengesellschaft) is named by it exactly. Contracts, preferred
+ * shares and notes are never the listing. With `quoted`, a listing with no
+ * quote (a line search keeps for a venue that no longer prices it) gives way
+ * to the next of the same company's lines that has one, never to another
+ * company's home line; when none has, or the source is too busy to say, the
+ * first stands. With `meant`, a fund or an index found for a name its
+ * company's stock says run together ("JP Morgan" for JPMorgan Chase & Co.)
+ * names that stock as `meant`, searched under the run-together name when the
+ * answer lacks it. With `oneWord`, for a name typed as one word, which many
+ * listings' names have ("oil", "steel"): only search's top result, a row the
+ * service marks with the word, or a name that is the word and nothing more
+ * (Apple Inc. for "apple") is the listing, never a short form ("grp" for any
+ * Group) or a coin, whose name is the crypto board's. Null when none matches;
+ * when none does because search was too busy to answer, `ProviderBusyError`.
  */
 export async function findListingOfCompanyName(
-  dataProvider: Pick<DataProvider, "search">,
+  dataProvider: Pick<DataProvider, "search"> & Partial<Pick<DataProvider, "getQuote">>,
   typed: string,
+  options: { meant?: boolean; oneWord?: boolean; quoted?: boolean } = {},
 ): Promise<CompanyNameListing | null> {
   const name = typed.trim();
   if (!name) return null;
   const queries = [...new Set([name, shortCompanyName(name)])].filter(Boolean);
-  const answers = await Promise.all(queries.map((query) => dataProvider.search(query, { limit: LISTING_SEARCH_LIMIT })
-    .catch((error: unknown): InstrumentSearchResult[] | ProviderBusyError => {
-      if (isProviderBusy(error)) return error;
-      logFailure("tickers-company-name-listing", "Could not search company listings")(error);
-      return [];
-    })));
+  const answers = await Promise.all(queries.map((query) => searchListings(dataProvider, query)));
   const busy = answers.find(isProviderBusy);
   const results = answers.flatMap((answer) => Array.isArray(answer) ? answer : []);
   const ranked = results.flatMap((result, order) => {
-    const exchange = canonicalExchange(result.exchange === "SMART" ? result.primaryExchange : result.exchange || result.primaryExchange);
-    const type = result.brokerContract?.secType || result.type || "";
-    const match = companyNameMatch(name, result.name);
+    const exchange = listedExchange(result);
+    const type = listedType(result);
+    const named = namedByService(name, result);
+    const match = named ? { extra: 0, abbreviated: 0 } : companyNameMatch(name, result.name);
     if (!exchange || match == null || classifyInstrumentKind(type) === "derivative" || NOT_COMMON.test(type)
       || parsePublicTickerKey(result.symbol).exchange) return [];
-    return [{ result, exchange, rank: [match.extra, match.abbreviated, isUsListingExchange(exchange) ? 0 : 1, RECEIPT.test(type) ? 1 : 0, result.symbol.length, order] }];
+    if (options.oneWord && (match.abbreviated > 0 || isCryptoInstrumentType(type) || !(order === 0 || named || match.extra === 0))) return [];
+    // A receipt is a company's shares too, however search types it ("Depositary Receipt" or "American Depositary Receipt").
+    const stock = classifyInstrumentKind(type) === "equity" || RECEIPT.test(type) ? 0 : 1;
+    const home = result.homeListing === true;
+    const line = home ? 0 : 1 + lineDistance(type, exchange, result.symbol);
+    return [{
+      result, exchange, stock, home,
+      rank: [match.extra, match.abbreviated, stock, line, named ? 0 : 1, isUsListingExchange(exchange) ? 0 : 1, result.symbol.length, order],
+    }];
   }).sort((left, right) => {
     const at = left.rank.findIndex((value, index) => value !== right.rank[index]);
     return at < 0 ? 0 : left.rank[at]! - right.rank[at]!;
   });
-  const best = ranked[0];
-  if (!best && busy) throw busy;
-  return best ? { symbol: best.result.symbol.toUpperCase(), exchange: best.exchange, name: best.result.name } : null;
+  const first = ranked[0];
+  // Listings are named in Latin letters: a name in another script ("任天堂 ソニー") names none, answered or not.
+  if (!first && busy && !hasNonLatinLetters(name)) throw busy;
+  if (!first) return null;
+  // The first may give way to its company's other lines: as near the name and of its kind. Another line the
+  // service marks as a home is another company's (Siemens Ltd. on NSE, for "SIEMENS AG"), and so is a line
+  // named as that one is (Siemens Ltd. on BSE).
+  const otherHomes = new Set(ranked.filter((listing) => listing.home && listing !== first).map(({ result }) => plainName(result.name)));
+  otherHomes.delete(plainName(first.result.name));
+  const lines = ranked.filter((listing) => listing === first || (!listing.home && !otherHomes.has(plainName(listing.result.name))
+    && sameCompany(first.result.name, listing.result.name)
+    && listing.rank.slice(0, NAME_RANKS).every((value, index) => value === first.rank[index])));
+  const best = options.quoted ? await firstQuoted(dataProvider, lines) : first;
+  const found = { symbol: best.result.symbol.toUpperCase(), exchange: best.exchange, name: best.result.name };
+  const meant = best.stock && options.meant ? await stockNamedRunTogether(dataProvider, name, results) : null;
+  return meant ? { ...found, meant } : found;
+}
+
+/** The ranks that say how near a listing's name is to the one typed, and whether it is a stock: one company's lines share them. */
+const NAME_RANKS = 3;
+
+/** Lines past the first a name's listing is asked a quote for, at once, when the first has none. */
+const QUOTE_FALLBACKS = 4;
+
+interface RankedListing {
+  result: InstrumentSearchResult;
+  exchange: string;
+}
+
+/**
+ * The first of a company's lines, in their order, that has a quote: the first
+ * itself, or when it has none, the first of the next few that does, asked
+ * together. The first stands when none has a quote, when the source is too
+ * busy to say, and when nothing here can ask for quotes.
+ */
+async function firstQuoted<T extends RankedListing>(dataProvider: Partial<Pick<DataProvider, "getQuote">>, lines: readonly T[]): Promise<T> {
+  const first = lines[0]!;
+  if (!dataProvider.getQuote) return first;
+  const quoted = ({ result, exchange }: RankedListing) => dataProvider.getQuote!(result.symbol.toUpperCase(), exchange).then(hasPrice);
+  try {
+    if (await quoted(first)) return first;
+  } catch (error) {
+    // A busy source says nothing of the listing; any other failure is a listing with no quote.
+    if (isProviderBusy(error)) return first;
+  }
+  const keys = new Set([listingKey(first)]);
+  const next: T[] = [];
+  for (const line of lines) {
+    if (next.length === QUOTE_FALLBACKS) break;
+    if (keys.has(listingKey(line))) continue;
+    keys.add(listingKey(line));
+    next.push(line);
+  }
+  const priced = await Promise.all(next.map((line) => quoted(line).catch(() => {
+    // Intentional ignore: a line whose quote fails is a line with no quote.
+    return false;
+  })));
+  return next.find((_, index) => priced[index]) ?? first;
+}
+
+/** A name as two venues may spell it alike: "SIEMENS LTD" for Siemens Ltd. */
+function plainName(name: string | null | undefined): string {
+  return (name ?? "").normalize("NFKD").replace(/\p{M}/gu, "").toUpperCase().replace(/[^\p{L}\p{N}]+/gu, " ").trim();
+}
+
+function listingKey({ result, exchange }: RankedListing): string {
+  return `${result.symbol.toUpperCase()}:${exchange}`;
+}
+
+function hasPrice(quote: { price?: number } | null | undefined): boolean {
+  return !!quote && Number.isFinite(quote.price) && quote.price !== 0;
+}
+
+function searchListings(dataProvider: Pick<DataProvider, "search">, query: string): Promise<InstrumentSearchResult[] | ProviderBusyError> {
+  return dataProvider.search(query, { limit: LISTING_SEARCH_LIMIT })
+    .catch((error: unknown): InstrumentSearchResult[] | ProviderBusyError => {
+      if (isProviderBusy(error)) return error;
+      logFailure("tickers-company-name-listing", "Could not search company listings")(error);
+      return [];
+    });
+}
+
+function listedExchange(result: InstrumentSearchResult): string {
+  return canonicalExchange(result.exchange === "SMART" ? result.primaryExchange : result.exchange || result.primaryExchange);
+}
+
+function listedType(result: InstrumentSearchResult): string {
+  return result.brokerContract?.secType || result.type || "";
+}
+
+/** Letters and digits only, in capitals: "JP Morgan" and "JPMorgan" are JPMORGAN. */
+function runTogether(text: string): string {
+  return text.normalize("NFKD").replace(/\p{M}/gu, "").toUpperCase().replace(/[^\p{L}\p{N}]/gu, "");
+}
+
+/** Whether the service marked the row with the name as typed: the company it means by it. */
+export function namedByService(typed: string, result: InstrumentSearchResult): boolean {
+  const wanted = runTogether(typed);
+  return !!wanted && Array.isArray(result.searchAliases)
+    && result.searchAliases.some((alias) => typeof alias === "string" && runTogether(alias) === wanted);
+}
+
+/**
+ * The company's common stock on a US exchange whose name starts with the
+ * typed words run together ("JPMorgan Chase & Co." for "JP Morgan"), first in
+ * search's order; the answer at hand is searched first, then the run-together
+ * name itself. Null when none is, or when a single word was typed.
+ */
+async function stockNamedRunTogether(
+  dataProvider: Pick<DataProvider, "search">,
+  typed: string,
+  results: readonly InstrumentSearchResult[],
+): Promise<Omit<CompanyNameListing, "meant"> | null> {
+  const wanted = runTogether(typed);
+  if (wanted.length < 4 || !/\s/.test(typed.trim())) return null;
+  const stockOf = (rows: readonly InstrumentSearchResult[]) => rows.find((result) => {
+    const type = listedType(result);
+    return classifyInstrumentKind(type) === "equity" && !NOT_COMMON.test(type) && !RECEIPT.test(type)
+      && isUsListingExchange(listedExchange(result)) && !parsePublicTickerKey(result.symbol).exchange
+      && (runTogether(result.name).startsWith(wanted) || namedByService(typed, result));
+  });
+  let stock = stockOf(results);
+  if (!stock) {
+    const answer = await searchListings(dataProvider, typed.trim().replace(/\s+/g, ""));
+    stock = Array.isArray(answer) ? stockOf(answer) : undefined;
+  }
+  return stock ? { symbol: stock.symbol.toUpperCase(), exchange: listedExchange(stock), name: stock.name } : null;
 }
 
 /** `BRK.B`, `BRK-B` and `BRK/B` alike. */
 const shareClassSymbol = (symbol: string) => symbol.trim().toUpperCase().replace(/[-/]/g, ".");
 
 /**
- * A terminal's code for a US listing typed where a symbol goes, when it is
- * one. A Reuters code (WFC.N) always is. A Bloomberg code is words, which a
- * fund's name can be too ("Putnam US Equity", "Global US Equity"), so it is
- * one only when search lists its root as a US ticker (JPM, in any case);
- * otherwise it is the name it reads as, and is searched as one. A search that
- * fails says nothing either way, and the code stands. Null for anything else.
+ * A terminal's code typed where a symbol goes, when it is one, on the listing
+ * search knows it by. A Reuters code (WFC.N), an index, a currency and a
+ * future always are. A Bloomberg equity code is words, which a fund's name can
+ * be too ("Putnam US Equity", "Global US Equity"), so one for the US, or typed
+ * in lower case, is one only when search lists its root there (JPM on a US
+ * exchange, VOD on LSE); otherwise it is the name it reads as, and is searched
+ * as one. One in capitals naming a venue abroad (`MC FP`) is one as typed: the
+ * venue's own check speaks when the symbol is not there. A code that can name
+ * several listings (`VOLVB SS` is VOLVB or VOLV.B in Stockholm, `RY CN`
+ * Toronto or the Venture exchange) is the first of them search lists. A
+ * search that fails says nothing either way, and the code stands. Null for
+ * anything else.
  */
 export async function readTerminalCodeArg(
   dataProvider: Pick<DataProvider, "search">,
   typed: string,
 ): Promise<TerminalListingCode | null> {
   const code = readTerminalListingCode(typed);
-  if (!code || code.terminal !== "bloomberg") return code;
+  if (!code?.market) return code;
+  const us = !code.exchange || isUsListingExchange(code.exchange);
+  const verify = us || /\p{Ll}/u.test(code.typed.split(" ")[0]!);
+  if (!verify && !code.alternatives) return code;
+  const listings: TerminalListing[] = [code, ...code.alternatives ?? []];
   try {
-    const results = await dataProvider.search(code.symbol, { limit: LISTING_SEARCH_LIMIT });
-    return results.some((result) => shareClassSymbol(result.symbol) === code.symbol
-      && isUsListingExchange(result.exchange === "SMART" ? result.primaryExchange : result.exchange || result.primaryExchange))
-      ? code : null;
+    const searched = new Set<string>();
+    for (const { symbol } of listings) {
+      if (searched.has(shareClassSymbol(symbol))) continue;
+      searched.add(shareClassSymbol(symbol));
+      const results = await dataProvider.search(symbol, { limit: LISTING_SEARCH_LIMIT });
+      for (const listing of listings) {
+        const listed = results.find((result) => shareClassSymbol(result.symbol) === shareClassSymbol(listing.symbol)
+          && (us ? isUsListingExchange(listedExchange(result)) : listedExchange(result) === listing.exchange));
+        // Abroad, the listing goes by search's own spelling of it, as the venue lists it.
+        const symbol = listed && !us ? listed.symbol.toUpperCase() : listing.symbol;
+        if (listed) return { ...code, symbol, exchange: listing.exchange, key: listing.exchange ? `${symbol}:${listing.exchange}` : symbol };
+      }
+    }
+    return verify ? null : code;
   } catch (error) {
     if (!isProviderBusy(error)) logFailure("tickers-company-name-listing", "Could not search a terminal code's root")(error);
     return code;

package/src/tickers/index-roots.ts

@@ -0,0 +1,47 @@
+/**
+ * Well-known index roots that people type bare. As a bare symbol each one is
+ * another instrument (MOVE is Corvex, MID a fund) or nothing at all (VIX); the
+ * index itself is quoted as ^ROOT. Every entry is offered as a command to run,
+ * so only roots whose ^ symbol returns a quote belong here.
+ */
+const INDEX_ROOTS = new Map([
+  ["VIX", "Cboe Volatility Index"],
+  ["VVIX", "Cboe VIX of VIX Index"],
+  ["VIX9D", "Cboe S&P 500 9-Day Volatility Index"],
+  ["VIX3M", "Cboe S&P 500 3-Month Volatility Index"],
+  ["VXN", "Cboe Nasdaq-100 Volatility Index"],
+  ["OVX", "Cboe Crude Oil ETF Volatility Index"],
+  ["GVZ", "Cboe Gold ETF Volatility Index"],
+  ["SKEW", "Cboe SKEW Index"],
+  ["TNX", "Cboe 10-Year Treasury Yield Index"],
+  ["SPX", "S&P 500 Index"],
+  ["OEX", "S&P 100 Index"],
+  ["MID", "S&P MidCap 400 Index"],
+  ["DJI", "Dow Jones Industrial Average"],
+  ["NDX", "Nasdaq-100 Index"],
+  ["SOX", "PHLX Semiconductor Index"],
+  ["RUT", "Russell 2000 Index"],
+  ["RUI", "Russell 1000 Index"],
+  ["RUA", "Russell 3000 Index"],
+  ["MOVE", "ICE BofA MOVE Index"],
+  ["NYA", "NYSE Composite Index"],
+]);
+
+export interface IndexRoot {
+  /** The index's own symbol: ^VIX. */
+  symbol: string;
+  name: string;
+}
+
+/** The index a bare root names (VIX is ^VIX); null for any other symbol, ^VIX included. */
+export function indexRootFor(symbol: string): IndexRoot | null {
+  const root = symbol.trim().toUpperCase();
+  const name = INDEX_ROOTS.get(root);
+  return name ? { symbol: `^${root}`, name } : null;
+}
+
+/** "Did you mean ^VIX (Cboe Volatility Index)?" after a bare root that is not a ticker; null for any other symbol. */
+export function indexRootSuggestion(symbol: string): string | null {
+  const root = indexRootFor(symbol);
+  return root ? `Did you mean ${root.symbol} (${root.name})?` : null;
+}

package/src/tickers/instrument-label.ts

@@ -1,4 +1,5 @@
 import type { BrokerContractRef } from "../types/instrument";
+import { deliveryMonthLabel } from "../utils/contract-month";
 
 /** Identifying contract terms belong in the existing title, never in a new toolbar. */
 export function tickerInstrumentLabel(symbol: string, contract?: BrokerContractRef | null): string {
@@ -6,6 +7,9 @@ export function tickerInstrumentLabel(symbol: string, contract?: BrokerContractR
   const label = contract.localSymbol || symbol;
   // Brokers report strike 0 (and no expiry) on stocks; only a real strike identifies a derivative.
   const strike = typeof contract.strike === "number" && Number.isFinite(contract.strike) && contract.strike > 0 ? String(contract.strike) : undefined;
-  const terms = [contract.lastTradeDateOrContractMonth, contract.right, strike].filter(Boolean);
+  // A future's month (IBKR's "202612") reads as every contract month does, "Dec 2026"; a dated expiry stays as the broker writes it.
+  const month = contract.secType === "FUT" && /^\d{6}$/.test(contract.lastTradeDateOrContractMonth ?? "")
+    ? deliveryMonthLabel(contract.lastTradeDateOrContractMonth) : null;
+  const terms = [month ?? contract.lastTradeDateOrContractMonth, contract.right, strike].filter(Boolean);
   return terms.length ? [label, ...terms].join(" ") : label;
 }

package/src/tickers/metadata.ts

@@ -60,5 +60,15 @@ export function hydrateTickerMetadata(data: Record<string, unknown>): TickerMeta
     broker_contracts: Array.isArray(data.broker_contracts) ? [...data.broker_contracts] : [],
     custom: data.custom && typeof data.custom === "object" ? { ...(data.custom as Record<string, unknown>) } : {},
     tags: Array.isArray(data.tags) ? [...data.tags] : [],
+    ...hydrateMergedLots(data.mergedLots),
   };
 }
+
+/** The merged-lots record, kept only as a map of keys to lists of strings. */
+function hydrateMergedLots(raw: unknown): Pick<TickerMetadata, "mergedLots"> {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return {};
+  const entries = Object.entries(raw as Record<string, unknown>)
+    .filter((entry): entry is [string, string[]] => Array.isArray(entry[1]) && entry[1].every((lot) => typeof lot === "string"))
+    .map(([key, lots]): [string, string[]] => [key, [...lots]]);
+  return entries.length > 0 ? { mergedLots: Object.fromEntries(entries) } : {};
+}

package/src/tickers/perpetual-listing.ts

@@ -37,6 +37,9 @@ export const PERPETUAL_TYPE = "PERP";
 /** Exchange codes of the perpetual venues, which trade around the clock. */
 export const PERPETUAL_EXCHANGES: readonly string[] = Object.keys(VENUE_BY_EXCHANGE);
 
+/** Venues with no spot market, where a coin pair names a contract. */
+const PERPETUALS_ONLY: ReadonlySet<string> = new Set(["hyperliquid", "dydx"]);
+
 /** A venue symbol: letters (any script), digits, dash, underscore and dot; no colon or space. */
 const VENUE_SYMBOL = /^[\p{L}\p{N}_.-]{1,64}$/u;
 
@@ -96,8 +99,8 @@ export function perpetualListing(symbol: string, exchange?: string | null): Perp
   const venue = VENUE_BY_EXCHANGE[venueCode];
   if (!venue || !VENUE_SYMBOL.test(parsed.symbol) || parsed.symbol.startsWith("-")) return null;
   // A coin pair (BTC-USD, as BTC/USD on Binance is read) is the venue's spot market; contracts there have no dash
-  // before their quote currency. Hyperliquid's dash is its dex.
-  if (venue !== "hyperliquid" && isCryptoPairSymbol(parsed.symbol)) return null;
+  // before their quote currency. Hyperliquid's dash is its dex, and dYdX trades only perpetuals, each named as a pair.
+  if (!PERPETUALS_ONLY.has(venue) && isCryptoPairSymbol(parsed.symbol)) return null;
   const marketId = venue === "hyperliquid"
     ? (() => {
       const dash = parsed.symbol.indexOf("-");

package/src/tickers/search/home-listing.ts

@@ -0,0 +1,75 @@
+import { canonicalExchange } from "../../utils/exchanges";
+import { companyNameExtraWords, sameCompany } from "../company-name";
+import { answersOnlyByKeyword, isQualifiedTickerQuery } from "./ranking";
+import type { TickerSearchCandidate } from "./types";
+
+/** 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", "XMUN", "XSTU", "XDUS", "XBER", "XHAM", "HANOVER", "XHAN"]);
+const RECEIPT_TYPE = /depositary|^(?:ADR|ADS|GDR|CDR|BDR)$/i;
+
+/** The venue a row lists on; broker routing (SMART) names its primary exchange. */
+export function candidateExchange(candidate: TickerSearchCandidate): string {
+  return canonicalExchange(candidate.result?.exchange === "SMART"
+    ? candidate.result.primaryExchange
+    : candidate.result?.exchange || candidate.result?.primaryExchange || candidate.ticker?.metadata.exchange || candidate.right);
+}
+
+/**
+ * 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.
+ */
+export function listingDistance(candidate: TickerSearchCandidate): 0 | 1 | 2 {
+  return lineDistance(candidate.instrumentType ?? "", candidateExchange(candidate), candidate.symbol);
+}
+
+/** `listingDistance` of a line by its type, its canonical venue and its symbol. */
+export function lineDistance(type: string, exchange: string, symbol: string): 0 | 1 | 2 {
+  if (RECEIPT_TYPE.test(type)) return 2;
+  return SECONDARY_VENUES.has(exchange) || /\d/.test(symbol) && /[A-Za-z]/.test(symbol) ? 1 : 0;
+}
+
+function candidateName(candidate: TickerSearchCandidate): string {
+  return candidate.result?.name || candidate.detail.split(" | ")[0] || "";
+}
+
+/** How many words two names of one company differ by: Sony Group Corp. is nearer Sony Group ADR than Sony Financial Group. */
+function nameGap(left: string, right: string): number {
+  return companyNameExtraWords(left, right) ?? companyNameExtraWords(right, left) ?? Number.MAX_SAFE_INTEGER;
+}
+
+function isListedEquity(candidate: TickerSearchCandidate): boolean {
+  return candidate.kind === "search" && !candidate.saved
+    && (candidate.instrumentClass === "equity" || candidate.instrumentClass === "other");
+}
+
+/**
+ * The company search lists first is listed under its home line, its common
+ * stock on its home exchange, ahead of its depositary receipts: "Sony" and
+ * "LVMH" match receipts' tickers (SONY in New York, LVMH in Toronto), and a
+ * provider can file Toyota's NYSE receipt before Tokyo's 7203. The line the
+ * service marks as the company's home (`homeListing`) takes the lead from
+ * the company's first row. Without that mark, a receipt in the lead gives
+ * way to the company's own shares on an exchange (`listingDistance` 0, not
+ * an OTC or regional line), the name nearest the receipt's first. A query that names a venue (LVMH:TSX,
+ * 7203.T) asked for that line, and a saved row keeps the lead.
+ */
+export function withHomeListingLead<T extends TickerSearchCandidate>(items: T[], query: string): T[] {
+  if (isQualifiedTickerQuery(query)) return items;
+  const lead = items.find((item) => item.instrumentClass !== "fund" && item.instrumentClass !== "derivative"
+    && !answersOnlyByKeyword(item, query));
+  if (!lead || !isListedEquity(lead)) return items;
+  const name = candidateName(lead);
+  const lines = items.filter((item) => item !== lead && isListedEquity(item) && sameCompany(name, candidateName(item)));
+  const nearest = (candidates: T[]) => [...candidates].sort((a, b) => nameGap(name, candidateName(a)) - nameGap(name, candidateName(b))
+    || items.indexOf(a) - items.indexOf(b))[0];
+  const marked = lines.filter((item) => item.result?.homeListing === true);
+  const home = lead.result?.homeListing === true ? undefined
+    : marked.length ? nearest(marked)
+    : listingDistance(lead) === 2 ? nearest(lines.filter((item) => listingDistance(item) === 0))
+    : undefined;
+  if (!home) return items;
+  const rest = items.filter((item) => item !== home);
+  const at = rest.indexOf(lead);
+  return [...rest.slice(0, at), home, ...rest.slice(at)];
+}