gloomberb 0.19.0 → 0.19.2

package/src/plugins/builtin/clinical-trials/sponsor-tickers.ts

@@ -7,16 +7,19 @@ import {
   type OrganizationTicker,
 } from "../../../api-client/organization-tickers";
 import { createTtlCache, type TtlCache } from "../../../data/ttl-cache";
+import { findSponsorListings, type ListingFinder } from "./sponsor-listing";
 
 /**
- * A lead sponsor's ticker, only ever as Gloom Cloud resolved it. `none` is an
- * answer (no listed company, or a name that fits several); `failed` means it
- * was not looked up at all and says nothing about the sponsor.
+ * A lead sponsor's ticker, as Gloom Cloud resolved it, or, for a company it
+ * has no reviewed name for, as the listing search finds it (`listingSearch`).
+ * `none` is an answer (no listed company, or a name that fits several);
+ * `failed` means it was not looked up at all and says nothing about the
+ * sponsor.
  */
 export type SponsorTicker =
   | { kind: "pending" }
   | { kind: "listed"; ticker: string; exchange: string | null; entityName: string | null }
-  | { kind: "none"; entityName: string | null; ambiguous: boolean }
+  | { kind: "none"; entityName: string | null; ambiguous: boolean; listingSearch?: "done" }
   | { kind: "failed"; reason: string };
 
 /** A ticker only when one company and its listing were found; an ambiguous name never gets one. */
@@ -50,6 +53,8 @@ export class SponsorTickerStore {
   private readonly answers: TtlCache<SponsorTicker>;
   private readonly failures = new Map<string, string>();
   private readonly inFlight = new Set<string>();
+  private readonly searching = new Set<string>();
+  private readonly searchFailures = new Set<string>();
   private readonly listeners = new Set<() => void>();
 
   constructor(private readonly lookup: Lookup, now: () => number = Date.now) {
@@ -104,24 +109,94 @@ export class SponsorTickerStore {
     }));
   }
 
