@gloom-sh/terminal 0.0.0-stage → 0.19.0

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

@@ -0,0 +1,149 @@
+import { logFailure } from "../../../utils/log-failure";
+import { useCallback, useMemo } from "react";
+import type { GasStorageRow } from "../../../api-client/europe-energy";
+import {
+  ChartTableHeader, CompositeChart, MarketBoardStack, PaneStatusBody, spanAxisFormatter, usePaneNoticeFooter, usePaneStatusFooter,
+  type MarketBoardRow, type PaneHint, type StatItem,
+} from "../../../components";
+import { usePaneRefreshKey } from "../../../components/data-table/table-pane";
+import { StatChartDetail } from "../../../components/market-board";
+import { useAsyncResource, useAutoRefresh, usePluginAppActions, usePluginPaneState } from "../../../public/react";
+import { usePaneInstance } from "../../../state/app/context";
+import { blendHex } from "../../../theme/colors";
+import { useThemeColors } from "../../../theme/theme-context";
+import { Box, useRendererHost } from "../../../ui";
+import { getCachedGasStorage, GAS_STORAGE_NOT_AVAILABLE, loadGasHistory, loadGasSeasonal, loadGasStorage, validateGasSeasonal, validateGasStorage } from "./gas-client";
+import {
+  formatGasFlow, formatGasFull, formatGasPoints, formatGasTwh, gasDayText, gasHistorySeries, gasRangeLabel, gasRangePosition,
+  gasSeasonalSeries, gasStorageArea, gasYearAxis,
+} from "./gas-model";
+import { useGasStorageEvidence, type GasStorageSnapshot } from "./evidence";
+
+const PANELS = [{ id: "main" }];
+const formatAxis = spanAxisFormatter((value, digits) => `${value.toFixed(digits)}%`);
+/** One decimal in a legend, so this year, last year and the average fit a phone's width. */
+const formatLegend = (value: number) => `${value.toFixed(1)}%`;
+/** EU first, as the server lists it. */
+const DEFAULT_AREA = "EU";
+
+interface GasBoardRow extends MarketBoardRow { gas: GasStorageRow }
+
+function boardRow(row: GasStorageRow): GasBoardRow {
+  const position = gasRangePosition(row);
+  return {
+    id: row.code, label: row.name, value: row.full, valueText: formatGasFull(row.full),
+    change: row.change, changeText: formatGasPoints(row.change),
+    percentile: position.value, percentileText: position.text,
+    asOf: row.gasDay, asOfText: gasDayText(row), status: row.full == null ? "unavailable" : "available",
+    history: row.trail.map((point) => ({ date: new Date(`${point.date}T00:00:00Z`), close: point.value })),
+    gas: row,
+  };
+}
+
+const column = (id: string, label: string, width: number, value: (row: GasStorageRow) => number | null, format: (value: number | null) => string) => ({
+  column: { id, label, width, align: "right" as const },
+  sortValue: (row: GasBoardRow) => value(row.gas),
+  renderCell: (row: GasBoardRow) => {
+    const current = value(row.gas);
+    return { text: format(current), ...(current != null ? { value: current } : {}) };
+  },
+});
+/** Against the range first, so a narrow board that scrolls still shows it beside the level. */
+const EXTRA_COLUMNS = [
+  column("five", "Vs 5Y", 8, (row) => row.fiveYear?.vsAverage ?? null, formatGasPoints),
+  column("year", "Vs 1Y", 8, (row) => row.yearAgo?.change ?? null, formatGasPoints),
+  column("twh", "TWh", 8, (row) => row.gasInStorage, formatGasTwh),
+  column("injection", "Inj GWh/d", 10, (row) => row.injection, formatGasFlow),
+  column("withdrawal", "Wdr GWh/d", 10, (row) => row.withdrawal, formatGasFlow),
+];
+
+/** An area's figures as of its gas day over its whole kept history. */
+function GasDetail({ row, width, height, focused }: { row: GasStorageRow; width: number; height: number; focused: boolean }) {
+  const colors = useThemeColors();
+  const loader = useCallback((force: boolean) => loadGasHistory(row.code, force), [row.code]);
+  const history = useAsyncResource(loader, { keepPreviousData: true });
+  const series = useMemo(() => history.data ? gasHistorySeries(history.data.payload, colors.positive) : [], [history.data, colors.positive]);
+  const five = row.fiveYear;
+  const items: StatItem[] = [
+    { id: "full", label: "% full", value: formatGasFull(row.full), detail: gasDayText(row) },
+    { id: "twh", label: "TWh", value: formatGasTwh(row.gasInStorage), ...(row.workingGasVolume != null ? { detail: `of ${formatGasTwh(row.workingGasVolume)}` } : {}) },
+    { id: "injection", label: "Inject GWh/d", value: formatGasFlow(row.injection) },
+    { id: "withdrawal", label: "Withdraw GWh/d", value: formatGasFlow(row.withdrawal) },
+    { id: "change", label: "1D pp", value: formatGasPoints(row.change), ...(row.previousGasDay ? { detail: `vs ${row.previousGasDay}` } : {}) },
+    { id: "year", label: "1Y ago %", value: formatGasFull(row.yearAgo?.full), ...(row.yearAgo ? { detail: row.yearAgo.gasDay } : {}) },
+    { id: "range", label: `${gasRangeLabel(five?.years.length ?? 0)} range %`,
+      value: five ? `${formatGasFull(five.min)} to ${formatGasFull(five.max)}` : "--",
+      ...(five ? { detail: `avg ${formatGasFull(five.average)}${five.years.length < 5 ? `, ${five.years.length} of 5 years` : ""}` } : {}) },
+  ];
+  return <StatChartDetail items={items} width={width} height={height} empty={!history.loading && (series[0]?.points.length ?? 0) < 2}
+    emptySubject="gas storage history" emptyTitle={history.error ?? "No gas storage history available."}
+    renderChart={(chartHeight) => <CompositeChart series={series} panels={PANELS} width={width} height={chartHeight} focused={focused}
+      showLegend navigable={false} showTimeAxis formatValue={formatLegend} formatAxisValue={formatAxis} remoteKind="gas-storage-history" />} />;
+}
+
+/**
+ * POWER's Prices tab on its gas board: the EU aggregate and every member
+ * state with storage as of its latest gas day, the selected area's year
+ * against last year and its five-year range above the board, and its whole
+ * kept history in the detail.
+ */
+export function GasStorageView({ width, height, focused, snapshot }: {
+  width: number; height: number; focused: boolean; snapshot: GasStorageSnapshot | null;
+}) {
+  const colors = useThemeColors();
+  const host = useRendererHost();
+  const { createPaneFromTemplate } = usePluginAppActions();
+  // `EPWR GAS DE` opens on the area in the instance params; a saved selection wins.
+  const params = usePaneInstance()?.params;
+  const [selectedId, setSelectedId] = usePluginPaneState<string | null>("power:prices:gas:selected", gasStorageArea(params?.area)?.code ?? null);
+  const [openId, setOpenId] = usePluginPaneState<string | null>("power:prices:gas:open", null);
+  const frozen = useMemo(() => {
+    try {
+      return snapshot ? { board: validateGasStorage(snapshot.board), seasonal: snapshot.seasonal ? validateGasSeasonal(snapshot.seasonal) : null } : null;
+    } catch (error) {
+      logFailure("power.gas", "Validate gas storage snapshot failed")(error);
+      return null;
+    }
+  }, [snapshot]);
+  const resource = useAsyncResource(frozen ? null : loadGasStorage, { initialData: getCachedGasStorage });
+  const board = frozen?.board ?? resource.data?.payload ?? null;
+  const rows = useMemo(() => board?.rows.map(boardRow) ?? [], [board]);
+  const selected = rows.find((row) => row.id === selectedId) ?? rows.find((row) => row.id === DEFAULT_AREA) ?? rows[0];
+  const code = selected?.gas.gasDay ? selected.id : null;
+  const seasonalLoader = useCallback((force: boolean) => loadGasSeasonal(code!, force), [code]);
+  const loaded = useAsyncResource(code && !frozen ? seasonalLoader : null, { keepPreviousData: true });
+  const seasonal = frozen ? frozen.seasonal : loaded.data?.payload ?? null;
+  const seasonalLoading = !frozen && loaded.loading;
+  useGasStorageEvidence(board, useMemo(() => rows.map((row) => row.id), [rows]), (!frozen && resource.loading) || seasonalLoading);
+  useAutoRefresh(resource.updatedAt, resource.load);
+  usePaneRefreshKey(() => { void resource.reload(); void loaded.reload(); }, { focused });
+  const open = rows.find((row) => row.id === openId);
+  const series = useMemo(() => seasonal && seasonal.code === code ? gasSeasonalSeries(seasonal, colors, blendHex) : [], [seasonal, code, colors]);
+  const year = seasonal?.code === code ? seasonal?.year : null;
+  const axis = useMemo(() => year ? gasYearAxis(year) : null, [year]);
+  const cursorDate = useMemo(() => selected?.gas.gasDay ? new Date(`${selected.gas.gasDay}T00:00:00Z`) : null, [selected?.gas.gasDay]);
+  const notAvailable = !board && resource.error === GAS_STORAGE_NOT_AVAILABLE;
+  const hints: PaneHint[] = [
+    ...(board ? [{ id: "source", key: "o", label: `pen ${board.source.name}`, title: "Open the publisher's page",
+      onPress: () => void host.openExternal(board.source.url) }] : []),
+    ...(code ? [{ id: "chart", key: "g", label: "raph", title: "Chart in a custom chart",
+      onPress: () => createPaneFromTemplate("chart-composer-pane", { arg: `CAP:gas-storage:${code.toLowerCase()}` }) }] : []),
+  ];
+  usePaneStatusFooter({ registrationId: "power-gas", loading: (!frozen && resource.loading) || seasonalLoading,
+    error: board ? (frozen ? null : resource.error ?? (open ? null : loaded.error)) : null, stale: !frozen && !!resource.data?.stale, hints });
+  usePaneNoticeFooter({ registrationId: "power-gas:notices", focused,
+    notices: [...(board?.gaps ?? []), ...(!frozen && resource.data?.refreshError ? [resource.data.refreshError] : [])] });
+  return <Box width={width} height={height} flexDirection="column">
+    <PaneStatusBody loading={!frozen && resource.loading && !board} error={!board && !notAvailable ? resource.error : null}
+      empty={notAvailable} emptyTitle={GAS_STORAGE_NOT_AVAILABLE} subject="gas storage" 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}
+          chart={selected ? { series, loading: seasonalLoading && !series.length, empty: `No gas storage range for ${selected.label}`,
+            viewport: axis?.viewport, xAxis: axis?.xAxis, cursorDate, formatValue: formatLegend, formatAxisValue: formatAxis, remoteKind: "gas-storage-seasonal" } : null} />}
+        selectedId={selected?.id ?? null} onSelectedIdChange={setSelectedId} openId={open?.id ?? null} onOpenIdChange={setOpenId}
+        labelHeader="AREA" labelWidth={14} valueLabel="% FULL" valueWidth={8} changeLabel="1D PP" percentileLabel="IN 5Y"
+        asOfWidth={14} extraColumns={EXTRA_COLUMNS} emptyTitle={GAS_STORAGE_NOT_AVAILABLE}
+        renderDetail={(row) => <GasDetail row={row.gas} width={width} height={Math.max(5, height - 2)} focused={focused} />} /> : null}
+    </PaneStatusBody>
+  </Box>;
+}

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

