gloomberb 0.16.4 → 0.16.6

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

@@ -16,18 +16,20 @@ import { publicTickerKey } from "../../../utils/exchanges";
 import { truncateToDisplayWidth } from "../../../utils/format";
 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 { isCloudSessionRequired, useResearchCloudSession } from "../shared/research-cloud-session";
 import { AwardDetail } from "./detail";
 import { useAwardAlerts } from "./alerts";
 import { AWARDS_UNAVAILABLE, fetchAwards, loadAward, loadAwards, validateAwards } from "./client";
 import { useAwardsEvidence } from "./evidence";
-import { AWARD_TABS, aggregateId, awardHistorySeries, awardPercent, awardPeriod, awardScope, awardTab, awardTypeLabel, money, rankedAggregates } from "./model";
+import { AWARD_TABS, aggregateId, awardHistorySeries, awardPercent, awardPeriod, awardScope, awardsPreviewNote, awardTab, awardTypeLabel, futureAwardDatesNote, money,
+  rankedAggregates } from "./model";
 
 type Item = { kind: "award"; row: AwardRow } | { kind: "aggregate"; row: AwardAggregate } | { kind: "leader"; row: AwardCompanyLeader } | { kind: "locked"; id: string }
-  | { kind: "section"; id: string; label: string; count: number };
-const itemId = (item: Item) => item.kind === "locked" || item.kind === "section" ? item.id : item.kind === "award" ? item.row.id : item.kind === "leader" ? `${aggregateId(item.row)}:${item.row.sector}` : aggregateId(item.row);
-const isRowItem = (item: Item) => item.kind !== "section";
+  | { kind: "section"; id: string; label: string; count: number } | { kind: "note"; id: string; text: string };
+const itemId = (item: Item) => item.kind === "locked" || item.kind === "section" || item.kind === "note" ? item.id : item.kind === "award" ? item.row.id : item.kind === "leader" ? `${aggregateId(item.row)}:${item.row.sector}` : aggregateId(item.row);
+const isRowItem = (item: Item) => item.kind !== "section" && item.kind !== "note";
 /** Shares only compare inside one scope and currency, so each pair is its own section. */
 function groupedAggregates<T extends AwardAggregate>(rows: readonly T[], toItem: (row: T) => Item): Item[] {
   const groups = new Map<string, T[]>();
@@ -72,6 +74,7 @@ function AwardsView({ width, height, focused, symbol }: PaneProps & { symbol: st
   const accessKey = `${session.requestKey}:${access.hasProAccess ? "full" : "preview"}`;
   const openUpgrade = useCloudUpgradeAction("awards");
   const { createPaneFromTemplate } = usePluginAppActions();
+  const openDescription = useOpenDescription();
   const [initialTab] = usePaneSettingValue("tab", symbol ? "company" : "feed");
   const [savedTab, setTab] = usePluginPaneState<string>("awards:tab", initialTab);
   const tab = awardTab(savedTab);
@@ -131,10 +134,13 @@ function AwardsView({ width, height, focused, symbol }: PaneProps & { symbol: st
   const aggregates = useMemo(() => rankedAggregates(tab === "agencies" ? data?.agencies ?? [] : data?.sectors ?? [], currency, awardType), [data, tab, currency, awardType]);
   const aggregated = tab === "agencies" || tab === "sectors";
   const showLeaders = tab === "sectors" && leaderView === "companies";
+  // A preview is the same latest awards whatever the filters say, so its award rows open with what they are.
+  const previewNote = data && (tab === "feed" || tab === "company") ? awardsPreviewNote(data, filter) : null;
   const items = useMemo<Item[]>(() => [
+    ...(previewNote ? [{ kind: "note" as const, id: "note:preview", text: previewNote }] : []),
     ...(showLeaders ? groupedAggregates(data?.leaders ?? [], (row): Item => ({ kind: "leader", row })) : aggregated ? groupedAggregates(aggregates, (row): Item => ({ kind: "aggregate", row })) : rows.map((row): Item => ({ kind: "award", row }))),
     ...(data?.locked ? Array.from({ length: 3 }, (_, i): Item => ({ kind: "locked", id: `locked:${i}` })) : []),
-  ], [showLeaders, aggregated, aggregates, rows, data?.leaders, data?.locked]);
+  ], [previewNote, showLeaders, aggregated, aggregates, rows, data?.leaders, data?.locked]);
   const selected = tab === "company" && !ticker ? null
     : items.find((item) => itemId(item) === selectedId && isRowItem(item)) ?? items.find(isRowItem) ?? null;
   const current = openRow ?? (selected?.kind === "award" ? selected.row : null);
@@ -157,7 +163,7 @@ function AwardsView({ width, height, focused, symbol }: PaneProps & { symbol: st
     ...(current ? [{ id: "source", key: "o", label: "pen source", onPress: () => void host.openExternal(current.sourceUrl) }] : []),
     ...(current && !openId ? [{ id: "evidence", key: "e", label: "vidence", onPress: () => setOpen(current.id) }] : []),
     ...(selectedEntity ? [
-      { id: "description", key: "d", label: "es", onPress: () => navigate("new-ticker-detail-pane") },
+      { id: "description", key: "d", label: "es", onPress: () => openDescription(selectedEntity.ticker, selectedEntity.exchange ?? undefined) },
       { id: "financials", key: "f", label: "a", onPress: () => navigate("financial-analysis-pane") },
       { id: "graph", key: "g", label: "raph", onPress: () => navigate("chart-composer-pane") },
       { id: "supply", key: "s", label: "plc", onPress: () => navigate("supply-chain-pane") },
@@ -174,6 +180,7 @@ function AwardsView({ width, height, focused, symbol }: PaneProps & { symbol: st
     ...(data?.truncated && Object.values(data.truncated).some(Boolean) ? ["Some aggregate history exceeds this response's limit. Narrow the date range or scope."] : []),
     ...(tab === "company" && currencies.length > 1 && !currency ? [`Chart in ${chartCurrency}; select a currency to inspect other obligations.`] : []),
     ...(tab === "company" && scopes.length > 1 && !source ? [`Chart covers ${awardScope(chartSource).toLowerCase()}; select a scope to inspect other contracts.`] : []),
+    ...(data && (tab === "feed" || tab === "company") ? [futureAwardDatesNote(rows, data.generatedAt)].filter((note): note is string => !!note) : []),
   ] });
   const { strip, rows: tabRows } = usePaneTabs(!denied ? { tabs: [...AWARD_TABS], activeValue: tab, onSelect: (value) => { setTab(value); setOpen(null); }, focused, dense: true } : null);
   const bodyHeight = Math.max(3, height - tabRows);
@@ -194,10 +201,12 @@ function AwardsView({ width, height, focused, symbol }: PaneProps & { symbol: st
     : aggregated ? AGG_COLUMNS.filter((column) => column.id !== "scope" && column.id !== "currency").map((column) => column.id === "label" ? { ...column, label: tab === "agencies" ? "Agency" : "Sector" } : column)
     : tab === "events" ? EVENT_COLUMNS : FEED_COLUMNS;
   const maxShare = Math.max(0, ...items.map((item) => item.kind === "aggregate" || item.kind === "leader" ? item.row.sharePercent ?? 0 : 0));
-  const latest = data?.history.filter((row) => row.source === chartSource && row.currency === chartCurrency && row.awardType === awardType).at(-1);
-  const chart = tab === "company" && ticker ? { series, formatValue: (value: number) => `${chartCurrency} ${money(value)}`, formatAxisValue: formatCompactAxis, ...chartSelection,
-    remoteKind: "award-obligations", empty: series.length ? undefined : data?.locked ? "Full award history requires Pro." : "History is accumulating for this company." } : null;
-  useAwardsEvidence(data, tab, tab === "company" && !ticker ? 0 : items.filter((item) => item.kind !== "locked").length);
+  // A preview's cohorts are the latest of any company, so they never chart as the ticker's.
+  const charted = data?.locked ? [] : series;
+  const latest = data?.locked ? undefined : data?.history.filter((row) => row.source === chartSource && row.currency === chartCurrency && row.awardType === awardType).at(-1);
+  const chart = tab === "company" && ticker ? { series: charted, formatValue: (value: number) => `${chartCurrency} ${money(value)}`, formatAxisValue: formatCompactAxis, ...chartSelection,
+    remoteKind: "award-obligations", empty: charted.length ? undefined : data?.locked ? "Full award history requires Pro." : "History is accumulating for this company." } : null;
+  useAwardsEvidence(data, tab, tab === "company" && !ticker ? 0 : items.filter((item) => item.kind !== "locked" && item.kind !== "note").length);
   if (denied || !data && isCloudSessionRequired(failed?.message)) return <SignInWall placement="awards-signin" action="view government awards" needsVerification={session.needsVerification} />;
   return <Box width={width} height={height} flexDirection="column">
     {strip}
@@ -213,15 +222,15 @@ function AwardsView({ width, height, focused, symbol }: PaneProps & { symbol: st
             figures={tab === "company" && ticker && latest ? [{ id: "total", label: `Obligated ${chartCurrency}`, value: money(latest.cumulativeObligatedAmount) },
               { id: "period", label: "Latest cohort", value: latest.month.slice(0, 7), detail: awardScope(chartSource) }] : undefined} />}
           selection={{ kind: "id", selectedId: selected ? itemId(selected) : null, getId: itemId, onChange: setSelected }} getItemKey={itemId}
-          isNavigable={isRowItem} renderSectionHeader={(item) => item.kind === "section" ? { text: `${item.label} (${item.count})` } : null}
-          onActivate={(item) => { if (item.kind === "section") return; if (item.kind === "locked") openUpgrade(); else if (item.kind === "award") setOpen(item.row.id);
+          isNavigable={isRowItem} renderSectionHeader={(item) => item.kind === "section" ? { text: `${item.label} (${item.count})` } : item.kind === "note" ? { text: item.text } : null}
+          onActivate={(item) => { if (item.kind === "section" || item.kind === "note") return; if (item.kind === "locked") openUpgrade(); else if (item.kind === "award") setOpen(item.row.id);
             else if (item.kind === "leader") { setCurrency(item.row.currency); setSource(item.row.source); setSector(item.row.sector);
               if (item.row.ticker) { setTicker(publicTickerKey(item.row.ticker, item.row.exchange ?? undefined)); setTab("company"); } else { setQuery(item.row.label); setTab("feed"); } }
             else { setCurrency(item.row.currency); setSource(item.row.source);
               if (tab === "agencies") { setAgency(item.row.key); setTab("feed"); } else { setSector(item.row.key); setLeaderView("companies"); } } }}
           sortColumnId={null} sortDirection="desc" selectedTextOverridesCellColor showHorizontalScrollbar resetScrollKey={JSON.stringify([tab, filter])}
           renderCell={(item, column, _index, state) => {
-            if (item.kind === "section") return { text: "" };
+            if (item.kind === "section" || item.kind === "note") return { text: "" };
             if (item.kind === "locked") {
               if (!desktop && ["recipient", "label"].includes(column.id) && item.id === "locked:0") return { text: "Upgrade for full awards", content: <UpgradeLabel text="Upgrade for full awards" onPress={openUpgrade} />, onMouseDown: openUpgrade };
               return desktop ? { text: "", content: <Blurred><Text fg={colors.textDim}>{["recipient", "label"].includes(column.id) ? "Additional award" : "Hidden"}</Text></Blurred> }

package/src/plugins/builtin/awards/series.ts

@@ -0,0 +1,29 @@
+import type { SeriesDefinition } from "../../../series/types";
+import { fetchAwards } from "./client";
+
+/** The scope AWARDS calls "US federal contracts": one source, one currency and prime awards, so no total counts a contract twice. */
+const US_FEDERAL = { source: "usaspending", currency: "USD", awardType: "prime" } as const;
+
+/**
+ * A company's US federal contract obligations by month, as AWARDS charts its
+ * company history. Pro: the free preview is one shared view, not the
+ * company's history, so it fails with the pane's own words.
+ */
+export const AWARD_SERIES: readonly SeriesDefinition[] = [{
+  id: "awards:us-federal-obligations",
+  name: "US federal contract obligations",
+  unit: "USD",
+  frequency: "monthly",
+  group: "Alternative data",
+  tags: ["government awards", "contracts", "procurement", "defense", "obligations"],
+  description: "Obligated dollars on US federal prime contracts awarded to the company, by award month, as AWARDS charts them. Needs Pro.",
+  input: "ticker",
+  style: "columns",
+  load: async ({ ticker, signal }) => {
+    const data = await fetchAwards({ ticker: ticker!, ...US_FEDERAL, limit: 1 }, undefined, signal);
+    if (data.locked || data.access === "preview") throw new Error("Full award history requires Pro.");
+    const rows = data.history.filter((row) => row.source === US_FEDERAL.source && row.currency === US_FEDERAL.currency && row.awardType === US_FEDERAL.awardType);
+    if (!rows.length) throw new Error(`No US federal contracts awarded to ${ticker}.`);
+    return rows.map((row) => ({ date: `${row.month.slice(0, 7)}-01`, value: row.obligatedAmount === null ? null : Number(row.obligatedAmount) }));
+  },
+}];

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

@@ -15,8 +15,8 @@ export const backtestHeadless: HeadlessPaneDefinition<"bundle"> = {
     aliases: ["BT", "BTST"],
     screenshotReadiness: "live-dom",
     limitations: [
-      "Long-only, one instrument, daily bars; signals fill at the next session's open",
-      "Price returns: dividends, borrow and cash interest are not modelled",
+      "Long-only, one instrument, daily bars; signals fill at the next session's open.",
+      "Price returns: dividends, borrow and cash interest are not modelled.",
     ],
   },
   options: [

package/src/plugins/builtin/bond-calculator/model.ts

@@ -1,3 +1,4 @@
+import { numberErrorMessage } from "../../../utils/decimal-comma";
 import { priceBond, solveBondYield, treasurySpread, type BondTerms, type TreasuryBenchmarkPoint } from "./math";
 
 export interface BondDraft {
@@ -20,7 +21,7 @@ export function defaultBondDraft(now = new Date()): BondDraft {
 }
 
 function inputNumber(value: string, label: string): number {
-  if (!value.trim() || !/^[+-]?(?:\d+(?:\.\d*)?|\.\d+)$/.test(value.trim())) throw new Error(`${label} must be a number`);
+  if (!value.trim() || !/^[+-]?(?:\d+(?:\.\d*)?|\.\d+)$/.test(value.trim())) throw new Error(numberErrorMessage(`${label} must be a number`, value));
   const number = Number(value);
   if (!Number.isFinite(number)) throw new Error(`${label} must be finite`);
   return number;

package/src/plugins/builtin/broker-manager/index.tsx

@@ -338,6 +338,7 @@ export const brokerManagerModule: PluginModule = {
     {
       id: "brokers",
       name: "Brokers",
+      personalData: "account",
       icon: "B",
       component: BrokersPane,
       defaultPosition: "right",

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

@@ -19,7 +19,7 @@ function definition(litigation: boolean): HeadlessPaneDefinition<"bundle"> {
       { key: "detailTab", type: "enum", values: [{ value: "evidence" }, { value: "history" }], defaultValue: "evidence", description: "Detail section for screenshots." },
       { key: "event", type: "string", settingKey: "open", description: "Event ID for evidence and revision history." },
     ],
-    discovery: { aliases: [litigation ? "LITI" : "CATL"], dataRequirements: ["Gloom Cloud catalyst records"], limitations: ["Pro; free preview includes three events", "Only published dates and confidently resolved corporate parties are linked", "Coverage varies by jurisdiction and source; absence is not proof of no event"] },
+    discovery: { aliases: [litigation ? "LITI" : "CATL"], dataRequirements: ["Gloom Cloud catalyst records"], limitations: ["Pro; free preview includes three events.", "Only published dates and confidently resolved corporate parties are linked.", "Coverage varies by jurisdiction and source; absence is not proof of no event."] },
     describe: litigation ? "Company litigation, enforcement and antitrust dockets with evidence" : "Regulatory, clinical, legal and trade-policy catalyst calendar with provenance",
     async load(args, ctx) {
       if (typeof args.options.event === "string" && args.options.event) {

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

@@ -14,6 +14,7 @@ import type { PaneProps } from "../../../types/plugin";
 import { Box, Text, useUiCapabilities, type ScrollBoxRenderable } 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 { listingCell } from "../shared/research-cells";
 import { isCloudSessionRequired, useResearchCloudSession } from "../shared/research-cloud-session";
@@ -47,6 +48,7 @@ export function CatalystView({ width, height, focused, symbol, litigation = fals
   const access = usePlanAccess();
   const accessKey = `${session.requestKey}:${access.hasProAccess ? "full" : "preview"}`;
   const { createPaneFromTemplate, openPluginCommandWorkflow } = usePluginAppActions();
+  const openDescription = useOpenDescription();
   const openUpgrade = useCloudUpgradeAction("catl");
   const [initialTab] = usePaneSettingValue("tab", "calendar");
   const [savedTab, setTab] = usePluginPaneState("catalyst:tab", initialTab);
@@ -100,7 +102,7 @@ export function CatalystView({ width, height, focused, symbol, litigation = fals
   const { strip, rows: tabRows } = usePaneTabs(!openId ? { tabs: [...CATALYST_TABS].map((item) => litigation && item.value === "calendar" ? { ...item, label: "Dockets" } : item), activeValue: tab, onSelect: (value) => { setTab(value); setSelectedId(null); }, focused, dense: true } : null);
   const selectedSymbol = selected ? catalystSymbol(selected) : symbol;
   const hints: PaneHint[] = [
-    ...(!openId && selectedSymbol ? [{ id: "description", key: "d", label: "es", onPress: () => createPaneFromTemplate("new-ticker-detail-pane", { symbol: selectedSymbol }) },
+    ...(!openId && selectedSymbol ? [{ id: "description", key: "d", label: "es", onPress: () => openDescription(selectedSymbol) },
       { id: "financials", key: "f", label: "a", onPress: () => createPaneFromTemplate("financial-analysis-pane", { symbol: selectedSymbol }) },
       { id: "chart", key: "g", label: "raph", onPress: () => createPaneFromTemplate("chart-composer-pane", { arg: selectedSymbol }) },
       { id: "related", key: "t", label: litigation ? "o calendar" : "o litigation", onPress: () => createPaneFromTemplate(litigation ? "catalysts-pane" : "litigation-pane", { symbol: selectedSymbol }) }] : []),

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

@@ -2,21 +2,33 @@ import {
   apiClient,
   type CloudCdsHistoryPointPayload,
   type CloudCdsHistoryResponse,
+  type CloudCdsLevelsResponse,
   type CloudCdsResponse,
 } from "../../../api-client";
 import type { CloudCdsHistoryParams } from "../../../api-client/paths";
 import type { InstrumentSearchResult } from "../../../types/instrument";
-import { normalizeCdsTrades, type CdsTrade } from "./model";
+import {
+  cdsReferenceEntity,
+  issuerNameOf,
+  normalizeCdsTrades,
+  spreadLevelsOf,
+  type CdsSpreadLevels,
+  type CdsTrade,
+} from "./model";
 
 /** One trading week of public dissemination is what "recent activity" means here. */
-const CDS_HISTORY_DAYS = 5;
+export const CDS_TRADE_DAYS = 5;
 const CDS_TRADE_LIMIT = 500;
 
 export interface CdsActivity {
   source: string;
   asOf: string | null;
+  /** What was asked for, as typed: a ticker or a name. Null for the market-wide view. */
+  query: string | null;
   /** The issuer name actually sent, after any symbol lookup. */
   issuer: string | null;
+  /** How many days of the tape the trades cover. */
+  days: number;
   trades: CdsTrade[];
 }
 
@@ -27,7 +39,8 @@ export type InstrumentSearch = (query: string, limit?: number) => Promise<Instru
 
 /**
  * A bare ticker with normal symbol punctuation and no spaces. Anything longer or
- * containing a space is already a company name and is sent to the backend as-is.
+ * containing a space is already a company name and is sent as the tape would
+ * name it.
  */
 const TICKER_LIKE = /^[A-Za-z0-9][A-Za-z0-9.^:-]{0,11}$/;
 const US_PRIMARY_EXCHANGES = new Set(["AMEX", "NASDAQ", "NYSE", "NYSEAMERICAN", "NYSEARCA"]);
@@ -42,22 +55,28 @@ function isPrimaryUsCommonStock(result: InstrumentSearchResult): boolean {
 
 /**
  * The backend matches DTCC issuer names, so a ticker has to become a company
- * name first. An untracked symbol has no local metadata to expand it, and its
- * quote name never arrives for a fixed binding, so the shared instrument search
- * is the only reliable expansion. A search outage falls back to the raw input
- * rather than taking the CDS request down with it.
+ * name first: its reference entity when the debt sits with another entity,
+ * else the listed company's name without its share class ("Alphabet Inc.",
+ * not "Alphabet Inc. Class A Common Stock"). An untracked symbol has no local
+ * metadata to expand it, and its quote name never arrives for a fixed
+ * binding, so the shared instrument search is the only reliable expansion. A
+ * search outage falls back to the raw input rather than taking the CDS
+ * request down with it.
  */
-async function resolveIssuerName(
+export async function resolveIssuerName(
   issuer: string,
   searchInstruments: InstrumentSearch,
 ): Promise<string> {
-  if (!TICKER_LIKE.test(issuer)) return issuer;
+  if (!TICKER_LIKE.test(issuer)) return issuerNameOf(issuer);
+  const referenceEntity = cdsReferenceEntity(issuer);
+  if (referenceEntity) return referenceEntity;
   try {
     const results = await searchInstruments(issuer);
     const symbol = issuer.toUpperCase();
     const exactMatches = results.filter((result) => result.symbol.toUpperCase() === symbol);
     const match = exactMatches.find(isPrimaryUsCommonStock) ?? exactMatches[0] ?? results[0];
-    return match?.name?.trim() || issuer;
+    const name = match?.name?.trim();
+    return name ? issuerNameOf(name) : issuer;
   } catch {
     return issuer;
   }
@@ -68,16 +87,19 @@ export async function loadCdsActivity(
   fetchCds: CdsFetch = (params) => apiClient.getCloudCds(params),
   searchInstruments: InstrumentSearch = (query, limit) => apiClient.searchInstruments(query, limit),
 ): Promise<CdsActivity> {
-  const resolved = issuer ? await resolveIssuerName(issuer, searchInstruments) : null;
+  const query = issuer?.trim() || null;
+  const resolved = query ? await resolveIssuerName(query, searchInstruments) : null;
   const response = await fetchCds({
     ...(resolved ? { issuer: resolved } : {}),
-    days: CDS_HISTORY_DAYS,
+    days: CDS_TRADE_DAYS,
     limit: CDS_TRADE_LIMIT,
   });
   return {
     source: response.source,
     asOf: response.asOf,
+    query,
     issuer: resolved,
+    days: CDS_TRADE_DAYS,
     trades: normalizeCdsTrades(response.trades ?? []),
   };
 }
@@ -107,3 +129,18 @@ export async function loadCdsSpreadHistory(
     .toSorted((left, right) => left.date.localeCompare(right.date));
   return { issuer: response.issuer, points };
 }
+
+export type CdsLevelsFetch = () => Promise<CloudCdsLevelsResponse>;
+export type CdsSpreadLevelsLoader = () => Promise<CdsSpreadLevels>;
+
+/**
+ * Every listed issuer's latest 5Y level, in one request: the last point of
+ * each name's line over the last month, the line the pane charts, so the list
+ * can be ranked by it. A name without one is not in the response.
+ */
+export async function loadCdsSpreadLevels(
+  fetchLevels: CdsLevelsFetch = () => apiClient.getCloudCdsLevels(),
+): Promise<CdsSpreadLevels> {
+  const response = await fetchLevels();
+  return spreadLevelsOf(response.levels ?? []);
+}

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

@@ -1,32 +1,50 @@
 import type {
+  HeadlessBundleResult,
+  HeadlessBundleSection,
   HeadlessPaneDefinition,
+  HeadlessPaneEntry,
   HeadlessPaneLoadArgs,
-  HeadlessRowsResult,
 } from "../../../types/plugin";
 import {
+  CDS_TRADE_DAYS,
   loadCdsActivity,
+  loadCdsSpreadHistory,
+  loadCdsSpreadLevels,
   type CdsActivity,
   type CdsFetch,
+  type CdsHistoryFetch,
+  type CdsLevelsFetch,
+  type CdsSpreadHistory,
   type InstrumentSearch,
 } from "./client";
 import {
   DEFAULT_ISSUER_SORT,
   DEFAULT_TRADE_SORT,
+  cdsFreshness,
+  displayIssuerName,
   formatBp,
   formatEventTime,
   formatNotional,
+  formatSpreadChange,
+  formatSpreadRange,
   formatUpfront,
+  lastTradeOf,
+  noTradesMessage,
   sortIssuers,
   sortTrades,
+  spreadSummary,
   summarizeIssuers,
+  withSpreadLevels,
+  type CdsSpreadLevels,
   type CdsTrade,
 } from "./model";
 
 const ISSUER_COLUMNS = [
   { key: "issuer", header: "Issuer" },
   { key: "trades", header: "Trades", align: "right" as const },
-  { key: "lastTradeAt", header: "Last UTC", format: (value: unknown) => formatEventTime(Number(value)) },
-  { key: "latestSpreadBp", header: "Spread", align: "right" as const, format: (value: unknown) => formatBp(value as number | null) },
+  { key: "lastTradeAt", header: "Last UTC", shrink: false, format: (value: unknown) => formatEventTime(Number(value)) },
+  { key: "spread5yBp", header: "5Y spread", align: "right" as const, format: (value: unknown) => formatBp(value as number | null) },
+  { key: "spread5yDate", header: "5Y date", shrink: false, format: (value: unknown) => (typeof value === "string" ? value : "--") },
 ];
 
 function tradeForFormatting(row: Record<string, unknown>): CdsTrade {
@@ -34,7 +52,7 @@ function tradeForFormatting(row: Record<string, unknown>): CdsTrade {
 }
 
 const TRADE_COLUMNS = [
-  { key: "eventAt", header: "Time UTC", format: (value: unknown) => formatEventTime(Number(value)) },
+  { key: "eventAt", header: "Time UTC", shrink: false, format: (value: unknown) => formatEventTime(Number(value)) },
   { key: "issuer", header: "Issuer" },
   { key: "maturity", header: "Maturity" },
   {
@@ -48,27 +66,94 @@ const TRADE_COLUMNS = [
   { key: "spreadBp", header: "Spread", align: "right" as const, format: (value: unknown) => formatBp(value as number | null) },
   {
     key: "upfront",
-    header: "Upfront",
+    header: "Abs upfront",
     align: "right" as const,
     format: (_value: unknown, row: Record<string, unknown>) => formatUpfront(tradeForFormatting(row)),
   },
 ];
 
-function projectCdsHeadless(activity: CdsActivity, issuer: string | null): HeadlessRowsResult {
-  if (issuer) {
+/**
+ * The pane's figures over its 5Y chart, as label and value lines: the level,
+ * its date, the 1M move on the same contract (`--` across a roll) and the
+ * range charted. JSON keeps the numbers; text and CSV read as the pane does.
+ */
+function spreadEntries(history: CdsSpreadHistory): HeadlessPaneEntry[] {
+  const summary = spreadSummary(history.points);
+  if (!summary) return [];
+  return [
+    { key: "spreadBp", label: "5Y spread", value: summary.spreadBp, formatted: formatBp(summary.spreadBp) },
+    { key: "date", label: "Date", value: summary.date },
+    {
+      key: "change1mBp",
+      label: "1M change",
+      value: summary.change1mBp,
+      formatted: summary.change1mBp == null ? "--" : formatSpreadChange(summary.change1mBp),
+    },
+    ...(summary.range ? [{
+      key: "range",
+      label: "Range",
+      value: summary.range,
+      formatted: `${formatSpreadRange(summary.range)} since ${summary.range.since}`,
+    }] : []),
+  ];
+}
+
+interface CdsReportInputs {
+  activity: CdsActivity;
+  /** The issuer's 5Y line, or the error that kept it out. */
+  history?: CdsSpreadHistory | Error | null;
+  /** Each listed issuer's 5Y level, or the error that kept them out. */
+  levels?: CdsSpreadLevels | Error | null;
+}
+
+function projectCdsHeadless({ activity, history, levels }: CdsReportInputs): HeadlessBundleResult {
+  const errors: string[] = [];
+  const notes: string[] = [];
+  const empty = noTradesMessage({ query: activity.query, issuer: activity.issuer, days: activity.days });
+  const metadata = { issuer: activity.issuer, days: activity.days };
+  if (activity.query) {
+    const line = history instanceof Error || !history ? null : history;
+    if (history instanceof Error) errors.push("5Y spread history unavailable.");
+    const entries = line ? spreadEntries(line) : [];
+    // The name the tape was queried for heads the figures, as in the pane, so a ticker says what it became.
+    const name = displayIssuerName(activity.issuer ?? line?.issuer ?? activity.query);
+    if (line && entries.length === 0) notes.push(`No 5Y spread level for ${name} in the last two years.`);
+    const sections: HeadlessBundleSection[] = [
+      ...(entries.length ? [{ title: name, entries }] : []),
+      {
+        title: "Trades",
+        columns: TRADE_COLUMNS,
+        rows: sortTrades(activity.trades, DEFAULT_TRADE_SORT).map((trade) => ({ ...trade })),
+        empty,
+      },
+    ];
     return {
-      columns: TRADE_COLUMNS,
-      rows: sortTrades(activity.trades, DEFAULT_TRADE_SORT).map((trade) => ({ ...trade })),
-      metadata: { source: activity.source, asOf: activity.asOf, issuer: activity.issuer },
+      sections,
+      metadata,
+      freshness: cdsFreshness(lastTradeOf(activity.trades, line?.points)),
+      ...(errors.length ? { errors } : {}),
+      ...(notes.length ? { notes } : {}),
     };
   }
+  if (levels instanceof Error) errors.push("5Y spreads unavailable.");
+  const issuers = withSpreadLevels(summarizeIssuers(activity.trades), levels instanceof Error ? null : levels ?? null);
   return {
-    columns: ISSUER_COLUMNS,
-    rows: sortIssuers(summarizeIssuers(activity.trades), DEFAULT_ISSUER_SORT).map((issuerRow) => ({ ...issuerRow })),
-    metadata: { source: activity.source, asOf: activity.asOf, issuer: null },
+    sections: [{
+      title: "Issuers",
+      columns: ISSUER_COLUMNS,
+      rows: sortIssuers(issuers, DEFAULT_ISSUER_SORT).map((issuerRow) => ({ ...issuerRow })),
+      empty,
+    }],
+    metadata,
+    freshness: cdsFreshness(lastTradeOf(activity.trades)),
+    ...(errors.length ? { errors } : {}),
   };
 }
 
+function settled<T>(pending: Promise<T>): Promise<T | Error> {
+  return pending.catch((error: unknown) => (error instanceof Error ? error : new Error(String(error))));
+}
+
 export interface CdsHeadlessDependencies {
   load(
     args: HeadlessPaneLoadArgs,
@@ -76,38 +161,53 @@ export interface CdsHeadlessDependencies {
     fetchCds: CdsFetch,
     searchInstruments: InstrumentSearch,
   ): Promise<CdsActivity>;
+  loadHistory?(issuer: string, fetchHistory: CdsHistoryFetch): Promise<CdsSpreadHistory>;
+  loadLevels?: typeof loadCdsSpreadLevels;
 }
 
 const defaultDependencies: CdsHeadlessDependencies = {
   load: (_args, issuer, fetchCds, searchInstruments) => (
     loadCdsActivity(issuer, fetchCds, searchInstruments)
   ),
+  loadHistory: (issuer, fetchHistory) => loadCdsSpreadHistory(issuer, fetchHistory),
+  loadLevels: loadCdsSpreadLevels,
 };
 
 export function createCdsHeadless(
   dependencies: CdsHeadlessDependencies = defaultDependencies,
-): HeadlessPaneDefinition<"rows"> {
+): HeadlessPaneDefinition<"bundle"> {
+  const loadHistory = dependencies.loadHistory ?? defaultDependencies.loadHistory!;
+  const loadLevels = dependencies.loadLevels ?? defaultDependencies.loadLevels!;
   return {
-    shape: "rows",
-    // Public dissemination of swap trades, held back by rule for some trades.
-    freshness: { source: "DTCC", status: "delayed" },
+    shape: "bundle",
+    description: `Single-name CDS from DTCC public dissemination. With no argument: the issuers traded in the last ${CDS_TRADE_DAYS} days, most active first, with trade count, last trade and 5Y spread. With a ticker or issuer: its 5Y spread (level, date, 1M change, range) and its trades.`,
+    freshness: cdsFreshness(null),
     argument: {
       kind: "free-text",
       placeholder: "ticker or issuer",
-      description: "Optional ticker or issuer. Omit for the most-active issuer view.",
+      description: "Optional ticker or issuer. Omit to list the most-active issuers with their 5Y spread.",
       optional: true,
     },
     options: [],
     describe: (args) => typeof args.argument === "string" ? `CDS | ${args.argument}` : "Single-Name CDS",
     async load(args, ctx) {
       const issuer = typeof args.argument === "string" ? args.argument : null;
+      const fetchHistory: CdsHistoryFetch = (params) => ctx.apiClient.getCloudCdsHistory(params);
+      const fetchLevels: CdsLevelsFetch = () => ctx.apiClient.getCloudCdsLevels();
+      // The list's levels are one request for every issuer, read beside its trades.
+      const levels = issuer?.trim() ? null : settled(loadLevels(fetchLevels));
       const activity = await dependencies.load(
         args,
         issuer,
         (params) => ctx.apiClient.getCloudCds(params),
         (query, limit) => ctx.apiClient.searchInstruments(query, limit),
       );
-      return projectCdsHeadless(activity, issuer);
+      if (activity.query) {
+        // The line follows the name the tape was queried for, as the pane's does.
+        const history = activity.issuer ? await settled(loadHistory(activity.issuer, fetchHistory)) : null;
+        return projectCdsHeadless({ activity, history });
+      }
+      return projectCdsHeadless({ activity, levels: await levels });
     },
   };
 }

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

@@ -1,5 +1,6 @@
 import type { PaneTemplateCreateOptions } from "../../../types/plugin";
 import type { PluginModule } from "../plugin-module";
+import { SINGLE_NAME_CDS_SERIES } from "./series";
 import { CDS_PANE_ID } from "./model";
 import { CdsPane } from "./pane";
 import { cdsHeadless } from "./headless";
@@ -12,6 +13,7 @@ function explicitSymbol(options?: PaneTemplateCreateOptions): string | null {
 }
 
 export const cdsModule: PluginModule = {
+  series: SINGLE_NAME_CDS_SERIES,
   panes: [{
     id: CDS_PANE_ID,
     name: "Single-Name CDS",
@@ -27,7 +29,7 @@ export const cdsModule: PluginModule = {
     id: "cds-pane",
     paneId: CDS_PANE_ID,
     label: "Single-Name CDS",
-    description: "Single-name corporate CDS trades and 5Y spread history from DTCC public dissemination.",
+    description: "Single-name corporate CDS from DTCC public dissemination: with no argument, the issuers traded in the last 5 days with their 5Y spread; with a ticker or issuer, its 5Y spread history and trades.",
     keywords: ["cds", "credit", "default", "swap", "spread", "single name", "issuer", "dtcc", "protection"],
     shortcut: { prefix: "CDS", argPlaceholder: "ticker", argKind: "ticker", argOptional: true },
     headless: cdsHeadless,