+  /**
+   * `load`, then `searchListings` for the companies among the names, but the
+   * caller waits no longer than `ms`: the lookups go on and tickers fill in
+   * when they answer.
+   */
+  async loadWithin(
+    names: readonly string[],
+    ms: number,
+    signal?: AbortSignal,
+    listings?: { companies: readonly string[]; find?: ListingFinder },
+  ): Promise<void> {
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const patience = new Promise<void>((resolve) => { timer = setTimeout(resolve, ms); });
+    const lookups = this.load(names, signal).then(() => listings ? this.searchListings(listings.companies, listings.find, signal) : undefined);
+    try {
+      await Promise.race([lookups, patience]);
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  /**
+   * Looks the companies Gloom Cloud had no name for up in Gloom Cloud's
+   * search, the one that finds `Bayer` when it is typed, and keeps a primary
+   * listing as the sponsor's ticker (`findSponsorListings` says which names
+   * qualify). Only names Cloud answered with no company, no listing and no
+   * ambiguity are asked: a company it knows, and a name that fits several,
+   * stay as it said. Each name is searched once, all in one request; a search
+   * that failed waits for `retryFailed`, and tells nothing about the sponsor.
+   */
+  async searchListings(names: readonly string[], find: ListingFinder = findSponsorListings, signal?: AbortSignal): Promise<void> {
+    const asked = new Map<string, string>();
+    for (const name of names) {
+      const trimmed = name.trim();
+      const key = sponsorKey(trimmed);
+      const answer = this.answers.peek(key);
+      if (!trimmed || asked.has(key) || this.searching.has(key) || this.searchFailures.has(key)) continue;
+      if (answer?.kind !== "none" || answer.ambiguous || answer.entityName || answer.listingSearch) continue;
+      asked.set(key, trimmed);
+    }
+    if (asked.size === 0) return;
+    const keys = [...asked.keys()];
+    keys.forEach((key) => this.searching.add(key));
+    try {
+      const found = await find([...asked.values()], signal);
+      if (signal?.aborted) return;
+      let changed = false;
+      for (const [key, name] of asked) {
+        const listing = found.get(name) ?? null;
+        this.answers.set(key, listing
+          ? { kind: "listed", ticker: listing.ticker, exchange: listing.exchange, entityName: listing.entityName }
+          : { kind: "none", entityName: null, ambiguous: false, listingSearch: "done" });
+        changed ||= listing !== null;
+      }
+      if (changed) this.listeners.forEach((listener) => listener());
+    } catch {
+      // A failed search says nothing about the sponsor; it is asked again on retry.
+      if (!signal?.aborted) keys.forEach((key) => this.searchFailures.add(key));
+    } finally {
+      keys.forEach((key) => this.searching.delete(key));
+    }
+  }
+
   /** Forgets failed lookups, so the next `load` asks again. */
   retryFailed(): void {
-    if (this.failures.size === 0) return;
+    if (this.failures.size === 0 && this.searchFailures.size === 0) return;
     this.failures.clear();
+    this.searchFailures.clear();
     this.listeners.forEach((listener) => listener());
   }
 }
 
-const sponsorTickerStore = new SponsorTickerStore(async (names, signal) => (
+export const sponsorTickerStore = new SponsorTickerStore(async (names, signal) => (
   validateOrganizationTickers(await apiClient.getCloudOrganizationTickers(names, signal), names)
 ));
 
+export interface SponsorTickersOptions {
+  /** The company sponsors among `names`: the ones Cloud's search may look up when its ticker lookup has no name for them. */
+  companies?: readonly string[];
+  store?: SponsorTickerStore;
+}
+
 /**
  * The tickers for the sponsors on screen. Rows draw at once and tickers fill
  * in when the lookup answers; `retry` asks again for the ones that failed.
  * `sessionKey` changing (a sign-in) retries them too.
  */
-export function useSponsorTickers(names: readonly string[], sessionKey: string, store: SponsorTickerStore = sponsorTickerStore) {
+export function useSponsorTickers(names: readonly string[], sessionKey: string, { companies, store = sponsorTickerStore }: SponsorTickersOptions = {}) {
   const [version, setVersion] = useState(0);
   const [epoch, setEpoch] = useState(0);
   const [signal, setSignal] = useState<AbortSignal | null>(null);
@@ -136,10 +211,13 @@ export function useSponsorTickers(names: readonly string[], sessionKey: string,
     store.retryFailed();
   }, [sessionKey, store]);
   const namesKey = names.join("\n");
+  const companiesKey = (companies ?? []).join("\n");
   useEffect(() => {
     if (!signal || signal.aborted || !namesKey) return;
-    void store.load(namesKey.split("\n"), signal);
-  }, [epoch, namesKey, sessionKey, signal, store, version]);
+    void store.load(namesKey.split("\n"), signal).then(() => {
+      if (companiesKey) return store.searchListings(companiesKey.split("\n"), findSponsorListings, signal);
+    });
+  }, [companiesKey, epoch, namesKey, sessionKey, signal, store, version]);
   const retry = useCallback(() => {
     store.retryFailed();
     setEpoch((current) => current + 1);

package/src/plugins/builtin/clinical-trials/trial-pages.ts

@@ -0,0 +1,50 @@
+import type { PageRequest, RowPage } from "../../../components";
+import type { ClinicalTrial, ClinicalTrialsPage, StudiesQuery } from "./client";
+
+/** What one stage of the list asks the registry for on top of the search: a sponsor class to keep or to leave out. */
+export type TrialStage = Pick<StudiesQuery, "sponsorClasses" | "excludedSponsorClasses">;
+
+/** The companies' studies first and everything else after them. */
+export const COMPANIES_FIRST: readonly TrialStage[] = [{ sponsorClasses: ["INDUSTRY"] }, { excludedSponsorClasses: ["INDUSTRY"] }];
+
+/** Where a page continues: which stage it is in, and the registry's token inside it. */
+interface StageCursor {
+  stage: number;
+  token?: string;
+}
+
+/**
+ * Pages the registry through `stages` one after the other: a stage's studies
+ * come newest first, and when it has no more the next stage starts, so the
+ * list reaches a university's study only once the companies' are in. The
+ * registry pages by an opaque token, which the next page's offset keys; the
+ * first page always starts at the first stage, so a reload starts over. A
+ * stage with nothing in it goes straight on to the next, so an empty page is
+ * never the end of the list while a stage is left. `onPage` runs on a page's
+ * studies before it is handed over.
+ */
+export function createTrialPageLoader({ list, query, stages, onPage }: {
+  list: (query: StudiesQuery, signal: AbortSignal) => Promise<ClinicalTrialsPage>;
+  query: StudiesQuery;
+  stages: readonly TrialStage[];
+  onPage?: (trials: ClinicalTrial[], signal: AbortSignal) => Promise<void>;
+}): (request: Pick<PageRequest, "offset" | "signal">) => Promise<RowPage<ClinicalTrial>> {
+  const cursors = new Map<number, StageCursor>();
+  return async ({ offset, signal }) => {
+    let cursor: StageCursor | undefined = offset === 0 ? { stage: 0 } : cursors.get(offset);
+    while (cursor) {
+      const page: ClinicalTrialsPage = await list({ ...query, ...stages[cursor.stage], pageToken: cursor.token }, signal);
+      const next: StageCursor | null = page.nextPageToken ? { stage: cursor.stage, token: page.nextPageToken }
+        : cursor.stage + 1 < stages.length ? { stage: cursor.stage + 1 } : null;
+      if (page.trials.length === 0 && next && !page.nextPageToken) {
+        cursor = next;
+        continue;
+      }
+      const nextOffset = offset + page.trials.length;
+      if (next) cursors.set(nextOffset, next);
+      await onPage?.(page.trials, signal);
+      return { rows: page.trials, hasMore: !!next, nextOffset };
+    }
+    return { rows: [], hasMore: false };
+  };
+}

package/src/plugins/builtin/commodity-balances/client.ts

@@ -1,4 +1,5 @@
 import { apiClient } from "../../../api-client";
+import { sourceDidNotAnswer } from "../../../api-client/errors";
 import type { PsdBoardPayload } from "../../../api-client/commodity-balances";
 import { unavailableOnServer } from "../shared/cloud-resource";
 import type { BalanceRow, PriceForecast } from "./model";
@@ -37,7 +38,9 @@ function readBoard(payload: PsdBoardPayload): CommodityBalances {
     || (payload.marketYear != null && !text(payload.marketYear))) {
     throw new Error("The server returned an invalid crop balance board");
   }
-  if (payload.status === "unavailable" || payload.rows.length === 0) throw new Error(CROPS_NOT_AVAILABLE);
+  // The server's source did not answer this time, which may pass; a board with no rows has none yet.
+  if (payload.status === "unavailable") throw sourceDidNotAnswer(CROPS_NOT_AVAILABLE);
+  if (payload.rows.length === 0) throw new Error(CROPS_NOT_AVAILABLE);
   return {
     rows: payload.rows,
     prices: payload.prices,

package/src/plugins/builtin/company-attention/headless.ts

@@ -3,6 +3,7 @@ import type { DataTableColumn } from "../../../components";
 import type { AppAttentionPayload, AppChart } from "../../../api-client/app-attention";
 import type { HiringBoard, HiringPayload } from "../../../api-client/hiring";
 import { fetchAppRank, fetchAttention, fetchBuilding, fetchMoves, fetchSignals, type BuildingPayload, type SignalsPayload } from "./client";
+import { companyDataNotes } from "../../../types/company-from";
 import { BUILDING_FILTERS, BUILDING_VIEWS, buildingBoardModel, buildingNumber, buildingPreviewNote, companyBuildingModel, isBuildingFilter, type BuildingSection } from "./building-model";
 import { appsModel, appsPreviewNote, attentionNumber, attentionSectionTitle, attentionTabs, hiringModel, hiringPreviewNote, remoteText, type AttentionKind } from "./model";
 import { companyMovesModel, isMovesFilter, movesBoardModel, movesNumber, movesPreviewNote, MOVES_FILTERS, MOVES_VIEWS, type MovesSection } from "./moves-model";
@@ -146,7 +147,7 @@ export function attentionHeadless(kind: AttentionKind): HeadlessPaneDefinition<"
       const why = movesModel?.latest?.why;
       const company = args.symbols[0] ? signalsReads[0]?.data : undefined;
       const held = company && !("group" in company) && company.held ? holdText(company.held) : null;
-      const notes = [...model.notices, ...(nextOffset !== null ? [`Additional observations available with --offset ${nextOffset}.`] : []),
+      const notes = [...model.notices, ...companyDataNotes("companyFrom" in data ? data.companyFrom : null), ...(nextOffset !== null ? [`Additional observations available with --offset ${nextOffset}.`] : []),
         ...(movesData instanceof Error ? [movesData.message] : []), ...(why ? [why] : []),
         ...(signalsData instanceof Error ? [signalsData.message] : []), ...(held ? [`No expansion or anomaly signal this week: ${held.toLowerCase()}.`] : []),
         ...(buildingData instanceof Error ? [buildingData.message] : []), ...(buildingHeld ? [`No mix to compare this week: ${buildingHeld.toLowerCase()}.`] : [])];

package/src/plugins/builtin/company-attention/pane.tsx

@@ -5,6 +5,7 @@ import { usePlanAccess } from "../../../api-client/plan-access";
 import type { AppAttentionFilter, AppAttentionPayload, AppChart } from "../../../api-client/app-attention";
 import type { HiringBoard, HiringPayload } from "../../../api-client/hiring";
 import { ChartTableHeader, DataTableView, PageStackView, PaneFooterScope, PaneLinkMenu, QueryBar, useChartTableSelection, usePagedRows, useTableLoadMore, usePaneNoticeFooter, usePaneStatusFooter, usePaneTabs, type PaneHint } from "../../../components";
+import { useCompanyDataFooter } from "../../../components/layout/pane/status-footer";
 import { DetailReader, type DetailFact } from "../../../components/reader/detail-reader";
 import type { CloudJobsPostingDetail } from "../../../api-client/types";
 import { descriptionText, postingFacts, postingTitle } from "../shared/job-posting";
@@ -184,6 +185,8 @@ function AttentionView({ kind, symbol, width, height, focused, initialTab }: Siz
   usePaneStatusFooter({ registrationId: `${kind}:status`, enabled: !openCompany && !app && !moves, loading: resource.loading || paged.loadingMore || (!!evidence && postingResource.loading), error: data ? resource.error ?? paged.moreError?.message ?? paged.error?.message : null, stale: resource.data?.stale,
     info: [...(model?.asOf ? [{ id: "observed", asOf: true, parts: [{ text: `as of ${model.asOf.slice(0, 10)}`, tone: "muted" as const }] }] : []), ...(model?.preview ? [{ id: "preview", parts: [{ text: "Pro preview", tone: "warning" as const }] }] : [])], hints });
   usePaneNoticeFooter({ registrationId: `${kind}:notices`, enabled: !openCompany && !app && !moves, focused, notices: [...(model?.notices ?? []), ...(resource.data?.refreshError ? [resource.data.refreshError] : [])] });
+  // A receipt's or foreign line's hiring or apps are its company's, read from the home line.
+  useCompanyDataFooter(data && "companyFrom" in data ? data.companyFrom : null, !openCompany && !app && !moves);
   if (signInWall) return <SignInWall placement={kind === "hiring" ? "hiring-momentum-signin" : "app-attention-signin"} action={kind === "hiring" ? "view hiring momentum" : "view app attention"} needsVerification={session.needsVerification} />;
   const countryOptions = data && kind === "apps" ? (data as AppAttentionPayload).coverage.configuredCountries : [];
   const query = kind === "hiring" && tab !== "mix" ? undefined : <QueryBar width={width} filters={kind === "apps" ? [

package/src/plugins/builtin/company-kpis/headless.ts

@@ -1,11 +1,12 @@
 import type { DataTableColumn } from "../../../components";
 import { DATE_OPTION_EXAMPLES, isoDateOption } from "../../../utils/calendar-date";
 import { optionFlag } from "../../../cli/pane-functions/capabilities";
+import { companyDataNotes } from "../../../types/company-from";
 import type { HeadlessBundleSection, HeadlessPaneColumn, HeadlessPaneDefinition } from "../../../types/plugin";
 import { withoutQuietColumns } from "../shared/research-cells";
 import { resolveHeadlessIssuerListing } from "../shared/headless-market-data";
 import { companyQuery, fetchCompanyData, type CompanyDataset, type CompanyMode } from "./client";
-import { allGuidance, allObservations, companyCellText, companyColumns, companyPreviewNote, KPI_COVERAGE_NOTE, kpiFreeLimitNote, QUIET_COLUMNS,
+import { allGuidance, allObservations, companyCellText, companyColumns, companyEmptyState, companyPreviewNote, KPI_COVERAGE_NOTE, kpiFreeLimitNote, QUIET_COLUMNS,
   type CompanyRow } from "./model";
 import type { KpiObservation } from "../../../api-client/company-kpis";
 
@@ -107,8 +108,12 @@ export function companyHeadless(mode: CompanyMode): HeadlessPaneDefinition<"bund
       const latest = ("series" in data ? data.series.map((series) => series.latest) : data.guidance).filter(keep);
       const ignored = data.access === "preview" ? PRO_FILTERS.filter((key) => typeof args.options[key] === "string" && args.options[key] !== "") : [];
       const notes = [ageNote(data, latest, mode),
-        ignored.length ? `The free preview is fixed: ${ignored.map(optionFlag).join(", ")} ${ignored.length > 1 ? "need" : "needs"} Gloom Pro.` : null].filter((note): note is string => !!note);
-      return { complete: !data.truncated, errors: data.truncated ? [data.access === "preview" ? companyPreviewNote(data, mode === "guidance") : "Response limit reached; narrow the metric or date range"] : [],
+        ignored.length ? `The free preview is fixed: ${ignored.map(optionFlag).join(", ")} ${ignored.length > 1 ? "need" : "needs"} Gloom Pro.` : null,
+        ...companyDataNotes(data.companyFrom)].filter((note): note is string => !!note);
+      // A company with nothing on file says so once, as the pane does, rather than "not covered".
+      const nothingOnFile = datasetRows(data).length === 0 && data.lockedRows === 0 && !requested;
+      const { title, hint } = companyEmptyState(mode, symbol, { tab: "table", hasRows: !nothingOnFile }, "cli");
+      return { complete: !data.truncated, ...(nothingOnFile ? { empty: `${title} ${hint}` } : {}), errors: data.truncated ? [data.access === "preview" ? companyPreviewNote(data, mode === "guidance") : "Response limit reached; narrow the metric or date range"] : [],
         ...(notes.length ? { notes } : {}),
         sections: "series" in data ? [
           section("Latest KPIs", data.series.map((series) => series.latest), { first: true }),

package/src/plugins/builtin/company-kpis/model.ts

@@ -1,9 +1,11 @@
 import type { GuidancePayload, KpiGuidance, KpiObservation, KpiSeries, KpiUnit, KpisPayload } from "../../../api-client/company-kpis";
 import type { DataTableColumn } from "../../../components";
 import { scalarPoint, staticSeries } from "../../../components/chart/static/series";
+import { getTableWidth, tableColumnWidth } from "../../../components/ui/table-layout";
 import type { CompositeChartXAxis } from "../../../components/chart/composite/types";
 import { formatCompact, formatNumber } from "../../../utils/format";
 import { freePreviewNote } from "../shared/free-preview";
+import type { CompanyMode } from "./client";
 
 export type CompanyRow = KpiObservation | KpiGuidance;
 export const isGuidance = (row: CompanyRow): row is KpiGuidance => "issuedDate" in row;
@@ -89,13 +91,30 @@ function unitSuffix(row: Pick<CompanyRow, "unit" | "currency" | "dimensions">):
   if (row.unit === "currency_per_unit" || row.unit === "volume") return ` ${unitLabel(row)}`;
   return "";
 }
-/** Raised reads as good news, a cut as bad, a reiteration as no news. */
-export const directionTone = (direction: KpiGuidance["direction"]) => direction === "raised" ? "positive" as const : direction === "cut" ? "negative" as const
-  : direction === "withdrawn" ? "warning" as const : direction === "initiated" ? "text" as const : "muted" as const;
+/** Raised reads as good news, a cut as bad, a reiteration as no news, and a New guide as itself whichever way the service reached it. */
+export const directionTone = (guide: Pick<KpiGuidance, "direction" | "previousId">) => guide.direction === "raised" ? "positive" as const : guide.direction === "cut" ? "negative" as const
+  : guide.direction === "withdrawn" ? "warning" as const : directionLabel(guide) === "New" ? "text" as const : "muted" as const;
 /** A change is good when it moves the way the metric's owner wants it to. */
 export const changeTone = (row: KpiObservation, value: number | null) => value === null || value === 0 || row.metric.favorable === "neutral" ? "muted" as const
   : (value > 0) === (row.metric.favorable === "higher") ? "positive" as const : "negative" as const;
-export const directionLabel = (direction: KpiGuidance["direction"]) => direction === "not_comparable" ? "Not comparable" : direction.charAt(0).toUpperCase() + direction.slice(1);
+/**
+ * What a guide did against the one before it for the same period, in plain
+ * words. A guide with no earlier one to set it against is New, whether it is
+ * the company's first or the first for its period. The service sets a guide it
+ * cannot rank (a different hedge or conditions) beside its predecessor as not
+ * comparable: that one Changed, with no word for up or down.
+ */
+export function directionLabel(guide: Pick<KpiGuidance, "direction" | "previousId">): string {
+  switch (guide.direction) {
+    case "raised": return "Raised";
+    case "cut": return "Lowered";
+    case "reiterated": return "Maintained";
+    case "mixed": return "Mixed";
+    case "withdrawn": return "Withdrawn";
+    case "initiated": return "New";
+    case "not_comparable": return guide.previousId ? "Changed" : "New";
+  }
+}
 export const outcomeLabel = (row: KpiGuidance) => !row.actual ? "Pending" : row.actual.favorable === "in_line" ? "In range"
   : row.actual.favorable === "neutral" ? row.actual.outcome === "above" ? "Above" : row.actual.outcome === "below" ? "Below" : "In range"
   : row.actual.favorable === "beat" ? "Beat" : "Miss";
@@ -163,7 +182,7 @@ export const QUIET_COLUMNS = { basis: ["Reported"], scope: ["Consolidated"] };
 /** The text of a table cell as the pane draws it; the report prints the same words. */
 export function companyCellText(row: CompanyRow, column: string, observations: KpiObservation[]): string {
   const guide = isGuidance(row) ? row : null;
-  if (column === "change") return guide ? directionLabel(guide.direction) : changeText(observationChange(row as KpiObservation, observations));
+  if (column === "change") return guide ? directionLabel(guide) : changeText(observationChange(row as KpiObservation, observations));
   return column === "metric" ? row.metric.name : column === "period" ? fiscalLabel(row) : column === "value" ? `${guide ? rangeText(guide) : observationValue(row as KpiObservation)}${guide?.status === "withdrawn" || guide?.hedge === "qualitative" ? "" : unitSuffix(row)}`
     : column === "unit" ? unitLabel(row)
     : column === "basis" ? basisLabel(row.basis) : column === "scope" ? dimensionLabel(row.dimensions) || "Consolidated"
@@ -195,6 +214,55 @@ export function companyColumns(guidance: boolean, evidence: boolean, history: bo
   return order ? shown.sort((a, b) => order.indexOf(a.id) - order.indexOf(b.id)) : shown;
 }
 
+/** Cells a column gives up on a narrow pane, before any column is dropped: a date needs 10, a range about 19. */
+const NARROW_WIDTHS: Record<string, number> = { value: 19, change: 11, issued: 10, actual: 12, outcome: 9, basis: 12, scope: 18 };
+/** The metric keeps at least this much: a name such as "Revenue growth", and its series detail only when there is room. */
+const METRIC_FLOOR = 14;
+
+/**
+ * The table's columns at a pane `width` in cells, so none is cut at the right edge.
+ * A table that already fits is left as it is. Otherwise the columns take their
+ * narrow widths, and the metric, which flexes, keeps what is left down to its
+ * floor. Below that a column whose meaning is in the detail goes (Action in History,
+ * where the outcome says it, then Issued), never one that names the row. A table that
+ * cannot fit even so keeps its narrow widths and scrolls sideways, as it always has.
+ */
+export function fitCompanyColumns(columns: readonly DataTableColumn[], width: number, history = false): DataTableColumn[] {
+  const room = width - 1;
+  if (getTableWidth(columns) <= room) return [...columns];
+  const narrow = (list: readonly DataTableColumn[]) => list.map((column) => column.id in NARROW_WIDTHS ? { ...column, width: Math.min(column.width, NARROW_WIDTHS[column.id]!) } : column);
+  const attempt = (list: readonly DataTableColumn[]): DataTableColumn[] | null => {
+    const tight = narrow(list);
+    const metric = tight.find((column) => column.id === "metric");
+    if (!metric) return getTableWidth(tight) <= room ? tight : null;
+    const fitted = Math.min(metric.width, room - (getTableWidth(tight) - tableColumnWidth(metric)));
+    return fitted >= METRIC_FLOOR ? tight.map((column) => column === metric ? { ...column, width: fitted } : column) : null;
+  };
+  let shown = [...columns];
+  for (const drop of [null, ...(history ? ["change", "issued"] : ["issued"])]) {
+    if (drop) shown = shown.filter((column) => column.id !== drop);
+    const fitted = attempt(shown);
+    if (fitted) return fitted;
+  }
+  return narrow(columns);
+}
+
+/** Companies to point an empty pane at, one that has data and one for when the pane is for the first. */
+const EXAMPLE_COMPANIES: Record<CompanyMode, readonly string[]> = { guidance: ["WMT", "DAL"], kpis: ["AAPL", "NVDA"] };
+
+/**
+ * What an empty table says. A company with nothing on file for the function says so
+ * plainly and names one that has some; a selection or tab that narrows what the company
+ * has says what is missing from it. `cli` types `fn GUIDE WMT`, the app's command bar `GUIDE WMT`.
+ */
+export function companyEmptyState(mode: CompanyMode, symbol: string, view: { tab: string; hasRows: boolean }, surface: "cli" | "pane" = "pane"): { title: string; hint?: string } {
+  if (view.hasRows) return { title: view.tab === "history" ? "Actuals have not been matched to these guidance periods yet." : "No disclosed observations for this selection yet." };
+  const examples = EXAMPLE_COMPANIES[mode];
+  const example = examples.find((candidate) => candidate !== symbol.trim().toUpperCase()) ?? examples[0]!;
+  const command = `${mode === "kpis" ? "KPIS" : "GUIDE"} ${example}`;
+  return { title: `No ${mode === "kpis" ? "KPIs" : "guidance"} on file for ${symbol}.`, hint: `Try ${surface === "cli" ? `\`fn ${command}\`` : command}.` };
+}
+
 /** What a missing KPI means, as KPIS states it among its limitations and EQS beside a KPI column with gaps. */
 export const KPI_COVERAGE_NOTE = "Coverage follows available company disclosures; missing data is not zero.";
 

package/src/plugins/builtin/company-kpis/pane.tsx

@@ -5,6 +5,7 @@ import type { KpiObservation } from "../../../api-client/company-kpis";
 import { listingAbroad } from "../../../api-client/paths";
 import { ChartTableHeader, DataTableStackView, DetailScrollBody, EmptyState, KeyValueRow, PaneStatusBody, QueryBar, SectionHeading,
   useChartTableSelection, usePaneMenuItems, usePaneNoticeFooter, usePaneStatusFooter, usePaneTabs, type DataTableCell, type PaneHint } from "../../../components";
+import { useCompanyDataFooter } from "../../../components/layout/pane/status-footer";
 import { usePaneRefreshKey } from "../../../components/data-table/table-pane";
 import { useAsyncResource, useAutoRefresh, usePaneSettingValue, usePluginAppActions, usePluginPaneState } from "../../../public/react";
 import { usePaneTickerIdentity } from "../../../state/hooks/pane-ticker";
@@ -20,7 +21,7 @@ import { Blurred, LockedOverlay, UpgradeLabel } from "../shared/locked-rows";
 import { isCloudSessionRequired, useResearchCloudSession } from "../shared/research-cloud-session";
 import { cachedCompanyData, loadCompanyData, KPI_UNAVAILABLE, validateCompanyData, type CompanyDataset, type CompanyMode } from "./client";
 import { useCompanyEvidence } from "./screenshot-evidence";
-import { allGuidance, allObservations, basisLabel, changeText, changeTone, companyCellText, companyColumns, dimensionLabel, directionLabel, directionTone, guideGroupKey, guidanceSeries, fiscalLabel,
+import { allGuidance, allObservations, basisLabel, changeText, changeTone, companyCellText, companyColumns, companyEmptyState, dimensionLabel, directionLabel, directionTone, fitCompanyColumns, guideGroupKey, guidanceSeries, fiscalLabel,
   isGuidance, exactObservation, observationValue, observationChange, observationChart, periodOrder, outcomeLabel, QUIET_COLUMNS, rangeText, scopeWords, seriesDetail, seriesLabel, seriesLabels, seriesName,
   seriesOrder, unitLabel, valueText, companyPreviewNote, type CompanyRow } from "./model";
 import { PriceSparkline } from "../../../components/price-sparkline/view";
@@ -47,7 +48,7 @@ function DisclosureEvidence({ row, sourceId, onSource, width }: { row: CompanyRo
     <KeyValueRow label="Revision" value={`${row.revision}${row.current ? " · current" : " · superseded"}${!isGuidance(row) && (row.conflict || row.contested) ? " · conflicting disclosures" : ""}`} labelWidth={18} />
     {row.revisionReason ? <KeyValueRow label="Correction" value={row.revisionReason} labelWidth={18} /> : null}
     {isGuidance(row) ? <>
-      <KeyValueRow label="Issued" value={row.issuedDate} detail={directionLabel(row.direction)} labelWidth={18} />
+      <KeyValueRow label="Issued" value={row.issuedDate} detail={directionLabel(row)} labelWidth={18} />
       <KeyValueRow label="Source range" value={row.rangeText} labelWidth={18} />
       {row.conditions ? <KeyValueRow label="Conditions" value={row.conditions} labelWidth={18} /> : null}
       <KeyValueRow label="Later actual" value={row.actual ? valueText(row, row.actual.value) : "Pending"} detail={row.actual ? outcomeLabel(row) : undefined} labelWidth={18} />
@@ -130,7 +131,7 @@ function CompanyView({ symbol, exchange, name, mode, width, height, focused }: P
         : sort.column === "actual" ? guide?.actual?.value ?? null : sort.column === "outcome" ? guide ? outcomeLabel(guide) : null
         : sort.column === "basis" ? row.basis : sort.column === "unit" ? unitLabel(row) : sort.column === "scope" ? dimensionLabel(row.dimensions)
         : sort.column === "published" ? row.evidence[0]!.publishedAt : sort.column === "revision" ? row.revision
-        : sort.column === "quote" ? row.evidence[0]!.quote : sort.column === "change" ? guide ? guide.direction : observationChange(row as KpiObservation, observations).value
+        : sort.column === "quote" ? row.evidence[0]!.quote : sort.column === "change" ? guide ? directionLabel(guide) : observationChange(row as KpiObservation, observations).value
         : periodOrder(row);
     };
     const direction = sort.direction === "asc" ? 1 : -1;
@@ -158,8 +159,13 @@ function CompanyView({ symbol, exchange, name, mode, width, height, focused }: P
     }
     return map;
   }, [kpis]);
-  const columns = useMemo(() => withoutQuietColumns(companyColumns(mode === "guidance", tab === "evidence", tab === "history", mode === "kpis" && tab === "table" && trends.size > 0 && width >= 100, desktop),
-    rows, (row, id) => id === "basis" ? basisLabel(row.basis) : id === "scope" ? dimensionLabel(row.dimensions) || "Consolidated" : "", QUIET_COLUMNS), [mode, tab, trends, rows, width, desktop]);
+  const columns = useMemo(() => {
+    const shown = withoutQuietColumns(companyColumns(mode === "guidance", tab === "evidence", tab === "history", mode === "kpis" && tab === "table" && trends.size > 0 && width >= 100, desktop),
+      rows, (row, id) => id === "basis" ? basisLabel(row.basis) : id === "scope" ? dimensionLabel(row.dimensions) || "Consolidated" : "", QUIET_COLUMNS);
+    // Evidence is a wide ledger that scrolls; the other tabs fit the pane.
+    return tab === "evidence" ? shown : fitCompanyColumns(shown, width, tab === "history");
+  }, [mode, tab, trends, rows, width, desktop]);
+  const emptyState = companyEmptyState(mode, symbol ?? "", { tab, hasRows: allRows.length > 0 });
   const metricOptions = useMemo(() => [{ value: "all", label: "All metrics" }, ...[...new Map(allRows.map((row) => [row.metricId, { value: row.metricId, label: row.metric.name }])).values()]], [allRows]);
   const kpiChart = useMemo(() => observationChart(rows.filter((row): row is KpiObservation => !isGuidance(row)), colors.warning), [rows, colors.warning]);
   const series = useMemo(() => tab !== "chart" ? [] : mode === "kpis" ? kpiChart.series
@@ -190,6 +196,8 @@ function CompanyView({ symbol, exchange, name, mode, width, height, focused }: P
   usePaneNoticeFooter({ registrationId: "company-kpis:notices", focused, notices: [resource.data?.refreshError,
     data?.truncated && data.access === "full" ? "The response reached its stored-record limit. Narrow the metric or date range in a CLI or REST query." : null,
     data?.coverage.conflicts ? "Conflicting disclosures are retained in Evidence and excluded from comparable trends." : null].filter((value): value is string => !!value) });
+  // A receipt's or foreign line's disclosures are its company's, read from the home line.
+  useCompanyDataFooter(data?.companyFrom);
   if (!symbol) return <EmptyState title="Select a ticker." />;
   if (signInWall) return <SignInWall placement="company-kpis-signin" action={mode === "guidance" ? "view company guidance" : "view company KPIs"} needsVerification={session.needsVerification} />;
   const bodyHeight = Math.max(3, height - tabRows);
@@ -212,7 +220,7 @@ function CompanyView({ symbol, exchange, name, mode, width, height, focused }: P
       return { text: "", content: <PriceSparkline priceHistory={points} width={column.width} period="all" trend={tone === "muted" ? "neutral" : tone} /> };
     }
     if (column.id === "change") {
-      if (guide) return { text: directionLabel(guide.direction), color: toneColor(directionTone(guide.direction), colors), keepColorWhenSelected: guide.direction === "raised" || guide.direction === "cut" };
+      if (guide) return { text: directionLabel(guide), color: toneColor(directionTone(guide), colors), keepColorWhenSelected: guide.direction === "raised" || guide.direction === "cut" };
       const change = observationChange(row as KpiObservation, observations);
       return { text: changeText(change), value: change.value, color: toneColor(changeTone(row as KpiObservation, change.value), colors) };
     }
@@ -244,7 +252,7 @@ function CompanyView({ symbol, exchange, name, mode, width, height, focused }: P
         detailScrollRef={detailScrollRef} detailContent={openRow ? <DetailScrollBody ref={detailScrollRef} resetScrollKey={openRow.id}><DisclosureEvidence row={openRow} sourceId={sourceId} onSource={setSource} width={width} /></DetailScrollBody> : null}
         sortColumnId={sort.column} sortDirection={sort.direction} onHeaderClick={(column) => setSort((previous) => ({ column, direction: previous.column === column && previous.direction === "desc" ? "asc" : "desc" }))}
         resetScrollKey={`${mode}:${symbol}:${tab}:${metric}:${activePlot}`}
-        emptyStateTitle={tab === "history" ? "Actuals have not been matched to these guidance periods yet." : "No disclosed observations for this selection yet."}
+        emptyStateTitle={emptyState.title} emptyStateHint={emptyState.hint}
         rootBefore={<ChartTableHeader width={width} height={bodyHeight} tableRows={items.length} tableColumns={columns} query={query}
           chart={tab === "chart" ? { series, ...(mode === "kpis" ? { xAxis: kpiChart.xAxis, viewport: kpiChart.viewport } : {}), empty: preview ? "Full history is available with Pro." : "History is accumulating. Two comparable disclosures are needed for a trend.",
             formatValue: (value) => selected ? `${valueText(selected, value)}${selected.currency ? ` ${unitLabel(selected)}` : ""}` : String(value),

package/src/plugins/builtin/composite-plugins.ts

@@ -14,6 +14,7 @@ import { portfolioAnalyticsModule } from "./analytics";
 import { brokerTradingModule } from "./broker-trading";
 import { brokerManagerModule } from "./broker-manager";
 import { changelogModule } from "./changelog";
+import { roadmapModule } from "./roadmap";
 import { connectionsModule } from "./connections";
 import { pluginMarketplaceModule } from "./plugin-marketplace";
 import { relativeRotationModule } from "./relative-rotation";
@@ -116,7 +117,7 @@ import { FIXED_INCOME_HOSTS } from "./fixed-income/model";
 
 export const applicationPlugin = composeBuiltinPlugin({
   ...applicationPluginMeta,
-  modules: [layoutManagerModule, pluginMarketplaceModule, helpModule, changelogModule, connectionsModule, docsModule],
+  modules: [layoutManagerModule, pluginMarketplaceModule, helpModule, changelogModule, connectionsModule, docsModule, roadmapModule],
 });
 
 export const portfolioPlugin = composeBuiltinPlugin({

package/src/plugins/builtin/cot/client.ts

@@ -3,7 +3,10 @@ import type { CotBoardPayload, CotClass, CotClassSummary, CotContractPayload, Co
 import { createPluginCache } from "../../../data/plugin-cache";
 import { cachedCloudResource, loadCloudResource, unavailableOnServer } from "../shared/cloud-resource";
 import type { PricePoint } from "../../../types/financials";
-import { COT_CLASSES, cotPriceMapping } from "./model";
+import { COT_CLASSES, cotFrontPriceUnit, cotPriceMapping } from "./model";
+import { futuresPriceUnit, loadFuturesContractTerms, loadFuturesPriceUnit } from "../../../market-data/futures-contract";
+import { futuresBoardContract } from "../../../market-data/futures-board";
+import { settleWithin } from "../../../utils/async-deadline";
 
 export const cotBoardCache = createPluginCache<CotBoardPayload>({ kind: "cot-board", source: "gloom-cloud", schemaVersion: 1,
   policy: { staleMs: 15 * 60_000, expireMs: 8 * 24 * 60 * 60_000 } });
@@ -88,7 +91,12 @@ export async function fetchCotContract(contractCode: string, family: CotFamily,
   catch (error) { throw unavailable(error); }
 }
 export interface CotDetailData { payload: CotContractPayload; price: PricePoint[]; priceSymbol: string | null; priceAsOf: string | null; priceWarning: string | null }
-export async function loadCotDetail(contractCode: string, family: CotFamily, client: Pick<typeof apiClient, "getCloudCotContract" | "getCloudHistory"> = apiClient,
+/**
+ * A market's report and its front price. The price's unit is not waited for
+ * here: it joins the legend when it is known (loadCotPriceUnit).
+ */
+export async function loadCotDetail(contractCode: string, family: CotFamily,
+  client: Pick<typeof apiClient, "getCloudCotContract" | "getCloudHistory"> = apiClient,
   positions: CotPositions = "futures-only"): Promise<CotDetailData> {
   const payload = await fetchCotContract(contractCode, family, client, positions);
   const mapping = cotPriceMapping(contractCode);
@@ -109,3 +117,21 @@ export async function loadCotDetail(contractCode: string, family: CotFamily, cli
       priceWarning: result.stale ? "Front-price history is stale." : price.length ? null : "Front-price history unavailable." };
   } catch { return { payload, price: [], priceSymbol: mapping.priceSymbol, priceAsOf: null, priceWarning: "Front-price history unavailable. Positioning remains available." }; }
 }
+
+/** How long the front price's legend waits for the contract terms before it writes the catalog's unit. */
+const COT_PRICE_UNIT_WAIT_MS = 1_500;
+
+/**
+ * The unit a market's front price is written in, as its legend writes it
+ * after the price (cotFrontPriceUnit): `USD/gal` for heating oil. It is the
+ * contract terms' unit, else the futures catalog's where the terms fail or
+ * have not answered within `waitMs`; null for a market with no front price.
+ * The chart draws without it, so a slow answer never holds the detail up.
+ */
+export async function loadCotPriceUnit(contractCode: string, client: Pick<typeof apiClient, "getCloudFuturesContract"> = apiClient,
+  waitMs = COT_PRICE_UNIT_WAIT_MS): Promise<string | null> {
+  const symbol = cotPriceMapping(contractCode)?.priceSymbol;
+  if (!symbol) return null;
+  const terms = await settleWithin(loadFuturesPriceUnit(symbol, (key) => loadFuturesContractTerms(key, client)), waitMs);
+  return cotFrontPriceUnit(contractCode, terms ?? futuresPriceUnit(futuresBoardContract(symbol), null));
+}

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

@@ -1,7 +1,7 @@
 import type { CotClass, CotClassSummary, CotContractPayload, CotHistoryPoint } from "../../../api-client/cot";
 import type { HeadlessPaneColumn, HeadlessPaneDefinition } from "../../../types/plugin";
 import { fetchCotBoard, fetchCotContract } from "./client";
-import { COT_CLASSES, COT_FAMILIES, COT_MAJOR_CODES, COT_POSITIONS, COT_SCOPES, cotClass, cotContractCode, cotContractUnitText, cotFamily, cotInteger, cotMarketName, cotPositions, cotPositionsText, cotScope, cotUnknownMarketMessage } from "./model";
+import { COT_CLASSES, COT_FAMILIES, COT_MAJOR_CODES, COT_POSITIONS, COT_SCOPES, cotClass, cotContractCode, cotContractUnitText, cotFamily, cotInteger, cotMarketName, cotPositions, cotPositionsText, cotProxyFor, cotProxyNote, cotScope, cotUnknownMarketMessage } from "./model";
 import { COMMODITIES_VIEW_STATE } from "../commodities-energy/view-state";
 import { REPORT_ROWS } from "../shared/headless-options";
 
@@ -67,6 +67,7 @@ export const cotHeadless: HeadlessPaneDefinition<"bundle"> = {
     if (args.argument) {
       const code = cotContractCode(args.argument);
       if (!code) throw new Error(cotUnknownMarketMessage(args.argument));
+      const proxy = cotProxyFor(args.argument);
       const data = await fetchCotContract(code, family, ctx.apiClient, positions);
       const classes = data.positions.map((row) => row.id);
       const limit = args.options.limit == null ? null : Number(args.options.limit);
@@ -80,6 +81,8 @@ export const cotHeadless: HeadlessPaneDefinition<"bundle"> = {
           ...classes.map((id) => ({ key: `${camelClass(id)}Net`, header: `${data.positions.find((row) => row.id === id)?.label ?? id} net`, align: "right" as const, format: signed }))],
         rows: weeks.map((row) => ({ reportDate: row.reportDate, openInterest: row.openInterest,
           ...Object.fromEntries(row.positions.map((position) => [`${camelClass(position.id)}Net`, position.net])) })) }],
+      // "jet fuel" reads heating oil's positions, and says so.
+      ...(proxy ? { notes: [cotProxyNote(proxy)] } : {}),
       errors: data.gaps, metadata: { ...data, complete: data.status === "available" } };
     }
     const traderClass = cotClass(family, args.options.traderClass);

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

@@ -1,7 +1,7 @@
 import type { PluginModule } from "../plugin-module";
 import { cotBoardCache } from "./client";
 import { cotHeadless } from "./headless";
-import { COT_ROOT_OPTIONS, cotContractCode, cotContractCodeForTicker, cotRoot, cotUnknownMarketMessage } from "./model";
+import { COT_ROOT_OPTIONS, cotContractCode, cotContractCodeForTicker, cotProxyFor, cotRoot, cotUnknownMarketMessage } from "./model";
 import { CotPane } from "./pane";
 import { COT_SERIES } from "./series";
 
@@ -19,7 +19,9 @@ export const cotModule: PluginModule = {
       const input = options?.arg?.trim();
       const code = input ? cotContractCode(input) : cotContractCodeForTicker(context.activeTicker);
       if (input && !code) throw new Error(cotUnknownMarketMessage(input));
-      return { title: code ? `COT ${cotRoot(code) ?? code}` : "CFTC Positioning", params: code ? { code } : undefined,
+      // "jet fuel" opens heating oil, and the title says which market stands in.
+      const proxy = input ? cotProxyFor(input) : null;
+      return { title: code ? `COT ${cotRoot(code) ?? code}${proxy ? ` (${proxy.subject} proxy)` : ""}` : "CFTC Positioning", params: code ? { code } : undefined,
         settings: { report: options?.values?.report ?? "legacy" }, placement: "floating" as const };
     },
   }],