@gloom-sh/terminal 0.0.0-stage → 0.18.5

package/src/plugins/builtin/attention/pane.tsx

@@ -0,0 +1,219 @@
+import { useCallback, useMemo } from "react";
+import { isAccessDenied } from "../../../api-client/errors";
+import { usePlanAccess } from "../../../api-client/plan-access";
+import type { AttentionGroup, AttentionPayload, AttentionPoint, AttentionRow } from "../../../api-client/attention";
+import { ActionRow, ChartTableHeader, DataTableView, EmptyState, KeyValueRow, PaneStatusBody, QueryBar, SectionHeading,
+  useChartTableSelection, usePaneNoticeFooter, usePaneStatusFooter, usePaneTabs, useQueryBarSearch, type DataTableCell, type DataTableColumn, type PaneHint, type StatItem } from "../../../components";
+import { staticSeries } from "../../../components/chart/static/series";
+import { usePaneRefreshKey } from "../../../components/data-table/table-pane";
+import { useAsyncResource, useAutoRefresh, usePaneSettingValue, usePluginAppActions, usePluginPaneState } from "../../../public/react";
+import { useThemeColors } from "../../../theme/theme-context";
+import type { PaneProps } from "../../../types/plugin";
+import { Box, ScrollBox, Text, TextAttributes, useRendererHost, useUiCapabilities } from "../../../ui";
+import { withCountryFlag } from "../../../components/ui/country-flag";
+import { SignInWall } from "../cloud/auth-actions";
+import { CLOUD_PLAN_KEY, useCloudUpgradeAction } from "../shared/cloud-upgrade";
+import { useOpenDescription } from "../shared/open-description";
+import { Blurred, LockedOverlay } from "../shared/locked-rows";
+import { isCloudSessionRequired, useResearchCloudSession } from "../shared/research-cloud-session";
+import { useAttentionEvidence } from "./evidence";
+import { cachedAttention, loadAttention } from "./client";
+import { listingCell, missingCell, shareCell, signedColor } from "../shared/research-cells";
+import { ATTENTION_TABS, attentionRows, attentionTab, attentionWindow, COLUMNS, date, emptyAttention, GROUP_COLUMNS, HISTORY_COLUMNS, historyPoints, hour, number, rowCell, signed, WINDOWS } from "./model";
+
+type DetailRow = Omit<AttentionRow, "researchUnits" | "rank" | "sharePct" | "baselinePeriods"> & {
+  researchUnits: number | null; rank: number | null; sharePct: number | null; baselinePeriods: number | null;
+};
+type Locked = { locked: true; id: string };
+const isLocked = (row: unknown): row is Locked => !!row && typeof row === "object" && "locked" in row;
+function History({ row, width, height, focused, preview }: { row: DetailRow; width: number; height: number; focused: boolean; preview: boolean }) {
+  const colors = useThemeColors();
+  const [selected, setSelected] = usePluginPaneState<string | null>("attention:hour", null);
+  const points = useMemo(() => [...row.history].sort((a, b) => a.bucketStart.localeCompare(b.bucketStart)).map((point, index, all) => ({ ...point,
+    change: index && Date.parse(point.bucketStart) - Date.parse(all[index - 1]!.bucketStart) === 3_600_000 ? point.researchUnits - all[index - 1]!.researchUnits : null,
+  })).reverse(), [row.history]);
+  const selectedHour = points.some((point) => point.bucketStart === selected) ? selected : points[0]?.bucketStart ?? null;
+  const series = useMemo(() => [staticSeries(historyPoints(row.history), {
+    id: "research-hours", label: `${row.symbol} research hours`, color: colors.warning, calendarSpaced: true,
+  })], [row, colors.warning]);
+  const link = useChartTableSelection({ rows: points, getId: (point: AttentionPoint) => point.bucketStart, getDate: (point: AttentionPoint) => new Date(point.bucketStart),
+    selectedId: selectedHour, onSelect: setSelected, focused });
+  return <DataTableView columns={HISTORY_COLUMNS} items={points} sortColumnId="bucketStart" sortDirection="desc" rootWidth={width} rootHeight={height} focused={focused}
+    selection={{ kind: "id", selectedId: selectedHour, getId: (point) => point.bucketStart, onChange: setSelected }}
+    getItemKey={(point) => point.bucketStart} onActivate={(point) => setSelected(point.bucketStart)} selectedTextOverridesCellColor
+    rootBefore={<ChartTableHeader width={width} height={height} tableRows={points.length} tableColumns={HISTORY_COLUMNS}
+      figures={[{ id: "research", label: "Research hours", value: number(row.researchUnits) },
+        { id: "z", label: "Latest-hour Z", value: signed(row.zScore), ...(row.zScore != null && row.zScore >= 2 ? { tone: "warning" as const } : {}) },
+        ...(row.priceChangePct != null ? [{ id: "price", label: "Price move", value: signed(row.priceChangePct, "%"), color: signedColor(row.priceChangePct, colors), detail: row.marketAsOf ? `${row.marketAsOf.slice(11, 16)} UTC` : undefined }] : [])]}
+      chart={{ series: points.length >= 3 ? series : [], viewport: points.length >= 3 ? { start: new Date(points.at(-1)!.bucketStart), end: new Date(Date.parse(points[0]!.bucketStart) + 3_600_000) } : undefined, formatValue: (value) => number(value), remoteKind: "attention-history", ...link,
+        empty: preview ? "Pro unlocks published history." : "Collecting privacy-qualified hourly history." }} />}
+    renderCell={(point, column) => column.id === "bucketStart" ? { text: hour(point.bucketStart), value: point.bucketStart }
+      : column.id === "researchUnits" ? { text: number(point.researchUnits), value: point.researchUnits, color: colors.textBright }
+      : point.change == null ? { text: "", value: null } : { text: point.change ? `${point.change > 0 ? "+" : ""}${number(point.change)}` : "0", value: point.change, color: signedColor(point.change, colors) }}
+    emptyStateTitle="No published hours for this ticker." />;
+}
+function Evidence({ row, data, width, height }: { row: DetailRow; data: AttentionPayload; width: number; height: number }) {
+  const desktop = !!useUiCapabilities().nativePaneChrome;
+  const host = useRendererHost();
+  const [selectedHour] = usePluginPaneState<string | null>("attention:hour", null);
+  const point = row.history.find((entry) => entry.bucketStart === selectedHour) ?? row.history.at(-1);
+  const sameDay = row.evidence.periodStart.slice(0, 10) === row.evidence.periodEnd.slice(0, 10);
+  const period = sameDay ? `${hour(row.evidence.periodStart)} to ${row.evidence.periodEnd.slice(11, 16)} UTC` : `${hour(row.evidence.periodStart)} to ${date(row.evidence.periodEnd)}`;
+  const latest = point?.bucketStart === row.history.at(-1)?.bucketStart;
+  return <ScrollBox scrollY width={width} height={desktop ? undefined : height} flexGrow={1} flexBasis={0} contentOptions={{ paddingX: 1 }}>
+    <KeyValueRow label="Listing" value={row.symbol} detail={row.name ?? undefined} labelWidth={20} />
+    <SectionHeading title="Publication" />
+    <KeyValueRow label="Research hours" value={number(row.researchUnits)} detail={`rounded to ${data.privacy.rounding}`} labelWidth={20} />
+    <KeyValueRow label="Hour" value={period} labelWidth={20} />
+    <KeyValueRow label="Published" value={date(row.evidence.asOf)} detail={`after ${data.privacy.lagHours}h minimum`} labelWidth={20} />
+    <KeyValueRow label="Privacy threshold" value={`${data.privacy.minimumContributors} contributors per hour`} detail={`passed · methodology ${row.evidence.methodologyVersion}`} labelWidth={20} />
+    <KeyValueRow label="Baseline" value={row.baselinePeriods === null ? "--" : `${row.baselinePeriods} qualified periods`} detail={row.zScore === null ? "Z-score unavailable" : `Z ${signed(row.zScore)}`} labelWidth={20} />
+    {row.marketAsOf || row.relativeVolumeAsOf ? <>
+      <SectionHeading title="Market Context" />
+      {row.marketAsOf ? <KeyValueRow label="Price move" value={signed(row.priceChangePct, "%")} detail={date(row.marketAsOf)} labelWidth={20} /> : null}
+      {row.relativeVolumeAsOf ? <KeyValueRow label="Relative volume" value={row.relativeVolume === null ? "--" : `${number(row.relativeVolume, 2)}x`} detail={date(row.relativeVolumeAsOf)} labelWidth={20} /> : null}
+    </> : null}
+    {point?.publishedAt && !latest ? <>
+      <SectionHeading title="Selected Hour" />
+      <KeyValueRow label="Hour" value={date(point.bucketStart)} labelWidth={20} />
+      <KeyValueRow label="Research hours" value={number(point.researchUnits)} detail={`rounded to ${point.rounding ?? "--"}`} labelWidth={20} />
+      <KeyValueRow label="Published" value={date(point.publishedAt)} detail={`${point.minimumContributors ?? "--"} contributors · ${point.lagHours ?? "--"}h lag · version ${point.methodologyVersion ?? "--"}`} labelWidth={20} />
+    </> : null}
+    <SectionHeading title="Related News" />
+    {row.news.length ? row.news.map((article) => <ActionRow key={article.url} label={`${hour(article.publishedAt)}  ${article.title}`} onPress={() => void host.openExternal(article.url)} />)
+      : <EmptyState title="No related headlines in this publication." />}
+  </ScrollBox>;
+}
+export function AttentionPane({ width, height, focused }: PaneProps) {
+  const colors = useThemeColors();
+  const desktop = !!useUiCapabilities().nativePaneChrome;
+  const host = useRendererHost();
+  const { createPaneFromTemplate } = usePluginAppActions();
+  const openDescription = useOpenDescription();
+  const session = useResearchCloudSession();
+  const access = usePlanAccess();
+  const accessKey = `${session.requestKey}:${access.hasProAccess ? "pro" : "preview"}`;
+  const openUpgrade = useCloudUpgradeAction("attention");
+  const [initialWindow] = usePaneSettingValue("window", "now");
+  const [savedWindow, setWindow] = usePluginPaneState("attention:window", initialWindow);
+  const window = attentionWindow(savedWindow);
+  const [initialSymbol] = usePaneSettingValue("symbol", "");
+  const [initialTab] = usePaneSettingValue("tab", initialSymbol ? "history" : "ranking");
+  const [savedTab, setTab] = usePluginPaneState("attention:tab", initialTab);
+  const tab = attentionTab(savedTab);
+  const [groupFilter, setGroupFilter] = usePluginPaneState<{ field: "sector" | "country"; value: string } | null>("attention:group-filter", null);
+  const [query, setQuery] = usePluginPaneState("attention:query", "");
+  const search = useQueryBarSearch();
+  const [selectedId, setSelected] = usePluginPaneState<string | null>("attention:selected", initialSymbol || null);
+  const [groupSelectedId, setGroupSelected] = usePluginPaneState<string | null>("attention:group", null);
+  const [sort, setSort] = usePluginPaneState<{ column: string; direction: "asc" | "desc" }>("attention:sort", { column: "rank", direction: "asc" });
+  const loader = useCallback((force: boolean) => loadAttention(window, accessKey, undefined, force), [window, accessKey]);
+  const resource = useAsyncResource(loader, { initialData: () => cachedAttention(window, accessKey), clearOnError: isAccessDenied });
+  const data = resource.data?.payload;
+  const rows = useMemo(() => attentionRows((data?.rows ?? []).filter((row) => !groupFilter || (row[groupFilter.field] ?? "Unknown") === groupFilter.value), tab, query, tab === "abnormal" ? "zScore" : sort.column, tab === "abnormal" ? "desc" : sort.direction), [data, tab, query, sort, groupFilter]);
+  const selectedSymbol = data?.rows.find((row) => row.symbol === selectedId || row.ticker === selectedId)?.symbol ?? selectedId ?? rows[0]?.symbol ?? "";
+  const detailMode = tab === "history" || tab === "evidence";
+  const groupMode = tab === "sectors" || tab === "countries";
+  const detailLoader = useCallback((force: boolean) => loadAttention(window, accessKey, selectedSymbol, force), [window, accessKey, selectedSymbol]);
+  const detail = useAsyncResource(detailMode && selectedSymbol ? detailLoader : null, { clearOnError: isAccessDenied });
+  const detailData = detail.data?.payload;
+  const selected: DetailRow | undefined = (detailMode ? detailData?.rows : rows)?.find((row) => row.symbol === selectedSymbol || row.ticker === selectedSymbol) ?? (detailMode && detailData?.rows.length === 1 ? detailData.rows[0] : !detailMode ? rows[0] : undefined)
+    ?? (detailMode && detailData?.selectedListing && detailData.historyEvidence && detailData.history?.length ? {
+      ...detailData.selectedListing, history: detailData.history, evidence: detailData.historyEvidence,
+      rank: null, researchUnits: null, sharePct: null, zScore: null, baselinePeriods: null,
+      priceChangePct: null, relativeVolume: null, marketAsOf: null, relativeVolumeAsOf: null, news: [],
+    } : undefined);
+  useAttentionEvidence((detailMode ? detailData : data) ?? null, tab, selectedSymbol, tab === "history" ? selected?.history.length ?? 0 : rows.length);
+  const signInWall = !data && isCloudSessionRequired(resource.error);
+  const { strip, rows: tabRows } = usePaneTabs(!signInWall ? { tabs: [...ATTENTION_TABS], activeValue: tab, onSelect: setTab, focused, dense: true } : null);
+  useAutoRefresh(resource.updatedAt, resource.load);
+  usePaneRefreshKey(() => { void resource.reload(); if (detailMode) void detail.reload(); }, { focused });
+  const hints: PaneHint[] = [
+    ...(selected && !groupMode ? [
+      { id: "description", key: "d", label: "es", onPress: () => openDescription(selected.symbol) },
+      { id: "financials", key: "f", label: "a", onPress: () => createPaneFromTemplate("financial-analysis-pane", { symbol: selected.symbol }) },
+      { id: "chart", key: "g", label: "raph", onPress: () => createPaneFromTemplate("chart-composer-pane", { arg: selected.symbol }) },
+      { id: "news", key: "n", label: "ews", onPress: () => createPaneFromTemplate("ticker-news-pane", { symbol: selected.symbol }) },
+      { id: "evidence", key: "e", label: "vidence", onPress: () => setTab("evidence") },
+    ] : []),
+    ...(tab === "evidence" && data ? [{ id: "methodology", key: "o", label: "pen methodology", onPress: () => void host.openExternal(data.methodologyUrl) }] : []),
+    ...(data?.entitlement === "preview" ? [{ id: "upgrade", key: CLOUD_PLAN_KEY, label: "upgrade", title: "Upgrade to Pro", onPress: openUpgrade }] : []),
+  ];
+  usePaneStatusFooter({ registrationId: "attention", loading: resource.loading || detailMode && detail.loading, error: data ? resource.error ?? (detailMode ? detail.error : null) : null,
+    stale: data?.stale || resource.data?.stale, info: data?.asOf ? [{ id: "asof", parts: [{ text: `published ${date(data.asOf)}`, tone: "muted" }] }] : [], hints });
+  usePaneNoticeFooter({ registrationId: "attention:notices", focused, notices: [resource.data?.refreshError, detailMode ? detail.data?.refreshError : null,
+    data?.status === "ready" && selected?.zScore === null ? "The selected ticker has insufficient qualified history for an abnormal-attention score." : null,
+  ].filter((value): value is string => !!value) });
+  if (signInWall) return <SignInWall placement="attention-signin" action="view research attention" needsVerification={session.needsVerification} />;
+  const bodyHeight = Math.max(3, height - tabRows);
+  const queryBar = <QueryBar width={width} filters={[{ id: "window", label: "Period", inline: true, value: window, options: WINDOWS,
+    onChange: (value: string) => setWindow(value) }, ...(detailMode && data?.rows.length ? [{ id: "ticker", label: "Ticker", value: selectedSymbol,
+      options: data.rows.map((row) => ({ value: row.symbol, label: row.symbol })), onChange: (value: string) => setSelected(value) }] : []),
+      ...(!detailMode && !groupMode && groupFilter ? [{ id: "group", label: groupFilter.field === "country" ? "Country" : "Sector", value: groupFilter.value, defaultValue: "all",
+        options: [{ value: "all", label: "All" }, ...(data?.[groupFilter.field === "country" ? "countries" : "sectors"] ?? []).map((group) => ({ value: group.name, label: group.name }))],
+        onChange: (value: string) => { setGroupFilter(value === "all" ? null : { ...groupFilter, value }); setSelected(null); } }] : [])]}
+    search={!detailMode ? { focused, value: query, onChange: (value: string) => { setQuery(value); setSelected(null); }, placeholder: groupMode ? "Find group" : "Find ticker, sector or country", ...search.searchProps } : undefined} />;
+  const groups = groupMode ? (data?.[tab] ?? []).filter((group) => group.name.toLowerCase().includes(query.toLowerCase())) : [];
+  const visibleRows: Array<AttentionRow | AttentionGroup | Locked> = groupMode ? groups : rows;
+  const hidden = data ? Math.max(0, data.counts[groupMode ? tab : "rows"] - (groupMode ? data[tab].length : data.rows.length)) : 0;
+  const items = [...visibleRows, ...Array.from({ length: Math.min(3, hidden) }, (_, i): Locked => ({ locked: true, id: `locked:${i}` }))];
+  const columns = groupMode ? GROUP_COLUMNS : COLUMNS;
+  const rowId = (row: AttentionRow | AttentionGroup | Locked) => isLocked(row) ? row.id : "symbol" in row ? row.symbol : row.name;
+  const maxShare = Math.max(0, ...visibleRows.map((row) => isLocked(row) ? 0 : row.sharePct ?? 0));
+  const cell = (row: AttentionRow | AttentionGroup | Locked, column: DataTableColumn, _index: number, state: { selected: boolean }): DataTableCell => {
+    if (isLocked(row)) return desktop ? { text: "", content: <Blurred><Text fg={colors.textDim}>{column.id === "name" ? "Additional research" : "Hidden"}</Text></Blurred> }
+      : { text: column.id === columns[0]!.id && row.id === "locked:0" ? "Pro" : "░░░", color: colors.textDim };
+    if (column.id === "sharePct") return { ...shareCell(number(row.sharePct, 1), maxShare ? row.sharePct / maxShare : null, column.width, colors, state.selected), value: row.sharePct };
+    if ("symbol" in row) {
+      const numeric = typeof row[column.id as keyof AttentionRow] === "number" ? row[column.id as keyof AttentionRow] as number : undefined;
+      switch (column.id) {
+        case "symbol": return listingCell(row.symbol, colors, state.selected);
+        case "rank": return { text: rowCell(row, column.id), value: numeric, color: colors.textDim };
+        case "researchUnits": return { text: rowCell(row, column.id), value: numeric, color: colors.textBright };
+        case "zScore": return row.zScore == null ? missingCell(colors) : { text: rowCell(row, column.id), value: row.zScore,
+          color: row.zScore >= 2 ? colors.warning : row.zScore < 0 ? colors.textDim : colors.text, attributes: row.zScore >= 2 ? TextAttributes.BOLD : 0, keepColorWhenSelected: row.zScore >= 2 };
+        case "priceChangePct": return row.priceChangePct == null ? missingCell(colors) : { text: rowCell(row, column.id), value: row.priceChangePct, color: signedColor(row.priceChangePct, colors) };
+        case "relativeVolume": return row.relativeVolume == null ? missingCell(colors) : { text: rowCell(row, column.id), value: row.relativeVolume, color: row.relativeVolume >= 2 ? colors.textBright : colors.text };
+        case "sector": return { text: rowCell(row, column.id), color: colors.textDim };
+        // The column has room for the flag beside a code.
+        case "country": return withCountryFlag({ text: rowCell(row, column.id), color: colors.textDim }, row.country, desktop);
+        default: return { text: rowCell(row, column.id), value: numeric, color: colors.text };
+      }
+    }
+    const value = row[column.id as keyof AttentionGroup];
+    const groupCell: DataTableCell = { text: typeof value === "number" ? number(value) : value, value: typeof value === "number" ? value : undefined,
+      color: column.id === "name" ? colors.textBright : column.id === "tickers" ? colors.textDim : colors.text };
+    return tab === "countries" && column.id === "name" ? withCountryFlag(groupCell, row.name, desktop) : groupCell;
+  };
+  // The whole board in four figures; a preview would only summarise its own three rows.
+  const top = (groups: readonly AttentionGroup[]) => groups[0] ? { value: groups[0].name, detail: `${number(groups[0].sharePct, 1)}%` } : null;
+  const topSector = data ? top(data.sectors) : null, topCountry = data ? top(data.countries) : null;
+  const abnormal = data?.rows.filter((row) => row.zScore != null && row.zScore >= 2).length ?? 0;
+  const figures: StatItem[] = data && !groupMode && !detailMode && data.entitlement !== "preview" && data.rows.length ? [
+    { id: "hours", label: "Research hours", value: number(data.rows.reduce((sum, row) => sum + row.researchUnits, 0)), detail: WINDOWS.find((entry) => entry.value === window)?.label.toLowerCase() },
+    { id: "abnormal", label: "Abnormal", value: String(abnormal), detail: "Z ≥ 2", ...(abnormal ? { tone: "warning" as const } : {}) },
+    ...(topSector ? [{ id: "sector", label: "Top sector", ...topSector }] : []),
+    ...(topCountry ? [{ id: "country", label: "Top country", ...topCountry }] : []),
+  ] : [];
+  // The strip and the period filter stay while a new period loads; only the body waits.
+  return <Box width={width} height={height} flexDirection="column">{strip}
+    {detailMode ? <Box flexGrow={1} flexBasis={0} flexDirection="column">{queryBar}
+      <PaneStatusBody loading={!data ? resource.loading : !detailData && detail.loading} error={!data ? resource.error : !detailData ? detail.error : null}
+        empty={!!data && !!detailData && !selected} subject={!data ? "research attention" : "ticker attention"}
+        emptyTitle={data?.entitlement === "preview" ? "This ticker is outside the current preview." : "No privacy-qualified hours for this ticker."}>
+        {data && selected ? tab === "history" ? <History row={selected} width={width} height={bodyHeight - 1} focused={focused} preview={data.entitlement === "preview"} />
+          : <Evidence row={selected} data={detailData ?? data} width={width} height={bodyHeight - 1} /> : null}
+      </PaneStatusBody>
+    </Box> : <DataTableView columns={columns} items={data ? items : []} rootWidth={width} rootHeight={bodyHeight} focused={focused && !search.active}
+        status={!data ? { loading: resource.loading, error: resource.error, subject: "research attention" }
+          : data.status !== "ready" && !data.rows.length ? { empty: true, emptyTitle: emptyAttention(data), subject: "research attention" } : undefined}
+        rootBefore={<ChartTableHeader width={width} height={bodyHeight} tableRows={items.length} tableColumns={columns} query={queryBar} figures={figures} />}
+        getItemKey={rowId} selection={{ kind: "id", selectedId: groupMode ? groupSelectedId : selected?.symbol ?? null, getId: rowId, onChange: (id) => { if (groupMode) setGroupSelected(id); else if (!id.startsWith("locked:")) setSelected(id); } }}
+        onActivate={(row) => { if (isLocked(row)) openUpgrade(); else if ("symbol" in row) { setSelected(row.symbol); setTab("history"); } else { setGroupFilter({ field: tab === "countries" ? "country" : "sector", value: row.name }); setQuery(""); setSelected(null); setTab("ranking"); } }}
+        renderCell={cell} selectedTextOverridesCellColor showHorizontalScrollbar
+        sortColumnId={!groupMode ? tab === "abnormal" ? "zScore" : sort.column : null} sortDirection={tab === "abnormal" ? "desc" : sort.direction}
+        onHeaderClick={!groupMode && tab !== "abnormal" ? (column) => setSort((current) => ({ column, direction: current.column === column && current.direction === "desc" ? "asc" : "desc" })) : undefined}
+        emptyStateTitle={tab === "abnormal" ? "Collecting enough qualified history for abnormal attention." : "No published research matches."}
+        bodyAfter={hidden && desktop ? <LockedOverlay rows={Math.min(3, hidden)} text="Pro unlocks the full attention graph" onPress={openUpgrade} /> : undefined} />}
+  </Box>;
+}

