@gloom-sh/terminal 0.19.0 → 0.19.1

package/src/plugins/builtin/research/index.tsx

@@ -6,6 +6,8 @@ import { CorporateActionsView } from "./corporate-actions-pane";
 import { EquityDiagnosticView } from "./equity-diagnostic-pane";
 import { RelativeValuationPane } from "./relative-valuation-pane";
 import { relativeValuationHeadless } from "./relative-valuation-headless";
+import { AUTO_PEERS_SETTING, relativeValuationTitle } from "./relative-valuation-peers";
+import { buildRelativeValuationSettingsDef, MAX_RELATIVE_VALUATION_TICKERS } from "./relative-valuation-settings";
 import { analystResearchHeadless } from "./analyst-headless";
 import { eventsHeadless } from "./events-headless";
 import { earningsEstimatesHeadless } from "./headless";
@@ -95,6 +97,7 @@ export const researchModule: PluginModule = {
       defaultMode: "floating",
       defaultFloatingSize: { width: 104, height: 24 },
       tableExport: true,
+      settings: buildRelativeValuationSettingsDef,
     },
     {
       id: "earnings-estimates",
@@ -168,14 +171,15 @@ export const researchModule: PluginModule = {
         try {
           symbols = options?.symbols?.length
             ? options.symbols
-            : parseTickerListInput(options?.arg ?? context.activeTicker ?? "", 12);
+            : parseTickerListInput(options?.arg ?? context.activeTicker ?? "", MAX_RELATIVE_VALUATION_TICKERS);
         } catch {
           return null;
         }
         return {
-          title: `RV ${formatTickerListInput(symbols)}`,
+          title: relativeValuationTitle(symbols, null),
           placement: "floating",
-          settings: { symbols, symbolsText: formatTickerListInput(symbols) },
+          // One ticker is compared with the peers `--peers` picks, which the pane finds once it opens.
+          settings: { symbols, symbolsText: formatTickerListInput(symbols), ...(symbols.length === 1 ? { [AUTO_PEERS_SETTING]: true } : {}) },
         };
       },
     },

package/src/plugins/builtin/research/relative-valuation-headless.ts

@@ -8,11 +8,10 @@ import {
   RELATIVE_VALUATION_STALE_FUNDAMENTALS_NOTICE, RELATIVE_VALUATION_STALE_QUOTE_NOTICE, relativeValuationValues, type RelativeValuationGapKey,
 } from "./relative-valuation-model";
 import { paneSchemas } from "./headless-schema";
-import { isRecord } from "../../../utils/guards";
-import { errorMessage } from "../../../utils/errors";
-import { notATickerSymbol } from "../../../sources/provider-errors";
 import { resolveCurrencyUnit } from "../../../utils/currency-units";
-import { pickPeers, peerMethodTitle, type PeerSelection } from "./relative-valuation-peers";
+import {
+  AUTO_PEERS_SETTING, findPeers, peerMethodTitle, peerSelectionOf, PEER_SELECTION_SETTING, relativeValuationTitle, type PeerSelection,
+} from "./relative-valuation-peers";
 import { extraColumns, extraColumnsBasis, loadExtraColumns, parseExtraColumns } from "./relative-valuation-columns";
 import { fundamentalsBasisParts } from "./relative-valuation-basis";
 import { conversionNote, convertMarketCaps, loadFxLegs } from "./relative-valuation-currency";
@@ -103,33 +102,14 @@ const VALUATION_COLUMNS: HeadlessPaneColumn[] = [
   })),
 ];
 
-/** Peers `--peers` chose, as the expansion left them in the settings or the load picked them. */
-function peerSelectionOf(value: unknown, symbols: readonly string[]): PeerSelection | null {
-  if (!isRecord(value) || typeof value.subject !== "string" || !Array.isArray(value.peers)) return null;
-  const selection = value as unknown as PeerSelection;
-  const expected = [selection.subject, ...selection.peers];
-  return expected.length === symbols.length && expected.every((symbol, index) => symbol.toUpperCase() === symbols[index]?.toUpperCase())
-    ? selection : null;
-}
-
 /** The peers of the one symbol `--peers` was given; several symbols are already a peer list. */
 async function choosePeers(symbols: readonly string[], ctx: HeadlessPaneContext): Promise<PeerSelection> {
   if (symbols.length !== 1) {
     throw new Error(`--peers picks the peers of one symbol, such as RV ${symbols[0] ?? "DUOL"} --peers; with several symbols, leave it out.`);
   }
-  const subject = symbols[0]!;
-  const financials = await loadHeadlessFinancials(ctx, subject).catch((error: unknown) => {
-    ctx.signal.throwIfAborted();
-    // A word that is no ticker is said as `fn RV duolingo lrn` says it, which the CLI follows with the search to run.
-    if (notATickerSymbol(errorMessage(error))) throw error;
-    // Any other failure leaves the peers to what the symbol alone places (a curated core's member).
-    return null;
-  });
-  return pickPeers(subject, financials, ctx);
+  return findPeers(symbols[0]!, ctx);
 }
 
