gloomberb 0.18.0 → 0.18.2

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

@@ -1,13 +1,25 @@
 import type { HeadlessPaneDefinition } from "../../../types/plugin";
 import { fetchCommodityBalances } from "./client";
-import { formatBalanceValue, formatForecast } from "./model";
+import { cropEstimateMonth, formatBalanceValue, formatForecast, PSD_CROPS, psdCrop, unknownCropMessage } from "./model";
+
+/**
+ * USDA sets coffee and sugar twice a year, in its own reports rather than the
+ * monthly WASDE, and forecasts no season-average price for either.
+ */
+const SEMIANNUAL_CROPS = new Set(["Coffee", "Sugar"]);
 
 const amount = (value: unknown) => typeof value === "number" ? formatBalanceValue(value) : "--";
 const forecast = (value: unknown) => typeof value === "number" ? formatForecast(value) : "--";
 
 export const commodityBalancesHeadless: HeadlessPaneDefinition<"bundle"> = {
   shape: "bundle",
-  argument: { kind: "none" },
+  argument: {
+    kind: "free-text",
+    optional: true,
+    placeholder: "crop",
+    description: "Wheat, corn, soybeans, cotton, coffee or sugar; omit for every crop.",
+    examples: ["coffee", "sugar"],
+  },
   options: [],
   discovery: {
     aliases: ["PSD"],
@@ -15,18 +27,40 @@ export const commodityBalancesHeadless: HeadlessPaneDefinition<"bundle"> = {
     limitations: [
       "Latest market year only",
       "Largest producers, and the world total when the file has one",
-      "Cotton is in 480 lb bales; grains and soybeans are in thousand metric tons",
+      "Cotton is in 480 lb bales and coffee in thousand 60 kg bags; grains, soybeans and sugar are in thousand metric tons",
+      "Coffee and sugar are USDA's semiannual estimates; price forecasts cover grains, soybeans and cotton",
     ],
   },
-  describe: "Wheat, corn, soybean and cotton balances",
+  describe: "Wheat, corn, soybean, cotton, coffee and sugar balances",
   freshness: { source: "USDA", status: "not-a-feed", basis: "monthly supply and demand estimates", periodicity: "monthly" },
-  async load(_args, ctx) {
-    const data = await fetchCommodityBalances(ctx.signal);
+  async load(args, ctx) {
+    const typed = typeof args.argument === "string" && args.argument.trim() ? args.argument.trim() : null;
+    const crop = typed ? psdCrop(typed) : null;
+    if (typed && !crop) throw new Error(unknownCropMessage(typed));
+    const board = await fetchCommodityBalances(ctx.signal, ctx.apiClient);
+    const rows = crop ? board.rows.filter((row) => row.crop === crop) : board.rows;
+    // A crop the server does not serve yet is said, not printed as an empty table.
+    if (crop && rows.length === 0) throw new Error(`${crop} balances are not available yet.`);
+    const prices = crop ? board.prices.filter((row) => row.crop === crop) : board.prices;
+    // One crop is dated by its own estimates: coffee's are not the month's WASDE.
+    const month = (crop ? cropEstimateMonth(rows) : null) ?? board.month;
+    const marketYear = crop ? [...new Set(rows.map((row) => row.year))].join(" ") : board.marketYear;
+    const semiannual = crop != null && SEMIANNUAL_CROPS.has(crop);
+    // Another crop's gap ("Soybean balances are unavailable.") is not this one's; one naming no crop stays,
+    // but for a crop without price forecasts, not theirs.
+    const names = (name: string, gap: string) => new RegExp(`\\b${name.replace(/s$/, "")}`, "i").test(gap);
+    const gaps = crop
+      ? board.gaps.filter((gap) => names(crop, gap)
+        || (!PSD_CROPS.some((name) => names(name, gap)) && !(semiannual && /\bprice forecasts?\b/i.test(gap))))
+      : board.gaps;
+    const data = { ...board, rows, prices, month, marketYear, gaps };
     return {
+      // Coffee and sugar are not the month's supply and demand estimates: `Jul 2026 (semiannual)`.
+      ...(semiannual ? { freshness: { basis: "supply and distribution estimates", periodicity: "semiannual" as const } } : {}),
       complete: data.rows.length > 0,
       sections: [
         {
-          title: data.marketYear ? `Balances ${data.marketYear}` : "Balances",
+          title: `${crop ? `${crop} balances` : "Balances"}${data.marketYear ? ` ${data.marketYear}` : ""}`,
           columns: [
             { key: "crop", header: "Crop" },
             { key: "country", header: "Country" },

package/src/plugins/builtin/commodity-balances/index.tsx

@@ -1,5 +1,7 @@
 import type { PluginModule } from "../plugin-module";
+import { commandRequestParams } from "../shared/command-tab";
 import { commodityBalancesHeadless } from "./headless";
+import { PSD_CROPS, psdCrop, unknownCropMessage } from "./model";
 import { CommodityBalancesPane } from "./pane";
 
 export const commodityBalancesModule: PluginModule = {
@@ -22,11 +24,24 @@ export const commodityBalancesModule: PluginModule = {
       id: "commodity-balances-pane",
       paneId: "commodity-balances",
       label: "Crop Balances",
-      description: "World balances for wheat, corn, soybeans and cotton, with season-average price forecasts when a table is published.",
-      keywords: ["wheat", "corn", "soybeans", "cotton", "crop", "balances", "production", "exports", "stocks", "harvest"],
-      shortcut: { prefix: "PSD" },
+      description: "World balances for wheat, corn, soybeans, cotton, coffee and sugar, with season-average price forecasts when a table is published.",
+      keywords: ["wheat", "corn", "soybeans", "cotton", "coffee", "sugar", "crop", "balances", "production", "exports", "stocks", "harvest"],
+      shortcut: {
+        prefix: "PSD",
+        argKind: "text",
+        argPlaceholder: "crop",
+        argOptional: true,
+        openWithoutArg: true,
+        argOptions: () => PSD_CROPS.map((crop) => ({ value: crop.toLowerCase(), label: crop })),
+      },
       headless: commodityBalancesHeadless,
-      createInstance: () => ({ placement: "floating" }),
+      // PSD coffee opens the board at coffee's first row.
+      createInstance: (_context, options) => {
+        const typed = options?.arg?.trim();
+        const crop = typed ? psdCrop(typed) : null;
+        if (typed && !crop) throw new Error(unknownCropMessage(typed));
+        return { placement: "floating", ...(crop ? { params: commandRequestParams({ crop }) } : {}) };
+      },
     },
   ],
 };

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

@@ -12,6 +12,28 @@ export type PriceColumnId = "crop" | "forecast" | "unit" | "season";
 export const BALANCE_SORT: SortPreference<BalanceColumnId> = { columnId: null, direction: "asc" };
 export const PRICE_SORT: SortPreference<PriceColumnId> = { columnId: null, direction: "asc" };
 
+/** The crops the board carries, in its order; the server names them so. */
+export const PSD_CROPS = ["Wheat", "Corn", "Soybeans", "Cotton", "Coffee", "Sugar"] as const;
+export type PsdCrop = typeof PSD_CROPS[number];
+
+/** A typed crop as the board names it: "coffee", "Soybean" and "soy" read as Coffee and Soybeans. Null for anything else. */
+export function psdCrop(input: string): PsdCrop | null {
+  const typed = input.trim().toLowerCase().replace(/s$/, "");
+  if (typed.length < 3) return null;
+  return PSD_CROPS.find((crop) => crop.toLowerCase().replace(/s$/, "").startsWith(typed)) ?? null;
+}
+
+/** What the CLI answers a crop the board does not carry. */
+export function unknownCropMessage(input: string): string {
+  const names = PSD_CROPS.map((crop) => crop.toLowerCase());
+  return `No crop "${input.trim()}". PSD covers ${names.slice(0, -1).join(", ")} and ${names.at(-1)}.`;
+}
+
+/** The month a crop's balances were estimated, from its rows; null when the board does not date them. */
+export function cropEstimateMonth(rows: readonly BalanceRow[]): string | null {
+  return rows.reduce<string | null>((latest, row) => row.month && (!latest || row.month > latest) ? row.month : latest, null);
+}
+
 export function formatBalanceValue(value: number): string {
   const rounded = Math.round(value * 100) / 100;
   const shown = Math.abs(rounded - Math.round(rounded)) < 0.001 ? Math.round(rounded) : rounded;

package/src/plugins/builtin/commodity-balances/pane.tsx

@@ -1,4 +1,4 @@
-import { useCallback, useEffect, useMemo } from "react";
+import { useCallback, useEffect, useMemo, useState } from "react";
 import {
   DataTableView,
   PaneStatusBody,
@@ -12,6 +12,7 @@ import { usePaneRefreshKey } from "../../../components/data-table/table-pane";
 import type { PaneFooterSegment } from "../../../components/layout/pane/footer";
 import { useAsyncResource } from "../../../react/async-resource";
 import { useAutoRefresh, useUpdatedAgo } from "../../../react/auto-refresh";
+import { usePaneInstance } from "../../../state/app/context";
 import { useThemeColors } from "../../../theme/theme-context";
 import type { PaneProps } from "../../../types/plugin";
 import { Box, TextAttributes } from "../../../ui";
@@ -76,6 +77,13 @@ export function CommodityBalancesPane({ width, height, focused }: PaneProps) {
     [balanceSort, data?.rows],
   );
   const priceRows = useMemo(() => sortPriceRows(prices, priceSort), [priceSort, prices]);
+  // PSD coffee opens the board at coffee's first row, once per command: a later move is the reader's.
+  const pane = usePaneInstance();
+  const requestedCrop = pane?.params?.crop ?? null;
+  const cropRequest = requestedCrop ? `${requestedCrop}|${pane?.params?.tabAt ?? ""}` : "";
+  const [shownRequest, setShownRequest] = usePluginPaneState("cropRequest", "");
+  // The row the request scrolls to the top, until the reader sorts or moves on.
+  const [cropAnchor, setCropAnchor] = useState<{ id: string; version: number } | null>(null);
   const { strip, rows: tabRows } = usePaneTabs(showPrices ? {
     tabs: TABS,
     activeValue: activeTab,
@@ -103,11 +111,24 @@ export function CommodityBalancesPane({ width, height, focused }: PaneProps) {
   });
   usePaneNoticeFooter({ registrationId: `${PANE_ID}:notices`, focused, notices: data?.gaps ?? [] });
 
+  const cropPending = !!cropRequest && cropRequest !== shownRequest;
   useEffect(() => {
-    if (balanceRows.length === 0) return;
+    if (!cropPending || !data) return;
+    setShownRequest(cropRequest);
+    const first = balanceRows.find((row) => row.crop === requestedCrop);
+    if (!first) return;
+    setTab("balances");
+    setBalanceId(first.id);
+    setCropAnchor((current) => ({ id: first.id, version: (current?.version ?? 0) + 1 }));
+  }, [balanceRows, cropPending, cropRequest, data, requestedCrop, setBalanceId, setShownRequest, setTab]);
+  const anchorIndex = cropAnchor ? balanceRows.findIndex((row) => row.id === cropAnchor.id) : -1;
+
+  useEffect(() => {
+    // The crop's row is chosen above; the first row would overwrite it in the same pass.
+    if (cropPending || balanceRows.length === 0) return;
     if (balanceId && balanceRows.some((row) => row.id === balanceId)) return;
     setBalanceId(balanceRows[0]!.id);
-  }, [balanceId, balanceRows, setBalanceId]);
+  }, [balanceId, balanceRows, cropPending, setBalanceId]);
 
   useEffect(() => {
     if (priceRows.length === 0) return;
@@ -116,6 +137,7 @@ export function CommodityBalancesPane({ width, height, focused }: PaneProps) {
   }, [priceId, priceRows, setPriceId]);
 
   const onBalanceHeader = useCallback((columnId: string) => {
+    setCropAnchor(null);
     setBalanceSort((current) => nextHeaderSort(current, columnId as BalanceColumnId, {
       firstDirection: columnId === "value" ? "desc" : "asc",
       resetTo: BALANCE_SORT,
@@ -212,14 +234,23 @@ export function CommodityBalancesPane({ width, height, focused }: PaneProps) {
           sortColumnId={balanceSort.columnId}
           sortDirection={balanceSort.direction}
           onHeaderClick={onBalanceHeader}
-          onSortChange={(columnId, direction) => setBalanceSort({ columnId: columnId as BalanceColumnId, direction })}
+          onSortChange={(columnId, direction) => {
+            setCropAnchor(null);
+            setBalanceSort({ columnId: columnId as BalanceColumnId, direction });
+          }}
           selectedTextOverridesCellColor
           selection={{
             kind: "id",
             selectedId: balanceId,
             getId: (row) => row.id,
-            onChange: (id) => setBalanceId(id),
+            onChange: (id) => {
+              if (id !== cropAnchor?.id) setCropAnchor(null);
+              setBalanceId(id);
+            },
           }}
+          scrollToIndex={anchorIndex >= 0 ? anchorIndex : undefined}
+          scrollToIndexAlign={anchorIndex >= 0 ? "start" : "nearest"}
+          scrollToIndexVersion={cropAnchor?.version ?? 0}
           renderCell={renderBalanceCell}
           emptyStateTitle="No crop balances."
           resetScrollKey={activeTab}

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

@@ -84,9 +84,10 @@ function answersFor(answered: string, symbol: string, abroad: ListingAbroad | nu
   const parsed = parsePublicTickerKey(answered);
   return parsed.symbol === abroad.symbol && (!parsed.exchange || parsed.exchange === abroad.exchange);
 }
-export async function fetchCompanyData(mode: CompanyMode, symbol: string, options: KpiQueryOptions = {}, client: CompanyClient = apiClient, listing: IssuerListingParams = {}) {
+export async function fetchCompanyData(mode: CompanyMode, symbol: string, options: KpiQueryOptions = {}, client: CompanyClient = apiClient, listing: IssuerListingParams = {}, signal?: AbortSignal) {
   try {
-    const data = validateCompanyData(await (mode === "kpis" ? client.getCloudCompanyKpis(symbol, options, listing) : client.getCloudCompanyGuidance(symbol, options, listing)));
+    const request = signal ? { signal } : undefined;
+    const data = validateCompanyData(await (mode === "kpis" ? client.getCloudCompanyKpis(symbol, options, listing, request) : client.getCloudCompanyGuidance(symbol, options, listing, request)));
     if (("series" in data) !== (mode === "kpis") || !answersFor(data.symbol, symbol, listingAbroad(symbol, listing.exchange, listing.name))) throw new Error("Company disclosures do not match the requested company");
     return data;
   }

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

@@ -4,7 +4,8 @@ import type { HeadlessBundleSection, HeadlessPaneColumn, HeadlessPaneDefinition
 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, QUIET_COLUMNS, type CompanyRow } from "./model";
+import { allGuidance, allObservations, companyCellText, companyColumns, companyPreviewNote, KPI_COVERAGE_NOTE, kpiFreeLimitNote, QUIET_COLUMNS,
+  type CompanyRow } from "./model";
 import type { KpiObservation } from "../../../api-client/company-kpis";
 
 /** What the server takes as a metric; anything else is not a metric id and is not sent. */
@@ -57,11 +58,8 @@ function metricFilter(requested: string, data: CompanyDataset, mode: CompanyMode
   const keep = (row: CompanyRow) => row.metricId === requested;
   if (rows.some(keep)) return { keep };
   if (data.access === "preview" && data.lockedRows > 0) {
-    const shown = Math.max(0, data.totalRows - data.lockedRows);
-    const noun = (count: number) => `${mode === "kpis" ? "KPI value" : "guidance figure"}${count === 1 ? "" : "s"}`;
-    const all = `Gloom Pro shows all ${data.totalRows.toLocaleString("en-US")}`;
-    return { keep, empty: shown === 0 ? `The free preview shows no ${noun(0)}; ${all}.`
-      : `${known.name} is not ${shown === 1 ? "the" : "among the"} ${shown.toLocaleString("en-US")} free ${noun(shown)}; ${all}.` };
+    return { keep, empty: kpiFreeLimitNote({ metric: known.name, shown: Math.max(0, data.totalRows - data.lockedRows), total: data.totalRows,
+      guidance: mode === "guidance" }) };
   }
   return { keep, empty: `${data.symbol} has no ${known.name} (${known.id}) ${mode === "kpis" ? "disclosures" : "guidance"}${offered ? `; it has ${offered}` : ""}.` };
 }
@@ -83,7 +81,7 @@ export function companyHeadless(mode: CompanyMode): HeadlessPaneDefinition<"bund
     freshness: { source: "Company filings and calls", status: "not-a-feed", basis: "reported data" },
     argument: { kind: "ticker", description: "Listed company ticker, including exchange-qualified global symbols.", placeholder: "ticker" },
     discovery: { aliases: [mode === "kpis" ? "KPIS" : "GUIDE"], dataRequirements: ["Gloom Cloud company disclosures"],
-      limitations: ["Pro dataset with a fixed latest preview on Free.", "Coverage follows available company disclosures; missing data is not zero.", "Compare matching definition, period, currency, basis and scope.", "Fiscal labels without explicit calendar dates are retained without inferred dates."] },
+      limitations: ["Pro dataset with a fixed latest preview on Free.", KPI_COVERAGE_NOTE, "Compare matching definition, period, currency, basis and scope.", "Fiscal labels without explicit calendar dates are retained without inferred dates."] },
     options: [
       { key: "tab", type: "enum", settingKey: "tab", defaultValue: "table", values: [{ value: "table" }, { value: "chart" }, ...(mode === "guidance" ? [{ value: "history" }] : []), { value: "evidence" }], description: "The pane section to render." },
       { key: "metric", type: "string", settingKey: "metric", description: "Canonical metric ID, such as arr or subscribers.", normalize: (value) => value.trim().toLowerCase() },

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

@@ -12,6 +12,59 @@ export const dimensionLabel = (dimensions: Record<string, string>) => Object.ent
   const rank = (key: string) => ["segment", "product", "geography", "region", "cohort"].includes(key) ? 0 : key === "comparison" ? 2 : 1;
   return rank(a) - rank(b) || a.localeCompare(b);
 }).map(([key, value]) => `${key.replaceAll("_", " ")}: ${value.replaceAll("_", " ")}`).join(" · ");
+/** Labels that name a part of the company, shown before the basis and the qualifiers. */
+const PART_KEY = /segment|product|offering|business|brand|platform|market|geograph|region|division|cloud|franchise|program|channel|line|customer|entity|scope|type|category/;
+/** Labels that say how a figure is measured, shown after the basis. */
+const QUALIFIER_KEY = /exclud|includ|except|without|compar|dilution|window|funded|horizon/;
+const FLAG_VALUE = /^(?:true|yes|y)$/i;
+const FALSE_VALUE = /^(?:false|no|n)$/i;
+const EXCLUDED_VALUE = /^(?:excluded|excludes|excluding|exclusive|ex)$/i;
+const INCLUDED_VALUE = /^(?:included|includes|including|inclusive)$/i;
+const plain = (text: string) => text.replaceAll("_", " ").replace(/\s+/g, " ").trim();
+/** One label in plain words: "Data Center", "excl. fuel", "year over year", never its key. */
+function labelWords(key: string, value: string): string | null {
+  const said = plain(value);
+  const subject = plain(key).replace(/\b(?:excluded|excludes|excluding|exclude|without|included|includes|including|include|ex)\b/gi, " ").replace(/\s+/g, " ").trim();
+  if (!said || FALSE_VALUE.test(said)) return null;
+  if (EXCLUDED_VALUE.test(said) || (FLAG_VALUE.test(said) && /exclud|without|(?:^|_)ex(?:_|$)/i.test(key))) return subject ? `excl. ${subject}` : null;
+  if (INCLUDED_VALUE.test(said) || (FLAG_VALUE.test(said) && /includ/i.test(key))) return subject ? `incl. ${subject}` : null;
+  if (FLAG_VALUE.test(said)) return subject || null;
+  if (/^(?:exclud|except|without)/i.test(key) && !/^(?:excl|exclud|except|without|ex\b)/i.test(said)) return `excl. ${said}`;
+  if (/^includ/i.test(key) && !/^incl/i.test(said)) return `incl. ${said}`;
+  return said;
+}
+const labelRank = (key: string) => QUALIFIER_KEY.test(key) ? 2 : PART_KEY.test(key) ? 0 : 1;
+/** What a series' labels name, in plain words: its parts, then its qualifiers. Empty for the company's consolidated figure. */
+export function scopeWords(dimensions: Record<string, string>, which: "parts" | "qualifiers" | "all" = "all"): string {
+  return Object.entries(dimensions)
+    .filter(([key]) => which === "all" || (which === "qualifiers") === (labelRank(key) === 2))
+    .sort(([a], [b]) => labelRank(a) - labelRank(b) || a.localeCompare(b))
+    .map(([key, value]) => labelWords(key, value)).filter((words): words is string => !!words)
+    .filter((words, index, list) => list.indexOf(words) === index).join(" · ");
+}
+/** The labels that tell a row's series apart: the server's `seriesLabels`, else (a server before them) its stored labels. */
+export const seriesLabels = (row: Pick<CompanyRow, "dimensions" | "seriesLabels">) => row.seriesLabels ?? row.dimensions;
+/**
+ * What tells a series apart from the metric's other series, in plain words
+ * (GLO-1046): its parts, a basis other than reported, then its qualifiers.
+ * "Data Center", "Adjusted · diluted", "International · Constant currency".
+ */
+export function seriesDetail(row: Pick<CompanyRow, "basis" | "dimensions" | "seriesLabels">): string {
+  const labels = seriesLabels(row);
+  return [scopeWords(labels, "parts"), row.basis === "reported" ? "" : basisLabel(row.basis), scopeWords(labels, "qualifiers")].filter(Boolean).join(" · ");
+}
+/** A series named in plain words: "Revenue · Data Center", for a chart's series list and a detail title. */
+export const seriesName = (row: Pick<CompanyRow, "metric" | "basis" | "dimensions" | "seriesLabels">) => [row.metric.name, seriesDetail(row)].filter(Boolean).join(" · ");
+const KIND_ORDER = ["quarter", "half", "ytd", "year", "instant", "other"];
+const BASIS_ORDER = ["reported", "adjusted", "constant_currency", "organic"];
+/** Series in reading order: by metric, the consolidated figure before its parts, reported before other bases, a quarter before its year. */
+export function seriesOrder(a: CompanyRow, b: CompanyRow): number {
+  const rank = (list: string[], value: string) => { const index = list.indexOf(value); return index < 0 ? list.length : index; };
+  const parts = (row: CompanyRow) => scopeWords(seriesLabels(row), "parts");
+  return a.metric.name.localeCompare(b.metric.name) || Number(parts(a) !== "") - Number(parts(b) !== "") || parts(a).localeCompare(parts(b))
+    || rank(BASIS_ORDER, a.basis) - rank(BASIS_ORDER, b.basis) || scopeWords(seriesLabels(a), "qualifiers").localeCompare(scopeWords(seriesLabels(b), "qualifiers"))
+    || rank(KIND_ORDER, a.period.kind) - rank(KIND_ORDER, b.period.kind);
+}
 export const unitLabel = (row: Pick<CompanyRow, "unit" | "currency" | "dimensions">) => ({
   currency: row.currency ?? "Currency", currency_per_share: `${row.currency ?? "Currency"}/share`, currency_per_unit: `${row.currency ?? "Currency"}/${row.dimensions.unit ?? "unit"}`,
   percent: "%", basis_points: "bp", count: "Count", ratio: "x", volume: row.dimensions.unit ?? "Volume",
@@ -118,7 +171,11 @@ export function companyCellText(row: CompanyRow, column: string, observations: K
     : column === "outcome" ? guide ? outcomeLabel(guide) : "--" : column === "published" ? row.evidence[0]!.publishedAt.slice(0, 10)
     : column === "confidence" ? `${Math.round(row.confidence * 100)}%` : column === "revision" ? `${row.revision} ${row.current ? "current" : "superseded"}` : row.evidence[0]!.quote;
 }
-export function companyColumns(guidance: boolean, evidence: boolean, history: boolean, trend = false): DataTableColumn[] {
+/**
+ * The table's columns. `named` is the desktop's: the metric cell names the
+ * series in plain words (seriesDetail), so no basis or scope column repeats it.
+ */
+export function companyColumns(guidance: boolean, evidence: boolean, history: boolean, trend = false, named = false): DataTableColumn[] {
   const columns: DataTableColumn[] = [
     { id: "metric", label: "Metric", width: 27, flexGrow: 1, align: "left" },
     { id: "period", label: "Fiscal period", width: 14, align: "left" },
@@ -134,7 +191,33 @@ export function companyColumns(guidance: boolean, evidence: boolean, history: bo
   ];
   const order = evidence ? ["metric", "period", "quote", "published", "confidence", "revision", "value", "basis", "scope", "issued", "change"]
     : history ? ["metric", "period", "actual", "outcome", "value", "issued", "change", "basis", "scope"] : null;
-  return order ? columns.sort((a, b) => order.indexOf(a.id) - order.indexOf(b.id)) : columns;
+  const shown = named ? columns.filter((column) => column.id !== "basis" && column.id !== "scope") : columns;
+  return order ? shown.sort((a, b) => order.indexOf(a.id) - order.indexOf(b.id)) : shown;
+}
+
+/** 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.";
+
+/**
+ * Why Free shows no value of a metric, in the same words in `fn KPIS`, `fn GUIDE` and EQS: "Order backlog is not
+ * among the 3 free KPI values; Gloom Pro shows all 63." With no free value at all, `where` says which free view
+ * shows none; without a total (EQS counts no company's disclosures), Pro shows each company's metric.
+ */
+export function kpiFreeLimitNote({ metric, shown, total, guidance = false, where = "The free preview" }: {
+  /** The metric's name: "Order backlog", "Backlog". */
+  metric: string;
+  /** How many values Free shows. */
+  shown: number;
+  /** How many Gloom Pro shows, when the response says. */
+  total: number | null;
+  guidance?: boolean;
+  where?: string;
+}): string {
+  const count = (value: number) => value.toLocaleString("en-US");
+  const noun = (value: number) => `${guidance ? "guidance figure" : "KPI value"}${value === 1 ? "" : "s"}`;
+  const pro = total == null ? `Gloom Pro shows each company's ${metric}` : `Gloom Pro shows all ${count(total)}`;
+  return shown === 0 ? `${where} shows no ${noun(0)}; ${pro}.`
+    : `${metric} is not ${shown === 1 ? "the" : "among the"} ${count(shown)} free ${noun(shown)}; ${pro}.`;
 }
 
 /** The lock line of a free preview, in the same words in the pane and `fn KPIS` / `fn GUIDE`. */

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

@@ -10,6 +10,7 @@ import { useAsyncResource, useAutoRefresh, usePaneSettingValue, usePluginAppActi
 import { usePaneTickerIdentity } from "../../../state/hooks/pane-ticker";
 import { useThemeColors } from "../../../theme/theme-context";
 import { quoteBlockStyle } from "../../../components/ui/quote";
+import { ClippedText } from "../../../components/ui/display";
 import type { PaneProps } from "../../../types/plugin";
 import { Box, Text, useRendererHost, useUiCapabilities, type ScrollBoxRenderable } from "../../../ui";
 import { SignInWall } from "../cloud/auth-actions";
@@ -20,8 +21,8 @@ import { isCloudSessionRequired, useResearchCloudSession } from "../shared/resea
 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,
-  isGuidance, exactObservation, observationValue, observationChange, observationChart, periodOrder, outcomeLabel, QUIET_COLUMNS, rangeText, seriesLabel, unitLabel, valueText, companyPreviewNote,
-  type CompanyRow } from "./model";
+  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";
 import type { PricePoint } from "../../../types/financials";
 import { toneColor, withoutQuietColumns } from "../shared/research-cells";
@@ -41,7 +42,7 @@ function DisclosureEvidence({ row, sourceId, onSource, width }: { row: CompanyRo
     <KeyValueRow label="Value" value={isGuidance(row) ? rangeText(row) : observationValue(row)} detail={row.currency || row.unit === "volume" || row.unit === "count" ? unitLabel(row) : undefined} labelWidth={18} />
     <KeyValueRow label="Fiscal period" value={row.period.label} detail={row.period.end ? row.period.start ? `${row.period.start} to ${row.period.end}` : `${row.period.kind === "instant" ? "As of" : "Ended"} ${row.period.end}` : "Calendar dates unavailable"} labelWidth={18} />
     <KeyValueRow label="Basis" value={basisLabel(row.basis)} labelWidth={18} />
-    <KeyValueRow label="Scope" value={dimensionLabel(row.dimensions) || "Consolidated"} labelWidth={18} />
+    <KeyValueRow label="Scope" value={(desktop ? scopeWords(seriesLabels(row)) : dimensionLabel(row.dimensions)) || "Consolidated"} labelWidth={18} />
     <KeyValueRow label="Definition" value={row.metric.definition} labelWidth={18} />
     <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}
@@ -106,15 +107,17 @@ function CompanyView({ symbol, exchange, name, mode, width, height, focused }: P
   const [selectedId, setSelected] = usePluginPaneState<string | null>(`company:selected:${tab}`, null);
   const [openId, setOpen] = usePluginPaneState<string | null>("company:open", null);
   const [sourceId, setSource] = usePluginPaneState<string | null>("company:source", null);
-  const [sort, setSort] = usePluginPaneState<{ column: string; direction: "asc" | "desc" }>("company:sort", { column: "period", direction: "desc" });
+  // The desktop lists KPIs by metric, each series named in plain words (GLO-1046); the terminal keeps its frames.
+  const [sort, setSort] = usePluginPaneState<{ column: string; direction: "asc" | "desc" }>("company:sort",
+    desktop && mode === "kpis" ? { column: "metric", direction: "asc" } : { column: "period", direction: "desc" });
   const detailScrollRef = useRef<ScrollBoxRenderable | null>(null);
   const observations = useMemo(() => kpis ? allObservations(kpis) : [], [kpis]);
   const guides = useMemo(() => guidance ? allGuidance(guidance) : [], [guidance]);
   const allRows = useMemo<CompanyRow[]>(() => [...observations, ...guides], [observations, guides]);
   const eligible = useMemo(() => allRows.filter((row) => metric === "all" || row.metricId === metric), [allRows, metric]);
   const plotOptions = useMemo(() => mode === "kpis"
-    ? [...new Map(eligible.filter((row) => !isGuidance(row)).map((row) => [`${row.seriesKey}:${row.period.kind}`, { value: `${row.seriesKey}:${row.period.kind}`, label: `${seriesLabel(row)} · ${row.period.kind}` }])).values()]
-    : [...new Map(eligible.filter(isGuidance).map((row) => [guideGroupKey(row), { value: guideGroupKey(row), label: `${seriesLabel(row)} · ${row.period.label}` }])).values()], [eligible, mode]);
+    ? [...new Map(eligible.filter((row) => !isGuidance(row)).map((row) => [`${row.seriesKey}:${row.period.kind}`, { value: `${row.seriesKey}:${row.period.kind}`, label: `${desktop ? seriesName(row) : seriesLabel(row)} · ${row.period.kind}` }])).values()]
+    : [...new Map(eligible.filter(isGuidance).map((row) => [guideGroupKey(row), { value: guideGroupKey(row), label: `${desktop ? seriesName(row) : seriesLabel(row)} · ${row.period.label}` }])).values()], [eligible, mode, desktop]);
   const activePlot = plotOptions.some((option) => option.value === plotKey) ? plotKey : plotOptions[0]?.value ?? "";
   const rows = useMemo(() => {
     const values = eligible.filter((row) => tab === "chart" ? (isGuidance(row) ? guideGroupKey(row) : `${row.seriesKey}:${row.period.kind}`) === activePlot
@@ -130,11 +133,13 @@ function CompanyView({ symbol, exchange, name, mode, width, height, focused }: P
         : sort.column === "quote" ? row.evidence[0]!.quote : sort.column === "change" ? guide ? guide.direction : observationChange(row as KpiObservation, observations).value
         : periodOrder(row);
     };
+    const direction = sort.direction === "asc" ? 1 : -1;
+    if (desktop && sort.column === "metric") return [...values].sort((a, b) => (seriesOrder(a, b) || periodOrder(b).localeCompare(periodOrder(a)) || a.id.localeCompare(b.id)) * direction);
     return [...values].sort((a, b) => { const x = key(a), y = key(b);
       return x === null || y === null ? x === y ? a.id.localeCompare(b.id) : x === null ? 1 : -1
-        : (x < y ? -1 : x > y ? 1 : a.metric.name.localeCompare(b.metric.name) || dimensionLabel(a.dimensions).localeCompare(dimensionLabel(b.dimensions)) || a.id.localeCompare(b.id)) * (sort.direction === "asc" ? 1 : -1);
+        : (x < y ? -1 : x > y ? 1 : a.metric.name.localeCompare(b.metric.name) || dimensionLabel(a.dimensions).localeCompare(dimensionLabel(b.dimensions)) || a.id.localeCompare(b.id)) * direction;
     });
-  }, [eligible, tab, activePlot, guidance, kpis, sort, observations]);
+  }, [eligible, tab, activePlot, guidance, kpis, sort, observations, desktop]);
   const selected = rows.find((row) => row.id === selectedId) ?? rows[0];
   const openRow = allRows.find((row) => row.id === openId);
   const activeRow = openRow ?? selected;
@@ -153,8 +158,8 @@ 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),
-    rows, (row, id) => id === "basis" ? basisLabel(row.basis) : id === "scope" ? dimensionLabel(row.dimensions) || "Consolidated" : "", QUIET_COLUMNS), [mode, tab, trends, rows, width]);
+  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 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,7 +195,7 @@ function CompanyView({ symbol, exchange, name, mode, width, height, focused }: P
   const query = <QueryBar width={width} filters={[{ id: "metric", label: "Metric", value: metric, defaultValue: "all", options: metricOptions,
     onChange: (value: string) => { setMetric(value); setSelected(null); setOpen(null); } }, ...(tab === "chart" && plotOptions.length ? [{ id: "series", label: "Series", value: activePlot,
       options: plotOptions, onChange: (value: string) => { setPlotKey(value); setSelected(null); } }] : [])]} />;
-  const renderCell = (item: Item, column: (typeof columns)[number]): DataTableCell => {
+  const renderCell = (item: Item, column: (typeof columns)[number], _index: number, state: { selected: boolean }): DataTableCell => {
     const row = item.row;
     if (!row) {
       if (isNote(item)) return { text: "" };
@@ -210,6 +215,15 @@ function CompanyView({ symbol, exchange, name, mode, width, height, focused }: P
       const change = observationChange(row as KpiObservation, observations);
       return { text: changeText(change), value: change.value, color: toneColor(changeTone(row as KpiObservation, change.value), colors) };
     }
+    if (desktop && column.id === "metric") {
+      // The series in plain words: the metric bright, what tells it apart dim. The detail starts from no width and takes
+      // what the name leaves, so it gives way first and the name is cut only when it alone does not fit.
+      const detail = seriesDetail(row);
+      return { text: detail ? `${row.metric.name}  ${detail}` : row.metric.name, content: <Box flexDirection="row" height={1} overflow="hidden" flexShrink={1} minWidth={0}>
+        <ClippedText fg={state.selected ? colors.selectedText : colors.textBright} text={row.metric.name} width={column.width} />
+        {detail ? <ClippedText fg={state.selected ? colors.selectedText : colors.textDim} lead="  " text={detail} width={column.width} flex="1 1 0%" /> : null}
+      </Box> };
+    }
     const text = companyCellText(row, column.id, observations);
     return { text, ...(column.id === "value" && !guide ? { value: exactObservation(row as KpiObservation) ? (row as KpiObservation).value : observationValue(row as KpiObservation) } : column.id === "actual" ? { value: guide?.actual?.value } : {}),
       color: column.id === "metric" ? colors.textBright : column.id === "value" || column.id === "actual" ? colors.textBright
@@ -225,7 +239,7 @@ function CompanyView({ symbol, exchange, name, mode, width, height, focused }: P
         selection={{ kind: "id", selectedId: selected?.id ?? null, getId, onChange: setSelected }}
         onActivate={(item) => item.row ? setOpen(item.row.id) : isNote(item) ? undefined : openUpgrade()} renderCell={renderCell}
         isNavigable={(item) => !isNote(item)} renderSectionHeader={(item) => "note" in item && item.note ? { text: item.note } : null} freezeFirstColumn selectedTextOverridesCellColor showHorizontalScrollbar
-        detailOpen={!!openRow} onBack={() => setOpen(null)} detailTitle={openRow ? `${openRow.metric.name} · ${fiscalLabel(openRow)}` : undefined}
+        detailOpen={!!openRow} onBack={() => setOpen(null)} detailTitle={openRow ? `${desktop ? seriesName(openRow) : openRow.metric.name} · ${fiscalLabel(openRow)}` : undefined}
         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}`}

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

@@ -10,6 +10,7 @@ import { supplyChainModule } from "./supply-chain";
 import { awardsModule } from "./awards";
 import { cryptoBoardModule } from "./crypto-board";
 import { portfolioAnalyticsModule } from "./analytics";
+import { brokerTradingModule } from "./broker-trading";
 import { brokerManagerModule } from "./broker-manager";
 import { changelogModule } from "./changelog";
 import { connectionsModule } from "./connections";
@@ -189,9 +190,9 @@ export const brokerPlugin = composeBuiltinPlugin({
   id: "broker",
   name: "Broker",
   version: "1.0.0",
-  description: "Broker profiles, account sync, and connection status.",
+  description: "Broker profiles, account sync, order review, and trading status.",
   toggleable: true,
-  modules: [brokerManagerModule],
+  modules: [brokerManagerModule, brokerTradingModule],
 });
 
 export const globalMarketsPlugin = composeBuiltinPlugin({

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

@@ -29,7 +29,7 @@ export const cotHeadless: HeadlessPaneDefinition<"bundle"> = {
   shape: "bundle",
   // Tuesday positions published the Friday after; two weeks without a new report means one was missed.
   freshness: { source: "CFTC", status: "not-a-feed", basis: "weekly report", maxAgeMinutes: 14 * 24 * 60 },
-  argument: { kind: "free-text", optional: true, placeholder: "code or root", description: "CFTC market code or verified futures root; omit for the extremes board." },
+  argument: { kind: "free-text", optional: true, placeholder: "code or name", description: "Futures root (KC), commodity name (coffee) or CFTC market code; omit for the extremes board." },
   options: [{ key: "report", type: "enum", values: [{ value: "legacy" }, { value: "disaggregated" }], defaultValue: "legacy", description: "CFTC report family." },
     { key: "traderClass", type: "enum", values: ["noncommercial", "commercial", "producer", "swap", "managed-money", "other-reportable", "nonreportable"].map((value) => ({ value })), description: "Trader class for the extremes board; defaults by report family.",
       pluginState: { pluginId: COMMODITIES_VIEW_STATE.cot, key: "class" } },

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

@@ -13,7 +13,7 @@ export const cotModule: PluginModule = {
   paneTemplates: [{ id: "cot-cot", paneId: "cot", label: "CFTC Positioning",
     description: "Weekly futures positioning, changes, historical percentiles and cross-market extremes.",
     keywords: ["cot", "cftc", "positioning", "commitments", "managed money", "net spec", "crude oil", "natural gas"],
-    shortcut: { prefix: "COT", aliases: ["CFTC"], argKind: "text" as const, argPlaceholder: "code or root", argOptional: true,
+    shortcut: { prefix: "COT", aliases: ["CFTC"], argKind: "text" as const, argPlaceholder: "code or name", argOptional: true,
       argOptions: () => COT_ROOT_OPTIONS }, headless: cotHeadless,
     createInstance: (context, options) => {
       const input = options?.arg?.trim();