@@ -0,0 +1,37 @@
+import { useMemo } from "react";
+import type { PowerProject } from "../../../api-client/power";
+import { ChartTableHeader, DataTableView, staticSeries, useChartTableSelection, type DataTableColumn } from "../../../components";
+import { usePluginPaneState } from "../../../public/react";
+import { useThemeColors } from "../../../theme/theme-context";
+import { powerNumber } from "./model";
+const MONTHS = ["January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"];
+const COLUMNS: DataTableColumn[] = [{ id: "month", label: "Month", width: 18, align: "left", flexGrow: 1 }, { id: "mwh", label: "Generation MWh", width: 20, align: "right" }, { id: "change", label: "Change MWh", width: 20, align: "right" }];
+export function generationRows(project: PowerProject) {
+  if (!/^\d{4}$/.test(project.period ?? "")) return [];
+  let previous: number | null = null;
+  return MONTHS.map((month, index) => {
+    const raw = project.metrics[`generation${month}Mwh`];
+    const value = typeof raw === "number" && Number.isFinite(raw) ? raw : null;
+    const change = value === null || previous === null ? null : value - previous;
+    previous = value;
+    return { id: `${project.period}-${String(index + 1).padStart(2, "0")}`, date: new Date(Date.UTC(Number(project.period), index, 1)), month, value, change };
+  });
+}
+const rowId = (row: ReturnType<typeof generationRows>[number]) => row.id;
+const rowDate = (row: ReturnType<typeof generationRows>[number]) => row.date;
+export function PowerGeneration({ project, width, height, focused }: { project: PowerProject; width: number; height: number; focused: boolean }) {
+  const colors = useThemeColors();
+  const rows = useMemo(() => generationRows(project), [project]);
+  const [selectedId, setSelectedId] = usePluginPaneState<string | null>("power:generation-month", null);
+  const selected = rows.find((row) => row.id === selectedId) ?? rows.at(-1);
+  const selection = useChartTableSelection({ rows, getId: rowId, getDate: rowDate, selectedId: selected?.id ?? null, onSelect: setSelectedId, focused });
+  const series = useMemo(() => [{ ...staticSeries(rows.map((row) => ({ date: row.date, observedAt: new Date(project.observedAt), value: row.value })),
+    { id: "power-generation", label: `${project.period} net generation`, color: colors.warning, negativeColor: colors.negative, style: "columns", calendarSpaced: true }), unit: "MWh", unitGroup: "power-energy" }], [rows, project.observedAt, project.period, colors.warning, colors.negative]);
+  return <DataTableView columns={COLUMNS} items={rows} getItemKey={rowId} rootWidth={width} rootHeight={height} focused={focused}
+    selection={{ kind: "id", getId: rowId, selectedId: selected?.id ?? null, onChange: setSelectedId }}
+    emptyStateTitle="No monthly generation reported." sortColumnId={null} sortDirection="asc" renderCell={(row, column) => column.id === "month" ? { text: row.month, value: row.id }
+      : { text: powerNumber(column.id === "mwh" ? row.value : row.change), value: (column.id === "mwh" ? row.value : row.change) ?? undefined }}
+    rootBefore={<ChartTableHeader width={width} height={height} tableRows={rows.length} tableColumns={COLUMNS}
+      figures={[{ id: "annual", label: `${project.period} MWh`, value: powerNumber(typeof project.metrics.generationMwh === "number" ? project.metrics.generationMwh : null) }]}
+      chart={{ series, ...selection, formatValue: (value) => `${powerNumber(value)} MWh`, remoteKind: "power-monthly-generation" }} />} />;
+}

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

