gloomberb 0.16.3 → 0.16.4

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

@@ -19,6 +19,7 @@ import {
   usePaneStatusFooter,
   type MetricTreemapDirection,
   type MetricTreemapItem,
+  type PaneFooterSegment,
 } from "../../../components";
 import { handleRefreshKey } from "../../../components/data-table/table-pane";
 import { useShortcut } from "../../../react/input";
@@ -27,7 +28,7 @@ import type { GloomPlugin, PaneProps, PaneSettingField } from "../../../types/pl
 import type { TickerRecord } from "../../../types/ticker";
 import { t, tf } from "../../../i18n";
 import { priceColor } from "../../../theme/colors";
-import { clipToDisplayWidth, formatCompact, formatCurrency, formatPercentRaw } from "../../../utils/format";
+import { clipToDisplayWidth, displayWidth, formatCompact, formatCurrency, formatPercentRaw } from "../../../utils/format";
 import { isPlainKey } from "../../../utils/keyboard";
 import { useAppSelector, usePaneAppConfig, usePaneSettingValue, usePaneStateValue } from "../../../state/app/context";
 import { usePluginTickerActions } from "../../runtime";
@@ -48,6 +49,7 @@ import {
   MARKET_HEATMAP_UNIVERSES,
   fetchMarketHeatmap,
   resetMarketHeatmapCache,
+  type MarketHeatmapBoard,
   type MarketHeatmapUniverseId,
 } from "./data";
 import {
@@ -79,8 +81,20 @@ import {
   rankHeatmapQuoteWeights,
   useSettledValue,
 } from "./live";
+import { useMarketHeatmapEvidence } from "./evidence";
 import { marketHeatmapHeadless } from "./headless";
-import { heatmapMove, resolveHeatmapGrouping, sizeWeightedMove, type HeatmapGrouping } from "./model";
+import {
+  HEATMAP_NAME_COUNTS,
+  heatmapBoardCaption,
+  heatmapMove,
+  heatmapNameCount,
+  heatmapSessionBasis,
+  regularSessionHeatmapAssets,
+  resolveHeatmapGrouping,
+  sizeWeightedMove,
+  type HeatmapGrouping,
+  type HeatmapSessionBasis,
+} from "./model";
 import {
   overlayScreenerQuoteEntries,
   resolveScreenerQuoteFeedStatus,
@@ -93,10 +107,15 @@ const LAYOUT_THROTTLE_MS = 5_000;
 /** A size change below this share of a tile's area is not worth moving it. */
 const LAYOUT_TOLERANCE = 0.005;
 const TERMINAL_PAINT_THROTTLE_MS = 250;
+/** "loading", which comes and goes with each refresh. */
+const LOADING_FOOTER_WIDTH = 7;
 const SELECTION_STREAM_SETTLE_MS = 1_500;
 const TOOLTIP_NAME_WIDTH = 28;
 const SIZE_BY_SETTING_KEY = "sizeBy";
 const SQRT_SIZE_VALUE: HeatmapSizeBy = "sqrt-market-cap";
+const SESSION_BASIS_SETTING_KEY = "sessionBasis";
+const REGULAR_SESSION_BASIS: HeatmapSessionBasis = "regular-session";
+const NAME_COUNT_SETTING_KEY = "maxNames";
 const NO_BOARD = { assets: NO_ASSETS, omitted: 0 };
 const EMPTY_TICKERS: TickerRecord[] = [];
 const NO_CURRENCIES: string[] = [];
@@ -125,6 +144,10 @@ function formatMoneyCompact(value: number | null | undefined, currency: string):
   return `${formatCompact(value)} ${currency}`;
 }
 
+function footerSegmentWidth(segment: PaneFooterSegment): number {
+  return segment.parts.reduce((total, part, index) => total + (index > 0 ? 1 : 0) + displayWidth(part.text), 0);
+}
+
 function sizeLabel(asset: HeatmapBoardAsset): string | null {
   if (asset.showSize === false || asset.size == null) return null;
   const label = asset.sizeCaption ?? (asset.sizeKind === "net-assets" ? "Assets" : "Mkt");
@@ -233,6 +256,10 @@ function MarketHeatmapPane({ focused, width, height }: PaneProps) {
   const [linkPortfolio] = usePaneSettingValue<boolean>("linkPortfolio", false);
   const [sizeBySetting] = usePaneSettingValue<string>(SIZE_BY_SETTING_KEY, SQRT_SIZE_VALUE);
   const sizeBy = heatmapSizeBy(sizeBySetting);
+  const [sessionBasisSetting] = usePaneSettingValue<unknown>(SESSION_BASIS_SETTING_KEY, null);
+  const regularSession = heatmapSessionBasis(sessionBasisSetting) === REGULAR_SESSION_BASIS;
+  const [nameCountSetting] = usePaneSettingValue<unknown>(NAME_COUNT_SETTING_KEY, null);
+  const nameCount = heatmapNameCount(nameCountSetting);
   const activeUniverse = heatmapTabId(universeSetting);
   const portfolioTab = activeUniverse === PORTFOLIO_HEATMAP_TAB;
   const config = usePaneAppConfig();
@@ -281,26 +308,38 @@ function MarketHeatmapPane({ focused, width, height }: PaneProps) {
         currency: boardCurrency,
         exchangeRates,
         sizeBy,
+        regularSession,
       })
       : NO_BOARD),
     [financials],
-    [boardCurrency, collectionId, collectionKind, collectionTickers, exchangeRates, financials.size, sizeBy],
+    [boardCurrency, collectionId, collectionKind, collectionTickers, exchangeRates, financials.size, regularSession, sizeBy],
     PORTFOLIO_REORDER_THROTTLE_MS,
   );
   const portfolioAssets = portfolioBoard.assets;
