@gloom-sh/terminal 0.0.0-stage → 0.19.0

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,209 @@
+import { logFailure } from "../../../utils/log-failure";
+import { useCallback, useMemo } from "react";
+import type { CarbonBoard, PowerPriceRow } from "../../../api-client/europe-energy";
+import {
+  ChartTableHeader, CompositeChart, MarketBoardStack, PaneStatusBody, QueryBar, 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 GasStorageSnapshot, type PowerPricesSnapshot } from "./evidence";
+import { GasStorageView } from "./gas";
+import { GAS_PUBLISHER } from "./gas-model";
+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" />} />;
+}
+
+const BOARDS = [{ value: "power", label: "Power" }, { value: "gas", label: "Gas storage" }] as const;
+
+/**
+ * POWER's Prices tab: European day-ahead power with the EU carbon allowance,
+ * or European gas storage, picked in the query bar. `EPWR GAS` opens on gas.
+ */
+export function PowerPricesView({ width, height, focused }: PaneProps) {
+  const [openingTab] = usePaneSettingValue("tab", "queue");
+  const [, setTab] = usePluginPaneState<string>("power:tab", openingTab);
+  const params = usePaneInstance()?.params;
+  const [board, setBoard] = usePluginPaneState<string>("power:prices:board", params?.board === "gas" ? "gas" : "power");
+  const gas = board === "gas";
+  const [gasSnapshot] = usePaneSettingValue<GasStorageSnapshot | null>("gasStorageSnapshot", null);
+  const { strip, rows: tabRows } = usePaneTabs({ tabs: [...POWER_TABS], activeValue: "prices", onSelect: (tab: string) => setTab(tab), focused, dense: true });
+  // GIE asks to be named under its data; the credit sits at the bar's right edge.
+  const query = <QueryBar width={width} meta={gas ? GAS_PUBLISHER : undefined}
+    filters={[{ id: "board", label: "Board", inline: true, value: gas ? "gas" : "power", options: BOARDS, onChange: setBoard }]} />;
+  const bodyHeight = Math.max(3, height - tabRows - 1);
+  return <Box width={width} height={height} flexDirection="column">
+    {strip}
+    <Box height={1} flexShrink={0}>{query}</Box>
+    {gas ? <GasStorageView width={width} height={bodyHeight} focused={focused} snapshot={gasSnapshot} />
+      : <PowerPriceBoard width={width} height={bodyHeight} focused={focused} />}
+  </Box>;
+}
+
+/**
+ * The power board: 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.
+ */
+function PowerPriceBoard({ width, height, focused }: { width: number; height: number; focused: boolean }) {
+  const colors = useThemeColors();
+  const host = useRendererHost();
+  const { createPaneFromTemplate } = usePluginAppActions();
+  // `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 {
+      if (snapshotSetting?.carbonError !== undefined && (typeof snapshotSetting.carbonError !== "string"
+        || !snapshotSetting.carbonError.trim() || snapshotSetting.carbon != null)) throw new Error("Invalid carbon price failure state.");
+      return snapshotSetting ? { ...snapshotSetting, board: validatePowerPrices(snapshotSetting.board),
+        carbon: snapshotSetting.carbon ? validateCarbonPrice(snapshotSetting.carbon) : null } : null;
+    } catch (error) {
+      logFailure("power.prices", "Validate power prices snapshot failed")(error);
+      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 carbonError = snapshot ? snapshot.carbonError : carbonResource.error;
+  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, snapshot?.carbonError);
+  useAutoRefresh(resource.updatedAt, resource.load);
+  useAutoRefresh(carbonResource.updatedAt, carbonResource.load);
+  usePaneRefreshKey(() => { void resource.reload(); void history.reload(); void carbonResource.reload(); }, { focused });
+  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 && carbonError ? [carbonError] : [])] });
+  return <Box width={width} height={height} flexDirection="column">
+    <PaneStatusBody loading={resource.loading && !board} error={!board && !notAvailable ? resource.error : null}
+      empty={notAvailable} emptyTitle={POWER_PRICES_NOT_AVAILABLE} subject="power prices" width={width} height={height}>
+      {board ? <MarketBoardStack rows={rows} width={width} height={height} focused={focused}
+        rootBefore={({ columns }) => <ChartTableHeader width={width} height={height} 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, height - 2)} focused={focused} />} /> : null}
+    </PaneStatusBody>
+  </Box>;
+}

package/src/plugins/builtin/power/query.ts