@@ -0,0 +1,116 @@
+import type { DataTableColumn } from "../../../components";
+import type { HeadlessPaneColumn, HeadlessPaneDefinition, HeadlessPaneRow } from "../../../types/plugin";
+import { withoutQuietColumns } from "../shared/research-cells";
+import { fetchPowerBoard, fetchAllPowerHistory, fetchPowerTickerScopes } from "./client";
+import { powerQuery } from "./query";
+import { loadPowerPricesReport } from "./prices-headless";
+import { isCarbonQuery, powerPriceMarket } from "./prices-model";
+import {
+  COVERAGE_COLUMNS, EXPOSURE_COLUMNS, GENERATION_COLUMNS, HISTORY_COLUMNS, POWER_TABS, PROJECT_COLUMNS, RATE_COLUMNS, UTILITY_COLUMNS,
+  historyRows, powerCoverageNote, powerLoadedSources, powerNumber, powerPercent, powerRegion, powerScopeOptions, powerTab, powerTickerEmpty, projectRows, tickerLabel, titleCase, UNMAPPED, type PowerTab,
+} from "./model";
+
+/** `GAS DE` and the like go to the gas board, which says so when it does not list the area. */
+const isGasQuery = (input: string | undefined) => /^(?:gas|storage)\b/i.test(input?.trim() ?? "");
+
+/** Bars the pane draws beside the numbers they are made of; the report has the numbers. */
+const GRAPHIC_COLUMNS = new Set(["outcome", "pipeline"]);
+/** Columns that only repeat a default on every row, as the pane leaves them out. */
+const QUIET_COLUMNS: Record<string, readonly string[]> = { scope: ["Project"], unknownCapacity: ["0"], unknown: ["0"], fuel: ["Load"], role: ["Direct"], kind: ["Queue"] };
+const text = (value: unknown) => value == null || value === "" ? "-" : String(value);
+const coded = (value: unknown) => typeof value === "string" && value ? titleCase(value) : "-";
+
+/**
+ * The pane's columns for a tab, printed as the pane prints them: MW and MWh
+ * to a tenth with thousands separators, rates as percentages, register codes
+ * by name, and each record's listed company or "unmapped". Raw metrics and
+ * evidence stay in the exported rows, out of the table.
+ */
+function reportColumns(tab: PowerTab, context: unknown): HeadlessPaneColumn[] {
+  const columns: DataTableColumn[] = tab === "capacity" && context === "generation" ? GENERATION_COLUMNS : tab === "capacity" && context === "utility" ? UTILITY_COLUMNS
+    : ["queue", "loads", "capacity"].includes(tab) ? PROJECT_COLUMNS : tab === "history" ? HISTORY_COLUMNS : tab === "outcomes" ? RATE_COLUMNS : tab === "utilities" ? EXPOSURE_COLUMNS : COVERAGE_COLUMNS;
+  // The coverage list names its register by its own id; everything else by the record's source.
+  const region = (value: unknown, row: HeadlessPaneRow) => typeof value !== "string" ? "-"
+    : tab === "utilities" ? value : powerRegion(value, String((tab === "coverage" ? row.id : row.sourceId) ?? ""));
+  const format = (column: DataTableColumn): HeadlessPaneColumn["format"] => {
+    if (column.id === "region") return region;
+    if (["fuel", "status", "kind", "role"].includes(column.id)) return coded;
+    if (column.id === "ticker") return (value) => typeof value === "string" && value ? value : UNMAPPED;
+    if (column.id === "developer") return (value, row) => text(value ?? row.utility);
+    if (column.id === "observedAt") return (value) => typeof value === "string" ? value.slice(0, 16).replace("T", " ") : "-";
+    if (/Rate$/.test(column.id)) return (value) => typeof value === "number" ? powerPercent(value) : "-";
+    if (column.align === "right") return (value) => typeof value === "number" ? `${column.id === "changeMw" && value > 0 ? "+" : ""}${powerNumber(value)}` : "-";
+    return text;
+  };
+  // The pane groups outcomes under region headings; the report names the region on each row.
+  return [...(tab === "outcomes" ? [{ id: "region", label: "Region", width: 16, align: "left" as const }] : []), ...columns].filter((column) => !GRAPHIC_COLUMNS.has(column.id))
+    .map((column) => ({ key: column.id, header: column.label, align: column.align === "right" ? "right" as const : "left" as const, format: format(column) }));
+}
+
+export const powerHeadless: HeadlessPaneDefinition<"bundle"> = {
+  shape: "bundle",
+  freshness: { source: "Grid operator queues and utility filings", status: "not-a-feed", basis: "published records", dataset: true },
+  argument: { kind: "free-text", optional: true, placeholder: "ticker", description: "Optional listed developer or utility ticker, with exchange suffix where needed." },
+  options: [
+    { key: "tab", type: "enum", settingKey: "tab", defaultValue: "queue", values: POWER_TABS.map(({ value }) => ({ value })), description: "Queue, history, outcomes, large loads, utility exposure, capacity, European day-ahead prices or coverage." },
+    ...["country", "region", "fuel", "status", "search", "sourceId", "from", "to"].map((key) => ({ key, type: "string" as const, settingKey: key, description: `Filter by ${key}.` })),
+    { key: "context", type: "enum", settingKey: "context", values: [{ value: "capacity" }, { value: "generation" }, { value: "utility" }], defaultValue: "capacity", description: "Generation capacity, monthly generation or utility context on the Capacity tab." },
+    { key: "loadClass", aliases: ["load-class"], type: "enum", settingKey: "loadClass", values: [{ value: "datacenter" }], description: "Only loads explicitly classified as datacenters." },
+    { key: "historical", type: "boolean", settingKey: "historical", defaultValue: false, description: "Use historical benchmark queues separately from direct observations." },
+  ],
+  discovery: { aliases: ["POWER"], dataRequirements: ["Gloom Cloud power queues and large-load disclosures"],
+    limitations: ["Pro dataset; free accounts see three rows per section and limited history.", "Proposed projects are not committed supply; requests and approvals are distinct.", "Coverage varies by jurisdiction; missing MW and unavailable sources remain explicit."] },
+  describe: "Power queues, large loads and utility exposure (Pro)",
+  async load(args, ctx) {
+    const tab = powerTab(args.options.tab);
+    const symbol = (Array.isArray(args.argument) ? args.argument.join(" ") : args.argument)?.trim();
+    // Prices are their own board (EPWR); a typed market narrows it, a ticker does not apply.
+    if (tab === "prices") return loadPowerPricesReport(powerPriceMarket(symbol) || isCarbonQuery(symbol) || isGasQuery(symbol) ? symbol : undefined, ctx.apiClient);
+    const filter = { ...powerQuery(args.options, symbol), limit: 500 };
+    const board = await fetchPowerBoard(filter, ctx.apiClient);
+    const projects = [...board.projects];
+    const ids = new Set(projects.map((row) => row.id));
+    let offset = board.nextOffset;
+    let hasMore = board.hasMore;
+    // Export traverses every page; a stuck cursor fails visibly instead of silently truncating.
+    while (["queue", "loads", "capacity"].includes(tab) && hasMore) {
+      if (offset === null || offset < projects.length) throw new Error("Power pagination did not advance.");
+      const page = await fetchPowerBoard({ ...filter, offset }, ctx.apiClient);
+      if (page.hasMore && (page.nextOffset === null || page.nextOffset <= offset)) throw new Error("Power pagination did not advance.");
+      if (page.projects.some((row) => ids.has(row.id))) throw new Error("Power records changed during export; retry the request.");
+      for (const row of page.projects) ids.add(row.id);
+      projects.push(...page.projects); offset = page.nextOffset; hasMore = page.hasMore;
+    }
+    const history = tab === "history" ? await fetchAllPowerHistory(filter, ctx.apiClient) : null;
+    // Exported rows keep every field the server sent; the pane's derived cells (the ticker map, location, scope) ride beside them.
+    const cells = projectRows(projects);
+    const rows: HeadlessPaneRow[] = tab === "history" ? historyRows(history!.points).map((point) => ({ ...point, date: point.basis === "published" ? point.period : point.observedAt.slice(0, 16).replace("T", " ") }))
+      : tab === "outcomes" ? board.rates.map((rate) => ({ ...rate }))
+        : tab === "utilities" ? board.exposure.map((exposure) => ({ ...exposure, ticker: tickerLabel(exposure) }))
+          : tab === "coverage" ? board.coverage.map((coverage) => ({ ...coverage }))
+            : projects.map((project, index) => {
+              const { ticker, location, scope, generationMwh, summerPeakDemandMw, winterPeakDemandMw, salesMwh, revenueUsd } = cells[index]!.cells;
+              return { ...project, ticker, location, scope, generationMwh, summerPeakDemandMw, winterPeakDemandMw, salesMwh, revenueUsd };
+            });
+    const locked = history?.locked ?? (tab === "outcomes" ? board.locked.rates : tab === "utilities" ? board.locked.exposure : tab === "coverage" ? 0 : board.locked.projects);
+    const columns = reportColumns(tab, args.options.context);
+    const shown = withoutQuietColumns(columns.map((column) => ({ id: column.key, label: column.header, width: 0, align: "left" as const })), rows,
+      (row, id) => columns.find((column) => column.key === id)!.format!(row[id], row), QUIET_COLUMNS).map((column) => column.id);
+    // A ticker with nothing on this tab says where its records are instead; a narrower filter is the filters' doing.
+    const narrowed = ["country", "region", "fuel", "status", "search", "sourceId", "from", "to", "loadClass", "historical"].some((key) => !!args.options[key]);
+    const empty = !rows.length && symbol && !narrowed && tab !== "coverage" ? await fetchPowerTickerScopes(symbol, tab, String(args.options.context ?? "capacity"), ctx.apiClient)
+      .then((scopes) => {
+        const message = powerTickerEmpty(symbol, tab, String(args.options.context ?? "capacity"), scopes);
+        const where = message.found.map((scope) => `${powerNumber(scope.total)} ${scope.label} (${powerScopeOptions(scope)})`).join(", ");
+        const loaded = powerLoadedSources(tab, board.coverage);
+        return [message.title, where ? `${symbol} has ${where}.` : message.hint?.replace(/\.$/, " (--search <name>)."),
+          loaded ? `Sources loaded now: ${loaded}.` : null].filter(Boolean).join(" ");
+      }) : "No reported records match these filters.";
+    // Missing or unsupported sources are coverage, not failures: one plain line, details in --tab coverage.
+    const coverageNote = tab === "capacity" ? null : powerCoverageNote(board.coverage);
+    return { complete: locked === 0, sections: [{ title: POWER_TABS.find((t) => t.value === tab)!.label, columns: columns.filter((column) => shown.includes(column.key)), rows, empty }],
+      metadata: { generatedAt: board.generatedAt, access: board.access, locked, total: board.total, units: "MW unless specified", filters: filter, aggregates: board.aggregates, coverage: board.coverage },
+      ...(coverageNote ? { notes: [coverageNote] } : {}),
+      ...(locked ? { errors: ["Additional records and history need Gloom Pro."] } : {}) };
+  },
+};

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

