gloomberb 0.15.8 → 0.16.0

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

@@ -1,12 +1,13 @@
-import { Box, ScrollBox, Text, type InputRenderable, type ScrollBoxRenderable } from "../../../ui";
-import { useCallback, useMemo, useRef, useState } from "react";
+import { Box, ScrollBox, Text, TextAttributes, type InputRenderable, type ScrollBoxRenderable } from "../../../ui";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { PaneStatusBody, QueryBar, usePaneFooter, usePaneNoticeFooter } from "../../../components";
 import { handleRefreshKey } from "../../../components/data-table/table-pane";
+import { afterLayout } from "../../../components/ui/reveal-in-scroll-box";
 import type { PaneProps } from "../../../types/plugin";
 import type { PluginModule } from "../plugin-module";
 import { TICKER_RESEARCH_PANE_ID } from "../../../types/config";
 import { colors } from "../../../theme/colors";
-import { usePluginTickerActions } from "../../runtime";
+import { usePluginAppActions, usePluginTickerActions } from "../../runtime";
 import { useAppSelector, usePaneInstance, usePaneSettingValue } from "../../../state/app/context";
 import { useChartQueries } from "../../../market-data/hooks";
 import { getSharedMarketDataCoordinator } from "../../../market-data/coordinator";
@@ -45,12 +46,21 @@ import {
 } from "./matrix/model";
 import { SymbolLabelCell } from "./matrix/symbol-cell";
 import { correlationHeadless, relationshipHeadless } from "./headless";
+import { CORRELATION_HISTORY_RESOLUTION } from "./history";
+import { buildMatrixPairHistory, clampMatrixCursor, matrixChartRows, matrixSelection, moveMatrixCursor, type MatrixCursor } from "./matrix/selection";
+import { MatrixPairChart } from "./matrix/pair-chart";
 
 function CorrelationMatrixPane({ focused, width, height }: PaneProps) {
   const pane = usePaneInstance();
   const { navigateTicker, pinTicker } = usePluginTickerActions();
+  const { createPaneFromTemplate } = usePluginAppActions();
   const tickers = useAppSelector((state) => state.tickers);
-  const [hoveredSymbol, setHoveredSymbol] = useState<string | null>(null);
+  const [{ cursor: cellCursor, hoveredSymbol }, setCursorState] = useState<{ cursor: MatrixCursor; hoveredSymbol: string | null }>({
+    cursor: { row: 0, column: 1 }, hoveredSymbol: null,
+  });
+  const hoverSymbol = useCallback((symbol: string) => {
+    setCursorState((current) => ({ ...current, hoveredSymbol: symbol }));
+  }, []);
   const settings = useMemo(() => getCorrelationPaneSettings(pane?.settings), [pane?.settings]);
   const [rangePreset, setRangePreset] = usePaneSettingValue<CorrelationRangePreset>("rangePreset", settings.rangePreset);
   const [symbolsText, setSymbolsText] = usePaneSettingValue<string>("symbolsText", settings.symbolsText);
@@ -63,6 +73,7 @@ function CorrelationMatrixPane({ focused, width, height }: PaneProps) {
   // Remounts the query bar so the field drops the draft Esc threw away.
   const [queryBarRevision, setQueryBarRevision] = useState(0);
   const matrixScrollRef = useRef<ScrollBoxRenderable | null>(null);
+  const horizontalScrollRef = useRef<ScrollBoxRenderable | null>(null);
 
   const instruments = useMemo(() => {
     if (settings.symbolsError) return [];
@@ -85,7 +96,7 @@ function CorrelationMatrixPane({ focused, width, height }: PaneProps) {
       },
       bufferRange: settings.rangePreset,
       granularity: "resolution" as const,
-      resolution: "1d" as const,
+      resolution: CORRELATION_HISTORY_RESOLUTION,
     })),
     [instrumentKey, settings.rangePreset],
   );