@@ -0,0 +1,25 @@
+import type { PowerFilter } from "../../../api-client/power";
+import { powerTab } from "./model";
+
+export const POWER_SORT_COLUMNS = ["capacityMw", "name", "region", "status", "proposedDate", "generationMwh", "salesMwh", "revenueUsd", "summerPeakDemandMw", "winterPeakDemandMw"];
+
+/** A shared scope keeps panes, exports and captured evidence on the same data. */
+export function powerQuery(options: Record<string, unknown>, symbol?: string | null): PowerFilter {
+  const tab = powerTab(options.tab);
+  const benchmark = options.historical === true && ["queue", "history", "outcomes"].includes(tab);
+  const sourceId = options.sourceId && (!String(options.sourceId).startsWith("us-lbnl") || benchmark) ? String(options.sourceId) : null;
+  const loads = tab === "loads" || tab === "utilities";
+  return {
+    ...Object.fromEntries(["country", "region", "search", "from", "to"].flatMap((key) => typeof options[key] === "string" && options[key] ? [[key, options[key]]] : [])),
+    ...(tab === "capacity" && !sourceId ? { sourceId: options.context === "generation" ? "us-eia923" : options.context === "utility" ? "us-eia861" : "us-eia860" } : {}),
+    ...(sourceId ? { sourceId } : {}),
+    ...(symbol ? { symbol } : {}),
+    ...(loads && options.loadClass ? { loadClass: String(options.loadClass) } : {}),
+    ...(!loads && tab !== "coverage" && options.fuel ? { fuel: String(options.fuel) } : {}),
+    ...(tab !== "coverage" && options.status ? { status: String(options.status) } : {}),
+    historical: benchmark,
+    ...(tab === "coverage" ? {} : { kind: loads ? "load" : tab === "capacity" ? options.context === "utility" ? "utility" : "capacity" : "queue" }),
+    sort: POWER_SORT_COLUMNS.includes(String(options.sort)) ? options.sort as PowerFilter["sort"] : tab === "capacity" && options.context === "generation" ? "generationMwh" : tab === "capacity" && options.context === "utility" ? "salesMwh" : "capacityMw",
+    direction: options.direction === "asc" ? "asc" : "desc",
+  };
+}

package/src/plugins/builtin/primary-dealers/client.ts