package/src/plugins/builtin/attention/series.ts

@@ -0,0 +1,26 @@
+import type { SeriesDefinition } from "../../../series/types";
+import { fetchAttention } from "./client";
+import { emptyAttention, historyPoints } from "./model";
+
+/**
+ * The hourly research attention ATTN charts for one ticker. A Pro reading
+ * served per account: the free preview carries no history, so it fails with
+ * the pane's own words instead of drawing an empty chart.
+ */
+export const ATTENTION_SERIES: readonly SeriesDefinition[] = [{
+  id: "attention:research-hours",
+  name: "Research attention",
+  unit: "hours",
+  frequency: "intraday",
+  group: "Alternative data",
+  tags: ["attention", "research", "trending", "researcher-hours"],
+  description: "Rounded researcher-hours opt-in users spent on the ticker in each published hour, as ATTN charts them; an hour below the privacy threshold is a gap. Needs Pro.",
+  input: "ticker",
+  load: async ({ ticker }) => {
+    const data = await fetchAttention("now", ticker!);
+    if (data.entitlement === "preview") throw new Error("Pro unlocks published history.");
+    if (data.status === "disabled") throw new Error(emptyAttention(data));
+    if (!data.history?.length) throw new Error("No privacy-qualified hours for this ticker.");
+    return historyPoints(data.history).map((point) => ({ date: point.date, value: point.value }));
+  },
+}];

