gloomberb 0.16.4 → 0.16.6

package/src/plugins/builtin/power/prices-headless.ts

@@ -0,0 +1,137 @@
+import { apiClient } from "../../../api-client";
+import type { CarbonBoard, EuropePowerBoard, PowerPriceRow } from "../../../api-client/europe-energy";
+import type { HeadlessBundleResult, HeadlessBundleSection, HeadlessPaneColumn, HeadlessPaneDefinition } from "../../../types/plugin";
+import { fetchCarbonPrice, fetchPowerPriceHistory, fetchPowerPrices } from "./prices-client";
+import {
+  CARBON_PRICE_UNIT, formatPowerChange, formatPowerPrice, isCarbonQuery, POWER_PRICE_UNIT, powerPriceMarket, powerRangePosition,
+} from "./prices-model";
+
+type PricesClient = Pick<typeof apiClient, "getCloudEuropePower" | "getCloudEuropePowerHistory" | "getCloudEuropeCarbon">;
+
+const price = (value: unknown) => typeof value === "number" ? formatPowerPrice(value) : "--";
+const text = (value: unknown) => typeof value === "string" && value ? value : "--";
+
+/** A board's columns, in its words: prices to the cent in the board's unit, each row dated by its own day. */
+const boardColumns = (unit: string, label = "Market"): HeadlessPaneColumn[] => [
+  { key: "market", header: label },
+  { key: "date", header: "As of", format: text, shrink: false },
+  { key: "price", header: unit, align: "right", format: price },
+  { key: "change", header: "1D", align: "right", format: (value) => typeof value === "number" ? formatPowerChange(value) : "--" },
+  { key: "average7", header: "7D avg", align: "right", format: price },
+  { key: "average30", header: "30D avg", align: "right", format: price },
+  { key: "yearAgo", header: "1Y ago", align: "right", format: price },
+  { key: "low52w", header: "52W low", align: "right", format: price },
+  { key: "high52w", header: "52W high", align: "right", format: price },
+  { key: "range", header: "In 1Y range", align: "right", format: (value) => typeof value === "number" ? `${value}%` : "--" },
+];
+const COLUMNS = boardColumns(POWER_PRICE_UNIT);
+const AUCTION_COLUMNS: HeadlessPaneColumn[] = [
+  { key: "date", header: "Date", shrink: false },
+  { key: "zone", header: "Zone", format: text },
+  { key: "status", header: "Status" },
+  { key: "price", header: CARBON_PRICE_UNIT, align: "right", format: price },
+  { key: "volume", header: "Volume tCO2", align: "right", format: (value) => typeof value === "number" ? value.toLocaleString("en-US") : "--" },
+  { key: "coverRatio", header: "Cover", align: "right", format: (value) => typeof value === "number" ? `${value.toFixed(2)}x` : "--" },
+  { key: "bidders", header: "Bidders", align: "right", format: (value) => typeof value === "number" ? String(value) : "--" },
+];
+
+function reportRow(row: Omit<PowerPriceRow, "code"> & { code: string }) {
+  const { trail: _trail, name, ...figures } = row;
+  return { market: name, ...figures, range: powerRangePosition(row as PowerPriceRow) };
+}
+
+/** The EUA as of its latest auction day, then its latest general-allowance auctions. */
+function carbonSections(carbon: CarbonBoard): HeadlessBundleSection[] {
+  const { volume: _volume, auctions: _auctions, ...row } = carbon.row;
+  return [
+    { title: `EU carbon allowance (EUA) auction price, ${CARBON_PRICE_UNIT}`, columns: boardColumns(CARBON_PRICE_UNIT, "Allowance"), rows: [reportRow(row)] },
+    { title: "Latest EUA auctions", columns: AUCTION_COLUMNS,
+      rows: carbon.auctions.filter((auction) => !auction.aviation).map(({ aviation: _aviation, ...auction }) => ({ ...auction })) },
+  ];
+}
+
+/**
+ * The delivery day most markets have reached: the median market's latest
+ * day. A few markets publish ahead of the rest (Ireland the day before, most
+ * of the continent four days behind), so the freshest one would understate
+ * how far behind the board is.
+ */
+function typicalPowerDate(rows: readonly Pick<PowerPriceRow, "date">[]): string | null {
+  const dates = rows.flatMap((row) => row.date ? [row.date] : []).sort();
+  return dates[Math.floor((dates.length - 1) / 2)] ?? null;
+}
+
+/**
+ * One short line, the same in the report, the pane and a capture: the board
+ * is dated by the day most markets have reached and lags from it (`most
+ * markets 2026-10-07 · lag 4 days`); one market by its own delivery day; the
+ * EUA alone by its last auction.
+ */
+function freshness(board: EuropePowerBoard | null, carbon: CarbonBoard | null, market?: PowerPriceRow): HeadlessBundleResult["freshness"] {
+  const asOf = market ? market.date : board ? typicalPowerDate(board.rows) : carbon?.row.date ?? null;
+  return {
+    source: [board?.source.name, carbon?.source.name].filter(Boolean).join(", "),
+    asOf, oldest: null,
+    observation: market ? "delivery day" : board ? "most markets" : "last auction",
+    status: "not-a-feed", observedKey: "date", basis: board ? "day-ahead auction" : "primary auction", dataset: true,
+  };
+}
+
+const failure = (error: unknown) => error instanceof Error ? error.message : String(error);
+
+/**
+ * Every market's latest day-ahead price and the EUA auction price; one
+ * market's figures and its last 30 delivery days when a market is named; the
+ * EUA and its latest auctions for EUA (or carbon).
+ */
+export async function loadPowerPricesReport(argument: string | undefined, client: PricesClient = apiClient): Promise<HeadlessBundleResult> {
+  if (isCarbonQuery(argument)) {
+    const carbon = await fetchCarbonPrice(client);
+    return { sections: carbonSections(carbon), notes: [...carbon.gaps], freshness: freshness(null, carbon),
+      metadata: { market: carbon.market, unit: carbon.unit, source: carbon.source, publishedAt: carbon.publishedAt, series: "CAP:carbon:eua" } };
+  }
+  const board = await fetchPowerPrices(client);
+  const notes = [...board.gaps];
+  if (argument?.trim()) {
+    const market = powerPriceMarket(argument);
+    const row = market ? board.rows.find((entry) => entry.code === market.code) : null;
+    if (!market || !row) throw new Error(`No day-ahead price for "${argument.trim()}". Use a market such as DE, FR, GB or Spain, or EUA.`);
+    const history = await fetchPowerPriceHistory(market.code, null, client);
+    return {
+      sections: [
+        { title: `${market.name} day-ahead power, ${POWER_PRICE_UNIT}`, columns: COLUMNS, rows: [reportRow(row)] },
+        { title: `${market.name}, last 30 delivery days`,
+          columns: [{ key: "date", header: "Date", shrink: false }, { key: "price", header: POWER_PRICE_UNIT, align: "right", format: price }],
+          rows: history.points.slice(-30).reverse().map((point) => ({ date: point.date, price: point.value })) },
+      ],
+      notes, freshness: freshness(board, null, row),
+      metadata: { market: board.market, unit: board.unit, source: board.source, publishedAt: board.publishedAt, row, series: `CAP:day-ahead:${market.code.toLowerCase()}` },
+    };
+  }
+  // The carbon allowance rides along; when it cannot load, the power board still reports and says so.
+  const carbon = await fetchCarbonPrice(client).catch((error: unknown) => failure(error));
+  return {
+    sections: [{ title: `Day-ahead power, ${POWER_PRICE_UNIT}`, columns: COLUMNS, rows: board.rows.map(reportRow) },
+      ...(typeof carbon === "string" ? [] : carbonSections(carbon))],
+    notes: [...notes, ...(typeof carbon === "string" ? [carbon] : carbon.gaps)],
+    freshness: freshness(board, typeof carbon === "string" ? null : carbon),
+    metadata: { market: board.market, unit: board.unit, source: board.source, publishedAt: board.publishedAt,
+      ...(typeof carbon === "string" ? {} : { carbon: { market: carbon.market, unit: carbon.unit, source: carbon.source, publishedAt: carbon.publishedAt } }) },
+  };
+}
+
+export const powerPricesHeadless: HeadlessPaneDefinition<"bundle"> = {
+  shape: "bundle",
+  argument: { kind: "free-text", optional: true, placeholder: "market", description: "A market such as DE, FR, GB or Spain, or EUA for the carbon auctions; omit for every market and the EUA." },
+  options: [],
+  freshness: { source: "Ember", status: "not-a-feed", basis: "day-ahead auction", dataset: true },
+  discovery: { aliases: ["EPWR"], dataRequirements: ["Gloom Cloud European power and carbon prices"],
+    limitations: ["Daily averages of the day-ahead auction, weighted by load, per country; not intraday or forward prices",
+      "Each market is dated by its own latest delivery day: continental markets usually trail by a few days",
+      "The EUA price is the primary auction clearing price on business days, volume-weighted across a day's auctions; not a futures settlement"] },
+  describe: "European day-ahead power prices by country (EUR/MWh) and the EU carbon allowance auction price (EUR/tCO2)",
+  async load(args, ctx) {
+    const argument = Array.isArray(args.argument) ? args.argument.join(" ") : args.argument ?? undefined;
+    return loadPowerPricesReport(argument, ctx.apiClient);
+  },
+};