-  const [assets, setAssets] = useState<HeatmapBoardAsset[]>([]);
-  // The universe `assets` came from. A board is drawn only under its own tab,
-  // so a switch never paints the previous universe's tiles.
-  const [loadedUniverse, setLoadedUniverse] = useState<MarketHeatmapUniverseId | null>(null);
-  const [lastUpdated, setLastUpdated] = useState<number | null>(null);
+  // The last market board that loaded, with the universe and count it was
+  // asked for. It is drawn only under its own tab, so a switch never paints the
+  // previous universe's tiles, and its footer names its own count while a new
+  // one is on its way.
+  const [board, setBoard] = useState<MarketHeatmapBoard | null>(null);
   // The first load starts before the effect runs; an empty board is not "no data".
   const [loading, setLoading] = useState(true);
   const [loadError, setLoadError] = useState<string | null>(null);
-  const [stale, setStale] = useState(false);
   const [selectedSymbol, setSelectedSymbol] = useState<string | null>(null);
   const fetchGenRef = useRef(0);
   const seenCollection = useRef<string | null>(null);
-  const boardAssets = portfolioTab ? portfolioAssets : (loadedUniverse === activeUniverse ? assets : NO_ASSETS);
+  const shownBoard = !portfolioTab && board?.universe === activeUniverse ? board : null;
+  const stale = board?.stale === true;
+  const requestCount = isRemoteHeatmapUniverse(activeUniverse)
+    ? Math.min(MARKET_HEATMAP_REQUEST_COUNT[activeUniverse], nameCount)
+    : 0;
+  const marketAssets = useMemo(
+    () => {
+      const assets: readonly HeatmapBoardAsset[] = shownBoard?.assets ?? NO_ASSETS;
+      return regularSession ? regularSessionHeatmapAssets(assets, shownBoard?.session) : assets;
+    },
+    [regularSession, shownBoard],
+  );
+  const boardAssets = portfolioTab ? portfolioAssets : marketAssets;
   const hasBoard = boardAssets.length > 0;
 
   const selectUniverse = useCallback((value: string) => {
@@ -345,9 +384,12 @@ function MarketHeatmapPane({ focused, width, height }: PaneProps) {
     freshnessScopeKey: `market-heatmap:${activeUniverse}`,
     liveStreaming,
   });
+  const completedSessionDate = shownBoard?.regularSessionDate ?? null;
   const resolvedAssets = useMemo(
-    () => overlayScreenerQuoteEntries(boardAssets, liveQuoteEntries, { extendedSessions: true }),
-    [boardAssets, liveQuoteEntries],
+    () => overlayScreenerQuoteEntries(boardAssets, liveQuoteEntries, regularSession
+      ? { regularSession: true, completedSessionDate }
+      : { extendedSessions: true }),
+    [boardAssets, completedSessionDate, liveQuoteEntries, regularSession],
   );
   const feedStatus = useMemo(
     () => resolveScreenerQuoteFeedStatus(quoteTargets, liveQuoteEntries, {
@@ -363,10 +405,11 @@ function MarketHeatmapPane({ focused, width, height }: PaneProps) {
     () => resolveHeatmapGrouping(boardAssets, activeUniverse === "us-equity"),
     [activeUniverse, boardAssets],
   );
+  // A new board, or a new Colour by, applies at once rather than on the next tick.
   const layoutAssets = useThrottledMemo(
     () => resolvedAssets,
     [resolvedAssets],
-    [boardAssets],
+    [boardAssets, regularSession],
     LAYOUT_THROTTLE_MS,
   );
   const layoutItems = useSettledLayoutItems(
@@ -384,11 +427,19 @@ function MarketHeatmapPane({ focused, width, height }: PaneProps) {
   const paintAssets = useThrottledMemo(
     () => resolvedAssets,
     [resolvedAssets],
-    [boardAssets],
+    [boardAssets, regularSession],
     nativePaneChrome ? 0 : TERMINAL_PAINT_THROTTLE_MS,
   );
   const paintItems = useMemo(() => buildPaintItems(paintAssets), [paintAssets]);
   const visibleTiles = scene.tiles;
+  useMarketHeatmapEvidence({
+    tab: activeUniverse,
+    tiles: visibleTiles,
+    assets: paintAssets,
+    grouped: grouping !== "flat",
+    loading: !portfolioTab && loading,
+    retained: !portfolioTab && (stale || loadError != null),
+  });
   const selectedTileIndex = selectedSymbol ? visibleTiles.findIndex((tile) => tile.item.id === selectedSymbol) : -1;
   const activeIdx = selectedTileIndex >= 0 ? selectedTileIndex : (visibleTiles.length > 0 ? 0 : -1);
   const activeSymbol = activeIdx >= 0 ? visibleTiles[activeIdx]!.item.id : null;
@@ -396,7 +447,7 @@ function MarketHeatmapPane({ focused, width, height }: PaneProps) {
     ? resolvedAssets.find((asset) => asset.symbol === activeSymbol) ?? null
     : null;
 
-  const loadUniverse = useCallback(async (universe: MarketHeatmapUniverseId, options?: { forceRefresh?: boolean }) => {
+  const loadUniverse = useCallback(async (universe: MarketHeatmapUniverseId, count: number, options?: { forceRefresh?: boolean }) => {
     fetchGenRef.current += 1;
     const gen = fetchGenRef.current;
     setLoading(true);
@@ -404,14 +455,11 @@ function MarketHeatmapPane({ focused, width, height }: PaneProps) {
 
     try {
       const result = await fetchMarketHeatmap(universe, {
-        count: MARKET_HEATMAP_REQUEST_COUNT[universe],
+        count,
         forceRefresh: options?.forceRefresh,
       });
       if (fetchGenRef.current !== gen) return;
-      setAssets(result.assets);
-      setLoadedUniverse(universe);
-      setLastUpdated(result.fetchedAt);
-      setStale(result.stale === true);
+      setBoard(result);
       // Selection is the user's; the effect below only fills it when it is gone.
     } catch {
       if (fetchGenRef.current !== gen) return;
@@ -424,8 +472,8 @@ function MarketHeatmapPane({ focused, width, height }: PaneProps) {
 
   useEffect(() => {
     if (!isRemoteHeatmapUniverse(activeUniverse)) return;
-    void loadUniverse(activeUniverse);
-  }, [activeUniverse, loadUniverse]);
+    void loadUniverse(activeUniverse, requestCount);
+  }, [activeUniverse, loadUniverse, requestCount]);
 
   useEffect(() => {
     const previous = seenCollection.current;
@@ -460,12 +508,12 @@ function MarketHeatmapPane({ focused, width, height }: PaneProps) {
       return;
     }
     if (!isRemoteHeatmapUniverse(activeUniverse)) return;
-    void loadUniverse(activeUniverse, { forceRefresh: true });
-  }, [activeUniverse, collectionId, collectionKind, collectionTickers, loadUniverse, portfolioTab]);
+    void loadUniverse(activeUniverse, requestCount, { forceRefresh: true });
+  }, [activeUniverse, collectionId, collectionKind, collectionTickers, loadUniverse, portfolioTab, requestCount]);
   // The list's quotes stream; on a timer only the market boards reload.
   const autoRefresh = useCallback(() => {
-    if (isRemoteHeatmapUniverse(activeUniverse)) void loadUniverse(activeUniverse, { forceRefresh: true });
-  }, [activeUniverse, loadUniverse]);
+    if (isRemoteHeatmapUniverse(activeUniverse)) void loadUniverse(activeUniverse, requestCount, { forceRefresh: true });
+  }, [activeUniverse, loadUniverse, requestCount]);
 
   const selectAdjacentUniverse = useCallback((direction: -1 | 1) => {
     const index = universeTabs.findIndex((tab) => tab.value === activeUniverse);
@@ -574,9 +622,11 @@ function MarketHeatmapPane({ focused, width, height }: PaneProps) {
     }
   });
 
-  const updated = useUpdatedAgo(!portfolioTab && loadedUniverse === activeUniverse ? lastUpdated : null);
+  // Ages the last check that succeeded, not the snapshot, which the server can
+  // hand back unchanged long after it was put together.
+  const checked = useUpdatedAgo(shownBoard?.checkedAt ?? null);
   // The snapshot carries sizes and every name the stream does not; the server caches it for a minute.
-  useAutoRefresh(lastUpdated, autoRefresh, { intervalMs: SNAPSHOT_REFRESH_MS });
+  useAutoRefresh(board?.checkedAt ?? null, autoRefresh, { intervalMs: SNAPSHOT_REFRESH_MS });
 
   usePaneStatusFooter({ registrationId: "market-heatmap-retained", stale: hasBoard && stale && !portfolioTab });
   usePaneNoticeFooter({
@@ -587,41 +637,53 @@ function MarketHeatmapPane({ focused, width, height }: PaneProps) {
     focused,
   });
 
-  usePaneFooter("market-heatmap", () => ({
-    info: [
-      ...(selectedAsset ? [{
-        id: "selected",
-        parts: [
-          { text: selectedAsset.symbol, tone: "label" as const },
-          {
-            text: heatmapMove(selectedAsset) == null ? "—" : formatPercentRaw(heatmapMove(selectedAsset)!),
-            tone: "value" as const,
-            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 }]
-            : []),
-          ...(sizeLabel(selectedAsset) ? [{ text: sizeLabel(selectedAsset)!, tone: "muted" as const }] : []),
-          ...(selectedAsset.volume != null
-            ? [{ text: `Vol ${formatCompact(selectedAsset.volume)}`, tone: "muted" as const }]
-            : []),
-        ],
-      }] : []),
-      ...(updated ? [{
-        id: "updated",
-        parts: [{ text: `updated ${updated}`, tone: "muted" as const }],
-      }] : []),
-      ...(!portfolioTab && loading ? [{ id: "loading", parts: [{ text: "loading", tone: "muted" as const }] }] : []),
-      // Without a board the body carries the failure.
-      ...(!portfolioTab && loadError && hasBoard ? [{ id: "error", parts: [{ text: "refresh failed", tone: "warning" as const }] }] : []),
-      ...(feedStatus ? [{
-        id: "feed",
-        parts: [{ text: feedStatus, tone: feedStatus === "live" ? "value" as const : "muted" as const }],
-      }] : []),
-    ],
-  }), [feedStatus, hasBoard, loadError, loading, portfolioTab, selectedAsset, updated]);
+  usePaneFooter("market-heatmap", () => {
+    const selected: PaneFooterSegment[] = selectedAsset ? [{
+      id: "selected",
+      parts: [
+        { text: selectedAsset.symbol, tone: "label" as const },
+        {
+          text: heatmapMove(selectedAsset) == null ? "—" : formatPercentRaw(heatmapMove(selectedAsset)!),
+          tone: "value" as const,
+          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 }]
+          : []),
+        ...(sizeLabel(selectedAsset) ? [{ text: sizeLabel(selectedAsset)!, tone: "muted" as const }] : []),
+        ...(selectedAsset.volume != null
+          ? [{ text: `Vol ${formatCompact(selectedAsset.volume)}`, tone: "muted" as const }]
+          : []),
+      ],
+    }] : [];
+    // Without a board the body carries the failure.
+    const failed: PaneFooterSegment[] = !portfolioTab && loadError && hasBoard
+      ? [{ id: "error", parts: [{ text: "refresh failed", tone: "warning" as const }] }]
+      : [];
+    const feed: PaneFooterSegment[] = feedStatus
+      ? [{ id: "feed", parts: [{ text: feedStatus, tone: feedStatus === "live" ? "value" as const : "muted" as const }] }]
+      : [];
+    const loadingSegment: PaneFooterSegment[] = !portfolioTab && loading
+      ? [{ id: "loading", parts: [{ text: "loading", tone: "muted" as const }] }]
+      : [];
+    // The caption takes the room the rest leaves, with "loading" counted in
+    // always, so a refresh never squeezes the row; a narrow pane drops its
+    // least important parts rather than truncating every segment.
+    const others = [...selected, ...failed, ...feed];
+    const room = width - others.reduce((total, segment) => total + footerSegmentWidth(segment) + 1, 0) - LOADING_FOOTER_WIDTH - 1;
+    const caption = shownBoard ? heatmapBoardCaption(shownBoard, { now: Date.now(), checked, failed: failed.length > 0, maxWidth: room }) : null;
+    return {
+      info: [
+        ...selected,
+        ...failed,
+        ...(caption ? [{ id: "board", parts: [{ text: caption, tone: "muted" as const }] }] : []),
+        ...feed,
+        ...loadingSegment,
+      ],
+    };
+  }, [checked, feedStatus, hasBoard, loadError, loading, portfolioTab, selectedAsset, shownBoard, width]);
 
   return (
     <Box flexDirection="column" width={width} height={height}>
@@ -701,6 +763,8 @@ export const marketHeatmapPlugin: GloomPlugin = {
         values: {
           linkPortfolio: context.settings.linkPortfolio === true,
           [SIZE_BY_SETTING_KEY]: heatmapSizeBy(context.settings[SIZE_BY_SETTING_KEY]),
+          [SESSION_BASIS_SETTING_KEY]: heatmapSessionBasis(context.settings[SESSION_BASIS_SETTING_KEY]),
+          [NAME_COUNT_SETTING_KEY]: String(heatmapNameCount(context.settings[NAME_COUNT_SETTING_KEY])),
         },
         fields: [
           {
@@ -725,6 +789,23 @@ export const marketHeatmapPlugin: GloomPlugin = {
             ],
             description: "Square root gives mid-size names room next to the largest. A portfolio is always sized by position value.",
           },
+          {
+            key: SESSION_BASIS_SETTING_KEY,
+            label: "Colour by",
+            type: "select",
+            options: [
+              { value: REGULAR_SESSION_BASIS, label: "Regular session" },
+              { value: "active-session", label: "Active session" },
+            ],
+            description: "Active session follows pre-market and after-hours trading. Regular session shows the regular session alone: its move while it trades, then its close and move until the next one opens.",
+          },
+          {
+            key: NAME_COUNT_SETTING_KEY,
+            label: "Names",
+            type: "select",
+            options: HEATMAP_NAME_COUNTS.map((count) => ({ value: String(count), label: `Top ${count}` })),
+            description: "How many of the largest names US Stocks draws, and US ETFs up to 160. Fewer names leave fewer in Other.",
+          },
           {
             key: "linkPortfolio",
             label: "Link to portfolio",

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

@@ -1,4 +1,7 @@
 import type { MarketHeatmapAsset } from "../../../api-client/market-discovery";
+import { formatShortDate } from "../../../utils/datetime-format";
+import { displayWidth } from "../../../utils/format";
+import { zonedDateKey, zonedDateTimeParts } from "../../../utils/zoned-date-time";
 
 /**
  * The board's grouping and move arithmetic, shared by the pane and the `fn HM`
@@ -13,14 +16,102 @@ type HeatmapMoveAsset = Pick<MarketHeatmapAsset, "symbol" | "hasChange" | "chang
 /**
  * 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`).
+ * pre-market or after-hours session it streams (`extendedSession`), or of the
+ * completed regular session its quote reports (`regularChangePercent`).
  */
-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)
+export function heatmapMove(
+  asset: Pick<MarketHeatmapAsset, "hasChange" | "changePercent" | "regularChangePercent"> & { extendedSession?: string },
+): number | null {
+  const moved = asset.hasChange || asset.extendedSession != null
+    || (typeof asset.regularChangePercent === "number" && Number.isFinite(asset.regularChangePercent));
+  return moved && typeof asset.changePercent === "number" && Number.isFinite(asset.changePercent)
     ? asset.changePercent
     : null;
 }
 
+/**
+ * What a market board's tiles are colored by. The active session, the
+ * default, follows an open pre-market or after-hours session; the regular
+ * session keeps the regular session's move through extended trading.
+ */
+export type HeatmapSessionBasis = "active-session" | "regular-session";
+
+/** A saved choice wins; a pane that never chose follows the active session. */
+export function heatmapSessionBasis(value: unknown): HeatmapSessionBasis {
+  return value === "regular-session" ? "regular-session" : "active-session";
+}
+
+/** How many of the largest names a market board asks for. */
+export const HEATMAP_NAME_COUNTS = [100, 150, 500] as const;
+export type HeatmapNameCount = typeof HEATMAP_NAME_COUNTS[number];
+
+/** A saved count, as the settings dialog stores it ("150") or as a number; anything else is the full 500. */
+export function heatmapNameCount(value: unknown): HeatmapNameCount {
+  const count = typeof value === "string" && value.trim() ? Number(value) : value;
+  return HEATMAP_NAME_COUNTS.find((option) => option === count) ?? 500;
+}
+
+/**
+ * A market board read by its regular session alone. Taken outside the regular
+ * session, a tile's move is that session's only when the server dates it as
+ * the completed session's (`regularChangePercent`); any other move there is
+ * from a session it does not name, so the tile shows none, and no price.
+ * Returns the same array when nothing changes.
+ */
+export function regularSessionHeatmapAssets<T extends Pick<MarketHeatmapAsset, "hasChange" | "price" | "regularChangePercent">>(
+  assets: readonly T[],
+  session: string | null | undefined,
+): readonly T[] {
+  if (session == null || session === "REGULAR") return assets;
+  let changed = false;
+  const next = assets.map((asset) => {
+    if (!asset.hasChange || (typeof asset.regularChangePercent === "number" && Number.isFinite(asset.regularChangePercent))) return asset;
+    changed = true;
+    return { ...asset, hasChange: false, price: 0 };
+  });
+  return changed ? next : assets;
+}
+
+const NEW_YORK = "America/New_York";
+const twoDigits = (value: number) => String(value).padStart(2, "0");
+/** A New York calendar day ("2026-10-09") as the footer names it: "Oct 9". */
+const dayLabel = (day: string) => formatShortDate(day, { year: false, utc: true, fallback: day });
+
+/**
+ * What a market board covers and when it is from, for the footer: how many of
+ * the largest names it holds, the completed regular session it shows outside
+ * that session, when the server put the snapshot together, in New York time,
+ * dated when that day is not the session's (or, while the session trades,
+ * today's), and when this client last checked, which is a separate figure.
+ * A footer narrower than `maxWidth` loses the check first, then the snapshot,
+ * then the session; after a failed refresh (`failed`) the age of the last good
+ * check outlasts the snapshot. Null when not even the count fits.
+ */
+export function heatmapBoardCaption(
+  board: { topCount: number; fetchedAt: number; regularSessionDate?: string | null },
+  { now, checked = null, failed = false, maxWidth = Number.POSITIVE_INFINITY }:
+    { now: number; checked?: string | null; failed?: boolean; maxWidth?: number },
+): string | null {
+  const sessionDate = board.regularSessionDate || null;
+  // Display order; `rank` is the order they give way in, highest first.
+  const parts: Array<{ text: string; rank: number }> = [{ text: `top ${board.topCount}`, rank: 0 }];
+  if (sessionDate) parts.push({ text: `${dayLabel(sessionDate)} session`, rank: 1 });
+  if (Number.isFinite(board.fetchedAt) && board.fetchedAt > 0) {
+    const { hour, minute } = zonedDateTimeParts(board.fetchedAt, NEW_YORK);
+    const clock = `${twoDigits(hour)}:${twoDigits(minute)} ET`;
+    const day = zonedDateKey(board.fetchedAt, NEW_YORK);
+    const text = `snapshot ${day === (sessionDate ?? zonedDateKey(now, NEW_YORK)) ? clock : `${dayLabel(day)} ${clock}`}`;
+    parts.push({ text, rank: failed ? 3 : 2 });
+  }
+  if (checked) parts.push({ text: `checked ${checked}`, rank: failed ? 2 : 3 });
+  const caption = () => parts.map((part) => part.text).join(" · ");
+  while (parts.length > 0 && displayWidth(caption()) > maxWidth) {
+    const weakest = parts.reduce((found, part, index) => (part.rank > parts[found]!.rank ? index : found), 0);
+    parts.splice(weakest, 1);
+  }
+  return parts.length > 0 ? caption() : null;
+}
+
 export type HeatmapGrouping = "sector-industry" | "sector" | "flat";
 
 /**

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

@@ -3,7 +3,12 @@ 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 {
+  getRegularSessionMoveDisplay,
+  getSessionMoveDisplay,
+  type ActiveQuoteDisplay,
+  type ExtendedSession,
+} from "../../../market-data/market/status";
 import type { TickerRecord } from "../../../types/ticker";
 import { getSortValue, type ColumnContext } from "../portfolio-list/metrics";
 
@@ -195,6 +200,7 @@ export function buildPortfolioHeatmapAssets({
   currency,
   exchangeRates,
   sizeBy = "sqrt-market-cap",
+  regularSession = false,
 }: {
   tickers: readonly TickerRecord[];
   financials: ReadonlyMap<string, TickerFinancials>;
@@ -204,6 +210,8 @@ export function buildPortfolioHeatmapAssets({
   currency: string;
   exchangeRates: Map<string, number>;
   sizeBy?: HeatmapSizeBy;
+  /** Color by the regular session alone, never an extended print (`getRegularSessionMoveDisplay`). */
+  regularSession?: boolean;
 }): { assets: HeatmapBoardAsset[]; omitted: number } {
   const context: ColumnContext = {
     activeTab: kind === "portfolio" ? collectionId : undefined,
@@ -217,7 +225,9 @@ export function buildPortfolioHeatmapAssets({
     const snapshot = financials.get(symbol);
     const quote = snapshot?.quote;
     // Colored like the market boards: an open extended session's move, else the regular session's.
-    const display = getSessionMoveDisplay(quote);
+    const display: (ActiveQuoteDisplay & { session?: ExtendedSession }) | null = regularSession
+      ? getRegularSessionMoveDisplay(quote)
+      : getSessionMoveDisplay(quote);
     const price = display != null && Number.isFinite(display.price) ? display.price : null;
     const size = positiveNumber(getSortValue(sizeColumn, ticker, snapshot, context));
     const hasChange = display?.changePercent != null && Number.isFinite(display.changePercent);

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

@@ -10,14 +10,18 @@ import type {
   CloudSessionMoversSide,
 } from "../../../api-client/market-movers";
 import { loadMarketMoverTab, loadSessionMovers, type MarketMoverTabResult } from "./client";
-import { createRows, fiftyTwoWeekPositionPercent, formatMoverPrice, moverReferencePrice, type MarketMoverRow, type ScreenerTabId, type TabId } from "./model";
+import { createRows, fiftyTwoWeekPositionPercent, formatMoverPrice, moverExtendedSessions, moverReferencePrice, type MarketMoverRow, type ScreenerTabId, type TabId } from "./model";
+import { EXTENDED_SESSION_LABELS, type ExtendedSession } from "../../../market-data/market/status";
+import type { HeadlessPaneColumn } from "../../../types/headless";
 import { isSessionTab, resolveSide } from "./session";
 
-const COLUMNS = [
+const rowPrice = (value: unknown, row: Record<string, unknown>) => formatMoverPrice(typeof value === "number" ? value : null, typeof row.currency === "string" ? row.currency : "", moverReferencePrice(row as unknown as MarketMoverRow));
+
+const COLUMNS: HeadlessPaneColumn[] = [
   { key: "rank", header: "Rank", align: "right" as const },
   { key: "symbol", header: "Symbol" },
   { key: "name", header: "Name" },
-  { key: "price", header: "Last", align: "right" as const, format: (value: unknown, row: Record<string, unknown>) => formatMoverPrice(typeof value === "number" ? value : null, typeof row.currency === "string" ? row.currency : "", moverReferencePrice(row as unknown as MarketMoverRow)) },
+  { key: "price", header: "Last", align: "right" as const, format: rowPrice },
   { key: "changePercent", header: "Change %", align: "right" as const, format: (value: unknown) => value == null ? "—" : formatPercentRaw(Number(value)) },
   { key: "volume", header: "Volume", align: "right" as const, format: (value: unknown) => value == null ? "—" : formatCompact(Number(value), { fixedDecimals: true }) },
   { key: "volumeRatio", header: "Vol / Avg", align: "right" as const, format: (value: unknown) => value == null ? "—" : formatNumber(Number(value), 1) },
@@ -30,6 +34,19 @@ const percent = (value: unknown) => value == null ? "—" : formatPercentRaw(Num
 const ratio = (value: unknown) => value == null ? "—" : `${formatNumber(Number(value), 1)}x`;
 const compact = (value: unknown) => value == null ? "—" : formatCompact(Number(value), { fixedDecimals: true });
 const CATALYST_LABEL: Record<string, string> = { halt: "Halt", filing: "8-K", news: "News" };
+
+/** The pre-market or after-hours print and its move from the regular close, for the rows that have one. */
+function extendedColumn(session: ExtendedSession): HeadlessPaneColumn {
+  return {
+    key: "extendedPrice",
+    header: EXTENDED_SESSION_LABELS[session],
+    align: "right",
+    format: (value, row) => row.extendedSession === session && typeof value === "number"
+      ? `${rowPrice(value, row)} ${percent(row.extendedChangePercent)}`
+      : "—",
+  };
+}
+
 const SESSION_VOLUME: Record<CloudSessionMoversCategory, string> = {
   premarket: "Pre-market volume",
   afterhours: "After-hours volume",
@@ -131,8 +148,15 @@ export function createMarketMoversHeadless(
         };
       }
       const result = await dependencies.load(args, tab, ctx.marketData);
-      const rows = createRows(result.quotes).map((row) => ({
+      const ranked = createRows(result.quotes);
+      // Last and Change % are the regular session; an extended print is a column of its own.
+      const extendedSessions = moverExtendedSessions(ranked);
+      const rows = ranked.map(({ extended, ...row }) => ({
         ...row,
+        extendedSession: extended?.session ?? null,
+        extendedPrice: extended?.price ?? null,
+        extendedChange: extended?.change ?? null,
+        extendedChangePercent: extended?.changePercent ?? null,
         rangePositionPercent: fiftyTwoWeekPositionPercent(
           row.price,
           row.fiftyTwoWeekLow,
@@ -140,6 +164,9 @@ export function createMarketMoversHeadless(
         ),
       }));
       return {
+        ...(extendedSessions.length > 0
+          ? { columns: [...COLUMNS.slice(0, 5), ...extendedSessions.map(extendedColumn), ...COLUMNS.slice(5)] }
+          : {}),
         rows,
         metadata: { list: tab, source: result.source, stale: result.stale },
       };

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

@@ -25,6 +25,7 @@ import {
   INDEX_SHORT,
   TABS,
   createRows,
+  moverExtendedSessions,
   overlayMarketMoverQuotes,
   resolveSummarySymbols,
   resolveTabs,
@@ -42,6 +43,7 @@ import { isSessionTab, resolveActiveTab, usSessionAt, type UsSession } from "./s
 import { SessionMoversBody } from "./session-body";
 import { marketMoversHeadless } from "./headless";
 import { buildMarketMoverColumns, renderMarketMoverCell } from "./table";
+import type { ExtendedSession } from "../../../market-data/market/status";
 import {
   LIVE_STREAMING_QUICK_SETTING,
   useLiveStreamingSetting,
@@ -188,8 +190,13 @@ function ScreenerMoversBody({ activeTab, focused, width, summaryQuotes, liveStre
     }),
     [freshnessNow, liveQuoteEntries, quoteTargets, subscriptionStartedAt],
   );
-  const columns = useMemo(() => buildMarketMoverColumns(width), [width]);
   const rankedRows = useMemo(() => createRows(resolvedQuotes), [resolvedQuotes]);
+  // A pre-market or after-hours column only while a row has such a print.
+  const extendedSessionsKey = moverExtendedSessions(rankedRows).join(",");
+  const columns = useMemo(
+    () => buildMarketMoverColumns(width, extendedSessionsKey ? extendedSessionsKey.split(",") as ExtendedSession[] : []),
+    [extendedSessionsKey, width],
+  );
   const rows = useMemo(() => sortRows(rankedRows, sortPreference), [rankedRows, sortPreference]);
   const selectedIdx = selectedSymbol
     ? rows.findIndex((row) => moverKey(row) === selectedSymbol)