gloomberb 0.16.4 → 0.16.6

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

@@ -15,17 +15,18 @@ import type { ResolvedSeries } from "../../../time-series/types";
 import type { PaneProps } from "../../../types/plugin";
 import { Box } from "../../../ui";
 import { loadSeasonalityHistory } from "./client";
-import { MONTH_LABELS, OVERLAY_YEAR, projectSeasonality, type SeasonalityModel } from "./model";
+import { type DailyReturnStat, MONTH_LABELS, OVERLAY_YEAR, projectSeasonality, projectWeekdays, type SeasonalityModel,
+  TURN_OF_MONTH_LABELS, type WeekdayModel } from "./model";
 
-const TABS = [{ value: "returns", label: "Returns" }, { value: "overlay", label: "Overlay" }];
+const TABS = [{ value: "returns", label: "Returns" }, { value: "overlay", label: "Overlay" }, { value: "weekdays", label: "Weekdays" }];
 export const LOOKBACK_OPTIONS = [{ value: "5", label: "5Y" }, { value: "10", label: "10Y" }, { value: "20", label: "20Y" }];
-/** The move that tints a cell at full strength: a month of ±10%, a year of ±30%. */
-const MONTH_SCALE = 0.1, YEAR_SCALE = 0.3;
-function pct(value: number | null | undefined): string {
+/** The move that tints a cell at full strength: a month of ±10%, a year of ±30%, an average session of ±0.5%. */
+const MONTH_SCALE = 0.1, YEAR_SCALE = 0.3, SESSION_SCALE = 0.005;
+function pct(value: number | null | undefined, digits = 1): string {
   if (value == null) return "--";
-  const fixed = (value * 100).toFixed(1);
+  const fixed = (value * 100).toFixed(digits);
   // A return that rounds to zero reads 0.0%, never -0.0%.
-  return /[1-9]/.test(fixed) ? `${value > 0 ? "+" : ""}${fixed}%` : "0.0%";
+  return /[1-9]/.test(fixed) ? `${value > 0 ? "+" : ""}${fixed}%` : `${(0).toFixed(digits)}%`;
 }
 
 interface Row { id: string; label: string; cells: (number | null)[]; total: number | null; kind: "stat" | "hit" | "year"; partial?: boolean }
@@ -46,14 +47,16 @@ function tableRows(model: SeasonalityModel): Row[] {
   ];
 }
 