@@ -106,6 +117,15 @@ function CorrelationMatrixPane({ focused, width, height }: PaneProps) {
 
   const symbols = instruments.map((instrument) => instrument.symbol);
   const symbolsKey = symbols.join(",");
+  const cursor = clampMatrixCursor(cellCursor, symbols.length);
+  const selection = matrixSelection(symbols, cursor);
+  const pair = selection && selection[0] !== selection[1] ? selection : null;
+  useEffect(() => {
+    setCursorState((current) => ({ ...current, cursor: clampMatrixCursor(current.cursor, symbols.length) }));
+  }, [symbolsKey]);
+  const pairHistory = useMemo(() => pair ? buildMatrixPairHistory(
+    seriesBySymbol.get(pair[0]), seriesBySymbol.get(pair[1]), settings.rangePreset,
+  ) : null, [pair?.[0], pair?.[1], seriesBySymbol, settings.rangePreset]);
 
   const matrix = useMemo(() => {
     return buildCorrelationMatrix(symbols, seriesBySymbol);
@@ -129,34 +149,31 @@ function CorrelationMatrixPane({ focused, width, height }: PaneProps) {
     navigateTicker(symbol);
   }, [navigateTicker, pinTicker, tickers]);
 
-  /** The row cursor shares the hover highlight, so mouse and keys point at one symbol. */
-  const moveSymbolCursor = useCallback((offset: -1 | 1) => {
+  /** Hovered symbols remain a keyboard starting point; Left reaches their row cursor. */
+  const moveCursor = (key: string) => {
     if (symbols.length === 0) return;
-    const index = hoveredSymbol ? symbols.indexOf(hoveredSymbol) : -1;
-    const next = index < 0
-      ? (offset > 0 ? 0 : symbols.length - 1)
-      : Math.max(0, Math.min(symbols.length - 1, index + offset));
-    setHoveredSymbol(symbols[next]!);
-    const scroll = matrixScrollRef.current;
-    if (!scroll) return;
-    const viewportHeight = Math.max(1, scroll.viewport?.height ?? 1);
-    if (next < scroll.scrollTop) scroll.scrollTo(next);
-    else if (next + 1 > scroll.scrollTop + viewportHeight) scroll.scrollTo(next + 1 - viewportHeight);
-  }, [hoveredSymbol, symbolsKey]);
+    setCursorState((current) => {
+      const hoveredRow = current.hoveredSymbol ? symbols.indexOf(current.hoveredSymbol) : -1;
+      const start = hoveredRow >= 0 ? { row: hoveredRow, column: -1 } : current.cursor;
+      return { cursor: moveMatrixCursor(start, key, symbols.length), hoveredSymbol: null };
+    });
+  };
 
   useShortcut((event) => {
     if (!focused || symbolsEditing || event.defaultPrevented) return;
     if (handleRefreshKey(event, refresh, { stopPropagation: true })) return;
-    if (isPlainKey(event, "j", "down", "k", "up")) {
+    if (isPlainKey(event, "j", "down", "k", "up", "h", "left", "l", "right")) {
       event.preventDefault();
       event.stopPropagation();
-      moveSymbolCursor(event.name === "j" || event.name === "down" ? 1 : -1);
-    } else if (isPlainKey(event, "return", "enter") && hoveredSymbol && symbols.includes(hoveredSymbol)) {
+      moveCursor(event.name ?? event.key ?? "");
+    } else if (isPlainKey(event, "return", "enter") && selection) {
       event.preventDefault();
       event.stopPropagation();
-      openSymbol(hoveredSymbol);
+      if (hoveredSymbol && symbols.includes(hoveredSymbol)) openSymbol(hoveredSymbol);
+      else if (pair) createPaneFromTemplate("relationship-graph-pane", { symbols: pair, arg: formatTickerListInput(pair) });
+      else openSymbol(selection[0]);
     }
-  });
+  }, { phase: "before", scope: "correlation:matrix" });
 
   // Esc cancels an edit of the list instead of clearing it: the field's own
   // Esc empties the draft, which would fall back to the default tickers.
@@ -177,7 +194,7 @@ function CorrelationMatrixPane({ focused, width, height }: PaneProps) {
     registrationId: "correlation-warnings", focused,
     notices: [...seriesBySymbol.values()].flatMap((series) => series.refreshError
       ? [`${series.symbol}: ${series.refreshError}${series.fetchedAt ? ` Retained history retrieved ${new Date(series.fetchedAt).toISOString()}.` : ""}`]
-      : []),
+      : []).concat(pair && pairHistory?.unavailable ? [`${pair.join("/")}: ${pairHistory.unavailable}`] : []),
   });
 
   // The ticker set and range are visible in-pane and an invalid list shows in
@@ -189,7 +206,7 @@ function CorrelationMatrixPane({ focused, width, height }: PaneProps) {
   }), [settings.symbolsError, statusSummary, symbols.length]);
 
   const clearHoveredSymbol = useCallback((symbol: string) => {
-    setHoveredSymbol((current) => (current === symbol ? null : current));
+    setCursorState((current) => current.hoveredSymbol === symbol ? { ...current, hoveredSymbol: null } : current);
   }, []);
 
   const headerBg = colors.panel;
