gloomberb 0.16.4 → 0.16.6

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

@@ -1,15 +1,194 @@
-import type { HeadlessPaneDefinition } from "../../../types/plugin";
-import type { ExposureRequest } from "../../../api-client/exposure";
+import type { HeadlessPaneColumn, HeadlessPaneDefinition, HeadlessPaneRow } from "../../../types/plugin";
+import type { ExposureExtensionObservation, ExposurePayload, ExposureRequest } from "../../../api-client/exposure";
+import { cliTerminalWidth } from "../../../utils/cli-output";
+import { clipToDisplayWidth, displayWidth } from "../../../utils/format";
+import { fiscalLabel } from "../company-kpis/model";
+import { humanLabel } from "../shared/research-cells";
 import { fetchExposure, fetchScenarios } from "./client";
-import { DEFAULT_SCENARIO, parseCustomScenario, parseHoldings, TABS } from "./model";
+import { DEFAULT_SCENARIO, exposureCellText, parseCustomScenario, parseHoldings, pathRows, portfolioRows, scenarioTitle, tableRows, TABS, type ExposureRow } from "./model";
 import { portfolioHoldings, watchlistHoldings } from "./holdings";
+import { describeCollections, findNamedCollection } from "../../../portfolio/collection-name";
+import { driverAmount, driverRows, driverScope } from "./drivers";
+
+/*
+ * The text report prints each section as its pane tab draws it: exposure
+ * ranges and weights as percents, a driver's value compact with its unit
+ * (201.18B USD), its fiscal period as KPIS prints it (FY2024) and its scope in
+ * words. The title names the scenario, so a one-shock scenario needs no shock
+ * column. Every table fits 100 columns, or a narrower terminal: names and
+ * scopes take the room the figures leave and are cut at a word only when they
+ * cannot fit. Caveats print under their row; a holding's own caveats are the
+ * report's error lines. CSV, NDJSON and JSON keep the records whole.
+ */
+type CellId = Parameters<typeof exposureCellText>[1];
+type TextRow = ExposureRow & { kind?: string; note?: string | null };
+/** A column's cells, and how far it may narrow to fit: `min` lets it give way, cut at a word; `long` is a fuller form printed only when the whole table fits with it. */
+interface TextColumn { key: string; header: string; read: (row: TextRow) => string; right?: boolean; min?: number; long?: (row: TextRow) => string }
+type ColumnOptions = Omit<TextColumn, "key" | "header" | "read">;
+const REPORT_WIDTH = 100;
+/** The space the report renderer puts between columns. */
+const GAP = 2;
+
+const column = (key: string, header: string, read: TextColumn["read"], options: ColumnOptions = {}): TextColumn => ({ key, header, read, ...options });
+const cell = (id: CellId, header: string, options?: ColumnOptions) => column(id, header, row => exposureCellText(row, id), options);
+const holding = (header: string) => column("symbol", header, row => row.symbol);
+/** The narrowest a name may get before the table gives up fitting, as the report renderer allows. */
+const NAME = 8;
+const period = cell("period", "Period");
+const note: HeadlessPaneColumn = { key: "note", header: "Note", underRow: true };
+const textRows = (items: TextRow[]) => items as unknown as HeadlessPaneRow[];
+/** Caveats that belong to one row, printed under it; null prints nothing. */
+const withNotes = (items: ExposureRow[], read: (row: ExposureRow) => string[]): TextRow[] => items.map(row => ({ ...row, note: read(row).join("\n") || null }));
+
+/** Whole words that fit `width`, then an ellipsis, with no separator left dangling; a first word too long for it is cut. */
+function clipWords(text: string, width: number): string {
+  if (displayWidth(text) <= width) return text;
+  let kept = "";
+  for (const word of text.split(" ")) {
+    const next = kept ? `${kept} ${word}` : word;
+    if (displayWidth(next) > width - 1) break;
+    kept = next;
+  }
+  kept = kept.replace(/[\s·,;:(/→-]+$/, "");
+  return kept ? `${kept}…` : clipToDisplayWidth(text, width);
+}
+/** The narrowest width past `width` at which a cut cell shows more of its text. */
+function revealWidth(text: string, width: number): number {
+  const shown = clipWords(text, width);
+  for (let next = displayWidth(shown) + 1; next < displayWidth(text); next++) if (clipWords(text, next) !== shown) return next;
+  return displayWidth(text);
+}
+
+/**
+ * Column widths for `rows` within `budget`. The fuller forms print when the
+ * whole table fits with them. Otherwise the widest narrowing column gives up
+ * a cell at a time until the table fits, or each is at its floor; then the
+ * room a word cut leaves goes back, a word at a time, to the cut cell that
+ * needs the least of it.
+ */
+function fit(columns: TextColumn[], rows: TextRow[], budget: number): { read: TextColumn["read"]; width: number }[] {
+  const header = (index: number) => displayWidth(columns[index]!.header);
+  const measure = (reads: TextColumn["read"][]) => reads.map((read, index) => Math.max(header(index), ...rows.map(row => displayWidth(read(row)))));
+  const total = (widths: number[]) => widths.reduce((sum, width) => sum + width, 0) + GAP * (widths.length - 1);
+  const long = columns.map(item => item.long ?? item.read);
+  const fuller = measure(long);
+  if (total(fuller) <= budget) return columns.map((_, index) => ({ read: long[index]!, width: fuller[index]! }));
+  const reads = columns.map(item => item.read);
+  const narrowing = columns.flatMap((item, index) => item.min === undefined ? [] : [index]);
+  const floor = (index: number) => Math.max(columns[index]!.min!, header(index));
+  let widths = measure(reads);
+  for (let overflow = total(widths) - budget; overflow > 0; overflow--) {
+    const widest = narrowing.reduce((pick, index) => widths[index]! > floor(index) && (pick < 0 || widths[index]! > widths[pick]!) ? index : pick, -1);
+    if (widest < 0) break;
+    widths[widest]!--;
+  }
+  const shown = (allotted: number[]) => allotted.map((width, index) => !narrowing.includes(index) ? width
+    : Math.max(header(index), ...rows.map(row => displayWidth(clipWords(reads[index]!(row), width)))));
+  widths = shown(widths);
+  for (;;) {
+    const spare = budget - total(widths);
+    let best: { index: number; width: number } | null = null;
+    for (const index of narrowing) for (const row of rows) {
+      const text = reads[index]!(row);
+      if (displayWidth(text) <= widths[index]!) continue;
+      const width = revealWidth(text, widths[index]!);
+      if (width - widths[index]! <= spare && (!best || width - widths[index]! < best.width - widths[best.index]!)) best = { index, width };
+    }
+    if (!best) break;
+    widths = shown(widths.map((width, index) => index === best!.index ? best!.width : width));
+  }
+  return columns.map((_, index) => ({ read: reads[index]!, width: widths[index]! }));
+}
+
+/** The text report's columns for these rows, fitted when they print, to 100 columns or the terminal when it is narrower. */
+function fitted(columns: TextColumn[], rows: TextRow[], under: HeadlessPaneColumn[] = []): HeadlessPaneColumn[] {
+  const layouts = new Map<number, ReturnType<typeof fit>>();
+  const layout = () => {
+    const budget = Math.min(REPORT_WIDTH, cliTerminalWidth() ?? REPORT_WIDTH);
+    if (!layouts.has(budget)) layouts.set(budget, fit(columns, rows, budget));
+    return layouts.get(budget)!;
+  };
+  return [...columns.map((item, index): HeadlessPaneColumn => ({ key: item.key, header: item.header, ...(item.right ? { align: "right" as const } : {}),
+    format: (_value, row) => { const { read, width } = layout()[index]!; return clipWords(read(row as unknown as TextRow), width); } })), ...under];
+}
+
+function holdingColumns(data: ExposurePayload): TextColumn[] {
+  return [holding("Holding"), ...(data.scenario.shocks.length > 1 ? [cell("label", "Shock", { min: NAME })] : []), cell("basis", "Basis"),
+    cell("exposure", "Exposure %", { right: true }), cell("classification", "Evidence", { min: 10 }), cell("impact", "Stress est. %", { right: true }), period, cell("weight", "NAV wt. %", { right: true })];
+}
+const PATH_COLUMNS = [holding("Holding"), cell("label", "Path", { min: NAME }), cell("basis", "Basis"), cell("exposure", "Exposure %", { right: true }),
+  cell("classification", "Evidence", { min: 10 }), cell("impact", "Stress est. %", { right: true }), period];
+
+/** A credit line's figures repeat the instrument their scope names: "$1.0 billion revolver: drawn" reads Drawn. */
+function driverLabel(driver: ExposureExtensionObservation): string {
+  const named = Object.values(driver.dimensions ?? {}).find(value => driver.label.startsWith(`${value}: `));
+  const rest = named ? driver.label.slice(named.length + 2) : driver.label;
+  return rest.charAt(0).toUpperCase() + rest.slice(1);
+}
+/** The scope in words, after the basis when the figure is not the reported one: Adjusted · diluted. */
+function driverScopeText(driver: ExposureExtensionObservation): string {
+  return [driver.basis && driver.basis !== "reported" ? humanLabel(driver.basis) : "", driverScope(driver)].filter(Boolean).join(" · ") || "--";
+}
+const MONTHS = ["jan", "feb", "mar", "apr", "may", "jun", "jul", "aug", "sep", "oct", "nov", "dec"];
+/**
+ * A disclosure's fiscal period as KPIS prints it, FY2024 or Q3 FY2026, with
+ * the date it ended (FY2024 · Sep 28, 2024) as the fuller form. The source
+ * words it freely; wording that is not a fiscal year or quarter prints as is.
+ */
+function driverPeriod(driver: ExposureExtensionObservation): { short: string; long: string } {
+  const text = driver.period?.trim() || "--";
+  const match = /^(?:full\s+)?(?:Q([1-4])\s+)?(?:fiscal(?:\s+year)?\s+|FY\s?)(\d{4})(?:\s+ended\s+(.+))?$/i.exec(text);
+  if (!match) return { short: text, long: text };
+  const quarter = match[1] ? Number(match[1]) : null;
+  const short = fiscalLabel({ period: { start: null, end: null, kind: quarter ? "quarter" : "year", fiscalYear: Number(match[2]), fiscalQuarter: quarter, label: text } });
+  const ended = /^([A-Za-z]{3})[a-z]*\.?\s+(\d{1,2}),?\s+(\d{4})$/.exec(match[3]?.trim() ?? "");
+  const month = ended && MONTHS.includes(ended[1]!.toLowerCase()) ? `${ended[1]!.charAt(0).toUpperCase()}${ended[1]!.slice(1).toLowerCase()}` : null;
+  return { short, long: month ? `${short} · ${month} ${ended![2]}, ${ended![3]}` : short };
+}
+const DRIVER_COLUMNS = [holding("Holding"), column("label", "Company driver", row => row.driver ? driverLabel(row.driver) : row.label, { min: NAME }),
+  column("value", "Value", row => row.driver ? driverAmount(row.driver) : "--", { right: true }),
+  column("period", "Period", row => row.driver ? driverPeriod(row.driver).short : "--", { min: 10, long: row => row.driver ? driverPeriod(row.driver).long : "--" }),
+  column("scope", "Scope", row => row.driver ? driverScopeText(row.driver) : "--", { min: NAME })];
+
+/**
+ * An anonymous counterparty leads with the name its filing gives it, and the
+ * Kind column already says what it is: "Undisclosed customer (Customer one)"
+ * reads "Customer one (undisclosed)", which still tells two apart when cut.
+ */
+const targetName = (row: TextRow) => {
+  const match = row.kind ? new RegExp(`^Undisclosed ${row.kind} \\((.+)\\)$`, "i").exec(row.label) : null;
+  return match ? `${match[1]} (undisclosed)` : row.label;
+};
+
+/**
+ * Stress lines are always estimates, so the unknown share of holdings under a
+ * line says how partial it is. A concentration's share is unknown or an
+ * estimate, so it says only when its bound is partial, leaving out
+ * relationships without a share. With one holding, which
+ * holdings a line covers and their weight say nothing the Holdings table does
+ * not.
+ */
+function portfolioColumns(data: ExposurePayload, concentration: boolean, items: ExposureRow[]): TextColumn[] {
+  const several = data.holdings.length > 1;
+  // Signed exposure differs from gross only where a holding is short.
+  const signed = concentration && items.some(row => JSON.stringify(row.impact) !== JSON.stringify(row.exposure));
+  const partial = (row: ExposureRow) => row.incomplete && row.exposure !== null;
+  const holdings = several ? [holding("Holdings")] : [];
+  if (concentration) return [column("kind", "Kind", row => humanLabel(row.kind ?? "")), ...holdings, column("label", "Target", targetName, { min: NAME }),
+    cell("basis", "Basis"), cell("exposure", "Gross exp. %", { right: true }), ...(signed ? [cell("impact", "Signed exp. %", { right: true })] : []),
+    ...(items.some(partial) ? [column("bound", "Bound", row => partial(row) ? "Partial" : "")] : []), period, ...(several ? [cell("weight", "Gross wt. %", { right: true })] : [])];
+  return [...holdings, ...(data.scenario.shocks.length > 1 ? [cell("label", "Target", { min: NAME })] : []), cell("basis", "Basis"),
+    cell("exposure", "Exposure %", { right: true }), cell("impact", "Stress est. %", { right: true }), period, cell("weight", "Covered wt. %", { right: true })];
+}
+
+const CONCENTRATION_VIEWS = ["country", "supplier", "customer"] as const;
 
 export const exposureHeadless: HeadlessPaneDefinition<"bundle"> = {
   shape: "bundle",
   freshness: { status: "not-a-feed", basis: "company disclosures" },
   argument: { kind: "free-text", optional: true, placeholder: "AAPL=60% NVDA=40%", description: "Tickers, signed NAV weights, PORT:<id>, or WATCH:<id>. Unweighted lists and watchlists use equal weights." },
   discovery: { aliases: ["EXPO"], dataRequirements: ["Gloom Cloud geographic revenue, disclosed supply chains, KPIs, guidance and credit disclosures", "Portfolio NAV for local PORT weights"],
-    limitations: ["Pro: full holdings and up to four-hop paths; free: one holding, one hop", "Operating exposure estimates, never predicted stock returns", "Missing relationships and sensitivities remain unknown", "Basis and reporting period are kept separate"] },
+    limitations: ["Pro: full holdings and up to four-hop paths; free: one holding, one hop.", "Operating exposure estimates, never predicted stock returns.", "Missing relationships and sensitivities remain unknown.", "Basis and reporting period are kept separate."] },
   options: [
     { key: "scenario", type: "string", settingKey: "scenario", defaultValue: "taiwan-disruption", description: "Library scenario id, or use --custom." },
     { key: "custom", type: "string", settingKey: "customScenario", description: "JSON scenario with label and shocks; supports multiple shocks and explicit transmission assumptions." },
@@ -19,19 +198,23 @@ export const exposureHeadless: HeadlessPaneDefinition<"bundle"> = {
     { key: "tab", type: "enum", settingKey: "tab", defaultValue: "table", values: TABS.map(t => ({ value: t.value })), description: "Pane tab." },
     { key: "view", type: "enum", settingKey: "view", defaultValue: "stress", values: ["stress", "country", "supplier", "customer"].map(value => ({ value })), description: "Portfolio stress or concentration grouping." },
   ],
-  describe: args => `Exposure | ${args.rawArgument || "holdings"}`,
+  describe: (args, result) => {
+    const payload = result?.metadata?.payload as ExposurePayload | undefined;
+    return `Exposure | ${args.rawArgument || "holdings"}${payload ? ` | ${scenarioTitle(payload.scenario)}` : ""}`;
+  },
   async load(args, ctx) {
     const input = args.rawArgument.trim();
     const source = /^(PORT|WATCH):(.+)$/i.exec(input);
     let holdings: ExposureRequest["holdings"];
     if (source?.[1]?.toUpperCase() === "PORT") {
       const local = await ctx.resolvePortfolio?.(source[2]!);
-      if (!local) throw new Error(`Unknown local portfolio: ${source[2]}`);
+      if (!local) throw new Error(`Unknown local portfolio: ${source[2]}.${ctx.config.portfolios.length ? ` Portfolios: ${describeCollections(ctx.config.portfolios)}.` : ""}`);
       holdings = await portfolioHoldings(local.portfolio, local.tickers, Number(args.options.nav), ctx.marketData);
     } else if (source) {
       const tickers = await ctx.resolveWatchlist?.(source[2]!);
-      if (!tickers) throw new Error(`Unknown local watchlist: ${source[2]}`);
-      holdings = watchlistHoldings(tickers, source[2]!);
+      if (!tickers) throw new Error(`Unknown local watchlist: ${source[2]}.${ctx.config.watchlists.length ? ` Watchlists: ${describeCollections(ctx.config.watchlists)}.` : ""}`);
+      // The host reads the name in any case; membership is kept under the configured id.
+      holdings = watchlistHoldings(tickers, findNamedCollection(ctx.config.watchlists, source[2])?.id ?? source[2]!);
     } else holdings = parseHoldings(input);
     const id = String(args.options.scenario ?? DEFAULT_SCENARIO.id);
     const scenario = args.options.custom ? parseCustomScenario(String(args.options.custom)) : (await fetchScenarios(ctx.apiClient)).find(s => s.id === id);
@@ -40,14 +223,23 @@ export const exposureHeadless: HeadlessPaneDefinition<"bundle"> = {
     if (cashWeight !== undefined && (!Number.isFinite(cashWeight) || Math.abs(cashWeight) > 10)) throw new Error("Cash must be a NAV fraction between -10 and 10.");
     if (ctx.signal.aborted) throw new Error("Exposure analysis cancelled.");
     const data = await fetchExposure({ holdings, scenario, depth: Number(args.options.depth ?? 2), ...(cashWeight === undefined ? {} : { cashWeight }) }, ctx.apiClient);
+    const drivers = withNotes(driverRows(data), row => row.driver?.notes ?? []);
+    const stress = withNotes(portfolioRows(data, "stress"), row => row.incomplete ? row.unknowns : []);
+    const concentrations = CONCENTRATION_VIEWS.flatMap(kind => portfolioRows(data, kind).map(row => ({ ...row, kind })));
+    const holdingRows = tableRows(data), paths = pathRows(data);
     return { complete: data.lockedHoldings === 0 && data.holdings.every(h => h.status === "quantified") && data.unknowns.length === 0,
       errors: [...data.unknowns, ...(data.access === "preview" ? ["Free preview: one holding, depth one. Full analysis requires Pro."] : [])],
       sections: [
-        { title: "Holdings", rows: data.holdings.map(h => ({ symbol: h.symbol, weight: h.weight, status: h.status, measures: h.measures, coverage: h.coverage, unknowns: h.unknowns })) },
-        { title: "Company drivers", rows: data.holdings.flatMap(h => (h.extensions ?? []).map(row => ({ symbol: h.symbol, ...row }))) },
-        { title: "Paths and evidence", rows: data.holdings.flatMap(h => h.components.map(c => ({ symbol: h.symbol, ...c }))) },
-        { title: "Portfolio operating stress", rows: data.portfolio.measures.map(m => ({ ...m })) },
-        { title: "Concentrations", rows: data.portfolio.concentrations.map(c => ({ ...c })) },
+        { title: "Holdings", rows: data.holdings.map(h => ({ symbol: h.symbol, weight: h.weight, status: h.status, measures: h.measures, coverage: h.coverage, unknowns: h.unknowns })),
+          textColumns: fitted(holdingColumns(data), holdingRows), textRows: textRows(holdingRows) },
+        { title: "Company drivers", rows: data.holdings.flatMap(h => (h.extensions ?? []).map(row => ({ symbol: h.symbol, ...row }))),
+          textColumns: fitted(DRIVER_COLUMNS, drivers, [note]), textRows: textRows(drivers) },
+        { title: "Paths and evidence", rows: data.holdings.flatMap(h => h.components.map(c => ({ symbol: h.symbol, ...c }))),
+          textColumns: fitted(PATH_COLUMNS, paths), textRows: textRows(paths) },
+        { title: "Portfolio operating stress", rows: data.portfolio.measures.map(m => ({ ...m })),
+          textColumns: fitted(portfolioColumns(data, false, stress), stress, [note]), textRows: textRows(stress) },
+        { title: "Concentrations", rows: data.portfolio.concentrations.map(c => ({ ...c })),
+          textColumns: fitted(portfolioColumns(data, true, concentrations), concentrations), textRows: textRows(concentrations) },
       ], metadata: { payload: data } };
   },
 };

package/src/plugins/builtin/exposure/holdings.ts

@@ -4,7 +4,7 @@ import type { Portfolio, TickerRecord } from "../../../types/ticker";
 import { publicTickerKey } from "../../../utils/exchanges";
 import { resolveCurrencyUnit } from "../../../utils/currency-units";
 import { convertCurrency } from "../../../utils/format";
-import { getPortfolioPositionMetrics, getPortfolioQuoteDisplay, resolvePortfolioMarketValue } from "../portfolio-list/position-metrics";
+import { getPortfolioPositionMetrics, getPortfolioQuoteDisplay, resolvePortfolioMarketValue } from "../../../portfolio/position-metrics";
 
 /** Explicit NAV preserves cash, shorts and leverage; net holdings are never used as NAV. */
 export async function portfolioHoldings(portfolio: Portfolio, tickers: TickerRecord[], nav: number, market: Pick<DataProvider, "getQuote" | "getExchangeRate">): Promise<ExposureHolding[]> {

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

@@ -4,6 +4,7 @@ import { ExposurePane } from "./pane";
 
 export const exposureModule: PluginModule = {
   panes: [{ id: "exposure", name: "Exposure", icon: "E", component: ExposurePane, defaultPosition: "right", defaultMode: "floating", defaultFloatingSize: { width: 138, height: 31 }, tableExport: true, headless: exposureHeadless,
+    personalData: "holdings",
     portableShare: { private: { params: true, settings: true, state: true } } }],
   paneTemplates: [{ id: "exposure-pane", paneId: "exposure", label: "Exposure", description: "Pro scenario exposures across holdings, geographic revenue and supply chains, with source evidence and portfolio concentrations.",
     keywords: ["exposure", "scenario", "stress", "portfolio", "supply", "country", "tariff", "pro"],

package/src/plugins/builtin/exposure/model.ts

@@ -1,4 +1,5 @@
 import type { ExposureBasis, ExposureComponent, ExposureExtensionObservation, ExposureHolding, ExposurePayload, ExposureRange, ExposureScenario } from "../../../api-client/exposure";
+import { humanLabel } from "../shared/research-cells";
 
 export const TABS = [{ value: "table", label: "Table" }, { value: "drivers", label: "Drivers" }, { value: "paths", label: "Paths" }, { value: "portfolio", label: "Portfolio" }];
 export const DEFAULT_SCENARIO: ExposureScenario = { id: "taiwan-disruption", label: "Taiwan disruption", shocks: [{ id: "taiwan", kind: "country", target: "TW", changePct: -100 }] };
@@ -61,12 +62,31 @@ export interface ExposureRow {
   exposure: ExposureRange | null; impact: ExposureRange | null; weight: number | null;
   classification: string; incomplete: boolean; concentration?: boolean; components: ExposureComponent[]; unknowns: string[];
 }
-function shockLabel(data: ExposurePayload, id: string): string {
-  const shock = data.scenario.shocks.find(s => s.id === id);
-  if (!shock) return id;
+/** A table cell's text as the pane draws it; `fn EXPO` prints the same words. */
+export function exposureCellText(row: ExposureRow, column: "label" | "basis" | "exposure" | "classification" | "impact" | "period" | "weight"): string {
+  switch (column) {
+    case "label": return row.label;
+    case "basis": return row.basis ? humanLabel(basisLabel(row.basis)) : "--";
+    case "exposure": return row.exposure ? rangeText(row.exposure) : "Unknown";
+    // What the number rests on, in words: disclosed by the company, estimated by a chain, or not visible.
+    case "classification": return `${humanLabel(row.classification)}${row.incomplete && row.classification !== "unknown" ? " · partial" : ""}`;
+    case "impact": return row.impact ? rangeText(row.impact) : "--";
+    case "period": return row.period ?? "--";
+    case "weight": return fraction(row.weight ?? 0);
+  }
+}
+function shockText(shock: ExposureScenario["shocks"][number]): string {
   const change = shock.changeBps ?? shock.changePct;
   return `${shock.target}${change == null ? "" : ` ${change > 0 ? "+" : ""}${change}${shock.kind === "rate" ? "bp" : "%"}`}`;
 }
+function shockLabel(data: ExposurePayload, id: string): string {
+  const shock = data.scenario.shocks.find(s => s.id === id);
+  return shock ? shockText(shock) : id;
+}
+/** The scenario as the pane's scenario picker names it, with its one shock when it has one: Taiwan disruption (TW -100%). */
+export function scenarioTitle(scenario: ExposureScenario): string {
+  return `${scenario.label}${scenario.shocks.length === 1 ? ` (${shockText(scenario.shocks[0]!)})` : ""}`;
+}
 export function tableRows(data: ExposurePayload): ExposureRow[] {
   return data.holdings.flatMap<ExposureRow>(holding => [
     ...holding.measures.map((measure, i): ExposureRow => ({

package/src/plugins/builtin/exposure/pane.tsx

@@ -10,6 +10,7 @@ import type { PaneProps } from "../../../types/plugin";
 import { Box, ScrollBox, Text, useRendererHost, useUiCapabilities } from "../../../ui";
 import { SignInWall } from "../cloud/auth-actions";
 import { CLOUD_PLAN_KEY, useCloudUpgradeAction } from "../shared/cloud-upgrade";
+import { useOpenDescription } from "../shared/open-description";
 import { Blurred, LockedOverlay, UpgradeLabel } from "../shared/locked-rows";
 import { humanLabel, listingCell, missingCell } from "../shared/research-cells";
 import { isCloudSessionRequired, useResearchCloudSession } from "../shared/research-cloud-session";
@@ -17,9 +18,9 @@ import { ExposurePathDiagram, ExposureRanges } from "./charts";
 import { fetchExposure, fetchScenarios, validateExposure } from "./client";
 import { ExposureEditor, type ExposureInputs } from "./editor";
 import { portfolioHoldings, watchlistHoldings } from "./holdings";
-import { basisLabel, DEFAULT_SCENARIO, fraction, parseCustomScenario, parseHoldings, pathRows, portfolioRows, rangeText, tableRows, TABS, type ExposureRow } from "./model";
+import { basisLabel, DEFAULT_SCENARIO, exposureCellText, fraction, parseCustomScenario, parseHoldings, pathRows, portfolioRows, rangeText, tableRows, TABS, type ExposureRow } from "./model";
 import { useExposureEvidence } from "./evidence";
-import { driverRows, driverUnits, driverValue } from "./drivers";
+import { driverRows, driverScope, driverUnits, driverValue } from "./drivers";
 
 function EvidenceItem({ item }: { item: ExposureEvidence }) {
   const colors = useThemeColors();
@@ -79,6 +80,7 @@ export function ExposurePane({ width, height, focused }: PaneProps) {
   const accessKey = `${session.requestKey}:${access.hasProAccess ? "full" : "preview"}`;
   const upgrade = useCloudUpgradeAction("expo");
   const { createPaneFromTemplate } = usePluginAppActions();
+  const openDescription = useOpenDescription();
   const [openingScenario] = usePaneSettingValue("scenario", "taiwan-disruption");
   const [customSetting] = usePaneSettingValue("customScenario", "");
   const [openingDepth] = usePaneSettingValue("depth", 2);
@@ -130,7 +132,7 @@ export function ExposurePane({ width, height, focused }: PaneProps) {
   usePaneRefreshKey(() => void resource.reload(), { focused: focused && !editing });
   const rawRows = useMemo(() => !data ? [] : tab === "drivers" ? driverRows(data) : tab === "paths" ? pathRows(data) : tab === "portfolio" ? portfolioRows(data, view) : tableRows(data), [data, tab, view]);
   const rows = useMemo(() => [...rawRows].sort((a, b) => {
-    const get = (r: ExposureRow) => sort.column === "value" ? r.driver?.value ?? r.driver?.range?.high ?? -Infinity : sort.column === "units" ? r.driver ? driverUnits(r.driver) : "" : sort.column === "scope" ? Object.values(r.driver?.dimensions ?? {}).join(" · ") : sort.column === "classification" ? r.classification : sort.column === "label" ? r.label : sort.column === "period" ? r.period ?? "" : sort.column === "exposure" ? r.exposure?.high ?? -Infinity : sort.column === "impact" ? r.impact?.low ?? -Infinity : sort.column === "weight" ? r.weight ?? -Infinity : sort.column === "basis" ? r.basis ?? "" : r.symbol;
+    const get = (r: ExposureRow) => sort.column === "value" ? r.driver?.value ?? r.driver?.range?.high ?? -Infinity : sort.column === "units" ? r.driver ? driverUnits(r.driver) : "" : sort.column === "scope" ? r.driver ? driverScope(r.driver) : "" : sort.column === "classification" ? r.classification : sort.column === "label" ? r.label : sort.column === "period" ? r.period ?? "" : sort.column === "exposure" ? r.exposure?.high ?? -Infinity : sort.column === "impact" ? r.impact?.low ?? -Infinity : sort.column === "weight" ? r.weight ?? -Infinity : sort.column === "basis" ? r.basis ?? "" : r.symbol;
     const av = get(a), bv = get(b); const delta = typeof av === "number" && typeof bv === "number" ? av - bv : String(av).localeCompare(String(bv));
     return (sort.direction === "asc" ? delta : -delta) || a.id.localeCompare(b.id);
   }), [rawRows, sort]);
@@ -150,7 +152,7 @@ export function ExposurePane({ width, height, focused }: PaneProps) {
     ...(symbol ? [
       ...(activeRow?.driver ? [{ id: "dataset", key: "a", label: "ll disclosures", title: "Open company disclosures", onPress: () => createPaneFromTemplate(activeRow.driver!.kind === "kpi" ? "company-kpis-pane" : activeRow.driver!.kind === "guidance" ? "company-guidance-pane" : "credit-documents-pane", { symbol }) }] : []),
       { id: "supply", key: "c", label: "hain", title: "Supply chain", onPress: () => createPaneFromTemplate("supply-chain-pane", { symbol }) },
-      { id: "des", key: "d", label: "es", onPress: () => createPaneFromTemplate("new-ticker-detail-pane", { symbol }) },
+      { id: "des", key: "d", label: "es", onPress: () => openDescription(symbol) },
       { id: "fa", key: "f", label: "a", onPress: () => createPaneFromTemplate("financial-analysis-pane", { symbol }) },
       { id: "chart", key: "g", label: "raph", onPress: () => createPaneFromTemplate("chart-composer-pane", { arg: symbol }) },
     ] : []),
@@ -190,17 +192,17 @@ export function ExposurePane({ width, height, focused }: PaneProps) {
       case "symbol": return row.symbol.includes(",") ? { text: row.symbol, color: colors.textBright } : listingCell(row.symbol, colors, state.selected);
       case "value": return { text: row.driver ? driverValue(row.driver) : "--", value: row.driver?.value ?? null, color: colors.textBright };
       case "units": return { text: row.driver ? driverUnits(row.driver) : "", color: colors.textDim };
-      case "scope": return { text: Object.values(row.driver?.dimensions ?? {}).join(" · "), color: colors.textDim };
-      case "label": return { text: row.label, color: unknown ? colors.textDim : colors.text };
-      case "basis": return row.basis ? { text: humanLabel(basisLabel(row.basis)), color: colors.textDim } : missingCell(colors);
-      case "exposure": return row.exposure ? { text: rangeText(row.exposure), value: row.exposure.high, color: colors.textBright } : { text: "Unknown", value: null, color: colors.textMuted };
+      case "scope": return { text: row.driver ? driverScope(row.driver) : "", color: colors.textDim };
+      case "label": return { text: exposureCellText(row, "label"), color: unknown ? colors.textDim : colors.text };
+      case "basis": return row.basis ? { text: exposureCellText(row, "basis"), color: colors.textDim } : missingCell(colors);
+      case "exposure": return row.exposure ? { text: exposureCellText(row, "exposure"), value: row.exposure.high, color: colors.textBright } : { text: exposureCellText(row, "exposure"), value: null, color: colors.textMuted };
       // Disclosed figures stand out; estimates read plainly, and the word says which is which.
-      case "classification": return { text: `${humanLabel(row.classification)}${row.incomplete && !unknown ? " · partial" : ""}`,
+      case "classification": return { text: exposureCellText(row, "classification"),
         color: row.classification === "disclosed" ? colors.borderFocused : unknown ? colors.textMuted : colors.textDim, keepColorWhenSelected: row.classification === "disclosed" };
-      case "impact": return !row.impact ? missingCell(colors) : { text: rangeText(row.impact), value: row.impact.low,
+      case "impact": return !row.impact ? missingCell(colors) : { text: exposureCellText(row, "impact"), value: row.impact.low,
         color: row.concentration ? colors.text : row.impact.high < 0 ? colors.negative : row.impact.low > 0 ? colors.positive : colors.text };
-      case "period": return row.period ? { text: row.period, color: colors.textDim } : missingCell(colors);
-      default: return { text: fraction(row.weight ?? 0), value: row.weight === null ? null : row.weight * 100, color: colors.text };
+      case "period": return row.period ? { text: exposureCellText(row, "period"), color: colors.textDim } : missingCell(colors);
+      default: return { text: exposureCellText(row, "weight"), value: row.weight === null ? null : row.weight * 100, color: colors.text };
     }
   };
   const lockedRows = data?.access === "preview" ? Math.min(3, data.lockedHoldings) : 0;

package/src/plugins/builtin/fear-greed/index.tsx

@@ -1,4 +1,5 @@
 import { CLI_COMMAND_GROUPS } from "../../../cli/help";
+import { rowsFreshness } from "../../../cli/freshness";
 import type { GloomPlugin } from "../../../types/plugin";
 import {
   attachFearGreedPersistence,
@@ -7,6 +8,7 @@ import {
 } from "./cache";
 import { FearGreedPane } from "./pane";
 import { fearGreedHeadless } from "./headless";
+import { FEAR_GREED_SERIES } from "./series";
 
 export const fearGreedPlugin: GloomPlugin = {
   id: "fear-greed",
@@ -29,6 +31,9 @@ export const fearGreedPlugin: GloomPlugin = {
     resetFearGreedPersistence();
   },
 
+  // The index and its seven readings, chartable against anything else.
+  series: FEAR_GREED_SERIES,
+
   panes: [
     {
       id: "fear-greed",
@@ -62,17 +67,20 @@ export const fearGreedPlugin: GloomPlugin = {
       description: "Fetch CNN Fear & Greed gauge data",
       help: { group: CLI_COMMAND_GROUPS.markets },
       async execute(_args, ctx) {
-        const { data } = await loadFearGreed(ctx.cliOptions.refresh);
+        const { data, stale } = await loadFearGreed(ctx.cliOptions.refresh);
+        const rows = [{
+          score: data.overall.score,
+          rating: data.overall.rating,
+          updatedAt: data.overall.updatedAt?.toISOString() ?? "",
+          previousClose: data.overall.previousClose,
+          previousWeek: data.overall.previousWeek,
+          previousMonth: data.overall.previousMonth,
+          previousYear: data.overall.previousYear,
+        }];
         ctx.printResult({
-          data: [{
-            score: data.overall.score,
-            rating: data.overall.rating,
-            updatedAt: data.overall.updatedAt?.toISOString() ?? "",
-            previousClose: data.overall.previousClose,
-            previousWeek: data.overall.previousWeek,
-            previousMonth: data.overall.previousMonth,
-            previousYear: data.overall.previousYear,
-          }],
+          data: rows,
+          // Exports cite CNN's reading as `fn FNG` does; the text stays the row alone.
+          exportFreshness: rowsFreshness(rows, { source: "CNN", status: stale ? "stale" : "not-a-feed", basis: "published index" }),
           metadata: {
             indicators: data.indicators.map((indicator) => ({
               id: indicator.definition.id,

package/src/plugins/builtin/fear-greed/series.ts

@@ -0,0 +1,52 @@
+import type { SeriesDefinition, SeriesLoadResult, SeriesPoint } from "../../../series/types";
+import { cachedSeriesWarning } from "../shared/series-warning";
+import { loadFearGreed } from "./cache";
+import type { FearGreedData } from "./data";
+
+/** The index refreshes through the session; the pane's cache keeps a copy for five minutes. */
+const REFRESH_MS = 5 * 60_000;
+
+type Reading = (data: FearGreedData) => SeriesPoint[];
+
+function component(id: string, pick: "primary" | "secondary"): Reading {
+  return (data) => {
+    const indicator = data.indicators.find((entry) => entry.definition.id === id);
+    if (!indicator) throw new Error("This component is missing from the latest reading.");
+    if (pick === "primary") return indicator.points.map((point) => ({ date: point.date, value: point.close }));
+    return indicator.secondaryPoints.flatMap((point) => {
+      const date = indicator.points[point.index]?.date;
+      return date ? [{ date, value: point.value }] : [];
+    });
+  };
+}
+
+function series(id: string, name: string, unit: string, read: Reading, tags: readonly string[]): SeriesDefinition {
+  return {
+    id: `fear-greed:${id}`,
+    name,
+    unit,
+    frequency: "daily",
+    group: "Sentiment",
+    tags: ["fear and greed", ...tags],
+    refreshMs: REFRESH_MS,
+    load: async (): Promise<SeriesLoadResult> => {
+      const result = await loadFearGreed();
+      const warning = cachedSeriesWarning(result);
+      return { points: read(result.data), ...(warning ? { warning } : {}) };
+    },
+  };
+}
+
+/** The index and the seven readings it is built from, as the pane charts them. */
+export const FEAR_GREED_SERIES: readonly SeriesDefinition[] = [
+  series("index", "Fear & Greed index", "score", (data) => data.overall.history.map((point) => ({ date: point.date, value: point.close })), ["sentiment"]),
+  series("market-momentum", "Fear & Greed: S&P 500 momentum", "index", component("market-momentum", "primary"), ["momentum", "S&P 500"]),
+  series("market-momentum-average", "Fear & Greed: S&P 500 125-day average", "index", component("market-momentum", "secondary"), ["momentum", "moving average"]),
+  series("stock-price-strength", "Fear & Greed: net new 52-week highs", "%", component("stock-price-strength", "primary"), ["breadth", "highs and lows"]),
+  series("stock-price-breadth", "Fear & Greed: McClellan volume summation", "index", component("stock-price-breadth", "primary"), ["breadth", "McClellan"]),
+  series("put-call-options", "Fear & Greed: 5-day put/call ratio", "ratio", component("put-call-options", "primary"), ["options", "put call"]),
+  series("market-volatility", "Fear & Greed: VIX", "index", component("market-volatility", "primary"), ["volatility", "VIX"]),
+  series("market-volatility-average", "Fear & Greed: VIX 50-day average", "index", component("market-volatility", "secondary"), ["volatility", "moving average"]),
+  series("safe-haven-demand", "Fear & Greed: stocks minus bonds, 20-day return", "%", component("safe-haven-demand", "primary"), ["safe haven", "bonds"]),
+  series("junk-bond-demand", "Fear & Greed: junk bond spread", "%", component("junk-bond-demand", "primary"), ["credit", "high yield", "junk"]),
+];

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

@@ -13,6 +13,7 @@ import {
   type PaneFooterSegment,
 } from "../../../components";
 import { handleRefreshKey } from "../../../components/data-table/table-pane";
+import { useRemoteUiNode } from "../../../remote/semantic-tree";
 import { usePaneVisible } from "../../../state/app/activity";
 import { usePaneInstance } from "../../../state/app/context";
 import { TICKER_RESEARCH_PANE_ID } from "../../../types/config";
@@ -22,7 +23,9 @@ import { isPlainArrowUp, stopSearchFocusNavigation } from "../../../utils/search
 import { cycleSortPreference, nextHeaderSort } from "../../../utils/sort-values";
 import { useAssetData, usePluginTickerActions } from "../../runtime";
 import type { PluginModule } from "../plugin-module";
+import { FUTURES_SERIES } from "./series";
 import { useLiveStreamingSetting } from "../../../state/hooks/live-streaming";
+import { quoteObservation } from "../shared/report-freshness";
 import {
   boardErrorMessage,
   quoteBoardFooterInfo,
@@ -34,9 +37,10 @@ import {
 import {
   FUTURES_CONTRACTS,
   FUTURES_SECTOR_LABELS,
+  futuresBoardContract,
   getContractsBySector,
   type FuturesSector,
-} from "./contracts";
+} from "../../../market-data/futures-board";
 import {
   buildFuturesRows,
   DEFAULT_FUTURES_SORT,
@@ -75,7 +79,8 @@ function FuturesPane({ focused, width, height }: PaneProps) {
   const liveStreaming = useLiveStreamingSetting();
   const [selectedId, setSelectedId] = useState<string | null>(null);
   const [sortPreference, setSortPreference] = useState<FuturesSortPreference>(DEFAULT_FUTURES_SORT);
-  const [searchQuery, setSearchQuery] = useState("");
+  // `FUT TTF` opens the board searched for the contract it names.
+  const [searchQuery, setSearchQuery] = useState(() => paneInstance?.params?.query ?? "");
   const { active: searchFocused, focus: focusSearch, searchProps } = useQueryBarSearch();
   const [collapsedSectors, setCollapsedSectors] = useState<ReadonlySet<FuturesSector>>(new Set());
   const [visibleRange, setVisibleRange] = useState<DataTableVisibleRange | null>(null);
@@ -196,6 +201,17 @@ function FuturesPane({ focused, width, height }: PaneProps) {
     return handlePaneKey(event);
   }, [focusSearch, handlePaneKey]);
 
+  // `fn FUT` and `shot FUT` are dated by the quotes the board shows, as `quote` dates them:
+  // the newest, its delay, and whether the markets are open.
+  useRemoteUiNode(quotes.size > 0 ? {
+    role: "report-freshness",
+    label: "Quote freshness",
+    getMetadata: () => {
+      const now = Date.now();
+      return { observations: [...quotes.values()].flatMap((state) => (state.quote ? [quoteObservation(state.quote, now)] : [])) };
+    },
+  } : null);
+
   const status = quoteBoardStatus(quotes);
   const errorMessage = boardErrorMessage(quotes);
   // Every load came back empty: a board of dashes reads as broken, so the
@@ -265,6 +281,7 @@ function FuturesPane({ focused, width, height }: PaneProps) {
       renderSectionHeader={renderSectorHeader}
       renderCell={renderCell}
       selectedTextOverridesCellColor
+      reportEveryRow
       emptyStateTitle={searchQuery.trim()
         ? "No matching contracts."
         : "No market data provider connected."}
@@ -288,6 +305,7 @@ function FuturesPane({ focused, width, height }: PaneProps) {
 }
 
 export const futuresModule: PluginModule = {
+  series: FUTURES_SERIES,
   panes: [
     {
       id: FUTURES_PANE_ID,
@@ -298,6 +316,7 @@ export const futuresModule: PluginModule = {
       defaultMode: "floating",
       defaultFloatingSize: { width: 76, height: 34 },
       tableExport: true,
+      shotFitsRows: true,
       // Resolved per open so the dialog shows the full default set until the
       // user saves a narrower selection.
       settings: (context) => ({
@@ -341,11 +360,32 @@ export const futuresModule: PluginModule = {
         "lumber",
         "aluminum",
         "ttf",
+        "energy",
+        "natural gas",
+        "gas",
+        "lng",
+        "brent",
+        "wti",
+        "heating oil",
+        "gasoline",
         "treasuries",
         "contracts",
         "cme",
       ],
-      shortcut: { prefix: "FUT", aliases: ["GLCO"] },
+      shortcut: {
+        prefix: "FUT",
+        aliases: ["GLCO"],
+        argKind: "text",
+        argPlaceholder: "code or name",
+        argOptional: true,
+      },
+      // A board code or symbol searches for that contract alone (NG=F: a bare NG also matches Orange Juice); other text searches as typed.
+      createInstance: (_context, options) => {
+        const input = options?.arg?.trim();
+        if (!input) return {};
+        const query = futuresBoardContract(input)?.symbol ?? input;
+        return { title: `FUT ${input.toUpperCase()}`, params: { query } };
+      },
     },
   ],
 };

package/src/plugins/builtin/futures/model.ts

@@ -1,7 +1,7 @@
 import type { Quote } from "../../../types/financials";
 import { compareSortValues, type SortDirection } from "../../../utils/sort-values";
 import type { BoardQuoteMap } from "../shared/use-quote-board";
-import { FUTURES_SECTOR_ORDER, type FuturesContract, type FuturesSector } from "./contracts";
+import { FUTURES_SECTOR_ORDER, type FuturesContract, type FuturesSector } from "../../../market-data/futures-board";
 import type { FuturesReturnHorizon } from "./returns";
 import type { FrontReturnsMap } from "./use-front-returns";