+function hitCell(value: number | null, quiet = false): DataTableCell {
+  const heat = resolveHeatCellColors(value == null ? null : (value - 0.5) * 2, { quiet });
+  return { text: value == null ? "--" : `${Math.round(value * 100)}%`, value: value == null ? null : value * 100,
+    backgroundColor: heat.background, color: heat.foreground };
+}
+
 function renderCell(row: Row, column: DataTableColumn, runningMonth: number | null): DataTableCell {
   if (column.id === "label") return { text: row.label };
   const value = column.id === "total" ? row.total : row.cells[Number(column.id.slice(1))] ?? null;
-  if (row.kind === "hit") {
-    const heat = resolveHeatCellColors(value == null ? null : (value - 0.5) * 2);
-    return { text: value == null ? "--" : `${Math.round(value * 100)}%`, value: value == null ? null : value * 100,
-      backgroundColor: heat.background, color: heat.foreground };
-  }
+  if (row.kind === "hit") return hitCell(value);
   const scale = column.id === "total" ? YEAR_SCALE : MONTH_SCALE;
   // The month still running is a return to date: shown, but not tinted as a finished month.
   const quiet = value == null || (row.partial && column.id === `m${runningMonth}`);
@@ -61,6 +64,40 @@ function renderCell(row: Row, column: DataTableColumn, runningMonth: number | nu
   return { text: pct(value), value: value == null ? null : value * 100, backgroundColor: heat.background, color: heat.foreground };
 }
 
+type WeekdayRow = { kind: "section"; id: string; label: string } | { kind: "stat"; id: string; label: string; stat: DailyReturnStat };
+
+const WEEKDAY_COLUMNS: DataTableColumn[] = [
+  { id: "label", label: "Day", width: 10, align: "left" },
+  { id: "mean", label: "Avg", width: 9, align: "right" },
+  { id: "median", label: "Median", width: 9, align: "right" },
+  { id: "hitRate", label: "Up %", width: 7, align: "right" },
+  { id: "count", label: "Sessions", width: 9, align: "right" },
+];
+
+function weekdayRows(model: WeekdayModel): WeekdayRow[] {
+  const stat = (label: string, value: DailyReturnStat): WeekdayRow => ({ kind: "stat", id: label, label, stat: value });
+  return [
+    { kind: "section", id: "weekdays", label: "By weekday" },
+    ...model.weekdays.map((value) => stat(value.day, value)),
+    { kind: "section", id: "turn", label: "Turn of month" },
+    ...model.turnOfMonth.map((value, index) => stat(TURN_OF_MONTH_LABELS[index]!, value)),
+  ];
+}
+
+/** A row with fewer sessions (an exchange's rare Saturday session) is shown but not tinted. */
+const MIN_TINTED_SESSIONS = 20;
+
+function renderWeekdayCell(row: WeekdayRow, column: DataTableColumn): DataTableCell {
+  if (row.kind === "section") return { text: "" };
+  if (column.id === "label") return { text: row.label };
+  if (column.id === "count") return { text: String(row.stat.count), value: row.stat.count };
+  const quiet = row.stat.count < MIN_TINTED_SESSIONS;
+  if (column.id === "hitRate") return hitCell(row.stat.hitRate, quiet);
+  const value = column.id === "mean" ? row.stat.mean : row.stat.median;
+  const heat = resolveHeatCellColors(value == null ? null : value / SESSION_SCALE, { quiet });
+  return { text: pct(value, 2), value: value == null ? null : value * 100, backgroundColor: heat.background, color: heat.foreground };
+}
+
 function overlaySeries(model: SeasonalityModel, colors: ReturnType<typeof useThemeColors>): ResolvedSeries[] {
   const toSeries = (id: string, label: string, color: string, points: { date: Date; value: number }[]): ResolvedSeries => ({
     ...staticSeries(points.map((point) => ({ date: point.date, observedAt: point.date, value: point.value * 100 })),
@@ -77,6 +114,29 @@ function overlaySeries(model: SeasonalityModel, colors: ReturnType<typeof useThe
   ];
 }
 
+/** Green above zero, red below; a figure that rounds to zero is neither. */
+const tone = (value: number | null, digits = 1) => value == null || !/[1-9]/.test((value * 100).toFixed(digits)) ? undefined
+  : value > 0 ? "positive" as const : "negative" as const;
+
+function weekdayStats(model: WeekdayModel): StatItem[] {
+  const figure = (id: string, label: string, stat: DailyReturnStat): StatItem => ({ id, label, value: pct(stat.mean, 2), tone: tone(stat.mean, 2),
+    detail: stat.count ? `${Math.round(stat.hitRate! * 100)}% up` : undefined });
+  return [figure("turn", "Turn of month", model.turnWindow), figure("other", "Other days", model.otherDays)];
+}
+
+function monthStats(model: SeasonalityModel): StatItem[] {
+  if (!model.asOf || !model.years.length) return [];
+  const month = model.asOf.getUTCMonth();
+  const stat = model.months[month]!;
+  const current = model.years[0]!;
+  return [
+    { id: "month-avg", label: `${MONTH_LABELS[month]} avg`, value: pct(stat.mean), tone: tone(stat.mean) },
+    { id: "month-hit", label: `${MONTH_LABELS[month]} up`, value: stat.count ? `${Math.round(stat.hitRate! * 100)}%` : "--",
+      detail: stat.count ? `${Math.round(stat.hitRate! * stat.count)} of ${stat.count} yrs` : undefined },
+    ...(current.partial ? [{ id: "ytd", label: `${current.year} YTD`, value: pct(current.total), tone: tone(current.total) }] : []),
+  ];
+}
+
 export function SeasonalityPane({ width, height, focused }: PaneProps) {
   const colors = useThemeColors();
   const { symbol, ticker, error: identityError } = usePaneTicker();
@@ -85,57 +145,68 @@ export function SeasonalityPane({ width, height, focused }: PaneProps) {
   const [selectedRow, setSelectedRow] = usePluginPaneState<string | null>("selectedRow", null);
   const instrument = instrumentFromTicker(ticker, symbol);
   const instrumentKey = JSON.stringify(instrument);
+  const exchange = instrument?.exchange;
+  // Weekdays reads daily closes, the other tabs monthly ones; only the open tab's cadence is fetched.
+  const cadence = view === "weekdays" ? "daily" : "monthly";
   const controller = useRef<AbortController | null>(null);
   const loader = useCallback(async (force: boolean) => {
     controller.current?.abort();
     controller.current = new AbortController();
-    const snapshot = await loadSeasonalityHistory({ instrument: instrument!, forceRefresh: force, signal: controller.current.signal });
+    const snapshot = await loadSeasonalityHistory({ instrument: instrument!, cadence, forceRefresh: force, signal: controller.current.signal });
     if (!snapshot.history.length && snapshot.error) throw new Error(snapshot.error);
     return snapshot;
-  }, [instrumentKey]);
+  }, [instrumentKey, cadence]);
   const history = useAsyncResource(instrument ? loader : null);
   useEffect(() => () => controller.current?.abort(), [loader]);
   useAutoRefresh(history.updatedAt, history.load);
   usePaneRefreshKey(() => { void history.reload(); }, { focused });
 
-  const model = useMemo(() => history.data ? projectSeasonality(history.data.history, { symbol: symbol ?? "", lookbackYears: Number(lookback) || 10 }) : null,
-    [history.data, lookback, symbol]);
+  const lookbackYears = Number(lookback) || 10;
+  const model = useMemo(() => history.data && cadence === "monthly"
+    ? projectSeasonality(history.data.history, { symbol: symbol ?? "", lookbackYears }) : null, [history.data, cadence, lookbackYears, symbol]);
+  // Daily closes are served for five years, so Weekdays counts all of them and has no lookback.
+  const weekdayModel = useMemo(() => history.data && cadence === "daily"
+    ? projectWeekdays(history.data.history, { symbol: symbol ?? "", exchange, fetchedAt: history.data.fetchedAt }) : null,
+  [history.data, cadence, symbol, exchange]);
   const rows = useMemo(() => model ? tableRows(model) : [], [model]);
+  const dailyRows = useMemo(() => weekdayModel ? weekdayRows(weekdayModel) : [], [weekdayModel]);
   const series = useMemo(() => model ? overlaySeries(model, colors) : [], [model, colors]);
   const runningMonth = model?.years[0]?.partial && model.asOf ? model.asOf.getUTCMonth() : null;
 
   usePaneNoticeFooter({ registrationId: "seasonality-notices", focused,
     notices: [...new Set([identityError, history.error, history.data?.error].filter((value): value is string => !!value))] });
+  const closes = model?.asOf ? `monthly closes to ${model.asOf.toISOString().slice(0, 7)}`
+    : weekdayModel?.start ? `daily closes ${weekdayModel.start} to ${weekdayModel.asOf}` : null;
   usePaneFooter("seasonality", () => ({ info: [
     ...(history.loading ? [{ id: "loading", parts: [{ text: "loading history", tone: "muted" as const }] }] : []),
     ...(history.data?.stale ? [{ id: "stale", parts: [{ text: "stale history", tone: "warning" as const }] }] : []),
-    ...(model?.asOf ? [{ id: "date", parts: [{ text: `monthly closes to ${model.asOf.toISOString().slice(0, 7)}`, tone: "muted" as const }] }] : []),
-  ] }), [history.loading, history.data?.stale, model?.asOf]);
-
-  const stats = useMemo((): StatItem[] => {
-    if (!model?.asOf || !model.years.length) return [];
-    const month = model.asOf.getUTCMonth();
-    const stat = model.months[month]!;
-    const current = model.years[0]!;
-    const tone = (value: number | null) => value == null ? undefined : value >= 0 ? "positive" as const : "negative" as const;
-    return [
-      { id: "month-avg", label: `${MONTH_LABELS[month]} avg`, value: pct(stat.mean), tone: tone(stat.mean) },
-      { id: "month-hit", label: `${MONTH_LABELS[month]} up`, value: stat.count ? `${Math.round(stat.hitRate! * 100)}%` : "--",
-        detail: stat.count ? `${Math.round(stat.hitRate! * stat.count)} of ${stat.count} yrs` : undefined },
-      ...(current.partial ? [{ id: "ytd", label: `${current.year} YTD`, value: pct(current.total), tone: tone(current.total) }] : []),
-    ];
-  }, [model]);
+    ...(closes ? [{ id: "date", parts: [{ text: closes, tone: "muted" as const }] }] : []),
+  ] }), [history.loading, history.data?.stale, closes]);
+
+  const stats = useMemo((): StatItem[] => weekdayModel?.start ? weekdayStats(weekdayModel) : model ? monthStats(model) : [],
+    [model, weekdayModel]);
 
   const { strip, rows: tabRows } = usePaneTabs({ tabs: TABS, activeValue: view, onSelect: setView, focused, dense: true });
