@gloom-sh/terminal 0.18.5 → 0.19.0

package/src/plugins/builtin/sec/fund-facts-view.tsx

@@ -4,7 +4,7 @@ import { useAsyncResource } from "../../../react/async-resource";
 import { Box } from "../../../ui";
 import { t } from "../../../i18n";
 import type { FundFactsPayload } from "../../../api-client/fund-facts";
-import { cachedFundFacts, fundFactItems, fundFactsEmptyText, fundFactsErrorLine, fundFactsStaleText, loadFundFacts } from "./fund-facts";
+import { cachedFundFacts, fundFactItems, fundFactsEmptyText, fundFactsErrorLine, fundFactsNavReasonText, fundFactsStaleText, loadFundFacts } from "./fund-facts";
 import type { CloudResource } from "../shared/cloud-resource";
 
 /** A fund's facts, served from the cache first and refreshed behind it; null asks for nothing. */
@@ -18,7 +18,8 @@ export function useFundFacts(symbol: string | null | undefined) {
 /**
  * The fund's facts as the summary sheet over its filings, or one line saying
  * why there are none. Loading is one muted line, so the filings never wait.
- * A stale NAV adds the line saying since when, under the marked figures.
+ * A stale NAV adds the line saying since when, under the marked figures; a
+ * fund without a NAV, the line saying why.
  */
 export function FundFactsSummary({ symbol, width, facts, loading, error }: {
   symbol: string;
@@ -29,10 +30,12 @@ export function FundFactsSummary({ symbol, width, facts, loading, error }: {
 }) {
   if (facts?.covered) {
     const stale = fundFactsStaleText(symbol, facts);
+    const noNav = fundFactsNavReasonText(symbol, facts);
     return (
       <>
         <StatGrid width={width} items={fundFactItems(facts)} />
         {stale ? <FundViewNotice lines={[stale]} tone="warning" /> : null}
+        {noNav ? <FundViewNotice lines={[noNav]} /> : null}
       </>
     );
   }

package/src/plugins/builtin/sec/fund-facts.ts

@@ -1,5 +1,5 @@
 import { apiClient } from "../../../api-client";
-import type { FundFactsPayload, FundLeverage, FundMetalHoldings } from "../../../api-client/fund-facts";
+import type { FundFactsPayload, FundLeverage, FundMetalHoldings, FundStructure } from "../../../api-client/fund-facts";
 import type { StatItem } from "../../../components/ui/stat-grid";
 import { leverageFactorLabel } from "../../../time-series/leverage";
 import { t, tf } from "../../../i18n";
@@ -7,7 +7,8 @@ import { createPluginCache } from "../../../data/plugin-cache";
 import type { HeadlessPaneEntry } from "../../../types/plugin";
 import { errorMessage } from "../../../utils/errors";
 import { formatCompact } from "../../../utils/format";
-import { bondClassText, bondFigures, isBondFactsShape } from "../../../market-data/bond-funds";
+import { bondClassText, bondFigures } from "../../../market-data/bond-funds";
+import { readFundFacts, validateFundFacts } from "../../../market-data/fund-facts";
 import { cachedCloudResource, loadCloudResource, unavailableOnServer } from "../shared/cloud-resource";
 
 /** Sponsors publish once a day, in the US evening; a copy younger than this is not asked for again. */
@@ -17,28 +18,6 @@ export const fundFactsCache = createPluginCache<FundFactsPayload>({
 
 type Client = Pick<typeof apiClient, "getFundFacts">;
 
-const fact = (value: unknown) => value === null || (typeof value === "object" && value !== null && "value" in value && "source" in value);
-const finite = (value: unknown): value is number => typeof value === "number" && Number.isFinite(value);
-
-function isMetalHoldingsShape(value: FundFactsPayload["metalHoldings"]): boolean {
-  return value == null || ((value.metal === "gold" || value.metal === "silver") && typeof value.asOf === "string" && finite(value.ounces)
-    && (value.tonnes === null || finite(value.tonnes)) && typeof value.source?.publisher === "string"
-    && (value.change === null || (typeof value.change?.since === "string" && finite(value.change.ounces))));
-}
-
-/** Absent from servers before it; otherwise a dated factor with its reset period. */
-const leverageShape = (value: FundFactsPayload["leverage"]) => value === undefined || value === null
-  || (fact(value) && typeof value.value === "number" && Number.isFinite(value.value) && (value.reset === "daily" || value.reset === "monthly"));
-
-function validateFundFacts(data: FundFactsPayload): FundFactsPayload {
-  if (!data || typeof data.ticker !== "string" || typeof data.covered !== "boolean"
-    || ![data.expenseRatio, data.nav, data.premiumDiscount, data.netAssets, data.sponsor, data.inception, data.index].every(fact)
-    || !isBondFactsShape(data.bond) || !leverageShape(data.leverage) || !isMetalHoldingsShape(data.metalHoldings)) {
-    throw new Error("Unreadable fund facts response");
-  }
-  return data;
-}
-
 export const FUND_FACTS_UNAVAILABLE = "Fund facts are not available on this server yet.";
 
 /** A failed load as one line: the server-not-ready message as it is, anything else after "Fund facts unavailable:". */
@@ -54,7 +33,7 @@ export function fundFactsErrorLine(error: unknown): string {
 }
 
 export async function fetchFundFacts(ticker: string, client: Client = apiClient, signal?: AbortSignal): Promise<FundFactsPayload> {
-  try { return validateFundFacts(await (signal ? client.getFundFacts(ticker, { signal }) : client.getFundFacts(ticker))); } catch (error) { throw unavailableOnServer(error, FUND_FACTS_UNAVAILABLE); }
+  try { return await readFundFacts(ticker, client, signal); } catch (error) { throw unavailableOnServer(error, FUND_FACTS_UNAVAILABLE); }
 }
 const cacheKey = (ticker: string) => ticker.trim().toUpperCase();
 export const cachedFundFacts = (ticker: string) => cachedCloudResource(fundFactsCache, cacheKey(ticker), validateFundFacts);
@@ -80,6 +59,40 @@ function formatNetAssets(value: number): string {
   return `$${formatCompact(value)}`;
 }
 
+/** A NAV the sponsor published as a range: `$4.12 to $4.22`. */
+const estimateRange = (estimate: { low: number; high: number }) => `${formatNav(estimate.low)} to ${formatNav(estimate.high)}`;
+
+/** Shares created less redeemed, signed: `+12.35M`, `-3.1M`. */
+const signedCompact = (value: number) => `${value > 0 ? "+" : value < 0 ? "-" : ""}${formatCompact(Math.abs(value))}`;
+
+/** A month's flows in dollars, when every day had a NAV to value them at. */
+const flowsValue = (value: number) => `${value < 0 ? "-" : value > 0 ? "+" : ""}$${formatCompact(Math.abs(value))}`;
+
+/** A closed-end fund's NAV is a month end's (a sponsor's estimate, or the filing's period end): its normal cadence, not a lag. */
+const monthEndNav = (facts: FundFactsPayload) => facts.nav?.period === "month-end";
+
+/** The session of the close a premium was computed from, when it is before the NAV's date: a month end on a weekend. */
+const closeSession = (facts: FundFactsPayload) => {
+  const close = facts.closingPrice?.asOf;
+  const premium = facts.premiumDiscount?.asOf;
+  return close && premium && close < premium ? close : null;
+};
+
+/** A registered closed-end fund or a BDC: its NAV is a month end's or a filing's, and its price trades at its own premium to it. */
+const closedEnd = (structure: FundFactsPayload["structure"]) => structure === "closed-end" || structure === "bdc";
+
+/** Each structure by its own name in a report; one a newer server adds, by its own key rather than another's name. */
+const STRUCTURE_LABELS: Record<FundStructure, string> = {
+  registered: "Registered fund",
+  trust: "Trust or pool, not an open-end fund",
+  "closed-end": "Closed-end fund",
+  bdc: "Business development company (BDC)",
+};
+const structureLabel = (structure: FundStructure) => STRUCTURE_LABELS[structure] ?? String(structure);
+
+/** The pane's shorter names, for the funds whose figures read unlike an ETF's. */
+const PANE_STRUCTURE: Partial<Record<FundStructure, string>> = { "closed-end": "Closed-end fund", bdc: "BDC" };
+
 /** Ounces and tonnes as the sponsor publishes them, to its own decimals (34,085,936.5; 1,060.18). */
 const metalFigure = (value: number, signed = false) =>
   `${signed && value > 0 ? "+" : ""}${value.toLocaleString("en-US", { maximumFractionDigits: 3 })}`;
@@ -156,9 +169,19 @@ function datedFigures(facts: FundFactsPayload): Record<"nav" | "premium" | "fee"
   const prospectus = facts.expenseRatio?.document === "prospectus";
   const nport = assets?.document === "N-PORT";
   return {
-    nav: { detail: nav ? (facts.stale ? tf("{date} stale", { date: nav }) : nav) : undefined, marked: facts.stale },
+    nav: {
+      detail: nav
+        ? facts.stale ? tf("{date} stale", { date: nav }) : monthEndNav(facts) ? tf("{date} month-end", { date: nav }) : nav
+        : undefined,
+      marked: facts.stale,
+    },
     premium: {
-      detail: premium?.asOf ? (premium.basis === "computed" ? tf("{date} close", { date: premium.asOf }) : premium.asOf) : undefined,
+      // A computed premium is dated by its close's session (a weekend month end's Friday), and says when it is an estimate's.
+      detail: premium?.asOf
+        ? premium.basis === "computed"
+          ? `${tf("{date} close", { date: closeSession(facts) ?? premium.asOf })}${premium.estimate ? ` · ${t("est.")}` : ""}`
+          : premium.asOf
+        : undefined,
       marked: facts.stale || (!!premium?.asOf && !!nav && premium.asOf !== nav),
     },
     fee: {
@@ -192,10 +215,29 @@ export function fundFactItems(facts: FundFactsPayload): StatItem[] {
   const cell = (id: string, label: string, value: string, figure: DatedFigure): StatItem => ({
     id, label, value, ...(figure.detail ? { detail: figure.detail } : {}), ...(figure.marked ? { tone: "warning" as const } : {}),
   });
-  if (facts.nav) items.push(cell("nav", "NAV", formatNav(facts.nav.value), dated.nav));
+  if (facts.nav) {
+    // A sponsor's estimate is a range: its midpoint is the figure, the range follows its date.
+    const estimate = facts.nav.estimate;
+    const nav = estimate && dated.nav.detail
+      ? { ...dated.nav, detail: `${dated.nav.detail} · ${tf("est. {range}", { range: estimateRange(estimate) })}` } : dated.nav;
+    items.push(cell("nav", "NAV", formatNav(facts.nav.value), nav));
+  }
   if (facts.premiumDiscount) items.push(cell("premium", "Premium/discount", formatPremiumPercent(facts.premiumDiscount.value), dated.premium));
   if (facts.expenseRatio) items.push(cell("fee", expenseRatioLabel(facts), formatFeePercent(facts.expenseRatio.value), dated.fee));
   if (facts.netAssets) items.push(cell("assets", wholeFund(facts) ? "Fund net assets" : "Net assets", formatNetAssets(facts.netAssets.value), dated.netAssets));
+  // Shares outstanding as the sponsor states them, then the month's creations less redemptions.
+  if (facts.sharesOutstanding) {
+    items.push(cell("shares", "Shares outstanding", formatCompact(facts.sharesOutstanding.value),
+      { detail: facts.sharesOutstanding.asOf ?? undefined, marked: facts.stale }));
+  }
+  if (facts.flows) {
+    // In dollars with the shares beside them; in shares alone when a day had no NAV to value them at.
+    const flows = facts.flows;
+    const shares = tf("{count} shares", { count: signedCompact(flows.shares) });
+    const since = tf("since {date}", { date: flows.from });
+    items.push(cell("flows", "1M flows", flows.value === null ? shares : flowsValue(flows.value),
+      { detail: flows.value === null ? since : `${shares} · ${since}`, marked: facts.stale }));
+  }
   // A bond fund's yields and duration, each dated by its sponsor.
   for (const figure of facts.bond ? bondFigures(facts.bond) : []) {
     items.push(cell(figure.key, figure.label, figure.text, { detail: figure.date, marked: facts.stale }));
@@ -212,6 +254,9 @@ export function fundFactItems(facts: FundFactsPayload): StatItem[] {
         { detail: metal.change.tonnes == null ? tf("since {date}", { date: metal.change.since }) : `${change} · ${tf("since {date}", { date: metal.change.since })}`, marked: metal.stale }));
     }
   }
+  // A closed-end fund or BDC says which: its figures read unlike an ETF's.
+  const structure = facts.structure ? PANE_STRUCTURE[facts.structure] : undefined;
+  if (structure) items.push({ id: "structure", label: "Structure", value: t(structure) });
   if (facts.sponsor) items.push({ id: "sponsor", label: "Sponsor", value: facts.sponsor.value });
   if (facts.inception) items.push({ id: "inception", label: "Inception", value: facts.inception.value });
   // A leveraged or inverse fund's objective, dated by the sponsor page it was read from, beside its benchmark.
@@ -276,19 +321,23 @@ export function fundFactEntries(facts: FundFactsPayload): HeadlessPaneEntry[] {
   const add = (key: string, label: string, value: unknown, formatted: string, unit?: string) =>
     entries.push({ key, label, value, formatted, ...(unit ? { unit } : {}) });
   if (facts.name) add("name", "Name", facts.name, facts.name);
-  if (facts.structure) add("structure", "Structure", facts.structure,
-    facts.structure === "trust" ? "Trust or pool, not an open-end fund" : "Registered fund");
+  if (facts.structure) add("structure", "Structure", facts.structure, structureLabel(facts.structure));
   if (facts.expenseRatio) {
     const kind = feeBasis(facts);
     const date = facts.expenseRatio.asOf && facts.expenseRatio.document === "prospectus" ? `${facts.expenseRatio.asOf} prospectus` : facts.expenseRatio.asOf;
     add("expenseRatioPercent", expenseRatioLabel(facts), facts.expenseRatio.value,
       provenance(`${formatFeePercent(facts.expenseRatio.value)}${kind ? ` ${kind}` : ""}`, date, facts.expenseRatio.source), "%");
   }
-  if (facts.nav) add("nav", "NAV", facts.nav.value, provenance(formatNav(facts.nav.value), facts.nav.asOf, facts.nav.source), "USD");
+  if (facts.nav) {
+    const date = facts.nav.asOf && monthEndNav(facts) ? `${facts.nav.asOf} month-end` : facts.nav.asOf;
+    const estimate = facts.nav.estimate ? `estimate ${estimateRange(facts.nav.estimate)}` : null;
+    add("nav", "NAV", facts.nav.value, provenance(formatNav(facts.nav.value), date, estimate, facts.nav.source), "USD");
+  }
   if (facts.closingPrice) add("closingPrice", "Closing price", facts.closingPrice.value,
     provenance(formatNav(facts.closingPrice.value), facts.closingPrice.asOf, facts.closingPrice.source), "USD");
   if (facts.premiumDiscount) {
-    const basis = facts.premiumDiscount.basis === "computed" ? "closing price vs NAV" : null;
+    const basis = facts.premiumDiscount.basis !== "computed" ? null
+      : facts.premiumDiscount.estimate ? "closing price vs NAV estimate midpoint" : "closing price vs NAV";
     add("premiumDiscountPercent", "Premium/discount", facts.premiumDiscount.value,
       provenance(formatPremiumPercent(facts.premiumDiscount.value), facts.premiumDiscount.asOf, basis, facts.premiumDiscount.source), "%");
   }
@@ -298,6 +347,16 @@ export function fundFactEntries(facts: FundFactsPayload): HeadlessPaneEntry[] {
       ? `${facts.netAssets.asOf} month-end${facts.netAssets.document ? ` ${facts.netAssets.document}` : ""}` : facts.netAssets.asOf;
     add("netAssets", "Net assets", facts.netAssets.value, provenance(formatNetAssets(facts.netAssets.value), date, scope, facts.netAssets.source), "USD");
   }
+  if (facts.sharesOutstanding) {
+    add("sharesOutstanding", "Shares outstanding", facts.sharesOutstanding.value,
+      provenance(facts.sharesOutstanding.value.toLocaleString("en-US"), facts.sharesOutstanding.asOf, facts.sharesOutstanding.source), "shares");
+  }
+  if (facts.flows) {
+    // JSON keeps the dollar figure (null when a day had no NAV); `fundFacts.flows` has the shares.
+    const flows = facts.flows;
+    add("flows1M", "1M flows", flows.value, provenance(flows.value === null ? null : flowsValue(flows.value),
+      `${signedCompact(flows.shares)} shares`, `${flows.from} to ${flows.asOf}`, flows.source), "USD");
+  }
   const metal = facts.metalHoldings;
   if (metal) {
     // The trust's own figures, as its sponsor's daily holdings file states them; JSON has the tonnes in `fundFacts`.
@@ -323,7 +382,8 @@ export function fundFactEntries(facts: FundFactsPayload): HeadlessPaneEntry[] {
   }
   if (facts.index) add("index", BENCHMARK_LABEL, facts.index.value, provenance(facts.index.value, facts.index.source));
   const url = facts.nav?.url ?? facts.expenseRatio?.url ?? facts.netAssets?.url;
-  if (url) add("url", "Sponsor page", url, url);
+  // The figures' own page: the sponsor's, or the SEC filing they were read from (a prospectus, an N-PORT, an 8-K).
+  if (url) add("url", /^https:\/\/www\.sec\.gov\//.test(url) ? "SEC filing" : "Sponsor page", url, url);
   return entries;
 }
 
@@ -338,7 +398,7 @@ export function listNames(names: readonly string[]): string {
  * the consolidated close cites Gloom Cloud on its own line, not here.
  */
 export function fundFactPublishers(facts: FundFactsPayload): string[] {
-  return [...new Set([...[facts.nav, facts.expenseRatio, facts.netAssets, facts.leverage, facts.index, facts.bond?.secYield, facts.bond?.yieldToWorst, facts.bond?.duration]
+  return [...new Set([...[facts.nav, facts.expenseRatio, facts.netAssets, facts.sharesOutstanding, facts.flows, facts.leverage, facts.index, facts.bond?.secYield, facts.bond?.yieldToWorst, facts.bond?.duration]
     .flatMap((value) => value ? [value.source] : []), ...facts.metalHoldings ? [facts.metalHoldings.source.publisher] : []])];
 }
 
@@ -352,6 +412,25 @@ export function fundFactsStaleText(symbol: string, facts: FundFactsPayload): str
   return fundFactsStaleNote(symbol, facts) ? tf("{symbol}'s newest NAV is from {date}; its sponsor has not published one since.", { symbol, date: facts.nav!.asOf! }) : null;
 }
 
+/**
+ * Why a covered fund has no NAV, in one line, translated for the pane: what
+ * Gloom reads for it and what that leaves out, as the server's `navReason`
+ * says it. Null when it has a NAV, and from servers before the reason.
+ */
+export function fundFactsNavReasonText(symbol: string, facts: FundFactsPayload): string | null {
+  if (!facts.covered || facts.nav || !facts.navReason) return null;
+  // A sponsor that publishes the fund's other figures.
+  const sponsor = fundFactPublishers(facts).find((publisher) => publisher !== "SEC EDGAR");
+  if (sponsor) return tf("No NAV for {symbol}: {publisher} publishes figures for it, but no NAV.", { symbol, publisher: sponsor });
+  if (closedEnd(facts.structure)) {
+    return tf("No NAV for {symbol}: its SEC filings state net assets but no NAV per share, and its sponsor's NAV is not one Gloom reads.", { symbol });
+  }
+  if (facts.structure === "trust") {
+    return tf("No NAV for {symbol}: its sponsor's site is not one Gloom reads, and a trust files no NAV with the SEC's fund data sets.", { symbol });
+  }
+  return tf("No NAV for {symbol}: its sponsor's site is not one Gloom reads, and the SEC's prospectus and N-PORT data sets state no NAV.", { symbol });
+}
+
 /**
  * Why a fund has no facts, in one line, and where to look instead: its SEC
  * filings, unless the caller already points there.
@@ -376,6 +455,9 @@ export function fundFactsEmptyText(symbol: string, facts: FundFactsPayload | nul
     if (facts.structure === "registered") {
       return tf("No figures for {symbol}: its sponsor's site is not one Gloom reads, and the SEC's prospectus and N-PORT data sets list none for it yet.", { symbol });
     }
+    if (closedEnd(facts.structure)) {
+      return tf("No figures for {symbol}: it files with the SEC as a closed-end fund or BDC, but neither the filings Gloom reads nor its sponsor's site state any for it yet.", { symbol });
+    }
     return tf("No figures for {symbol}: it lists as a fund, but the SEC's lists do not name it yet and its sponsor's site is not one Gloom reads.", { symbol });
   }
   if (facts.status === "not-a-fund") return tf("No fund facts for {symbol}: it is not on the SEC's lists of US-listed funds.", { symbol });

package/src/plugins/builtin/sec/headless.ts

@@ -268,7 +268,8 @@ export function createFundHeadless(dependencies: FundHeadlessDependencies = defa
           ...(factsResult.status === "rejected" ? [fundFactsErrorText(factsResult.reason)] : []),
           ...(filingsResult.status === "rejected" ? [`Fund filings: ${errorMessage(filingsResult.reason)}`] : []),
         ],
-        notes: facts ? [fundFactsStaleNote(symbol, facts)].filter((note): note is string => !!note) : [],
+        // A stale NAV says since when; a covered fund without one says why, as the server words it.
+        notes: facts ? [fundFactsStaleNote(symbol, facts), facts.covered && !facts.nav ? facts.navReason : null].filter((note): note is string => !!note) : [],
         // The facts' publisher is the source, named the same way for every fund; without facts it is the SEC.
         freshness: {
           source: listNames(publishers) || "SEC EDGAR",

package/src/plugins/builtin/series-inventory.ts

@@ -64,9 +64,11 @@ export const SERIES_INVENTORY: readonly SeriesInventoryEntry[] = [
   { module: "perps", chart: "Perpetual funding, open interest, premium and long/short account share", series: ["perps:*"] },
   { module: "crypto-etf-flows", chart: "The running net flow of the US spot bitcoin or ether ETFs since launch", notInCatalog: "not-yet", reason: "Daily and dated: the running total and each fund's daily flow could be crypto ETF series, and none is registered for the composer yet." },
   { module: "perps", chart: "Perpetual mark price", notInCatalog: "not-yet", reason: "The pair's price is in the catalog; the perpetual's own mark price could be a crypto series." },
+  { module: "treasury-daily", chart: "The Treasury General Account's daily closing balance", notInCatalog: "not-yet", reason: "Daily and dated, from the Daily Treasury Statement's operating cash balance table; the pane reads it with the day's cash lines, and none is registered for the composer yet." },
   { module: "primary-dealers", chart: "A primary dealer position's weekly net level, the sum of the release's series behind the row", notInCatalog: "not-yet", reason: "Weekly and dated, one series per row of the board; the pane reads each only when its row is selected, and none is registered for the composer yet." },
   { module: "short-interest", chart: "A ticker's short interest and days to cover", series: ["short-interest:*"] },
   { module: "short-volume", chart: "A ticker's daily short volume ratio", series: ["short-volume:*"] },
+  { module: "scanner", chart: "Net options premium through the session, for the market or one ticker (FLOW's Tide)", notInCatalog: "per-item", reason: "One per ticker, filter set and session, summed on request from the recorded option prints." },
   { module: "social-mentions", chart: "A ticker's daily posts", series: ["social-mentions:*"] },
   { module: "jobs", chart: "A company's open job postings", series: ["jobs:*"] },
   { module: "attention", chart: "Research hours on a ticker, hour by hour", series: ["attention:*"] },

package/src/plugins/builtin/shared/cloud-resource.ts

@@ -1,3 +1,4 @@
+import { logFailure } from "../../../utils/log-failure";
 import { ApiRequestError, isAccessDenied } from "../../../api-client/errors";
 import type { PluginCacheResult } from "../../../data/plugin-cache";
 
@@ -26,8 +27,8 @@ export function cachedCloudResource<T>(
   if (!cached) return null;
   try {
     return { payload: validate(cached.data), stale: false, refreshError: null };
-  } catch {
-    return null;
+  } catch (error) {
+    return logFailure("shared.cloud-resource", "Validate cached cloud payload failed", null)(error);
   }
 }
 

package/src/plugins/builtin/shared/cloud-upgrade.ts

@@ -1,3 +1,4 @@
+import { logFailure } from "../../../utils/log-failure";
 import { useCallback, useEffect, useMemo, useRef } from "react";
 import { apiClient } from "../../../api-client";
 import { recordResearchActivity, researchUpgradeUrl } from "../../../api-client/research-activity";
@@ -159,7 +160,7 @@ async function openCheckoutWithHandoff(
     .then(({ url, link }): CheckoutHandoffTarget => ({
       url,
       link: link ?? null,
-      opened: rendererHost.openExternal(url).then((result) => result !== false, () => false),
+      opened: rendererHost.openExternal(url).then((result) => result !== false, logFailure("shared.cloud-upgrade", "Open checkout in the browser failed", false)),
     }));
   void promptCheckoutHandoff(dialog, target);
   await (await target).opened;
@@ -221,10 +222,10 @@ export function useCloudUpgradeAction(placement: string): (options?: unknown) =>
         openCloudUpgradePage("cloud", async () => {
           const url = await apiClient.createBrowserHandoff()
             .then((handoff) => handoff.url)
-            .catch(() => CLOUD_UPGRADE_URL);
+            .catch(logFailure("shared.cloud-upgrade", "Create Cloud page handoff failed", CLOUD_UPGRADE_URL));
           await rendererHost.openExternal(url);
         })
-      )).catch(() => {});
+      )).catch(logFailure("shared.cloud-upgrade", "Open Cloud upgrade page failed"));
     };
     if (
       checkout.sheet === false ||

package/src/plugins/builtin/shared/earnings-calendar.ts

@@ -55,7 +55,7 @@ function calendarDateWins(calendar: EarningsDateStatus | null, other: EarningsDa
 }
 
 /** The calendar's report as a quarter on record takes it. */
-interface CalendarReport {
+export interface CalendarReport {
   date: string;
   timing: "bmo" | "amc" | null;
   dateStatus: EarningsDateStatus | null;
@@ -86,7 +86,11 @@ function consensusIsReports(event: EarningsEvent, dateStatus: EarningsDateStatus
   return periodEnd != null && periodEnd < date;
 }
 
-function calendarReport(event: EarningsEvent, today: string): CalendarReport {
+/**
+ * A calendar event read as its report, as every surface reads it: reported
+ * once out, and with a consensus only when it is that report's.
+ */
+export function calendarReport(event: EarningsEvent, today: string): CalendarReport {
   const date = calendarDay(event);
   const dateStatus = calendarStatus(event, today);
   const ownConsensus = consensusIsReports(event, dateStatus, date);

package/src/plugins/builtin/shared/earnings-report.ts

@@ -54,8 +54,8 @@ export function epsBasisShort(basis: EarningsEpsBasis | null): string {
   return basis === "gaap" ? "GAAP" : basis === "adjusted" ? "adj" : "?";
 }
 
-/** Known bases are named in row details; unknown stays in the structured data and drilldown. */
-const BASIS_TEXT: Record<EpsBasisName, string> = { GAAP: "GAAP", adjusted: "adj", unknown: "" };
+/** A reported row's detail names its basis as ERN's Basis column does, unknown included. */
+const BASIS_TEXT: Record<EpsBasisName, string> = { GAAP: "GAAP", adjusted: "adj", unknown: "unknown" };
 
 type EarningsRecord = CorporateActionsData["earnings"][number];
 

package/src/plugins/builtin/shared/job-posting.ts

@@ -34,6 +34,7 @@ export function countryName(code: string | null | undefined): string | null {
   try {
     return countryNames.of(code) ?? null;
   } catch {
+    // Intentional ignore: a region code Intl cannot name is left out of the posting's place.
     return null;
   }
 }

package/src/plugins/builtin/shared/members-menu.tsx

@@ -1,3 +1,4 @@
+import { logFailure } from "../../../utils/log-failure";
 import { ChoiceDialog, TextPromptDialog, usePaneMenuItems } from "../../../components";
 import { createFormCollectionActions } from "../../../components/form-modal/deps";
 import { t, tf } from "../../../i18n";
@@ -195,7 +196,7 @@ export function useMembersMenu(registrationId: string, list: MemberList | null)
         const choice = choices.find((item) => item.id === templateId && !item.disabled);
         // CORR and RIPL resolve `arg` like the command bar; RRG and SIW read `symbols`.
         if (choice) createPaneFromTemplate(choice.id, { symbols: choice.symbols, arg: formatTickerListInput(choice.symbols) });
-      }).catch(() => {});
+      }).catch(logFailure("shared.members-menu", "Open members in a function failed"));
     };
     const saveAsWatchlist = async (requested: string) => {
       // The writes hold the app for about a second with a hundred names; let the dialog close on screen first.
@@ -253,7 +254,7 @@ export function useMembersMenu(registrationId: string, list: MemberList | null)
           saveAsWatchlist(name).catch((error: unknown) => {
             notify({ type: "error", body: error instanceof Error ? error.message : t("The watchlist was not saved.") });
           });
-        }).catch(() => {});
+        }).catch(logFailure("shared.members-menu", "Open save members as watchlist prompt failed"));
       } },
     ];
   }, [createPaneFromTemplate, dialog, disabledPlugins, dispatch, getState, list, notify]);

package/src/plugins/builtin/shared/pro-lock-note.ts

@@ -1,3 +1,4 @@
+import { createTtlCache, type TtlCache } from "../../../data/ttl-cache";
 import type { HeadlessPaneContext } from "../../../types/headless";
 import type { PaneLock } from "../../../types/plugin";
 import { settleWithin, signalWithTimeout } from "../../../utils/async-deadline";
@@ -35,8 +36,7 @@ const ANSWER_TTL_MS = 5 * 60_000;
  */
 const ROUTE_CHECK_WAIT_MS = 3_000;
 
-interface KeptAnswer { at: number; answer: Promise<boolean> }
-const answers = new WeakMap<FreeRoute, Map<string, KeptAnswer>>();
+const answers = new WeakMap<FreeRoute, TtlCache<boolean>>();
 
 /**
  * Whether the route has data for the symbol, null when its check failed or was
@@ -45,20 +45,20 @@ const answers = new WeakMap<FreeRoute, Map<string, KeptAnswer>>();
  * rather than hiding the route for minutes over one slow read.
  */
 async function routeAnswers(route: FreeRoute, check: NonNullable<FreeRoute["answers"]>, symbol: string, context: HeadlessPaneContext, deadline: number): Promise<boolean | null> {
-  const bySymbol = answers.get(route) ?? new Map<string, KeptAnswer>();
+  const bySymbol = answers.get(route) ?? createTtlCache<boolean>({ ttlMs: ANSWER_TTL_MS });
   answers.set(route, bySymbol);
   const key = symbol.trim().toUpperCase();
-  let kept = bySymbol.get(key);
-  if (!kept || Date.now() - kept.at >= ANSWER_TTL_MS) {
+  const kept = bySymbol.load(key, () => {
     // The check's own reads stop at the deadline where they take a signal.
     const signal = signalWithTimeout(context.signal, Math.max(0, deadline - Date.now()));
-    const entry: KeptAnswer = { at: Date.now(), answer: check(symbol, { ...context, signal }) };
-    entry.answer.catch(logFailure("plugins.pro-lock-note", "Check a free route's data failed"));
-    bySymbol.set(key, entry);
-    kept = entry;
-  }
-  const answer = await settleWithin(kept.answer, Math.max(0, deadline - Date.now()));
-  if (answer === null && bySymbol.get(key) === kept) bySymbol.delete(key);
+    return check(symbol, { ...context, signal }).catch((error: unknown) => {
+      logFailure("plugins.pro-lock-note", "Check a free route's data failed")(error);
+      throw error;
+    });
+  });
+  const answer = await settleWithin(kept, Math.max(0, deadline - Date.now()));
+  // Only this check is dropped: a newer one for the symbol stays.
+  if (answer === null) bySymbol.delete(key, kept);
   return answer;
 }
 

package/src/plugins/builtin/shared/report-freshness.ts

@@ -1,3 +1,4 @@
+import { logFailure } from "../../../utils/log-failure";
 import type { HeadlessPaneFreshness } from "../../../types/headless";
 import type { Quote, QuoteIndexSession } from "../../../types/financials";
 import { isQuoteBeforeLatestSession, isQuoteStaleForCurrentSession } from "../../../market-data/quotes/freshness";
@@ -129,8 +130,8 @@ export async function cloudRealtimeAccess(): Promise<boolean | null> {
   if (!apiClient.isSignedIn()) return false;
   try {
     return hasProAccess(apiClient.getCurrentUser() ?? await apiClient.getSession());
-  } catch {
-    return null;
+  } catch (error) {
+    return logFailure("shared.report-freshness", "Read Cloud plan for report freshness failed", null)(error);
   }
 }
 

package/src/plugins/builtin/shared/ticker-choice.tsx

@@ -1,3 +1,4 @@
+import { logFailure } from "../../../utils/log-failure";
 import { useCallback } from "react";
 import { ChoiceDialog } from "../../../components/ui/choice-dialog";
 import { t } from "../../../i18n";
@@ -29,6 +30,6 @@ export function useOpenTickerChoice(): (symbols: readonly string[]) => void {
       ),
     }).then((symbol) => {
       if (symbol) openTicker(symbol);
-    }).catch(() => {});
+    }).catch(logFailure("shared.ticker-choice", "Open ticker choice failed"));
   }, [dialog, openTicker]);
 }