@@ -0,0 +1,158 @@
+import { createTtlCache } from "../../../data/ttl-cache";
+import { httpFetch } from "../../../utils/http-transport";
+import { isoDateOrNull, numericOrNull, recordOrNull, textOrNull } from "../../../utils/guards";
+import {
+  boardAsOf,
+  buildDealerRows,
+  newestSeriesBreak,
+  sumSeries,
+  type DealerRow,
+  type SeriesPoint,
+} from "./model";
+
+const API = "https://markets.newyorkfed.org/api/pd";
+const FETCH_TIMEOUT_MS = 15_000;
+/** The release is weekly; a series read is kept this long so moving through the board never asks twice. */
+const HISTORY_TTL_MS = 30 * 60_000;
+
+export interface DealerBoard {
+  seriesBreak: string;
+  positions: DealerRow[];
+  fails: DealerRow[];
+  asOf: string | null;
+}
+
+/** A row's weekly history: the sum of the series behind it, oldest first. */
+export interface DealerHistory {
+  rowId: string;
+  points: SeriesPoint[];
+}
+
+function timeseriesRows(payload: unknown): unknown[] {
+  const root = recordOrNull(payload);
+  const pd = recordOrNull(root?.pd);
+  return Array.isArray(pd?.timeseries) ? pd.timeseries : Array.isArray(root?.timeseries) ? root.timeseries : [];
+}
+
+function parseSeriesBreaks(payload: unknown): Array<{ seriesBreak: string; startDate: string }> {
+  const root = recordOrNull(payload);
+  const pd = recordOrNull(root?.pd);
+  const rows = Array.isArray(pd?.seriesbreaks) ? pd.seriesbreaks : [];
+  const breaks: Array<{ seriesBreak: string; startDate: string }> = [];
+  for (const raw of rows) {
+    const row = recordOrNull(raw);
+    const seriesBreak = textOrNull(row?.seriesbreak) ?? textOrNull(row?.seriesBreak);
+    const startDate = isoDateOrNull(row?.startdate) ?? isoDateOrNull(row?.startDate);
+    if (seriesBreak && startDate) breaks.push({ seriesBreak, startDate });
+  }
+  return breaks;
+}
+
+/** The newest observation of every series that has a figure (the release writes `*` for a suppressed one). */
+function parseLatest(payload: unknown): Map<string, SeriesPoint> {
+  const latest = new Map<string, SeriesPoint>();
+  for (const raw of timeseriesRows(payload)) {
+    const row = recordOrNull(raw);
+    const keyid = textOrNull(row?.keyid) ?? textOrNull(row?.keyId);
+    const asOf = isoDateOrNull(row?.asofdate) ?? isoDateOrNull(row?.asOfDate);
+    const value = numericOrNull(row?.value);
+    if (!keyid || !asOf || value == null) continue;
+    const known = latest.get(keyid);
+    if (!known || asOf > known.asOf) latest.set(keyid, { asOf, value });
+  }
+  return latest;
+}
+
+/** Every observation of one series, oldest first. */
+function parseSeriesPoints(payload: unknown): SeriesPoint[] {
+  const points: SeriesPoint[] = [];
+  for (const raw of timeseriesRows(payload)) {
+    const row = recordOrNull(raw);
+    const asOf = isoDateOrNull(row?.asofdate) ?? isoDateOrNull(row?.asOfDate);
+    const value = numericOrNull(row?.value);
+    if (asOf && value != null) points.push({ asOf, value });
+  }
+  return points.sort((a, b) => (a.asOf < b.asOf ? -1 : a.asOf > b.asOf ? 1 : 0));
+}
+
+async function readJson(url: string): Promise<unknown> {
+  const response = await httpFetch(url, {
+    headers: { Accept: "application/json", "User-Agent": "gloomberb" },
+    signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+  });
+  if (!response.ok) throw new Error(`Request failed (${response.status})`);
+  return response.json() as Promise<unknown>;
+}
+
+/** The series break changes about every two years; one read serves the session. */
+const seriesBreaks = createTtlCache<string>({ ttlMs: Infinity });
+
+function currentSeriesBreak(force: boolean): Promise<string> {
+  return seriesBreaks.load("current", async () => {
+    const seriesBreak = newestSeriesBreak(parseSeriesBreaks(await readJson(`${API}/list/seriesbreaks.json`)));
+    if (!seriesBreak) throw new Error("No series break was listed.");
+    return seriesBreak;
+  }, { force });
+}
+
+/**
+ * The board in two reads: the break the release is in now, and the latest
+ * figure of every series in it together with each one's change from the week
+ * before. History is not read here; see `loadDealerHistory`.
+ */
+export async function fetchPrimaryDealers(): Promise<DealerBoard> {
+  const seriesBreak = await currentSeriesBreak(false);
+  const rows = buildDealerRows(parseLatest(await readJson(`${API}/latest/${encodeURIComponent(seriesBreak)}.json`)));
+  if (rows.length === 0) throw new Error("No positions were recognized.");
+  return {
+    seriesBreak,
+    positions: rows.filter((row) => row.tab === "positions"),
+    fails: rows.filter((row) => row.tab === "fails"),
+    asOf: boardAsOf(rows),
+  };
+}
+
+const seriesReads = createTtlCache<SeriesPoint[]>({ ttlMs: HISTORY_TTL_MS });
+
+function seriesRead(seriesBreak: string, key: string, force: boolean): Promise<SeriesPoint[]> {
+  const url = `${API}/get/${encodeURIComponent(seriesBreak)}/timeseries/${encodeURIComponent(key)}.json`;
+  return seriesReads.load(`${seriesBreak}:${key}`, async () => parseSeriesPoints(await readJson(url)), { force });
+}
+
+/** A row's history, one read per series behind it, each kept for the session. */
+export async function loadDealerHistory(
+  seriesBreak: string,
+  row: Pick<DealerRow, "id" | "keys">,
+  force = false,
+): Promise<DealerHistory> {
+  const series = await Promise.all(row.keys.map((key) => seriesRead(seriesBreak, key, force)));
+  return { rowId: row.id, points: sumSeries(series) };
+}
+
+/** The points of every series behind the row when they are all in hand and fresh. */
+function heldSeries(seriesBreak: string, row: Pick<DealerRow, "keys">): SeriesPoint[][] | null {
+  const series: SeriesPoint[][] = [];
+  for (const key of row.keys) {
+    const points = seriesReads.peek(`${seriesBreak}:${key}`);
+    if (!points) return null;
+    series.push(points);
+  }
+  return series;
+}
+
+/** Whether the row's history is in hand, so a chart can follow the selection at once. */
+export function hasDealerHistory(seriesBreak: string, row: Pick<DealerRow, "keys">): boolean {
+  return heldSeries(seriesBreak, row) != null;
+}
+
+/** The history when every series behind the row is already in hand, so a chart can draw before any read. */
+export function cachedDealerHistory(seriesBreak: string, row: Pick<DealerRow, "id" | "keys">): DealerHistory | null {
+  const series = heldSeries(seriesBreak, row);
+  return series ? { rowId: row.id, points: sumSeries(series) } : null;
+}
+
+/** Forgets what was read, for a test or a refresh that must see the release again. */
+export function resetPrimaryDealersCache(): void {
+  seriesBreaks.clear();
+  seriesReads.clear();
+}