@@ -0,0 +1,51 @@
+import type { PaneTemplateInstanceConfig } from "../../../types/plugin";
+import type { PluginModule } from "../plugin-module";
+import { powerBoardCache, powerDetailCache, powerHistoryCache } from "./client";
+import { powerHeadless } from "./headless";
+import { PowerPane } from "./pane";
+import { carbonHistoryCache, carbonPriceCache, powerPriceHistoryCache, powerPricesCache } from "./prices-client";
+import { powerPricesHeadless } from "./prices-headless";
+import { CARBON_SELECTION, CARBON_SERIES, DAY_AHEAD_SERIES, isCarbonQuery, POWER_PRICE_MARKETS, powerPriceMarket } from "./prices-model";
+import { gasHistoryCache, gasSeasonalCache, gasStorageCache } from "./gas-client";
+import { GAS_STORAGE_AREAS, GAS_STORAGE_SERIES, parseGasQuery } from "./gas-model";
+
+const CACHES = [powerBoardCache, powerHistoryCache, powerDetailCache, powerPricesCache, powerPriceHistoryCache, carbonPriceCache, carbonHistoryCache,
+  gasStorageCache, gasHistoryCache, gasSeasonalCache];
+
+export const powerModule: PluginModule = {
+  series: [...DAY_AHEAD_SERIES, ...CARBON_SERIES, ...GAS_STORAGE_SERIES],
+  // POWER sets the symbol param, EPWR the prices tab.
+  panes: [{ id: "power", name: "Power & Grid", icon: "P", component: PowerPane, defaultPosition: "right", defaultMode: "floating", identitySettings: ["tab", "symbol"],
+    defaultFloatingSize: { width: 132, height: 34 }, tableExport: true, headless: powerHeadless }],
+  paneTemplates: [{ id: "power-pane", paneId: "power", label: "Power & Grid",
+    description: "Pro: interconnection queues, historical MW and outcomes, datacenter loads, utility exposure and generation capacity, with primary evidence.",
+    keywords: ["power", "electricity", "interconnection", "grid", "datacenter", "utility", "renewables", "storage", "capacity"],
+    shortcut: { prefix: "POWER", argKind: "text", argPlaceholder: "ticker", argOptional: true }, headless: powerHeadless,
+    createInstance: (_context, options) => {
+      const symbol = options?.symbol ?? options?.arg?.trim().toUpperCase() ?? "";
+      return { placement: "floating", params: { symbol }, ...(symbol ? { title: `POWER ${symbol}` } : {}) };
+    } }, {
+    id: "power-prices-pane", paneId: "power", label: "EU Power, Carbon & Gas",
+    description: "Day-ahead power prices for 32 European markets in EUR/MWh, the EU carbon allowance (EUA) auction price in EUR/tCO2, and European gas storage: % full, TWh and daily injection and withdrawal for the EU and each member state against a year ago and the five-year range.",
+    keywords: ["day-ahead", "day ahead", "power price", "power prices", "electricity price", "electricity prices", "wholesale power",
+      "spot power", "baseload", "europe", "european", "eur/mwh", "carbon", "eu carbon", "eua", "eu ets", "carbon price",
+      "carbon allowance", "emission allowances", "co2", "eur/tco2", "gas storage", "european gas storage", "eu gas storage",
+      "gas inventories", "storage fullness", "filling level", "agsi", "injection", "withdrawal"],
+    shortcut: { prefix: "EPWR", argKind: "text", argPlaceholder: "market", argOptional: true,
+      argOptions: () => [{ value: "EUA", label: "EU carbon allowance" }, ...POWER_PRICE_MARKETS.map(({ code, name }) => ({ value: code, label: name })),
+        ...GAS_STORAGE_AREAS.map(({ code, name }) => ({ value: code === "EU" ? "GAS" : `GAS ${code}`, label: `${name} gas storage` }))] },
+    headless: powerPricesHeadless,
+    createInstance: (_context, options): PaneTemplateInstanceConfig => {
+      const input = options?.arg?.trim();
+      // EPWR GAS opens the gas board, on the EU or the area named after it.
+      const gas = parseGasQuery(input);
+      if (gas) return { placement: "floating", settings: { tab: "prices" }, params: { board: "gas", area: gas.area.code } };
+      const market = powerPriceMarket(input);
+      // EPWR EUA opens the tab with the carbon allowance charted above the board.
+      const carbon = isCarbonQuery(input);
+      if (input && !market && !carbon) throw new Error("Use a market such as DE, FR, GB or Spain, EUA, or GAS for gas storage");
+      return { placement: "floating", settings: { tab: "prices" }, ...(market || carbon ? { params: { market: market?.code ?? CARBON_SELECTION } } : {}) };
+    } }],
+  setup(ctx) { for (const cache of CACHES) cache.attach(ctx.persistence); },
+  dispose() { for (const cache of CACHES) cache.reset(); },
+};

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