package/src/plugins/builtin/power/prices-model.ts

@@ -0,0 +1,103 @@
+import type { PowerPriceRow } from "../../../api-client/europe-energy";
+import type { SeriesDefinition } from "../../../series/types";
+import { fetchCarbonHistory, fetchPowerPriceHistory } from "./prices-client";
+
+/**
+ * The markets the server serves day-ahead prices for, by ISO 3166 alpha-2
+ * code, known before the board loads so the data catalog can list them. Great
+ * Britain is its own market; Northern Ireland trades with Ireland.
+ */
+export const POWER_PRICE_MARKETS = [
+  { code: "AL", name: "Albania" }, { code: "AT", name: "Austria" }, { code: "BE", name: "Belgium" },
+  { code: "BG", name: "Bulgaria" }, { code: "HR", name: "Croatia" }, { code: "CZ", name: "Czechia" },
+  { code: "DK", name: "Denmark" }, { code: "EE", name: "Estonia" }, { code: "FI", name: "Finland" },
+  { code: "FR", name: "France" }, { code: "DE", name: "Germany" }, { code: "GB", name: "Great Britain" },
+  { code: "GR", name: "Greece" }, { code: "HU", name: "Hungary" }, { code: "IE", name: "Ireland" },
+  { code: "IT", name: "Italy" }, { code: "LV", name: "Latvia" }, { code: "LT", name: "Lithuania" },
+  { code: "LU", name: "Luxembourg" }, { code: "ME", name: "Montenegro" }, { code: "NL", name: "Netherlands" },
+  { code: "MK", name: "North Macedonia" }, { code: "NO", name: "Norway" }, { code: "PL", name: "Poland" },
+  { code: "PT", name: "Portugal" }, { code: "RO", name: "Romania" }, { code: "RS", name: "Serbia" },
+  { code: "SK", name: "Slovakia" }, { code: "SI", name: "Slovenia" }, { code: "ES", name: "Spain" },
+  { code: "SE", name: "Sweden" }, { code: "CH", name: "Switzerland" },
+] as const;
+
+export type PowerPriceMarket = (typeof POWER_PRICE_MARKETS)[number];
+
+/** Words a market goes by besides its name and code. */
+const ALIASES: Readonly<Record<string, string>> = {
+  UK: "GB", "UNITED KINGDOM": "GB", BRITAIN: "GB", ENGLAND: "GB", GBR: "GB",
+  DEU: "DE", FRA: "FR", NLD: "NL", BEL: "BE", ESP: "ES", ITA: "IT", AUT: "AT", CHE: "CH", POL: "PL", IRL: "IE",
+  "CZECH REPUBLIC": "CZ", HOLLAND: "NL",
+};
+
+/** A typed market: its code (DE), alpha-3 code (DEU), name (germany) or a common alias (UK). */
+export function powerPriceMarket(input: string | null | undefined): PowerPriceMarket | null {
+  const key = input?.trim().toUpperCase().replace(/\s+/g, " ") ?? "";
+  if (!key) return null;
+  const code = ALIASES[key] ?? key;
+  return POWER_PRICE_MARKETS.find((market) => market.code === code || market.name.toUpperCase() === key) ?? null;
+}
+
+export const CARBON_PRICE_UNIT = "EUR/tCO2";
+/** The Prices tab's selection when the band charts the carbon allowance instead of a market. */
+export const CARBON_SELECTION = "EUA";
+/** What `EPWR EUA` (or carbon, EU ETS, CO2) asks for: the carbon allowance instead of a market. */
+const CARBON_WORDS = new Set(["EUA", "EUAS", "CARBON", "EU CARBON", "EU ETS", "ETS", "CO2", "EU ALLOWANCE", "EU ALLOWANCES"]);
+export const isCarbonQuery = (input: string | null | undefined) =>
+  CARBON_WORDS.has(input?.trim().toUpperCase().replace(/[-\s]+/g, " ") ?? "");
+
+/** Germany is the benchmark market a trader reads first. */
+export const DEFAULT_PRICE_MARKET = "DE";
+
+export const POWER_PRICE_UNIT = "EUR/MWh";
+export const formatPowerPrice = (value: number | null | undefined) => value == null ? "--" : value.toFixed(2);
+export const formatPowerChange = (value: number | null | undefined) =>
+  value == null ? "--" : `${value > 0 ? "+" : ""}${value.toFixed(2)}`;
+/** Where the latest price sits in its 52-week range, 0 at the low and 100 at the high. */
+export function powerRangePosition(row: PowerPriceRow): number | null {
+  if (row.price == null || row.low52w == null || row.high52w == null || row.high52w <= row.low52w) return null;
+  return Math.round(((row.price - row.low52w) / (row.high52w - row.low52w)) * 100);
+}
+const DAY_AHEAD_PAGE_URL = "https://ember-energy.org/data/european-wholesale-electricity-price-data/";
+
+/** The benchmark markets a search lists first; the rest follow by name. */
+const LEAD_MARKETS = ["DE", "FR", "GB", "NL", "BE", "IT", "ES"];
+const leadRank = (code: string) => (LEAD_MARKETS.indexOf(code) + LEAD_MARKETS.length + 1) % (LEAD_MARKETS.length + 1);
+
+/** Each market's daily day-ahead price, as `CAP:day-ahead:de`. */
+export const DAY_AHEAD_SERIES: readonly SeriesDefinition[] = [...POWER_PRICE_MARKETS].sort((left, right) =>
+  leadRank(left.code) - leadRank(right.code)).map((market): SeriesDefinition => ({
+  id: `day-ahead:${market.code.toLowerCase()}`,
+  name: `${market.name} day-ahead power price`,
+  unit: POWER_PRICE_UNIT,
+  frequency: "daily",
+  group: "Energy",
+  tags: ["electricity", "power price", "day-ahead", "wholesale", "Europe", market.code, ...(market.code === "GB" ? ["UK"] : [])],
+  description: `Daily average of the ${market.name} day-ahead auction price, weighted by load, in euros per MWh.`,
+  publisher: "Ember",
+  url: DAY_AHEAD_PAGE_URL,
+  load: async ({ start }) => {
+    const history = await fetchPowerPriceHistory(market.code, start?.toISOString().slice(0, 10));
+    return history.points;
+  },
+}));
+
+/**
+ * The EU carbon allowance price, as `CAP:carbon:eua`: each business day's
+ * primary auction clearing price, volume-weighted across that day's auctions.
+ */
+export const CARBON_SERIES: readonly SeriesDefinition[] = [{
+  id: "carbon:eua",
+  name: "EU carbon allowance (EUA) auction price",
+  unit: CARBON_PRICE_UNIT,
+  frequency: "daily",
+  group: "Energy",
+  tags: ["carbon", "EU carbon", "EUA", "EU ETS", "carbon price", "carbon allowance", "emission allowances", "emissions", "CO2", "Europe"],
+  description: "Clearing price of each business day's EU ETS primary auctions of general allowances, volume-weighted, in euros per tonne of CO2. An auction price, not a futures settlement.",
+  publisher: "EEX",
+  url: "https://www.eex.com/en/markets/environmental-markets/emissions-auctions",
+  load: async ({ start }) => {
+    const history = await fetchCarbonHistory(start?.toISOString().slice(0, 10));
+    return history.points;
+  },
+}];