package/src/plugins/builtin/primary-dealers/headless.ts

@@ -0,0 +1,78 @@
+import type { HeadlessPaneColumn, HeadlessPaneDefinition } from "../../../types/headless";
+import { fetchPrimaryDealers } from "./client";
+import { formatChange, formatLevel, type DealerRow } from "./model";
+
+const level = (value: unknown) => typeof value === "number" ? formatLevel(value) : "—";
+const change = (value: unknown) => typeof value === "number" ? formatChange(value) : "—";
+const text = (value: unknown) => typeof value === "string" && value ? value : "—";
+const group = (value: unknown) => typeof value === "string" ? value : "";
+
+const COLUMNS: HeadlessPaneColumn[] = [
+  { key: "position", header: "Position" },
+  { key: "group", header: "Group", format: group },
+  { key: "asOf", header: "As of", format: text },
+  { key: "latest", header: "Latest $mn", align: "right", format: level },
+  { key: "previous", header: "Previous $mn", align: "right", format: level },
+  { key: "change", header: "Change $mn", align: "right", format: change },
+];
+
+/** The report's table sets a breakdown in under its total, as the pane does; the export names the total in `group` instead. */
+const TEXT_COLUMNS: HeadlessPaneColumn[] = COLUMNS.filter((column) => column.key !== "group");
+
+function reportRow(row: DealerRow) {
+  return {
+    id: row.id,
+    position: row.label,
+    group: row.parent,
+    series: row.keys.join("+"),
+    asOf: row.asOf,
+    latest: row.latest,
+    previous: row.previous,
+    change: row.change,
+  };
+}
+
+function textRow(row: DealerRow) {
+  return { ...reportRow(row), position: `${"  ".repeat(row.depth)}${row.label}` };
+}
+
+function section(title: string, rows: readonly DealerRow[]) {
+  return {
+    title,
+    columns: COLUMNS,
+    rows: rows.map(reportRow),
+    textColumns: TEXT_COLUMNS,
+    textRows: rows.map(textRow),
+    unit: "USD millions",
+    rowSymbolKey: "series",
+    rowAsOfKey: "asOf",
+    interval: "weekly",
+  };
+}
+
+export const primaryDealersHeadless: HeadlessPaneDefinition<"bundle"> = {
+  shape: "bundle",
+  argument: { kind: "none" },
+  options: [],
+  describe: "Primary dealer net positions and settlement fails",
+  freshness: { source: "New York Fed", status: "not-a-feed", basis: "weekly release" },
+  discovery: {
+    aliases: ["PDLR"],
+    dataRequirements: ["Weekly primary dealer positions and settlement fails"],
+    limitations: [
+      "Net positions in Treasuries (bills, coupons by tenor, TIPS, FRN), agencies, MBS, corporates, munis and ABS; settlement fails in Treasuries, TIPS and MBS",
+      "Latest observation and the change from the week before; the weekly history is in the pane",
+    ],
+  },
+  async load() {
+    const board = await fetchPrimaryDealers();
+    return {
+      complete: board.positions.length > 0,
+      sections: [
+        section("Positions", board.positions),
+        section("Fails", board.fails),
+      ],
+      metadata: { asOf: board.asOf, seriesBreak: board.seriesBreak },
+    };
+  },
+};

package/src/plugins/builtin/primary-dealers/index.tsx

@@ -0,0 +1,18 @@
+import type { PluginModule } from "../plugin-module";
+import { fixedIncomeShortcut } from "../fixed-income/shortcut";
+import { primaryDealersHeadless } from "./headless";
+import { PRIMARY_DEALERS_PANE_ID } from "./model";
+
+export const primaryDealersModule: PluginModule = {
+  paneTemplates: [fixedIncomeShortcut({
+    id: "primary-dealers-pane",
+    paneId: PRIMARY_DEALERS_PANE_ID,
+    label: "Primary Dealer Positions",
+    description: "Weekly net positions with history, by sector and Treasury tenor, and settlement fails.",
+    // No "muni": a muni search lands on DVD's muni funds alone (known-gaps.test.ts), not on a table of two functions.
+    keywords: ["primary", "dealer", "dealers", "positions", "fails", "treasury", "bills", "coupons", "tips", "frn", "mbs", "pdlr"],
+    shortcut: { prefix: "PDLR" },
+    headless: primaryDealersHeadless,
+    createInstance: () => ({ placement: "floating" }),
+  }, "treasury", "dealers")],
+};