package/src/plugins/builtin/attention/trending.tsx

@@ -0,0 +1,61 @@
+import { useCallback } from "react";
+import { usePlanAccess } from "../../../api-client/plan-access";
+import { isAccessDenied } from "../../../api-client/errors";
+import { ActionRow, DataTableView, EmptyState, KeyValueRow, PaneStatusBody, SectionHeading, usePaneStatusFooter } from "../../../components";
+import { usePaneRefreshKey } from "../../../components/data-table/table-pane";
+import { useAsyncResource, useAutoRefresh, usePluginAppActions, usePluginPaneState } from "../../../public/react";
+import type { PaneProps } from "../../../types/plugin";
+import { Box } from "../../../ui";
+import { isCloudSessionRequired, useResearchCloudSession } from "../shared/research-cloud-session";
+import { SignInWall } from "../cloud/auth-actions";
+import { cachedAttention, loadAttention } from "./client";
+import { date, emptyAttention, number, signed } from "./model";
+import { useThemeColors } from "../../../theme/theme-context";
+import { listingCell, missingCell } from "../shared/research-cells";
+function useTrending(symbol?: string) {
+  const session = useResearchCloudSession();
+  const access = usePlanAccess();
+  const key = `${session.requestKey}:${access.hasProAccess ? "pro" : "preview"}`;
+  const loader = useCallback((force: boolean) => loadAttention("today", key, symbol, force), [key, symbol]);
+  const resource = useAsyncResource(access.signedIn ? loader : null, { initialData: () => cachedAttention("today", key, symbol), clearOnError: isAccessDenied });
+  useAutoRefresh(resource.updatedAt, resource.load);
+  return { resource, session, access };
+}
+/**
+ * Optional profile context. A failure here never hides or blocks the description,
+ * and a symbol with no published research hours shows no section at all: the
+ * Overview leaves out what it has nothing to say about.
+ */
+export function TrendingSummary({ symbol, onOpen }: { symbol: string; onOpen?: () => void }) {
+  const { resource, access } = useTrending(symbol);
+  const data = resource.data?.payload;
+  const row = data?.rows[0];
+  if (!access.signedIn || !data || !row) return null;
+  return <Box flexDirection="column">
+    <SectionHeading title="Gloom Trending" />
+    <KeyValueRow label="Research rank" value={`#${row.rank}`} detail={`Today · ${number(row.researchUnits)} research hours`} />
+    <KeyValueRow label="Latest-hour Z" value={signed(row.zScore)} detail={data.asOf ? date(data.asOf) : undefined} />
+    {onOpen ? <ActionRow label="Open research attention" onPress={onOpen} /> : null}
+  </Box>;
+}
+export function TrendingPane({ width, height, focused }: PaneProps) {
+  const colors = useThemeColors();
+  const { resource, session, access } = useTrending();
+  const data = resource.data?.payload;
+  const { createPaneFromTemplate } = usePluginAppActions();
+  const [selectedIndex, setSelectedIndex] = usePluginPaneState("trending:selected", 0);
+  const open = () => createPaneFromTemplate("attention-pane", { values: { window: "today" } });
+  usePaneRefreshKey(() => void resource.reload(), { focused });
+  usePaneStatusFooter({ registrationId: "attention:trending", loading: resource.loading, error: data ? resource.error : null, stale: data?.stale || resource.data?.stale,
+    info: data?.asOf ? [{ id: "asof", parts: [{ text: `published ${date(data.asOf)}`, tone: "muted" }] }] : [],
+    hints: [{ id: "attention", key: "a", label: "ttention", onPress: open }] });
+  if (!access.signedIn || !data && isCloudSessionRequired(resource.error)) return <SignInWall placement="attention-trending-signin" action="view research attention" needsVerification={session.needsVerification} />;
+  return <PaneStatusBody loading={!data && resource.loading} error={!data ? resource.error : null} empty={!!data && !data.rows.length} emptyTitle={emptyAttention(data)} subject="research attention">
+    {data ? <DataTableView columns={[{ id: "symbol", label: "Ticker", width: 16, flexGrow: 1, align: "left" }, { id: "research", label: "Research hrs", width: 12, align: "right" }, { id: "z", label: "1H Z", width: 8, align: "right" }]}
+      items={data.rows.slice(0, 5)} emptyStateTitle="No published research hours." rootWidth={width} rootHeight={height} focused={focused} getItemKey={(row) => row.symbol} selection={{ kind: "index", selectedIndex, onChange: setSelectedIndex }}
+      sortColumnId={null} sortDirection="desc" onActivate={(row) => createPaneFromTemplate("attention-pane", { arg: row.symbol, values: { window: "today" } })}
+      selectedTextOverridesCellColor renderCell={(row, column, _index, state) => column.id === "symbol" ? listingCell(row.symbol, colors, state.selected)
+        : column.id === "research" ? { text: number(row.researchUnits), value: row.researchUnits, color: colors.textBright }
+        : row.zScore == null ? missingCell(colors) : { text: signed(row.zScore), value: row.zScore, color: row.zScore >= 2 ? colors.warning : colors.text, keepColorWhenSelected: row.zScore >= 2 }} /> : <EmptyState title="Sign in to view research attention." />}
+  </PaneStatusBody>;
+}