package/src/plugins/builtin/power/prices.tsx

@@ -0,0 +1,179 @@
+import { useCallback, useMemo } from "react";
+import type { CarbonBoard, PowerPriceRow } from "../../../api-client/europe-energy";
+import {
+  ChartTableHeader, CompositeChart, MarketBoardStack, PaneStatusBody, spanAxisFormatter, usePaneNoticeFooter, usePaneStatusFooter,
+  usePaneTabs, type MarketBoardRow, type PaneHint, type StatItem,
+} from "../../../components";
+import { staticSeries } from "../../../components/chart/static/series";
+import { usePaneRefreshKey } from "../../../components/data-table/table-pane";
+import { StatChartDetail } from "../../../components/market-board";
+import { useAsyncResource, useAutoRefresh, usePaneSettingValue, usePluginAppActions, usePluginPaneState } from "../../../public/react";
+import { usePaneInstance } from "../../../state/app/context";
+import { useThemeColors } from "../../../theme/theme-context";
+import type { PaneProps } from "../../../types/plugin";
+import { Box, useRendererHost } from "../../../ui";
+import { POWER_TABS } from "./model";
+import { usePowerPricesEvidence, type PowerPricesSnapshot } from "./evidence";
+import { getCachedCarbonPrice, getCachedPowerPrices, loadCarbonHistory, loadCarbonPrice, loadPowerPriceHistory, loadPowerPrices, POWER_PRICES_NOT_AVAILABLE, validateCarbonPrice, validatePowerPrices } from "./prices-client";
+import { CARBON_PRICE_UNIT, CARBON_SELECTION, DEFAULT_PRICE_MARKET, formatPowerChange, formatPowerPrice, POWER_PRICE_UNIT, powerPriceMarket, powerRangePosition } from "./prices-model";
+
+const PANELS = [{ id: "main" }];
+const DAY_MS = 86_400_000;
+/** The board's chart: the selected market's year, as the 1Y figures read. */
+const CHART_DAYS = 366;
+const formatAxis = spanAxisFormatter((value, digits) => value.toFixed(digits));
+
+interface PriceBoardRow extends MarketBoardRow { price: PowerPriceRow }
+
+function boardRow(row: PowerPriceRow): PriceBoardRow {
+  const position = powerRangePosition(row);
+  return {
+    id: row.code, label: row.name, value: row.price, valueText: formatPowerPrice(row.price),
+    change: row.change, changeText: formatPowerChange(row.change),
+    percentile: position, percentileText: position == null ? "--" : `${position}%`,
+    asOf: row.date, status: row.price == null ? "unavailable" : "available",
+    history: row.trail.map((point) => ({ date: new Date(`${point.date}T00:00:00Z`), close: point.value })),
+    price: row,
+  };
+}
+
+const average = (key: "average7" | "average30" | "yearAgo", header: string) => ({
+  column: { id: key, label: header, width: 9, align: "right" as const },
+  sortValue: (row: PriceBoardRow) => row.price[key],
+  renderCell: (row: PriceBoardRow) => ({ text: formatPowerPrice(row.price[key]), ...(row.price[key] != null ? { value: row.price[key]! } : {}) }),
+});
+const EXTRA_COLUMNS = [average("average7", "7D AVG"), average("average30", "30D AVG"), average("yearAgo", "1Y AGO")];
+
+function historySeries(row: Pick<PowerPriceRow, "code" | "name" | "date">, points: ReadonlyArray<{ date: string; value: number }>, color: string, days?: number,
+  label = `${row.name} day-ahead`) {
+  const from = days && row.date ? new Date(Date.parse(`${row.date}T00:00:00Z`) - days * DAY_MS).toISOString().slice(0, 10) : "";
+  return [staticSeries(points.filter((point) => point.date >= from).map((point) => {
+    const date = new Date(`${point.date}T00:00:00Z`);
+    return { date, observedAt: date, value: point.value };
+  }), { id: `day-ahead:${row.code}`, label, color, calendarSpaced: true })];
+}
+
+const compactTonnes = (value: number) => value >= 1e6 ? `${(value / 1e6).toFixed(2)}M t` : `${Math.round(value / 1e3)}k t`;
+
+/**
+ * The EU carbon allowance above the board: its latest auction day's price,
+ * how it moved, and how the latest general-allowance auction was covered.
+ */
+function carbonFigures(board: CarbonBoard): StatItem[] {
+  const row = board.row;
+  if (row.price == null) return [];
+  const latest = board.auctions.find((auction) => !auction.aviation && auction.price != null);
+  return [
+    { id: "eua", label: `EUA ${CARBON_PRICE_UNIT}`, value: formatPowerPrice(row.price), detail: row.date ?? undefined },
+    { id: "eua-change", label: "EUA 1D", value: formatPowerChange(row.change), ...(row.previousDate ? { detail: `vs ${row.previousDate}` } : {}) },
+    { id: "eua-30d", label: "EUA 30D avg", value: formatPowerPrice(row.average30) },
+    { id: "eua-1y", label: "EUA 1Y ago", value: formatPowerPrice(row.yearAgo), ...(row.yearAgoDate ? { detail: row.yearAgoDate } : {}) },
+    ...(latest?.coverRatio != null ? [{ id: "eua-cover", label: "EUA cover", value: `${latest.coverRatio.toFixed(2)}x`,
+      detail: [latest.zone, compactTonnes(latest.volume)].filter(Boolean).join(" ") }] : []),
+  ];
+}
+
+function PriceDetail({ row, width, height, focused }: { row: PowerPriceRow; width: number; height: number; focused: boolean }) {
+  const colors = useThemeColors();
+  const loader = useCallback((force: boolean) => loadPowerPriceHistory(row.code, force), [row.code]);
+  const history = useAsyncResource(loader, { keepPreviousData: true });
+  const series = useMemo(() => historySeries(row, history.data?.payload.points ?? [], colors.warning), [row, history.data, colors.warning]);
+  const items: StatItem[] = [
+    { id: "price", label: POWER_PRICE_UNIT, value: formatPowerPrice(row.price), detail: row.date ?? undefined },
+    { id: "change", label: "1D", value: formatPowerChange(row.change), detail: row.previousDate ? `vs ${row.previousDate}` : undefined },
+    { id: "average7", label: "7D avg", value: formatPowerPrice(row.average7) },
+    { id: "average30", label: "30D avg", value: formatPowerPrice(row.average30) },
+    { id: "yearAgo", label: "1Y ago", value: formatPowerPrice(row.yearAgo), detail: row.yearAgoDate ?? undefined },
+    { id: "range", label: "52W range", value: `${formatPowerPrice(row.low52w)} to ${formatPowerPrice(row.high52w)}` },
+  ];
+  return <StatChartDetail items={items} width={width} height={height} empty={!history.loading && series[0]!.points.length < 2}
+    emptySubject="price history" emptyTitle={history.error ?? "No price history available."}
+    renderChart={(chartHeight) => <CompositeChart series={series} panels={PANELS} width={width} height={chartHeight} focused={focused}
+      showLegend navigable={false} showTimeAxis formatValue={(value) => `${formatPowerPrice(value)} ${POWER_PRICE_UNIT}`}
+      formatAxisValue={formatAxis} remoteKind="day-ahead-history" />} />;
+}
+
+/**
+ * POWER's Prices tab: every European market's latest day-ahead price, each
+ * dated by its own delivery day, with the selected market's year above the
+ * board and its whole history in the detail. The EU carbon allowance's
+ * auction price sits in the figures above, in its own unit.
+ */
+export function PowerPricesView({ width, height, focused }: PaneProps) {
+  const colors = useThemeColors();
+  const host = useRendererHost();
+  const { createPaneFromTemplate } = usePluginAppActions();
+  const [openingTab] = usePaneSettingValue("tab", "queue");
+  const [, setTab] = usePluginPaneState<string>("power:tab", openingTab);
+  // `EPWR DE` opens with the market in the instance params, `EPWR EUA` with the carbon allowance; a saved selection wins.
+  const params = usePaneInstance()?.params;
+  const [selectedId, setSelectedId] = usePluginPaneState<string | null>("power:prices:selected", powerPriceMarket(params?.market)?.code ?? null);
+  const [carbonMode, setCarbonMode] = usePluginPaneState("power:prices:carbon", params?.market === CARBON_SELECTION);
+  const [openId, setOpenId] = usePluginPaneState<string | null>("power:prices:open", null);
+  // `shot` freezes the boards and the charted history, so the capture and its check read the same days.
+  const [snapshotSetting] = usePaneSettingValue<PowerPricesSnapshot | null>("powerPricesSnapshot", null);
+  const snapshot = useMemo(() => {
+    try {
+      return snapshotSetting ? { ...snapshotSetting, board: validatePowerPrices(snapshotSetting.board),
+        carbon: snapshotSetting.carbon ? validateCarbonPrice(snapshotSetting.carbon) : null } : null;
+    } catch { return null; }
+  }, [snapshotSetting]);
+  const resource = useAsyncResource(snapshot ? null : loadPowerPrices, { initialData: getCachedPowerPrices });
+  const board = snapshot?.board ?? resource.data?.payload ?? null;
+  // The carbon allowance loads beside the board; its failure is a notice, never the board's.
+  const carbonResource = useAsyncResource(snapshot ? null : loadCarbonPrice, { initialData: getCachedCarbonPrice });
+  const carbon = snapshot ? snapshot.carbon : carbonResource.data?.payload ?? null;
+  const figures = useMemo(() => carbon ? carbonFigures(carbon) : [], [carbon]);
+  const rows = useMemo(() => board?.rows.map(boardRow) ?? [], [board]);
+  // The band charts the selected market, or the carbon allowance from `c` or EPWR EUA until a market is chosen.
+  const carbonCharted = carbonMode && !!carbon?.row.date;
+  const selected = rows.find((row) => row.id === selectedId) ?? rows.find((row) => row.id === DEFAULT_PRICE_MARKET) ?? rows[0];
+  const selectMarket = useCallback((id: string) => { setSelectedId(id); setCarbonMode(false); }, [setSelectedId, setCarbonMode]);
+  const code = carbonCharted ? CARBON_SELECTION : selected?.price.date ? selected.id : null;
+  const historyLoader = useCallback((force: boolean) => code === CARBON_SELECTION ? loadCarbonHistory(force) : loadPowerPriceHistory(code!, force), [code]);
+  const loaded = useAsyncResource<{ payload: { code: string; points: ReadonlyArray<{ date: string; value: number }> } }>(
+    code && !snapshot ? historyLoader : null, { keepPreviousData: true });
+  const history = snapshot ? { ...loaded, data: snapshot.history ? { payload: snapshot.history } : null, loading: false, error: null } : loaded;
+  usePowerPricesEvidence(board, carbon, useMemo(() => rows.map((row) => row.id), [rows]), resource.loading || history.loading || carbonResource.loading);
+  useAutoRefresh(resource.updatedAt, resource.load);
+  useAutoRefresh(carbonResource.updatedAt, carbonResource.load);
+  usePaneRefreshKey(() => { void resource.reload(); void history.reload(); void carbonResource.reload(); }, { focused });
+  const { strip, rows: tabRows } = usePaneTabs({ tabs: [...POWER_TABS], activeValue: "prices", onSelect: (tab: string) => setTab(tab), focused, dense: true });
+  const notAvailable = !board && resource.error === POWER_PRICES_NOT_AVAILABLE;
+  const open = rows.find((row) => row.id === openId);
+  const charted = carbonCharted ? carbon!.row : selected?.price;
+  const unit = carbonCharted ? CARBON_PRICE_UNIT : POWER_PRICE_UNIT;
+  const series = useMemo(() => charted && history.data?.payload.code === charted.code
+    ? historySeries(charted, history.data.payload.points, carbonCharted ? colors.positive : colors.warning, CHART_DAYS, carbonCharted ? "EU carbon (EUA) auction" : undefined)
+    : [], [charted, carbonCharted, history.data, colors.warning, colors.positive]);
+  const sourceUrl = board?.source.url;
+  const chartExpression = carbonCharted ? "CAP:carbon:eua" : selected?.price.date ? `CAP:day-ahead:${selected.id.toLowerCase()}` : null;
+  const hints: PaneHint[] = [
+    ...(sourceUrl ? [{ id: "source", key: "o", label: `pen ${carbonCharted ? carbon!.source.name : board!.source.name}`, title: "Open the publisher's page",
+      onPress: () => void host.openExternal(carbonCharted ? carbon!.source.url : sourceUrl) }] : []),
+    ...(chartExpression ? [{ id: "chart", key: "g", label: "raph", title: "Chart in a custom chart",
+      onPress: () => createPaneFromTemplate("chart-composer-pane", { arg: chartExpression }) }] : []),
+    ...(figures.length && !carbonCharted ? [{ id: "carbon", key: "c", label: "arbon", title: "Chart the EU carbon auction price above the board",
+      onPress: () => setCarbonMode(true) }] : []),
+  ];
+  usePaneStatusFooter({ registrationId: "power-prices", loading: resource.loading || history.loading,
+    error: board ? resource.error ?? (open ? null : history.error) : null, stale: !!resource.data?.stale, hints });
+  usePaneNoticeFooter({ registrationId: "power-prices:notices", focused,
+    notices: [...(board?.gaps ?? []), ...(resource.data?.refreshError ? [resource.data.refreshError] : []),
+      ...(carbon?.gaps ?? []), ...(board && !carbon && carbonResource.error ? [carbonResource.error] : [])] });
+  const bodyHeight = Math.max(3, height - tabRows);
+  return <Box width={width} height={height} flexDirection="column">
+    {strip}
+    <PaneStatusBody loading={resource.loading && !board} error={!board && !notAvailable ? resource.error : null}
+      empty={notAvailable} emptyTitle={POWER_PRICES_NOT_AVAILABLE} subject="power prices" width={width} height={bodyHeight}>
+      {board ? <MarketBoardStack rows={rows} width={width} height={bodyHeight} focused={focused}
+        rootBefore={({ columns }) => <ChartTableHeader width={width} height={bodyHeight} tableRows={rows.length} tableColumns={columns}
+          figures={figures} chart={charted ? { series, loading: history.loading && !series.length, empty: `No price history for ${charted.name}`,
+            formatValue: (value) => `${formatPowerPrice(value)} ${unit}`, formatAxisValue: formatAxis, remoteKind: "day-ahead-history" } : null} />}
+        selectedId={selected?.id ?? null} onSelectedIdChange={selectMarket} openId={open?.id ?? null} onOpenIdChange={setOpenId}
+        labelHeader="MARKET" labelWidth={16} valueLabel={POWER_PRICE_UNIT} valueWidth={10} percentileLabel="IN 1Y" extraColumns={EXTRA_COLUMNS}
+        emptyTitle={POWER_PRICES_NOT_AVAILABLE}
+        renderDetail={(row) => <PriceDetail row={row.price} width={width} height={Math.max(5, bodyHeight - 2)} focused={focused} />} /> : null}
+    </PaneStatusBody>
+  </Box>;
+}