@@ -203,6 +220,27 @@ function CorrelationMatrixPane({ focused, width, height }: PaneProps) {
   // Rows are exactly as wide as the matrix (after the one-cell inset), so the
   // zebra and hover bands stop at the last column instead of running on.
   const matrixRowWidth = 1 + rowHeaderWidth + symbols.length * cellWidth;
+  const chartRows = pair ? matrixChartRows(width, height, symbols.length, matrixRowWidth) : 0;
+  const matrixHeight = Math.max(1, height - 1 - (chartRows > 0 ? chartRows + 1 : 0));
+  const horizontalBarRows = matrixRowWidth > width - 1 ? 1 : 0;
+
+  // Scroll after React commits a movement, including several keys in one input batch.
+  useEffect(() => afterLayout(() => {
+    const scroll = matrixScrollRef.current;
+    if (scroll) {
+      const viewportHeight = Math.max(1, scroll.viewport?.height ?? 1);
+      if (cursor.row < scroll.scrollTop) scroll.scrollTo(cursor.row);
+      else if (cursor.row + 1 > scroll.scrollTop + viewportHeight) scroll.scrollTo(cursor.row + 1 - viewportHeight);
+    }
+    const horizontal = horizontalScrollRef.current;
+    if (!horizontal) return;
+    const left = cursor.column < 0 ? 0 : 1 + rowHeaderWidth + cursor.column * cellWidth;
+    const right = left + (cursor.column < 0 ? rowHeaderWidth : cellWidth);
+    const scrollLeft = horizontal.scrollLeft ?? 0;
+    const viewportWidth = horizontal.viewport?.width || width;
+    if (left < scrollLeft) horizontal.scrollTo({ x: left, y: 0 });
+    else if (right > scrollLeft + viewportWidth) horizontal.scrollTo({ x: right - viewportWidth, y: 0 });
+  }), [cursor.row, cursor.column, matrixHeight, rowHeaderWidth, cellWidth, width]);
   const bodyStatus = settings.symbolsError
     ? <PaneStatusBody error={settings.symbolsError} />
     : symbols.length < 2
@@ -210,7 +248,7 @@ function CorrelationMatrixPane({ focused, width, height }: PaneProps) {
       : null;
 
   return (
-    <Box flexDirection="column" width={width} height={height}>
+    <Box flexDirection="column" width={width} height={height} overflow="hidden">
       <QueryBar
         key={queryBarRevision}
         width={width}
@@ -243,67 +281,88 @@ function CorrelationMatrixPane({ focused, width, height }: PaneProps) {
       />
       {bodyStatus ?? (
         <>
-          {/* Column header row */}
-          <Box flexDirection="row" paddingLeft={1} height={1} width={matrixRowWidth} backgroundColor={headerBg}>
-            <Box width={rowHeaderWidth} flexShrink={0} />
-            {symbols.map((sym) => (
-              <SymbolLabelCell
-                key={sym}
-                symbol={sym}
-                width={cellWidth}
-                align="flex-end"
-                color={colors.textDim}
-                hovered={hoveredSymbol === sym}
-                onHover={setHoveredSymbol}
-                onLeave={clearHoveredSymbol}
-                onOpen={openSymbol}
-              />
-            ))}
-          </Box>
+          <ScrollBox ref={horizontalScrollRef} height={matrixHeight} flexShrink={1} minHeight={Math.min(matrixHeight, symbols.length + 1, 5)} scrollX scrollY={false} focusable={false}>
+            <Box flexDirection="column" width={Math.max(width - 1, matrixRowWidth)} height={matrixHeight - horizontalBarRows}>
+              {/* Column header row */}
+              <Box flexDirection="row" paddingLeft={1} height={1} flexShrink={0} width={matrixRowWidth} backgroundColor={headerBg}>
+                <Box width={rowHeaderWidth} flexShrink={0} />
+                {symbols.map((sym) => (
+                  <SymbolLabelCell
+                    key={sym}
+                    symbol={sym}
+                    width={cellWidth}
+                    align="flex-end"
+                    color={colors.textDim}
+                    hovered={hoveredSymbol === sym || selection?.[1] === sym}
+                    onHover={hoverSymbol}
+                    onLeave={clearHoveredSymbol}
+                    onOpen={openSymbol}
+                  />
+                ))}
+              </Box>
 
-          {/* Matrix rows */}
-          <ScrollBox ref={matrixScrollRef} flexGrow={1} scrollY scrollX focusable={false}>
-            <Box flexDirection="column">
-              {symbols.map((rowSym, rowIndex) => (
-                <Box key={rowSym} flexDirection="row" paddingLeft={1} width={matrixRowWidth} backgroundColor={rowIndex % 2 === 0 ? colors.bg : undefined}>
-                  {/* Row header */}
-                  <Box
-                    width={rowHeaderWidth}
-                    flexShrink={0}
-                    overflow="hidden"
-                  >
-                    <SymbolLabelCell
-                      symbol={rowSym}
-                      width={rowHeaderWidth}
-                      color={rowHeaderColor(seriesBySymbol.get(rowSym)?.status ?? "loading")}
-                      hovered={hoveredSymbol === rowSym}
-                      onHover={setHoveredSymbol}
-                      onLeave={clearHoveredSymbol}
-                      onOpen={openSymbol}
-                    />
-                  </Box>
-                  {/* Cells */}
-                  {symbols.map((colSym) => {
-                    const r = matrix.results.get(pairKey(rowSym, colSym))?.correlation ?? null;
-                    const cellColors = resolveHeatCellColors(r, { quiet: rowSym === colSym });
-                    const text = formatCorrelation(r);
-                    return (
+              {/* Matrix rows */}
+              <ScrollBox ref={matrixScrollRef} flexGrow={1} flexBasis={0} minHeight={0} scrollY scrollX={false} focusable={false}>
+                <Box flexDirection="column">
+                  {symbols.map((rowSym, rowIndex) => (
+                    <Box key={rowSym} flexDirection="row" paddingLeft={1} width={matrixRowWidth} backgroundColor={rowIndex % 2 === 0 ? colors.bg : undefined}>
+                      {/* Row header */}
                       <Box
-                        key={colSym}
-                        width={cellWidth}
-                        flexDirection="row"
-                        justifyContent="flex-end"
-                        paddingRight={1}
-                        backgroundColor={cellColors.background}
+                        width={rowHeaderWidth}
+                        flexShrink={0}
+                        overflow="hidden"
                       >
-                        <Text fg={cellColors.foreground}>{text}</Text>
+                        <SymbolLabelCell
+                          symbol={rowSym}
+                          width={rowHeaderWidth}
+                          color={rowHeaderColor(seriesBySymbol.get(rowSym)?.status ?? "loading")}
+                          hovered={hoveredSymbol === rowSym || selection?.[0] === rowSym}
+                          onHover={hoverSymbol}
+                          onLeave={clearHoveredSymbol}
+                          onOpen={openSymbol}
+                        />
                       </Box>
-                    );
-                  })}
+                      {/* Cells */}
+                      {symbols.map((colSym, colIndex) => {
+                        const r = matrix.results.get(pairKey(rowSym, colSym))?.correlation ?? null;
+                        const cellColors = resolveHeatCellColors(r, { quiet: rowSym === colSym });
+                        const text = formatCorrelation(r);
+                        const selected = cursor.row === rowIndex && cursor.column === colIndex;
+                        return (
+                          <Box
+                            key={colSym}
+                            width={cellWidth}
+                            flexShrink={0}
+                            flexDirection="row"
+                            justifyContent="flex-end"
+                            paddingRight={1}
+                            backgroundColor={cellColors.background}
+                            style={{ cursor: "pointer" }}
+                            onMouseDown={(event: any) => {
+                              event.preventDefault?.();
+                              event.stopPropagation?.();
+                              setCursorState({ cursor: { row: rowIndex, column: colIndex }, hoveredSymbol: null });
+                            }}
+                          >
+                            <Text fg={cellColors.foreground} attributes={selected ? TextAttributes.BOLD | TextAttributes.UNDERLINE : TextAttributes.NONE}>{text}</Text>
+                          </Box>
+                        );
+                      })}
+                    </Box>
+                  ))}
                 </Box>
-              ))}
+              </ScrollBox>
             </Box>
           </ScrollBox>
+          {chartRows > 0 && pair && pairHistory ? (
+            <MatrixPairChart
+              pair={pair}
+              history={pairHistory}
+              fullPeriod={matrix.results.get(pairKey(...pair))?.correlation ?? null}
+              width={width}
+              height={chartRows}
+            />
+          ) : null}
         </>
       )}
     </Box>

package/src/plugins/builtin/correlation/matrix/pair-chart.tsx

@@ -0,0 +1,48 @@
+import { useMemo } from "react";
+import { CompositeChart } from "../../../../components";
+import { scalarPoint, staticSeries } from "../../../../components/chart/static/series";
+import { colors } from "../../../../theme/colors";
+import { Box, Text } from "../../../../ui";
+import type { buildMatrixPairHistory } from "./selection";
+import { matrixPairRead } from "./selection";
+
+const PANELS = [{ id: "main" }];
+const formatValue = (value: number) => value.toFixed(2);
+
+export function MatrixPairChart({ pair, history, fullPeriod, width, height }: {
+  pair: [string, string];
+  history: ReturnType<typeof buildMatrixPairHistory>;
+  fullPeriod: number | null;
+  width: number;
+  height: number;
+}) {
+  const series = useMemo(() => [
+    staticSeries(history.points.map(({ date, value }) => scalarPoint(date, value)), {
+      id: "rolling", label: `${pair[0]}/${pair[1]} (${history.window} day)`, color: "#f6c85f",
+    }),
+    staticSeries(history.points.map(({ date }) => scalarPoint(date, fullPeriod)), {
+      id: "full-period", label: "Full period", color: colors.textDim,
+    }),
+  ], [history, pair[0], pair[1], fullPeriod]);
+  return (
+    <Box flexDirection="column" flexGrow={1} flexBasis={0} minHeight={0} overflow="hidden">
+      <Box flexGrow={1} flexBasis={0} minHeight={0} overflow="hidden">
+        <CompositeChart
+          series={series}
+          panels={PANELS}
+          width={width}
+          height={height}
+          focused={false}
+          navigable={false}
+          showTimeAxis
+          formatAxisValue={formatValue}
+          formatValue={formatValue}
+          emptyMessage={history.unavailable ?? "No paired history"}
+        />
+      </Box>
+      <Box paddingX={1} height={1} flexShrink={0} overflow="hidden">
+        <Text fg={colors.textMuted} wrapMode="none">{matrixPairRead(pair, fullPeriod, history)}</Text>
+      </Box>
+    </Box>
+  );
+}

package/src/plugins/builtin/correlation/matrix/selection.ts

@@ -0,0 +1,77 @@
+import { chartTableLayout } from "../../../../components/chart-table/layout";
+import { alignDailyCloses } from "../compute";
+import { buildRelationshipReturns, buildRollingCorrelationPoints } from "../relationship/model";
+import type { CorrelationRangePreset } from "../settings";
+import type { CorrelationSeries } from "./model";
+
+/** Column -1 is the existing symbol-row cursor, reachable from the first cell. */
+export interface MatrixCursor { row: number; column: number }
+
+export function clampMatrixCursor(cursor: MatrixCursor, count: number): MatrixCursor {
+  const last = Math.max(0, count - 1);
+  return {
+    row: Math.max(0, Math.min(last, cursor.row)),
+    column: Math.max(-1, Math.min(last, cursor.column)),
+  };
+}
+
+export function moveMatrixCursor(cursor: MatrixCursor, key: string, count: number): MatrixCursor {
+  const next = clampMatrixCursor(cursor, count);
+  if (key === "j" || key === "down") next.row++;
+  if (key === "k" || key === "up") next.row--;
+  if (key === "h" || key === "left") next.column--;
+  if (key === "l" || key === "right") next.column++;
+  return clampMatrixCursor(next, count);
+}
+
+export function matrixSelection(symbols: readonly string[], cursor: MatrixCursor): [string, string] | null {
+  if (!symbols.length) return null;
+  const { row, column } = clampMatrixCursor(cursor, symbols.length);
+  return [symbols[row]!, symbols[column < 0 ? row : column]!];
+}
+
+/** The kit budget includes the read line. No compact strip: the matrix wins. */
+export function matrixChartRows(width: number, height: number, count: number, matrixWidth: number): number {
+  const layout = chartTableLayout({
+    width, height, queryRows: 1, tableRows: count,
+    tableChromeRows: matrixWidth > width - 1 ? 2 : 1,
+    chart: { minRows: 7, strip: false },
+  });
+  return layout.mode === "full" ? layout.chartRows - 1 : 0;
+}
+
+export function buildMatrixPairHistory(
+  left: CorrelationSeries | undefined,
+  right: CorrelationSeries | undefined,
+  range: CorrelationRangePreset,
+) {
+  const window = range === "1M" ? 20 : 60;
+  const aligned = alignDailyCloses(left?.prices ?? [], right?.prices ?? []).map((point) => ({
+    ...point, date: new Date(`${point.dateKey}T00:00:00Z`),
+  }));
+  const returns = buildRelationshipReturns(aligned);
+  const points = buildRollingCorrelationPoints(returns, window);
+  const byTime = new Map(points.map((point) => [point.date.getTime(), point.close]));
+  const values = points.map((point) => point.close);
+  const latest = byTime.get(returns.at(-1)?.date.getTime() ?? NaN) ?? null;
+  return {
+    window,
+    // Explicit gaps retain the warm-up period and zero-variance windows.
+    points: aligned.map(({ date }) => ({ date, value: byTime.get(date.getTime()) ?? null })),
+    latest,
+    min: values.length ? Math.min(...values) : null,
+    max: values.length ? Math.max(...values) : null,
+    unavailable: returns.length < window
+      ? `Rolling correlation needs ${window} shared returns; ${returns.length} available.`
+      : latest === null ? `Rolling correlation unavailable: zero return variance in the latest ${window} shared returns.` : null,
+  };
+}
+
+export function matrixPairRead(
+  pair: readonly [string, string],
+  fullPeriod: number | null,
+  history: Pick<ReturnType<typeof buildMatrixPairHistory>, "window" | "latest" | "min" | "max">,
+): string {
+  const value = (number: number | null) => number !== null && Number.isFinite(number) ? number.toFixed(2) : "—";
+  return `${pair[0]} and ${pair[1]}: full period ${value(fullPeriod)}, now ${value(history.latest)} (${history.window} day), range ${value(history.min)} to ${value(history.max)}`;
+}

package/src/plugins/builtin/correlation/relationship/model.ts

@@ -72,7 +72,7 @@ function alignRelationshipPrices(leftPoints: PricePoint[], rightPoints: PricePoi
   }));
 }
 
-function buildRelationshipReturns(aligned: RelationshipAlignedPoint[]): RelationshipReturnPoint[] {
+export function buildRelationshipReturns(aligned: readonly Omit<RelationshipAlignedPoint, "ratio">[]): RelationshipReturnPoint[] {
   const returns: RelationshipReturnPoint[] = [];
   for (let index = 1; index < aligned.length; index++) {
     const previous = aligned[index - 1]!;
@@ -91,7 +91,7 @@ function buildRelationshipReturns(aligned: RelationshipAlignedPoint[]): Relation
   return returns;
 }
 
-function buildRollingCorrelationPoints(
+export function buildRollingCorrelationPoints(
   returns: RelationshipReturnPoint[],
   windowSize: number,
 ): ProjectedChartPoint[] {

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

@@ -0,0 +1,66 @@
+import { apiClient } from "../../../api-client";
+import type { CpiBoardPayload, CpiRow } from "../../../api-client/cpi";
+import { ApiRequestError } from "../../../api-client/errors";
+import { createPluginCache } from "../../../data/plugin-cache";
+import { cachedCloudResource, loadCloudResource } from "../shared/cloud-resource";
+
+/** What the pane says while the server has no months to serve: before the backend ships, or before its first read. */
+export const CPI_NOT_AVAILABLE = "US consumer prices are not available yet.";
+
+export const cpiBoardCache = createPluginCache<CpiBoardPayload>({
+  kind: "cpi-board", source: "gloom-cloud", schemaVersion: 1,
+  // Monthly data: a quarter hour is soon enough to catch a release.
+  policy: { staleMs: 15 * 60_000, expireMs: 45 * 24 * 60 * 60_000 },
+});
+
+const month = (value: unknown) => typeof value === "string" && /^\d{4}-(0[1-9]|1[0-2])$/.test(value);
+const monthOrNull = (value: unknown) => value === null || month(value);
+const instantOrNull = (value: unknown) => value === null || typeof value === "string" && Number.isFinite(Date.parse(value));
+const finite = (value: unknown): value is number => typeof value === "number" && Number.isFinite(value);
+const finiteOrNull = (value: unknown) => value === null || finite(value);
+
+function validRow(row: CpiRow): boolean {
+  return typeof row.id === "string" && typeof row.label === "string" && Number.isInteger(row.depth) && row.depth >= 0
+    && (row.code === null || typeof row.code === "string") && (row.parent === null || typeof row.parent === "string")
+    && typeof row.pinned === "boolean" && typeof row.derived === "boolean"
+    && [row.weight, row.change, row.annualized3m, row.annualized6m, row.yoy, row.contribution, row.contributionYoy].every(finiteOrNull)
+    && (row.read === null || typeof row.read === "string")
+    && Array.isArray(row.history) && row.history.every((point) => Array.isArray(point) && month(point[0])
+      && finiteOrNull(point[1]) && finiteOrNull(point[2]));
+}
+
+/** A board that breaks the contract is refused whole rather than drawn with holes in it. */
+function validateCpiBoard(payload: CpiBoardPayload): CpiBoardPayload {
+  const release = payload?.release;
+  if (!payload || payload.source !== "BLS" || !Number.isFinite(Date.parse(payload.generatedAt))
+    || !instantOrNull(payload.retrievedAt ?? null)
+    || !["available", "partial", "unavailable"].includes(payload.status)
+    || !Array.isArray(payload.gaps) || !payload.gaps.every((gap) => typeof gap === "string")
+    || !release || !monthOrNull(release.period) || !monthOrNull(release.weightsPeriod) || !monthOrNull(release.nextPeriod)
+    || !instantOrNull(release.releasedAt) || !instantOrNull(release.nextReleaseAt)
+    || !Array.isArray(payload.rows) || new Set(payload.rows.map((row) => row.id)).size !== payload.rows.length
+    || !payload.rows.every(validRow)) {
+    throw new Error("The server returned an invalid consumer price board");
+  }
+  return payload;
+}
+
+/**
+ * The board, or the not-available message when the server does not serve the
+ * route yet (404), cannot read its tables yet (503) or has no months stored.
+ */
+export async function fetchCpiBoard(client: Pick<typeof apiClient, "getCloudCpiBoard"> = apiClient): Promise<CpiBoardPayload> {
+  let payload: CpiBoardPayload;
+  try {
+    payload = await client.getCloudCpiBoard();
+  } catch (error) {
+    if (error instanceof ApiRequestError && (error.status === 404 || error.status === 503)) throw new Error(CPI_NOT_AVAILABLE);
+    throw error;
+  }
+  const board = validateCpiBoard(payload);
+  if (board.status === "unavailable" || !board.release.period || !board.rows.length) throw new Error(CPI_NOT_AVAILABLE);
+  return board;
+}
+
+export const getCachedCpiBoard = () => cachedCloudResource(cpiBoardCache, "board", validateCpiBoard);
+export const loadCpiBoard = (force = false) => loadCloudResource(cpiBoardCache, "board", () => fetchCpiBoard(), { force, validate: validateCpiBoard });

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

@@ -0,0 +1,78 @@
+import type { CpiRow } from "../../../api-client/cpi";
+import type { HeadlessPaneDefinition } from "../../../types/plugin";
+import { fetchCpiBoard } from "./client";
+import { cpiHeaderLine, cpiMonth, cpiRowOption, cpiRows } from "./model";
+
+/** Two decimals; a value that rounds to zero reads 0.00, never -0.00. */
+const percent = (value: unknown) => typeof value === "number" ? (Number(value.toFixed(2)) === 0 ? "0.00" : value.toFixed(2)) : "--";
+const weight = (value: unknown) => typeof value === "number" ? value.toFixed(3) : "--";
+const text = (value: unknown) => typeof value === "string" ? value : "--";
+
+/** One row per component in the release's order; numbers stay raw for JSON, rounded for text. */
+function reportRow(row: CpiRow, indent = true) {
+  return {
+    id: row.id, component: `${indent ? "  ".repeat(row.depth) : ""}${row.label}`, depth: row.depth, weight: row.weight, monthChange: row.change,
+    annualized3m: row.annualized3m, annualized6m: row.annualized6m, yearChange: row.yoy,
+    contributionMonth: row.contribution, contributionYear: row.contributionYoy, read: row.read,
+  };
+}
+
+const SUMMARY_COLUMNS = [
+  { key: "component", header: "Component" },
+  { key: "weight", header: "Weight %", align: "right" as const, format: weight },
+  { key: "monthChange", header: "M/M % SA", align: "right" as const, format: percent },
+  { key: "annualized3m", header: "3M ann %", align: "right" as const, format: percent },
+  { key: "annualized6m", header: "6M ann %", align: "right" as const, format: percent },
+  { key: "yearChange", header: "Y/Y % NSA", align: "right" as const, format: percent },
+  { key: "contributionMonth", header: "M/M pts", align: "right" as const, format: percent },
+  { key: "contributionYear", header: "Y/Y pts", align: "right" as const, format: percent },
+];
+
+/** The selected row's months against the headline's year over year: the chart as a table. */
+function historyRows(row: CpiRow, headline: CpiRow | null) {
+  const headlineYear = new Map((headline?.history ?? []).map(([month, , yoy]) => [month, yoy]));
+  return [...row.history].reverse().map(([month, change, yoy]) => ({
+    month, monthChange: change, yearChange: yoy, headlineYearChange: headlineYear.get(month) ?? null,
+  }));
+}
+
+/** `CPI` reads every component; a component argument adds its monthly history. */
+export const cpiHeadless: HeadlessPaneDefinition<"bundle"> = {
+  shape: "bundle",
+  argument: { kind: "free-text", optional: true, placeholder: "component", description: "A component such as shelter, core, gasoline or supercore; omit for the table." },
+  options: [],
+  discovery: { aliases: ["CPI", "ECAN"], dataRequirements: ["Gloom Cloud US consumer price history"],
+    limitations: ["Monthly data, published by BLS at 08:30 ET on its release schedule",
+      "Weights and contributions are BLS's for the month; services ex shelter is computed from two BLS series",
+      "No October 2025 index was published, so changes that need it are empty"] },
+  describe: "US consumer prices by component",
+  async load(args) {
+    const data = await fetchCpiBoard();
+    const header = cpiHeaderLine(data.release) ?? "US consumer prices";
+    const headline = data.rows.find((row) => row.code === "SA0") ?? null;
+    const argument = Array.isArray(args.argument) ? args.argument.join(" ") : args.argument;
+    const metadata = { ...data, complete: data.status === "available" };
+    if (argument) {
+      const option = cpiRowOption(argument);
+      const row = option ? data.rows.find((entry) => entry.id === option.value) : null;
+      if (!row) throw new Error("Use a component such as shelter, core, gasoline or supercore");
+      return {
+        sections: [
+          { title: header, columns: [...SUMMARY_COLUMNS, { key: "read", header: "Read", format: text }], rows: [reportRow(row, false)] },
+          { title: `${row.label} by month to ${data.release.period ? cpiMonth(data.release.period) : "date"}`,
+            columns: [{ key: "month", header: "Month" }, { key: "monthChange", header: "M/M % SA", align: "right" as const, format: percent },
+              { key: "yearChange", header: "Y/Y % NSA", align: "right" as const, format: percent },
+              ...(headline && headline.id !== row.id ? [{ key: "headlineYearChange", header: "All items Y/Y %", align: "right" as const, format: percent }] : [])],
+            rows: historyRows(row, headline) },
+        ],
+        errors: data.gaps,
+        metadata: { ...metadata, rows: [row] },
+      };
+    }
+    return {
+      sections: [{ title: header, columns: SUMMARY_COLUMNS, rows: cpiRows(data).map((row) => reportRow(row)) }],
+      errors: data.gaps,
+      metadata,
+    };
+  },
+};

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

@@ -0,0 +1,31 @@
+import type { PaneTemplateCreateOptions, PaneTemplateInstanceConfig } from "../../../types/plugin";
+import type { PluginModule } from "../plugin-module";
+import { cpiBoardCache } from "./client";
+import { cpiHeadless } from "./headless";
+import { CPI_ROW_OPTIONS, cpiRowOption } from "./model";
+import { CpiPane } from "./pane";
+
+/** Opens on the table, or on the component typed after the mnemonic. */
+function cpiInstance(options?: PaneTemplateCreateOptions): PaneTemplateInstanceConfig {
+  const input = options?.arg?.trim();
+  const row = cpiRowOption(input);
+  if (input && !row) throw new Error("Use a component such as shelter, core, gasoline or supercore");
+  return { placement: "floating", ...(row ? { params: { row: row.value } } : {}) };
+}
+
+export const cpiModule: PluginModule = {
+  panes: [{ id: "cpi", name: "US Consumer Prices", icon: "C", component: CpiPane,
+    defaultPosition: "right", defaultMode: "floating", defaultFloatingSize: { width: 100, height: 36 },
+    tableExport: true, headless: cpiHeadless }],
+  paneTemplates: [{
+    id: "cpi-pane", paneId: "cpi", label: "US Consumer Prices",
+    description: "The US consumer price index by component: weights, monthly, annualised and yearly changes, and contributions to the headline.",
+    keywords: ["cpi", "ecan", "inflation", "consumer prices", "bls", "core", "shelter", "supercore", "rent", "gasoline"],
+    shortcut: { prefix: "CPI", aliases: ["ECAN"], argKind: "text", argPlaceholder: "component", argOptional: true,
+      argOptions: () => CPI_ROW_OPTIONS.map(({ value, label }) => ({ value, label })) },
+    headless: cpiHeadless,
+    createInstance: (_context, options) => cpiInstance(options),
+  }],
+  setup(ctx) { cpiBoardCache.attach(ctx.persistence); },
+  dispose() { cpiBoardCache.reset(); },
+};