gloomberb 0.16.1 → 0.16.3

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

@@ -0,0 +1,135 @@
+import type { HeadlessPaneColumn, HeadlessPaneDefinition } from "../../../types/plugin";
+import { formatCompact, formatPercentRaw } from "../../../utils/format";
+import { MARKET_HEATMAP_REQUEST_COUNT, MARKET_HEATMAP_UNIVERSES, fetchMarketHeatmap, type MarketHeatmapUniverseId } from "./data";
+import { heatmapMove, summarizeHeatmapGroups, type HeatmapGroupBy, type HeatmapGroupSummary } from "./model";
+
+/**
+ * A few names always lack a move (foreign listings and new tickers the snapshot
+ * has no change for). They are listed in a notice and in `metadata.noMove`; the
+ * report is incomplete only when so many lack one that the groups mislead.
+ */
+const MIN_MOVE_COVERAGE = 0.9;
+
+const percent = (value: unknown) => typeof value === "number" ? formatPercentRaw(value) : "—";
+const share = (value: unknown) => typeof value === "number" ? `${value.toFixed(1)}%` : "—";
+const dollars = (value: unknown) => typeof value === "number" && value > 0 ? `$${formatCompact(value)}` : "—";
+const member = (symbol: unknown, move: unknown) => typeof symbol === "string" && typeof move === "number"
+  ? `${symbol} ${formatPercentRaw(move)}`
+  : "—";
+
+function columns(universe: MarketHeatmapUniverseId, groupBy: HeatmapGroupBy, flat: boolean): HeadlessPaneColumn[] {
+  return [
+    ...(flat ? [] : groupBy === "industry"
+      ? [{ key: "group", header: "Industry" }, { key: "sector", header: "Sector" }]
+      : [{ key: "group", header: "Sector" }]),
+    { key: "names", header: "Names", align: "right" },
+    { key: "size", header: universe === "us-etf" ? "Net assets" : "Mkt cap", align: "right", format: dollars },
+    ...(flat ? [] : [{ key: "sharePercent", header: "Share", align: "right" as const, format: share }]),
+    { key: "move", header: universe === "us-etf" ? "Move (asset-wtd)" : "Move (cap-wtd)", align: "right", format: percent },
+    { key: "up", header: "Up", align: "right" },
+    { key: "down", header: "Down", align: "right" },
+    { key: "bestSymbol", header: "Best", format: (value, row) => member(value, row.bestMove) },
+    { key: "worstSymbol", header: "Worst", format: (value, row) => member(value, row.worstMove) },
+  ];
+}
+
+function noMoveNotice(symbols: readonly string[], names: number): string {
+  const shown = symbols.slice(0, 8).join(", ");
+  const rest = symbols.length > 8 ? ` and ${symbols.length - 8} more` : "";
+  return `${symbols.length} of ${names} names have no move yet and count toward size only: ${shown}${rest}.`;
+}
+
+function projectRow(summary: HeatmapGroupSummary, groupBy: HeatmapGroupBy, whole = false) {
+  return {
+    group: whole ? "All" : summary.group ?? (summary.sector ? "No industry" : groupBy === "industry" ? "Unclassified" : "No sector"),
+    ...(groupBy === "industry" ? { sector: summary.sector ?? "—" } : {}),
+    names: summary.names,
+    size: summary.size,
+    sharePercent: summary.share * 100,
+    move: summary.move,
+    moved: summary.moved,
+    up: summary.up,
+    down: summary.down,
+    unchanged: summary.unchanged,
+    bestSymbol: summary.best?.symbol ?? null,
+    bestMove: summary.best?.move ?? null,
+    worstSymbol: summary.worst?.symbol ?? null,
+    worstMove: summary.worst?.move ?? null,
+  };
+}
+
+export const marketHeatmapHeadless: HeadlessPaneDefinition<"rows"> = {
+  shape: "rows",
+  description: "The heat map's sectors or industries: each group's size-weighted day move, how many names rose and fell, and its best and worst name, for the 500 largest US stocks or large US ETFs.",
+  argument: { kind: "none" },
+  options: [
+    {
+      key: "universe",
+      description: "Board: the 500 largest US stocks, or large US ETFs (one group, as the ETF map has no sectors).",
+      type: "enum",
+      values: [
+        { value: "us-equity", aliases: ["stocks", "equity", "us"] },
+        { value: "us-etf", aliases: ["etf", "etfs"] },
+      ],
+      defaultValue: "us-equity",
+      settingKey: "universe",
+    },
+    {
+      key: "group",
+      description: "Group the stocks by sector, or by industry within each sector.",
+      type: "enum",
+      values: [{ value: "sector", aliases: ["sectors"] }, { value: "industry", aliases: ["industries"] }],
+      defaultValue: "sector",
+    },
+  ],
+  discovery: {
+    aliases: ["HM", "heatmap"],
+    dataRequirements: ["Gloom Cloud market heatmap snapshot"],
+    limitations: [
+      "The snapshot the pane starts from, refreshed about once a minute; the pane's live-streamed colors are not in the report",
+      "Moves are weighted by market cap (net assets for ETFs), not by the pane's square-root tile area",
+    ],
+  },
+  // A board snapshot refreshed on a schedule, not a feed; the pane streams on top of it, the report does not.
+  freshness: { status: "delayed" },
+  describe: (args) => {
+    const universe = MARKET_HEATMAP_UNIVERSES.find((entry) => entry.id === args.options.universe)?.label ?? "US Stocks";
+    return args.options.universe === "us-etf" ? `Market Heatmap | ${universe}` : `Market Heatmap | ${universe} by ${String(args.options.group)}`;
+  },
+  async load(args, ctx) {
+    const universe: MarketHeatmapUniverseId = args.options.universe === "us-etf" ? "us-etf" : "us-equity";
+    const groupBy: HeatmapGroupBy = args.options.group === "industry" ? "industry" : "sector";
+    const result = await fetchMarketHeatmap(
+      universe,
+      { count: MARKET_HEATMAP_REQUEST_COUNT[universe], forceRefresh: ctx.refresh },
+      { client: ctx.apiClient },
+    );
+    ctx.signal.throwIfAborted();
+    const { grouping, groups, board } = summarizeHeatmapGroups(result.assets, groupBy);
+    const flat = grouping === "flat";
+    const noMove = result.assets.filter((asset) => heatmapMove(asset) == null).map((asset) => asset.symbol);
+    const covered = result.assets.length > 0 && board.moved / board.names >= MIN_MOVE_COVERAGE;
+    return {
+      columns: columns(universe, groupBy, flat),
+      rows: groups.map((summary) => projectRow(summary, groupBy, flat)),
+      complete: !result.stale && covered,
+      unavailableSymbols: covered ? [] : noMove,
+      metadata: {
+        universe,
+        groupBy: flat ? null : groupBy,
+        asOf: new Date(result.fetchedAt).toISOString(),
+        stale: result.stale === true,
+        session: result.session ?? null,
+        regularSessionDate: result.regularSessionDate ?? null,
+        names: result.assets.length,
+        noMove,
+        ...(noMove.length > 0 ? { notices: [noMoveNotice(noMove, result.assets.length)] } : {}),
+        board: projectRow(board, groupBy, true),
+        unit: "move and sharePercent in percent; size in USD",
+        weighting: universe === "us-etf"
+          ? "Each group's move is its names' day moves weighted by net assets, over the names with a move."
+          : "Each group's move is its names' day moves weighted by market cap, over the names with a move.",
+      },
+    };
+  },
+};