-  const contentHeight = Math.max(4, height - 1 - tabRows - statGridRows(stats, width));
+  const queryRows = cadence === "monthly" ? 1 : 0;
+  const contentHeight = Math.max(4, height - queryRows - tabRows - statGridRows(stats, width));
   const palette = resolveChartPalette(colors);
 
   return <Box width={width} height={height} flexDirection="column" overflow="hidden">
     {strip}
-    <QueryBar width={width} filters={[{ id: "lookback", label: "Lookback", value: String(lookback), options: LOOKBACK_OPTIONS, onChange: setLookback }]} />
-    {!symbol ? <EmptyState title="Select a ticker." /> : <PaneStatusBody subject="seasonality" loading={history.loading && !model}
-      error={!model ? history.error ?? identityError ?? null : null} empty={!!model && !model.years.length}>
-      {model ? <>
+    {queryRows ? <QueryBar width={width} filters={[{ id: "lookback", label: "Lookback", value: String(lookback), options: LOOKBACK_OPTIONS, onChange: setLookback }]} /> : null}
+    {!symbol ? <EmptyState title="Select a ticker." /> : <PaneStatusBody subject="seasonality" loading={history.loading && !model && !weekdayModel}
+      error={!model && !weekdayModel ? history.error ?? identityError ?? null : null}
+      empty={model ? !model.years.length : !!weekdayModel && !weekdayModel.start}>
+      {weekdayModel ? <>
+        <StatGrid items={stats} width={width} />
+        <DataTableView<WeekdayRow> focused={focused} columns={WEEKDAY_COLUMNS} items={dailyRows} rootWidth={width} rootHeight={contentHeight}
+          getItemKey={(row) => row.id} emptyStateTitle="No daily returns." sortColumnId={null} sortDirection="desc"
+          isNavigable={(row) => row.kind === "stat"} renderSectionHeader={(row) => row.kind === "section" ? { text: row.label } : null}
+          selection={{ kind: "id", selectedId: selectedRow, getId: (row) => row.id, onChange: (id) => setSelectedRow(id) }}
+          getExportMetadata={() => [["symbol", weekdayModel.symbol], ["from", weekdayModel.start], ["as of", weekdayModel.asOf],
+            ["units", "percent, local-price session close to close"]]}
+          renderCell={renderWeekdayCell} />
+      </> : model ? <>
         <StatGrid items={stats} width={width} />
         {view === "overlay"
           ? <CompositeChart series={series} panels={[{ id: "main" }]} width={width} height={contentHeight} focused={focused}

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

@@ -42,11 +42,31 @@ export interface SecHeadlessOptions {
   forms?: readonly string[];
   title?: string;
   argumentDescription?: string;
+  /**
+   * What the report says when none of the issuer's filings is one of `forms`,
+   * in place of "No data.": `searched` filings were read, all of them when `complete`.
+   */
+  empty?(symbol: string, searched: { count: number; complete: boolean }): string;
+}
+
+const FUND_FACTS_NOTE = "Fund facts (fee, NAV, premium) are not available yet";
+
+/**
+ * ETF's empty report: a fund that files none of the fund forms, such as a
+ * grantor trust (IBIT, GLD) filing 10-Qs, says so and where its filings are.
+ */
+export function fundFilingsEmpty(symbol: string, searched: { count: number; complete: boolean }): string {
+  if (searched.count === 0) return `No SEC filings found for ${symbol}. ${FUND_FACTS_NOTE}.`;
+  const forms = "prospectus, shareholder reports, N-CEN, N-PORT";
+  const none = searched.complete
+    ? `${symbol} files none of the fund forms ETF lists (${forms}).`
+    : `None of ${symbol}'s latest ${searched.count} SEC filings is a fund form ETF lists (${forms}).`;
+  return `${none} ${FUND_FACTS_NOTE}; try fn SEC ${symbol}.`;
 }
 
 export function createSecHeadless(
   dependencies: SecHeadlessDependencies = defaultDependencies,
-  { forms, title = "SEC Filings", argumentDescription = "US equity ticker." }: SecHeadlessOptions = {},
+  { forms, title = "SEC Filings", argumentDescription = "US equity ticker.", empty }: SecHeadlessOptions = {},
 ): HeadlessPaneDefinition<"rows"> {
   return {
     shape: "rows",
@@ -79,10 +99,12 @@ export function createSecHeadless(
       }
       const issuerFilings = await dependencies.loadFilings(symbol, SEC_FILING_FETCH_LIMIT, args, ctx);
       const filings = filterFilingsByForms(issuerFilings, forms).slice(0, limit);
+      // A full page of issuer filings can hide older matches past it.
+      const complete = issuerFilings.length < SEC_FILING_FETCH_LIMIT;
       return {
         rows: buildSecFilingRows(filings),
-        // A full page of issuer filings can hide older matches past it.
-        complete: issuerFilings.length < SEC_FILING_FETCH_LIMIT,
+        ...(empty && filings.length === 0 ? { empty: empty(symbol, { count: issuerFilings.length, complete }) } : {}),
+        complete,
         metadata: {
           acceptanceNote: SEC_ACCEPTANCE_NOTE,
           symbol,

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

@@ -35,7 +35,7 @@ import { usePaneStatusLinkFooter } from "../../../components/layout/pane/status-
 import { isCloudSessionRequired, useResearchCloudSession } from "../shared/research-cloud-session";
 import { SignInWall } from "../cloud/auth-actions";
 import { ETF_FILING_FORMS, ETF_FORMS_SETTING, filterFilingsByForms, parseFormsSetting, SEC_FILING_FETCH_LIMIT } from "./forms";
-import { createSecHeadless, secHeadless } from "./headless";
+import { createSecHeadless, fundFilingsEmpty, secHeadless } from "./headless";
 import {
   getFilingDisplayTitle,
   getFilingColumnText,
@@ -469,6 +469,7 @@ export const secModule: PluginModule = {
         forms: ETF_FILING_FORMS,
         title: "Fund Filings",
         argumentDescription: "US-listed fund ticker.",
+        empty: fundFilingsEmpty,
       }),
     },
   ],

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

@@ -0,0 +1,93 @@
+/**
+ * Every chart a built-in pane draws, and whether its series is in the data
+ * catalog. `series-inventory.test.ts` fails when a module starts drawing a
+ * chart without an entry here, when an entry names a series nobody
+ * registers, or when a built-in registers a series this list does not name,
+ * so the audit cannot drift from the code.
+ *
+ * `series` lists catalog ids, with a trailing `*` for a prefix. A chart that
+ * is not in the catalog says why:
+ * - `not-a-time-series`: plotted against something other than dates (a
+ *   curve by maturity, a surface, a treemap, strikes, a distribution).
+ * - `derived`: a chart composer study draws it from catalog series
+ *   (correlation, realized volatility, a spread between two tickers).
+ * - `per-item`: one deal, trial, filing or model run, with no stable id to list.
+ * - `account`: built from the user's own portfolio or inputs.
+ * - `not-yet`: a dated series that could be registered and is not yet.
+ */
+type SeriesInventoryStatus =
+  /** `runtime`: registered while the app runs (files, accounts), so none exist in a test. */
+  | { series: readonly string[]; runtime?: true }
+  | { notInCatalog: "not-a-time-series" | "derived" | "per-item" | "account" | "not-yet"; reason: string };
+
+export type SeriesInventoryEntry = SeriesInventoryStatus & {
+  /** The module's folder under `src/plugins/builtin`. */
+  module: string;
+  /** What the pane draws. */
+  chart: string;
+};
+
+export const SERIES_INVENTORY: readonly SeriesInventoryEntry[] = [
+  { module: "chart-composer", chart: "Any ticker field: price, volume, fundamentals, valuation multiples", series: ["field:*", "option:*"] },
+  { module: "chart-composer", chart: "CSV files in the profile's series folder", series: ["user:*"], runtime: true },
+  { module: "ticker-detail", chart: "Price history and the overview's sparklines", series: ["field:market.*"] },
+  { module: "fear-greed", chart: "Fear & Greed index and its seven indicator charts, with their moving averages", series: ["fear-greed:*"] },
+  { module: "volatility", chart: "VIX curve history, the 3M/30D ratio and the cross-asset volatility board", series: ["volatility:*", "fred:VIXCLS", "fred:VXVCLS"] },
+  { module: "iv-history", chart: "A ticker's implied volatility by tenor", series: ["implied-vol:*"] },
+  { module: "realized-vol", chart: "Realized volatility cone and rolling windows", notInCatalog: "derived", reason: "The composer's realized volatility study draws it from any price series." },
+  { module: "vol-surface", chart: "Implied volatility surface by strike and expiry", notInCatalog: "not-a-time-series", reason: "A surface over strike and tenor." },
+  { module: "options-positioning", chart: "Open interest and gamma by strike and expiry", notInCatalog: "not-a-time-series", reason: "Plotted by strike and expiry, not by date." },
+  { module: "options-scenario", chart: "Option payoff by underlying price", notInCatalog: "not-a-time-series", reason: "A payoff curve over prices." },
+  { module: "kelly-sizer", chart: "Position size against win rate", notInCatalog: "account", reason: "Drawn from the inputs typed into the sizer." },
+  { module: "yield-curve", chart: "Treasury curve and each maturity's history", series: ["ust:*", "fred:T10Y2Y", "fred:T10Y3M", "fred:DFII*"] },
+  { module: "yield-curve", chart: "Government curves for Germany, the UK, Japan, Canada and euro AAA", series: ["bond-yield:*"] },
+  { module: "rate-path", chart: "Implied policy path by meeting", notInCatalog: "not-a-time-series", reason: "A path over future meetings; the rates it starts from are FRED series in the catalog." },
+  { module: "money-markets", chart: "Money market rates, bill yields, liquidity and net liquidity", series: ["money-markets:*", "fred:SOFR", "fred:EFFR", "fred:IORB", "fred:OBFR", "fred:DTB*", "fred:RRPONTSYD", "fred:WDTGAL", "fred:WRESBAL", "fred:WALCL"] },
+  { module: "central-bank-rates", chart: "Policy rate history for each central bank", series: ["policy-rate:*"] },
+  { module: "econ", chart: "Release history of each economic calendar event", series: ["fred:*"] },
+  { module: "econ-statistics", chart: "Inflation, labor and growth statistics with their ranges", series: ["fred:CPIAUCNS", "fred:CPILFENS", "fred:PCEPI", "fred:PCEPILFE", "fred:PPIFID", "fred:UNRATE", "fred:PAYEMS", "fred:ICSA", "fred:JTSJOL", "fred:GDPC1", "fred:INDPRO"] },
+  { module: "cpi", chart: "CPI components, month on month and year on year", series: ["fred:CPI*", "fred:CUSR*"] },
+  { module: "market-valuation", chart: "Whole-market valuation ratios against their history", series: ["market-valuation:*"] },
+  { module: "credit-conditions", chart: "Corporate bond spreads by rating", series: ["fred:BAML*"] },
+  { module: "credit-boards", chart: "Index CDS (CDX, iTraxx) and sovereign 5Y CDS", series: ["cdx:*", "sovereign-cds:*"] },
+  { module: "cds", chart: "A company's 5Y CDS spread", series: ["cds:*"] },
+  { module: "credit-documents", chart: "Principal due by year", notInCatalog: "not-a-time-series", reason: "A maturity schedule, not a history." },
+  { module: "debt-maturities", chart: "A company's principal and the share due soon, across annual filings", series: ["debt-maturities:*"] },
+  { module: "debt-maturities", chart: "A company's maturity wall", notInCatalog: "not-a-time-series", reason: "A schedule by maturity year from one filing; its total and near-term shares across filings are in the catalog." },
+  { module: "doe", chart: "Weekly oil and gas inventories against their five-year range", series: ["doe:*"] },
+  { module: "cot", chart: "Net positioning by trader class, over the front-month price", series: ["cot:*"] },
+  { module: "futures", chart: "Front-month futures board, charted from the board", series: ["fut:*"] },
+  { module: "futures-curve", chart: "Futures curve by contract month", notInCatalog: "not-a-time-series", reason: "Plotted by delivery month; each front month is in the catalog as FUT:code." },
+  { module: "crypto-board", chart: "Price sparklines for the large coins", series: ["crypto:*"] },
+  { module: "perps", chart: "Perpetual funding, open interest, premium and long/short account share", series: ["perps:*"] },
+  { module: "perps", chart: "Perpetual mark price", notInCatalog: "not-yet", reason: "The pair's price is in the catalog; the perpetual's own mark price could be a crypto series." },
+  { module: "short-interest", chart: "A ticker's short interest and days to cover", series: ["short-interest:*"] },
+  { module: "short-volume", chart: "A ticker's daily short volume ratio", series: ["short-volume:*"] },
+  { module: "social-mentions", chart: "A ticker's daily posts", series: ["social-mentions:*"] },
+  { module: "jobs", chart: "A company's open job postings", series: ["jobs:*"] },
+  { module: "attention", chart: "Research hours on a ticker, hour by hour", series: ["attention:*"] },
+  { module: "company-attention", chart: "A company's weekly open roles and daily app attention score", series: ["hiring:*", "app-attention:*"] },
+  { module: "gpu", chart: "GPU rental list index per model", series: ["gpu:*"] },
+  { module: "gpu", chart: "GPU rental prices per provider listing", notInCatalog: "per-item", reason: "One provider listing each, listed by the server and changing without a release." },
+  { module: "power", chart: "Interconnection queue capacity and project generation", notInCatalog: "per-item", reason: "Per project and per queue filter." },
+  { module: "power", chart: "European day-ahead power price by country", series: ["day-ahead:*"] },
+  { module: "power", chart: "EU carbon allowance (EUA) auction price", series: ["carbon:*"] },
+  { module: "awards", chart: "A company's government award totals by period", series: ["awards:*"] },
+  { module: "company-kpis", chart: "A company's reported operating metrics", notInCatalog: "per-item", reason: "Each company reports its own metrics, with no shared list to register." },
+  { module: "estimate-revisions", chart: "Consensus estimate for one fiscal period over time", notInCatalog: "per-item", reason: "One fiscal period of one company." },
+  { module: "earnings", chart: "Implied and actual moves around past earnings", notInCatalog: "per-item", reason: "One bar per earnings event." },
+  { module: "dividend-yield", chart: "A ticker's trailing 12-month cash dividends", series: ["dividends:*"] },
+  { module: "pe-band", chart: "Price against P/E multiples", notInCatalog: "derived", reason: "The composer charts price and the P/E fields for any ticker." },
+  { module: "research", chart: "Analyst price targets over price", notInCatalog: "per-item", reason: "Targets are dated events on one ticker." },
+  { module: "catalysts", chart: "Clinical trial enrollment", notInCatalog: "per-item", reason: "One trial." },
+  { module: "mna", chart: "Deal spread for one merger", notInCatalog: "per-item", reason: "One deal." },
+  { module: "correlation", chart: "Rolling correlation of two tickers and the matrix", notInCatalog: "derived", reason: "The composer's correlation study draws it for any two series." },
+  { module: "relative-rotation", chart: "Relative strength and momentum against a benchmark", notInCatalog: "derived", reason: "Built from two price series; the rotation plot is not dated." },
+  { module: "seasonality", chart: "Average returns by month and weekday", notInCatalog: "not-a-time-series", reason: "Plotted by calendar month, not by date." },
+  { module: "backtest", chart: "A strategy's equity curve", notInCatalog: "account", reason: "One run of the user's own strategy settings." },
+  { module: "analytics", chart: "Portfolio value, drawdown and factor exposure", notInCatalog: "account", reason: "Built from the user's own portfolio; the factor legs are tickers in the catalog." },
+  { module: "holders", chart: "Holders treemap", notInCatalog: "not-a-time-series", reason: "A treemap of one filing date." },
+  { module: "market-heatmap", chart: "Market heat map", notInCatalog: "not-a-time-series", reason: "A treemap of today's moves." },
+  { module: "portfolio-list", chart: "Portfolio treemap", notInCatalog: "not-a-time-series", reason: "A treemap of current positions." },
+  { module: "world-venue-map", chart: "Chokepoint transits and the map's place series", series: ["geo:*"] },
+];

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

@@ -0,0 +1,15 @@
+import { ApiRequestError } from "../../../api-client/errors";
+
+/** A Gloom Cloud refusal the reader can act on: signed out, an unverified email, or no Pro plan. */
+export type CloudDeniedStatus = 401 | 402 | 403;
+
+/** The account refusal behind a failed request, or null when it failed for another reason. */
+export function cloudDeniedStatus(error: unknown): CloudDeniedStatus | null {
+  const status = error instanceof ApiRequestError ? error.status : undefined;
+  return status === 401 || status === 402 || status === 403 ? status : null;
+}
+
+/** What the refused account needs, as a report finishes "JOBS needs ...". */
+export function cloudAccountNeed(status: CloudDeniedStatus): string {
+  return status === 401 ? "sign-in" : status === 403 ? "a verified email" : "Gloom Pro";
+}

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

@@ -12,7 +12,7 @@ import { requestAccountManagementTab } from "../account-management/navigation";
 import { resolvePlanAccess, usePlanAccess, type PlanAccess } from "../../../api-client/plan-access";
 import { useViewport } from "../../../react/input";
 import { useOptionalDialog } from "../../../ui/dialog";
-import { promptCloudUpgrade } from "../cloud/upgrade-dialog";
+import { promptCloudUpgrade } from "../../../account/upgrade-dialog";
 
 const CLOUD_UPGRADE_URL = "https://gloom.sh/cloud?upgrade=pro";
 

package/src/plugins/builtin/shared/command-tab.ts

@@ -3,9 +3,17 @@ import { usePluginPaneState } from "../../../public/react";
 import { usePaneInstance } from "../../../state/app/context";
 import type { PaneTemplateDef, PaneTemplateInstanceConfig } from "../../../types/plugin";
 
+/**
+ * A command's request (a market, a record), stamped so a later command can ask again: a pane the command reuses
+ * sees the newer stamp even when it asks for the same thing.
+ */
+export function commandRequestParams(params: Record<string, string>): Record<string, string> {
+  return { ...params, tabAt: String(Date.now()) };
+}
+
 /** A command's request to show one tab, stamped so a later command can ask again. */
 export function commandTabParams(tab: string, params?: Record<string, string>): Record<string, string> {
-  return { ...(params ?? {}), tab, tabAt: String(Date.now()) };
+  return commandRequestParams({ ...(params ?? {}), tab });
 }
 
 /** The template's pane, with the command's tab written onto the instance. */
@@ -26,26 +34,36 @@ export function withCommandTab(template: PaneTemplateDef, tab: string): PaneTemp
 }
 
 /**
- * The tab a command asked this pane to show. A stored choice wins until a
- * newer command arrives. Another pane's params, such as Ticker Research
- * around a nested tab, are ignored.
+ * A value a command asked this pane to show, kept in pane state like a choice made in the pane: the stored
+ * choice wins until a newer command arrives. `read` takes the value from the command's params, null when the
+ * command names none. Another pane's params, such as Ticker Research around a nested tab, are ignored.
  */
-export function useCommandTab<T extends string>(
+export function useCommandValue<T>(
   paneId: string,
   stateKey: string,
-  tabs: readonly T[],
+  read: (params: Readonly<Record<string, string>>) => T | null,
   fallback: T,
 ): [T, (next: T) => void] {
   const instance = usePaneInstance();
   const params = instance?.paneId === paneId ? instance.params : undefined;
-  const requested = params && (tabs as readonly string[]).includes(params.tab ?? "") ? params.tab as T : null;
+  const requested = params ? read(params) : null;
   const requestAt = params?.tabAt ?? "";
-  const [tab, setTab] = usePluginPaneState<T>(stateKey, requested ?? fallback);
+  const [value, setValue] = usePluginPaneState<T>(stateKey, requested ?? fallback);
   const seen = useRef(requestAt);
   useEffect(() => {
-    if (!requested || requestAt === seen.current) return;
+    if (requested === null || requestAt === seen.current) return;
     seen.current = requestAt;
-    setTab(requested);
-  }, [requestAt, requested, setTab]);
-  return [tab, setTab];
+    setValue(requested);
+  }, [requestAt, requested, setValue]);
+  return [value, setValue];
+}
+
+/** The tab a command asked this pane to show, one of `tabs`. */
+export function useCommandTab<T extends string>(
+  paneId: string,
+  stateKey: string,
+  tabs: readonly T[],
+  fallback: T,
+): [T, (next: T) => void] {
+  return useCommandValue<T>(paneId, stateKey, (params) => (tabs as readonly string[]).includes(params.tab ?? "") ? params.tab as T : null, fallback);
 }

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

@@ -0,0 +1,55 @@
+import type { EarningsDateStatus, EarningsEpsBasis } from "../../../types/financials";
+
+/**
+ * How every earnings surface (ERN, EE, the corporate-actions events and
+ * their headless rows) reads and names a reported quarter's EPS basis and a
+ * report date's status. Gloom Cloud resolves one figure per quarter; this
+ * keeps the panes from naming it differently.
+ */
+
+const BASES: ReadonlySet<string> = new Set<EarningsEpsBasis>(["gaap", "adjusted"]);
+const STATUSES: ReadonlySet<string> = new Set<EarningsDateStatus>(["reported", "confirmed", "projected"]);
+
+/** A server value read defensively: anything unrecognised is an unknown basis. */
+export function earningsEpsBasis(value: unknown): EarningsEpsBasis | null {
+  return typeof value === "string" && BASES.has(value) ? value as EarningsEpsBasis : null;
+}
+
+export function earningsDateStatus(value: unknown): EarningsDateStatus | null {
+  return typeof value === "string" && STATUSES.has(value) ? value as EarningsDateStatus : null;
+}
+
+/** The per-ticker calendar flags an estimated date; it says nothing about a date it does not flag. */
+export function dateStatusFromEstimateFlag(isDateEstimate: boolean | null | undefined): EarningsDateStatus | null {
+  return isDateEstimate === true ? "projected" : isDateEstimate === false ? "confirmed" : null;
+}
+
+export type EpsBasisName = "GAAP" | "adjusted" | "unknown";
+
+/** What the basis names mean, in every report's metadata. */
+export const EPS_BASIS_NOTE = "One reported EPS per quarter. GAAP: the quarter's diluted statement EPS. adjusted: the consensus-basis figure the estimate is measured against, which leaves out items the statements include. unknown: no statement on a comparable share basis to tell.";
+
+/** The basis as rows, exports and tools name it. */
+export function epsBasisName(basis: EarningsEpsBasis | null): EpsBasisName {
+  return basis === "gaap" ? "GAAP" : basis === "adjusted" ? "adjusted" : "unknown";
+}
+
+/** The basis in a table cell or a detail line. */
+export function epsBasisShort(basis: EarningsEpsBasis | null): string {
+  return basis === "gaap" ? "GAAP" : basis === "adjusted" ? "adj" : "?";
+}
+
+/** Actual over estimate minus one, against the estimate's size so a negative estimate reads the right way. */
+export function epsSurprise(actual: number | null | undefined, estimate: number | null | undefined): number | null {
+  if (actual == null || estimate == null || estimate === 0) return null;
+  return (actual - estimate) / Math.abs(estimate);
+}
+
+/** A fiscal quarter end month (YYYY-MM) holds a period end in that month, or a 52/53-week end a few days either side. */
+export function inFiscalMonth(periodEnd: string | null | undefined, fiscalPeriod: string | null | undefined): boolean {
+  const month = /^(\d{4})-(\d{2})$/.exec(fiscalPeriod ?? "");
+  const end = Date.parse(`${periodEnd ?? ""}T00:00:00Z`);
+  if (!month || !Number.isFinite(end)) return false;
+  const monthEnd = Date.UTC(Number(month[1]), Number(month[2]), 0);
+  return end >= monthEnd - 35 * 86_400_000 && end <= monthEnd + 10 * 86_400_000;
+}

package/src/plugins/builtin/shared/fred-points.ts

@@ -0,0 +1,20 @@
+import { apiClient } from "../../../api-client";
+import { loadCachedFredSeries } from "../../../sources/gloomberb-cloud/fred-series";
+
+/** A FRED series from `start` on, oldest first, through the shared FRED cache. */
+export async function loadFredPoints(seriesId: string, start?: Date): Promise<{
+  points: Array<{ date: string; value: number | null }>;
+  stale: boolean;
+  refreshError?: string;
+}> {
+  const startDate = start ? start.toISOString().slice(0, 10) : "1900-01-01";
+  const result = await loadCachedFredSeries(
+    { seriesId, startDate, sortOrder: "asc" },
+    () => apiClient.getCloudFredSeries(seriesId, { startDate, sortOrder: "asc" }),
+  );
+  return {
+    points: (result.data.observations ?? []).map((row) => ({ date: row.date, value: row.value })),
+    stale: result.stale,
+    ...(result.refreshError ? { refreshError: result.refreshError } : {}),
+  };
+}

package/src/plugins/builtin/shared/free-preview.ts

@@ -0,0 +1,47 @@
+/**
+ * What the free preview of a Pro function says in place of a bare "requires
+ * Gloom Pro": what the free rows are, what Pro adds and when its history
+ * starts. Each clause comes from the response; one the response cannot back
+ * is left out rather than guessed. The line names Gloom Pro, so reports print
+ * it as the lock it is (under "Pro") and a bot-safe check still calls it one.
+ */
+export interface FreePreviewNote {
+  /** What the free rows are, after "Free shows": `3 of 6 KPI values`, `the 3 latest awards`. */
+  shows: string;
+  /** What Pro adds, after "Gloom Pro adds": `the other 3`. Left out, the line says "the rest". */
+  adds?: string | null;
+  /** The first day Pro's history covers, as YYYY-MM-DD or an ISO instant. */
+  historyFrom?: string | null;
+}
+
+const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
+
+/** "1 Oct 2024", the way report lines write a day; null for anything that is not a date. */
+function day(value: string | null | undefined): string | null {
+  const match = /^(\d{4})-(\d{2})-(\d{2})/.exec(value ?? "");
+  if (!match) return null;
+  const date = new Date(Date.UTC(Number(match[1]), Number(match[2]) - 1, Number(match[3])));
+  if (date.toISOString().slice(0, 10) !== match[0]) return null;
+  return `${date.getUTCDate()} ${MONTHS[date.getUTCMonth()]} ${date.getUTCFullYear()}`;
+}
+
+/** "Free shows 3 of 6 KPI values. Gloom Pro adds the other 3, with history from 31 Dec 2024." */
+export function freePreviewNote({ shows, adds, historyFrom }: FreePreviewNote): string {
+  const since = day(historyFrom);
+  return `Free shows ${shows}. Gloom Pro adds ${adds?.trim() || "the rest"}${since ? `, with history from ${since}` : ""}.`;
+}
+
+/** "3 awards", "1 award", "no earnings calls": a count as a sentence says it. */
+export function countOf(count: number, singular: string, plural = `${singular}s`): string {
+  return count === 0 ? `no ${plural}` : `${count.toLocaleString("en-US")} ${count === 1 ? singular : plural}`;
+}
+
+/**
+ * "the preview can't filter by ticker", "... by ticker or country": the same
+ * words wherever a preview shows the same rows whatever was asked for.
+ */
+export function previewCantFilter(filters: readonly string[]): string {
+  const names = [...new Set(filters)];
+  if (!names.length) return "the preview can't filter";
+  return `the preview can't filter by ${names.length === 1 ? names[0] : `${names.slice(0, -1).join(", ")} or ${names.at(-1)}`}`;
+}