package/src/plugins/builtin/rate-path/headless.ts

@@ -10,6 +10,14 @@ const bps = (value: unknown) => {
   const bp = finiteOrNull(value);
   return bp == null ? "--" : `${bp > 0 ? "+" : ""}${bp.toFixed(1)}bp`;
 };
+/** What a text report calls each current policy rate; JSON keeps the keys. */
+const POLICY_LABELS: Record<string, string> = {
+  effr: "Effective fed funds rate",
+  targetLower: "Target range lower",
+  targetUpper: "Target range upper",
+};
+const policyLabel = (value: unknown) => POLICY_LABELS[String(value)] ?? String(value);
+const yesNo = (value: unknown) => value === true ? "yes" : value === false ? "no" : "--";
 const timestamp = (value: unknown) => typeof value === "string" ? value.replace("T", " ").slice(0, 16) : "--";
 const probabilities = (value: unknown) => {
   const outcomes = Array.isArray(value) ? value as RateMeeting["probabilities"] : [];
@@ -17,43 +25,63 @@ const probabilities = (value: unknown) => {
     : outcomes.map((outcome) => `${outcome.targetMidpoint.toFixed(3)}% ${(outcome.probability * 100).toFixed(0)}%`).join(" / ");
 };
 
+// A narrow terminal leaves out the sample count, status, percentile and quote time (the closing line has it),
+// then moves the staleness and month under each row.
 const contractColumns: HeadlessPaneColumn[] = [
-  { key: "symbol", header: "Symbol" }, { key: "month", header: "Month" },
+  { key: "symbol", header: "Symbol", shrink: false }, { key: "month", header: "Month", shrink: false, stackPriority: 1 },
   { key: "price", header: "Price", align: "right", format: (value) => finiteOrNull(value)?.toFixed(3) ?? "--" },
   { key: "impliedRate", header: "Implied rate", align: "right", format: rate },
-  { key: "percentile", header: "Pctl 1Y", align: "right", format: pctl },
-  { key: "samples", header: "Samples", align: "right" },
-  { key: "asOf", header: "As of UTC", format: timestamp },
-  { key: "status", header: "Status" }, { key: "stale", header: "Stale" },
+  { key: "percentile", header: "Pctl 1Y", align: "right", stackPriority: 4, stackRows: 0, format: pctl },
+  { key: "samples", header: "Samples", align: "right", stackPriority: 6, stackRows: 0 },
+  { key: "asOf", header: "As of UTC", shrink: false, stackPriority: 3, stackRows: 0, format: timestamp },
+  { key: "status", header: "Status", stackPriority: 5, stackRows: 0 }, { key: "stale", header: "Data stale", stackPriority: 2, format: yesNo },
 ];
 
+/**
+ * How far the fed funds and SOFR futures quotes are held back. The rate-path
+ * endpoint does not carry a delay. CME Group's delayed market data is at least
+ * 10 minutes behind its real-time feed (its information license agreement
+ * defines delayed data as published more than 10 minutes after it is
+ * disseminated), and the futures-curve endpoint reports `delayMinutes: 10` on
+ * every CME contract.
+ */
+const CME_FUTURES_DELAY_MINUTES = 10;
+
 export const ratePathHeadless: HeadlessPaneDefinition<"bundle"> = {
   discovery: { aliases: ["WIRP", "FFIP"], dataRequirements: ["Gloom Cloud rate-path endpoint"],
-    limitations: ["Conditional two-outcome probabilities", "SR3 history from hourly trades", "Maintained FOMC schedule and SEP snapshot"] },
+    limitations: ["Conditional two-outcome probabilities.", "SR3 history from hourly trades.", "Maintained FOMC schedule and SEP snapshot."] },
   shape: "bundle", argument: { kind: "none" }, options: [], describe: "US rate path",
-  // Delayed futures quotes; each contract and policy rate says whether it is stale.
-  freshness: { status: "delayed" },
+  // Delayed CME futures quotes.
+  freshness: { source: "CME futures", status: "delayed", delayMinutes: CME_FUTURES_DELAY_MINUTES },
   async load(_args, ctx) {
     const data = await fetchRatePath(ctx.apiClient);
     const moves = meetingMoves(data.meetings);
+    // The line cites CME futures, so the contracts alone date it and count its stale rows. The policy rates
+    // (FRED) keep their own date and stale flag in their table, and the meetings are read from the contracts.
+    const contracts = [...data.fedFunds, ...data.sofr].filter((contract) => contract.status !== "unavailable")
+      .map(({ asOf, stale }) => ({ asOf, stale }));
     return {
+      freshness: { observedKey: "asOf", observations: contracts },
       sections: [
         { title: "Current policy", columns: [
-          { key: "name", header: "Name" }, { key: "value", header: "Value", align: "right", format: rate },
-          { key: "asOf", header: "As of" }, { key: "percentile", header: "Pctl 1Y", align: "right", format: pctl },
-          { key: "samples", header: "Samples", align: "right" }, { key: "source", header: "Source" }, { key: "stale", header: "Stale" },
+          { key: "name", header: "Name", minWidth: 18, format: policyLabel }, { key: "value", header: "Value", align: "right", format: rate },
+          { key: "asOf", header: "As of", shrink: false }, { key: "percentile", header: "Pctl 1Y", align: "right", stackPriority: 1, format: pctl },
+          { key: "samples", header: "Samples", align: "right", stackPriority: 2, stackRows: 0 }, { key: "stale", header: "Data stale", format: yesNo },
         ], rows: Object.entries(data.current).map(([name, metric]) => ({ name, ...metric })) },
+        // A narrow terminal keeps the moves and change, prints the probabilities of the next two meetings
+        // under their rows, and leaves out the rest; a reason a meeting has no rate stays under its row.
         { title: "FOMC meetings", columns: [
-          { key: "date", header: "Date" },
+          { key: "date", header: "Date", shrink: false },
           { key: "moves", header: "Moves", align: "right", format: (value) => movesText(finiteOrNull(value)) },
           { key: "moveOdds", header: "P(move)", align: "right", format: (value) => moveOddsText(finiteOrNull(value)) },
-          { key: "impliedRate", header: "Implied rate", align: "right", format: rate },
-          { key: "targetMidpoint", header: "Target midpoint", align: "right", format: (value) => finiteOrNull(value)?.toFixed(3) ?? "--" },
+          { key: "impliedRate", header: "Implied rate", align: "right", stackPriority: 3, stackRows: 0, format: rate },
+          { key: "targetMidpoint", header: "Target midpoint", align: "right", stackPriority: 6, stackRows: 0, format: (value) => finiteOrNull(value)?.toFixed(3) ?? "--" },
           { key: "changeBps", header: "Change", align: "right", format: bps },
-          { key: "percentile", header: "Pctl 1Y", align: "right", format: pctl },
-          { key: "samples", header: "Samples", align: "right" }, { key: "asOf", header: "As of UTC", format: timestamp },
-          { key: "probabilities", header: "Probabilities", format: probabilities },
-          { key: "method", header: "Method" }, { key: "reason", header: "Reason" },
+          { key: "percentile", header: "Pctl 1Y", align: "right", stackPriority: 7, stackRows: 0, format: pctl },
+          { key: "samples", header: "Samples", align: "right", stackPriority: 8, stackRows: 0 },
+          { key: "asOf", header: "As of UTC", shrink: false, stackPriority: 5, stackRows: 0, format: timestamp },
+          { key: "probabilities", header: "Probabilities", shrink: false, stackPriority: 4, stackRows: 2, format: probabilities },
+          { key: "method", header: "Method", stackPriority: 9, stackRows: 0 }, { key: "reason", header: "Reason", stackPriority: 10 },
         ], rows: data.meetings.map((meeting) => ({ ...meeting, moves: movesPriced(meeting), moveOdds: moves.get(meeting.date) ?? null })) },
         { title: "Fed funds contracts", columns: contractColumns, rows: data.fedFunds.map((contract) => ({ ...contract })) },
         { title: "SOFR contracts", columns: contractColumns, rows: data.sofr.map((contract) => ({ ...contract })) },

package/src/plugins/builtin/realized-vol/headless.ts

@@ -5,6 +5,7 @@ import { createRealizedVolatilityDependencies, loadCurrentAtmIv, loadRealizedVol
 import { projectRealizedVolatility, type CurrentAtmIvSnapshot } from "./model";
 import { ESTIMATOR_OPTIONS, selectedWindows } from "./settings";
 import { DAILY_CLOSES } from "../shared/report-freshness";
+import { listingAbroadVenue } from "../../../utils/sec";
 
 export function realizedVolHeadless(initialView: "graph" | "cone"): HeadlessPaneDefinition<"bundle"> {
   return {
@@ -26,8 +27,11 @@ export function realizedVolHeadless(initialView: "graph" | "cone"): HeadlessPane
         throw new Error("Choose session windows from 10,20,30,60,90,180,260");
       }
       const instrument = await resolveHeadlessInstrument(ctx, args.symbols[0]!);
+      // Options are US listings'; SAN:EPA has none, and bare SAN's chain is another company's.
+      const abroad = listingAbroadVenue(args.symbols[0]!) != null;
       const currentIv = async (): Promise<CurrentAtmIvSnapshot | null> => {
         if (!args.options.showIv) return null;
+        if (abroad) return { reference: null, error: null, warnings: [], noOptionChain: true };
         try {
           const quote = await ctx.marketData.getQuote(instrument.symbol, instrument.exchange);
           if (quote.stale || !(quote.price > 0) || !Number.isFinite(quote.price)) throw new Error("Underlying quote is missing or stale");
@@ -71,6 +75,7 @@ export function realizedVolHeadless(initialView: "graph" | "cone"): HeadlessPane
           && (!args.options.showIv || iv?.reference != null || iv?.noOptionChain === true),
         unavailableSymbols: model.history.length ? [] : [instrument.symbol], errors,
         metadata: { unit: "decimal annualized volatility", annualization: 252, model, currentIv: iv,
+          ...(abroad && args.options.showIv ? { notices: [`Options data covers US listings only, so ${args.symbols[0]} has no current IV.`] } : {}),
           source: history.source, stale: history.stale, fetchedAt: history.fetchedAt,
           methodology: "docs/research-data.md#shared-volatility-calculations" },
       };

package/src/plugins/builtin/relative-rotation/headless.ts

@@ -37,9 +37,9 @@ export const rotationHeadless: HeadlessPaneDefinition<"bundle"> = {
     aliases: ["RRG", "GRR"],
     dataRequirements: ["Cloud daily history and listing currencies"],
     limitations: [
-      "Transparent 13-week strength and 4-week momentum, not proprietary JdK indices",
-      "Same-currency price returns; dividends are not reinvested",
-      "Completed weeks only",
+      "Transparent 13-week strength and 4-week momentum, not proprietary JdK indices.",
+      "Same-currency price returns; dividends are not reinvested.",
+      "Completed weeks only.",
     ],
   },
   async load(args, ctx) {

package/src/plugins/builtin/research/corporate-actions-pane.tsx

@@ -283,8 +283,11 @@ export function buildEventDetail({
   if (row.status !== "Earnings") return sections;
 
   const comparison: EventDetailBlock[] = [
-    detailRow("Actual", earningsInput(row.epsActual, row.epsCurrency)),
-    detailRow("Consensus", earningsInput(row.epsEstimate, row.epsCurrency)),
+    ...(row.dateStatus && row.dateStatus !== "reported" ? [detailRow("Report date", row.date, row.dateStatus)] : []),
+    detailRow("Actual", earningsInput(row.epsActual, row.epsCurrency),
+      row.epsBasis === "unknown" ? "basis unknown" : row.epsBasis),
+    detailRow("Consensus", earningsInput(row.epsEstimate, row.epsCurrency),
+      row.epsAnalysts != null ? `${row.epsAnalysts} analysts` : undefined),
   ];
   if (row.epsDifference != null) comparison.push(detailRow("Difference", earningsInput(row.epsDifference, row.epsCurrency)));
   if (row.surprisePercent != null) {