package/src/plugins/builtin/awards/alerts.ts

@@ -0,0 +1,32 @@
+import { useEffect } from "react";
+import type { AwardRow, AwardsPayload } from "../../../api-client/awards";
+import { usePaneSettingValue, usePaneVisible, usePluginAppActions, usePluginPaneState } from "../../../public/react";
+
+interface AlertState { scope: string; seen: string[]; through: string }
+export function newAwardAlerts(data: AwardsPayload, previous: AlertState | null, scope: string): { state: AlertState; fresh: AwardRow[] } {
+  const seen = new Set(previous?.scope === scope ? previous.seen : []);
+  const now = Date.parse(data.generatedAt);
+  const fresh = previous?.scope === scope ? data.alerts.filter((row) => !seen.has(row.id)
+    && (row.revenueComparison?.percent ?? 0) >= 1
+    && Date.parse(row.observedAt) > Date.parse(previous.through)
+    && Date.parse(row.awardDate) >= now - 7 * 86_400_000 && Date.parse(row.awardDate) <= now) : [];
+  return { state: { scope, seen: [...new Set([...data.alerts.map((row) => row.id), ...seen])].slice(0, 500), through: data.generatedAt }, fresh };
+}
+
+export function useAwardAlerts(data: AwardsPayload | undefined, scope: string, openAward: (id: string) => void) {
+  const [enabled] = usePaneSettingValue("awardAlerts", false);
+  const visible = usePaneVisible();
+  const [previous, setPrevious] = usePluginPaneState<AlertState | null>("awards:alerts", null);
+  const { notify } = usePluginAppActions();
+  useEffect(() => {
+    if (!data || !visible) return;
+    const key = `${scope}:${enabled}:${data.access}`;
+    if (previous?.scope === key && previous.through === data.generatedAt) return;
+    const { state, fresh } = newAwardAlerts(data, previous, key);
+    setPrevious(state);
+    if (!enabled || data.access !== "full" || !fresh.length) return;
+    const row = [...fresh].sort((a, b) => (b.revenueComparison?.percent ?? 0) - (a.revenueComparison?.percent ?? 0))[0]!;
+    notify({ title: "Government award", body: `${row.entity?.ticker ?? row.recipient.name}: award = ${row.revenueComparison!.percent.toFixed(2)}% of annual revenue${fresh.length > 1 ? ` · ${fresh.length - 1} more new awards` : ""}`,
+      desktop: "never", action: { label: "View award", onClick: () => openAward(row.id) } });
+  }, [data, scope, enabled, visible, previous, setPrevious, notify, openAward]);
+}

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