@@ -0,0 +1,160 @@
+import type { PowerAggregate, PowerBoard, PowerCoverage, PowerExposure, PowerHistoryPoint, PowerProject, PowerRates } from "../../../api-client/power";
+import { staticSeries, type DataTableColumn } from "../../../components";
+
+export const POWER_TABS = [{ value: "queue", label: "Queue" }, { value: "history", label: "History" }, { value: "outcomes", label: "Outcomes" },
+  { value: "loads", label: "Loads" }, { value: "utilities", label: "Utilities" }, { value: "capacity", label: "Capacity" }, { value: "prices", label: "Prices" }, { value: "coverage", label: "Coverage" }] as const;
+export type PowerTab = typeof POWER_TABS[number]["value"];
+export const powerTab = (value: unknown): PowerTab => POWER_TABS.find((tab) => tab.value === value)?.value ?? "queue";
+const REGISTERS: Record<string, string> = { "neso-tec": "GB transmission", "neso-embedded": "GB embedded", "neso-interconnector": "GB interconnectors" };
+const REGIONS: Record<string, string> = { LBNL: "US project queues", "LBNL-ANNUAL": "US annual queues", EIA860: "US generation capacity", EIA861: "US utilities", EIA923: "US generation output" };
+export const powerRegion = (value: string, sourceId?: string) => REGISTERS[sourceId ?? ""] ?? REGIONS[value] ?? value;
+/** A source with stored records, even when its latest refresh failed. */
+const loadedSource = (c: PowerCoverage) => (c.status === "current" || c.status === "stale") && c.records > 0;
+const names = (rows: readonly PowerCoverage[]) => [...new Set(rows.map((c) => c.region === "EirGrid" ? "Ireland" : c.region))].join(", ");
+/**
+ * Which US grid operators' queues loaded, in plain words. Source errors and
+ * unsupported registers stay in the Coverage tab and on the server; a missing
+ * queue is a gap in coverage, never zero.
+ */
+export function powerCoverageNote(coverage: readonly PowerCoverage[]): string | null {
+  const queues = coverage.filter((c) => c.country === "US" && c.role === "direct" && c.kind === "queue");
+  const missing = queues.filter((c) => !loadedSource(c));
+  if (!missing.length) return null;
+  const loaded = queues.filter(loadedSource);
+  return `US queues: ${loaded.length ? `${names(loaded)} loaded; ` : ""}${names(missing)} not available`;
+}
+/**
+ * The registers carrying records right now, named, for a ticker that has none
+ * in them: grid operator and TSO registers, or the EIA filings behind the
+ * Capacity tab. Null when nothing is loaded.
+ */
+export function powerLoadedSources(tab: PowerTab, coverage: readonly PowerCoverage[]): string | null {
+  const loaded = coverage.filter((c) => loadedSource(c) && (tab === "capacity" ? c.role === "context" : c.role === "direct"));
+  if (!loaded.length) return null;
+  return tab === "capacity" ? "US EIA generation and utility filings" : names([...loaded.filter((c) => c.country === "US"), ...loaded.filter((c) => c.country !== "US")]);
+}
+export const titleCase = (value: string) => value.replace(/(^|[ _-])\w/g, (match) => match.toUpperCase());
+export const powerNumber = (n: number | null | undefined) => n == null ? "--" : n.toLocaleString("en-US", { maximumFractionDigits: 1 });
+export const powerPercent = (n: number | null) => n == null ? "--" : `${(n * 100).toFixed(1)}%`;
+/** The listed companies a record names, or null when its register names none: the ticker map. */
+export const tickerLabel = (row: { entities: PowerProject["entities"] }) => [...new Set(row.entities.flatMap((e) => e.tickers.map((t) => t.ticker)))].join(", ") || null;
+/** What the ticker column says for a record no listed company is mapped to. */
+export const UNMAPPED = "unmapped";
+
+/** Where else a ticker's records can sit: each tab, and the capacity tab's contexts, with what they list. */
+const POWER_TICKER_SCOPES = [
+  { tab: "queue", context: "capacity", label: "interconnection queue records", view: "Queue" },
+  { tab: "loads", context: "capacity", label: "large-load requests", view: "Loads" },
+  { tab: "capacity", context: "capacity", label: "generation capacity records", view: "Capacity" },
+  { tab: "capacity", context: "generation", label: "monthly generation records", view: "Generation" },
+  { tab: "capacity", context: "utility", label: "utility sales records", view: "Utility sales" },
+] as const satisfies readonly { tab: PowerTab; context: string; label: string; view: string }[];
+/** `total` is null for a scope that did not answer, which is no evidence either way. */
+export type PowerTickerScope = (typeof POWER_TICKER_SCOPES)[number] & { total: number | null };
+const sameScope = (scope: { tab: string; context: string }, tab: PowerTab, context: string) =>
+  scope.tab === tab && (tab !== "capacity" || scope.context === context)
+  // Utilities are the large loads summed by utility: a ticker with no loads has no exposure either.
+  || tab === "utilities" && scope.tab === "loads";
+/** The scopes to count a ticker's records in when the open tab has none of them. */
+export const powerTickerScopes = (tab: PowerTab, context: string) => POWER_TICKER_SCOPES.filter((scope) => !sameScope(scope, tab, context));
+
+/** What the open tab lists, for the sentence that says none of it maps to a ticker. */
+function powerTabRecords(tab: PowerTab, context: string): string {
+  if (tab === "capacity") return POWER_TICKER_SCOPES.find((scope) => scope.tab === "capacity" && scope.context === context)?.label ?? "capacity records";
+  return { queue: "interconnection queue records", history: "queue history records", outcomes: "queue outcomes", loads: "large-load requests",
+    utilities: "large-load requests or utility exposure", prices: "records", coverage: "records" }[tab];
+}
+
+/**
+ * Why a ticker's tab is empty, and where its records are instead: the title
+ * says what does not map to it, the hint where it has records, or, once every
+ * other tab has answered with none, that a name search is what is left.
+ */
+export function powerTickerEmpty(symbol: string, tab: PowerTab, context: string, scopes: readonly PowerTickerScope[]) {
+  const found = scopes.filter((scope): scope is PowerTickerScope & { total: number } => (scope.total ?? 0) > 0);
+  const answered = scopes.length > 0 && scopes.every((scope) => scope.total != null);
+  return {
+    title: `No ${powerTabRecords(tab, context)} map to ${symbol}.`,
+    found,
+    hint: found.length ? `${symbol} has ${found.map((scope) => `${powerNumber(scope.total)} ${scope.label}`).join(", ")}.`
+      : answered ? `No power records map to ${symbol}; search by the company's or a subsidiary's name instead.` : null,
+  };
+}
+/** The options that open a scope from the command line. */
+export const powerScopeOptions = (scope: { tab: string; context: string }) =>
+  scope.tab === "capacity" && scope.context !== "capacity" ? `--tab capacity --context ${scope.context}` : `--tab ${scope.tab}`;
+const historyKey = (p: PowerHistoryPoint) => JSON.stringify([p.sourceId, p.country, p.region, p.kind, p.fuel, p.status, p.historical, p.basis]);
+/** Annual benchmarks use their stated period. Current queues use when we observed them, never a proposed completion date. */
+export function historyDate(p: PowerHistoryPoint): Date {
+  if (p.basis === "published" && p.period) {
+    const period = /^\d{4}$/.test(p.period) ? `${p.period}-12-31` : p.period;
+    if (Number.isFinite(Date.parse(period))) return new Date(period);
+  }
+  return new Date(p.observedAt);
+}
+export const historyId = (p: PowerHistoryPoint) => `${historyKey(p)}:${p.observedAt}:${p.period ?? ""}`;
+export type HistoryRow = PowerHistoryPoint & { changeMw: number | null };
+export function historyRows(points: readonly PowerHistoryPoint[]): HistoryRow[] {
+  const previous = new Map<string, number | null>();
+  return [...points].sort((a, b) => historyDate(a).getTime() - historyDate(b).getTime()).map((p) => {
+    const key = historyKey(p); const last = previous.get(key); previous.set(key, p.unknownCapacity ? null : p.capacityMw);
+    return { ...p, changeMw: last == null || p.unknownCapacity ? null : p.capacityMw - last };
+  }).reverse();
+}
+export function historySeries(points: readonly PowerHistoryPoint[], selected: PowerHistoryPoint | undefined, color: string) {
+  if (!selected) return [];
+  const rows = points.filter((p) => historyKey(p) === historyKey(selected)).sort((a, b) => historyDate(a).getTime() - historyDate(b).getTime());
+  if (new Set(rows.filter((p) => p.unknownCapacity === 0).map((p) => historyDate(p).getTime())).size < 3) return [];
+  return [{ ...staticSeries(rows.map((p) => ({ date: historyDate(p), observedAt: new Date(p.observedAt), value: p.unknownCapacity ? null : p.capacityMw })),
+    { id: historyKey(selected), label: `${powerRegion(selected.region, selected.sourceId)} ${titleCase(selected.fuel)} ${titleCase(selected.status)}`, color, style: "step", calendarSpaced: true }),
+    unit: "MW", unitGroup: "power-mw", interpolation: "step-after" as const }];
+}
+const col = (id: string, label: string, width: number, numeric = false, flexGrow?: number): DataTableColumn => ({ id, label, width, align: numeric ? "right" : "left", ...(flexGrow ? { flexGrow } : {}) });
+export const PROJECT_COLUMNS = [col("name", "Project / area", 30, false, 1), col("capacityMw", "MW", 11, true), col("region", "Region", 16), col("fuel", "Fuel", 10), col("status", "Status", 11), col("scope", "Record scope", 18), col("ticker", "Ticker", 13), col("developer", "Developer / utility", 26), col("location", "Location", 24), col("proposedDate", "Proposed service", 17), col("asOf", "As of", 12)];
+export const GENERATION_COLUMNS = [col("name", "Plant / generator", 30, false, 1), col("generationMwh", "Generation MWh", 18, true), col("period", "Period", 9), col("fuel", "Fuel", 11), col("region", "Region", 12), col("ticker", "Ticker", 12), col("developer", "Operator", 25), col("location", "Location", 20)];
+export const UTILITY_COLUMNS = [col("name", "Utility", 30, false, 1), col("summerPeakDemandMw", "Summer peak MW", 17, true), col("winterPeakDemandMw", "Winter peak MW", 17, true), col("salesMwh", "Sales MWh", 17, true), col("revenueUsd", "Retail revenue USD", 20, true), col("generationMwh", "Generation MWh", 18, true), col("period", "Period", 9), col("ticker", "Ticker", 12), col("location", "Location", 20)];
+export const HISTORY_COLUMNS = [col("date", "Observed / period", 20), col("region", "Region", 15, false, 1), col("fuel", "Fuel", 11), col("status", "Status", 12), col("capacityMw", "MW", 13, true), col("changeMw", "Change MW", 13, true), col("projects", "Records", 9, true), col("unknownCapacity", "Missing MW records", 19, true)];
+// Outcomes are grouped by region, so the cohort leads; the bar shows how each cohort ended.
+export const RATE_COLUMNS = [col("cohort", "Entry cohort", 14), col("outcome", "Completed · active · withdrawn", 34, false, 1), col("projects", "Projects", 10, true), col("completed", "Completed", 11, true), col("withdrawn", "Withdrawn", 11, true), col("active", "Active", 10, true), col("completionRate", "Complete %", 12, true), col("withdrawalRate", "Withdraw %", 12, true), col("unknown", "Other", 10, true)];
+export const EXPOSURE_COLUMNS = [col("utility", "Utility / grid", 28, false, 1), col("region", "Region", 9), col("pipeline", "Operating · approved · requested", 34), col("requestedMw", "Requested MW", 15, true), col("approvedMw", "Approved MW", 14, true), col("operatingMw", "Operating MW", 14, true), col("requests", "Records", 9, true), col("ticker", "Ticker", 10), col("unknownCapacity", "Missing MW records", 19, true)];
+export const COVERAGE_COLUMNS = [col("region", "Region", 20, false, 1), col("country", "Country", 9), col("kind", "Dataset", 12), col("role", "Scope", 12), col("status", "State", 12), col("asOf", "As of", 12), col("observedAt", "Observed UTC", 19), col("records", "Records", 11, true)];
+export type PowerRow = { id: string; label: string; cells: Record<string, string | number | null>; project?: PowerProject; history?: HistoryRow; rate?: PowerRates; exposure?: PowerExposure; coverage?: PowerCoverage; locked?: boolean;
+  /** A region heading in the outcomes table; never selected or exported. */ section?: { count: number } };
+export function projectRows(rows: readonly PowerProject[]): PowerRow[] {
+  return rows.map((p) => ({ id: p.id, label: p.name, project: p, cells: { name: p.name, capacityMw: p.capacityMw, region: powerRegion(p.region, p.sourceId),
+    fuel: titleCase(p.fuel), scope: p.metrics.aggregationLevel === "region" ? "Regional summary" : titleCase(String(p.metrics.aggregationLevel ?? "project").replaceAll("_", " ")), status: titleCase(p.status), ticker: tickerLabel(p), developer: p.developer ?? p.utility,
+    generationMwh: typeof p.metrics.generationMwh === "number" ? p.metrics.generationMwh : null,
+    summerPeakDemandMw: typeof p.metrics.summerPeakDemandMw === "number" ? p.metrics.summerPeakDemandMw : null,
+    winterPeakDemandMw: typeof p.metrics.winterPeakDemandMw === "number" ? p.metrics.winterPeakDemandMw : null,
+    salesMwh: typeof p.metrics.salesMwh === "number" ? p.metrics.salesMwh : null,
+    revenueUsd: typeof p.metrics.revenueUsd === "number" ? p.metrics.revenueUsd : null, period: p.period,
+    location: [p.county, p.state, p.country].filter(Boolean).join(", "), proposedDate: p.proposedDate, asOf: p.asOf } }));
+}
+export function otherRows(tab: PowerTab, board: PowerBoard, history: readonly PowerHistoryPoint[]): PowerRow[] {
+  if (tab === "history") return historyRows(history).map((p) => ({ id: historyId(p), label: `${p.region} ${titleCase(p.fuel)} ${titleCase(p.status)}`, history: p,
+    cells: { date: p.basis === "published" ? p.period : p.observedAt.slice(0, 16).replace("T", " "), region: powerRegion(p.region, p.sourceId), fuel: titleCase(p.fuel), status: titleCase(p.status),
+      capacityMw: p.capacityMw, changeMw: p.changeMw, projects: p.projects, unknownCapacity: p.unknownCapacity } }));
+  if (tab === "outcomes") {
+    const regions = new Map<string, PowerRates[]>();
+    for (const r of board.rates) { const region = powerRegion(r.region, r.sourceId); regions.set(region, [...(regions.get(region) ?? []), r]); }
+    return [...regions].flatMap(([region, rates]) => [{ id: `section:${region}`, label: region, cells: {}, section: { count: rates.length } },
+      ...rates.map((r) => ({ id: JSON.stringify([r.sourceId, r.country, r.region, r.cohort]), label: `${r.region} · ${r.cohort}`, rate: r, coverage: board.coverage.find((c) => c.id === r.sourceId), cells: { region, country: r.country, cohort: r.cohort, outcome: r.projects, projects: r.projects, completed: r.completed, withdrawn: r.withdrawn, active: r.active, unknown: r.unknown, completionRate: r.completionRate, withdrawalRate: r.withdrawalRate } }))]);
+  }
+  if (tab === "utilities") return board.exposure.map((r) => ({ id: JSON.stringify([r.sourceId, r.country, r.region, r.utility]), label: r.utility, exposure: r,
+    cells: { utility: r.utility, country: r.country, region: r.region, requestedMw: r.requestedMw, approvedMw: r.approvedMw, operatingMw: r.operatingMw,
+      requests: r.requests, unknownCapacity: r.unknownCapacity, ticker: tickerLabel(r), pipeline: r.requestedMw } }));
+  return board.coverage.map((r) => ({ id: r.id, label: `${powerRegion(r.region)} ${titleCase(r.kind)}`, coverage: r,
+    cells: { country: r.country, region: powerRegion(r.region, r.id), kind: titleCase(r.kind), role: titleCase(r.role), status: titleCase(r.status), asOf: r.asOf,
+      observedAt: r.observedAt?.slice(0, 16).replace("T", " ") ?? null, records: r.records } }));
+}
+export function powerFigures(aggregates: readonly PowerAggregate[]) {
+  const sum = (status?: string) => aggregates.filter((a) => !status || a.status === status).reduce((n, a) => n + a.capacityMw, 0);
+  const unknown = aggregates.reduce((n, a) => n + a.unknownCapacity, 0);
+  return [
+    { id: "mw", label: "Reported MW", value: powerNumber(sum()) },
+    { id: "active", label: "Active MW", value: powerNumber(sum("active")) },
+    { id: "completed", label: "Completed MW", value: powerNumber(sum("completed")) },
+    { id: "withdrawn", label: "Withdrawn MW", value: powerNumber(sum("withdrawn")) },
+    ...(unknown ? [{ id: "unknown", label: "Missing MW", value: powerNumber(unknown), detail: "records" }] : []),
+  ];
+}