package/src/plugins/builtin/shared/ticker-company.ts

@@ -0,0 +1,77 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import { isNoSourceAnswer } from "../../../sources/provider-errors";
+import type { DataProvider } from "../../../types/data-provider";
+import { shortCompanyName } from "../../../tickers/company-name";
+import { classifyInstrumentKind } from "../../../tickers/search/ranking";
+
+/**
+ * A search typed as a ticker (`TRIAL VKTX`, `FDA AZN`): one to five letters,
+ * with a share class. Registries know companies by name, so a symbol no record
+ * mentions is looked up as its company.
+ */
+export function looksLikeTicker(term: string): boolean {
+  return /^[A-Za-z]{1,5}(?:[.-][A-Za-z])?$/.test(term.trim());
+}
+
+/**
+ * The company a ticker is, by the name a registry files its records under:
+ * VKTX is "Viking Therapeutics", AZN "AstraZeneca". Read from the listing's
+ * quote, which names it; a fund or a contract is no company. Null when no
+ * share trades under it. A quote that could not be read (unreachable, busy,
+ * timed out) rejects: it says nothing about the company.
+ */
+export async function tickerCompanyName(dataProvider: Pick<DataProvider, "getQuote"> | null, ticker: string): Promise<string | null> {
+  const symbol = ticker.trim().toUpperCase();
+  if (!dataProvider || !symbol) return null;
+  const quote = await dataProvider.getQuote(symbol).catch((error: unknown) => {
+    if (isNoSourceAnswer(error)) return null;
+    throw error;
+  });
+  const name = quote?.name?.trim();
+  const kind = classifyInstrumentKind(quote?.instrumentType);
+  return name && kind !== "fund" && kind !== "derivative" ? shortCompanyName(name) : null;
+}
+
+export interface TickerCompanySearch {
+  /** The company is being looked up: the pane shows it loading. */
+  resolving: boolean;
+  /** The lookup failed, for the pane's unavailable state; null otherwise. */
+  error: string | null;
+  /** Looks again after a failure: the pane's refresh calls it. */
+  retry: () => void;
+}
+
+/**
+ * A search for a ticker that found nothing is searched again as its company's
+ * name: `onCompany` runs with it, once per `key` (the term as the pane compares
+ * it). `eligible` is true once the search has finished empty and the term reads
+ * as a ticker. A lookup that failed is no answer: it reports `error` until
+ * `retry`, or until the term changes and comes back.
+ */
+export function useTickerCompanySearch(
+  dataProvider: Pick<DataProvider, "getQuote"> | null,
+  term: string,
+  { eligible, key, onCompany }: { eligible: boolean; key: string; onCompany: (name: string) => void },
+): TickerCompanySearch {
+  const [looked, setLooked] = useState<ReadonlySet<string>>(() => new Set());
+  const [failed, setFailed] = useState<string | null>(null);
+  // A failure belongs to its term: another search clears it, so coming back looks again.
+  if (failed !== null && failed !== key) setFailed(null);
+  const onCompanyRef = useRef(onCompany);
+  onCompanyRef.current = onCompany;
+  const resolving = eligible && !looked.has(key) && failed !== key;
+  useEffect(() => {
+    if (!resolving) return;
+    let live = true;
+    tickerCompanyName(dataProvider, term).then((name) => {
+      if (!live) return;
+      setLooked((current) => new Set([...current, key]));
+      if (name) onCompanyRef.current(name);
+    }, () => {
+      if (live) setFailed(key);
+    });
+    return () => { live = false; };
+  }, [dataProvider, key, resolving, term]);
+  const retry = useCallback(() => setFailed(null), []);
+  return { resolving, error: eligible && failed === key ? `Couldn't look up ${term}'s company.` : null, retry };
+}

package/src/plugins/builtin/shared/use-quote-board.ts

@@ -1,3 +1,4 @@
+import { logFailure } from "../../../utils/log-failure";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import type { DataTableCell, DataTableVisibleRange, PaneFooterSegment } from "../../../components";
 import { savedCopyFooterSegment } from "../../../components/layout/pane/footer/model";
@@ -341,7 +342,7 @@ export function useQuoteBoard(symbols: string[], options: QuoteBoardOptions = {}
         if (fetchGenRef.current !== gen) return;
         setSnapshots((prev) => paintCachedQuotes(prev, cached));
       })
-      .catch(() => {});
+      .catch(logFailure("shared.use-quote-board", "Paint cached board quotes failed"));
   }, [dataProvider]);
 
   /** The cache-first full load: the listed symbols' cached quotes at once, then from the network. */