@@ -0,0 +1,82 @@
+import { apiClient } from "../../../api-client";
+import type { AwardDetailPayload, AwardFilter, AwardInput, AwardRow, AwardsPayload } from "../../../api-client/awards";
+import { createPluginCache } from "../../../data/plugin-cache";
+import { loadCloudResource, unavailableOnServer } from "../shared/cloud-resource";
+
+export const AWARDS_UNAVAILABLE = "Government awards are not available yet.";
+export const awardsCache = createPluginCache<AwardsPayload>({ kind: "government-awards", source: "gloom-cloud", schemaVersion: 1,
+  policy: { staleMs: 5 * 60_000, expireMs: 7 * 86_400_000 } });
+export const awardDetailCache = createPluginCache<AwardDetailPayload>({ kind: "government-award-detail", source: "gloom-cloud", schemaVersion: 1,
+  policy: { staleMs: 5 * 60_000, expireMs: 7 * 86_400_000 } });
+
+const text = (value: unknown): value is string => typeof value === "string";
+const optionalText = (value: unknown) => value == null || text(value);
+const amount = (value: unknown) => value == null || text(value) && /^-?\d+(?:\.\d+)?$/.test(value) && Number.isFinite(Number(value));
+const date = (value: unknown) => text(value) && /^\d{4}-\d{2}-\d{2}$/.test(value) && Number.isFinite(Date.parse(value)) && new Date(value).toISOString().slice(0, 10) === value;
+const instant = (value: unknown) => text(value) && Number.isFinite(Date.parse(value));
+const url = (value: unknown) => { try { return text(value) && ["https:", "http:"].includes(new URL(value).protocol); } catch { return false; } };
+const confidence = (value: unknown) => typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= 1;
+const count = (value: unknown) => Number.isSafeInteger(value) && Number(value) >= 0;
+const currency = (value: unknown) => text(value) && /^[A-Z]{3}$/.test(value);
+const type = (value: unknown) => ["prime", "subaward", "modification", "notice"].includes(String(value));
+function validInput(row: AwardInput): boolean {
+  return !!row && text(row.source) && text(row.sourceAwardId) && text(row.title) && text(row.jurisdiction) && type(row.awardType)
+    && date(row.awardDate) && (row.periodStart == null || date(row.periodStart)) && (row.periodEnd == null || date(row.periodEnd))
+    && currency(row.currency) && amount(row.awardAmount) && amount(row.obligatedAmount) && amount(row.ceilingAmount)
+    && !!row.recipient && text(row.recipient.name) && !!row.agency && text(row.agency.name) && url(row.sourceUrl)
+    && (row.fieldSourceUrls == null || typeof row.fieldSourceUrls === "object" && Object.values(row.fieldSourceUrls).every(url))
+    && (row.fieldAsOf == null || typeof row.fieldAsOf === "object" && Object.values(row.fieldAsOf).every(instant))
+    && optionalText(row.description) && optionalText(row.evidenceQuote) && (row.confidence == null || confidence(row.confidence));
+}
+function validRow(row: AwardRow): boolean {
+  const match = row?.entity, revenue = row?.revenueComparison;
+  return validInput(row) && text(row.id) && text(row.revisionId) && instant(row.observedAt)
+    && (match === null || !!match && text(match.ticker) && text(match.legalName) && optionalText(match.exchange)
+      && ["identifier", "legal-name", "verified-alias"].includes(match.method) && url(match.evidenceUrl) && confidence(match.confidence))
+    && (revenue === null || !!revenue && amount(revenue.awardAmount) && amount(revenue.annualRevenue) && Number(revenue.annualRevenue) > 0
+      && currency(revenue.currency) && revenue.currency === row.currency && date(revenue.periodStart) && date(revenue.periodEnd)
+      && instant(revenue.filedAt) && url(revenue.sourceUrl) && Number.isFinite(revenue.percent) && revenue.percent >= 0
+      && ["award-value", "obligated"].includes(revenue.basis));
+}
+export function validateAwards(data: AwardsPayload): AwardsPayload {
+  if (!data || !instant(data.generatedAt) || !(data.asOf === null || instant(data.asOf))
+    || !["available", "partial", "unavailable"].includes(data.status) || !["full", "preview"].includes(data.access)
+    || typeof data.locked !== "boolean" || !(data.nextCursor === null || text(data.nextCursor))
+    || !Array.isArray(data.rows) || !data.rows.every(validRow) || new Set(data.rows.map((row) => row.id)).size !== data.rows.length
+    || !Array.isArray(data.alerts) || !data.alerts.every(validRow)
+    || ![data.agencies, data.sectors].every((rows) => Array.isArray(rows) && rows.every((row) => text(row.key) && text(row.label) && text(row.source)
+      && currency(row.currency) && type(row.awardType) && count(row.count) && [row.awardAmount, row.obligatedAmount, row.ceilingAmount].every(amount)
+      && (row.sharePercent === null || Number.isFinite(row.sharePercent))))
+    || !(data.leaders === undefined || Array.isArray(data.leaders) && data.leaders.every((row) => text(row.label) && text(row.key) && text(row.source)
+      && text(row.sector) && optionalText(row.ticker) && optionalText(row.exchange) && currency(row.currency) && type(row.awardType) && count(row.count)
+      && [row.awardAmount, row.obligatedAmount, row.ceilingAmount].every(amount) && (row.sharePercent === null || Number.isFinite(row.sharePercent))))
+    || !Array.isArray(data.history) || !data.history.every((row) => text(row.source) && text(row.month) && date(`${row.month.slice(0, 7)}-01`)
+      && currency(row.currency) && type(row.awardType) && count(row.count)
+      && [row.awardAmount, row.obligatedAmount, row.ceilingAmount, row.cumulativeObligatedAmount].every(amount))
+    || !Array.isArray(data.gaps) || !data.gaps.every(text) || !Array.isArray(data.sources) || !Array.isArray(data.coverage)) {
+    throw new Error("The server returned unreadable government awards");
+  }
+  return data;
+}
+export function validateAwardDetail(data: AwardDetailPayload): AwardDetailPayload {
+  if (!data || !(data.row === null || validRow(data.row)) || !["full", "preview"].includes(data.access) || typeof data.locked !== "boolean"
+    || ![data.subawards, data.modifications].every((rows) => Array.isArray(rows) && rows.every(validRow))
+    || !Array.isArray(data.revisions) || !data.revisions.every((row) => text(row.id) && instant(row.observedAt) && optionalText(row.supersedes) && validInput(row.award))
+    || !Array.isArray(data.edges) || !data.edges.every((edge) => ["government-customer", "subcontractor"].includes(edge.kind)
+      && text(edge.from?.name) && text(edge.to?.name) && amount(edge.amount) && currency(edge.currency) && url(edge.sourceUrl))) {
+    throw new Error("The server returned unreadable award evidence");
+  }
+  return data;
+}
+export async function fetchAwards(query: AwardFilter = {}, client: Pick<typeof apiClient, "getCloudAwards"> = apiClient, signal?: AbortSignal) {
+  try { return validateAwards(await client.getCloudAwards(query, signal)); }
+  catch (error) { throw unavailableOnServer(error, AWARDS_UNAVAILABLE, [404, 503]); }
+}
+export async function fetchAward(id: string, client: Pick<typeof apiClient, "getCloudAward"> = apiClient, signal?: AbortSignal, revisionsCursor?: string) {
+  return validateAwardDetail(await client.getCloudAward(id, signal, revisionsCursor));
+}
+// Account and plan are part of every key so a different session cannot read a paid cache.
+export const loadAwards = (query: AwardFilter, access: string, force = false) => loadCloudResource(awardsCache,
+  JSON.stringify([access, query]), () => fetchAwards(query), { force, validate: validateAwards });
+export const loadAward = (id: string, access: string, force = false) => loadCloudResource(awardDetailCache,
+  JSON.stringify([access, id]), () => fetchAward(id), { force, validate: validateAwardDetail });