-const PEER_SELECTION_SETTING = "peerSelection";
-
 export const relativeValuationHeadless: HeadlessPaneDefinition<"rows"> = {
   ...paneSchemas["relative-valuation-pane"],
   // What Ask Gloom reads. The template's "across peers" never said this is where a list of holdings' P/E is.
@@ -149,9 +129,12 @@ export const relativeValuationHeadless: HeadlessPaneDefinition<"rows"> = {
     return {
       argument: [selection.subject, ...selection.peers].join(", "),
       settings: { [PEER_SELECTION_SETTING]: selection },
-      title: `RV ${selection.subject} + ${peerMethodTitle(selection, { automatic: true })}`,
+      title: relativeValuationTitle([], selection),
     };
   },
+  // The app adds the peers of a pane opened on one ticker; a capture draws the tickers given, as the report does,
+  // unless --peers widened them.
+  shotState: (args) => args.options.peers === true ? {} : { settings: { [AUTO_PEERS_SETTING]: false } },
   async load(args, ctx) {
     // --peers picked in advance (fn and shot) reads the same peers; any other caller picks them here.
     const preset = args.options.peers === true ? peerSelectionOf(ctx.settings?.[PEER_SELECTION_SETTING], args.symbols) : null;

package/src/plugins/builtin/research/relative-valuation-pane.tsx

@@ -1,5 +1,5 @@
 import { formatPriceEarnings, NOT_MEANINGFUL } from "../../../utils/price-earnings";
-import { useCallback, useMemo, useState } from "react";
+import { useCallback, useEffect, useMemo, useState } from "react";
 import { TextAttributes } from "../../../ui";
 import {
   DataTableView,
@@ -11,7 +11,7 @@ import {
   type PaneFooterSegment,
 } from "../../../components";
 import type { PaneProps } from "../../../types/plugin";
-import { useAppSelector, usePaneInstance } from "../../../state/app/context";
+import { useAppSelector, usePaneInstance, usePaneTitle, useUpdatePaneSettings } from "../../../state/app/context";
 import { getSharedMarketDataCoordinator, resolveEntryValue } from "../../../market-data/coordinator";
 import { buildQuoteKey } from "../../../market-data/selectors";
 import { useLiveQuoteEntries } from "../../../state/hooks/quote-streaming";
@@ -25,7 +25,10 @@ import { compareSortValues, nextHeaderSort, type SortDirection } from "../../../
 import { formatCompact, formatLevelPercent, formatNumber, formatPercent, formatPercentRaw } from "../../../utils/format";
 import { parseDisplayDate } from "../../../utils/datetime-format";
 import { convertMarketCapitalization } from "../../../utils/market-capitalization";
-import { usePluginTickerActions } from "../../runtime";
+import { useAssetData, usePluginTickerActions } from "../../runtime";
+import { apiClient } from "../../../api-client";
+import { errorMessage } from "../../../utils/errors";
+import { formatTickerListInput } from "../../../tickers/list";
 import { handleRefreshKey, useClampSelectedIndex } from "../../../components/data-table/table-pane";
 import { useAsyncResource } from "../../../react/async-resource";
 import { useBoundTicker as useSymbolBinding } from "../shared/ticker-request";
@@ -35,6 +38,10 @@ import { quoteFreshnessFields } from "../shared/report-freshness";
 import { RELATIVE_VALUATION_STALE_FUNDAMENTALS_NOTICE, formatRelativePrice, relativeValuationValues, withLiveQuote } from "./relative-valuation-model";
 import { conversionNote, conversionPairText, convertMarketCaps, usdRateFromEntry } from "./relative-valuation-currency";
 import { fundamentalsBasisParts, fundamentalsThroughText } from "./relative-valuation-basis";
+import {
+  AUTO_PEERS_SETTING, findPeers, PEER_SELECTION_SETTING, PeerPickError, peerSelectionOf, relativeValuationTitle,
+} from "./relative-valuation-peers";
+import { relativeSymbolsFromPane } from "./relative-valuation-settings";
 
 type ExtendedColumnId = "preMarket" | "afterHours" | "overnight";
 type RelativeColumnId = "symbol" | "price" | "changePercent" | ExtendedColumnId | "marketCap" | "trailingPE" | "forwardPE" | "evSales" | "fcfYield" | "revenueGrowth" | "operatingMargin";
@@ -44,14 +51,6 @@ type RelativeRow = ReturnType<typeof relativeValuationValues> & {
   error?: string;
 };
 
-function relativeSymbolsFromPane(symbol: string | null, paneSettings: Record<string, unknown> | undefined): string[] {
-  const settingsSymbols = Array.isArray(paneSettings?.symbols)
-    ? paneSettings.symbols.filter((value): value is string => typeof value === "string")
-    : [];
-  if (settingsSymbols.length > 0) return settingsSymbols;
-  return symbol ? [symbol] : [];
-}
-
 const EXTENDED_COLUMN_IDS: Record<ExtendedSession, ExtendedColumnId> = { PRE: "preMarket", POST: "afterHours", OVERNIGHT: "overnight" };
 
 /** The latest quarter's revenue against the same quarter a year earlier; the footer names the quarter. */
@@ -151,6 +150,8 @@ function sortRelativeRowIndices(
     .map((entry) => entry.index);
 }
 
+const NO_SYMBOLS: string[] = [];
+
 /** Live values keep moving; the row order follows them at most this often. */
 const RELATIVE_ORDER_SAMPLE_MS = 5_000;
 
@@ -170,7 +171,37 @@ export function RelativeValuationPane({ focused, width, height }: PaneProps) {
   // Keyed on the list itself, so a settings write that leaves the peers alone
   // does not start the snapshot over.
   const symbolList = relativeSymbolsFromPane(symbol, pane?.settings).join(",");
-  const symbols = useMemo(() => (symbolList ? symbolList.split(",") : []), [symbolList]);
+  const listed = useMemo(() => (symbolList ? symbolList.split(",") : []), [symbolList]);
+  const settings = pane?.settings;
+  // A pane opened on one ticker compares it with the peers `fn RV <ticker> --peers` picks, by the same
+  // method, and keeps them in its settings with how they were chosen.
+  const peerSelection = useMemo(() => peerSelectionOf(settings?.[PEER_SELECTION_SETTING], listed), [listed, settings]);
+  const peerSubject = settings?.[AUTO_PEERS_SETTING] === true && listed.length === 1 && !peerSelection ? listed[0]! : null;
+  const dataProvider = useAssetData();
+  const updateSettings = useUpdatePaneSettings();
+  const [peerAttempt, setPeerAttempt] = useState(0);
+  const [peerFailure, setPeerFailure] = useState<{ subject: string; message: string } | null>(null);
+  useEffect(() => {
+    if (!peerSubject || !dataProvider) return;
+    const controller = new AbortController();
+    setPeerFailure(null);
+    findPeers(peerSubject, { marketData: dataProvider, apiClient, signal: controller.signal }).then((selection) => {
+      if (controller.signal.aborted) return;
+      const compared = [selection.subject, ...selection.peers];
+      updateSettings({ symbols: compared, symbolsText: formatTickerListInput(compared), [PEER_SELECTION_SETTING]: selection });
+    }, (failure: unknown) => {
+      if (controller.signal.aborted) return;
+      setPeerFailure({ subject: peerSubject, message: failure instanceof PeerPickError ? failure.reason : `No peers: ${errorMessage(failure)}` });
+    });
+    return () => controller.abort();
+  }, [dataProvider, peerAttempt, peerSubject, updateSettings]);
+  const peerError = peerSubject && peerFailure?.subject === peerSubject ? peerFailure.message : null;
+  // The table waits for the peers, so it fills once; without any it shows the ticker alone.
+  const pickingPeers = peerSubject != null && peerError == null;
+  const symbols = pickingPeers ? NO_SYMBOLS : listed;
+  // The title says how the peers were chosen, or lists the tickers; a title the user gave the pane stays.
+  const ownsTitle = /^RV(?:\s|$)/.test(pane?.title ?? "");
+  usePaneTitle(ownsTitle && listed.length > 0 ? relativeValuationTitle(listed, peerSelection) : null);
   const { navigateTicker } = usePluginTickerActions();
   const loadPeers = useCallback(async (forceRefresh: boolean): Promise<PeerSnapshot[]> => {
     const coordinator = getSharedMarketDataCoordinator();
@@ -189,8 +220,14 @@ export function RelativeValuationPane({ focused, width, height }: PaneProps) {
   // Fundamentals come from one batched snapshot; prices stream on top of it.
   // A changed peer list keeps the last snapshot up until its own answer.
   const peerSnapshot = useAsyncResource(symbols.length > 0 ? loadPeers : null, { keepPreviousData: true });
-  const { data: peers, loading, updatedAt, reload } = peerSnapshot;
-  const error = symbols.length > 0 ? peerSnapshot.error : "No tickers selected";
+  const { data: peers, updatedAt, reload: reloadSnapshot } = peerSnapshot;
+  const loading = peerSnapshot.loading || pickingPeers;
+  const error = symbols.length > 0 ? peerSnapshot.error : pickingPeers ? null : "No tickers selected";
+  // Refreshing asks for the peers again when picking them failed.
+  const reload = useCallback(() => {
+    if (peerError) setPeerAttempt((attempt) => attempt + 1);
+    return reloadSnapshot();
+  }, [peerError, reloadSnapshot]);
   const [selectedIdx, setSelectedIdx] = useState(0);
   const [sortPreference, setSortPreference] = useState<RelativeSortPreference>(DEFAULT_RELATIVE_SORT);
   const appBaseCurrency = useAppSelector((state) => state.config.baseCurrency);
@@ -274,7 +311,7 @@ export function RelativeValuationPane({ focused, width, height }: PaneProps) {
 
   const staleSymbols = rows.filter((row) => row.quoteStale).map((row) => row.symbol);
   const rowErrors = rows.filter((row) => row.error).map((row) => `${row.symbol}: ${row.error}`);
-  const status = [error, ...rowErrors, staleSymbols.length ? `Stale quotes: ${staleSymbols.join(", ")}` : null,
+  const status = [error, peerError, ...rowErrors, staleSymbols.length ? `Stale quotes: ${staleSymbols.join(", ")}` : null,
     missingFx ? "Market-cap FX unavailable" : null].filter(Boolean).join(" · ") || null;
 
   usePaneNoticeFooter({

package/src/plugins/builtin/research/relative-valuation-peers.ts

@@ -3,21 +3,58 @@ import type { HeadlessPaneContext } from "../../../types/headless";
 import type { TickerFinancials } from "../../../types/financials";
 import { isUsListingExchange, parsePublicTickerKey } from "../../../utils/exchanges";
 import { errorMessage } from "../../../utils/errors";
+import { isRecord } from "../../../utils/guards";
+import { formatTickerListInput } from "../../../tickers/list";
 import { selectMarketCapitalization } from "../../../utils/market-capitalization";
+import { notATickerSymbol } from "../../../sources/provider-errors";
 import { fetchScreen } from "../equity-screener/client";
+import { loadHeadlessFinancials } from "../shared/headless-market-data";
 import { loadFxLegs } from "./relative-valuation-currency";
 
+/** The pane setting holding the peers chosen for its subject (`PeerSelection`), which the report reads back too. */
+export const PEER_SELECTION_SETTING = "peerSelection";
+/** The pane setting `--peers` sets, and a pane opened on one ticker: pick that ticker's peers. */
+export const AUTO_PEERS_SETTING = "autoPeers";
+
+/**
+ * What picking peers reads through: the subject's financials and FX rates
+ * from the market data client, the covered equities from the screener. The
+ * report passes its own context, the pane the app's clients, so both pick
+ * the same peers.
+ */
+export type PeerPickContext = Pick<HeadlessPaneContext, "signal" | "marketData" | "apiClient" | "resolveInstrument">;
+
+/**
+ * No peers could be picked. The message is the report's, which names
+ * `--peers` and the command that lists peers instead; `reason` is the pane's,
+ * which says only why.
+ */
+export class PeerPickError extends Error {
+  constructor(readonly reason: string, reportReason: string, symbol: string) {
+    super(`${reportReason} List them yourself: gloom fn RV ${symbol} <tickers>.`);
+    this.name = "PeerPickError";
+  }
+}
+
 /** How many peers `--peers` adds at most, and the fewest it settles for before it falls back. */
 const MOST_PEERS = 6;
 const FEWEST_PEERS = 4;
+/**
+ * A peer of comparable size is at most this many times smaller than the
+ * subject: an airline keeps its smaller airlines, a $5T company is not shown
+ * beside $2M ones. A larger peer always counts; a small company is compared
+ * with its industry's leaders.
+ */
+const COMPARABLE_CAP_FACTOR = 100;
 
 /**
  * How the peers were picked: the subject's own industry, the industry its
- * business belongs to when its profile files it under another, a curated
+ * business belongs to when its profile files it under another, its
+ * industry's peers of comparable size and then its sector's, a curated
  * group's core first (the subject is one of that core) and its industry
  * after, or a curated list when too few covered equities can be read.
  */
-type PeerMethod = "industry" | "related-industry" | "curated-core" | "curated";
+type PeerMethod = "industry" | "related-industry" | "sector" | "curated-core" | "curated";
 
 /** The peers `--peers` added to one symbol, and how; the pane and the report both read it. */
 export interface PeerSelection {
@@ -32,6 +69,10 @@ export interface PeerSelection {
   curatedPeers?: string[];
   /** The curated group, as the header and the note name it (`online learning`). */
   curatedGroup?: string;
+  /** The sector the rest of the peers come from, when too few in `industry` are of comparable size. */
+  sector?: string;
+  /** The peers of comparable size taken from `industry`, first in `peers`; the rest came from `sector`. */
+  industryPeers?: string[];
   /** How the peers were chosen, read after "Peers chosen automatically: ". */
   basis: string;
 }
@@ -81,6 +122,8 @@ export interface PeerCandidate {
   marketCapUsd: number | null;
   /** It reports revenue figures (growth or a margin): a shell or a treasury vehicle filed in an industry does not. */
   reportsOperations: boolean;
+  /** Its sector, as the screener names it. */
+  sector?: string | null;
 }
 
 /** Where the subject's peers come from: its own industry, or the related one its business belongs to. */
@@ -157,10 +200,76 @@ function listText(items: readonly string[]): string {
   return items.length <= 1 ? items.join("") : `${items.slice(0, -1).join(", ")} and ${items.at(-1)}`;
 }
 
-/** The covered equities the screener returned for a subject's group: its industry's, and its curated core's. */
+/**
+ * The covered equities the screener returned for a subject's group: its
+ * industry's, its curated core's, and its sector's of comparable size when
+ * the industry has too few.
+ */
 export interface PeerCandidates {
   industry: readonly PeerCandidate[];
   core: readonly PeerCandidate[];
+  sector?: { name: string; candidates: readonly PeerCandidate[] } | null;
+}
+
+/** At least a hundredth of the subject's market cap. */
+function comparableCap(subjectCap: number | null, cap: number | null): boolean {
+  return subjectCap != null && subjectCap > 0 && cap != null && cap > 0 && cap * COMPARABLE_CAP_FACTOR >= subjectCap;
+}
+
+function comparablePeers(
+  subject: Pick<PeerSubject, "symbol" | "marketCapUsd">,
+  candidates: readonly PeerCandidate[],
+  options?: { limit?: number; exclude?: readonly string[] },
+): string[] {
+  return rankPeerCandidates(subject, candidates.filter((candidate) => comparableCap(subject.marketCapUsd, candidate.marketCapUsd)), options);
+}
+
+/**
+ * A subject of known size whose own industry (no curated group) has fewer
+ * than four covered equities of comparable size: a megacap among micro-caps,
+ * or a small industry. Its sector is asked for the rest.
+ */
+function needsSectorPeers(subject: PeerSubject, group: PeerGroup, industry: readonly PeerCandidate[]): boolean {
+  return !group.related && subject.marketCapUsd != null && subject.marketCapUsd > 0
+    && comparablePeers(subject, industry).length < FEWEST_PEERS;
+}
+
+/**
+ * The sector to widen to, as the screener files the subject, else as it files
+ * most of the subject's industry, else as the subject's profile names it.
+ */
+function peerSectorOf(subject: Pick<PeerSubject, "symbol">, industry: readonly PeerCandidate[], profileSector?: string | null): string | null {
+  const own = industry.find((candidate) => bareSymbol(candidate.symbol) === bareSymbol(subject.symbol))?.sector?.trim();
+  if (own) return own;
+  const counts = new Map<string, number>();
+  for (const candidate of industry) {
+    const sector = candidate.sector?.trim();
+    if (sector) counts.set(sector, (counts.get(sector) ?? 0) + 1);
+  }
+  return [...counts].sort((left, right) => right[1] - left[1])[0]?.[0] ?? (profileSector?.trim() || null);
+}
+
+/**
+ * The industry's peers of comparable size first, then the sector's closest in
+ * market cap, also of comparable size, to six. Null when industry and sector
+ * together still have fewer than four: the industry's closest stand, as they
+ * would without a sector.
+ */
+function sectorSelection(subject: PeerSubject, group: PeerGroup, sector: PeerCandidates["sector"], industryPeers: string[]): PeerSelection | null {
+  if (!sector) return null;
+  const fill = comparablePeers(subject, sector.candidates, { limit: MOST_PEERS - industryPeers.length, exclude: industryPeers });
+  const peers = [...industryPeers, ...fill];
+  if (fill.length === 0 || peers.length < FEWEST_PEERS) return null;
+  const count = (names: readonly string[]) => (names.length === 1 ? "the covered equity" : `the ${names.length} covered equities`);
+  const fromSector = `${count(fill)} in the ${sector.name} sector closest to ${subject.symbol} in market cap`;
+  return {
+    subject: subject.symbol, peers, method: "sector", industry: group.industry, subjectIndustry: subject.industry,
+    sector: sector.name, industryPeers,
+    basis: industryPeers.length === 0
+      ? `${fromSector}, as no other covered equity in ${group.industry} has a hundredth of its market cap`
+      : `${listText(industryPeers)}, ${count(industryPeers)} in ${group.industry} of at least a hundredth of ${subject.symbol}'s market cap; `
+        + `${listText(fill)}, ${fromSector}`,
+  };
 }
 
 /**
@@ -168,7 +277,10 @@ export interface PeerCandidates {
  * curated core is compared with the rest of that core first, closest in
  * market cap, and the industry's closest fill the table to six. Any other
  * subject takes the closest of its own industry, or of the related industry
- * its business belongs to with that core among the candidates. Fewer than
+ * its business belongs to with that core among the candidates. Its own
+ * industry's are the ones of at least a hundredth of its market cap; with
+ * fewer than four of those and the sector read, they come first and the
+ * sector's closest of comparable size fill the table. Fewer than
  * four, or no candidates at all (`candidates` null: the screener did not
  * answer), falls back to the related industry's curated core when it has
  * one; otherwise what was found, or null when nothing was.
@@ -177,10 +289,15 @@ export function selectPeers(subject: PeerSubject, group: PeerGroup, candidates:
   const symbol = subject.symbol;
   const related = group.related;
   const curatedCore = group.inCore && related ? (candidates ? rankPeerCandidates(subject, candidates.core) : []) : [];
+  // Its own industry's peers of comparable size; too few, and the sector's fill in when it was read.
+  const comparable = candidates && !related ? comparablePeers(subject, candidates.industry) : [];
+  const widened = candidates && !related && comparable.length < FEWEST_PEERS ? sectorSelection(subject, group, candidates.sector, comparable) : null;
+  if (widened) return widened;
   const fill = candidates
     ? group.inCore
       ? rankPeerCandidates(subject, candidates.industry, { limit: MOST_PEERS - curatedCore.length, exclude: curatedCore })
-      : rankPeerCandidates(subject, [...candidates.industry, ...related ? candidates.core : []])
+      : comparable.length >= FEWEST_PEERS ? comparable
+        : rankPeerCandidates(subject, [...candidates.industry, ...related ? candidates.core : []])
     : [];
   const peers = [...curatedCore, ...fill];
   if (peers.length < FEWEST_PEERS && related) {
@@ -225,6 +342,10 @@ export function peerMethodTitle(selection: PeerSelection, { automatic = false }:
       return `${peers} by industry: ${selection.industry}`;
     case "related-industry":
       return `${peers} by related industry: ${selection.industry}`;
+    case "sector":
+      return selection.industryPeers?.length
+        ? `${peers} by industry: ${selection.industry}, then sector: ${selection.sector}`
+        : `${peers} by sector: ${selection.sector}`;
     case "curated-core":
       return selection.peers.length > (selection.curatedPeers?.length ?? 0)
         ? `${peers}: ${selection.curatedGroup} curated core, then ${selection.industry}`
@@ -234,6 +355,17 @@ export function peerMethodTitle(selection: PeerSelection, { automatic = false }:
   }
 }
 
+/**
+ * An RV pane's title: the subject and how its peers were chosen
+ * (`RV AAPL + auto peers by industry: Consumer Electronics`), as a capture
+ * of `--peers` is titled, or the tickers as listed.
+ */
+export function relativeValuationTitle(symbols: readonly string[], selection: PeerSelection | null): string {
+  return selection
+    ? `RV ${selection.subject} + ${peerMethodTitle(selection, { automatic: true })}`
+    : `RV ${formatTickerListInput([...symbols])}`;
+}
+
 function screenSymbol(row: ScreenRow): string {
   return isUsListingExchange(row.exchange) ? row.symbol : `${row.symbol}:${row.exchange}`;
 }
@@ -245,16 +377,36 @@ function candidateOf(row: ScreenRow): PeerCandidate {
     marketCapUsd: metric("marketCap"),
     reportsOperations: metric("revenueGrowthPercent") != null || metric("grossMarginPercent") != null
       || metric("operatingMarginPercent") != null,
+    sector: row.sector,
   };
 }
 
-async function screenRows(criterion: ScreenDefinition["criteria"][number], ctx: HeadlessPaneContext): Promise<ScreenRow[]> {
-  const definition: ScreenDefinition = { version: 1, criteria: [criterion], sort: { field: "marketCap", direction: "desc" }, currency: "USD" };
-  return (await fetchScreen(definition, null, ctx.signal, ctx.apiClient)).rows;
+async function screenRows(
+  criteria: ScreenDefinition["criteria"],
+  ctx: PeerPickContext,
+  { direction = "desc", limit }: { direction?: "asc" | "desc"; limit?: number } = {},
+): Promise<ScreenRow[]> {
+  const definition: ScreenDefinition = { version: 1, criteria, sort: { field: "marketCap", direction }, currency: "USD" };
+  return (await fetchScreen(definition, null, ctx.signal, ctx.apiClient, limit)).rows;
+}
+
+/**
+ * The sector's covered equities of comparable size nearest the subject's cap:
+ * the next larger and the next smaller, asked apart so a crowded sector
+ * cannot crowd out the closest.
+ */
+async function sectorCandidates(sector: string, capUsd: number, ctx: PeerPickContext): Promise<PeerCandidate[]> {
+  const inSector: ScreenDefinition["criteria"][number] = { field: "sector", op: "in", value: [sector] };
+  const [larger, smaller] = await Promise.all([
+    screenRows([inSector, { field: "marketCap", op: "gte", value: Math.floor(capUsd) }], ctx, { direction: "asc", limit: 25 }),
+    screenRows([inSector, { field: "marketCap", op: "between", value: [Math.floor(capUsd / COMPARABLE_CAP_FACTOR), Math.ceil(capUsd)] }],
+      ctx, { direction: "desc", limit: 25 }),
+  ]);
+  return [...larger, ...smaller].map(candidateOf);
 }
 
 /** The subject's market cap in US dollars, through the app's FX rates when it is quoted in another currency. */
-async function subjectCapUsd(financials: TickerFinancials | null, ctx: HeadlessPaneContext): Promise<number | null> {
+async function subjectCapUsd(financials: TickerFinancials | null, ctx: PeerPickContext): Promise<number | null> {
   const cap = selectMarketCapitalization(financials?.quote, financials?.fundamentals);
   if (!cap) return null;
   if (cap.currency === "USD") return cap.value;
@@ -266,27 +418,29 @@ async function subjectCapUsd(financials: TickerFinancials | null, ctx: HeadlessP
 /**
  * Picks the peers of `symbol` for `--peers`: its group from its symbol or
  * profile, the group's covered equities from the screener (its industry, and
- * a related industry's curated core), ranked as `selectPeers` says. Throws
- * when nothing places the subject, or nothing can be found, saying how to
- * list peers instead.
+ * a related industry's curated core, or its sector's of comparable size when
+ * the industry has too few), ranked as `selectPeers` says. Throws a
+ * `PeerPickError` when nothing places the subject, or nothing can be found.
  */
-export async function pickPeers(symbol: string, financials: TickerFinancials | null, ctx: HeadlessPaneContext): Promise<PeerSelection> {
+export async function pickPeers(symbol: string, financials: TickerFinancials | null, ctx: PeerPickContext): Promise<PeerSelection> {
   const subject: PeerSubject = {
     symbol,
     industry: financials?.profile?.industry?.trim() || null,
     description: financials?.profile?.description ?? null,
     marketCapUsd: null,
   };
-  const listYourOwn = `List them yourself: gloom fn RV ${symbol} <tickers>.`;
   const group = peerGroupOf(subject);
-  if (!group) throw new Error(`${symbol}'s profile names no industry, so --peers cannot pick its peers. ${listYourOwn}`);
+  if (!group) {
+    throw new PeerPickError(`No peers: ${symbol}'s profile names no industry.`,
+      `${symbol}'s profile names no industry, so --peers cannot pick its peers.`, symbol);
+  }
   let candidates: PeerCandidates | null = null;
   let failure: string | null = null;
   try {
     const [capUsd, industryRows, coreRows] = await Promise.all([
       subjectCapUsd(financials, ctx).catch(() => null),
-      screenRows({ field: "industry", op: "in", value: [group.industry] }, ctx),
-      group.related ? screenRows({ field: "symbol", op: "in", value: [...group.related.core] }, ctx) : Promise.resolve([]),
+      screenRows([{ field: "industry", op: "in", value: [group.industry] }], ctx),
+      group.related ? screenRows([{ field: "symbol", op: "in", value: [...group.related.core] }], ctx) : Promise.resolve([]),
     ]);
     subject.marketCapUsd = capUsd;
     candidates = { industry: industryRows.map(candidateOf), core: coreRows.map(candidateOf) };
@@ -294,9 +448,52 @@ export async function pickPeers(symbol: string, financials: TickerFinancials | n
     ctx.signal.throwIfAborted();
     failure = errorMessage(error);
   }
+  // A megacap among micro-caps: the sector's companies of comparable size. Without them the industry's stand.
+  const sectorName = candidates && needsSectorPeers(subject, group, candidates.industry)
+    ? peerSectorOf(subject, candidates.industry, financials?.profile?.sector) : null;
+  if (candidates && sectorName) {
+    const sector = await sectorCandidates(sectorName, subject.marketCapUsd!, ctx).catch(() => {
+      ctx.signal.throwIfAborted();
+      return null;
+    });
+    if (sector) candidates = { ...candidates, sector: { name: sectorName, candidates: sector } };
+  }
   const selection = selectPeers(subject, group, candidates);
   if (selection) return selection;
-  throw new Error(failure
-    ? `--peers could not read the covered equities in ${group.industry}: ${failure} ${listYourOwn}`
-    : `No other covered equity is in ${group.industry}, so --peers found no peers for ${symbol}. ${listYourOwn}`);
+  throw failure
+    ? new PeerPickError(`No peers: the covered equities in ${group.industry} could not be read (${failure}).`,
+      `--peers could not read the covered equities in ${group.industry}: ${failure}`, symbol)
+    : new PeerPickError(`No peers: no other covered equity is in ${group.industry}.`,
+      `No other covered equity is in ${group.industry}, so --peers found no peers for ${symbol}.`, symbol);
+}
+
+/**
+ * The peers of one symbol, as `fn RV <symbol> --peers` and the RV pane opened
+ * on one ticker both pick them: its financials for its industry, profile and
+ * market cap, then `pickPeers`. A word that is no ticker fails as such; any
+ * other failure to read the financials leaves the peers to what the symbol
+ * alone places (a curated core's member).
+ */
+export async function findPeers(symbol: string, ctx: PeerPickContext): Promise<PeerSelection> {
+  const financials = await loadHeadlessFinancials(ctx, symbol).catch((error: unknown) => {
+    ctx.signal.throwIfAborted();
+    // A word that is no ticker is said as `fn RV duolingo lrn` says it, which the CLI follows with the search to run.
+    if (notATickerSymbol(errorMessage(error))) throw error;
+    return null;
+  });
+  return pickPeers(symbol, financials, ctx);
+}
+
+/**
+ * The peers chosen for a list, as the expansion or the pane left them in its
+ * settings: null unless `symbols` is still the subject followed by those
+ * peers, in order.
+ */
+export function peerSelectionOf(value: unknown, symbols: readonly string[]): PeerSelection | null {
+  if (!isRecord(value) || typeof value.subject !== "string" || !Array.isArray(value.peers)
+    || typeof value.method !== "string" || typeof value.basis !== "string") return null;
+  const selection = value as unknown as PeerSelection;
+  const expected = [selection.subject, ...selection.peers];
+  return expected.length === symbols.length && expected.every((symbol, index) => symbol.toUpperCase() === symbols[index]?.toUpperCase())
+    ? selection : null;
 }

package/src/plugins/builtin/research/relative-valuation-settings.ts

@@ -0,0 +1,44 @@
+import type { PaneSettingsContext, PaneSettingsDef } from "../../../types/plugin";
+import { formatTickerListInput, parseTickerListInput } from "../../../tickers/list";
+import { AUTO_PEERS_SETTING, PEER_SELECTION_SETTING, peerSelectionOf } from "./relative-valuation-peers";
+
+/** The most tickers RV compares, as it reads its argument. */
+export const MAX_RELATIVE_VALUATION_TICKERS = 12;
+
+/** The tickers an RV pane compares: the list in its settings, else the ticker it is bound to. */
+export function relativeSymbolsFromPane(symbol: string | null, paneSettings: Record<string, unknown> | undefined): string[] {
+  const settingsSymbols = Array.isArray(paneSettings?.symbols)
+    ? paneSettings.symbols.filter((value): value is string => typeof value === "string")
+    : [];
+  if (settingsSymbols.length > 0) return settingsSymbols;
+  return symbol ? [symbol] : [];
+}
+
+/**
+ * The pane's Tickers setting: the list it compares, with how its peers were
+ * chosen while they are the ones picked. A list typed there is compared as
+ * typed, one ticker alone included.
+ */
+export function buildRelativeValuationSettingsDef(context: PaneSettingsContext): PaneSettingsDef {
+  const symbols = relativeSymbolsFromPane(null, context.settings);
+  const selection = peerSelectionOf(context.settings[PEER_SELECTION_SETTING], symbols);
+  return {
+    title: "Relative Valuation Settings",
+    values: { symbolsText: formatTickerListInput(symbols) },
+    fields: [{
+      key: "symbolsText",
+      label: "Tickers",
+      description: selection
+        ? `Peers chosen automatically: ${selection.basis}. Edit the list to compare your own.`
+        : `Enter up to ${MAX_RELATIVE_VALUATION_TICKERS} tickers separated by commas.`,
+      type: "text",
+      placeholder: "AAPL, MSFT, GOOGL",
+    }],
+    applyValue: (settings, field, value) => {
+      if (field.key !== "symbolsText") return { ...settings, [field.key]: value };
+      const next = parseTickerListInput(typeof value === "string" ? value : "", MAX_RELATIVE_VALUATION_TICKERS);
+      const { [PEER_SELECTION_SETTING]: _picked, ...rest } = settings;
+      return { ...rest, symbols: next, symbolsText: formatTickerListInput(next), [AUTO_PEERS_SETTING]: false };
+    },
+  };
+}

package/src/plugins/builtin/risk-factors/data.ts

@@ -5,6 +5,7 @@ import {
 } from "../../../api-client";
 import { ApiRequestError, isPermanentClientError } from "../../../api-client/errors";
 import { listingAbroad, type IssuerListingParams } from "../../../api-client/paths";
+import { servedFromSavedCopy } from "../../../data/saved-copies";
 import type { HeadlessPaneApiClient, PluginPersistence } from "../../../types/plugin";
 import { secListingKey } from "../../../utils/sec";
 
@@ -78,13 +79,14 @@ function loadCached<T extends object>(
     }
     const fallback = store?.getResource<T>(kind, key, { ...options, allowExpired: true });
     if (!fallback) throw error;
-    return {
+    // A command that shows it ends with when the copy was saved, not with the failure.
+    return servedFromSavedCopy({
       ...fallback.value,
       fetchedAt: fallback.fetchedAt,
       stale: true,
       refreshError: (error instanceof Error ? error.message : String(error)).trim() || "Request failed",
       errorStatus: error instanceof ApiRequestError ? error.status : undefined,
-    };
+    }, fallback.fetchedAt);
   }).finally(() => { if (active.get(key) === request) active.delete(key); });
   active.set(key, request);
   return request.promise;