package/src/plugins/builtin/market-heatmap/index.tsx

@@ -29,7 +29,7 @@ import { t, tf } from "../../../i18n";
 import { priceColor } from "../../../theme/colors";
 import { clipToDisplayWidth, formatCompact, formatCurrency, formatPercentRaw } from "../../../utils/format";
 import { isPlainKey } from "../../../utils/keyboard";
-import { useAppSelector, usePaneAppConfig, usePaneSettingValue } from "../../../state/app/context";
+import { useAppSelector, usePaneAppConfig, usePaneSettingValue, usePaneStateValue } from "../../../state/app/context";
 import { usePluginTickerActions } from "../../runtime";
 import { useLiveQuoteEntries } from "../../../state/hooks/quote-streaming";
 import { useFxRatesMap, useTickerFinancialsMap } from "../../../market-data/hooks";
@@ -44,18 +44,21 @@ import { resolvePortfolioTotalsCurrency } from "../portfolio-list/metrics";
 import { useThrottledMemo } from "../portfolio-list/use-throttled-memo";
 import { PORTFOLIO_REORDER_THROTTLE_MS } from "../portfolio-list/use-throttled-ticker-order";
 import {
+  MARKET_HEATMAP_REQUEST_COUNT,
   MARKET_HEATMAP_UNIVERSES,
   fetchMarketHeatmap,
   resetMarketHeatmapCache,
   type MarketHeatmapUniverseId,
 } from "./data";
 import {
+  HEATMAP_COLLECTION_KIND_STATE_KEY,
   PORTFOLIO_HEATMAP_TAB,
   buildPortfolioHeatmapAssets,
   fallbackHeatmapCollectionId,
   heatmapCollectionLabel,
   heatmapFollowsCollection,
   heatmapSizeBy,
+  heatmapSizeByApplies,
   heatmapSizeWeight,
   heatmapTabId,
   isRemoteHeatmapUniverse,
@@ -76,6 +79,8 @@ import {
   rankHeatmapQuoteWeights,
   useSettledValue,
 } from "./live";
+import { marketHeatmapHeadless } from "./headless";
+import { heatmapMove, resolveHeatmapGrouping, sizeWeightedMove, type HeatmapGrouping } from "./model";
 import {
   overlayScreenerQuoteEntries,
   resolveScreenerQuoteFeedStatus,
@@ -83,8 +88,6 @@ import {
 
 const NO_ASSETS: HeatmapBoardAsset[] = [];
 const NO_TARGETS: QuoteSubscriptionTarget[] = [];
-/** The 500 largest US stocks (an older server answers with its own maximum); ETFs stay flat and need fewer. */
-const MARKET_HEATMAP_REQUEST_COUNT: Record<MarketHeatmapUniverseId, number> = { "us-equity": 500, "us-etf": 160 };
 const SNAPSHOT_REFRESH_MS = 60_000;
 const LAYOUT_THROTTLE_MS = 5_000;
 /** A size change below this share of a tile's area is not worth moving it. */
@@ -128,34 +131,16 @@ function sizeLabel(asset: HeatmapBoardAsset): string | null {
   return `${label} ${formatMoneyCompact(asset.size, asset.sizeCurrency ?? asset.currency)}`;
 }
 
-/** The move, or null when there is none: no change data is not a flat session. */
-function changeOf(asset: HeatmapBoardAsset): number | null {
-  return asset.hasChange && typeof asset.changePercent === "number" && Number.isFinite(asset.changePercent)
-    ? asset.changePercent
-    : null;
+/** Marks a pre-market or after-hours move, which is measured from the regular close. */
+function sessionMark(asset: HeatmapBoardAsset): string | null {
+  if (asset.extendedSession === "PRE") return "PM";
+  if (asset.extendedSession === "POST") return "AH";
+  return null;
 }
 
-type HeatmapGrouping = "sector-industry" | "sector" | "flat";
-
-/**
- * Sector and industry blocks when the board knows its sectors. A board where
- * most of the value has none (ETFs, or a snapshot whose classification
- * failed) lays out flat rather than as one big unlabeled block.
- */
-function resolveGrouping(assets: readonly HeatmapBoardAsset[], industries: boolean): HeatmapGrouping {
-  let total = 0;
-  let classified = 0;
-  const sectors = new Set<string>();
-  for (const asset of assets) {
-    const weight = asset.weight ?? asset.size ?? 0;
-    total += weight;
-    if (asset.sector) {
-      classified += weight;
-      sectors.add(asset.sector);
-    }
-  }
-  if (sectors.size < 2 || classified < total / 2) return "flat";
-  return industries ? "sector-industry" : "sector";
+function formatMove(asset: HeatmapBoardAsset, change: number | null): string {
+  const mark = sessionMark(asset);
+  return change == null ? "—" : mark ? `${formatPercentRaw(change)} ${mark}` : formatPercentRaw(change);
 }
 
 /**
@@ -191,7 +176,7 @@ const paintItemCache = new WeakMap<HeatmapBoardAsset, MetricTreemapItem<HeatmapB
 function paintItem(asset: HeatmapBoardAsset): MetricTreemapItem<HeatmapBoardAsset> {
   const cached = paintItemCache.get(asset);
   if (cached) return cached;
-  const change = changeOf(asset);
+  const change = heatmapMove(asset);
   const details = [
     asset.price > 0 ? formatCurrency(asset.price, asset.currency) : null,
     sizeLabel(asset),
@@ -205,8 +190,9 @@ function paintItem(asset: HeatmapBoardAsset): MetricTreemapItem<HeatmapBoardAsse
     weight: asset.weight ?? asset.size ?? 0,
     colorValue: change,
     primaryText: formatHeatTileMove(change),
+    primaryTextSuffix: sessionMark(asset),
     tooltip: [
-      [asset.symbol, name, change == null ? "—" : formatPercentRaw(change)].filter(Boolean).join(" · "),
+      [asset.symbol, name, formatMove(asset, change)].filter(Boolean).join(" · "),
       ...(details.length > 0 ? [details.join(" · ")] : []),
     ],
     data: asset,
@@ -224,18 +210,10 @@ function otherSummary(items: readonly MetricTreemapItem<HeatmapBoardAsset>[]): s
 }
 
 function otherTooltip(items: readonly MetricTreemapItem<HeatmapBoardAsset>[]): string[] {
-  let weight = 0;
-  let weightedMove = 0;
-  for (const item of items) {
-    const change = changeOf(item.data);
-    const size = item.data.size ?? 0;
-    if (change == null || !(size > 0)) continue;
-    weight += size;
-    weightedMove += change * size;
-  }
+  const move = sizeWeightedMove(items.map((item) => item.data));
   return [
     tf("Other · {count} smaller names", { count: items.length }),
-    ...(weight > 0 ? [`${formatPercentRaw(weightedMove / weight)} ${t("cap-weighted")}`] : []),
+    ...(move != null ? [`${formatPercentRaw(move)} ${t("cap-weighted")}`] : []),
   ];
 }
 
@@ -262,6 +240,7 @@ function MarketHeatmapPane({ focused, width, height }: PaneProps) {
   const linkedPortfolio = useLinkedHeatmapCollection();
   const collectionId = linkedPortfolio.collectionId ?? fallbackHeatmapCollectionId(config);
   const collectionKind = getCollectionTypeFromConfig(config, collectionId);
+  const [, publishCollectionKind] = usePaneStateValue<string>(HEATMAP_COLLECTION_KIND_STATE_KEY, "");
   const portfolioLabel = heatmapCollectionLabel(config, collectionId);
   const universeTabs = useMemo(() => [
     ...MARKET_HEATMAP_UNIVERSES.map((universe) => ({ label: universe.label, value: universe.id })),
@@ -367,7 +346,7 @@ function MarketHeatmapPane({ focused, width, height }: PaneProps) {
     liveStreaming,
   });
   const resolvedAssets = useMemo(
-    () => overlayScreenerQuoteEntries(boardAssets, liveQuoteEntries),
+    () => overlayScreenerQuoteEntries(boardAssets, liveQuoteEntries, { extendedSessions: true }),
     [boardAssets, liveQuoteEntries],
   );
   const feedStatus = useMemo(
@@ -381,7 +360,7 @@ function MarketHeatmapPane({ focused, width, height }: PaneProps) {
   // Sizes follow live prices at most every LAYOUT_THROTTLE_MS and only past
   // LAYOUT_TOLERANCE; a new snapshot relays out at once. Ticks only recolour.
   const grouping = useMemo(
-    () => resolveGrouping(boardAssets, activeUniverse === "us-equity"),
+    () => resolveHeatmapGrouping(boardAssets, activeUniverse === "us-equity"),
     [activeUniverse, boardAssets],
   );
   const layoutAssets = useThrottledMemo(
@@ -456,6 +435,11 @@ function MarketHeatmapPane({ focused, width, height }: PaneProps) {
     setSelectedSymbol(null);
   }, [collectionId, linkPortfolio, setActiveUniverse]);
 
+  // The header shows the square-root control only where it changes the board.
+  useEffect(() => {
+    publishCollectionKind(collectionKind ?? "");
+  }, [collectionKind, publishCollectionKind]);
+
   // The financials map only reads the cache; this fills it for the list on screen.
   useEffect(() => {
     if (!portfolioTab) return;
@@ -610,11 +594,12 @@ function MarketHeatmapPane({ focused, width, height }: PaneProps) {
         parts: [
           { text: selectedAsset.symbol, tone: "label" as const },
           {
-            text: changeOf(selectedAsset) == null ? "—" : formatPercentRaw(changeOf(selectedAsset)!),
+            text: heatmapMove(selectedAsset) == null ? "—" : formatPercentRaw(heatmapMove(selectedAsset)!),
             tone: "value" as const,
-            color: changeOf(selectedAsset) == null ? undefined : priceColor(changeOf(selectedAsset)!),
+            color: heatmapMove(selectedAsset) == null ? undefined : priceColor(heatmapMove(selectedAsset)!),
             bold: true,
           },
+          ...(sessionMark(selectedAsset) ? [{ text: sessionMark(selectedAsset)!, tone: "muted" as const }] : []),
           ...(selectedAsset.price > 0
             ? [{ text: formatCurrency(selectedAsset.price, selectedAsset.currency), tone: "value" as const }]
             : []),
@@ -696,12 +681,20 @@ export const marketHeatmapPlugin: GloomPlugin = {
       name: "Market Heatmap",
       icon: "H",
       component: MarketHeatmapPane,
+      headless: marketHeatmapHeadless,
       defaultPosition: "right",
       defaultMode: "floating",
       defaultFloatingSize: { width: 110, height: 36 },
       quickSettings: [
         LIVE_STREAMING_QUICK_SETTING,
-        { type: "toggle", key: SIZE_BY_SETTING_KEY, icon: "sqrt", onValue: SQRT_SIZE_VALUE, label: "Size by square root of market cap" },
+        {
+          type: "toggle",
+          key: SIZE_BY_SETTING_KEY,
+          icon: "sqrt",
+          onValue: SQRT_SIZE_VALUE,
+          label: "Size by square root of market cap",
+          visible: (context) => heatmapSizeByApplies(context.settings.universe, context.paneState[HEATMAP_COLLECTION_KIND_STATE_KEY]),
+        },
       ],
       settings: (context) => withLiveStreamingSetting({
         title: "Market Heatmap Settings",

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

@@ -0,0 +1,146 @@
+import type { MarketHeatmapAsset } from "../../../api-client/market-discovery";
+
+/**
+ * The board's grouping and move arithmetic, shared by the pane and the `fn HM`
+ * report so a sector reads the same in both. Isomorphic: no React or renderer.
+ */
+
+type HeatmapMoveAsset = Pick<MarketHeatmapAsset, "symbol" | "hasChange" | "changePercent" | "size" | "sector" | "industry"> & {
+  /** Treemap area, when it is not `size` itself. */
+  weight?: number;
+};
+
+/**
+ * The move, or null when there is none: no change data is not a flat session.
+ * A name without the last session's close still has the move of the open
+ * pre-market or after-hours session it streams (`extendedSession`).
+ */
+export function heatmapMove(asset: Pick<MarketHeatmapAsset, "hasChange" | "changePercent"> & { extendedSession?: string }): number | null {
+  return (asset.hasChange || asset.extendedSession != null) && typeof asset.changePercent === "number" && Number.isFinite(asset.changePercent)
+    ? asset.changePercent
+    : null;
+}
+
+export type HeatmapGrouping = "sector-industry" | "sector" | "flat";
+
+/**
+ * Sector and industry blocks when the board knows its sectors. A board where
+ * most of the value has none (ETFs, or a snapshot whose classification
+ * failed) lays out flat rather than as one big unlabeled block.
+ */
+export function resolveHeatmapGrouping(assets: readonly HeatmapMoveAsset[], industries: boolean): HeatmapGrouping {
+  let total = 0;
+  let classified = 0;
+  const sectors = new Set<string>();
+  for (const asset of assets) {
+    const weight = asset.weight ?? asset.size ?? 0;
+    total += weight;
+    if (asset.sector) {
+      classified += weight;
+      sectors.add(asset.sector);
+    }
+  }
+  if (sectors.size < 2 || classified < total / 2) return "flat";
+  return industries ? "sector-industry" : "sector";
+}
+
+/**
+ * The move of a set of names weighted by their size (market cap, an ETF's net
+ * assets, a position's value), over the names that have both. Null when none do.
+ */
+export function sizeWeightedMove(assets: readonly HeatmapMoveAsset[]): number | null {
+  let weight = 0;
+  let weightedMove = 0;
+  for (const asset of assets) {
+    const change = heatmapMove(asset);
+    const size = asset.size ?? 0;
+    if (change == null || !(size > 0)) continue;
+    weight += size;
+    weightedMove += change * size;
+  }
+  return weight > 0 ? weightedMove / weight : null;
+}
+
+export type HeatmapGroupBy = "sector" | "industry";
+
+export interface HeatmapGroupSummary {
+  /** The sector or industry; null for names the snapshot does not classify, or every name on a flat board. */
+  group: string | null;
+  /** The industry's sector, when grouping by industry. */
+  sector: string | null;
+  names: number;
+  /** Total size: market cap, or net assets on the ETF board. */
+  size: number;
+  /** This group's share of the board's total size. */
+  share: number;
+  move: number | null;
+  /** Names with a move, and the size they carry; the rest have no change data yet. */
+  moved: number;
+  up: number;
+  down: number;
+  unchanged: number;
+  best: { symbol: string; move: number } | null;
+  worst: { symbol: string; move: number } | null;
+}
+
+function summarize(group: string | null, sector: string | null, assets: readonly HeatmapMoveAsset[], boardSize: number): HeatmapGroupSummary {
+  let up = 0;
+  let down = 0;
+  let unchanged = 0;
+  let size = 0;
+  let best: HeatmapGroupSummary["best"] = null;
+  let worst: HeatmapGroupSummary["worst"] = null;
+  for (const asset of assets) {
+    size += asset.size ?? 0;
+    const move = heatmapMove(asset);
+    if (move == null) continue;
+    if (move > 0) up += 1;
+    else if (move < 0) down += 1;
+    else unchanged += 1;
+    if (!best || move > best.move) best = { symbol: asset.symbol, move };
+    if (!worst || move < worst.move) worst = { symbol: asset.symbol, move };
+  }
+  return {
+    group,
+    sector,
+    names: assets.length,
+    size,
+    share: boardSize > 0 ? size / boardSize : 0,
+    move: sizeWeightedMove(assets),
+    moved: up + down + unchanged,
+    up,
+    down,
+    unchanged,
+    best,
+    worst,
+  };
+}
+
+/**
+ * One summary per sector or industry, largest first as the board lays them
+ * out. A flat board (ETFs) is one group of every name. Unclassified names form
+ * their own group last.
+ */
+export function summarizeHeatmapGroups(
+  assets: readonly HeatmapMoveAsset[],
+  groupBy: HeatmapGroupBy,
+): { grouping: HeatmapGrouping; groups: HeatmapGroupSummary[]; board: HeatmapGroupSummary } {
+  const grouping = resolveHeatmapGrouping(assets, groupBy === "industry");
+  const boardSize = assets.reduce((sum, asset) => sum + (asset.size ?? 0), 0);
+  const board = summarize(null, null, assets, boardSize);
+  if (grouping === "flat") return { grouping, groups: [board], board };
+  const buckets = new Map<string, { group: string | null; sector: string | null; assets: HeatmapMoveAsset[] }>();
+  for (const asset of assets) {
+    const sector = asset.sector ?? null;
+    const group = sector == null ? null : grouping === "sector-industry" ? asset.industry ?? null : sector;
+    const key = `${sector ?? ""}\u0000${group ?? ""}`;
+    const bucket = buckets.get(key) ?? { group, sector, assets: [] };
+    bucket.assets.push(asset);
+    buckets.set(key, bucket);
+  }
+  const groups = [...buckets.values()]
+    .map((bucket) => summarize(bucket.group, grouping === "sector-industry" ? bucket.sector : null, bucket.assets, boardSize))
+    .sort((left, right) => Number(left.sector == null && left.group == null) - Number(right.sector == null && right.group == null)
+      || right.size - left.size);
+  return { grouping, groups, board };
+}

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

@@ -3,6 +3,7 @@ import type { MarketHeatmapAsset, MarketHeatmapUniverseId } from "../../../api-c
 import { useAppSelector, usePaneStateValue } from "../../../state/app/context";
 import type { ColumnConfig } from "../../../types/config";
 import type { TickerFinancials } from "../../../types/financials";
+import { getSessionMoveDisplay, type ExtendedSession } from "../../../market-data/market/status";
 import type { TickerRecord } from "../../../types/ticker";
 import { getSortValue, type ColumnContext } from "../portfolio-list/metrics";
 
@@ -36,6 +37,8 @@ export interface HeatmapBoardAsset extends MarketHeatmapAsset {
   sizeCurrency?: string;
   /** Treemap area, when it is not `size` itself. */
   weight?: number;
+  /** The price and move are this open pre-market or after-hours session's, from the regular close. */
+  extendedSession?: ExtendedSession;
 }
 
 export interface HeatmapPortfolioPane {
@@ -48,6 +51,19 @@ export function heatmapTabId(value: string | null | undefined): HeatmapTabId {
   return "us-equity";
 }
 
+/** Pane state where the pane says which kind of list its portfolio tab shows, for the header to read. */
+export const HEATMAP_COLLECTION_KIND_STATE_KEY = "collectionKind";
+
+/**
+ * Whether Size by changes the board: the market boards and a watchlist, never
+ * a portfolio, whose holdings are always sized by position value. Until the
+ * pane has said which list its tab shows, the control stays away.
+ */
+export function heatmapSizeByApplies(universe: unknown, collectionKind: unknown): boolean {
+  return heatmapTabId(typeof universe === "string" ? universe : null) !== PORTFOLIO_HEATMAP_TAB
+    || collectionKind === "watchlist";
+}
+
 export function isRemoteHeatmapUniverse(value: HeatmapTabId): value is MarketHeatmapUniverseId {
   return value !== PORTFOLIO_HEATMAP_TAB;
 }
@@ -200,16 +216,19 @@ export function buildPortfolioHeatmapAssets({
     const symbol = ticker.metadata.ticker;
     const snapshot = financials.get(symbol);
     const quote = snapshot?.quote;
-    const price = quote != null && Number.isFinite(quote.price) ? quote.price : null;
+    // Colored like the market boards: an open extended session's move, else the regular session's.
+    const display = getSessionMoveDisplay(quote);
+    const price = display != null && Number.isFinite(display.price) ? display.price : null;
     const size = positiveNumber(getSortValue(sizeColumn, ticker, snapshot, context));
-    const hasChange = quote != null && Number.isFinite(quote.changePercent);
+    const hasChange = display?.changePercent != null && Number.isFinite(display.changePercent);
     return {
       symbol,
       name: quote?.name?.trim() || ticker.metadata.name || symbol,
       price: price ?? 0,
-      change: quote != null && Number.isFinite(quote.change) ? quote.change : 0,
-      changePercent: hasChange ? quote.changePercent : 0,
+      change: display?.change != null && Number.isFinite(display.change) ? display.change : 0,
+      changePercent: hasChange ? display.changePercent! : 0,
       hasChange,
+      ...(display?.session ? { extendedSession: display.session } : {}),
       size,
       weight: size == null ? undefined : kind === "portfolio" ? size : heatmapSizeWeight(size, sizeBy),
       sizeKind: "market-cap",

package/src/plugins/builtin/market-movers/headless.ts

@@ -81,6 +81,8 @@ export function createMarketMoversHeadless(
 ): HeadlessPaneDefinition<"rows"> {
   return {
     shape: "rows",
+    // A screener snapshot, not a real-time feed; rows keep the time of their own last price.
+    freshness: { status: "delayed" },
     argument: { kind: "none" },
     options: [{
       key: "list",

package/src/plugins/builtin/market-valuation/headless.ts

@@ -120,6 +120,8 @@ function projectValuationHeadlessBundle(
 
 export const marketValuationHeadless: HeadlessPaneDefinition<"bundle"> = {
   shape: "bundle",
+  // Each indicator row checks its own release schedule and says when it is stale.
+  freshness: { status: "not-a-feed", basis: "published statistics" },
   argument: {
     kind: "free-text",
     placeholder: "indicator",

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

@@ -1,7 +1,9 @@
 import { apiClient } from "../../../api-client";
+import { ApiRequestError } from "../../../api-client/errors";
 import type { FundMembersPayload, FundChangesPayload, MemberFundsPayload } from "../../../api-client/members";
 import { createPluginCache } from "../../../data/plugin-cache";
 import { cachedCloudResource, loadCloudResource, unavailableOnServer } from "../shared/cloud-resource";
+import { coveredFund, notCoveredMessage } from "./model";
 const policy = { staleMs: 60_000, expireMs: 2 * 60 * 60_000 };
 export const fundListCache = createPluginCache<MemberFundsPayload>({ kind: "member-funds", source: "gloom-cloud", schemaVersion: 1, policy });
 export const fundMembersCache = createPluginCache<FundMembersPayload>({ kind: "fund-members", source: "gloom-cloud", schemaVersion: 1, policy });
@@ -22,12 +24,27 @@ function validateFunds(data: MemberFundsPayload) {
   if (!data || !Array.isArray(data.funds) || !data.funds.every((fund) => typeof fund.ticker === "string" && typeof fund.name === "string")) throw new Error("Unreadable covered funds response");
   return data;
 }
+const UNAVAILABLE = "Fund members are not available on this server yet.";
 async function fetchPayload<T>(fetcher: () => Promise<T>, validate: (data: T) => T) {
-  try { return validate(await fetcher()); } catch (error) { throw unavailableOnServer(error, "Fund members are not available on this server yet."); }
+  try { return validate(await fetcher()); } catch (error) { throw unavailableOnServer(error, UNAVAILABLE); }
+}
+/**
+ * A 404 for one fund means either an uncovered fund or a server without the route, and the two read the
+ * same. The covered list tells them apart: a fund missing from a readable list is not covered; a list
+ * that cannot be read, or that holds the fund, leaves the server-side message.
+ */
+async function fetchFundPayload<T>(fund: string, fetcher: () => Promise<T>, validate: (data: T) => T, client: Client) {
+  try { return validate(await fetcher()); } catch (error) {
+    if (error instanceof ApiRequestError && error.status === 404) {
+      const funds = await fetchFunds(client).then((payload) => payload.funds, () => []);
+      if (funds.length && !coveredFund(funds, fund)) throw new Error(notCoveredMessage(fund, funds));
+    }
+    throw unavailableOnServer(error, UNAVAILABLE);
+  }
 }
 export const fetchFunds = (client: Client = apiClient) => fetchPayload(() => client.getMemberFunds(), validateFunds);
-export const fetchMembers = (fund: string, client: Client = apiClient) => fetchPayload(() => client.getFundMembers(fund), validateMembers);
-export const fetchChanges = (fund: string, client: Client = apiClient) => fetchPayload(() => client.getFundChanges(fund), validateChanges);
+export const fetchMembers = (fund: string, client: Client = apiClient) => fetchFundPayload(fund, () => client.getFundMembers(fund), validateMembers, client);
+export const fetchChanges = (fund: string, client: Client = apiClient) => fetchFundPayload(fund, () => client.getFundChanges(fund), validateChanges, client);
 export const cachedFunds = () => cachedCloudResource(fundListCache, "list", validateFunds);
 export const loadFunds = (force = false) => loadCloudResource(fundListCache, "list", () => fetchFunds(), { force, validate: validateFunds });
 export const cachedMembers = (fund: string) => cachedCloudResource(fundMembersCache, fund, validateMembers);

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

@@ -15,17 +15,19 @@ export const membersHeadless: HeadlessPaneDefinition<"rows"> = {
   describe: (args) => args.rawArgument ? `MEMB ${args.rawArgument}` : "Index and ETF members",
   async load(args, context) {
     const input = args.symbols[0] ?? args.rawArgument ?? "";
-    if (!input) return { rows: (await fetchFunds(context.apiClient)).funds.map((fund) => ({ ...fund })), columns: [{ key: "ticker", header: "Fund" }, { key: "name", header: "Index" }, { key: "asOf", header: "Holdings as of" }] };
+    if (!input) return { freshness: { status: "not-a-feed", basis: "fund holdings files" }, rows: (await fetchFunds(context.apiClient)).funds.map((fund) => ({ ...fund })), columns: [{ key: "ticker", header: "Fund" }, { key: "name", header: "Index" }, { key: "asOf", header: "Holdings as of" }] };
     const fund = canonicalFund(input);
     if (args.options.tab === "changes") {
       const data = await fetchChanges(fund, context.apiClient);
-      return { rows: data.changes.map((row) => ({ ...row, reason: changeReason(row) })), columns: [{ key: "effectiveDate", header: "Effective" }, { key: "added", header: "Added" }, { key: "removed", header: "Removed" }, { key: "daysToGo", header: "In days", align: "right" }, { key: "reason", header: "Reason" }],
+      return { freshness: { status: "not-a-feed", basis: "index changes" }, rows: data.changes.map((row) => ({ ...row, reason: changeReason(row) })), columns: [{ key: "effectiveDate", header: "Effective" }, { key: "added", header: "Added" }, { key: "removed", header: "Removed" }, { key: "daysToGo", header: "In days", align: "right" }, { key: "reason", header: "Reason" }],
         complete: data.available && !data.stale, metadata: { ...data, changes: undefined } };
     }
     const data = await fetchMembers(fund, context.apiClient);
     const movers = args.options.tab === "movers";
     const rows = memberRows(data.members, movers ? "movers" : "members", "", DEFAULT_SORT).flatMap((row) => row.kind === "item" ? [{ ...row.item }] : []);
-    return { rows, columns: movers ? [...columns.slice(0, 3), { key: "contribution", header: "Contrib. pp", align: "right", format: (value) => percent(value as number | null, "", 3) }] : columns,
+    // Member prices are the pane's 15-minute delayed quotes. As in the pane, the fund's snapshot says
+    // whether it is stale; the members' own flags are not what the pane reads.
+    return { freshness: { status: data.stale ? "stale" : "delayed", delayMinutes: 15, ignoreStaleFlags: true }, rows, columns: movers ? [...columns.slice(0, 3), { key: "contribution", header: "Contrib. pp", align: "right", format: (value) => percent(value as number | null, "", 3) }] : columns,
       complete: !data.stale && data.aggregate.fresh1D === data.aggregate.total,
       unavailableSymbols: data.members.flatMap((row) => row.symbol && row.changePercent === null ? [row.symbol] : []),
       metadata: { fund: data.fund, asOf: data.asOf, snapshotAsOf: data.snapshotAsOf, aggregate: data.aggregate, stale: data.stale } };