package/src/plugins/builtin/awards/detail.tsx

@@ -0,0 +1,107 @@
+import { useMemo, useRef } from "react";
+import type { AwardRow } from "../../../api-client/awards";
+import { ActionRow, KeyValueRow, PaneStatusBody, Section, StatGrid, usePagedRows, usePaneNoticeFooter, usePaneStatusFooter, useTableLoadMore } from "../../../components";
+import { usePaneRefreshKey } from "../../../components/data-table/table-pane";
+import { useThemeColors } from "../../../theme/theme-context";
+import { Box, ScrollBox, Text, useRendererHost, useUiCapabilities, type ScrollBoxRenderable } from "../../../ui";
+import { fetchAward, loadAward } from "./client";
+import { awardPeriod, awardTypeLabel, money } from "./model";
+import { UpgradeLabel } from "../shared/locked-rows";
+
+export function AwardDetail({ row, accessKey, width, height, focused, openAward, openChildren, openUpgrade }: {
+  row: AwardRow; accessKey: string; width: number; height: number; focused: boolean; openAward: (id: string) => void;
+  openChildren: (type: "subaward" | "modification") => void; openUpgrade: () => void;
+}) {
+  const colors = useThemeColors();
+  const host = useRendererHost();
+  const desktop = !!useUiCapabilities().nativePaneChrome;
+  const loader = useMemo(() => {
+    const cursors = new Map<number, string>();
+    return async ({ offset, signal, force }: { offset: number; signal: AbortSignal; force: boolean }) => {
+      const result = offset === 0 ? await loadAward(row.id, accessKey, force)
+        : { payload: await fetchAward(row.id, undefined, signal, cursors.get(offset)), stale: false, refreshError: null };
+      if (result.payload.nextRevisionsCursor) cursors.set(offset + result.payload.revisions.length, result.payload.nextRevisionsCursor);
+      return { ...result, rows: result.payload.revisions, hasMore: !!result.payload.nextRevisionsCursor && !result.payload.locked };
+    };
+  }, [row.id, accessKey]);
+  const resource = usePagedRows(loader, { getId: (revision) => revision.id });
+  usePaneRefreshKey(resource.reload, { focused });
+  const loaded = resource.pages[0], detail = loaded?.payload;
+  const current = detail?.row ?? row;
+  const scrollRef = useRef<ScrollBoxRenderable | null>(null);
+  const loadMore = useTableLoadMore(scrollRef, resource.hasMore, resource.loadMore);
+  usePaneStatusFooter({ registrationId: "awards:detail", loading: resource.loading || resource.loadingMore, error: resource.error?.message ?? resource.moreError?.message, stale: loaded?.stale });
+  usePaneNoticeFooter({ registrationId: "awards:detail-notice", focused, notices: loaded?.refreshError ? [loaded.refreshError] : [] });
+  const labelWidth = width < 85 ? 18 : 23;
+  return <ScrollBox ref={scrollRef} scrollY width={width} height={desktop ? undefined : height} flexGrow={1} flexBasis={0} contentOptions={{ paddingX: 1 }} onMouseScroll={loadMore}>
+    <StatGrid width={Math.max(1, width - 2)} items={[
+      { id: "value", label: `Value (${current.currency})`, value: money(current.awardAmount), detail: current.fieldAsOf?.awardAmount ? `as of ${current.fieldAsOf.awardAmount.slice(0, 10)}` : undefined },
+      { id: "obligated", label: `Obligated (${current.currency})`, value: money(current.obligatedAmount), detail: current.fieldAsOf?.obligatedAmount ? `as of ${current.fieldAsOf.obligatedAmount.slice(0, 10)}` : undefined },
+      { id: "ceiling", label: `Ceiling (${current.currency})`, value: money(current.ceilingAmount), detail: current.fieldAsOf?.ceilingAmount ? `as of ${current.fieldAsOf.ceilingAmount.slice(0, 10)}` : undefined },
+    ]} />
+    <Section title="Contract" width={width - 2}>
+      <KeyValueRow label="Awardee" value={current.recipient.name} labelWidth={labelWidth} />
+      <KeyValueRow label={current.entity?.parentName && current.entity.parentName !== current.recipient.name ? "Listed parent" : "Listed company"} value={current.entity ? `${current.entity.ticker} · ${current.entity.parentName ?? current.entity.legalName}` : "Unresolved"} labelWidth={labelWidth} />
+      <KeyValueRow label="Agency" value={current.agency.name} detail={current.agency.parentName && current.agency.parentName !== current.agency.name ? current.agency.parentName : undefined} labelWidth={labelWidth} />
+      <KeyValueRow label={current.dateBasis === "period-start" ? "Period start date" : current.dateBasis === "publication" ? "Published" : "Awarded"} value={current.awardDate} detail={`${current.jurisdiction} · ${awardTypeLabel(current.awardType)}`} labelWidth={labelWidth} />
+      {current.awardStatus ? <KeyValueRow label="Status" value={current.awardStatus} labelWidth={labelWidth} /> : null}
+      {current.dataBasis === "bulk-latest-transaction" ? <KeyValueRow label="Record basis" value="Latest published transaction" labelWidth={labelWidth} /> : null}
+      <KeyValueRow label="Performance period" value={awardPeriod(current)} labelWidth={labelWidth} />
+      <KeyValueRow label="Performance place" value={[current.placeOfPerformance?.city, current.placeOfPerformance?.region, current.placeOfPerformance?.country].filter(Boolean).join(", ") || "--"} labelWidth={labelWidth} />
+      <KeyValueRow label="NAICS / PSC" value={`${current.naics ?? "--"} / ${current.psc ?? "--"}`} labelWidth={labelWidth} />
+      {current.classifications?.map((classification) => <KeyValueRow key={`${classification.scheme}:${classification.code}`} label={classification.scheme.toUpperCase()} value={classification.code} detail={classification.label} labelWidth={labelWidth} />)}
+      <KeyValueRow label="Award id" value={current.sourceAwardId} labelWidth={labelWidth} />
+      {current.parentAwardId ? <KeyValueRow label="Parent award" value={current.parentAwardId} labelWidth={labelWidth} /> : null}
+      {current.recipient.identifiers?.map((identifier) => <KeyValueRow key={identifier.scheme + identifier.value} label={identifier.scheme.toUpperCase()} value={identifier.value} labelWidth={labelWidth} />)}
+      {current.description ? <Box paddingY={1}><Text fg={colors.text} width={width - 2} wrapMode="word" wrapText>{current.description}</Text></Box> : null}
+    </Section>
+    {current.revenueComparison ? <Section title="Annual revenue comparison" width={width - 2}>
+      <KeyValueRow label="Award / revenue" value={`${current.revenueComparison.percent.toFixed(2)}%`} detail={current.revenueComparison.basis === "obligated" ? "Obligated amount" : "Award value"} labelWidth={labelWidth} />
+      <KeyValueRow label="Annual revenue" value={`${current.currency} ${money(current.revenueComparison.annualRevenue)}`} labelWidth={labelWidth} />
+      <KeyValueRow label="Revenue period" value={`${current.revenueComparison.periodStart} / ${current.revenueComparison.periodEnd}`} labelWidth={labelWidth} />
+      <KeyValueRow label="Revenue filed" value={current.revenueComparison.filedAt.slice(0, 10)} labelWidth={labelWidth} />
+      <KeyValueRow label="Revenue filing" value={current.revenueComparison.sourceUrl} labelWidth={labelWidth} />
+      <ActionRow label="Open annual revenue filing" onPress={() => void host.openExternal(current.revenueComparison!.sourceUrl)} />
+    </Section> : null}
+    <Section title="Evidence" width={width - 2}>
+      <KeyValueRow label="Observed (UTC)" value={current.observedAt.replace("T", " ").slice(0, 19)} labelWidth={labelWidth} />
+      {current.dataEffectiveDate ? <KeyValueRow label="Record effective" value={current.dataEffectiveDate.slice(0, 10)} labelWidth={labelWidth} /> : null}
+      <KeyValueRow label="Confidence" value={current.confidence == null ? "--" : `${Math.round(current.confidence * 100)}%`} labelWidth={labelWidth} />
+      {current.entity ? <KeyValueRow label="Entity match" value={`${current.entity.method.replaceAll("-", " ")} · ${Math.round(current.entity.confidence * 100)}%`} labelWidth={labelWidth} /> : null}
+      {current.evidenceQuote ? <Box paddingY={1}><Text fg={colors.textBright} width={width - 2} wrapMode="word" wrapText>{current.evidenceQuote}</Text></Box> : null}
+      <Text fg={colors.textDim} width={width - 2} wrapMode="word" wrapText>{current.sourceUrl}</Text>
+      {Object.entries(current.fieldSourceUrls ?? {}).map(([field, url]) => <ActionRow key={field} label={`Open ${({ obligatedAmount: "obligation", ceilingAmount: "ceiling", awardAmount: "award value", parentRecipient: "parent relationship" } as Record<string, string>)[field] ?? field.replace(/([a-z])([A-Z])/g, "$1 $2").replaceAll("_", " ").toLowerCase()} evidence${current.fieldAsOf?.[field] ? ` · ${current.fieldAsOf[field]!.slice(0, 10)}` : ""}`} onPress={() => void host.openExternal(url)} />)}
+      {current.entity ? <KeyValueRow label="Entity evidence" value={current.entity.evidenceUrl} labelWidth={labelWidth} /> : null}
+      {current.entity ? <ActionRow label="Open entity evidence" onPress={() => void host.openExternal(current.entity!.evidenceUrl)} /> : null}
+    </Section>
+    <PaneStatusBody loading={resource.loading && !detail} error={!detail ? resource.error?.message : null} subject="award revisions">
+      {detail ? <>
+        <Section title="Revisions" width={width - 2}>
+          {resource.rows.map((revision) => <Box key={revision.id} flexDirection="column" paddingBottom={1}>
+            <KeyValueRow label={revision.observedAt.slice(0, 10)} value={`${revision.award.currency} ${money(revision.award.obligatedAmount)} obligated · ${money(revision.award.ceilingAmount)} ceiling`} labelWidth={labelWidth} />
+            <KeyValueRow label="Record" value={revision.id} detail={revision.supersedes ? `Supersedes ${revision.supersedes}` : "Original observation"} labelWidth={labelWidth} />
+            <KeyValueRow label="Awardee" value={revision.award.recipient.name} labelWidth={labelWidth} />
+            <KeyValueRow label="Agency" value={revision.award.agency.name} labelWidth={labelWidth} />
+            <KeyValueRow label="Award date / value" value={`${revision.award.awardDate} · ${revision.award.currency} ${money(revision.award.awardAmount)}`} labelWidth={labelWidth} />
+            <KeyValueRow label="Performance period" value={`${revision.award.periodStart ?? "--"} / ${revision.award.periodEnd ?? "--"}`} labelWidth={labelWidth} />
+            <Text fg={colors.textDim} width={width - 2} wrapMode="word" wrapText>{revision.award.title}</Text>
+            {revision.award.evidenceQuote ? <Text fg={colors.text} width={width - 2} wrapMode="word" wrapText>{revision.award.evidenceQuote}</Text> : null}
+            <ActionRow label="Open revision source" onPress={() => void host.openExternal(revision.award.sourceUrl)} />
+          </Box>)}
+        </Section>
+        <Section title="Subawards" width={width - 2}>
+          {detail.subawards.length ? detail.subawards.slice(0, 50).map((award) => <ActionRow key={award.id} label={`${award.recipient.name} · ${award.currency} ${money(award.awardAmount)}`} onPress={() => openAward(award.id)} />) : <Text fg={colors.textDim}>No disclosed subawards.</Text>}
+          {detail.truncated?.subawards || detail.subawards.length > 50 ? <ActionRow label="Open subcontract feed" onPress={() => openChildren("subaward")} /> : null}
+        </Section>
+        <Section title="Modifications" width={width - 2}>
+          {detail.modifications.length ? detail.modifications.slice(0, 50).map((award) => <ActionRow key={award.id} label={`${award.awardDate} · ${award.modificationNumber ?? award.sourceAwardId} · ${award.currency} ${money(award.awardAmount)}`} onPress={() => openAward(award.id)} />) : <Text fg={colors.textDim}>No recorded modifications.</Text>}
+          {detail.truncated?.modifications || detail.modifications.length > 50 ? <ActionRow label="Open contract action feed" onPress={() => openChildren("modification")} /> : null}
+        </Section>
+        <Section title="Contract relationships" width={width - 2}>
+          {detail.edges.map((edge, index) => <KeyValueRow key={`${edge.awardId}:${index}`} label={edge.kind === "government-customer" ? "Government customer" : "Subcontractor"} value={`${edge.from.name} → ${edge.to.name}`} detail={`${edge.currency} ${money(edge.amount)}`} labelWidth={labelWidth} />)}
+        </Section>
+        {detail.locked ? <UpgradeLabel text="Upgrade for complete award evidence" onPress={openUpgrade} /> : null}
+      </> : null}
+    </PaneStatusBody>
+  </ScrollBox>;
+}

