gloomberb 0.16.3 → 0.16.4

package/src/plugins/builtin/macro-day/headless.ts

@@ -1,8 +1,8 @@
 import type { HeadlessPaneDefinition } from "../../../types/plugin";
 import { resolveHeadlessInstrument } from "../shared/headless-market-data";
-import { loadMacroDayHistory } from "./client";
+import { loadMacroDayHistory, loadMacroReleases } from "./client";
 import { projectMacroDays, type MacroDayStats } from "./model";
-import { MACRO_EVENT_KINDS, MACRO_EVENT_LABELS, MACRO_RELEASE_BASIS } from "./releases";
+import { MACRO_EVENT_KINDS, MACRO_EVENT_LABELS, MACRO_RELEASE_SOURCES, staleMacroReleasesNotice } from "./releases";
 
 // A mean that rounds to zero reads 0.00%, never -0.00%.
 const percent = (value: unknown) => typeof value !== "number" ? "--" : /[1-9]/.test((value * 100).toFixed(2)) ? `${(value * 100).toFixed(2)}%` : "0.00%";
@@ -11,12 +11,12 @@ const share = (value: unknown) => typeof value === "number" ? `${Math.round(valu
 
 export const macroDayHeadless: HeadlessPaneDefinition<"bundle"> = {
   shape: "bundle", argument: { kind: "ticker", description: "Ticker" },
-  // Dated by the maintained release list as much as by the closes, so no session schedule applies.
+  // Dated by the release list (releasesThrough) as much as by the closes, so no session schedule applies.
   freshness: { status: "not-a-feed", basis: "release-day study on daily closes" },
   describe: (args) => `MDAY ${args.symbols[0] ?? ""}`,
   discovery: { screenshotReadiness: "live-dom", limitations: [
     "US listings; close-to-close on the release day.",
-    `Published CPI, jobs and FOMC days through ${MACRO_RELEASE_BASIS.coveredThrough}.`,
+    "Published CPI, jobs and FOMC days; sessions after the list's last covered day (releasesThrough) are left out.",
   ] },
   options: [
     { key: "release", type: "enum", values: [{ value: "all" }, ...MACRO_EVENT_KINDS.map((value) => ({ value }))], defaultValue: "all",
@@ -25,9 +25,11 @@ export const macroDayHeadless: HeadlessPaneDefinition<"bundle"> = {
   ],
   async load(args, ctx) {
     const instrument = await resolveHeadlessInstrument(ctx, args.symbols[0]!);
-    const history = await loadMacroDayHistory({ instrument, signal: ctx.signal }, ctx.marketData);
+    const [history, releases] = await Promise.all([loadMacroDayHistory({ instrument, signal: ctx.signal }, ctx.marketData), loadMacroReleases()]);
     ctx.signal.throwIfAborted();
-    const model = projectMacroDays(history.history, { symbol: instrument.symbol, lookbackYears: Number(args.options.lookbackYears) || 5 });
+    const model = projectMacroDays(history.history, { symbol: instrument.symbol, lookbackYears: Number(args.options.lookbackYears) || 5,
+      releases: releases.releases, coveredThrough: releases.coveredThrough });
+    const releasesNotice = staleMacroReleasesNotice(releases);
     const row = (label: string, stats: MacroDayStats) => ({ label, ...stats });
     const release = String(args.options.release ?? "all");
     const events = release === "all" ? model.events : model.events.filter((event) => event.kind === release);
@@ -42,11 +44,12 @@ export const macroDayHeadless: HeadlessPaneDefinition<"bundle"> = {
           { key: "session", header: "Session" }, { key: "move", header: "Move", format: percent }, { key: "multiple", header: "vs normal", format: multiple }],
         rows: events.map((event) => ({ ...event, event: MACRO_EVENT_LABELS[event.kind] })) },
       ],
-      complete: !history.stale && !history.error && model.events.length > 0,
+      complete: !history.stale && !history.error && !releasesNotice && model.events.length > 0,
       unavailableSymbols: model.events.length ? [] : [instrument.symbol],
       errors: history.error ? [history.error] : [],
+      ...(releasesNotice ? { notes: [releasesNotice] } : {}),
       metadata: { unit: "decimal return, close to close on the release day", start: model.start, asOf: model.asOf,
-        releasesThrough: MACRO_RELEASE_BASIS.coveredThrough, releaseSources: MACRO_RELEASE_BASIS.sources,
+        releasesThrough: releases.coveredThrough, releaseSources: Object.values(MACRO_RELEASE_SOURCES),
         stale: history.stale, fetchedAt: history.fetchedAt, methodology: "docs/research-data.md#macro-day-reaction" },
     };
   },

package/src/plugins/builtin/macro-day/index.tsx

@@ -1,5 +1,6 @@
 import type { PluginModule } from "../plugin-module";
 import { createTickerSurfacePaneTemplate } from "../shared/ticker-surface";
+import { macroReleaseCache } from "./client";
 import { macroDayHeadless } from "./headless";
 import { LOOKBACK_OPTIONS, MacroDayPane } from "./pane";
 
@@ -18,4 +19,6 @@ export const macroDayModule: PluginModule = {
     keywords: ["mday", "macro day", "cpi day", "fomc day", "jobs day", "nfp", "payrolls", "event study", "release reaction"],
     shortcut: "MDAY", publicShare: true,
   }), headless: macroDayHeadless }],
+  setup(ctx) { macroReleaseCache.attach(ctx.persistence); },
+  dispose() { macroReleaseCache.reset(); },
 };

package/src/plugins/builtin/macro-day/model.ts

@@ -1,6 +1,6 @@
 import type { PricePoint } from "../../../types/financials";
 import { zonedDateTimeParts } from "../../../utils/zoned-date-time";
-import { MACRO_EVENT_KINDS, MACRO_RELEASE_BASIS, macroReleases, type MacroEventKind, type MacroRelease } from "./releases";
+import { MACRO_EVENT_KINDS, type MacroEventKind, type MacroRelease } from "./releases";
 
 const DAY_MS = 86_400_000;
 /** Longest calendar gap between two closes that is still one session apart: Thursday to Monday over a Friday holiday. */
@@ -71,10 +71,11 @@ function stats(moves: number[], normalAbs: number | null): MacroDayStats {
 export function projectMacroDays(history: readonly PricePoint[], options: {
   symbol: string;
   lookbackYears: number;
-  releases?: readonly MacroRelease[];
-  coveredThrough?: string;
+  releases: readonly MacroRelease[];
+  /** The release list's last covered day. */
+  coveredThrough: string;
 }): MacroDayModel {
-  const coveredThrough = options.coveredThrough ?? MACRO_RELEASE_BASIS.coveredThrough;
+  const { coveredThrough } = options;
   const byDate = new Map<string, number>();
   for (const point of history) {
     const time = new Date(point.date).getTime();
@@ -90,7 +91,11 @@ export function projectMacroDays(history: readonly PricePoint[], options: {
   // Sessions after the published lists end may be unlisted release days, so they are left out of both sides.
   const end = last < coveredThrough ? last : coveredThrough;
   const startYear = Number(end.slice(0, 4)) - Math.max(1, options.lookbackYears);
-  const start = `${startYear}${end.slice(4)}`;
+  const nominalStart = `${startYear}${end.slice(4)}`;
+  // The history can begin after the nominal start (daily bars reach back five years from today, the list's end is older).
+  // The first bar has no close before it, so the window opens there: a release before it falls outside the stated start.
+  const firstSession = sessions[0]!;
+  const start = firstSession > nominalStart ? firstSession : nominalStart;
   /** Session date -> close-to-close move from the session before, when the two are one session apart. */
   const moves = new Map<string, number>();
   for (let index = 1; index < sessions.length; index++) {
@@ -101,7 +106,7 @@ export function projectMacroDays(history: readonly PricePoint[], options: {
 
   const reactionSessions = new Set<string>();
   const found: Omit<MacroDayEvent, "multiple">[] = [];
-  for (const release of options.releases ?? macroReleases()) {
+  for (const release of options.releases) {
     if (release.date <= start || release.date > end || !isWeekday(release.date)) continue;
     const at = sessions.findIndex((date) => date >= release.date);
     if (at < 1) continue;

package/src/plugins/builtin/macro-day/pane.tsx

@@ -9,9 +9,9 @@ import { useAutoRefresh } from "../../../react/auto-refresh";
 import { useThemeColors } from "../../../theme/theme-context";
 import type { PaneProps } from "../../../types/plugin";
 import { Box } from "../../../ui";
-import { loadMacroDayHistory } from "./client";
+import { loadMacroDayHistory, loadMacroReleases } from "./client";
 import { projectMacroDays, type MacroDayEvent, type MacroDayModel } from "./model";
-import { MACRO_EVENT_KINDS, MACRO_EVENT_LABELS, type MacroEventKind } from "./releases";
+import { MACRO_EVENT_KINDS, MACRO_EVENT_LABELS, staleMacroReleasesNotice, type MacroEventKind } from "./releases";
 
 export const LOOKBACK_OPTIONS = [{ value: "1", label: "1Y" }, { value: "2", label: "2Y" }, { value: "3", label: "3Y" }, { value: "5", label: "5Y" }];
 const RELEASE_OPTIONS = [{ value: "all", label: "All" }, ...MACRO_EVENT_KINDS.map((kind) => ({ value: kind, label: MACRO_EVENT_LABELS[kind] }))];
@@ -64,22 +64,26 @@ export function MacroDayPane({ width, height, focused }: PaneProps) {
   const loader = useCallback(async (force: boolean) => {
     controller.current?.abort();
     controller.current = new AbortController();
-    const snapshot = await loadMacroDayHistory({ instrument: instrument!, forceRefresh: force, signal: controller.current.signal });
+    const [snapshot, releases] = await Promise.all([
+      loadMacroDayHistory({ instrument: instrument!, forceRefresh: force, signal: controller.current.signal }),
+      loadMacroReleases({ force }),
+    ]);
     if (!snapshot.history.length && snapshot.error) throw new Error(snapshot.error);
-    return snapshot;
+    return { ...snapshot, releases };
   }, [instrumentKey]);
   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 ? projectMacroDays(history.data.history, { symbol: symbol ?? "", lookbackYears: Number(lookback) || 5 }) : null,
-    [history.data, lookback, symbol]);
+  const model = useMemo(() => history.data ? projectMacroDays(history.data.history, { symbol: symbol ?? "", lookbackYears: Number(lookback) || 5,
+    releases: history.data.releases.releases, coveredThrough: history.data.releases.coveredThrough }) : null, [history.data, lookback, symbol]);
+  const releasesNotice = history.data ? staleMacroReleasesNotice(history.data.releases) : null;
   const rows = useMemo(() => model ? model.events.filter((event) => release === "all" || event.kind === release) : [], [model, release]);
   const stats = useMemo(() => model?.events.length ? figures(model, release) : [], [model, release]);
 
   usePaneNoticeFooter({ registrationId: "macro-day-notices", focused,
-    notices: [...new Set([identityError, history.error, history.data?.error].filter((value): value is string => !!value))] });
+    notices: [...new Set([identityError, history.error, history.data?.error, releasesNotice].filter((value): value is string => !!value))] });
   usePaneFooter("macro-day", () => ({ 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 }] }] : []),
@@ -102,7 +106,7 @@ export function MacroDayPane({ width, height, focused }: PaneProps) {
       { id: "release", label: "Release", value: release, options: RELEASE_OPTIONS, onChange: setRelease, inline: true },
       { id: "lookback", label: "Lookback", value: String(lookback), options: LOOKBACK_OPTIONS, onChange: setLookback },
     ]} />
-    {!symbol ? <EmptyState title="Choose a ticker." /> : <PaneStatusBody subject="macro-day moves" loading={history.loading && !model}
+    {!symbol ? <EmptyState title="Select a ticker." /> : <PaneStatusBody subject="macro-day moves" loading={history.loading && !model}
       error={!model ? history.error ?? identityError ?? null : null} empty={!!model && !model.events.length}>
       {model ? <>
         <StatGrid items={stats} width={width} />

package/src/plugins/builtin/macro-day/release-table.ts

@@ -0,0 +1,40 @@
+// Generated by scripts/update-macro-releases.ts from the publishers' archives
+// (bun run macro-releases:update). Dates are New York calendar days.
+export const MACRO_RELEASE_TABLE: {
+  checkedAt: string;
+  coveredThrough: string;
+  days: Record<"cpi" | "jobs" | "fomc", Record<number, readonly string[]>>;
+} = {
+  checkedAt: "2026-10-10",
+  /** The last day the lists are complete for: later sessions are left out, release day or not. */
+  coveredThrough: "2026-10-09",
+  days: {
+    // BLS Consumer Price Index, 8:30 ET.
+    cpi: {
+      2021: ["01-13", "02-10", "03-10", "04-13", "05-12", "06-10", "07-13", "08-11", "09-14", "10-13", "11-10", "12-10"],
+      2022: ["01-12", "02-10", "03-10", "04-12", "05-11", "06-10", "07-13", "08-10", "09-13", "10-13", "11-10", "12-13"],
+      2023: ["01-12", "02-14", "03-14", "04-12", "05-10", "06-13", "07-12", "08-10", "09-13", "10-12", "11-14", "12-12"],
+      2024: ["01-11", "02-13", "03-12", "04-10", "05-15", "06-12", "07-11", "08-14", "09-11", "10-10", "11-13", "12-11"],
+      2025: ["01-15", "02-12", "03-12", "04-10", "05-13", "06-11", "07-15", "08-12", "09-11", "10-24", "12-18"],
+      2026: ["01-13", "02-13", "03-11", "04-10", "05-12", "06-10", "07-14", "08-12", "09-11"],
+    },
+    // BLS Employment Situation (nonfarm payrolls), 8:30 ET.
+    jobs: {
+      2021: ["01-08", "02-05", "03-05", "04-02", "05-07", "06-04", "07-02", "08-06", "09-03", "10-08", "11-05", "12-03"],
+      2022: ["01-07", "02-04", "03-04", "04-01", "05-06", "06-03", "07-08", "08-05", "09-02", "10-07", "11-04", "12-02"],
+      2023: ["01-06", "02-03", "03-10", "04-07", "05-05", "06-02", "07-07", "08-04", "09-01", "10-06", "11-03", "12-08"],
+      2024: ["01-05", "02-02", "03-08", "04-05", "05-03", "06-07", "07-05", "08-02", "09-06", "10-04", "11-01", "12-06"],
+      2025: ["01-10", "02-07", "03-07", "04-04", "05-02", "06-06", "07-03", "08-01", "09-05", "11-20", "12-16"],
+      2026: ["01-09", "02-11", "03-06", "04-03", "05-08", "06-05", "07-02", "08-07", "09-04", "10-02"],
+    },
+    // FOMC statement days (the meeting's last day), 14:00 ET. The August 2025 notation vote is not a meeting.
+    fomc: {
+      2021: ["01-27", "03-17", "04-28", "06-16", "07-28", "09-22", "11-03", "12-15"],
+      2022: ["01-26", "03-16", "05-04", "06-15", "07-27", "09-21", "11-02", "12-14"],
+      2023: ["02-01", "03-22", "05-03", "06-14", "07-26", "09-20", "11-01", "12-13"],
+      2024: ["01-31", "03-20", "05-01", "06-12", "07-31", "09-18", "11-07", "12-18"],
+      2025: ["01-29", "03-19", "05-07", "06-18", "07-30", "09-17", "10-29", "12-10"],
+      2026: ["01-28", "03-18", "04-29", "06-17", "07-29", "09-16"],
+    },
+  },
+};

package/src/plugins/builtin/macro-day/releases.ts

@@ -1,58 +1,76 @@
 // Published US release days, not a rule engine: the dates each release came
 // out, read from the publishers' own archives. A release cancelled or moved (the
-// 2025 shutdown) is as published. Dates are New York calendar days.
+// 2025 shutdown) is as published, and a scheduled date is not a release day
+// until it is out. Dates are New York calendar days.
+import { zonedDateKey } from "../../../utils/zoned-date-time";
+import { MACRO_RELEASE_TABLE } from "./release-table";
+
 export type MacroEventKind = "cpi" | "jobs" | "fomc";
 
 export const MACRO_EVENT_KINDS: readonly MacroEventKind[] = ["cpi", "jobs", "fomc"];
 
 export const MACRO_EVENT_LABELS: Record<MacroEventKind, string> = { cpi: "CPI", jobs: "Jobs", fomc: "FOMC" };
 
-const RELEASES: Record<MacroEventKind, Record<number, readonly string[]>> = {
-  // BLS Consumer Price Index, 8:30 ET.
-  cpi: {
-    2021: ["01-13", "02-10", "03-10", "04-13", "05-12", "06-10", "07-13", "08-11", "09-14", "10-13", "11-10", "12-10"],
-    2022: ["01-12", "02-10", "03-10", "04-12", "05-11", "06-10", "07-13", "08-10", "09-13", "10-13", "11-10", "12-13"],
-    2023: ["01-12", "02-14", "03-14", "04-12", "05-10", "06-13", "07-12", "08-10", "09-13", "10-12", "11-14", "12-12"],
-    2024: ["01-11", "02-13", "03-12", "04-10", "05-15", "06-12", "07-11", "08-14", "09-11", "10-10", "11-13", "12-11"],
-    2025: ["01-15", "02-12", "03-12", "04-10", "05-13", "06-11", "07-15", "08-12", "09-11", "10-24", "12-18"],
-    2026: ["01-13", "02-13", "03-11", "04-10", "05-12", "06-10", "07-14", "08-12", "09-11"],
-  },
-  // BLS Employment Situation (nonfarm payrolls), 8:30 ET.
-  jobs: {
-    2021: ["01-08", "02-05", "03-05", "04-02", "05-07", "06-04", "07-02", "08-06", "09-03", "10-08", "11-05", "12-03"],
-    2022: ["01-07", "02-04", "03-04", "04-01", "05-06", "06-03", "07-08", "08-05", "09-02", "10-07", "11-04", "12-02"],
-    2023: ["01-06", "02-03", "03-10", "04-07", "05-05", "06-02", "07-07", "08-04", "09-01", "10-06", "11-03", "12-08"],
-    2024: ["01-05", "02-02", "03-08", "04-05", "05-03", "06-07", "07-05", "08-02", "09-06", "10-04", "11-01", "12-06"],
-    2025: ["01-10", "02-07", "03-07", "04-04", "05-02", "06-06", "07-03", "08-01", "09-05", "11-20", "12-16"],
-    2026: ["01-09", "02-11", "03-06", "04-03", "05-08", "06-05", "07-02", "08-07", "09-04"],
-  },
-  // FOMC statement days (the meeting's last day), 14:00 ET. The August 2025 notation vote is not a meeting.
-  fomc: {
-    2021: ["01-27", "03-17", "04-28", "06-16", "07-28", "09-22", "11-03", "12-15"],
-    2022: ["01-26", "03-16", "05-04", "06-15", "07-27", "09-21", "11-02", "12-14"],
-    2023: ["02-01", "03-22", "05-03", "06-14", "07-26", "09-20", "11-01", "12-13"],
-    2024: ["01-31", "03-20", "05-01", "06-12", "07-31", "09-18", "11-07", "12-18"],
-    2025: ["01-29", "03-19", "05-07", "06-18", "07-30", "09-17", "10-29", "12-10"],
-    2026: ["01-28", "03-18", "04-29", "06-17", "07-29", "09-16"],
-  },
+/** BLS news release archives for CPI and the Employment Situation, and the Federal Reserve's meeting calendar. */
+export const MACRO_RELEASE_SOURCES: Record<MacroEventKind, string> = {
+  cpi: "https://www.bls.gov/bls/news-release/cpi.htm",
+  jobs: "https://www.bls.gov/bls/news-release/empsit.htm",
+  fomc: "https://www.federalreserve.gov/monetarypolicy/fomccalendars.htm",
 };
 
-export const MACRO_RELEASE_BASIS = {
-  checkedAt: "2026-10-04",
-  /** The last day the lists are complete for: later sessions are left out, release day or not. */
-  coveredThrough: "2026-10-01",
-  sources: [
-    "https://www.bls.gov/bls/news-release/cpi.htm",
-    "https://www.bls.gov/bls/news-release/empsit.htm",
-    "https://www.federalreserve.gov/monetarypolicy/fomccalendars.htm",
-  ],
-} as const;
+/** A list more than this many days behind today says so: a release day may be missing from its end. */
+export const MACRO_RELEASES_STALE_DAYS = 14;
 
 export interface MacroRelease { kind: MacroEventKind; date: string }
 
-/** Every published release day, oldest first. */
-export function macroReleases(): MacroRelease[] {
-  return MACRO_EVENT_KINDS.flatMap((kind) => Object.entries(RELEASES[kind]).flatMap(([year, days]) =>
-    days.map((day) => ({ kind, date: `${year}-${day}` }))))
-    .sort((left, right) => left.date.localeCompare(right.date) || left.kind.localeCompare(right.kind));
+export interface MacroReleaseList {
+  /** Oldest first. */
+  releases: MacroRelease[];
+  /** The last day the list is complete for: later sessions are left out, release day or not. */
+  coveredThrough: string;
+}
+
+const DAY_MS = 86_400_000;
+const isDate = (value: unknown): value is string => typeof value === "string" && /^\d{4}-\d{2}-\d{2}$/.test(value)
+  && new Date(`${value}T00:00:00Z`).toISOString().startsWith(value);
+const byDate = (left: MacroRelease, right: MacroRelease) => left.date.localeCompare(right.date) || left.kind.localeCompare(right.kind);
+
+/** The list the app ships with: the floor whenever the server's list is missing or older. */
+export function bundledMacroReleases(): MacroReleaseList {
+  const releases = MACRO_EVENT_KINDS.flatMap((kind) => Object.entries(MACRO_RELEASE_TABLE.days[kind]).flatMap(([year, days]) =>
+    days.map((day) => ({ kind, date: `${year}-${day}` }))));
+  return { releases: releases.sort(byDate), coveredThrough: MACRO_RELEASE_TABLE.coveredThrough };
+}
+
+/**
+ * The served list extends the floor past its end; the floor keeps its own
+ * days up to there. A served list that breaks the contract, or ends no later
+ * than the floor, adds nothing.
+ */
+export function mergeMacroReleases(floor: MacroReleaseList, served: unknown): MacroReleaseList {
+  const payload = served as { coveredThrough?: unknown; releases?: Partial<Record<MacroEventKind, unknown>> } | null;
+  const coveredThrough = payload?.coveredThrough;
+  if (!isDate(coveredThrough) || coveredThrough <= floor.coveredThrough) return floor;
+  const later: MacroRelease[] = [];
+  for (const kind of MACRO_EVENT_KINDS) {
+    const dates = payload?.releases?.[kind];
+    if (!Array.isArray(dates) || !dates.every(isDate)) return floor;
+    for (const date of new Set(dates)) {
+      if (date > floor.coveredThrough && date <= coveredThrough) later.push({ kind, date });
+    }
+  }
+  return { releases: [...floor.releases, ...later].sort(byDate), coveredThrough };
+}
+
+/** Whole days from the list's last covered day to today in New York. */
+export function macroReleasesBehind(coveredThrough: string, now = Date.now()): number {
+  const today = zonedDateKey(now, "America/New_York");
+  return Math.round((Date.parse(`${today}T00:00:00Z`) - Date.parse(`${coveredThrough}T00:00:00Z`)) / DAY_MS);
+}
+
+/** The pane footer and the report notes say so once the list is old enough to miss a release day. */
+export function staleMacroReleasesNotice(list: MacroReleaseList, now = Date.now()): string | null {
+  return macroReleasesBehind(list.coveredThrough, now) > MACRO_RELEASES_STALE_DAYS
+    ? `Release days are listed through ${list.coveredThrough}; later sessions are left out.`
+    : null;
 }

package/src/plugins/builtin/market-heatmap/data.ts

@@ -1,6 +1,6 @@
 import { apiClient } from "../../../api-client";
 import type { MarketHeatmapResult, MarketHeatmapUniverseId } from "../../../api-client/market-discovery";
-export type { MarketHeatmapResult, MarketHeatmapUniverseId } from "../../../api-client/market-discovery";
+export type { MarketHeatmapUniverseId } from "../../../api-client/market-discovery";
 
 export const MARKET_HEATMAP_UNIVERSES = [
   { id: "us-equity", label: "US Stocks" },
@@ -10,12 +10,30 @@ export const MARKET_HEATMAP_UNIVERSES = [
 export const MARKET_HEATMAP_REQUEST_COUNT: Record<MarketHeatmapUniverseId, number> = { "us-equity": 500, "us-etf": 160 };
 export interface MarketHeatmapFetchOptions { count?: number; forceRefresh?: boolean; cache?: boolean; }
 export interface MarketHeatmapSources { client?: Pick<typeof apiClient, "getMarketHeatmap">; }
+
+/** A board as this client holds it: the server's snapshot, and what the request behind it was. */
+export interface MarketHeatmapBoard extends MarketHeatmapResult {
+  /**
+   * When the response arrived and passed validation. `fetchedAt` is when the
+   * server put the snapshot together, which a check a minute later can
+   * return unchanged. A board served from the cache keeps the time of the
+   * response it came from.
+   */
+  checkedAt: number;
+  /**
+   * How many of the largest listings the board covers: the count asked for,
+   * or fewer when the server serves fewer. A company listed twice is one
+   * listing of them but one tile, so `assets` can be shorter.
+   */
+  topCount: number;
+}
+
 const DEFAULT_COUNT = 80;
 /** The most names one board asks for; a server that serves fewer answers with its own maximum. */
 const MAX_MARKET_HEATMAP_COUNT = 500;
 const CACHE_TTL_MS = 60_000;
-const activeFetches = new Map<string, Promise<MarketHeatmapResult>>();
-const memoryCache = new Map<string, { expiresAt: number; result: MarketHeatmapResult }>();
+const activeFetches = new Map<string, Promise<MarketHeatmapBoard>>();
+const memoryCache = new Map<string, { expiresAt: number; result: MarketHeatmapBoard }>();
 
 /**
  * One tile per symbol. A company listed on two exchanges (KHC on NASDAQ and
@@ -37,7 +55,7 @@ export function dedupeHeatmapAssets<T extends { symbol: string; size: number | n
   return result;
 }
 
-async function loadMarketHeatmap(universe: MarketHeatmapUniverseId, count: number, sources?: MarketHeatmapSources): Promise<MarketHeatmapResult> {
+async function loadMarketHeatmap(universe: MarketHeatmapUniverseId, count: number, sources?: MarketHeatmapSources): Promise<MarketHeatmapBoard> {
   const response = await (sources?.client ?? apiClient).getMarketHeatmap(universe, count);
   if (!response.data || !Array.isArray(response.data.assets) || response.data.universe !== universe
     || (response.status !== "success" && response.status !== "partial")) throw new Error("Market heatmap unavailable");
@@ -45,6 +63,8 @@ async function loadMarketHeatmap(universe: MarketHeatmapUniverseId, count: numbe
     ...response.data,
     stale: response.stale === true || response.data.stale === true,
     assets: dedupeHeatmapAssets(response.data.assets).slice(0, count),
+    checkedAt: Date.now(),
+    topCount: Math.min(count, response.data.assets.length),
   };
 }
 
@@ -52,7 +72,7 @@ export async function fetchMarketHeatmap(
   universe: MarketHeatmapUniverseId,
   options?: MarketHeatmapFetchOptions,
   sources?: MarketHeatmapSources,
-): Promise<MarketHeatmapResult> {
+): Promise<MarketHeatmapBoard> {
   const count = Math.max(1, Math.min(MAX_MARKET_HEATMAP_COUNT, Math.round(options?.count ?? DEFAULT_COUNT)));
   const cacheKey = `${universe}:${count}`;
   const useCache = options?.cache !== false && !sources?.client;

package/src/plugins/builtin/market-heatmap/evidence.ts

@@ -0,0 +1,90 @@
+/**
+ * What `gloomberb shot HM` certifies: the tab the heat map drew, how many tiles
+ * and sectors are plotted, and whether its snapshot had loaded. The heat map has
+ * no table rows or labeled values, so this is how a capture counts as data.
+ */
+import type { PaneScreenshotEvidenceHook } from "../../../cli/pane-functions/screenshot-evidence";
+import { useRemoteUiNode } from "../../../remote/semantic-tree";
+import { isRecord } from "../../../utils/guards";
+import { heatmapMove } from "./model";
+import { heatmapTabId, type HeatmapBoardAsset, type HeatmapTabId } from "./portfolio";
+
+interface MarketHeatmapEvidence {
+  kind: "market-heatmap";
+  version: 1;
+  complete: boolean;
+  plottedValueCount: number;
+  tab: HeatmapTabId;
+  tiles: number;
+  sectors: number;
+  /** Tiles colored by a move, not left grey for want of one. */
+  moved: number;
+}
+
+interface HeatmapEvidenceInput {
+  tab: HeatmapTabId;
+  tiles: readonly { item: { id: string; data: Pick<HeatmapBoardAsset, "sector"> } }[];
+  /** The assets the tiles are colored by. */
+  assets: readonly HeatmapBoardAsset[];
+  /** Whether the tiles are grouped into sectors, rather than laid out flat. */
+  grouped: boolean;
+  /** A snapshot is on its way. */
+  loading: boolean;
+  /** The tiles are a retained board: its refresh failed, or the server served a stale snapshot. */
+  retained: boolean;
+}
+
+export function marketHeatmapEvidence({ tab, tiles, assets, grouped, loading, retained }: HeatmapEvidenceInput): MarketHeatmapEvidence {
+  const drawn = new Set(tiles.map((tile) => tile.item.id));
+  const sectors = grouped
+    ? new Set(tiles.flatMap((tile) => (tile.item.data.sector ? [tile.item.data.sector] : []))).size
+    : 0;
+  const moved = assets.filter((asset) => drawn.has(asset.symbol) && heatmapMove(asset) != null).length;
+  return {
+    kind: "market-heatmap",
+    version: 1,
+    complete: !loading && !retained && moved > 0,
+    plottedValueCount: tiles.length,
+    tab,
+    tiles: tiles.length,
+    sectors,
+    moved,
+  };
+}
+
+export function useMarketHeatmapEvidence(input: HeatmapEvidenceInput) {
+  useRemoteUiNode({
+    role: "chart-data",
+    label: "Rendered market heatmap",
+    // The capture waits for a board that is still loading.
+    getMetadata: () => ({ ...marketHeatmapEvidence(input), ready: !input.loading }),
+  });
+}
+
+const isCount = (value: unknown): value is number => Number.isSafeInteger(value) && (value as number) >= 0;
+
+export const marketHeatmapScreenshotEvidence: PaneScreenshotEvidenceHook<MarketHeatmapEvidence> = {
+  paneId: "market-heatmap",
+  kind: "market-heatmap",
+  label: "market heatmap",
+  read(value) {
+    if (!isRecord(value) || value.kind !== "market-heatmap" || value.version !== 1 || typeof value.complete !== "boolean"
+      || !isCount(value.plottedValueCount) || value.tiles !== value.plottedValueCount
+      || value.tab !== heatmapTabId(typeof value.tab === "string" ? value.tab : null)
+      || !isCount(value.sectors) || value.sectors > value.tiles
+      || !isCount(value.moved) || value.moved > value.tiles
+      || (value.complete && value.moved === 0)) return null;
+    return value as unknown as MarketHeatmapEvidence;
+  },
+  mismatches(evidence, { resolved, payload }) {
+    const settings = payload.config.layout.instances.find((entry) => entry.instanceId === payload.paneId)?.settings;
+    const asked = settings?.universe ?? resolved.options.universe;
+    return evidence.tab === heatmapTabId(typeof asked === "string" ? asked : null) ? [] : ["Heat map tab differs from the request"];
+  },
+  unavailable(evidence) {
+    return evidence?.complete ? [] : ["market heatmap"];
+  },
+  symbols() {
+    return [];
+  },
+};