package/src/plugins/builtin/awards/evidence.ts

@@ -0,0 +1,36 @@
+import type { AwardFilter, AwardsPayload } from "../../../api-client/awards";
+import type { PaneScreenshotEvidenceHook } from "../../../cli/pane-functions/screenshot-evidence";
+import { useRemoteUiNode } from "../../../remote/semantic-tree";
+import { isRecord } from "../../../utils/guards";
+import { fetchAwards, validateAwards } from "./client";
+import { awardTab, type AwardTab } from "./model";
+
+interface AwardsEvidence { kind: "government-awards"; version: 1; complete: boolean; plottedValueCount: number; payload: AwardsPayload; tab: AwardTab }
+export function useAwardsEvidence(payload: AwardsPayload | undefined, tab: AwardTab, plottedValueCount: number) {
+  useRemoteUiNode({ role: "chart-data", label: "Rendered government awards", getMetadata: () => ({ kind: "government-awards", version: 1,
+    complete: !!payload, ready: !!payload, plottedValueCount, payload, tab }) });
+}
+export const awardsScreenshotEvidence: PaneScreenshotEvidenceHook<AwardsEvidence> = {
+  paneId: "awards", kind: "government-awards", label: "government awards",
+  async prepare({ resolved }) {
+    const ticker = (resolved.createOptions?.symbol ?? resolved.createOptions?.arg)?.trim().toUpperCase();
+    const query: AwardFilter = { ticker: ticker || undefined, awardType: (resolved.options.type as AwardFilter["awardType"]) ?? "prime", limit: 100 };
+    for (const key of ["jurisdiction", "currency", "source", "agency", "sector", "parentId", "from", "to", "query"] as const) {
+      if (resolved.options[key]) query[key] = String(resolved.options[key]);
+    }
+    const payload = await fetchAwards(query);
+    return { settings: { awardsSnapshot: payload }, financials: ticker ? [[ticker, { annualStatements: [], quarterlyStatements: [], priceHistory: [] }]] : [] };
+  },
+  read(value) {
+    if (!isRecord(value) || value.kind !== "government-awards" || value.version !== 1 || value.complete !== true || !Number.isSafeInteger(value.plottedValueCount)
+      || Number(value.plottedValueCount) < 0 || awardTab(value.tab) !== value.tab || !isRecord(value.payload)) return null;
+    try { validateAwards(value.payload as unknown as AwardsPayload); return value as unknown as AwardsEvidence; } catch { return null; }
+  },
+  mismatches(evidence, { resolved, payload }) {
+    const snapshot = payload.config.layout.instances.find((entry) => entry.instanceId === payload.paneId)?.settings?.awardsSnapshot;
+    return [...(JSON.stringify(evidence.payload) !== JSON.stringify(snapshot) ? ["Award records differ from the captured source data"] : []),
+      ...(evidence.tab !== awardTab(resolved.options.tab) ? ["Award tab differs from the request"] : [])];
+  },
+  unavailable(evidence) { return evidence?.complete ? [] : ["government awards"]; },
+  symbols({ payload }) { return payload.financials.map(([symbol]) => symbol); },
+};